From 9e8e06d04e441cd09dcf6c44218e712d00c08419 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 18 Nov 2026 16:04:58 -0800 Subject: [PATCH 01/10] chore(quest): claim quest/m2/export-replaced-rendition.md Quest-Claim: f9b47b3722265658 From 68ca4c2a97031d776a47bad74c2fabc6fef5fb15 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 18 Nov 2026 16:17:25 -0800 Subject: [PATCH 02/10] fix(mux): a TS export outlives a rendition whose track fails Co-Authored-By: Claude Opus 5.5 --- rs/moq-mux/src/container/consumer.rs | 25 ++++++++----- rs/moq-mux/src/container/source.rs | 22 ++++++++++-- rs/moq-mux/src/container/ts/export.rs | 42 +++++++++++++++++++--- rs/moq-mux/src/container/ts/export_test.rs | 42 ++++++++++++++++++++++ 4 files changed, 117 insertions(+), 14 deletions(-) diff --git a/rs/moq-mux/src/container/consumer.rs b/rs/moq-mux/src/container/consumer.rs index 4cbc59709b..5520913267 100644 --- a/rs/moq-mux/src/container/consumer.rs +++ b/rs/moq-mux/src/container/consumer.rs @@ -236,6 +236,8 @@ enum Reader { /// An error ended the reader, which reads as finished from then on. The subscription is /// released, and the publisher's demand with it. Ended, + /// The track's own failure ended the reader once its groups drained, as [`Self::Ended`] does. + Lost, } /// How a [`Consumer`]'s cursor chooses its first group. @@ -576,18 +578,25 @@ impl Consumer { Poll::Ready(Ok(Some(item))) } + /// Whether the error that ended the reader was its track's own failure, rather than its media. + pub(crate) fn lost(&self) -> bool { + matches!(self.reader, Reader::Lost) + } + /// Read media or a clean group boundary without waiting for a successor group. pub(crate) fn poll_event(&mut self, waiter: &kio::Waiter) -> Poll, F::Error>> { // An error ended the reader, which reads as finished from then on: a decode error has // already consumed the frame it came from, so reading on would skip it. - if let Reader::Ended = self.reader { + if let Reader::Ended | Reader::Lost = self.reader { return Poll::Ready(Ok(None)); } let event = ready!(self.poll_event_inner(waiter)); if event.is_err() { // Nothing more is read, so release the subscription and the groups it holds rather // than pin the publisher's demand and cache for as long as the caller keeps this. - self.reader = Reader::Ended; + if !matches!(self.reader, Reader::Lost) { + self.reader = Reader::Ended; + } self.pending.clear(); } Poll::Ready(event) @@ -877,7 +886,7 @@ impl Consumer { Reader::Reading(track) | Reader::Failed(track, _) => { track.next_in_range(self.current).is_none_or(|next| next >= sequence) } - Reader::Ended => false, + Reader::Ended | Reader::Lost => false, }; // The groups past the hole already fill the max buffer, so it can hold none of what // would arrive into it. @@ -968,7 +977,7 @@ impl Consumer { if finished && self.pending.is_empty() { if let Reader::Failed(..) = self.reader - && let Reader::Failed(_, err) = std::mem::replace(&mut self.reader, Reader::Ended) + && let Reader::Failed(_, err) = std::mem::replace(&mut self.reader, Reader::Lost) { // The caller only gets the bare error, with nothing to say which track died. tracing::warn!(track = &*self.name, error = ?err, "track failed; ending the reader"); @@ -1177,7 +1186,7 @@ impl Consumer { fn subscriber(&mut self) -> &mut moq_net::track::Subscriber { match &mut self.reader { Reader::Reading(track) | Reader::Failed(track, _) => track, - Reader::Ended => unreachable!("read only until an error ends the reader"), + Reader::Ended | Reader::Lost => unreachable!("read only until an error ends the reader"), } } @@ -1216,7 +1225,7 @@ impl Consumer { /// Receive group handles and wait for the track and every received group to finish. pub(crate) fn poll_received(&mut self, waiter: &kio::Waiter) -> Poll<()> { - if let Reader::Ended = self.reader { + if let Reader::Ended | Reader::Lost = self.reader { return Poll::Ready(()); } ready!(self.poll_read_finish(waiter)); @@ -1402,7 +1411,7 @@ impl Consumer { pub fn is_skipped(&self, groups: std::ops::Range) -> bool { match &self.reader { Reader::Reading(track) | Reader::Failed(track, _) => track.is_skipped(groups), - Reader::Ended => false, + Reader::Ended | Reader::Lost => false, } } @@ -1825,7 +1834,7 @@ mod tests { fn subscribed(consumer: &Consumer) -> &moq_net::track::Subscriber { match &consumer.reader { Reader::Reading(track) | Reader::Failed(track, _) => track, - Reader::Ended => panic!("the reader ended"), + Reader::Ended | Reader::Lost => panic!("the reader ended"), } } use std::time::Duration; diff --git a/rs/moq-mux/src/container/source.rs b/rs/moq-mux/src/container/source.rs index 524ca362c8..037b826207 100644 --- a/rs/moq-mux/src/container/source.rs +++ b/rs/moq-mux/src/container/source.rs @@ -76,6 +76,9 @@ enum SourceState { Active(Box), /// The track ended, the sibling instance it read went, or the source was stopped. Ended, + /// The track itself failed: its subscription was refused, or it ended with an error once the + /// groups already here were read. Media that failed to decode is the export's own error instead. + Lost, } /// How a source subscribes, fixed before its first poll. @@ -524,7 +527,7 @@ impl ExportSource { pub fn poll_received(&mut self, waiter: &kio::Waiter) -> Poll<()> { match &mut self.state { SourceState::Active(active) => active.consumer.poll_received(waiter), - SourceState::Ended => Poll::Ready(()), + SourceState::Ended | SourceState::Lost => Poll::Ready(()), _ => Poll::Pending, } } @@ -617,7 +620,7 @@ impl ExportSource { { return self.end(); } - Poll::Ready(Err(err)) => return Poll::Ready(Err(err.into())), + Poll::Ready(Err(err)) => return self.lose(err.into()), Poll::Pending => return Poll::Pending, }; let priority = self.source.control(track.control())?; @@ -684,6 +687,7 @@ impl ExportSource { { return self.end(); } + Poll::Ready(Err(err)) if consumer.lost() => return self.lose(err), Poll::Ready(Err(err)) => return Poll::Ready(Err(err)), Poll::Pending => return Poll::Pending, }; @@ -792,6 +796,20 @@ impl ExportSource { Poll::Ready(Ok(None)) } + /// Fail the rendition with its track's own error, which [`Self::lost`] then tells apart from + /// the export's own errors. + fn lose(&mut self, err: crate::Error) -> Poll>> { + self.stop(); + self.state = SourceState::Lost; + Poll::Ready(Err(err)) + } + + /// Whether the error this source returned was its track failing, which ends only this + /// rendition: a publisher that loses a source may list a replacement for it. + pub(crate) fn lost(&self) -> bool { + matches!(self.state, SourceState::Lost) + } + fn finish_ends(&mut self) { if let Some((_, count)) = self.ends.take() { self.skips += count; diff --git a/rs/moq-mux/src/container/ts/export.rs b/rs/moq-mux/src/container/ts/export.rs index 3491e8aaf8..126c8a9271 100644 --- a/rs/moq-mux/src/container/ts/export.rs +++ b/rs/moq-mux/src/container/ts/export.rs @@ -565,12 +565,23 @@ impl Track { let is_video = matches!(self.kind, Kind::Video(_)); // A placed frame is judged at release, against the keyframe's departure ([`Export::leads_video`]). let aligned = !is_video && !self.kind.placed(); + let mut lost = None; loop { if !input.waiting_for_header && input.jitter.full(&self.key, waiter) { let _ = self.source.poll_received(waiter); break; } - match self.source.poll_event(waiter)? { + let event = match self.source.poll_event(waiter) { + // The track failed: it ends like a finished one, and the export decides whether that + // ends it too ([`Export::survive`]). + Poll::Ready(Err(err)) if self.source.lost() => { + self.read = Read::Ended; + lost = Some(err); + break; + } + event => event?, + }; + match event { Poll::Ready(Some(Event::Frame { frame, arrived })) => { if is_video && frame.keyframe && input.waiting_for_header { tracing::debug!(target: "moq_mux::container::ts::handoff", phase = "keyframe", now = ?kio::clock::now(), program = self.key.program, ?arrived); @@ -641,7 +652,7 @@ impl Track { if self.read == Read::Ended && !input.waiting_for_header { self.release(name, input.jitter, true)?; } - Ok(()) + lost.map_or(Ok(()), Err) } /// The samples an audio frame of `payload` lasts and their rate, if it may share a PES with @@ -1922,7 +1933,11 @@ where }, ); let ended = live && track.read != Read::Live; - if let Err(err) = filled { + let lost = track.source.lost(); + if let Err(err) = filled.or_else(|err| match lost { + true => self.survive(&name, err), + false => Err(err), + }) { self.leave(err)?; } if ended || matches!(self.program.feed, Feed::Retired(_)) { @@ -2365,9 +2380,28 @@ where jitter: &mut self.jitter, trimmed: &mut self.program.trimmed, }; + let mut lost = Vec::new(); for (name, track) in &mut self.program.tracks { - track.fill(name, waiter, &mut input)?; + if let Err(err) = track.fill(name, waiter, &mut input) { + if !track.source.lost() { + return Err(err); + } + lost.push((name.clone(), err)); + } + } + lost.into_iter().try_for_each(|(name, err)| self.survive(&name, err)) + } + + /// Whether the export outlives the failure of track `name`, which [`Track::fill`] ended. + /// + /// While another track still reads, only that rendition ends: a publisher that loses a + /// source, such as a microphone, may list a replacement, which joins like any new rendition. + /// With nothing left reading, the failure is the program's, as before. + fn survive(&self, name: &str, err: crate::Error) -> crate::Result<()> { + if !self.program.tracks.values().any(|track| track.read == Read::Live) { + return Err(err); } + tracing::warn!(track = name, %err, "rendition failed; the export keeps its other media"); Ok(()) } diff --git a/rs/moq-mux/src/container/ts/export_test.rs b/rs/moq-mux/src/container/ts/export_test.rs index 89ad03d502..2145a24c63 100644 --- a/rs/moq-mux/src/container/ts/export_test.rs +++ b/rs/moq-mux/src/container/ts/export_test.rs @@ -9117,6 +9117,48 @@ async fn a_track_leaving_the_catalog_is_read_to_its_end() { assert_eq!(pes_count(&frames), 20 + 15, "every frame of both tracks went out"); } +/// A rendition whose track fails ends alone while another still reads, and a replacement the +/// publisher lists joins the program, as `moq import capture` publishes a reopened microphone. +#[tokio::test(start_paused = true)] +async fn a_failed_rendition_is_replaced_while_the_rest_plays_on() { + let mut broadcast = moq_net::broadcast::Info::new().produce(); + let consumer = broadcast.consume(); + let mut catalog = crate::catalog::Producer::new(&mut broadcast, crate::catalog::Config::default()).unwrap(); + let mut kept = aac_rendition(&mut broadcast, &mut catalog, "kept.aac"); + let mut failing = aac_rendition(&mut broadcast, &mut catalog, "0.aac"); + + let mut export = open_export(crate::source::announced(&consumer).await, RECORDING_MAX_AGE) + .await + .unwrap() + .with_replay(); + for ms in (0..200).step_by(20) { + write_aac(&mut kept, ms); + write_aac(&mut failing, ms); + } + let mut frames = poll_frames(&mut export); + + // The failed track stays listed while its retained groups drain, as a capture's does. + failing.abort(moq_net::Error::Transport("audio device lost".into())); + for ms in (200..300).step_by(20) { + write_aac(&mut kept, ms); + } + frames.extend(poll_frames(&mut export)); + let mut replacement = aac_rendition(&mut broadcast, &mut catalog, "1.aac"); + for ms in (300..400).step_by(20) { + write_aac(&mut kept, ms); + write_aac(&mut replacement, ms); + } + catalog.modify().unwrap().audio.renditions.remove("0.aac"); + let _finished = kept.finish().unwrap(); + let _finished = replacement.finish().unwrap(); + catalog.finish().unwrap(); + + let (rest, end) = drain_to_end(&mut export).await; + end.expect("a failed rendition with others still playing does not end the export"); + frames.extend(rest); + assert_eq!(pes_count(&frames), 20 + 10 + 5, "every frame of all three tracks went out"); +} + /// Publish an empty catalog at `live` under `route`. fn publish_live( origin: &moq_net::origin::Producer, From 2da61a784010ae8485a2a78a211623003af2d21a Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 18 Nov 2026 16:23:45 -0800 Subject: [PATCH 03/10] fix(mux): an fMP4 export continues a failed rendition on its replacement Co-Authored-By: Claude Opus 5.5 --- rs/moq-mux/src/container/fmp4/export.rs | 132 +++++++++++++++++-- rs/moq-mux/src/container/fmp4/export_test.rs | 76 +++++++++++ 2 files changed, 198 insertions(+), 10 deletions(-) diff --git a/rs/moq-mux/src/container/fmp4/export.rs b/rs/moq-mux/src/container/fmp4/export.rs index eb2a0be206..9e3888d44b 100644 --- a/rs/moq-mux/src/container/fmp4/export.rs +++ b/rs/moq-mux/src/container/fmp4/export.rs @@ -85,6 +85,14 @@ pub struct Export { /// so a publisher cycling names holds only what it recorded. departed: HashMap, + /// Renditions that joined after the init while a declared track of their medium still + /// reads: each waits to continue a declared track of its medium that fails + /// ([`Phase::Lost`]), and fails the export once none is left that could. + spares: HashMap, + + /// Renditions a spare replaced after their track failed, ignored while still listed. + replaced: HashSet, + init: Init, /// Keep a rendition that joins after the init segment instead of failing, for a writer @@ -298,6 +306,9 @@ enum Phase { Reading(Subscription), /// The subscription ended while the rendition stays in the catalog. Ended(Subscription), + /// The track failed while the rendition stays in the catalog. A rendition of its medium + /// that joins later continues it, as a publisher lists a reopened source. + Lost(Subscription), /// The rendition left the catalog after the init. One that returns resumes here. Departed(Resume), /// [`Export::stop`] ended the read. @@ -479,14 +490,14 @@ impl Fmp4Track { /// The subscription, while the rendition is in the catalog. fn subscription(&self) -> Option<&Subscription> { match &self.phase { - Phase::Reading(subscription) | Phase::Ended(subscription) => Some(subscription), + Phase::Reading(subscription) | Phase::Ended(subscription) | Phase::Lost(subscription) => Some(subscription), Phase::Departed(_) | Phase::Stopped => None, } } fn subscription_mut(&mut self) -> Option<&mut Subscription> { match &mut self.phase { - Phase::Reading(subscription) | Phase::Ended(subscription) => Some(subscription), + Phase::Reading(subscription) | Phase::Ended(subscription) | Phase::Lost(subscription) => Some(subscription), Phase::Departed(_) | Phase::Stopped => None, } } @@ -508,6 +519,18 @@ impl Fmp4Track { }; } + /// The track failed: its rendition reads no more, unless a later one of its medium continues it. + fn lose(&mut self) { + self.phase = match std::mem::replace(&mut self.phase, Phase::Stopped) { + Phase::Reading(subscription) => Phase::Lost(subscription), + phase => phase, + }; + } + + fn lost(&self) -> bool { + matches!(self.phase, Phase::Lost(_)) + } + /// The rendition left the catalog after the init: end the subscription, keeping where /// it stopped for a return. What was already read still goes out. fn depart(&mut self) { @@ -698,6 +721,8 @@ impl Export { fragment_duration: None, tracks: HashMap::new(), departed: HashMap::new(), + spares: HashMap::new(), + replaced: HashSet::new(), init: Init::Waiting { queued: VecDeque::new(), deadline: None, @@ -826,12 +851,21 @@ impl Export { // polling for the SPS/PPS-bearing keyframe instead of parking. Before the init, a // track that holds its share parks instead. let waiting = !self.init.written(); + let mut lost = Vec::new(); for (name, track) in &mut self.tracks { if track.pending.is_some() || track.buffer.is_closed() || (waiting && track.held >= INIT_SHARE) { continue; } while let Phase::Reading(subscription) = &mut track.phase { - match subscription.source.poll_event(waiter)? { + let event = match subscription.source.poll_event(waiter) { + Poll::Ready(Err(err)) if subscription.source.lost() => { + track.lose(); + lost.push((name.clone(), err)); + break; + } + event => event?, + }; + match event { Poll::Ready(Some(Event::Frame { frame, .. })) => { // A keyframe may carry new parameter sets, so check it still matches. if !track.described() || frame.keyframe { @@ -875,6 +909,11 @@ impl Export { } } } + for (name, err) in lost { + self.survive(&name, err)?; + } + // A track that ended may have been the last a spare could continue. + self.settle_spares()?; // 3. Emit the init segment once every track can be described, then the // fragments queued while it waited. @@ -1076,9 +1115,18 @@ impl Export { .map(|(name, config)| (name, Rendition::Audio(config))); let mut active = HashSet::new(); + let mut listed = HashSet::new(); + let mut spares = HashMap::new(); for (name, config) in video.chain(audio) { // A name used by both a video and an audio rendition is the video one. - if active.contains(&name) { + if active.contains(&name) || !listed.insert(name.clone()) || self.replaced.contains(&name) { + continue; + } + if !self.tracks.contains_key(&name) && !self.departed.contains_key(&name) && self.init.written() && !self.late { + if !self.spares.contains_key(&name) { + tracing::warn!(track = %name, "rendition joined after the init; it waits to continue a failed one"); + } + spares.insert(name, config); continue; } if !self.tracks.contains_key(&name) @@ -1106,7 +1154,7 @@ impl Export { // subscription would start at, so resume after what was read. A move is new // content, which continues past what was read under the declared track. let source = match std::mem::replace(&mut track.phase, Phase::Stopped) { - Phase::Reading(previous) | Phase::Ended(previous) => { + Phase::Reading(previous) | Phase::Ended(previous) | Phase::Lost(previous) => { track.moved(); source.continuing(&previous.source) } @@ -1121,9 +1169,6 @@ impl Export { let Some(source) = config.subscribe(&self.source, &name, self.delay)? else { continue; }; - if self.init.written() && !self.late { - return Err(Error::TrackAdded(name).into()); - } let mut track = Fmp4Track::new(source, config, self.next_track_id)?; self.next_track_id += 1; track.describe(&name)?; @@ -1136,9 +1181,10 @@ impl Export { match &mut self.init { Init::Written { first_late, .. } => { // The init declared these tracks, so keep them for a rendition that returns. - // Ending the subscription writes out what was already read. + // Ending the subscription writes out what was already read. A failed track stays + // for a spare to continue, which may join as its rendition leaves. for (name, track) in &mut self.tracks { - if !active.contains(name) { + if !active.contains(name) && !track.lost() { track.depart(); } } @@ -1157,7 +1203,73 @@ impl Export { queued.retain(|(name, _)| active.contains(name)); } } + self.replaced.retain(|name| listed.contains(name)); + self.spares = spares; + self.settle_spares() + } + + /// Whether the export outlives the failure of track `name`, which ended it. + /// + /// A spare of its medium continues it at once. Otherwise, while another track still reads, + /// only that rendition ends: a publisher that loses a source, such as a microphone, may list + /// a replacement, which continues it then. With nothing left reading, the failure is the + /// export's, as before. + fn survive(&mut self, name: &str, err: crate::Error) -> Result<()> { + // Before the init a track that could not be described declares nothing. + if !self.init.written() + && let Some(track) = self.tracks.get(name) + && !track.described() + { + self.tracks.remove(name); + } + self.settle_spares()?; + if !self.tracks.values().any(|track| matches!(track.phase, Phase::Reading(_))) { + return Err(err); + } + if self.tracks.get(name).is_some_and(Fmp4Track::lost) { + tracing::warn!(track = name, %err, "rendition failed; the export keeps its other media"); + } + Ok(()) + } + /// Continue each failed track with a spare of its medium, holding the other spares while a + /// track of their medium still reads. A spare with neither is a new rendition the init never + /// declared, which fails the export. + fn settle_spares(&mut self) -> Result<()> { + let mut names: Vec = self.spares.keys().cloned().collect(); + names.sort(); + for name in names { + let is_video = self.spares[&name].is_video(); + let failed = self + .tracks + .iter() + .filter(|(_, track)| track.is_video == is_video && track.lost()) + .map(|(failed, track)| (track.track_id, failed.clone())) + .min(); + if let Some((_, failed)) = failed { + let config = self.spares.remove(&name).expect("a listed spare"); + let Some(source) = config.subscribe(&self.source, &name, self.delay)? else { + continue; + }; + let mut track = self.tracks.remove(&failed).expect("a failed track"); + let Phase::Lost(previous) = std::mem::replace(&mut track.phase, Phase::Stopped) else { + unreachable!("picked a lost track"); + }; + tracing::info!(track = %name, replaces = %failed, "continuing a failed rendition"); + track.moved(); + track.rejoin(&name, config, source.continuing(&previous.source))?; + self.tracks.insert(name.clone(), track); + self.replaced.insert(failed); + continue; + } + let reading = self + .tracks + .values() + .any(|track| track.is_video == is_video && matches!(track.phase, Phase::Reading(_))); + if !reading { + return Err(Error::TrackAdded(name).into()); + } + } Ok(()) } diff --git a/rs/moq-mux/src/container/fmp4/export_test.rs b/rs/moq-mux/src/container/fmp4/export_test.rs index 97b8f050e3..e0d50b4af2 100644 --- a/rs/moq-mux/src/container/fmp4/export_test.rs +++ b/rs/moq-mux/src/container/fmp4/export_test.rs @@ -1544,6 +1544,82 @@ async fn a_rendition_joining_after_the_init_fails() { ); } +/// A capture that loses its microphone fails the audio track, keeps it listed while it drains, +/// and lists the reopened one under a new name, either before or after a reader sees the failure. +/// The replacement continues the declared audio track while the video plays on. +#[tokio::test(start_paused = true)] +async fn a_failed_rendition_continues_on_its_replacement() { + for listed_first in [false, true] { + let (mut live, audio) = live_av(); + let failed = audio.name().to_string(); + let mut audio = audio; + live.track.write(video_frame(0, true)).unwrap(); + write_audio(&mut audio, 0, 6); + let mut exporter = crate::container::fmp4::Export::new(live.source().await, live.catalog_stream().await) + .with_delay(moq_net::track::Delay::default().with_max(RECORDING_MAX_DELAY)); + let ids = track_ids(&chunk_now(&mut exporter).await.init().expect("init")); + let mut fragments = drain_now(&mut exporter).await; + + let mut replacement = None; + if listed_first { + replacement = Some(add_opus(&mut live).0); + fragments.extend(drain_now(&mut exporter).await); + } + audio.abort(moq_net::Error::Transport("audio device lost".into())); + live.track.write(video_frame(100_000, true)).unwrap(); + fragments.extend(drain_now(&mut exporter).await); + let mut replacement = replacement.unwrap_or_else(|| add_opus(&mut live).0); + // A replacement is new content, read from its live edge, as a moved rendition is. + fragments.extend(drain_now(&mut exporter).await); + write_audio(&mut replacement, 1_000_000, 5); + fragments.extend(drain_now(&mut exporter).await); + write_audio(&mut replacement, 1_100_000, 1); + live.track.write(video_frame(1_100_000, true)).unwrap(); + live.catalog.modify().unwrap().audio.renditions.remove(&failed); + live.track.write(video_frame(1_200_000, true)).unwrap(); + let _finished = replacement.finish().unwrap(); + fragments.extend(drain_now(&mut exporter).await); + + let samples = samples_per_track(&fragments); + assert_eq!(samples.get(&ids.1), Some(&12), "listed first: {listed_first}: {samples:?}"); + assert!(samples[&ids.0] >= 3, "the video played on: {samples:?}"); + assert_eq!(samples.len(), 2, "no track beyond the init's: {samples:?}"); + } +} + +/// A rendition that joins after the init waits only while a declared track of its medium could +/// still fail: once that one ends cleanly, it is a track the init never declared. +#[tokio::test(start_paused = true)] +async fn a_spare_rendition_fails_once_its_medium_ends_cleanly() { + let (mut live, mut audio) = live_av(); + live.track.write(video_frame(0, true)).unwrap(); + write_audio(&mut audio, 0, 6); + let mut exporter = crate::container::fmp4::Export::new(live.source().await, live.catalog_stream().await); + chunk_now(&mut exporter).await.init().expect("init"); + drain_now(&mut exporter).await; + + let (_spare, name) = add_opus(&mut live); + drain_now(&mut exporter).await; + let _finished = audio.finish().unwrap(); + let err = error_now(&mut exporter).await; + assert!( + matches!(&err, crate::Error::Cmaf(crate::container::fmp4::Error::TrackAdded(added)) if *added == name), + "{err:?}" + ); +} + +/// With nothing else reading, a failed track still fails the export. +#[tokio::test(start_paused = true)] +async fn the_last_failed_track_fails_the_export() { + let mut live = Live::avc3(); + live.track.write(video_frame(0, true)).unwrap(); + let mut exporter = crate::container::fmp4::Export::new(live.source().await, live.catalog_stream().await); + chunk_now(&mut exporter).await.init().expect("init"); + live.track.abort(moq_net::Error::Transport("camera lost".into())); + let err = error_now(&mut exporter).await; + assert!(err.to_string().contains("camera lost"), "{err:?}"); +} + /// Catalog hints that don't reach the sample entry may churn; a change that does fails /// the export instead of writing samples the moov misdescribes. #[tokio::test(start_paused = true)] From cdb46945168f1482757ca34a53d932c1d43f52e0 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 18 Nov 2026 16:26:40 -0800 Subject: [PATCH 04/10] fix(mux): an MKV export continues a failed rendition on its replacement Co-Authored-By: Claude Opus 5.5 --- rs/moq-mux/src/container/mkv/export.rs | 165 +++++++++++++++++--- rs/moq-mux/src/container/mkv/export_test.rs | 111 +++++++++++++ 2 files changed, 251 insertions(+), 25 deletions(-) diff --git a/rs/moq-mux/src/container/mkv/export.rs b/rs/moq-mux/src/container/mkv/export.rs index 096fdb051c..4db2513f9e 100644 --- a/rs/moq-mux/src/container/mkv/export.rs +++ b/rs/moq-mux/src/container/mkv/export.rs @@ -1,4 +1,4 @@ -use std::collections::HashMap; +use std::collections::{HashMap, HashSet}; use std::io::Cursor; use std::task::Poll; use std::time::Duration; @@ -61,6 +61,12 @@ pub struct Export { fragment_duration: Option, tracks: HashMap, + /// Renditions that joined after the header while a declared track of their kind still + /// reads: each waits to continue a declared track of its kind that fails, and fails the + /// export once none is left that could. + spares: HashSet, + /// Renditions a spare replaced after their track failed, ignored while still listed. + replaced: HashSet, /// Catalog snapshot used to build the header. Retained until header emission; /// subsequent catalog updates only (un)subscribe tracks. catalog_snapshot: Option, @@ -86,7 +92,10 @@ struct MkvTrack { subscribed: kio::clock::Instant, // The latest arrival read from the source, which settles the frames held for their DTS. latest: kio::clock::Instant, - finished: bool, + read: Read, + /// The catalog rendition the track reads: the one the header declared it for, or a spare + /// that continues it after that one failed. + rendition: String, track_number: u64, kind: TrackKind, /// The TrackEntry the header declared. @@ -96,9 +105,26 @@ struct MkvTrack { moved: bool, } +/// Whether a track still reads its source. +#[derive(Clone, Copy, PartialEq, Eq)] +enum Read { + Live, + /// The track ended, cleanly or as a sibling instance went. + Finished, + /// The track itself failed. A spare of its kind may continue it. + Lost, +} + impl MkvTrack { - /// A track numbered `track_number` reading `source`, with the video `config` it was added under. - fn new(source: ExportSource, kind: TrackKind, config: Option, track_number: u64) -> Self { + /// A track numbered `track_number` reading rendition `name` from `source`, with the video + /// `config` it was added under. + fn new( + name: &str, + source: ExportSource, + kind: TrackKind, + config: Option, + track_number: u64, + ) -> Self { Self { clock: Default::default(), declared: None, @@ -109,7 +135,8 @@ impl MkvTrack { pending: None, subscribed: kio::clock::now(), latest: kio::clock::Instant::ZERO, - finished: false, + read: Read::Live, + rendition: name.to_string(), track_number, kind, entry: None, @@ -130,12 +157,17 @@ impl MkvTrack { self.declared = None; self.reorder = None; self.source = source.continuing(&self.source); - self.finished = false; + self.read = Read::Live; self.subscribed = kio::clock::now(); self.moved = true; Ok(()) } + /// Nothing more is read: the track ended or failed. + fn finished(&self) -> bool { + self.read != Read::Live + } + /// The TrackEntry declaring this track under its catalog entry in `catalog`. fn track_entry(&self, catalog: &Catalog, name: &str) -> Result { match self.kind { @@ -202,7 +234,7 @@ impl MkvTrack { if (arrival.item.timestamp.as_nanos()? * 90_000 / 1_000_000_000) as u64 != pts { arrival.item.timestamp = moq_net::Timestamp::from_scale(pts, 90_000)?; } - if !self.finished && !flush { + if self.read == Read::Live && !flush { arrival.arrived = arrival.arrived.max(self.latest); } arrival.decode = crate::jitter::Decode::from_ticks(dts); @@ -241,7 +273,7 @@ impl MkvTrack { let Some((mut arrival, dts)) = self.clock.pop(lookahead, floor, settle) else { break; }; - if !self.finished && !flush { + if !self.finished() && !flush { arrival.arrived = arrival.arrived.max(self.latest); } arrival.decode = moq_net::Timestamp::from_scale(dts, 90_000)?.try_into()?; @@ -348,6 +380,8 @@ impl Export { held: None, fragment_duration: None, tracks: HashMap::new(), + spares: HashSet::new(), + replaced: HashSet::new(), catalog_snapshot: None, header_emitted: false, cluster: None, @@ -414,7 +448,7 @@ impl Export { // Still waiting on codec configs. If every track is finished and // the header still isn't ready, the source never produced enough // info to build it. - if self.catalog.is_none() && self.tracks.values().all(|t| t.finished) { + if self.catalog.is_none() && self.tracks.values().all(MkvTrack::finished) { return Poll::Ready(Ok(None)); } @@ -441,7 +475,7 @@ impl Export { // has finished. We don't require catalog EOS here - a long-lived // producer may keep the catalog open even after every active track has // ended, and we'd rather flush the cluster than hold the last frames. - if !self.tracks.is_empty() && self.tracks.values().all(|t| t.finished) { + if !self.tracks.is_empty() && self.tracks.values().all(MkvTrack::finished) { if let Some(cluster) = self.cluster.take() { return Poll::Ready(Ok(Some(cluster.finish()))); } @@ -486,6 +520,7 @@ impl Export { /// Read each track within its jitter window, preserving ingress timing before buffering. fn fill(&mut self, waiter: &kio::Waiter) -> Result<()> { + let mut lost = Vec::new(); for (name, track) in &mut self.tracks { loop { if self.header_emitted && self.jitter.full(name, waiter) { @@ -498,10 +533,18 @@ impl Export { let arrival = if let Some(pending) = track.pending.take() { pending } else { - if track.finished { + if track.finished() { break; } - let (frame, arrived) = match track.source.poll_event(waiter)? { + let event = match track.source.poll_event(waiter) { + Poll::Ready(Err(err)) if track.source.lost() => { + track.read = Read::Lost; + lost.push((name.clone(), err)); + break; + } + event => event?, + }; + let (frame, arrived) = match event { Poll::Ready(Some(Event::Frame { frame, arrived })) => (frame, arrived.max(track.subscribed)), // A group that ended or was cut short holds frames no later one can precede. Poll::Ready(Some(Event::GroupEnd | Event::Cut { .. })) => { @@ -512,7 +555,7 @@ impl Export { } Poll::Ready(Some(Event::FrameEnd { .. })) => continue, Poll::Ready(None) => { - track.finished = true; + track.read = Read::Finished; break; } Poll::Pending => break, @@ -522,7 +565,7 @@ impl Export { || self .catalog_snapshot .as_ref() - .and_then(|catalog| catalog.video.renditions.get(name)) + .and_then(|catalog| catalog.video.renditions.get(&track.rendition)) .is_some_and(|config| track.source.video_geometry_ready(config)); let declaring = !self.header_emitted || track.moved; if declaring && (!track.source.header_ready() || !geometry_ready) { @@ -533,7 +576,7 @@ impl Export { if track.moved && let Some(catalog) = self.catalog_snapshot.as_ref() { - if Some(track.track_entry(catalog, name)?) != track.entry { + if Some(track.track_entry(catalog, &track.rendition)?) != track.entry { return Err(Error::TrackChanged(name.clone()).into()); } track.moved = false; @@ -570,10 +613,75 @@ impl Export { self.jitter.push(name.clone(), arrival)?; } } - if track.finished { + if track.finished() { track.release(name, &mut self.jitter, true)?; } } + for (name, err) in lost { + self.survive(&name, err)?; + } + // A track that ended may have been the last a spare could continue. + self.settle_spares() + } + + /// Whether the export outlives the failure of track `name`, which [`Self::fill`] ended. + /// + /// A spare of its kind continues it at once. Otherwise, while another track still reads, + /// only that rendition ends: a publisher that loses a source, such as a microphone, may + /// list a replacement, which continues it then. With nothing left reading, the failure is + /// the export's, as before. + fn survive(&mut self, name: &str, err: crate::Error) -> Result<()> { + self.settle_spares()?; + if self.tracks.values().all(MkvTrack::finished) { + return Err(err); + } + if self.tracks.get(name).is_some_and(|track| track.read == Read::Lost) { + tracing::warn!(track = name, %err, "rendition failed; the export keeps its other media"); + } + Ok(()) + } + + /// Continue each failed track with a spare of its kind, holding the other spares while a + /// track of their kind still reads. A spare with neither is a rendition the header never + /// declared, which fails the export. + fn settle_spares(&mut self) -> Result<()> { + let Some(catalog) = self.catalog_snapshot.as_ref() else { + return Ok(()); + }; + let mut names: Vec = self.spares.iter().cloned().collect(); + names.sort(); + for name in names { + let (kind, source) = match (catalog.video.renditions.get(&name), catalog.audio.renditions.get(&name)) { + (Some(config), _) => (TrackKind::Video, ExportSource::for_video(&self.source, &name, config, self.delay)), + (None, Some(config)) => (TrackKind::Audio, ExportSource::for_audio(&self.source, &name, config, self.delay)), + (None, None) => continue, + }; + let failed = self + .tracks + .iter() + .filter(|(_, track)| track.kind == kind && track.read == Read::Lost) + .map(|(key, track)| (track.track_number, key.clone())) + .min(); + if let Some((_, key)) = failed { + let Some(source) = source? else { + continue; + }; + self.spares.remove(&name); + let track = self.tracks.get_mut(&key).expect("a failed track"); + tracing::info!(track = %name, replaces = %track.rendition, "continuing a failed rendition"); + track.rebind(&key, source, &mut self.jitter)?; + let failed = std::mem::replace(&mut track.rendition, name); + if kind == TrackKind::Video { + track.config = catalog.video.renditions.get(&track.rendition).cloned(); + track.reorder = None; + } + self.replaced.insert(failed); + continue; + } + if !self.tracks.values().any(|track| track.kind == kind && !track.finished()) { + return Err(Error::HeaderAddedTrack(name).into()); + } + } Ok(()) } @@ -598,25 +706,32 @@ impl Export { // track and is read to its own end: a disabled rendition idles until it re-enables, // and a retired one finishes on its own. if self.header_emitted { + let mut spares = HashSet::new(); for name in active.keys() { - if !self.tracks.contains_key(name) { - return Err(Error::HeaderAddedTrack(name.clone()).into()); + if self.replaced.contains(name) || self.tracks.values().any(|track| track.rendition == *name) { + continue; } + if !self.spares.contains(name) { + tracing::warn!(track = %name, "rendition joined after the header; it waits to continue a failed one"); + } + spares.insert(name.clone()); } + self.spares = spares; + self.replaced.retain(|name| active.contains_key(name)); for (name, config) in &catalog.audio.renditions { - if let Some(track) = self.tracks.get_mut(name) + if let Some((key, track)) = self.tracks.iter_mut().find(|(_, track)| track.rendition == *name) && !track.source.reads(&self.source, name, config) && let Some(source) = ExportSource::for_audio(&self.source, name, config, self.delay)? { - track.rebind(name, source, &mut self.jitter)?; + track.rebind(key, source, &mut self.jitter)?; } } for (name, config) in &catalog.video.renditions { - if let Some(track) = self.tracks.get_mut(name) { + if let Some((key, track)) = self.tracks.iter_mut().find(|(_, track)| track.rendition == *name) { if !track.source.reads(&self.source, name, config) && let Some(source) = ExportSource::for_video(&self.source, name, config, self.delay)? { - track.rebind(name, source, &mut self.jitter)?; + track.rebind(key, source, &mut self.jitter)?; } if track .config @@ -629,7 +744,7 @@ impl Export { } } self.catalog_snapshot = Some(catalog); - return Ok(()); + return self.settle_spares(); } // Nothing went out yet, so a rendition that left the catalog is dropped, and one the @@ -650,7 +765,7 @@ impl Export { let Some(source) = ExportSource::for_video(&self.source, name, config, self.delay)? else { continue; }; - let track = MkvTrack::new(source, TrackKind::Video, Some(config.clone()), next_track_number); + let track = MkvTrack::new(name, source, TrackKind::Video, Some(config.clone()), next_track_number); self.tracks.insert(name.clone(), track); next_track_number += 1; } @@ -662,7 +777,7 @@ impl Export { let Some(source) = ExportSource::for_audio(&self.source, name, config, self.delay)? else { continue; }; - let track = MkvTrack::new(source, TrackKind::Audio, None, next_track_number); + let track = MkvTrack::new(name, source, TrackKind::Audio, None, next_track_number); self.tracks.insert(name.clone(), track); next_track_number += 1; } diff --git a/rs/moq-mux/src/container/mkv/export_test.rs b/rs/moq-mux/src/container/mkv/export_test.rs index 4d5456ccba..385c8457ce 100644 --- a/rs/moq-mux/src/container/mkv/export_test.rs +++ b/rs/moq-mux/src/container/mkv/export_test.rs @@ -935,6 +935,117 @@ async fn a_moved_rendition_continues_on_its_new_track() { } } +/// Add a Legacy AAC rendition to `live`. +fn add_aac(live: &mut Live) -> crate::container::Producer { + live.add_track(".aac", |catalog, name| { + let mut config = hang::catalog::AudioConfig::new(hang::catalog::AAC { profile: 2 }, 44100, 2); + config.description = Some(Bytes::from_static(&[0x12, 0x10])); + config.container = hang::catalog::Container::Legacy; + catalog.modify().unwrap().audio.renditions.insert(name, config); + }) +} + +/// The `(track number, payload)` of every block in `mkv`. +fn blocks(mkv: Vec) -> Vec<(u64, Vec)> { + WebmIterator::new(&mut Cursor::new(mkv), &[]) + .filter_map(|tag| match tag { + Ok(MatroskaSpec::SimpleBlock(data)) => { + let block = SimpleBlock::try_from(&data).unwrap(); + Some((block.track, block.read_frame_data().unwrap()[0].data.to_vec())) + } + _ => None, + }) + .collect() +} + +/// A capture that loses its microphone fails the audio track, keeps it listed while it drains, +/// and lists the reopened one under a new name, either before or after a reader sees the failure. +/// The replacement continues under the audio track number the header declared while the video +/// plays on. +#[tokio::test(start_paused = true)] +async fn a_failed_rendition_continues_on_its_replacement() { + for listed_first in [false, true] { + let mut live = Live::avc3(); + let mut audio = add_aac(&mut live); + let failed = audio.name().to_string(); + live.track.write(video_frame(0, true)).unwrap(); + audio.write(raw_frame(0, b"old", true)).unwrap(); + let mut exporter = crate::container::mkv::Export::new(live.source().await, live.catalog_stream().await) + .with_delay(moq_net::track::Delay::default().with_max(std::time::Duration::from_secs(5))); + let mut out = drain_now(&mut exporter).await.unwrap(); + + let mut replacement = None; + if listed_first { + replacement = Some(add_aac(&mut live)); + out.extend(drain_now(&mut exporter).await.unwrap()); + } + audio.write(raw_frame(20_000, b"old", true)).unwrap(); + out.extend(drain_now(&mut exporter).await.unwrap()); + audio.abort(moq_net::Error::Transport("audio device lost".into())); + live.track.write(video_frame(100_000, true)).unwrap(); + out.extend(drain_now(&mut exporter).await.unwrap()); + let mut replacement = replacement.unwrap_or_else(|| add_aac(&mut live)); + out.extend(drain_now(&mut exporter).await.unwrap()); + for ms in [200, 220, 240] { + replacement.write(raw_frame(ms * 1000, b"new", true)).unwrap(); + out.extend(drain_now(&mut exporter).await.unwrap()); + } + live.catalog.modify().unwrap().audio.renditions.remove(&failed); + live.track.write(video_frame(300_000, true)).unwrap(); + out.extend(drain_now(&mut exporter).await.unwrap()); + live.track.end_with(None).unwrap(); + let _finished = replacement.finish().unwrap(); + live.catalog.finish().unwrap(); + while let Some(chunk) = exporter.next().await.unwrap() { + out.extend_from_slice(&chunk); + } + + let blocks = blocks(out); + let audio: Vec<_> = blocks + .iter() + .filter(|(_, payload)| payload.as_slice() == b"old" || payload.as_slice() == b"new") + .collect(); + let payloads: Vec<&[u8]> = audio.iter().map(|(_, payload)| payload.as_slice()).collect(); + assert_eq!(payloads, [&b"old"[..], b"old", b"new", b"new", b"new"], "listed first: {listed_first}"); + let numbers: std::collections::HashSet = audio.iter().map(|(number, _)| *number).collect(); + assert_eq!(numbers.len(), 1, "the replacement writes under the declared track"); + assert_eq!(blocks.len(), audio.len() + 3, "the video played on"); + } +} + +/// A rendition that joins after the header waits only while a declared track of its kind could +/// still fail: once that one ends cleanly, it is a track the header never declared. +#[tokio::test(start_paused = true)] +async fn a_spare_rendition_fails_once_its_kind_ends_cleanly() { + let mut live = Live::avc3(); + let mut audio = add_aac(&mut live); + live.track.write(video_frame(0, true)).unwrap(); + audio.write(raw_frame(0, b"old", true)).unwrap(); + let mut exporter = crate::container::mkv::Export::new(live.source().await, live.catalog_stream().await); + drain_now(&mut exporter).await.unwrap(); + + let spare = add_aac(&mut live); + drain_now(&mut exporter).await.unwrap(); + let _finished = audio.finish().unwrap(); + let err = drain_now(&mut exporter).await.unwrap_err(); + assert!( + matches!(&err, crate::Error::Mkv(crate::container::mkv::Error::HeaderAddedTrack(added)) if added == spare.name()), + "{err:?}" + ); +} + +/// With nothing else reading, a failed track still fails the export. +#[tokio::test(start_paused = true)] +async fn the_last_failed_track_fails_the_export() { + let mut live = Live::avc3(); + live.track.write(video_frame(0, true)).unwrap(); + let mut exporter = crate::container::mkv::Export::new(live.source().await, live.catalog_stream().await); + drain_now(&mut exporter).await.unwrap(); + live.track.abort(moq_net::Error::Transport("camera lost".into())); + let err = drain_now(&mut exporter).await.unwrap_err(); + assert!(err.to_string().contains("camera lost"), "{err:?}"); +} + /// The header's TrackEntry carries the rendition's first avcC, which a move to a track /// described by another SPS cannot change mid-file. It fails before writing any of that track. #[tokio::test(start_paused = true)] From d770c8a7124dc47f3dcdbf9c2e52ac3c9fe46b68 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 18 Nov 2026 16:31:36 -0800 Subject: [PATCH 05/10] fix(mux): an FLV export continues a failed rendition on a listed one Co-Authored-By: Claude Opus 5.5 --- rs/moq-mux/src/container/flv/export.rs | 148 ++++++++++++++++++-- rs/moq-mux/src/container/flv/export_test.rs | 92 ++++++++++++ 2 files changed, 230 insertions(+), 10 deletions(-) diff --git a/rs/moq-mux/src/container/flv/export.rs b/rs/moq-mux/src/container/flv/export.rs index 071c5b6551..77718ff81d 100644 --- a/rs/moq-mux/src/container/flv/export.rs +++ b/rs/moq-mux/src/container/flv/export.rs @@ -157,6 +157,11 @@ pub struct Export { /// True once the file header and sequence headers have been emitted. header_emitted: bool, + /// The latest catalog, where a track that failed after the header finds a rendition to + /// continue on. + listed: Catalog, + /// Renditions a track left after theirs failed, never picked again while still listed. + replaced: std::collections::HashSet, /// Milliseconds added to every tag's timestamps, so the decode times a declared reorder /// depth puts before a group's earliest presentation still fit FLV's unsigned clock. shift: u32, @@ -191,7 +196,7 @@ struct FlvTrack { pending: Option<(crate::jitter::Arrival, Bill)>, /// When the source was last empty, bounding the next frame's arrival. empty: kio::clock::Instant, - finished: bool, + read: Read, /// The FLV payload shape (legacy CodecID vs enhanced FourCC) to mux this /// track as, fixed from its catalog codec when it's bound. flavor: Flavor, @@ -212,14 +217,37 @@ struct FlvTrack { announced: Option, } +/// Whether a track still reads its source. +#[derive(Clone, Copy, PartialEq, Eq)] +enum Read { + Live, + /// The track ended, cleanly or as a sibling instance went. + Finished, + /// The track itself failed. Another rendition of its kind and codec may continue it. + Lost, +} + impl FlvTrack { /// Read `source`, the track the catalog moved this rendition to. fn rebind(&mut self, source: ExportSource) { self.source = source.continuing(&self.source); - self.finished = false; + self.read = Read::Live; self.empty = kio::clock::now(); } + /// Continue this failed track on rendition `name`, read from `source`, returning the + /// rendition it read before. + fn replace(&mut self, name: String, source: ExportSource) -> String { + tracing::info!(track = %name, replaces = %self.name, "continuing a failed rendition"); + self.rebind(source); + std::mem::replace(&mut self.name, name) + } + + /// Nothing more is read: the track ended or failed. + fn finished(&self) -> bool { + self.read != Read::Live + } + /// The tag timestamp of a frame presented at `pts` on the tag clock, on the inferred clock. fn tag_timestamp(&self, pts: u32) -> crate::Result { if self.flavor.has_composition_time() { @@ -366,6 +394,8 @@ impl Export { video: Vec::new(), audio: Vec::new(), header_emitted: false, + listed: Catalog::default(), + replaced: Default::default(), shift: 0, } } @@ -422,7 +452,7 @@ impl Export { } // The catalog closed and nothing more can resolve a codec config (no // tracks arrived, or every bound track ended first): there's no header. - if self.catalog.is_none() && (!self.has_tracks() || self.tracks().all(|t| t.finished)) { + if self.catalog.is_none() && (!self.has_tracks() || self.tracks().all(FlvTrack::finished)) { return Poll::Ready(Ok(None)); } return Poll::Pending; @@ -437,7 +467,7 @@ impl Export { } // 5. End-of-stream once every subscribed track is drained. - if self.has_tracks() && self.tracks().all(|t| t.finished && t.pending.is_none()) { + if self.has_tracks() && self.tracks().all(|t| t.finished() && t.pending.is_none()) { if self.catalog.is_none() { return Poll::Ready(Ok(None)); } @@ -476,6 +506,7 @@ impl Export { /// Read each track within its jitter window, preserving ingress timing before buffering. fn fill(&mut self, waiter: &kio::Waiter) -> crate::Result<()> { + let mut lost = Vec::new(); for kind in [0, 1] { let count = if kind == 0 { self.video.len() } else { self.audio.len() }; for index in 0..count { @@ -495,10 +526,18 @@ impl Export { let (arrival, bill) = if let Some(pending) = track.pending.take() { pending } else { - if track.finished { + if track.finished() { break; } - let frame = match track.source.poll_event(waiter)? { + let event = match track.source.poll_event(waiter) { + Poll::Ready(Err(err)) if track.source.lost() => { + track.read = Read::Lost; + lost.push((track.name.clone(), err)); + break; + } + event => event?, + }; + let frame = match event { Poll::Ready(Some(Event::Frame { frame, .. })) => frame, // A group that ended or was cut short holds frames no later one can precede. Poll::Ready(Some(Event::GroupEnd | Event::Cut { .. })) => { @@ -507,7 +546,7 @@ impl Export { } Poll::Ready(Some(Event::FrameEnd { .. })) => continue, Poll::Ready(None) => { - track.finished = true; + track.read = Read::Finished; break; } Poll::Pending => { @@ -560,14 +599,98 @@ impl Export { &mut self.audio[index] }; // Nothing settles the frames held when a track ends, so they keep their own arrival. - if track.finished && self.header_emitted { + if track.finished() && self.header_emitted { track.release((kind, index), None, self.shift, true, &mut self.jitter)?; } } } + for (name, err) in lost { + self.survive(&name, err)?; + } + Ok(()) + } + + /// Whether the export outlives the failure of track `name`, which [`Self::fill`] ended. + /// + /// A listed rendition of its kind and codec continues it at once. Otherwise, while another + /// track still reads, only that rendition ends: a publisher that loses a source, such as a + /// microphone, may list a replacement, which continues it then. With nothing left reading, + /// the failure is the export's, as before. + fn survive(&mut self, name: &str, err: crate::Error) -> crate::Result<()> { + self.replace_lost()?; + if self.tracks().all(FlvTrack::finished) { + return Err(err); + } + if self.tracks().any(|track| track.name == name && track.read == Read::Lost) { + tracing::warn!(track = name, %err, "rendition failed; the export keeps its other media"); + } + Ok(()) + } + + /// Continue each track that failed after the header on a listed rendition no track reads, + /// of its kind and codec, best first: the header fixed the tag shape, so a rendition of + /// another codec cannot continue it. + fn replace_lost(&mut self) -> crate::Result<()> { + if !self.header_emitted { + return Ok(()); + } + for index in 0..self.video.len() { + let track = &self.video[index]; + if track.read != Read::Lost { + continue; + } + let Some((name, config)) = self + .listed + .video + .ranked() + .find(|(name, config)| { + video_flavor(config).ok() == Some(track.flavor) && self.unread(&self.video, name, &config.container) + }) + .map(|(name, config)| (name.clone(), config.clone())) + else { + continue; + }; + let Some(source) = ExportSource::for_video(&self.source, &name, &config, self.delay)? else { + continue; + }; + let track = &mut self.video[index]; + track.fallback_description = fallback_description(&config); + track.dts_reserve = dts_reserve(&config); + track.config = Some(config); + self.replaced.insert(track.replace(name, source)); + } + for index in 0..self.audio.len() { + let track = &self.audio[index]; + if track.read != Read::Lost { + continue; + } + let Some((name, config)) = self + .listed + .audio + .ranked() + .find(|(name, config)| { + audio_flavor(config).ok() == Some(track.flavor) && self.unread(&self.audio, name, &config.container) + }) + .map(|(name, config)| (name.clone(), config.clone())) + else { + continue; + }; + let Some(source) = ExportSource::for_audio(&self.source, &name, &config, self.delay)? else { + continue; + }; + self.replaced.insert(self.audio[index].replace(name, source)); + } Ok(()) } + /// Whether rendition `name`, carried in `container`, is free to continue a failed track among + /// `tracks`: none reads it, and none left it after it failed. + fn unread(&self, tracks: &[FlvTrack], name: &str, container: &Container) -> bool { + matches!(container, Container::Legacy | Container::Loc) + && !self.replaced.contains(name) + && !tracks.iter().any(|track| track.name == name) + } + fn update_catalog(&mut self, mut catalog: Catalog) -> crate::Result<()> { self.source.retain_selectable(&mut catalog); @@ -594,6 +717,11 @@ impl Export { self.bind_audio(&catalog)?; } else { self.rebind(&catalog)?; + self.replaced.retain(|name| { + catalog.video.renditions.contains_key(name) || catalog.audio.renditions.contains_key(name) + }); + self.listed = catalog.clone(); + self.replace_lost()?; if self.multitrack && (catalog.video.renditions.len() > self.video.len() || catalog.audio.renditions.len() > self.audio.len()) @@ -689,7 +817,7 @@ impl Export { source, pending: None, empty: kio::clock::now(), - finished: false, + read: Read::Live, flavor, fallback_description, config: Some(config.clone()), @@ -738,7 +866,7 @@ impl Export { source, pending: None, empty: kio::clock::now(), - finished: false, + read: Read::Live, flavor, fallback_description: None, config: None, diff --git a/rs/moq-mux/src/container/flv/export_test.rs b/rs/moq-mux/src/container/flv/export_test.rs index 597463cee5..7c7c397968 100644 --- a/rs/moq-mux/src/container/flv/export_test.rs +++ b/rs/moq-mux/src/container/flv/export_test.rs @@ -1729,6 +1729,98 @@ async fn a_track_leaving_the_catalog_is_read_to_its_end() { assert_eq!(audio_frames, 2, "the leaving track's tail went out"); } +/// A capture that loses its microphone fails the audio track, keeps it listed while it drains, +/// and lists the reopened one under a new name, either before or after a reader sees the failure. +/// The FLV audio goes on with the replacement while the video plays on. +#[tokio::test(start_paused = true)] +async fn a_failed_rendition_continues_on_its_replacement() { + use hang::catalog::{AAC, AudioConfig, Container, H264, VideoConfig}; + use moq_net::Timestamp; + + for listed_first in [false, true] { + let mut producer = moq_net::broadcast::Info::new().produce(); + let consumer = producer.consume(); + let mut catalog = crate::catalog::Producer::new(&mut producer, crate::catalog::Config::default()).unwrap(); + let mut video_config = VideoConfig::new(H264 { + profile: 0x42, + constraints: 0xc0, + level: 0x1f, + inline: false, + }); + video_config.container = Container::Legacy; + video_config.description = Some(Bytes::from(avcc())); + let mut audio_config = AudioConfig::new(AAC { profile: 2 }, 44100, 2); + audio_config.container = Container::Legacy; + audio_config.description = Some(Bytes::from_static(&ASC)); + + let legacy = || crate::catalog::hang::Container::Legacy(crate::container::Kind::Data); + let mut add = |name: &str, video: bool| { + let track = producer.create_track(producer.unique_name(name), timed()).unwrap(); + let mut modify = catalog.modify().unwrap(); + if video { + modify.video.renditions.insert(track.name().to_string(), video_config.clone()); + } else { + modify.audio.renditions.insert(track.name().to_string(), audio_config.clone()); + } + crate::container::Producer::new(track, legacy()) + }; + let mut video = add(".avc1", true); + let mut audio = add(".aac", false); + let failed = audio.name().to_string(); + let frame = |timestamp_ms: u64, payload: &'static [u8], keyframe| crate::container::Frame { + timestamp: Timestamp::from_millis(timestamp_ms).unwrap(), + duration: None, + payload: Bytes::from_static(payload), + keyframe, + }; + video.write(frame(0, &[0, 0, 0, 1, 0x65], true)).unwrap(); + audio.write(frame(0, &[0xde, 0xad], true)).unwrap(); + + let mut exporter = open_export(crate::source::announced(&consumer).await) + .await + .with_delay(moq_net::track::Delay::default().with_max(RECORDING_MAX_DELAY)) + .with_replay(); + let mut exported = Vec::new(); + assert!(drain_until_idle(&mut exporter, &mut exported).await.is_none()); + + let mut replacement = None; + if listed_first { + replacement = Some(add(".aac", false)); + assert!(drain_until_idle(&mut exporter, &mut exported).await.is_none()); + } + audio.abort(moq_net::Error::Transport("audio device lost".into())); + video.write(frame(33, &[0, 0, 0, 1, 0x41], false)).unwrap(); + assert!(drain_until_idle(&mut exporter, &mut exported).await.is_none()); + let mut replacement = replacement.unwrap_or_else(|| add(".aac", false)); + assert!(drain_until_idle(&mut exporter, &mut exported).await.is_none()); + for ms in [100, 123] { + replacement.write(frame(ms, &[0xbe, 0xef], true)).unwrap(); + assert!(drain_until_idle(&mut exporter, &mut exported).await.is_none()); + } + catalog.modify().unwrap().audio.renditions.remove(&failed); + video.write(frame(166, &[0, 0, 0, 1, 0x41], false)).unwrap(); + let _finished = replacement.finish().unwrap(); + let _finished = video.finish().unwrap(); + catalog.finish().unwrap(); + + let end = drain_until_idle(&mut exporter, &mut exported).await; + assert!(matches!(end, Some(Ok(()))), "listed first: {listed_first}: {end:?}"); + let tags = parse_tags(&exported); + let audio: Vec<&[u8]> = tags + .iter() + .filter(|t| t.tag_type == super::TAG_AUDIO && t.body[1] == super::AAC_RAW) + .map(|t| &t.body[2..]) + .collect(); + assert_eq!( + audio, + [&[0xde, 0xad][..], &[0xbe, 0xef], &[0xbe, 0xef]], + "listed first: {listed_first}" + ); + let video = tags.iter().filter(|t| t.tag_type == super::TAG_VIDEO).count(); + assert!(video >= 3, "the video played on: {video} tags"); + } +} + async fn drain_exporter_chunks(mut exporter: Export, chunks: usize) -> Vec { let mut exported = Vec::new(); for _ in 0..chunks { From 8fe4f84dfdef6063aec395234ee287f011c46692 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 18 Nov 2026 16:38:53 -0800 Subject: [PATCH 06/10] docs: exports follow a failed rendition's replacement; finish the quest Co-Authored-By: Claude Opus 5.5 --- doc/bin/cli.md | 15 +++++++++++-- quest/m2/export-replaced-rendition.md | 30 ------------------------- rs/moq-mux/src/container/flv/export.rs | 5 ++++- rs/moq-mux/src/container/fmp4/export.rs | 6 +++++ rs/moq-mux/src/container/fmp4/mod.rs | 3 ++- rs/moq-mux/src/container/mkv/export.rs | 10 ++++++--- rs/moq-mux/src/container/mkv/mod.rs | 3 ++- 7 files changed, 34 insertions(+), 38 deletions(-) delete mode 100644 quest/m2/export-replaced-rendition.md diff --git a/doc/bin/cli.md b/doc/bin/cli.md index a84872d319..ffe91a1945 100644 --- a/doc/bin/cli.md +++ b/doc/bin/cli.md @@ -141,10 +141,20 @@ keyframe when it re-enables. The muxed exports declare only enabled renditions in their header; one disabled afterwards keeps its track, idle until it re-enables. +A rendition whose track fails ends alone while the export still reads another, with +a warning: the muxed exports keep the other media, and the export fails only when +nothing else is left reading. A rendition of the same medium that the catalog +lists afterwards takes its place, as `import capture` publishes a reopened +microphone. `ts` adds it as a new stream; `fmp4`, `mkv`, and `flv` continue the +failed track with it, from its first sync frame past what was written, as long as +it has the same codec configuration. + fMP4 writes one fragment per publisher group; `--fragment-duration` caps it. The init segment declares every enabled rendition, so it is written only once each can be described, and the track set is then fixed: a new rendition or a changed -codec configuration ends the export. Restart it to pick up the change. +codec configuration ends the export. Restart it to pick up the change. A new +rendition waits instead while a track of its medium could still fail, to take +that track's place. Annex-B H.264 and H.265 whose catalog codec string and dimensions fix the sample entry are described at once as `avc3` or `hev1`, with SPS, PPS, and VPS kept in the samples, so an encoder restarting with a new SPS does not end the export. @@ -249,7 +259,8 @@ fallback when built with `openh264`, and audio is Opus; [moq-video](/lib/rs/moq- backends. An audio device that fails mid-session, such as a USB microphone re-enumerating, is reopened every 0.5 to 4 seconds as a new audio track. One still failing after 10 seconds ends only the audio track: video keeps -publishing, and the import exits with the audio error once it stops. A device +publishing, and the import exits with the audio error once it stops. A muxed +export of the broadcast follows each reopened track. A device that fails to open at startup ends the import at once. Audio appears in the catalog once its device opens; a microphone permission prompt leaves other media available. The camera and diff --git a/quest/m2/export-replaced-rendition.md b/quest/m2/export-replaced-rendition.md deleted file mode 100644 index 1f3bdb51eb..0000000000 --- a/quest/m2/export-replaced-rendition.md +++ /dev/null @@ -1,30 +0,0 @@ -# [M] Container exports outlive a rendition that fails and is replaced - -## Goal - -`moq export ts`, `fmp4`, `mkv`, and `flv` keep writing when one rendition's -track ends with an error and the catalog lists a replacement, as `moq import -capture` does when it reopens a failed microphone as a new audio track. The -export follows the replacement, or keeps the other media and says so, instead -of ending with the failed track's error. - -## Plan - -Found while validating the CLI's microphone reopen: with -`moq import capture -- export ts`, the reopen kept the video publishing, yet -the export ended with `audio capture: The requested audio device is not -available` once the old audio track failed -(`rs/moq-mux/src/container/consumer.rs`, "track failed; ending the reader"). -An `export h264` of the same broadcast kept writing, since it reads only video. - -Before that quest, the failed microphone ended the whole publish, so no -export outlived it; the reopen is what exposes this. - -Recommended: a rendition whose track fails while the catalog still lists the -broadcast ends only that rendition's reader, and the export picks up a new -rendition of the same medium the way it handles a catalog change; the export -fails only when no rendition of a selected medium remains. Check what the -catalog-identity republish ([moq-dev/moq#7110](https://github.com/moq-dev/moq/pull/7110)) -already does for a cleanly finished track and reuse it. - -Public API: none expected. Wire: none. diff --git a/rs/moq-mux/src/container/flv/export.rs b/rs/moq-mux/src/container/flv/export.rs index 77718ff81d..db7d005aa9 100644 --- a/rs/moq-mux/src/container/flv/export.rs +++ b/rs/moq-mux/src/container/flv/export.rs @@ -16,7 +16,10 @@ //! the stream yields are muxed and the rest are ignored. Each pick follows the //! catalog until the stream header goes out, then stays, following that rendition to another //! track when the catalog moves it (under a new sequence-header tag when its codec config -//! record changes; a move back in time fails the export). With +//! record changes; a move back in time fails the export). A pick whose track fails ends alone +//! while another track still reads, and continues on the best rendition of its kind and codec +//! that the catalog lists and no track reads, as a publisher that loses a microphone lists the +//! reopened one under a new name. With //! [`with_multitrack`](Export::with_multitrack) every rendition the stream yields //! is muxed instead, each as an enhanced-RTMP multitrack track addressed by its own //! track id (use this only for a player that advertised the `Multitrack` capability). diff --git a/rs/moq-mux/src/container/fmp4/export.rs b/rs/moq-mux/src/container/fmp4/export.rs index 9e3888d44b..c7704f4da1 100644 --- a/rs/moq-mux/src/container/fmp4/export.rs +++ b/rs/moq-mux/src/container/fmp4/export.rs @@ -64,6 +64,12 @@ const INIT_SHARE: usize = crate::container::consumer::DEFAULT_MAX_BUFFER; /// the new track's first sync sample past what was read. A new rendition, a changed sample /// entry, or a return that replays media already written fails the export. /// +/// A rendition whose track fails ends alone while another track still reads, and a new +/// rendition of its medium continues it the same way, under its declared track: a publisher +/// that loses a source, such as a microphone, lists a replacement under a new name. A new +/// rendition that joins while a track of its medium still reads waits to continue that one +/// should it fail, and fails the export once no track of its medium could. +/// /// [`poll_next_chunk`](Self::poll_next_chunk) returns the same bytes as a [`Chunk`], which /// separates the init segment from a [`Fragment`] carrying whether it begins at a /// sync sample and how long it lasts. A segmenting consumer (e.g. an HLS/LL-HLS diff --git a/rs/moq-mux/src/container/fmp4/mod.rs b/rs/moq-mux/src/container/fmp4/mod.rs index 5bae1b119d..31aa90cd4c 100644 --- a/rs/moq-mux/src/container/fmp4/mod.rs +++ b/rs/moq-mux/src/container/fmp4/mod.rs @@ -350,7 +350,8 @@ pub enum Error { previous: moq_net::Timestamp, }, - /// The init segment fixes the track set, so a rendition that joins later can't be written. + /// The init segment fixes the track set, so a rendition that joins later can't be written, + /// unless it continues a declared track of its medium that failed. #[error("rendition {0} joined after the init segment; restart the export to include it")] TrackAdded(String), diff --git a/rs/moq-mux/src/container/mkv/export.rs b/rs/moq-mux/src/container/mkv/export.rs index 4db2513f9e..81ec09b4b1 100644 --- a/rs/moq-mux/src/container/mkv/export.rs +++ b/rs/moq-mux/src/container/mkv/export.rs @@ -50,7 +50,10 @@ const TIMESTAMP_SCALE_NS: u64 = 1_000_000; /// A rendition the catalog moves to another track (a new `track` or `broadcast`) goes on /// under its track number from the new track's first sync frame past what was read, when /// the header's TrackEntry still describes it; otherwise, or when it goes back in time, the -/// export fails. +/// export fails. A rendition whose track fails ends alone while another track still reads, and +/// a rendition of its kind that joins after the header continues it the same way: a publisher +/// that loses a source, such as a microphone, lists a replacement under a new name. One that +/// joins while a track of its kind still reads waits to continue that one should it fail. pub struct Export { source: crate::Source, catalog: Option, @@ -699,8 +702,9 @@ impl Export { active.insert(name.clone(), ()); } - // The MKV `Tracks` element is written once and can't be amended, so reject a - // rendition added once the header has been emitted. + // The MKV `Tracks` element is written once and can't be amended, so a rendition added + // once the header has been emitted only continues a declared track of its kind that + // failed ([`Self::settle_spares`]). // // A declared rendition that leaves the catalog (disabled, or retired) keeps its // track and is read to its own end: a disabled rendition idles until it re-enables, diff --git a/rs/moq-mux/src/container/mkv/mod.rs b/rs/moq-mux/src/container/mkv/mod.rs index e48757945a..dda9a8bf80 100644 --- a/rs/moq-mux/src/container/mkv/mod.rs +++ b/rs/moq-mux/src/container/mkv/mod.rs @@ -137,7 +137,8 @@ pub enum Error { #[error("unsupported spherical video: {0}")] UnsupportedSpatial(&'static str), - /// The named track joined after the MKV header was emitted. + /// The named track joined after the MKV header was emitted, with no failed track of its + /// kind to continue. #[error("MKV track layout changed after header was emitted: track '{0}' added")] HeaderAddedTrack(String), From 6e66d81abb386786bff3ed4db5bb8749e253c89b Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 18 Nov 2026 16:41:39 -0800 Subject: [PATCH 07/10] style: format Co-Authored-By: Claude Opus 5.5 --- rs/moq-mux/src/container/flv/export.rs | 5 +++- rs/moq-mux/src/container/flv/export_test.rs | 10 ++++++-- rs/moq-mux/src/container/fmp4/export.rs | 12 ++++++++-- rs/moq-mux/src/container/fmp4/export_test.rs | 6 ++++- rs/moq-mux/src/container/mkv/export.rs | 24 ++++++++++++-------- rs/moq-mux/src/container/mkv/export_test.rs | 6 ++++- rs/moq-mux/src/container/ts/export_test.rs | 6 ++++- 7 files changed, 51 insertions(+), 18 deletions(-) diff --git a/rs/moq-mux/src/container/flv/export.rs b/rs/moq-mux/src/container/flv/export.rs index db7d005aa9..3b7e05c759 100644 --- a/rs/moq-mux/src/container/flv/export.rs +++ b/rs/moq-mux/src/container/flv/export.rs @@ -624,7 +624,10 @@ impl Export { if self.tracks().all(FlvTrack::finished) { return Err(err); } - if self.tracks().any(|track| track.name == name && track.read == Read::Lost) { + if self + .tracks() + .any(|track| track.name == name && track.read == Read::Lost) + { tracing::warn!(track = name, %err, "rendition failed; the export keeps its other media"); } Ok(()) diff --git a/rs/moq-mux/src/container/flv/export_test.rs b/rs/moq-mux/src/container/flv/export_test.rs index 7c7c397968..7cf8cab9b1 100644 --- a/rs/moq-mux/src/container/flv/export_test.rs +++ b/rs/moq-mux/src/container/flv/export_test.rs @@ -1758,9 +1758,15 @@ async fn a_failed_rendition_continues_on_its_replacement() { let track = producer.create_track(producer.unique_name(name), timed()).unwrap(); let mut modify = catalog.modify().unwrap(); if video { - modify.video.renditions.insert(track.name().to_string(), video_config.clone()); + modify + .video + .renditions + .insert(track.name().to_string(), video_config.clone()); } else { - modify.audio.renditions.insert(track.name().to_string(), audio_config.clone()); + modify + .audio + .renditions + .insert(track.name().to_string(), audio_config.clone()); } crate::container::Producer::new(track, legacy()) }; diff --git a/rs/moq-mux/src/container/fmp4/export.rs b/rs/moq-mux/src/container/fmp4/export.rs index c7704f4da1..c24bd70e10 100644 --- a/rs/moq-mux/src/container/fmp4/export.rs +++ b/rs/moq-mux/src/container/fmp4/export.rs @@ -1128,7 +1128,11 @@ impl Export { if active.contains(&name) || !listed.insert(name.clone()) || self.replaced.contains(&name) { continue; } - if !self.tracks.contains_key(&name) && !self.departed.contains_key(&name) && self.init.written() && !self.late { + if !self.tracks.contains_key(&name) + && !self.departed.contains_key(&name) + && self.init.written() + && !self.late + { if !self.spares.contains_key(&name) { tracing::warn!(track = %name, "rendition joined after the init; it waits to continue a failed one"); } @@ -1229,7 +1233,11 @@ impl Export { self.tracks.remove(name); } self.settle_spares()?; - if !self.tracks.values().any(|track| matches!(track.phase, Phase::Reading(_))) { + if !self + .tracks + .values() + .any(|track| matches!(track.phase, Phase::Reading(_))) + { return Err(err); } if self.tracks.get(name).is_some_and(Fmp4Track::lost) { diff --git a/rs/moq-mux/src/container/fmp4/export_test.rs b/rs/moq-mux/src/container/fmp4/export_test.rs index e0d50b4af2..b7c373b85a 100644 --- a/rs/moq-mux/src/container/fmp4/export_test.rs +++ b/rs/moq-mux/src/container/fmp4/export_test.rs @@ -1581,7 +1581,11 @@ async fn a_failed_rendition_continues_on_its_replacement() { fragments.extend(drain_now(&mut exporter).await); let samples = samples_per_track(&fragments); - assert_eq!(samples.get(&ids.1), Some(&12), "listed first: {listed_first}: {samples:?}"); + assert_eq!( + samples.get(&ids.1), + Some(&12), + "listed first: {listed_first}: {samples:?}" + ); assert!(samples[&ids.0] >= 3, "the video played on: {samples:?}"); assert_eq!(samples.len(), 2, "no track beyond the init's: {samples:?}"); } diff --git a/rs/moq-mux/src/container/mkv/export.rs b/rs/moq-mux/src/container/mkv/export.rs index 81ec09b4b1..f1560f300c 100644 --- a/rs/moq-mux/src/container/mkv/export.rs +++ b/rs/moq-mux/src/container/mkv/export.rs @@ -121,13 +121,7 @@ enum Read { impl MkvTrack { /// A track numbered `track_number` reading rendition `name` from `source`, with the video /// `config` it was added under. - fn new( - name: &str, - source: ExportSource, - kind: TrackKind, - config: Option, - track_number: u64, - ) -> Self { + fn new(name: &str, source: ExportSource, kind: TrackKind, config: Option, track_number: u64) -> Self { Self { clock: Default::default(), declared: None, @@ -655,8 +649,14 @@ impl Export { names.sort(); for name in names { let (kind, source) = match (catalog.video.renditions.get(&name), catalog.audio.renditions.get(&name)) { - (Some(config), _) => (TrackKind::Video, ExportSource::for_video(&self.source, &name, config, self.delay)), - (None, Some(config)) => (TrackKind::Audio, ExportSource::for_audio(&self.source, &name, config, self.delay)), + (Some(config), _) => ( + TrackKind::Video, + ExportSource::for_video(&self.source, &name, config, self.delay), + ), + (None, Some(config)) => ( + TrackKind::Audio, + ExportSource::for_audio(&self.source, &name, config, self.delay), + ), (None, None) => continue, }; let failed = self @@ -681,7 +681,11 @@ impl Export { self.replaced.insert(failed); continue; } - if !self.tracks.values().any(|track| track.kind == kind && !track.finished()) { + if !self + .tracks + .values() + .any(|track| track.kind == kind && !track.finished()) + { return Err(Error::HeaderAddedTrack(name).into()); } } diff --git a/rs/moq-mux/src/container/mkv/export_test.rs b/rs/moq-mux/src/container/mkv/export_test.rs index 385c8457ce..d916f32217 100644 --- a/rs/moq-mux/src/container/mkv/export_test.rs +++ b/rs/moq-mux/src/container/mkv/export_test.rs @@ -1006,7 +1006,11 @@ async fn a_failed_rendition_continues_on_its_replacement() { .filter(|(_, payload)| payload.as_slice() == b"old" || payload.as_slice() == b"new") .collect(); let payloads: Vec<&[u8]> = audio.iter().map(|(_, payload)| payload.as_slice()).collect(); - assert_eq!(payloads, [&b"old"[..], b"old", b"new", b"new", b"new"], "listed first: {listed_first}"); + assert_eq!( + payloads, + [&b"old"[..], b"old", b"new", b"new", b"new"], + "listed first: {listed_first}" + ); let numbers: std::collections::HashSet = audio.iter().map(|(number, _)| *number).collect(); assert_eq!(numbers.len(), 1, "the replacement writes under the declared track"); assert_eq!(blocks.len(), audio.len() + 3, "the video played on"); diff --git a/rs/moq-mux/src/container/ts/export_test.rs b/rs/moq-mux/src/container/ts/export_test.rs index 2145a24c63..da4613620d 100644 --- a/rs/moq-mux/src/container/ts/export_test.rs +++ b/rs/moq-mux/src/container/ts/export_test.rs @@ -9156,7 +9156,11 @@ async fn a_failed_rendition_is_replaced_while_the_rest_plays_on() { let (rest, end) = drain_to_end(&mut export).await; end.expect("a failed rendition with others still playing does not end the export"); frames.extend(rest); - assert_eq!(pes_count(&frames), 20 + 10 + 5, "every frame of all three tracks went out"); + assert_eq!( + pes_count(&frames), + 20 + 10 + 5, + "every frame of all three tracks went out" + ); } /// Publish an empty catalog at `live` under `route`. From 0c041f31b719185cf1e745ac4d4d3b739934ef31 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 18 Nov 2026 20:20:03 -0800 Subject: [PATCH 08/10] fix(mux): exports outlive a track failing before its config, and read a continued track at once Addresses the local Codex review: - A video that fails before its codec config no longer holds the header (TS, MKV, FLV) or the init (fMP4) forever: header readiness skips finished tracks without a config, and the header leaves them out. - A failed track continued on a spare is read in the same poll, since nothing else wakes the export for the spare's first frames (fMP4, MKV, FLV). - fMP4 prefers continuing a failed track over a departed one, and MKV builds a spare's source only when it continues a track. - MKV reads on after releasing frames into an open cluster: a track whose end had already arrived woke nothing, so an audio-only tail never ended. Co-Authored-By: Claude Opus 5.5 --- rs/moq-mux/src/container/flv/export.rs | 55 ++++--- rs/moq-mux/src/container/flv/export_test.rs | 145 +++++++++++++++++++ rs/moq-mux/src/container/fmp4/export.rs | 102 ++++++++----- rs/moq-mux/src/container/fmp4/export_test.rs | 91 +++++++++++- rs/moq-mux/src/container/mkv/export.rs | 136 +++++++++++------ rs/moq-mux/src/container/mkv/export_test.rs | 61 ++++++++ rs/moq-mux/src/container/test_util.rs | 16 ++ rs/moq-mux/src/container/ts/export.rs | 9 +- rs/moq-mux/src/container/ts/export_test.rs | 49 +++++++ 9 files changed, 553 insertions(+), 111 deletions(-) diff --git a/rs/moq-mux/src/container/flv/export.rs b/rs/moq-mux/src/container/flv/export.rs index 3b7e05c759..abfc12445d 100644 --- a/rs/moq-mux/src/container/flv/export.rs +++ b/rs/moq-mux/src/container/flv/export.rs @@ -607,8 +607,13 @@ impl Export { } } } + let mut continued = false; for (name, err) in lost { - self.survive(&name, err)?; + continued |= self.survive(&name, err)?; + } + // A continued track's new source is read now, since nothing else would wake the export for it. + if continued { + return self.fill(waiter); } Ok(()) } @@ -618,9 +623,9 @@ impl Export { /// A listed rendition of its kind and codec continues it at once. Otherwise, while another /// track still reads, only that rendition ends: a publisher that loses a source, such as a /// microphone, may list a replacement, which continues it then. With nothing left reading, - /// the failure is the export's, as before. - fn survive(&mut self, name: &str, err: crate::Error) -> crate::Result<()> { - self.replace_lost()?; + /// the failure is the export's, as before. Returns whether a track continued on another rendition. + fn survive(&mut self, name: &str, err: crate::Error) -> crate::Result { + let continued = self.replace_lost()?; if self.tracks().all(FlvTrack::finished) { return Err(err); } @@ -630,16 +635,18 @@ impl Export { { tracing::warn!(track = name, %err, "rendition failed; the export keeps its other media"); } - Ok(()) + Ok(continued) } /// Continue each track that failed after the header on a listed rendition no track reads, /// of its kind and codec, best first: the header fixed the tag shape, so a rendition of - /// another codec cannot continue it. - fn replace_lost(&mut self) -> crate::Result<()> { + /// another codec cannot continue it. Returns whether a track continued, whose new source has + /// yet to be polled. + fn replace_lost(&mut self) -> crate::Result { if !self.header_emitted { - return Ok(()); + return Ok(false); } + let mut continued = false; for index in 0..self.video.len() { let track = &self.video[index]; if track.read != Read::Lost { @@ -664,6 +671,7 @@ impl Export { track.dts_reserve = dts_reserve(&config); track.config = Some(config); self.replaced.insert(track.replace(name, source)); + continued = true; } for index in 0..self.audio.len() { let track = &self.audio[index]; @@ -685,8 +693,9 @@ impl Export { continue; }; self.replaced.insert(self.audio[index].replace(name, source)); + continued = true; } - Ok(()) + Ok(continued) } /// Whether rendition `name`, carried in `container`, is free to continue a failed track among @@ -718,15 +727,14 @@ impl Export { track.config = Some(config.clone()); } } + self.replaced + .retain(|name| catalog.video.renditions.contains_key(name) || catalog.audio.renditions.contains_key(name)); + self.listed = catalog.clone(); if !self.header_emitted { self.bind_video(&catalog)?; self.bind_audio(&catalog)?; } else { self.rebind(&catalog)?; - self.replaced.retain(|name| { - catalog.video.renditions.contains_key(name) || catalog.audio.renditions.contains_key(name) - }); - self.listed = catalog.clone(); self.replace_lost()?; if self.multitrack && (catalog.video.renditions.len() > self.video.len() @@ -885,11 +893,12 @@ impl Export { Ok(()) } - /// Header is ready once at least one track is bound and every bound track's - /// [`ExportSource`] has resolved its codec config (from the catalog - /// `description` or synthesized by the Avc3 transform). + /// Header is ready once a bound track and every bound track still reading has resolved its + /// codec config through its [`ExportSource`] (from the catalog `description` or synthesized by + /// the Avc3 transform). fn header_ready(&self) -> bool { - self.has_tracks() && self.tracks().all(|t| t.source.header_ready()) + // A track that ended before its codec config has no sequence header, and holds nothing back. + self.tracks().any(|t| t.source.header_ready()) && self.tracks().all(|t| t.finished() || t.source.header_ready()) } /// Build the FLV file header plus every bound track's sequence-header tag. @@ -899,11 +908,13 @@ impl Export { // FLV file header: signature, version 1, type flags, data offset = 9. out.put_slice(b"FLV"); out.put_u8(1); + // A track that ended before its codec config is left out: it has nothing to announce. + let declared = |track: &FlvTrack| !track.finished() || track.source.header_ready(); let mut flags = 0u8; - if !self.video.is_empty() { + if self.video.iter().any(declared) { flags |= 0x01; } - if !self.audio.is_empty() { + if self.audio.iter().any(declared) { flags |= 0x04; } out.put_u8(flags); @@ -911,14 +922,16 @@ impl Export { // PreviousTagSize0 is always zero. out.put_u32(0); - for track in self.video.iter().chain(&self.audio) { + for track in self.video.iter().chain(&self.audio).filter(|track| declared(track)) { if let Some(config) = track.config_record()? { let (tag_type, body) = self.sequence_header(track, &config); write_tag(&mut out, tag_type, 0, &body)?; } } for track in self.video.iter_mut().chain(&mut self.audio) { - track.announced = track.config_record()?; + if declared(track) { + track.announced = track.config_record()?; + } } // A group decodes its first `reorder` frames a millisecond apart before its earliest // presentation, so the deepest declaration bounds how far before zero a DTS can fall. diff --git a/rs/moq-mux/src/container/flv/export_test.rs b/rs/moq-mux/src/container/flv/export_test.rs index 7cf8cab9b1..0435d14c21 100644 --- a/rs/moq-mux/src/container/flv/export_test.rs +++ b/rs/moq-mux/src/container/flv/export_test.rs @@ -1827,6 +1827,151 @@ async fn a_failed_rendition_continues_on_its_replacement() { } } +/// An audio-only export binds the best-ranked of two listed renditions. When that one fails it +/// continues on the other with no catalog update, reading it from the poll that continues the +/// failed track: nothing else would wake the export for its first frames. +#[tokio::test(start_paused = true)] +async fn a_continued_track_wakes_the_export() { + use std::future::Future; + + use hang::catalog::{AAC, AudioConfig, Container}; + use moq_net::Timestamp; + + let mut producer = moq_net::broadcast::Info::new().produce(); + let consumer = producer.consume(); + let mut catalog = crate::catalog::Producer::new(&mut producer, crate::catalog::Config::default()).unwrap(); + let mut add = |name: &str, bitrate: u64| { + let track = producer.create_track(name, timed()).unwrap(); + let mut config = AudioConfig::new(AAC { profile: 2 }, 44100, 2); + config.container = Container::Legacy; + config.description = Some(Bytes::from_static(&ASC)); + config.bitrate = Some(bitrate); + catalog + .modify() + .unwrap() + .audio + .renditions + .insert(name.to_string(), config); + crate::container::Producer::new( + track, + crate::catalog::hang::Container::Legacy(crate::container::Kind::Data), + ) + }; + // Named so the name order alone would bind the other one. + let mut low = add("a.aac", 64_000); + let mut high = add("b.aac", 128_000); + let frame = |timestamp_ms: u64, payload: &'static [u8]| crate::container::Frame { + timestamp: Timestamp::from_millis(timestamp_ms).unwrap(), + duration: None, + payload: Bytes::from_static(payload), + keyframe: true, + }; + high.write(frame(0, &[0xde, 0xad])).unwrap(); + low.write(frame(0, &[0x10, 0x01])).unwrap(); + + let mut exporter = open_export(crate::source::announced(&consumer).await) + .await + .with_delay(moq_net::track::Delay::default().with_max(RECORDING_MAX_DELAY)) + .with_replay(); + let mut exported = Vec::new(); + assert!(drain_until_idle(&mut exporter, &mut exported).await.is_none()); + + let woken = std::sync::Arc::new(crate::container::test_util::Woken::default()); + let waker = std::task::Waker::from(woken.clone()); + let mut cx = std::task::Context::from_waker(&waker); + let mut next = Box::pin(exporter.next()); + assert!(next.as_mut().poll(&mut cx).is_pending()); + high.abort(moq_net::Error::Transport("audio device lost".into())); + assert!(woken.take(), "the failure woke the export"); + assert!(next.as_mut().poll(&mut cx).is_pending()); + low.write(frame(200, &[0xbe, 0xef])).unwrap(); + kio::clock::sleep(Duration::from_millis(10)).await; + assert!(woken.take(), "the continued rendition's frames woke the export"); + drop(next); + + let _finished = low.finish().unwrap(); + catalog.finish().unwrap(); + let end = drain_until_idle(&mut exporter, &mut exported).await; + assert!(matches!(end, Some(Ok(()))), "{end:?}"); + let tags = parse_tags(&exported); + let audio: Vec<&[u8]> = tags + .iter() + .filter(|t| t.tag_type == super::TAG_AUDIO && t.body[1] == super::AAC_RAW) + .map(|t| &t.body[2..]) + .collect(); + assert_eq!(audio, [&[0xde, 0xad][..], &[0xbe, 0xef]]); +} + +/// A video that fails before supplying its codec configuration leaves the header to the audio, +/// which plays on without it. +#[tokio::test(start_paused = true)] +async fn a_track_failing_before_its_config_leaves_the_header_to_the_rest() { + use hang::catalog::{AAC, AudioConfig, Container, H264, VideoConfig}; + use moq_net::Timestamp; + + let mut producer = moq_net::broadcast::Info::new().produce(); + let consumer = producer.consume(); + let mut catalog = crate::catalog::Producer::new(&mut producer, crate::catalog::Config::default()).unwrap(); + let legacy = || crate::catalog::hang::Container::Legacy(crate::container::Kind::Data); + + let video = producer.create_track(producer.unique_name(".avc3"), timed()).unwrap(); + let mut config = VideoConfig::new(H264 { + profile: 0x42, + constraints: 0xc0, + level: 0x1f, + inline: true, + }); + config.container = Container::Legacy; + catalog + .modify() + .unwrap() + .video + .renditions + .insert(video.name().to_string(), config); + let video = crate::container::Producer::new(video, legacy()); + + let audio = producer.create_track(producer.unique_name(".aac"), timed()).unwrap(); + let mut config = AudioConfig::new(AAC { profile: 2 }, 44100, 2); + config.container = Container::Legacy; + config.description = Some(Bytes::from_static(&ASC)); + catalog + .modify() + .unwrap() + .audio + .renditions + .insert(audio.name().to_string(), config); + let mut audio = crate::container::Producer::new(audio, legacy()); + let frame = |timestamp_ms: u64| crate::container::Frame { + timestamp: Timestamp::from_millis(timestamp_ms).unwrap(), + duration: None, + payload: Bytes::from_static(&[0xde, 0xad]), + keyframe: true, + }; + audio.write(frame(0)).unwrap(); + + let mut exporter = open_export(crate::source::announced(&consumer).await).await; + let mut exported = Vec::new(); + assert!(drain_until_idle(&mut exporter, &mut exported).await.is_none()); + assert!(exported.is_empty(), "the header waits on the video's config"); + + video.abort(moq_net::Error::Transport("camera lost".into())); + audio.write(frame(20)).unwrap(); + let _finished = audio.finish().unwrap(); + catalog.finish().unwrap(); + let end = drain_until_idle(&mut exporter, &mut exported).await; + assert!(matches!(end, Some(Ok(()))), "{end:?}"); + let tags = parse_tags(&exported); + let audio = tags + .iter() + .filter(|t| t.tag_type == super::TAG_AUDIO && t.body[1] == super::AAC_RAW) + .count(); + assert_eq!(audio, 2, "the audio went out"); + assert!( + tags.iter().all(|t| t.tag_type != super::TAG_VIDEO), + "no video was declared" + ); +} + async fn drain_exporter_chunks(mut exporter: Export, chunks: usize) -> Vec { let mut exported = Vec::new(); for _ in 0..chunks { diff --git a/rs/moq-mux/src/container/fmp4/export.rs b/rs/moq-mux/src/container/fmp4/export.rs index c24bd70e10..e57f2b100c 100644 --- a/rs/moq-mux/src/container/fmp4/export.rs +++ b/rs/moq-mux/src/container/fmp4/export.rs @@ -915,11 +915,15 @@ impl Export { } } } + let mut continued = false; for (name, err) in lost { - self.survive(&name, err)?; + continued |= self.survive(&name, err)?; + } + // A track that ended may have been the last a spare could continue. A continued track's + // new source is read before parking, since nothing else would wake the export for it. + if self.settle_spares()? || continued { + continue; } - // A track that ended may have been the last a spare could continue. - self.settle_spares()?; // 3. Emit the init segment once every track can be described, then the // fragments queued while it waited. @@ -1215,7 +1219,7 @@ impl Export { } self.replaced.retain(|name| listed.contains(name)); self.spares = spares; - self.settle_spares() + self.settle_spares().map(|_| ()) } /// Whether the export outlives the failure of track `name`, which ended it. @@ -1224,7 +1228,9 @@ impl Export { /// only that rendition ends: a publisher that loses a source, such as a microphone, may list /// a replacement, which continues it then. With nothing left reading, the failure is the /// export's, as before. - fn survive(&mut self, name: &str, err: crate::Error) -> Result<()> { + /// + /// Returns whether a spare continued a track, whose new source has yet to be polled. + fn survive(&mut self, name: &str, err: crate::Error) -> Result { // Before the init a track that could not be described declares nothing. if !self.init.written() && let Some(track) = self.tracks.get(name) @@ -1232,7 +1238,7 @@ impl Export { { self.tracks.remove(name); } - self.settle_spares()?; + let continued = self.settle_spares()?; if !self .tracks .values() @@ -1243,48 +1249,72 @@ impl Export { if self.tracks.get(name).is_some_and(Fmp4Track::lost) { tracing::warn!(track = name, %err, "rendition failed; the export keeps its other media"); } - Ok(()) + Ok(continued) } /// Continue each failed track with a spare of its medium, holding the other spares while a - /// track of their medium still reads. A spare with neither is a new rendition the init never - /// declared, which fails the export. - fn settle_spares(&mut self) -> Result<()> { + /// track of their medium still reads. Failing that, a spare continues a declared track of its + /// medium that left the catalog, which may have failed unread as its rendition left: a + /// publisher can retire the failed rendition in the snapshot that lists its replacement. A + /// spare with none of these is a new rendition the init never declared, which fails the + /// export. Returns whether a spare continued a track, whose new source has yet to be polled. + fn settle_spares(&mut self) -> Result { let mut names: Vec = self.spares.keys().cloned().collect(); names.sort(); + let mut continued = false; for name in names { let is_video = self.spares[&name].is_video(); - let failed = self - .tracks - .iter() - .filter(|(_, track)| track.is_video == is_video && track.lost()) - .map(|(failed, track)| (track.track_id, failed.clone())) - .min(); - if let Some((_, failed)) = failed { - let config = self.spares.remove(&name).expect("a listed spare"); - let Some(source) = config.subscribe(&self.source, &name, self.delay)? else { - continue; - }; - let mut track = self.tracks.remove(&failed).expect("a failed track"); - let Phase::Lost(previous) = std::mem::replace(&mut track.phase, Phase::Stopped) else { - unreachable!("picked a lost track"); - }; - tracing::info!(track = %name, replaces = %failed, "continuing a failed rendition"); - track.moved(); - track.rejoin(&name, config, source.continuing(&previous.source))?; - self.tracks.insert(name.clone(), track); - self.replaced.insert(failed); - continue; - } + let medium = |track: &Fmp4Track| track.is_video == is_video; + let pick = |tracks: &HashMap, phase: fn(&Phase) -> bool| { + tracks + .iter() + .filter(|(_, track)| medium(track) && phase(&track.phase)) + .map(|(key, track)| (track.track_id, key.clone())) + .min() + .map(|(_, key)| key) + }; let reading = self .tracks .values() - .any(|track| track.is_video == is_video && matches!(track.phase, Phase::Reading(_))); - if !reading { + .any(|track| medium(track) && matches!(track.phase, Phase::Reading(_))); + let lost = pick(&self.tracks, |phase| matches!(phase, Phase::Lost(_))); + let track = match lost { + Some(key) => self.tracks.remove(&key).map(|track| (key, track)), + None if reading => continue, + None => match pick(&self.tracks, |phase| matches!(phase, Phase::Departed(_))) { + Some(key) => self.tracks.remove(&key).map(|track| (key, track)), + None => pick(&self.departed, |_| true).and_then(|key| self.departed.remove_entry(&key)), + }, + }; + let Some((previous, mut track)) = track else { return Err(Error::TrackAdded(name).into()); - } + }; + let config = self.spares.remove(&name).expect("a listed spare"); + let Some(source) = config.subscribe(&self.source, &name, self.delay)? else { + // The catalog entry names no track to read, so the declared track stays as it was. + match track.phase { + Phase::Departed(_) if track.subscription().is_none() && track.buffer.is_empty() => { + self.departed.insert(previous, track) + } + _ => self.tracks.insert(previous, track), + }; + continue; + }; + let source = match std::mem::replace(&mut track.phase, Phase::Stopped) { + Phase::Lost(failed) => { + self.replaced.insert(previous.clone()); + source.continuing(&failed.source) + } + Phase::Departed(resume) => source.resuming(&resume), + _ => unreachable!("picked a lost or departed track"), + }; + tracing::info!(track = %name, replaces = %previous, "continuing a declared rendition"); + track.moved(); + track.rejoin(&name, config, source)?; + self.tracks.insert(name, track); + continued = true; } - Ok(()) + Ok(continued) } /// The bytes of media the export holds between its sources and the output. diff --git a/rs/moq-mux/src/container/fmp4/export_test.rs b/rs/moq-mux/src/container/fmp4/export_test.rs index b7c373b85a..8d71ad610a 100644 --- a/rs/moq-mux/src/container/fmp4/export_test.rs +++ b/rs/moq-mux/src/container/fmp4/export_test.rs @@ -1,11 +1,13 @@ //! Tests for the fMP4 exporter. +use std::future::Future; use std::io::Cursor; +use std::sync::Arc; use bytes::{Bytes, BytesMut}; use mp4_atom::{DecodeMaybe, Encode}; -use crate::container::test_util::{IDR, Live, PPS, SPS, raw_frame, video_frame}; +use crate::container::test_util::{IDR, Live, PPS, SPS, Woken, raw_frame, video_frame}; /// A millisecond track: the frames written here carry timestamps. fn timed() -> moq_net::track::Info { @@ -1549,7 +1551,7 @@ async fn a_rendition_joining_after_the_init_fails() { /// The replacement continues the declared audio track while the video plays on. #[tokio::test(start_paused = true)] async fn a_failed_rendition_continues_on_its_replacement() { - for listed_first in [false, true] { + for (listed_first, retired_unread) in [(false, false), (true, false), (false, true)] { let (mut live, audio) = live_av(); let failed = audio.name().to_string(); let mut audio = audio; @@ -1567,8 +1569,15 @@ async fn a_failed_rendition_continues_on_its_replacement() { } audio.abort(moq_net::Error::Transport("audio device lost".into())); live.track.write(video_frame(100_000, true)).unwrap(); - fragments.extend(drain_now(&mut exporter).await); + // Unless the publisher retires the failed rendition in the snapshot that lists its + // replacement, before the export reads the failure. + if !retired_unread { + fragments.extend(drain_now(&mut exporter).await); + } let mut replacement = replacement.unwrap_or_else(|| add_opus(&mut live).0); + if retired_unread { + live.catalog.modify().unwrap().audio.renditions.remove(&failed); + } // A replacement is new content, read from its live edge, as a moved rendition is. fragments.extend(drain_now(&mut exporter).await); write_audio(&mut replacement, 1_000_000, 5); @@ -1591,6 +1600,48 @@ async fn a_failed_rendition_continues_on_its_replacement() { } } +/// An audio-only export whose replacement was listed before the failure reads it from the poll +/// that continues the failed track: nothing else would wake the export for its first frames. +#[tokio::test(start_paused = true)] +async fn a_continued_track_wakes_the_export() { + let mut config = hang::catalog::AudioConfig::new(hang::catalog::AudioCodec::Opus, 48_000, 2); + config.container = hang::catalog::Container::Legacy; + let mut live = Live::audio(config); + write_audio(&mut live.track, 0, 6); + // One fragment per frame, so nothing of the failed track is left to write when it fails. + let mut exporter = crate::container::fmp4::Export::new(live.source().await, live.catalog_stream().await) + .with_delay(moq_net::track::Delay::default().with_max(RECORDING_MAX_DELAY)) + .with_fragment_duration(std::time::Duration::ZERO); + chunk_now(&mut exporter).await.init().expect("init"); + drain_now(&mut exporter).await; + let (mut replacement, _) = add_opus(&mut live); + drain_now(&mut exporter).await; + + let woken = Arc::new(Woken::default()); + let waker = std::task::Waker::from(woken.clone()); + let mut cx = std::task::Context::from_waker(&waker); + let mut next = Box::pin(exporter.next_chunk()); + assert!(next.as_mut().poll(&mut cx).is_pending()); + live.track.abort(moq_net::Error::Transport("audio device lost".into())); + // The failure wakes the export, whose next poll continues the track on the replacement. + assert!(woken.take(), "the failure woke the export"); + assert!(next.as_mut().poll(&mut cx).is_pending()); + write_audio(&mut replacement, 1_000_000, 6); + kio::clock::sleep(std::time::Duration::from_millis(10)).await; + assert!(woken.take(), "the replacement's frames woke the export"); + let chunk = kio::clock::timeout(std::time::Duration::from_secs(1), next) + .await + .expect("the export wrote the replacement") + .expect("exporter failed") + .expect("a chunk"); + let samples = samples_per_track(&[chunk.fragment().expect("a fragment")]); + assert_eq!( + samples.keys().copied().collect::>(), + [1], + "the declared track: {samples:?}" + ); +} + /// A rendition that joins after the init waits only while a declared track of its medium could /// still fail: once that one ends cleanly, it is a track the init never declared. #[tokio::test(start_paused = true)] @@ -1612,6 +1663,40 @@ async fn a_spare_rendition_fails_once_its_medium_ends_cleanly() { ); } +/// A video that fails before supplying its codec configuration leaves the init to the audio, +/// which plays on without it. +#[tokio::test(start_paused = true)] +async fn a_track_failing_before_its_config_leaves_the_init_to_the_rest() { + let (mut live, mut audio) = live_av(); + // The baseline catalog would describe the video without its SPS. + wait_for_sps(&mut live); + write_audio(&mut audio, 0, 5); + let mut exporter = crate::container::fmp4::Export::new(live.source().await, live.catalog_stream().await) + .with_delay(moq_net::track::Delay::default().with_max(RECORDING_MAX_DELAY)); + let early = kio::clock::timeout(std::time::Duration::from_millis(1), exporter.next_chunk()).await; + assert!(early.is_err(), "the init waits on the video's config: {early:?}"); + live.track.abort(moq_net::Error::Transport("camera lost".into())); + write_audio(&mut audio, 100_000, 5); + let _finished = audio.finish().unwrap(); + live.catalog.finish().unwrap(); + + let init = chunk_now(&mut exporter).await.init().expect("init"); + let mut cursor = Cursor::new(init.as_ref()); + let mut handlers = Vec::new(); + while let Some(atom) = mp4_atom::Any::decode_maybe(&mut cursor).expect("decode init") { + if let mp4_atom::Any::Moov(moov) = atom { + handlers.extend(moov.trak.iter().map(|trak| trak.mdia.hdlr.handler.to_string())); + } + } + assert_eq!(handlers, ["soun"], "only the audio is declared"); + let fragments = drain_now(&mut exporter).await; + assert_eq!( + samples_per_track(&fragments).values().sum::(), + 10, + "the audio went out" + ); +} + /// With nothing else reading, a failed track still fails the export. #[tokio::test(start_paused = true)] async fn the_last_failed_track_fails_the_export() { diff --git a/rs/moq-mux/src/container/mkv/export.rs b/rs/moq-mux/src/container/mkv/export.rs index f1560f300c..e803c44783 100644 --- a/rs/moq-mux/src/container/mkv/export.rs +++ b/rs/moq-mux/src/container/mkv/export.rs @@ -280,6 +280,17 @@ impl MkvTrack { } } +/// Whether the header can declare `track`, read for rendition `name`: its codec config, and a +/// video track's geometry, are known. +fn declarable(catalog: &Catalog, name: &str, track: &MkvTrack) -> bool { + track.source.header_ready() + && catalog + .video + .renditions + .get(name) + .is_none_or(|config| track.source.video_geometry_ready(config)) +} + #[derive(Clone, Copy, PartialEq, Eq)] enum TrackKind { Video, @@ -452,14 +463,22 @@ impl Export { return Poll::Pending; } + // A frame released into the open cluster returns nothing, yet may be what kept its track + // from reading on: read again, since a track whose end already arrived wakes nothing. + let mut released = false; loop { let (name, frame) = match self.held.take() { Some(held) => held, None => match self.jitter.poll_next(waiter) { Poll::Ready(ready) => (ready.track, ready.item), + Poll::Pending if std::mem::take(&mut released) => { + self.fill(waiter)?; + continue; + } Poll::Pending => break, }, }; + released = true; if let Some(chunk) = self.feed_frame(&name, frame)? { return Poll::Ready(Ok(Some(chunk))); } @@ -614,11 +633,16 @@ impl Export { track.release(name, &mut self.jitter, true)?; } } + let mut continued = false; for (name, err) in lost { - self.survive(&name, err)?; + continued |= self.survive(&name, err)?; + } + // A track that ended may have been the last a spare could continue. A continued track's + // new source is read now, since nothing else would wake the export for it. + if self.settle_spares()? || continued { + return self.fill(waiter); } - // A track that ended may have been the last a spare could continue. - self.settle_spares() + Ok(()) } /// Whether the export outlives the failure of track `name`, which [`Self::fill`] ended. @@ -626,37 +650,33 @@ impl Export { /// A spare of its kind continues it at once. Otherwise, while another track still reads, /// only that rendition ends: a publisher that loses a source, such as a microphone, may /// list a replacement, which continues it then. With nothing left reading, the failure is - /// the export's, as before. - fn survive(&mut self, name: &str, err: crate::Error) -> Result<()> { - self.settle_spares()?; + /// the export's, as before. Returns whether a spare continued a track. + fn survive(&mut self, name: &str, err: crate::Error) -> Result { + let continued = self.settle_spares()?; if self.tracks.values().all(MkvTrack::finished) { return Err(err); } if self.tracks.get(name).is_some_and(|track| track.read == Read::Lost) { tracing::warn!(track = name, %err, "rendition failed; the export keeps its other media"); } - Ok(()) + Ok(continued) } /// Continue each failed track with a spare of its kind, holding the other spares while a /// track of their kind still reads. A spare with neither is a rendition the header never - /// declared, which fails the export. - fn settle_spares(&mut self) -> Result<()> { + /// declared, which fails the export. Returns whether a spare continued a track, whose new + /// source has yet to be polled. + fn settle_spares(&mut self) -> Result { let Some(catalog) = self.catalog_snapshot.as_ref() else { - return Ok(()); + return Ok(false); }; let mut names: Vec = self.spares.iter().cloned().collect(); names.sort(); + let mut continued = false; for name in names { - let (kind, source) = match (catalog.video.renditions.get(&name), catalog.audio.renditions.get(&name)) { - (Some(config), _) => ( - TrackKind::Video, - ExportSource::for_video(&self.source, &name, config, self.delay), - ), - (None, Some(config)) => ( - TrackKind::Audio, - ExportSource::for_audio(&self.source, &name, config, self.delay), - ), + let kind = match (catalog.video.renditions.get(&name), catalog.audio.renditions.get(&name)) { + (Some(_), _) => TrackKind::Video, + (None, Some(_)) => TrackKind::Audio, (None, None) => continue, }; let failed = self @@ -665,31 +685,40 @@ impl Export { .filter(|(_, track)| track.kind == kind && track.read == Read::Lost) .map(|(key, track)| (track.track_number, key.clone())) .min(); - if let Some((_, key)) = failed { - let Some(source) = source? else { - continue; - }; - self.spares.remove(&name); - let track = self.tracks.get_mut(&key).expect("a failed track"); - tracing::info!(track = %name, replaces = %track.rendition, "continuing a failed rendition"); - track.rebind(&key, source, &mut self.jitter)?; - let failed = std::mem::replace(&mut track.rendition, name); - if kind == TrackKind::Video { - track.config = catalog.video.renditions.get(&track.rendition).cloned(); - track.reorder = None; + let Some((_, key)) = failed else { + if !self + .tracks + .values() + .any(|track| track.kind == kind && !track.finished()) + { + return Err(Error::HeaderAddedTrack(name).into()); } - self.replaced.insert(failed); continue; + }; + let source = match kind { + TrackKind::Video => { + ExportSource::for_video(&self.source, &name, &catalog.video.renditions[&name], self.delay)? + } + TrackKind::Audio => { + ExportSource::for_audio(&self.source, &name, &catalog.audio.renditions[&name], self.delay)? + } + }; + let Some(source) = source else { + continue; + }; + self.spares.remove(&name); + let track = self.tracks.get_mut(&key).expect("a failed track"); + tracing::info!(track = %name, replaces = %track.rendition, "continuing a failed rendition"); + track.rebind(&key, source, &mut self.jitter)?; + let failed = std::mem::replace(&mut track.rendition, name); + if kind == TrackKind::Video { + track.config = catalog.video.renditions.get(&track.rendition).cloned(); + track.reorder = None; } - if !self - .tracks - .values() - .any(|track| track.kind == kind && !track.finished()) - { - return Err(Error::HeaderAddedTrack(name).into()); - } + self.replaced.insert(failed); + continued = true; } - Ok(()) + Ok(continued) } fn update_catalog(&mut self, mut catalog: Catalog) -> Result<()> { @@ -752,7 +781,7 @@ impl Export { } } self.catalog_snapshot = Some(catalog); - return self.settle_spares(); + return self.settle_spares().map(|_| ()); } // Nothing went out yet, so a rendition that left the catalog is dropped, and one the @@ -807,13 +836,17 @@ impl Export { let Some(catalog) = self.catalog_snapshot.as_ref() else { return false; }; - !self.tracks.is_empty() - && self.tracks.values().all(|t| t.source.header_ready()) - && catalog.video.renditions.iter().all(|(name, config)| { - self.tracks - .get(name) - .is_some_and(|track| track.source.video_geometry_ready(config)) - }) + // A track that ended before its codec config can't be declared, and holds nothing back. + self.tracks.iter().any(|(name, track)| declarable(catalog, name, track)) + && self + .tracks + .iter() + .all(|(name, track)| track.finished() || declarable(catalog, name, track)) + && catalog + .video + .renditions + .keys() + .all(|name| self.tracks.contains_key(name)) } fn build_header(&mut self) -> Result { @@ -836,6 +869,13 @@ impl Export { let video = catalog.video.renditions.keys().map(|name| (name, TrackKind::Video)); let audio = catalog.audio.renditions.keys().map(|name| (name, TrackKind::Audio)); for (name, kind) in video.chain(audio) { + if self + .tracks + .get(name) + .is_some_and(|track| track.finished() && !declarable(catalog, name, track)) + { + continue; + } let track = self.tracks.get_mut(name).ok_or_else(|| match kind { TrackKind::Video => Error::MissingVideoTrack(name.clone()), TrackKind::Audio => Error::MissingAudioTrack(name.clone()), diff --git a/rs/moq-mux/src/container/mkv/export_test.rs b/rs/moq-mux/src/container/mkv/export_test.rs index d916f32217..b3a93d0c7b 100644 --- a/rs/moq-mux/src/container/mkv/export_test.rs +++ b/rs/moq-mux/src/container/mkv/export_test.rs @@ -1017,6 +1017,67 @@ async fn a_failed_rendition_continues_on_its_replacement() { } } +/// An audio-only export whose replacement was listed before the failure reads it from the poll +/// that continues the failed track: nothing else would wake the export for its first frames. +#[tokio::test(start_paused = true)] +async fn a_continued_track_wakes_the_export() { + use std::future::Future; + + let mut config = hang::catalog::AudioConfig::new(hang::catalog::AAC { profile: 2 }, 44100, 2); + config.description = Some(Bytes::from_static(&[0x12, 0x10])); + let mut live = Live::audio(config); + live.track.write(raw_frame(0, b"old", true)).unwrap(); + let mut exporter = crate::container::mkv::Export::new(live.source().await, live.catalog_stream().await) + .with_fragment_duration(std::time::Duration::ZERO); + let mut out = drain_now(&mut exporter).await.unwrap(); + let mut replacement = add_aac(&mut live); + out.extend(drain_now(&mut exporter).await.unwrap()); + + let woken = std::sync::Arc::new(crate::container::test_util::Woken::default()); + let waker = std::task::Waker::from(woken.clone()); + let mut cx = std::task::Context::from_waker(&waker); + let mut next = Box::pin(exporter.next()); + assert!(next.as_mut().poll(&mut cx).is_pending()); + live.track.abort(moq_net::Error::Transport("audio device lost".into())); + assert!(woken.take(), "the failure woke the export"); + assert!(next.as_mut().poll(&mut cx).is_pending()); + replacement.write(raw_frame(200_000, b"new", true)).unwrap(); + kio::clock::sleep(std::time::Duration::from_millis(10)).await; + assert!(woken.take(), "the replacement's frames woke the export"); + drop(next); + + let _finished = replacement.finish().unwrap(); + live.catalog.finish().unwrap(); + while let Some(chunk) = exporter.next().await.unwrap() { + out.extend_from_slice(&chunk); + } + let payloads: Vec> = blocks(out).into_iter().map(|(_, payload)| payload).collect(); + assert_eq!(payloads, [b"old".to_vec(), b"new".to_vec()]); +} + +/// A video track that fails before its codec configuration declares nothing, so the header goes +/// out with the audio that still plays. +#[tokio::test(start_paused = true)] +async fn a_track_failing_before_its_config_leaves_the_header_to_the_rest() { + let mut live = Live::avc3(); + let mut audio = add_aac(&mut live); + audio.write(raw_frame(0, b"aud", true)).unwrap(); + let mut exporter = crate::container::mkv::Export::new(live.source().await, live.catalog_stream().await); + assert!( + drain_now(&mut exporter).await.unwrap().is_empty(), + "the header waits on the video" + ); + live.track.abort(moq_net::Error::Transport("camera lost".into())); + audio.write(raw_frame(20_000, b"aud", true)).unwrap(); + let _finished = audio.finish().unwrap(); + live.catalog.finish().unwrap(); + let mut out = Vec::new(); + while let Some(chunk) = exporter.next().await.unwrap() { + out.extend_from_slice(&chunk); + } + assert_eq!(blocks(out).len(), 2, "the audio went out"); +} + /// A rendition that joins after the header waits only while a declared track of its kind could /// still fail: once that one ends cleanly, it is a track the header never declared. #[tokio::test(start_paused = true)] diff --git a/rs/moq-mux/src/container/test_util.rs b/rs/moq-mux/src/container/test_util.rs index fb30b24cb0..7252c032fb 100644 --- a/rs/moq-mux/src/container/test_util.rs +++ b/rs/moq-mux/src/container/test_util.rs @@ -590,3 +590,19 @@ impl moq_net::transport::poll::Session for Gated { self.inner.metrics() } } + +/// Records whether it was woken since last asked. +#[derive(Default)] +pub(crate) struct Woken(std::sync::atomic::AtomicBool); + +impl Woken { + pub(crate) fn take(&self) -> bool { + self.0.swap(false, std::sync::atomic::Ordering::SeqCst) + } +} + +impl std::task::Wake for Woken { + fn wake(self: std::sync::Arc) { + self.0.store(true, std::sync::atomic::Ordering::SeqCst); + } +} diff --git a/rs/moq-mux/src/container/ts/export.rs b/rs/moq-mux/src/container/ts/export.rs index 126c8a9271..0dcd58f2c6 100644 --- a/rs/moq-mux/src/container/ts/export.rs +++ b/rs/moq-mux/src/container/ts/export.rs @@ -3129,10 +3129,13 @@ where } } - /// Header is ready when every track's [`ExportSource`] has resolved its - /// codec config (from the catalog `description`, or built by the transform). + /// Header is ready when a track, and every track still reading, has resolved its codec + /// config through its [`ExportSource`] (from the catalog `description`, or built by the + /// transform). A track that ended before its config holds nothing back. fn header_ready(&self) -> bool { - self.program.tracks.values().all(|t| t.source.header_ready()) + let tracks = &self.program.tracks; + tracks.values().any(|t| t.source.header_ready()) + && tracks.values().all(|t| t.read != Read::Live || t.source.header_ready()) } /// Every video track has buffered its first frame (the keyframe) or finished. diff --git a/rs/moq-mux/src/container/ts/export_test.rs b/rs/moq-mux/src/container/ts/export_test.rs index da4613620d..a427b7055c 100644 --- a/rs/moq-mux/src/container/ts/export_test.rs +++ b/rs/moq-mux/src/container/ts/export_test.rs @@ -9163,6 +9163,55 @@ async fn a_failed_rendition_is_replaced_while_the_rest_plays_on() { ); } +/// A video that fails before supplying its codec configuration leaves the program to the audio, +/// which plays on without it. +#[tokio::test(start_paused = true)] +async fn a_track_failing_before_its_config_leaves_the_header_to_the_rest() { + let mut broadcast = moq_net::broadcast::Info::new().produce(); + let consumer = broadcast.consume(); + let mut catalog = crate::catalog::Producer::new(&mut broadcast, crate::catalog::Config::default()).unwrap(); + let vtrack = broadcast + .create_track("0.avc3", hang::container::track_info(hang::catalog::PRIORITY.video)) + .unwrap(); + let mut cfg = VideoConfig::new(H264 { + profile: 0x42, + constraints: 0xc0, + level: 0x1f, + inline: true, + }); + cfg.container = Container::Legacy; + catalog + .modify() + .unwrap() + .video + .renditions + .insert("0.avc3".to_string(), cfg); + let video = Producer::new(vtrack, HangContainer::Legacy(crate::container::Kind::Data)); + let mut audio = aac_rendition(&mut broadcast, &mut catalog, "0.aac"); + + let mut export = open_export(crate::source::announced(&consumer).await, RECORDING_MAX_AGE) + .await + .unwrap() + .with_replay(); + for ms in (0..100).step_by(20) { + write_aac(&mut audio, ms); + } + let mut frames = poll_frames(&mut export); + assert_eq!(pes_count(&frames), 0, "the program waits on the video's config"); + + video.abort(moq_net::Error::Transport("camera lost".into())); + for ms in (100..200).step_by(20) { + write_aac(&mut audio, ms); + } + let _finished = audio.finish().unwrap(); + catalog.finish().unwrap(); + + let (rest, end) = drain_to_end(&mut export).await; + end.expect("a video failing before its config does not end the export"); + frames.extend(rest); + assert_eq!(pes_count(&frames), 10, "every audio frame went out"); +} + /// Publish an empty catalog at `live` under `route`. fn publish_live( origin: &moq_net::origin::Producer, From 7cb3a3dd4549563c6b3f082cbc5c765b2c86ca65 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 18 Nov 2026 20:45:38 -0800 Subject: [PATCH 09/10] fix(mux): a track the header left out stays out FLV and MKV leave a track that ended before its codec config out of the header. A new Read::Omitted keeps a replacement or a catalog move from reviving it: FLV would write video under an audio-only header, and MKV a track number its header never declared. MKV fails such a replacement with HeaderAddedTrack, as for any kind the header lacks; FLV ignores it. Co-Authored-By: Claude Opus 5.5 --- rs/moq-mux/src/container/flv/export.rs | 12 ++++--- rs/moq-mux/src/container/flv/export_test.rs | 32 ++++++++++++++++++- rs/moq-mux/src/container/mkv/export.rs | 22 +++++++++---- rs/moq-mux/src/container/mkv/export_test.rs | 35 +++++++++++++-------- rs/moq-mux/src/container/test_util.rs | 2 +- 5 files changed, 78 insertions(+), 25 deletions(-) diff --git a/rs/moq-mux/src/container/flv/export.rs b/rs/moq-mux/src/container/flv/export.rs index abfc12445d..c4ed53e58c 100644 --- a/rs/moq-mux/src/container/flv/export.rs +++ b/rs/moq-mux/src/container/flv/export.rs @@ -228,6 +228,9 @@ enum Read { Finished, /// The track itself failed. Another rendition of its kind and codec may continue it. Lost, + /// The track ended before its codec config, so the header left it out: nothing may continue + /// it, or the file would carry media its header never declared. + Omitted, } impl FlvTrack { @@ -764,7 +767,7 @@ impl Export { let Some(config) = catalog.video.renditions.get(&track.name) else { continue; }; - if track.source.reads(&self.source, &track.name, config) { + if track.read == Read::Omitted || track.source.reads(&self.source, &track.name, config) { continue; } if video_flavor(config)? != track.flavor { @@ -781,7 +784,7 @@ impl Export { let Some(config) = catalog.audio.renditions.get(&track.name) else { continue; }; - if track.source.reads(&self.source, &track.name, config) { + if track.read == Read::Omitted || track.source.reads(&self.source, &track.name, config) { continue; } if audio_flavor(config)? != track.flavor { @@ -929,8 +932,9 @@ impl Export { } } for track in self.video.iter_mut().chain(&mut self.audio) { - if declared(track) { - track.announced = track.config_record()?; + match declared(track) { + true => track.announced = track.config_record()?, + false => track.read = Read::Omitted, } } // A group decodes its first `reorder` frames a millisecond apart before its earliest diff --git a/rs/moq-mux/src/container/flv/export_test.rs b/rs/moq-mux/src/container/flv/export_test.rs index 0435d14c21..291293b5af 100644 --- a/rs/moq-mux/src/container/flv/export_test.rs +++ b/rs/moq-mux/src/container/flv/export_test.rs @@ -1903,7 +1903,7 @@ async fn a_continued_track_wakes_the_export() { } /// A video that fails before supplying its codec configuration leaves the header to the audio, -/// which plays on without it. +/// which plays on without it, and no replacement can add the video the header left out. #[tokio::test(start_paused = true)] async fn a_track_failing_before_its_config_leaves_the_header_to_the_rest() { use hang::catalog::{AAC, AudioConfig, Container, H264, VideoConfig}; @@ -1956,10 +1956,40 @@ async fn a_track_failing_before_its_config_leaves_the_header_to_the_rest() { video.abort(moq_net::Error::Transport("camera lost".into())); audio.write(frame(20)).unwrap(); + assert!(drain_until_idle(&mut exporter, &mut exported).await.is_none()); + + // The header declared no video, so a compatible replacement can't add it. + let replacement = producer.create_track(producer.unique_name(".avc1"), timed()).unwrap(); + let mut config = VideoConfig::new(H264 { + profile: 0x42, + constraints: 0xc0, + level: 0x1f, + inline: false, + }); + config.container = Container::Legacy; + config.description = Some(Bytes::from(avcc())); + catalog + .modify() + .unwrap() + .video + .renditions + .insert(replacement.name().to_string(), config); + let mut replacement = crate::container::Producer::new(replacement, legacy()); + replacement + .write(crate::container::Frame { + timestamp: Timestamp::from_millis(40).unwrap(), + duration: None, + payload: Bytes::from_static(&[0, 0, 0, 1, 0x65]), + keyframe: true, + }) + .unwrap(); + assert!(drain_until_idle(&mut exporter, &mut exported).await.is_none()); + let _finished = audio.finish().unwrap(); catalog.finish().unwrap(); let end = drain_until_idle(&mut exporter, &mut exported).await; assert!(matches!(end, Some(Ok(()))), "{end:?}"); + assert_eq!(exported[4], 0x04, "the header declares only audio"); let tags = parse_tags(&exported); let audio = tags .iter() diff --git a/rs/moq-mux/src/container/mkv/export.rs b/rs/moq-mux/src/container/mkv/export.rs index e803c44783..fdbe3672d0 100644 --- a/rs/moq-mux/src/container/mkv/export.rs +++ b/rs/moq-mux/src/container/mkv/export.rs @@ -116,6 +116,9 @@ enum Read { Finished, /// The track itself failed. A spare of its kind may continue it. Lost, + /// The track ended before its codec config, so the header left it out: nothing may continue + /// it, or the file would carry a track number its header never declared. + Omitted, } impl MkvTrack { @@ -756,7 +759,10 @@ impl Export { self.spares = spares; self.replaced.retain(|name| active.contains_key(name)); for (name, config) in &catalog.audio.renditions { - if let Some((key, track)) = self.tracks.iter_mut().find(|(_, track)| track.rendition == *name) + if let Some((key, track)) = self + .tracks + .iter_mut() + .find(|(_, track)| track.rendition == *name && track.read != Read::Omitted) && !track.source.reads(&self.source, name, config) && let Some(source) = ExportSource::for_audio(&self.source, name, config, self.delay)? { @@ -764,7 +770,11 @@ impl Export { } } for (name, config) in &catalog.video.renditions { - if let Some((key, track)) = self.tracks.iter_mut().find(|(_, track)| track.rendition == *name) { + if let Some((key, track)) = self + .tracks + .iter_mut() + .find(|(_, track)| track.rendition == *name && track.read != Read::Omitted) + { if !track.source.reads(&self.source, name, config) && let Some(source) = ExportSource::for_video(&self.source, name, config, self.delay)? { @@ -869,11 +879,11 @@ impl Export { let video = catalog.video.renditions.keys().map(|name| (name, TrackKind::Video)); let audio = catalog.audio.renditions.keys().map(|name| (name, TrackKind::Audio)); for (name, kind) in video.chain(audio) { - if self - .tracks - .get(name) - .is_some_and(|track| track.finished() && !declarable(catalog, name, track)) + if let Some(track) = self.tracks.get_mut(name) + && track.finished() + && !declarable(catalog, name, track) { + track.read = Read::Omitted; continue; } let track = self.tracks.get_mut(name).ok_or_else(|| match kind { diff --git a/rs/moq-mux/src/container/mkv/export_test.rs b/rs/moq-mux/src/container/mkv/export_test.rs index b3a93d0c7b..5bef25bac6 100644 --- a/rs/moq-mux/src/container/mkv/export_test.rs +++ b/rs/moq-mux/src/container/mkv/export_test.rs @@ -1059,23 +1059,32 @@ async fn a_continued_track_wakes_the_export() { /// out with the audio that still plays. #[tokio::test(start_paused = true)] async fn a_track_failing_before_its_config_leaves_the_header_to_the_rest() { - let mut live = Live::avc3(); - let mut audio = add_aac(&mut live); - audio.write(raw_frame(0, b"aud", true)).unwrap(); - let mut exporter = crate::container::mkv::Export::new(live.source().await, live.catalog_stream().await); + let mut config = hang::catalog::AudioConfig::new(hang::catalog::AAC { profile: 2 }, 44100, 2); + config.description = Some(Bytes::from_static(&[0x12, 0x10])); + let mut live = Live::audio(config); + let video = live.add_track(".avc3", Live::insert_avc3); + live.track.write(raw_frame(0, b"aud", true)).unwrap(); + let mut exporter = crate::container::mkv::Export::new(live.source().await, live.catalog_stream().await) + .with_fragment_duration(std::time::Duration::ZERO); assert!( drain_now(&mut exporter).await.unwrap().is_empty(), "the header waits on the video" ); - live.track.abort(moq_net::Error::Transport("camera lost".into())); - audio.write(raw_frame(20_000, b"aud", true)).unwrap(); - let _finished = audio.finish().unwrap(); - live.catalog.finish().unwrap(); - let mut out = Vec::new(); - while let Some(chunk) = exporter.next().await.unwrap() { - out.extend_from_slice(&chunk); - } - assert_eq!(blocks(out).len(), 2, "the audio went out"); + video.abort(moq_net::Error::Transport("camera lost".into())); + live.track.write(raw_frame(20_000, b"aud", true)).unwrap(); + let out = drain_now(&mut exporter).await.unwrap(); + assert!( + !blocks(out).is_empty(), + "the header went out without the video, then the audio" + ); + + // The header declared no video track, so a replacement can't continue the one it left out. + let replacement = live.add_track(".avc3", Live::insert_avc3); + let err = drain_now(&mut exporter).await.unwrap_err(); + assert!( + matches!(&err, crate::Error::Mkv(crate::container::mkv::Error::HeaderAddedTrack(added)) if added == replacement.name()), + "{err:?}" + ); } /// A rendition that joins after the header waits only while a declared track of its kind could diff --git a/rs/moq-mux/src/container/test_util.rs b/rs/moq-mux/src/container/test_util.rs index 7252c032fb..a659e913ca 100644 --- a/rs/moq-mux/src/container/test_util.rs +++ b/rs/moq-mux/src/container/test_util.rs @@ -72,7 +72,7 @@ impl Live { Self::new(".avc3", Self::insert_avc3) } - fn insert_avc3(catalog: &mut crate::catalog::Producer, name: String) { + pub(crate) fn insert_avc3(catalog: &mut crate::catalog::Producer, name: String) { let mut config = VideoConfig::new(H264 { profile: 0x42, constraints: 0xc0, From 75adb15d415c747556f851a024e8ac5dadd6873b Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Thu, 19 Nov 2026 00:18:46 -0800 Subject: [PATCH 10/10] fix(mux): keep a failed undescribed track retired, and its flush error the export's - fMP4: a track that fails before the init describes it stays retired while its rendition is listed, so a later catalog update neither resubscribes it nor holds it as a spare that fails the export with TrackAdded. - FLV: a video replacement declaring a reorder depth raises the shift before its first DTS, as a depth declared after the header does. - TS: the PMT leaves out a track that ended before its codec config, and a flush error on a lost track stays the export's error instead of passing for the track's loss. Co-Authored-By: Claude Opus 5.5 --- rs/moq-mux/src/container/flv/export.rs | 5 ++ rs/moq-mux/src/container/flv/export_test.rs | 89 ++++++++++++++++++++ rs/moq-mux/src/container/fmp4/export.rs | 17 ++-- rs/moq-mux/src/container/fmp4/export_test.rs | 22 +++-- rs/moq-mux/src/container/ts/export.rs | 25 +++--- rs/moq-mux/src/container/ts/export_test.rs | 6 ++ 6 files changed, 138 insertions(+), 26 deletions(-) diff --git a/rs/moq-mux/src/container/flv/export.rs b/rs/moq-mux/src/container/flv/export.rs index c4ed53e58c..6bb47cecde 100644 --- a/rs/moq-mux/src/container/flv/export.rs +++ b/rs/moq-mux/src/container/flv/export.rs @@ -670,6 +670,11 @@ impl Export { continue; }; let track = &mut self.video[index]; + // The replacement's declared depth deepens the shift before its first DTS, as a depth + // declared after the header does ([`Self::update_catalog`]). + if track.flavor.has_composition_time() { + self.shift = self.shift.max(config.reorder.map_or(0, u32::from)); + } track.fallback_description = fallback_description(&config); track.dts_reserve = dts_reserve(&config); track.config = Some(config); diff --git a/rs/moq-mux/src/container/flv/export_test.rs b/rs/moq-mux/src/container/flv/export_test.rs index 291293b5af..b3fdf7ed8c 100644 --- a/rs/moq-mux/src/container/flv/export_test.rs +++ b/rs/moq-mux/src/container/flv/export_test.rs @@ -1827,6 +1827,95 @@ async fn a_failed_rendition_continues_on_its_replacement() { } } +/// A video replacement that declares a reorder depth deepens the shift before its first DTS, so +/// a group presenting from just past zero still decodes at or after it. +#[tokio::test(start_paused = true)] +async fn a_replacement_declaring_reorder_raises_the_shift() { + use hang::catalog::{AAC, AudioConfig, Container, H264, VideoConfig}; + use moq_net::Timestamp; + + let mut producer = moq_net::broadcast::Info::new().produce(); + let consumer = producer.consume(); + let mut catalog = crate::catalog::Producer::new(&mut producer, crate::catalog::Config::default()).unwrap(); + let mut video_config = VideoConfig::new(H264 { + profile: 0x42, + constraints: 0xc0, + level: 0x1f, + inline: false, + }); + video_config.container = Container::Legacy; + video_config.description = Some(Bytes::from(avcc())); + let mut audio_config = AudioConfig::new(AAC { profile: 2 }, 44100, 2); + audio_config.container = Container::Legacy; + audio_config.description = Some(Bytes::from_static(&ASC)); + + let legacy = || crate::catalog::hang::Container::Legacy(crate::container::Kind::Data); + let add_video = + |producer: &mut moq_net::broadcast::Producer, catalog: &mut crate::catalog::Producer, config: &VideoConfig| { + let track = producer.create_track(producer.unique_name(".avc1"), timed()).unwrap(); + catalog + .modify() + .unwrap() + .video + .renditions + .insert(track.name().to_string(), config.clone()); + crate::container::Producer::new(track, legacy()) + }; + let mut video = add_video(&mut producer, &mut catalog, &video_config); + let audio_track = producer.create_track(producer.unique_name(".aac"), timed()).unwrap(); + let mut audio = crate::container::Producer::new(audio_track, legacy()); + let frame = |ms: u64, payload: &'static [u8], keyframe| crate::container::Frame { + timestamp: Timestamp::from_millis(ms).unwrap(), + duration: None, + payload: Bytes::from_static(payload), + keyframe, + }; + video.write(frame(0, &[0, 0, 0, 1, 0x65], true)).unwrap(); + audio.write(frame(0, &[0xde, 0xad], true)).unwrap(); + catalog + .modify() + .unwrap() + .audio + .renditions + .insert(audio.name().to_string(), audio_config); + + let mut exporter = open_export(crate::source::announced(&consumer).await) + .await + .with_delay(moq_net::track::Delay::default().with_max(RECORDING_MAX_DELAY)) + .with_replay(); + let mut exported = Vec::new(); + assert!(drain_until_idle(&mut exporter, &mut exported).await.is_none()); + + video.abort(moq_net::Error::Transport("camera lost".into())); + assert!(drain_until_idle(&mut exporter, &mut exported).await.is_none()); + video_config.reorder = Some(2); + let mut replacement = add_video(&mut producer, &mut catalog, &video_config); + assert!(drain_until_idle(&mut exporter, &mut exported).await.is_none()); + for (ms, keyframe) in [(1, true), (5, false), (3, false)] { + let payload: &'static [u8] = if keyframe { + &[0, 0, 0, 1, 0x65] + } else { + &[0, 0, 0, 1, 0x41] + }; + replacement.write(frame(ms, payload, keyframe)).unwrap(); + } + let _finished = replacement.finish().unwrap(); + let _finished = audio.finish().unwrap(); + catalog.finish().unwrap(); + + let end = drain_until_idle(&mut exporter, &mut exported).await; + assert!(matches!(end, Some(Ok(()))), "{end:?}"); + let video: Vec<_> = parse_tags(&exported) + .iter() + .filter(|tag| tag.tag_type == super::TAG_VIDEO && tag.body[1] == super::AVC_NALU) + .map(|tag| { + let pts = i64::from(tag.timestamp) + i64::from(super::read_i24(&tag.body[2..5])); + (tag.timestamp, pts) + }) + .collect(); + assert_eq!(video, [(0, 0), (1, 3), (2, 7), (3, 5)]); +} + /// An audio-only export binds the best-ranked of two listed renditions. When that one fails it /// continues on the other with no catalog update, reading it from the poll that continues the /// failed track: nothing else would wake the export for its first frames. diff --git a/rs/moq-mux/src/container/fmp4/export.rs b/rs/moq-mux/src/container/fmp4/export.rs index e57f2b100c..d98beff896 100644 --- a/rs/moq-mux/src/container/fmp4/export.rs +++ b/rs/moq-mux/src/container/fmp4/export.rs @@ -96,8 +96,9 @@ pub struct Export { /// ([`Phase::Lost`]), and fails the export once none is left that could. spares: HashMap, - /// Renditions a spare replaced after their track failed, ignored while still listed. - replaced: HashSet, + /// Failed renditions ignored while still listed: one a spare replaced, or one whose track + /// failed before the init described it. + retired: HashSet, init: Init, @@ -728,7 +729,7 @@ impl Export { tracks: HashMap::new(), departed: HashMap::new(), spares: HashMap::new(), - replaced: HashSet::new(), + retired: HashSet::new(), init: Init::Waiting { queued: VecDeque::new(), deadline: None, @@ -1129,7 +1130,7 @@ impl Export { let mut spares = HashMap::new(); for (name, config) in video.chain(audio) { // A name used by both a video and an audio rendition is the video one. - if active.contains(&name) || !listed.insert(name.clone()) || self.replaced.contains(&name) { + if active.contains(&name) || !listed.insert(name.clone()) || self.retired.contains(&name) { continue; } if !self.tracks.contains_key(&name) @@ -1217,7 +1218,7 @@ impl Export { queued.retain(|(name, _)| active.contains(name)); } } - self.replaced.retain(|name| listed.contains(name)); + self.retired.retain(|name| listed.contains(name)); self.spares = spares; self.settle_spares().map(|_| ()) } @@ -1231,12 +1232,14 @@ impl Export { /// /// Returns whether a spare continued a track, whose new source has yet to be polled. fn survive(&mut self, name: &str, err: crate::Error) -> Result { - // Before the init a track that could not be described declares nothing. + // Before the init a track that could not be described declares nothing, and its rendition + // is not read again while the publisher keeps it listed. if !self.init.written() && let Some(track) = self.tracks.get(name) && !track.described() { self.tracks.remove(name); + self.retired.insert(name.to_string()); } let continued = self.settle_spares()?; if !self @@ -1302,7 +1305,7 @@ impl Export { }; let source = match std::mem::replace(&mut track.phase, Phase::Stopped) { Phase::Lost(failed) => { - self.replaced.insert(previous.clone()); + self.retired.insert(previous.clone()); source.continuing(&failed.source) } Phase::Departed(resume) => source.resuming(&resume), diff --git a/rs/moq-mux/src/container/fmp4/export_test.rs b/rs/moq-mux/src/container/fmp4/export_test.rs index 8d71ad610a..c51226ae22 100644 --- a/rs/moq-mux/src/container/fmp4/export_test.rs +++ b/rs/moq-mux/src/container/fmp4/export_test.rs @@ -1664,10 +1664,12 @@ async fn a_spare_rendition_fails_once_its_medium_ends_cleanly() { } /// A video that fails before supplying its codec configuration leaves the init to the audio, -/// which plays on without it. +/// which plays on without it. While the publisher keeps the failed video listed, a later catalog +/// update neither reads it again nor takes it for a rendition the init never declared. #[tokio::test(start_paused = true)] async fn a_track_failing_before_its_config_leaves_the_init_to_the_rest() { let (mut live, mut audio) = live_av(); + let name = audio.name().to_string(); // The baseline catalog would describe the video without its SPS. wait_for_sps(&mut live); write_audio(&mut audio, 0, 5); @@ -1677,10 +1679,20 @@ async fn a_track_failing_before_its_config_leaves_the_init_to_the_rest() { assert!(early.is_err(), "the init waits on the video's config: {early:?}"); live.track.abort(moq_net::Error::Transport("camera lost".into())); write_audio(&mut audio, 100_000, 5); - let _finished = audio.finish().unwrap(); - live.catalog.finish().unwrap(); let init = chunk_now(&mut exporter).await.init().expect("init"); + let mut fragments = drain_now(&mut exporter).await; + live.catalog + .modify() + .unwrap() + .audio + .renditions + .get_mut(&name) + .unwrap() + .bitrate = Some(64_000); + write_audio(&mut audio, 200_000, 5); + let _finished = audio.finish().unwrap(); + live.catalog.finish().unwrap(); let mut cursor = Cursor::new(init.as_ref()); let mut handlers = Vec::new(); while let Some(atom) = mp4_atom::Any::decode_maybe(&mut cursor).expect("decode init") { @@ -1689,10 +1701,10 @@ async fn a_track_failing_before_its_config_leaves_the_init_to_the_rest() { } } assert_eq!(handlers, ["soun"], "only the audio is declared"); - let fragments = drain_now(&mut exporter).await; + fragments.extend(drain_now(&mut exporter).await); assert_eq!( samples_per_track(&fragments).values().sum::(), - 10, + 15, "the audio went out" ); } diff --git a/rs/moq-mux/src/container/ts/export.rs b/rs/moq-mux/src/container/ts/export.rs index 0dcd58f2c6..8e8fbd7b85 100644 --- a/rs/moq-mux/src/container/ts/export.rs +++ b/rs/moq-mux/src/container/ts/export.rs @@ -555,12 +555,15 @@ impl Track { } /// Read within the jitter window, or hold the first frame until the program tables are built. - fn fill(&mut self, name: &str, waiter: &kio::Waiter, input: &mut Input<'_>) -> crate::Result<()> { + /// + /// Returns the track's own failure, which ended it, apart from the export's errors: the + /// export decides whether it outlives that ([`Export::survive`]). + fn fill(&mut self, name: &str, waiter: &kio::Waiter, input: &mut Input<'_>) -> crate::Result> { if self.key.name.is_empty() { self.key.name = name.to_string(); } if self.pending.is_some() || self.read != Read::Live { - return Ok(()); + return Ok(None); } let is_video = matches!(self.kind, Kind::Video(_)); // A placed frame is judged at release, against the keyframe's departure ([`Export::leads_video`]). @@ -652,7 +655,7 @@ impl Track { if self.read == Read::Ended && !input.waiting_for_header { self.release(name, input.jitter, true)?; } - lost.map_or(Ok(()), Err) + Ok(lost) } /// The samples an audio frame of `payload` lasts and their rate, if it may share a PES with @@ -1933,11 +1936,7 @@ where }, ); let ended = live && track.read != Read::Live; - let lost = track.source.lost(); - if let Err(err) = filled.or_else(|err| match lost { - true => self.survive(&name, err), - false => Err(err), - }) { + if let Err(err) = filled.and_then(|lost| lost.map_or(Ok(()), |err| self.survive(&name, err))) { self.leave(err)?; } if ended || matches!(self.program.feed, Feed::Retired(_)) { @@ -2382,10 +2381,7 @@ where }; let mut lost = Vec::new(); for (name, track) in &mut self.program.tracks { - if let Err(err) = track.fill(name, waiter, &mut input) { - if !track.source.lost() { - return Err(err); - } + if let Some(err) = track.fill(name, waiter, &mut input)? { lost.push((name.clone(), err)); } } @@ -3273,8 +3269,9 @@ where /// Build the PAT/PMT once every track's PID and codec is known. fn build_psi(&mut self) -> Result<()> { + // A track that ended before its codec config never carries a frame, so the PMT leaves it out. for track in self.program.tracks.values_mut() { - track.listed = true; + track.listed = track.read == Read::Live || track.source.header_ready(); } let pcr_pid = self.pick_clock()?; let pmt = self.program_map(pcr_pid)?; @@ -3296,7 +3293,7 @@ where if !self.program.pcr_discontinuity { self.program.schedule.open(); } - for track in self.program.tracks.values() { + for track in self.program.tracks.values().filter(|track| track.listed) { self.program.liveness.register(track.pid); } self.program.psi = Some(Psi { diff --git a/rs/moq-mux/src/container/ts/export_test.rs b/rs/moq-mux/src/container/ts/export_test.rs index a427b7055c..d30f6211a7 100644 --- a/rs/moq-mux/src/container/ts/export_test.rs +++ b/rs/moq-mux/src/container/ts/export_test.rs @@ -9210,6 +9210,12 @@ async fn a_track_failing_before_its_config_leaves_the_header_to_the_rest() { end.expect("a video failing before its config does not end the export"); frames.extend(rest); assert_eq!(pes_count(&frames), 10, "every audio frame went out"); + let listed: Vec<_> = pmts(&frames).into_iter().map(|(_, types)| types).collect(); + assert!(!listed.is_empty(), "the program went out"); + assert!( + listed.iter().all(|types| *types == [StreamType::AdtsAac]), + "the PMT lists only the audio: {listed:?}" + ); } /// Publish an empty catalog at `live` under `route`.