refactor(cmaf): lift pipeline into qbz-qobuz + add download_raw

Prep work for offline-cache CMAF hardening. The full CMAF pipeline
(init-segment setup, full-download, decrypt) used to live in
src-tauri/src/commands_v2/helpers.rs — fine for playback but unreachable
from the offline-cache code without dragging Tauri deps around.

Moves:
- try_cmaf_full_download → qbz_qobuz::cmaf::download_full
- try_cmaf_streaming_setup → qbz_qobuz::cmaf::setup_streaming
- CmafStreamingInfo struct → qbz_qobuz::cmaf

Adds:
- qbz_qobuz::cmaf::download_raw + CmafRawBundle — fetches the same track
  but returns the ENCRYPTED segments + init bytes + the unwrapped
  content_key + the session infos, ready to be persisted to disk as-is.
  The offline cache will use this so that cached files are bit-identical
  to what Qobuz delivered (no decrypt-to-disk), with the content key
  stored separately under an OS-keyring-wrapped blob. Coming in next
  commits.
- qbz_qobuz::cmaf::decrypt_segments_into — shared decrypt helper used by
  download_full and (in the next commits) by the offline-playback path
  that reads encrypted segments from disk instead of CDN.

In-tree behaviour is unchanged: try_cmaf_full_download /
try_cmaf_streaming_setup in helpers.rs are now thin wrappers that hand
the CoreBridge's QobuzClient to the crate functions. Same API surface
for playback.rs callers, same log tags, same on-wire behaviour.

v2_cmaf_stream stays in src-tauri because it binds to qbz-player's
BufferWriter + qbz-cache's AudioCache — those are playback-only deps
that don't belong in qbz-qobuz.

Net: -100 LOC out of src-tauri, +390 LOC in a properly-layered crate
module with docs explaining the two variants and why the raw one exists.

cc
This commit is contained in:
vicrodh committed 2026-04-17 00:46:31 -06:00
1 parent 19fa779063
commit 391e797c9a
3 files changed
+417 -184

No files matched your search

