diff --git a/quest/m1/precut-fixes/video-decode-lifecycle.md b/quest/m1/precut-fixes/video-decode-lifecycle.md
deleted file mode 100644
index 50d133ccee9..00000000000
--- a/quest/m1/precut-fixes/video-decode-lifecycle.md
+++ /dev/null
@@ -1,34 +0,0 @@
-# [S] moq-video keeps a boundary through a failed drain and bounds its colour queue
-
-## Goal
-
-The video decoder and capture keep their lifecycles whole: a Gap or End is
-delivered and leading-picture recovery is armed even when the drain before
-it fails; the colour-switch queue stays bounded by the decoder's reorder
-depth whatever a publisher's keyframes signal; and capture flushes its
-encoder before dropping it, so the frames it holds are published.
-
-## Plan
-
-Found by the 2026-11-17 pre-cut correctness audit, from source; reproduce
-first (inject a flush error through the `probe` backend).
-
-- `rs/moq-video/src/decode/consumer.rs`: at a Gap or End, `self.drain().await?`
- returns before queueing `Read::Gap`/`Read::End` and setting `recover`, and
- the marker is already consumed. Keep the drained pictures ahead of their
- boundary: take the drain's result without `?`, queue whatever it drained,
- then the boundary, arm recovery, and only then return the drain's error.
- Read the end-of-track branch, which already survives a failed drain. From
- [moq-dev/moq#6475](https://github.com/moq-dev/moq/pull/6475).
-- `rs/moq-video/src/decode/decoder.rs`: an entry pushes per keyframe whose SPS
- changes colour space and pops only when a delivered picture reaches it; a
- publisher alternating colour spaces with a dropped first picture grows it
- until the next Gap. Drop entries at or after a new keyframe's timestamp and
- cap at the reorder depth, as `arrivals` is. From
- [moq-dev/moq#5808](https://github.com/moq-dev/moq/pull/5808).
-- `rs/moq-video/src/encode/producer.rs` `capture_loop`: `drop(encoder)` with
- no `flush()`, against the crate's own rule from #8372; Media Foundation and
- MediaCodec lose their last frames on a source end or resize. On `release`
- too.
-
-Public API: none. Wire: none.
diff --git a/rs/moq-video/src/decode/backend/mod.rs b/rs/moq-video/src/decode/backend/mod.rs
index 850aa2472c6..ee2d9b18ad5 100644
--- a/rs/moq-video/src/decode/backend/mod.rs
+++ b/rs/moq-video/src/decode/backend/mod.rs
@@ -297,6 +297,12 @@ const NAMED_ONLY: &[Candidate] = &[
open: probe::Buffered::open,
drives: Drives::Own,
},
+ Candidate {
+ name: probe::FAILING_FLUSH_NAME,
+ supports: |c| matches!(c, Codec::H264),
+ open: probe::Buffered::open_failing_flush,
+ drives: Drives::Own,
+ },
Candidate {
name: probe::REORDER_NAME,
supports: |c| matches!(c, Codec::H264),
@@ -305,7 +311,7 @@ const NAMED_ONLY: &[Candidate] = &[
},
Candidate {
name: probe::HOLDING_NAME,
- supports: |c| matches!(c, Codec::H264),
+ supports: |c| matches!(c, Codec::H264 | Codec::H265),
open: probe::Reorder::open_holding,
drives: Drives::Own,
},
diff --git a/rs/moq-video/src/decode/backend/probe.rs b/rs/moq-video/src/decode/backend/probe.rs
index 3b6aa933ae4..ebfde73fdf1 100644
--- a/rs/moq-video/src/decode/backend/probe.rs
+++ b/rs/moq-video/src/decode/backend/probe.rs
@@ -25,6 +25,10 @@ pub(crate) const NAME: &str = "probe";
/// A test decoder that holds one picture until the next call or a flush.
pub(crate) const BUFFERED_NAME: &str = "probe-buffered";
+/// A test decoder that holds one picture like [`BUFFERED_NAME`], whose flush
+/// readies it and then fails, as a codec that errors partway through a drain.
+pub(crate) const FAILING_FLUSH_NAME: &str = "probe-failing-flush";
+
/// A test decoder that reorders like B-frames do: it holds two pictures and
/// returns the earliest once it has a third. It hands pictures back at
/// nanosecond scale, as MediaCodec does, whatever scale the access unit came in.
@@ -148,6 +152,7 @@ pub(crate) const SIZE: Size = Size {
pub(crate) struct Probe(VecDeque);
pub(crate) struct Buffered {
+ name: &'static str,
held: Option,
ready: VecDeque,
}
@@ -180,6 +185,15 @@ impl Probe {
impl Buffered {
pub(crate) fn open(_stream: &Stream, _config: &Config) -> Result, Error> {
Ok(Box::new(Self {
+ name: BUFFERED_NAME,
+ held: None,
+ ready: VecDeque::new(),
+ }))
+ }
+
+ pub(crate) fn open_failing_flush(_stream: &Stream, _config: &Config) -> Result, Error> {
+ Ok(Box::new(Self {
+ name: FAILING_FLUSH_NAME,
held: None,
ready: VecDeque::new(),
}))
@@ -381,11 +395,14 @@ impl Backend for Buffered {
fn flush(&mut self) -> Result<(), Error> {
self.ready.extend(self.held.take());
+ if self.name == FAILING_FLUSH_NAME {
+ return Err(anyhow::anyhow!("probe: flush failed").into());
+ }
Ok(())
}
fn name(&self) -> &str {
- BUFFERED_NAME
+ self.name
}
}
diff --git a/rs/moq-video/src/decode/consumer.rs b/rs/moq-video/src/decode/consumer.rs
index 73db18de7ed..015dc47c15d 100644
--- a/rs/moq-video/src/decode/consumer.rs
+++ b/rs/moq-video/src/decode/consumer.rs
@@ -350,16 +350,20 @@ impl Reader {
// Drained so the pictures from before the boundary all come out ahead of it,
// rather than whenever the media after it pushes them through. The decoder
// stays usable and restarts on the next group's keyframe.
+ // The marker is consumed, so a failed drain still queues it and arms recovery
+ // before reporting, or the next read would never see it.
Some(Encoded::Gap { timestamp, duration }) => {
- self.drain().await?;
+ let drained = self.drain().await;
self.pending.push_back((Read::Gap { timestamp, duration }, None));
self.recover = true;
+ drained?;
continue;
}
// A fresh encoder has no preceding GOP to reference, so no recovery.
Some(Encoded::End { end, .. }) => {
- self.drain().await?;
+ let drained = self.drain().await;
self.pending.push_back((Read::End { end }, None));
+ drained?;
continue;
}
None => None,
@@ -370,7 +374,7 @@ impl Reader {
// dropped before the drain ran retries it rather than reporting
// an end the stream has not reached. Flushing twice is safe: the
// second hands back nothing.
- let tail = self.decoder.flush().await;
+ let drained = self.drain().await;
// Set before the error is returned, not after. A flush that
// failed once fails the same way every time, and the track has
// ended either way, so leaving the flag down turns one bad
@@ -378,13 +382,7 @@ impl Reader {
// nothing in between to wait on. A caller that treats a codec
// error as one lost picture and carries on then spins.
self.drained = true;
- // Queue what the flush readied before reporting its error, so a
- // later read still hands those pictures over.
- let received = self.receive();
- // Whatever the flush did not return never comes back.
- self.arrivals.clear();
- tail?;
- received?;
+ drained?;
continue;
};
@@ -452,15 +450,14 @@ impl Reader {
Ok(())
}
- /// Queue every picture the decoder still holds.
+ /// Queue every picture the decoder still holds. A flush that fails still
+ /// queues what it readied, so a later read hands those pictures over.
async fn drain(&mut self) -> Result<(), Error> {
- let drained = match self.decoder.flush().await {
- Ok(()) => self.receive(),
- Err(err) => Err(err),
- };
+ let flushed = self.decoder.flush().await;
+ let received = self.receive();
// Whatever the flush did not return never comes back.
self.arrivals.clear();
- drained
+ flushed.and(received)
}
}
@@ -1144,6 +1141,145 @@ mod tests {
assert_eq!(reads, ["frame 100000", "end 133332", "frame 200000", "none"]);
}
+ /// Every read until the track is done, as text: a codec error is one read too.
+ async fn read_all(consumer: &mut Consumer) -> Vec {
+ let mut reads = Vec::new();
+ loop {
+ reads.push(match consumer.read().await {
+ Ok(Some(Read::Frame(frame))) => format!("frame {}", frame.timestamp.as_micros().unwrap()),
+ Ok(Some(Read::Gap { timestamp, .. })) => format!("gap {}", timestamp.as_micros().unwrap()),
+ Ok(Some(Read::End { end })) => format!("end {}", end.as_micros().unwrap()),
+ Ok(None) => return reads,
+ Err(_) => "error".to_string(),
+ });
+ }
+ }
+
+ /// A drain that fails at an end still delivers the pictures it readied ahead
+ /// of the end, and the end itself, after reporting the error.
+ #[tokio::test]
+ async fn a_failed_drain_keeps_its_end() {
+ let broadcast = moq_net::broadcast::Info::new().produce();
+ let track = broadcast
+ .create_track("video", hang::container::track_info(hang::catalog::PRIORITY.video))
+ .unwrap();
+ let subscriber = broadcast.consume();
+ let mut producer = moq_mux::container::Producer::new(
+ track,
+ moq_mux::catalog::hang::Container::Legacy(moq_mux::container::Kind::Video),
+ );
+ let picture = |micros: u64| moq_mux::container::Frame {
+ timestamp: Timestamp::from_micros(micros).unwrap(),
+ duration: Some(Timestamp::from_micros(33_333).unwrap()),
+ payload: Bytes::from_static(b"access unit"),
+ keyframe: true,
+ };
+ producer.write(picture(100_000)).unwrap();
+ producer.cut(None).unwrap();
+ producer.discontinuity().unwrap();
+ producer.write(picture(200_000)).unwrap();
+ let _finished = producer.finish().unwrap();
+
+ let catalog = VideoConfig::new(hang::catalog::H264 {
+ inline: true,
+ profile: 0x42,
+ constraints: 0,
+ level: 30,
+ });
+ let mut consumer = Consumer::new(
+ &subscriber,
+ &catalog,
+ "video",
+ Options {
+ decoder: Config {
+ kind: Kind::Named(probe::FAILING_FLUSH_NAME.into()),
+ ..Config::new()
+ },
+ delay: Delay {
+ max: Some(std::time::Duration::from_secs(10)),
+ ..Delay::default()
+ },
+ ..Options::new()
+ },
+ )
+ .await
+ .unwrap();
+
+ assert_eq!(
+ read_all(&mut consumer).await,
+ ["error", "frame 100000", "end 133332", "error", "frame 200000"]
+ );
+ }
+
+ /// A drain that fails at a gap still delivers the gap after the pictures it
+ /// readied, and still trims the leading pictures of the recovery group.
+ #[tokio::test(start_paused = true)]
+ async fn a_failed_drain_keeps_its_gap_and_recovery() {
+ let broadcast = moq_net::broadcast::Info::new().produce();
+ let track = broadcast
+ .create_track("video", hang::container::track_info(hang::catalog::PRIORITY.video))
+ .unwrap();
+ let catalog = VideoConfig::new(hang::catalog::H264 {
+ inline: true,
+ profile: 0x42,
+ constraints: 0,
+ level: 30,
+ });
+ let mut consumer = Consumer::new(
+ &broadcast.consume(),
+ &catalog,
+ "video",
+ Options {
+ decoder: Config {
+ kind: Kind::Named(probe::FAILING_FLUSH_NAME.into()),
+ ..Config::new()
+ },
+ delay: Delay {
+ max: Some(std::time::Duration::from_secs(10)),
+ ..Delay::default()
+ },
+ ..Options::new()
+ },
+ )
+ .await
+ .unwrap();
+ let wire = moq_mux::catalog::hang::Container::Legacy(moq_mux::container::Kind::Video);
+ let write = |sequence, stamps: &[u64]| {
+ let mut group = track.create_group(moq_net::group::Info { start: sequence }).unwrap();
+ let frames: Vec<_> = stamps
+ .iter()
+ .enumerate()
+ .map(|(index, stamp)| moq_mux::container::Frame {
+ timestamp: Timestamp::from_micros(*stamp).unwrap(),
+ duration: None,
+ payload: Bytes::from_static(b"access unit"),
+ keyframe: index == 0,
+ })
+ .collect();
+ wire.write(&mut group, &frames).unwrap();
+ group.finish().unwrap();
+ };
+ write(10, &[1000, 1100]);
+ let first = consumer.next_frame().await.unwrap().unwrap();
+ assert_eq!(first.timestamp.as_micros().unwrap(), 1000);
+
+ consumer.reader().track.set_delay(Delay::default());
+ write(11, &[2000]);
+ write(12, &[3000, 2800, 2900, 3100]);
+ let _track = track.finish().unwrap();
+ let reads = read_all(&mut consumer).await;
+ assert_eq!(
+ reads[..3],
+ ["error", "frame 1100", "gap 1100"],
+ "the drained picture, then its gap: {reads:?}"
+ );
+ assert_eq!(
+ reads[3..],
+ ["frame 3000", "error", "frame 3100"],
+ "recovery trims the leading pictures: {reads:?}"
+ );
+ }
+
/// A read dropped while a threaded flush is in flight loses nothing: the
/// next read finishes that same flush rather than issuing another into a
/// poisoned sink, and only then reports the end.
diff --git a/rs/moq-video/src/decode/decoder.rs b/rs/moq-video/src/decode/decoder.rs
index 5516d65d3ae..fa502df749b 100644
--- a/rs/moq-video/src/decode/decoder.rs
+++ b/rs/moq-video/src/decode/decoder.rs
@@ -139,6 +139,12 @@ impl Conversion {
}
}
+/// The most colour switches a decoder waits on. Each one is a keyframe whose
+/// pictures the backend still holds behind earlier ones, so a decoder never needs
+/// more than it holds pictures: at most 16 for H.264 and H.265, and this leaves
+/// room for a hardware pipeline beyond that, as the consumer's arrivals do.
+const SWITCHES: usize = 32;
+
/// Decodes container payloads (the codec bitstream) into raw [`Frame`]s.
///
/// The bring-your-own-payload layer under [`Consumer`](super::Consumer): use it
@@ -294,13 +300,36 @@ impl Decoder {
/// Convert one access unit and hand it to the backend.
fn submit(&mut self, payload: &Bytes, timestamp: Timestamp, keyframe: bool) -> Result<(), Error> {
let access_unit = self.conversion.access_unit(payload, keyframe)?;
- if keyframe
- && let Some(color) = super::vui::signalled(self.codec, &access_unit)
- && self.switches.back().map_or(self.color, |(_, color)| *color) != color
+ let signalled = keyframe
+ .then(|| super::vui::signalled(self.codec, &access_unit))
+ .flatten();
+ // A refused keyframe yields no picture, so its switch would wait for one forever.
+ self.backend.decode(access_unit, timestamp, keyframe)?;
+ if keyframe {
+ self.switch(timestamp, signalled);
+ }
+ Ok(())
+ }
+
+ /// Record the space a keyframe at `timestamp` switched to, if it signalled one.
+ fn switch(&mut self, timestamp: Timestamp, signalled: Option