From eadcc8d65d564fb6426979ae81efe6fc028916c1 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sat, 14 Nov 2026 16:38:18 -0800 Subject: [PATCH 1/2] fix(moq-hls): a segment URL names one byte sequence on every edge An edge muxed with the catalog's live estimates: the framerate it saw when building a rendition picked the timescale, and the latest bitrate the AAC descriptor. Neither is in the tag, so two edges serving one segment URL could serve differently timed bytes. The rendition now keeps and muxes its normalized config, the one its tag hashes. A retired rendition's cut segment ended where its own edge stopped reading, under the uncut segment's URL. A cut is now named by where it ends. Co-Authored-By: Claude Opus 5.5 --- rs/moq-hls/src/export/mod.rs | 146 +++++++++++++++++++++-------- rs/moq-hls/src/export/rendition.rs | 50 +++++----- rs/moq-hls/src/export/segments.rs | 8 ++ 3 files changed, 141 insertions(+), 63 deletions(-) diff --git a/rs/moq-hls/src/export/mod.rs b/rs/moq-hls/src/export/mod.rs index d8fce6fe945..ddba2fbcc59 100644 --- a/rs/moq-hls/src/export/mod.rs +++ b/rs/moq-hls/src/export/mod.rs @@ -1055,8 +1055,8 @@ mod tests { let audio_init = audio.latest_init().await.unwrap().expect("AAC init segment"); assert_eq!( aac_avg_bitrate(&audio_init), - 96_000, - "the muxer keeps the declared catalog bitrate" + 128_000, + "the descriptor carries the AAC-LC default, never a catalog bitrate an estimate rewrites" ); assert_eq!(video.bandwidth(), 2_000_000, "the catalog carries no video bitrate yet"); assert_eq!(audio.bandwidth(), 96_000); @@ -1104,8 +1104,8 @@ mod tests { } // The estimator also measures the framerate and publishes it once it settles, so an - // imported source gains one about a second in. Rebuilding for it would re-time the fMP4 - // (its timescale derives from the framerate) and churn every recording cursor mid-stream. + // imported source gains one about a second in. Rebuilding for it would churn every recording + // cursor mid-stream, and muxing with it would re-time the fMP4 under the same URLs. #[tokio::test(start_paused = true)] async fn estimated_framerate_keeps_the_rendition() { let origin = produce_origin(); @@ -1131,42 +1131,11 @@ mod tests { "the video rendition survives a framerate estimate of {framerate:?}" ); assert!(next_event(&mut cursor).await.is_none(), "no rendition churn"); - // Still muxed at the timescale the rendition was built with. + // Still muxed at the default timescale. assert_eq!(video.muxer().unwrap().timescale().as_u64(), 90_000); } } - #[tokio::test] - async fn estimate_before_first_init_reaches_aac_descriptor() { - let origin = produce_origin(); - let _broadcast = origin - .route("live", moq_net::origin::RouteOptions::default()) - .expect("publish allowed"); - settle().await; - let upstream = empty_upstream(&origin, "live").await; - - let mut catalog = catalog_with_both(); - catalog.audio.renditions.get_mut("audio0").unwrap().bitrate = None; - let renditions = renditions::Producer::spawned(Config::default().window); - renditions.sync(&upstream, &catalog); - let audio = renditions.get(Kind::Audio, "audio0").expect("audio rendition"); - - catalog.audio.renditions.get_mut("audio0").unwrap().bitrate = Some(110_000); - renditions.sync(&upstream, &catalog); - assert!( - Arc::ptr_eq(&audio, &renditions.get(Kind::Audio, "audio0").unwrap()), - "the estimate updates the existing rendition" - ); - let init = audio.latest_init().await.unwrap().expect("AAC init segment"); - - assert_eq!(audio.bandwidth(), 110_000); - assert_eq!( - aac_avg_bitrate(&init), - 110_000, - "the latest estimate reaches an init that was not cached yet" - ); - } - // The other half: a change that alters how the rendition decodes, or which track it // lists, still rebuilds it, so the cached init segment can never describe media it no // longer matches. @@ -4467,7 +4436,9 @@ mod tests { let snapshot = test.listed("video0", 2).await; assert_eq!(numbers(&snapshot), [0, 1, 2], "no segment is lost to the hand-over"); let tags: Vec<_> = snapshot.segments.iter().map(|s| s.tag.as_str()).collect(); - assert_eq!(tags, [old.tag(), old.tag(), new.tag()]); + // The predecessor's part is a cut, named by where it ends. + let cut = segments::cut(old.tag(), 6, Duration::from_secs(3)); + assert_eq!(tags, [old.tag(), &cut, new.tag()]); let durations: Vec<_> = snapshot.segments.iter().map(|s| s.duration.as_millis()).collect(); assert_eq!( durations, @@ -4476,7 +4447,7 @@ mod tests { ); let id = segments::Id { generation: None, - tag: old.tag().to_string(), + tag: cut, at: segments::At::Sequence(1), }; assert!( @@ -4541,7 +4512,8 @@ mod tests { let snapshot = test.listed("video0", 2).await; assert_eq!(numbers(&snapshot), [0, 1, 2]); let tags: Vec<_> = snapshot.segments.iter().map(|s| s.tag.as_str()).collect(); - assert_eq!(tags, [old.tag(), old.tag(), new.tag()]); + let cut = segments::cut(old.tag(), 6, Duration::from_secs(3)); + assert_eq!(tags, [old.tag(), &cut, new.tag()]); let durations: Vec<_> = snapshot.segments.iter().map(|s| s.duration.as_millis()).collect(); assert_eq!( durations, @@ -4712,6 +4684,46 @@ mod tests { assert_eq!(target(&test, "video1"), 6, "a returning rendition derives its own"); } + // A retired rendition cuts its last segment where its edge stopped reading, and edges that + // see the catalog update at different media points cut it at different groups. Each cut lists + // under a URL naming it, so no URL names one edge's cut on one edge and another's elsewhere. + #[tokio::test(start_paused = true)] + async fn edges_name_a_retired_cut_apart() { + let mut early = Groups::with(&["video0"], &[]); + let mut late = early.join(); + let mut video0 = early.publish("video0"); + // Two groups a segment: segment 3 opens at group 6. + for sequence in 0..7 { + video0.at(sequence, sequence * 1_000); + settle().await; + } + let retired = [&mut early, &mut late].map(|edge| edge.rendition("video0")); + early.catalog.video.renditions.remove("video0"); + early.sync(); + video0.at(7, 7_000); + settle().await; + late.catalog.video.renditions.remove("video0"); + late.sync(); + for sequence in 8..10 { + video0.at(sequence, sequence * 1_000); + settle().await; + } + + let [early, late] = retired; + let [cut, other] = [&early, &late].map(|edge| { + let snapshot = edge.snapshot(); + assert_eq!(numbers(&snapshot), [0, 1, 2, 3]); + let tags: Vec<_> = snapshot.segments.iter().map(|s| s.tag.to_string()).collect(); + assert_eq!(tags[..3], [edge.tag(); 3], "a whole segment keeps its URL"); + tags[3].clone() + }); + assert_ne!(cut, other, "cut at groups 7 and 8"); + assert!(early.numbered(&cut, 3).await.unwrap().is_some()); + for tag in [&other, early.tag()] { + assert!(early.numbered(tag, 3).await.unwrap().is_none(), "{tag} names other bytes"); + } + } + // Two edges over one media track agree on the media sequence. #[tokio::test(start_paused = true)] async fn edges_agree_on_the_media_sequence() { @@ -4727,4 +4739,60 @@ mod tests { assert_eq!(joined.media_sequence, 12, "eight 2s segments cover the 16s window"); assert_eq!(numbers(&followed), numbers(&joined)); } + + // A publisher's estimator republishes its framerate and bitrate as they settle, and each edge + // builds its renditions at its own moment. Edges on either side of an estimate still name + // every init and segment by one URL and serve the same bytes under it. + #[tokio::test(start_paused = true)] + async fn edges_mux_alike_across_live_estimates() { + let mut early = Groups::with(&[], &[]); + let mut video = video_config(); + video.framerate = None; + let mut audio = catalog_with_both().audio.renditions.remove("audio0").unwrap(); + audio.bitrate = None; + early.catalog.video.renditions.insert("video0".into(), video); + early.catalog.audio.renditions.insert("audio0".into(), audio); + early.sync(); + let mut tracks = [early.publish("video0"), early.publish("audio0")]; + for sequence in 0..4 { + tracks.iter_mut().for_each(|track| track.gop(sequence)); + settle().await; + } + for name in ["video0", "audio0"] { + early.listed(name, 2).await; + } + + // The estimates settle after this edge built its renditions, and before the next one does. + early.catalog.video.renditions.get_mut("video0").unwrap().framerate = Some(30.0); + early.catalog.audio.renditions.get_mut("audio0").unwrap().bitrate = Some(110_000); + early.sync(); + let late = early.join(); + for sequence in 4..7 { + tracks.iter_mut().for_each(|track| track.gop(sequence)); + settle().await; + } + + for name in ["video0", "audio0"] { + let (followed, joined) = (early.listed(name, 5).await, late.listed(name, 5).await); + let (early, late) = (early.rendition(name), late.rendition(name)); + assert_eq!(early.tag(), late.tag(), "{name}: one segment URL"); + let shared: Vec<_> = numbers(&joined) + .into_iter() + .filter(|segment| numbers(&followed).contains(segment)) + .collect(); + assert!(shared.len() >= 2, "{name}: both list {shared:?}"); + for segment in shared { + let bytes = early.listed_segment(segment).await.unwrap().expect("segment"); + assert_eq!( + Some(bytes), + late.listed_segment(segment).await.unwrap(), + "{name}: segment {segment} names one byte sequence" + ); + } + // An init URL names its bytes by hash, so the same bytes are what keep it valid on + // every edge. + let init = early.latest_init().await.unwrap().expect("init"); + assert_eq!(Some(init), late.latest_init().await.unwrap(), "{name}: one init"); + } + } } diff --git a/rs/moq-hls/src/export/rendition.rs b/rs/moq-hls/src/export/rendition.rs index 63c0d4a5386..10b5400047b 100644 --- a/rs/moq-hls/src/export/rendition.rs +++ b/rs/moq-hls/src/export/rendition.rs @@ -107,7 +107,9 @@ struct Run { epoch: u64, } -/// The rendition's catalog config, kept whole so a [`Muxer`] can be built per request. +/// The rendition's normalized catalog config: what its [tag](segments::tag) hashes and every +/// [`Muxer`] it builds reads, so a segment URL names the same bytes on every edge, whenever the +/// edge built the rendition. The publisher's live estimates never reach the bytes. #[allow( clippy::large_enum_variant, reason = "one per rendition, so the variant sizes never add up to an allocation's worth; only large when extra features grow the video config" @@ -634,7 +636,7 @@ impl Rendition { self.enabled.load(Ordering::Relaxed) } - /// The latest catalog bitrate, preserving `None` for muxer-specific fallback behavior. + /// The latest catalog bitrate, preserving `None` for the per-kind default. fn bitrate(&self) -> Option { *self.bitrate.read().expect("bitrate lock poisoned") } @@ -661,8 +663,9 @@ impl Rendition { let track = config.track(&name); let container = Arc::new(moq_mux::catalog::hang::Container::try_from(config)?); let media = Media::bind(source, config, track, fanout.lazy)?; + let normalized = normalize_video(config); Ok(Self { - tag: tag(track, interval, &normalize_video(config)), + tag: tag(track, interval, &normalized), container, name, kind: Kind::Video, @@ -672,7 +675,7 @@ impl Rendition { width: config.coded_width, height: config.coded_height, codec: config.codec.to_string(), - config: Config::Video(config.clone()), + config: Config::Video(normalized), target_duration: target_duration(grid::segment_length(interval)), overruns: AtomicU64::new(0), interval, @@ -703,8 +706,9 @@ impl Rendition { let track = config.track(&name); let container = Arc::new(moq_mux::catalog::hang::Container::try_from(config)?); let media = Media::bind(source, config, track, fanout.lazy)?; + let normalized = normalize_audio(config); Ok(Self { - tag: tag(track, interval, &normalize_audio(config)), + tag: tag(track, interval, &normalized), container, name, kind: Kind::Audio, @@ -714,7 +718,7 @@ impl Rendition { width: None, height: None, codec: config.codec.to_string(), - config: Config::Audio(config.clone()), + config: Config::Audio(normalized), target_duration: target_duration(grid::segment_length(interval)), overruns: AtomicU64::new(0), interval, @@ -1385,23 +1389,16 @@ impl Rendition { clock.wall_clock(pts).ok() } - /// A muxer at the timescale this rendition's config chose, with the latest bitrate. + /// A muxer for this rendition's normalized config. /// - /// Each segment times its last sample from its own row, so no catalog estimate changes - /// the media bytes. + /// No catalog estimate reaches it: an estimated framerate would pick the timescale and an + /// estimated bitrate the AAC descriptor, so edges that built the rendition before and after + /// an estimate would serve different bytes under one URL. Each segment times its last sample + /// from its own row instead. pub(crate) fn muxer(&self) -> Result { - let bitrate = self.bitrate(); Ok(match &self.config { - Config::Video(config) => { - let mut config = config.clone(); - config.bitrate = bitrate; - Muxer::video(&config)? - } - Config::Audio(config) => { - let mut config = config.clone(); - config.bitrate = bitrate; - Muxer::audio(&config)? - } + Config::Video(config) => Muxer::video(config)?, + Config::Audio(config) => Muxer::audio(config)?, }) } @@ -1534,12 +1531,12 @@ impl Rendition { /// [generation](super::Broadcaster::set_generation), since a restart reuses segment numbers /// and another run's URL would name different bytes. pub async fn segment(&self, id: &segments::Id) -> Result> { - // A predecessor's segments still listed are muxed under its config. A config that returns - // gets its tag back, but the instances' segment numbers never overlap. + // A predecessor's segments still listed, its cut among them, are muxed under its config. A + // config that returns gets its tag back, but the instances' segment numbers never overlap. let owner = self .lineage() .into_iter() - .find(|rendition| *rendition.tag == *id.tag && rendition.live.holds(&id.tag, id.at)); + .find(|rendition| rendition.live.holds(&id.tag, id.at)); let owner = owner.as_deref().unwrap_or(self); let Some(mut fetch) = owner.fetch_own(id)? else { return Ok(None); @@ -2242,7 +2239,12 @@ impl Follow { *whole = true; } claim.next = segment + 1; - rendition.push(row(&rendition, slot, *broken)); + let mut row = row(&rendition, slot, *broken); + if last { + // Where it stopped reading is this edge's own, so the cut gets a URL of its own. + row.tag = segments::cut(&row.tag, row.groups.end, row.end).into(); + } + rendition.push(row); *broken = false; if last { return Some(Ok(())); diff --git a/rs/moq-hls/src/export/segments.rs b/rs/moq-hls/src/export/segments.rs index b139090e49e..03fcdec9c8b 100644 --- a/rs/moq-hls/src/export/segments.rs +++ b/rs/moq-hls/src/export/segments.rs @@ -128,6 +128,14 @@ pub(crate) fn tag(track: &str, config: &[u8]) -> String { hash.as_ref()[..4].iter().map(|b| format!("{b:02x}")).collect() } +/// The tag of a segment under `tag` cut short before group `groups_end`, ending at `end`. +/// +/// A retired rendition cuts its last segment where its edge stopped reading, which another edge +/// may place elsewhere, so a cut is named by where it ends rather than by its number alone. +pub(crate) fn cut(tag: &str, groups_end: u64, end: Duration) -> String { + self::tag(&format!("{tag}/{groups_end}/{}", end.as_nanos()), b"") +} + /// One playlist segment: its number, timing, and the groups it holds. #[derive(Clone, Debug, PartialEq)] pub(crate) struct Row { From abd9aa7f0aaea2b8a597e020d52edcf67caa116c Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sat, 14 Nov 2026 16:44:18 -0800 Subject: [PATCH 2/2] style(moq-hls): format the cut test Co-Authored-By: Claude Opus 5.5 --- rs/moq-hls/src/export/mod.rs | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/rs/moq-hls/src/export/mod.rs b/rs/moq-hls/src/export/mod.rs index ddba2fbcc59..ea67cc04e67 100644 --- a/rs/moq-hls/src/export/mod.rs +++ b/rs/moq-hls/src/export/mod.rs @@ -4720,7 +4720,10 @@ mod tests { assert_ne!(cut, other, "cut at groups 7 and 8"); assert!(early.numbered(&cut, 3).await.unwrap().is_some()); for tag in [&other, early.tag()] { - assert!(early.numbered(tag, 3).await.unwrap().is_none(), "{tag} names other bytes"); + assert!( + early.numbered(tag, 3).await.unwrap().is_none(), + "{tag} names other bytes" + ); } }