+391
View File
@@ -0,0 +1,391 @@
//! CMAF streaming pipeline for Qobuz.
//!
//! Qobuz's modern mobile client uses CMAF (Common Media Application Format)
//! segmented streaming over Akamai CDN, with AES-CTR per-frame encryption.
//! This is the pipeline that the v9.7.0.3 Android app uses and the one we
//! need to match if we want to stay compatible as Qobuz deprecates the
//! legacy `/track/getFileUrl` nginx path.
//!
//! # Pipeline shape
//!
//! 1. `/file/url` returns `{ url_template, key (wrapped), n_segments, ... }`
//! 2. `/session/start` returns `{ session_id, infos }` — the `infos` string
//! is the HKDF salt needed to derive the per-session AES key
//! 3. Session key = `HKDF(CMAF_SEED, infos)`
//! 4. Content key = unwrap(session_key, key) — this is the per-track AES key
//! 5. Fetch init segment (s=0) → parse FLAC header + segment table
//! 6. For each s=1..n_segments: fetch → parse crypto boxes → decrypt frames
//! in place → emit decrypted FLAC frames to the consumer
//!
//! # Why live in `qbz-qobuz` and not `qbz-cmaf`
//!
//! `qbz-cmaf` is pure parsing + crypto primitives (no I/O, no Qobuz client).
//! This module is the Qobuz-specific orchestration: it calls `/file/url`,
//! `/session/start`, owns the Akamai HTTP client, and returns ready-to-play
//! or ready-to-store bundles.
//!
//! # Why two variants
//!
//! - [`download_full`] — returns the fully decrypted FLAC as `Vec<u8>`. Used
//! by the playback pipeline for in-memory cache writes and eager downloads.
//! - [`download_raw`] — returns a [`CmafRawBundle`] of **encrypted** segments
//! plus key material. Used by the offline cache so we can persist
//! bit-identical bytes to what Qobuz delivered, and decrypt only at
//! playback time. This is the security-sensitive path.
use std::sync::Arc;
use qbz_models::Quality;
use crate::client::QobuzClient;
use crate::error::Result;
/// Concurrency cap for the full-download path. 3 segments in flight is the
/// empirically-determined sweet spot — Akamai CDN rate-limits with 1s windows
/// past ~5 parallel requests per client IP.
pub const CMAF_PREFETCH_CONCURRENCY: usize = 3;
/// Info gathered from the CMAF init segment, enough to start streaming
/// playback. The caller is expected to fetch audio segments 1..n_segments
/// and feed them through [`qbz_cmaf::parse_segment_crypto`] +
/// [`qbz_cmaf::decrypt_frame`].
pub struct CmafStreamingInfo {
pub url_template: String,
pub n_segments: u8,
pub content_key: [u8; 16],
pub flac_header: Vec<u8>,
pub segment_table: Vec<qbz_cmaf::SegmentTableEntry>,
pub format_id: u32,
pub sampling_rate: Option<u32>,
pub bit_depth: Option<u32>,
/// How long the init segment fetch took (ms), for speed estimation.
pub init_fetch_ms: u64,
}
/// Raw (encrypted) CMAF bundle suitable for offline storage.
///
/// Everything in this struct is **bit-identical** to what Qobuz's CDN
/// returned. In particular:
///
/// - `init_bytes` is the raw init segment (unencrypted mp4 box with the
/// FLAC header inside — cheap to store).
/// - `segments` are the raw encrypted segment mp4 files, one per
/// `s=1..=n_segments`. These are useless without `content_key` and
/// without running them through the CMAF decrypt pipeline.
/// - `content_key` is the 16-byte AES key unwrapped from the session key;
/// it must be stored **encrypted at rest** on the caller's side.
/// - `infos` is the original `session/start` infos string. With the
/// `CMAF_SEED` constant this is enough to re-derive `session_key` and
/// re-unwrap the content key if we ever need to audit or migrate.
///
/// The intent is that an attacker who copies the user's offline directory
/// out without also extracting the OS-keyring wrapped `content_key` gets
/// nothing usable — the segments are encrypted, the `infos` is just a
/// salt, and the seed alone isn't enough.
pub struct CmafRawBundle {
pub init_bytes: Vec<u8>,
pub segments: Vec<Vec<u8>>,
pub content_key: [u8; 16],
pub infos: String,
pub format_id: u32,
pub sampling_rate: Option<u32>,
pub bit_depth: Option<u32>,
pub n_segments: u8,
}
/// Prepare CMAF streaming: fetch init segment only, derive keys, return info.
/// Does NOT download audio segments -- the caller streams those in background.
pub async fn setup_streaming(
client: &QobuzClient,
track_id: u64,
quality: Quality,
) -> std::result::Result<CmafStreamingInfo, String> {
let file_url = client.get_file_url(track_id, quality).await
.map_err(|e| format!("get_file_url failed: {}", e))?;
let url_template = file_url
.url_template
.as_ref()
.ok_or("No url_template in file/url response")?
.clone();
let key_str = file_url
.key
.as_ref()
.ok_or("No key in file/url response")?;
let (_session_id, infos) = client.ensure_cmaf_session().await
.map_err(|e| format!("ensure_cmaf_session failed: {}", e))?;
let session_key = qbz_cmaf::derive_session_key(crate::auth::CMAF_SEED, &infos)
.map_err(|e| format!("Session key derivation failed: {}", e))?;
let content_key = qbz_cmaf::unwrap_content_key(&session_key, key_str)
.map_err(|e| format!("Content key unwrap failed: {}", e))?;
// Fetch only the init segment (s=0) -- typically small, <500ms
let http = build_cdn_client()?;
let init_url = url_template.replace("$SEGMENT$", "0");
let init_start = std::time::Instant::now();
log::info!("[CMAF] Fetching init segment for track {}", track_id);
let init_data = http
.get(&init_url)
.header("User-Agent", "Mozilla/5.0")
.send()
.await
.map_err(|e| format!("Failed to fetch init segment: {}", e))?
.bytes()
.await
.map_err(|e| format!("Failed to read init segment: {}", e))?;
let init_fetch_ms = init_start.elapsed().as_millis() as u64;
let init_info = qbz_cmaf::parse_init_segment(&init_data)
.map_err(|e| format!("Failed to parse init segment: {}", e))?;
log::info!(
"[CMAF] Init for track {}: FLAC header {}B, segment_table={} entries, API n_segments={}, fetched in {}ms",
track_id,
init_info.flac_header.len(),
init_info.segment_table.len(),
file_url.n_segments,
init_fetch_ms
);
if init_info.segment_table.len() != file_url.n_segments as usize {
log::warn!(
"[CMAF] MISMATCH for track {}: segment_table has {} entries but API says n_segments={}",
track_id,
init_info.segment_table.len(),
file_url.n_segments
);
}
let format_id = file_url.format_id.unwrap_or(quality.id());
Ok(CmafStreamingInfo {
url_template,
n_segments: file_url.n_segments,
content_key,
flac_header: init_info.flac_header,
segment_table: init_info.segment_table,
format_id,
sampling_rate: file_url.sampling_rate,
bit_depth: file_url.bits_depth.or(file_url.bit_depth),
init_fetch_ms,
})
}
/// Download a track's complete CMAF stream and return decrypted FLAC bytes.
///
/// Used by the playback path for in-memory cache writes. Segments are
/// fetched concurrently with a semaphore cap, decrypted, and concatenated.
pub async fn download_full(
client: &QobuzClient,
track_id: u64,
quality: Quality,
) -> std::result::Result<Vec<u8>, String> {
let setup = setup_streaming(client, track_id, quality).await?;
let http = build_cdn_client()?;
let total_size: usize = setup.flac_header.len()
+ setup.segment_table.iter().map(|s| s.byte_len as usize).sum::<usize>();
let segments = fetch_all_segments(&http, &setup.url_template, setup.n_segments, "CMAF-FULL").await?;
let mut output = Vec::with_capacity(total_size);
output.extend_from_slice(&setup.flac_header);
decrypt_segments_into(&segments, &setup.content_key, &mut output)?;
log::info!(
"[CMAF-FULL] Track {} complete: {:.2} MB FLAC, expected {:.2} MB",
track_id,
output.len() as f64 / (1024.0 * 1024.0),
total_size as f64 / (1024.0 * 1024.0),
);
Ok(output)
}
/// Download a track's complete CMAF stream and return it as a raw (still
/// encrypted) bundle suitable for offline storage.
///
/// The caller is responsible for:
/// 1. Persisting `init_bytes` + `segments` to disk as bit-identical blobs
/// 2. Wrapping `content_key` with a device-bound key before storing it
/// 3. Storing `infos` (either wrapped or as plaintext — it's only a salt,
/// useless without `CMAF_SEED` + `content_key`)
///
/// At playback time, the caller feeds `init_bytes` through
/// [`qbz_cmaf::parse_init_segment`] to recover the FLAC header + segment
/// table, then decrypts each segment with the unwrapped content key.
pub async fn download_raw(
client: &QobuzClient,
track_id: u64,
quality: Quality,
) -> std::result::Result<CmafRawBundle, String> {
let file_url = client.get_file_url(track_id, quality).await
.map_err(|e| format!("get_file_url failed: {}", e))?;
let url_template = file_url
.url_template
.as_ref()
.ok_or("No url_template in file/url response")?
.clone();
let key_str = file_url
.key
.as_ref()
.ok_or("No key in file/url response")?;
let (_session_id, infos) = client.ensure_cmaf_session().await
.map_err(|e| format!("ensure_cmaf_session failed: {}", e))?;
let session_key = qbz_cmaf::derive_session_key(crate::auth::CMAF_SEED, &infos)
.map_err(|e| format!("Session key derivation failed: {}", e))?;
let content_key = qbz_cmaf::unwrap_content_key(&session_key, key_str)
.map_err(|e| format!("Content key unwrap failed: {}", e))?;
let http = build_cdn_client()?;
// Init segment — used for FLAC header + segment table at playback
let init_url = url_template.replace("$SEGMENT$", "0");
log::info!("[CMAF-RAW] Fetching init for track {}", track_id);
let init_bytes = http
.get(&init_url)
.header("User-Agent", "Mozilla/5.0")
.send()
.await
.map_err(|e| format!("Failed to fetch init segment: {}", e))?
.bytes()
.await
.map_err(|e| format!("Failed to read init segment: {}", e))?
.to_vec();
// Audio segments — encrypted, stored as-is
let segments = fetch_all_segments(&http, &url_template, file_url.n_segments, "CMAF-RAW").await?;
log::info!(
"[CMAF-RAW] Track {} bundle: init={}B, {} encrypted segments, total raw size={} bytes",
track_id,
init_bytes.len(),
segments.len(),
init_bytes.len() + segments.iter().map(|s| s.len()).sum::<usize>(),
);
Ok(CmafRawBundle {
init_bytes,
segments,
content_key,
infos,
format_id: file_url.format_id.unwrap_or(quality.id()),
sampling_rate: file_url.sampling_rate,
bit_depth: file_url.bits_depth.or(file_url.bit_depth),
n_segments: file_url.n_segments,
})
}
/// Build a reqwest client configured for Akamai CDN fetches.
///
/// Uses the workspace reqwest feature set (rustls-tls). The original in-tree
/// version in `src-tauri/commands_v2/helpers.rs` called `.use_native_tls()`
/// but the src-tauri Cargo opts into both stacks; this crate stays on
/// rustls for smaller binary + no system SSL dependency. If Akamai ever
/// surfaces a cert issue, adding the `native-tls` feature to qbz-qobuz is
/// the escape hatch.
fn build_cdn_client() -> std::result::Result<reqwest::Client, String> {
reqwest::Client::builder()
.connect_timeout(std::time::Duration::from_secs(10))
.build()
.map_err(|e| format!("CMAF client error: {}", e))
}
/// Fetch segments 1..=n_segments concurrently with a semaphore cap and a
/// cooldown per slot to stay under CDN rate limits.
async fn fetch_all_segments(
http: &reqwest::Client,
url_template: &str,
n_segments: u8,
log_tag: &str,
) -> std::result::Result<Vec<Vec<u8>>, String> {
let semaphore = Arc::new(tokio::sync::Semaphore::new(CMAF_PREFETCH_CONCURRENCY));
let seg_indices: Vec<u8> = (1..=n_segments).collect();
let mut handles = Vec::with_capacity(seg_indices.len());
for seg_idx in seg_indices {
let sem = semaphore.clone();
let http = http.clone();
let seg_url = url_template.replace("$SEGMENT$", &seg_idx.to_string());
let log_tag = log_tag.to_string();
handles.push(tokio::spawn(async move {
let permit = sem.acquire_owned().await.map_err(|e| format!("semaphore: {}", e))?;
let seg_data = http
.get(&seg_url)
.header("User-Agent", "Mozilla/5.0")
.send()
.await
.map_err(|e| format!("[{}] seg {} fetch: {}", log_tag, seg_idx, e))?
.bytes()
.await
.map_err(|e| format!("[{}] seg {} read: {}", log_tag, seg_idx, e))?;
// Cooldown before releasing the slot — keeps requests spaced out
// to stay under CDN rate limits (most use 1s windows)
tokio::time::sleep(std::time::Duration::from_millis(500)).await;
drop(permit);
Ok::<(u8, Vec<u8>), String>((seg_idx, seg_data.to_vec()))
}));
}
// Collect results in arrival order, then re-sort by segment index
let mut segments: Vec<(u8, Vec<u8>)> = Vec::with_capacity(handles.len());
for handle in handles {
let (idx, data) = handle
.await
.map_err(|e| format!("[{}] task panic: {}", log_tag, e))?
.map_err(|e| format!("[{}] download failed: {}", log_tag, e))?;
segments.push((idx, data));
}
segments.sort_by_key(|(idx, _)| *idx);
Ok(segments.into_iter().map(|(_, data)| data).collect())
}
/// Decrypt a sequence of encrypted CMAF segments in order and append the
/// decrypted frames to `output`.
///
/// This is the common decryption logic shared between the full-download
/// path (decrypt-then-return) and the offline playback path (decrypt-from-
/// disk-then-feed-player).
pub fn decrypt_segments_into(
segments: &[Vec<u8>],
content_key: &[u8; 16],
output: &mut Vec<u8>,
) -> std::result::Result<(), String> {
for (seg_idx, seg_data) in segments.iter().enumerate() {
// seg_idx is 0-based here but the original segment number is idx+1
let log_idx = seg_idx + 1;
let crypto = qbz_cmaf::parse_segment_crypto(seg_data)
.map_err(|e| format!("CMAF seg {} parse: {}", log_idx, e))?;
let mut data_pos = crypto.data_offset;
for entry in &crypto.entries {
let frame_end = data_pos + entry.size as usize;
if frame_end > seg_data.len() {
return Err(format!("CMAF seg {} frame overflow", log_idx));
}
let mut frame = seg_data[data_pos..frame_end].to_vec();
if entry.flags != 0 {
qbz_cmaf::decrypt_frame(content_key, &entry.iv, &mut frame);
}
output.extend_from_slice(&frame);
data_pos = frame_end;
}
if data_pos < crypto.mdat_end && crypto.mdat_end <= seg_data.len() {
output.extend_from_slice(&seg_data[data_pos..crypto.mdat_end]);
}
}
Ok(())
}
// Silence "unused imports" if we end up not using everything at some point;
// the Result alias is kept for future variants that want to surface ApiError.
#[allow(dead_code)]
fn _type_assertions() {
let _: fn() -> Result<()> = || Ok(());
}
+6
View File
@@ -33,6 +33,7 @@
pub mod auth;
pub mod bundle;
pub mod client;
pub mod cmaf;
pub mod endpoints;
pub mod error;
pub mod link_resolver;
@@ -41,5 +42,10 @@ pub mod performers;
// Re-export main types
pub use bundle::BundleTokens;
pub use client::QobuzClient;
pub use cmaf::{
decrypt_segments_into, download_full as cmaf_download_full,
download_raw as cmaf_download_raw, setup_streaming as cmaf_setup_streaming, CmafRawBundle,
CmafStreamingInfo, CMAF_PREFETCH_CONCURRENCY,
};
pub use error::{ApiError, Result};
pub use link_resolver::{resolve_link, LinkResolverError, ResolvedLink};