diff --git a/crates/video/src/av1/encode/README.md b/crates/video/src/av1/encode/README.md index 2df88ba64..0fd60c50f 100644 --- a/crates/video/src/av1/encode/README.md +++ b/crates/video/src/av1/encode/README.md @@ -8,9 +8,10 @@ no `unsafe`, builds for `wasm32-unknown-unknown`). The optional `av1-large-encode` feature exposes `LargeEncoder`, a tiled rav1e-backed encoder for 8-bit 4:2:0 frames up to 8192 samples per side. Use it when the clean-room `Encoder`'s one-tile limits (4096 samples per side and 2304 superblocks) would reject the frame. It supports constant -quantizer rate control and emits one low-latency packet per input frame. The fallback is native -only; the clean-room encoder remains available without the feature and supports 8- and 10-bit -input. +quantizer rate control. `push` returns packets available so far, which can be empty while frames +are buffered; `finish` returns delayed packets. Each packet includes its input frame number for +matching durations. The fallback is native only; the clean-room encoder remains available without +the feature and supports 8- and 10-bit input. ## What is implemented diff --git a/crates/video/src/av1/encode/large.rs b/crates/video/src/av1/encode/large.rs index 109a536dc..8ed26d52b 100644 --- a/crates/video/src/av1/encode/large.rs +++ b/crates/video/src/av1/encode/large.rs @@ -12,6 +12,14 @@ pub struct LargeEncoder { width: usize, height: usize, seq_header: Option>, + finished: bool, +} + +/// An encoded frame and the number of the input frame it represents. +#[derive(Clone, Debug, PartialEq, Eq)] +pub struct BufferedPacket { + pub input_frame_number: u64, + pub packet: Packet, } impl LargeEncoder { @@ -50,11 +58,13 @@ impl LargeEncoder { ec.max_key_frame_interval = cfg.keyint.clamp(1, 120) as u64; ec.tiles = std::thread::available_parallelism().map_or(4, |n| n.get()).clamp(2, 16); let ctx = Config::new().with_encoder_config(ec).new_context().map_err(|e| Error::InvalidConfig(format!("rav1e: {e}")))?; - Ok(Self { ctx, width: cfg.width as usize, height: cfg.height as usize, seq_header: None }) + Ok(Self { ctx, width: cfg.width as usize, height: cfg.height as usize, seq_header: None, finished: false }) } - /// Encodes one frame. The frame planes must match the configured 4:2:0 dimensions. - pub fn encode_with_key(&mut self, frame: &Frame<'_>, force_key: bool) -> Result { + fn submit(&mut self, frame: &Frame<'_>, force_key: bool) -> Result<(), Error> { + if self.finished { + return Err(Error::InvalidFrame("AV1 encoder was already finished".into())); + } if frame.y_stride < self.width || frame.uv_stride < self.width / 2 || frame.y.len() < frame.y_stride.saturating_mul(self.height) @@ -70,14 +80,54 @@ impl LargeEncoder { let params = FrameParameters { frame_type_override: if force_key { FrameTypeOverride::Key } else { FrameTypeOverride::No }, ..Default::default() }; self.ctx.send_frame((input, params)).map_err(|e| Error::InvalidFrame(format!("rav1e: {e}")))?; + Ok(()) + } + + fn packet(&mut self, packet: rav1e::prelude::Packet) -> Result { + let (data, seq) = sample_data(&packet.data)?; + if self.seq_header.is_none() { + self.seq_header = seq; + } + Ok(BufferedPacket { input_frame_number: packet.input_frameno, packet: Packet { data, keyframe: packet.frame_type == FrameType::KEY } }) + } + + fn drain(&mut self) -> Result, Error> { + let mut packets = Vec::new(); + loop { + match self.ctx.receive_packet() { + Ok(packet) => packets.push(self.packet(packet)?), + Err(rav1e::prelude::EncoderStatus::Encoded) => {} + Err(rav1e::prelude::EncoderStatus::NeedMoreData) if !self.finished => return Ok(packets), + Err(rav1e::prelude::EncoderStatus::LimitReached) if self.finished => return Ok(packets), + Err(e) => return Err(Error::InvalidFrame(format!("rav1e: {e}"))), + } + } + } + + /// Submit a frame and return all packets available now, which may be empty while the encoder + /// buffers input. Call [`Self::finish`] after the last frame to retrieve delayed packets. + pub fn push(&mut self, frame: &Frame<'_>, force_key: bool) -> Result, Error> { + self.submit(frame, force_key)?; + self.drain() + } + + /// Finish the stream and return its remaining packets. Repeated calls return no packets. + pub fn finish(&mut self) -> Result, Error> { + if !self.finished { + self.ctx.send_frame(None).map_err(|e| Error::InvalidFrame(format!("rav1e: {e}")))?; + self.finished = true; + } + self.drain() + } + + /// Encodes one frame if a packet is immediately available. The input is accepted even if + /// rav1e needs more frames and this returns an error; new callers should use [`Self::push`]. + pub fn encode_with_key(&mut self, frame: &Frame<'_>, force_key: bool) -> Result { + self.submit(frame, force_key)?; loop { match self.ctx.receive_packet() { Ok(packet) => { - let (data, seq) = sample_data(&packet.data)?; - if self.seq_header.is_none() { - self.seq_header = seq; - } - return Ok(Packet { data, keyframe: packet.frame_type == FrameType::KEY }); + return Ok(self.packet(packet)?.packet); } Err(rav1e::prelude::EncoderStatus::Encoded) => continue, Err(rav1e::prelude::EncoderStatus::NeedMoreData | rav1e::prelude::EncoderStatus::LimitReached) => { @@ -153,3 +203,67 @@ fn sample_data(data: &[u8]) -> Result<(Vec, Option>), Error> { } Ok((sample, sequence)) } + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn buffered_frames_are_returned_with_input_numbers_and_finish_drains() { + let cfg = EncoderConfig::new(64, 48, 24, 1); + let mut encoder = LargeEncoder::with_speed(&cfg, 10).unwrap(); + assert!(encoder.av1c().is_none()); + let y = vec![96; 64 * 48]; + let uv = vec![128; 32 * 24]; + let frame = Frame { y: &y, u: &uv, v: &uv, y_stride: 64, uv_stride: 32 }; + let mut packets = Vec::new(); + for i in 0..4 { + packets.extend(encoder.push(&frame, i == 2).unwrap()); + } + packets.extend(encoder.finish().unwrap()); + assert_eq!(packets.iter().map(|p| p.input_frame_number).collect::>(), [0, 1, 2, 3]); + assert!(packets[0].packet.keyframe); + assert!(packets[2].packet.keyframe, "requested key frame"); + assert!(encoder.av1c().is_some()); + #[cfg(feature = "av1-decode")] + { + let mut decoder = crate::av1::decode::Decoder::with_threads(1); + let mut frames = Vec::new(); + for packet in &packets { + frames.extend(decoder.decode(&packet.packet.data).unwrap()); + } + frames.extend(decoder.flush_result().unwrap()); + assert_eq!(frames.len(), 4); + assert!(frames.iter().all(|frame| (frame.width, frame.height) == (64, 48))); + } + assert!(encoder.finish().unwrap().is_empty()); + assert!(encoder.push(&frame, false).is_err()); + } + + #[test] + fn a_large_frame_can_be_flushed_even_when_the_first_push_is_buffered() { + let cfg = EncoderConfig::new(4112, 16, 30, 1); + let mut encoder = LargeEncoder::with_speed(&cfg, 10).unwrap(); + let y = vec![64; 4112 * 16]; + let uv = vec![128; 2056 * 8]; + let frame = Frame { y: &y, u: &uv, v: &uv, y_stride: 4112, uv_stride: 2056 }; + let mut packets = encoder.push(&frame, false).unwrap(); + packets.extend(encoder.finish().unwrap()); + assert_eq!(packets.len(), 1); + assert_eq!(packets[0].input_frame_number, 0); + assert!(packets[0].packet.keyframe); + assert!(!packets[0].packet.data.is_empty()); + assert!(encoder.av1c().is_some()); + } + + #[test] + fn invalid_frame_is_not_queued_and_empty_stream_finishes() { + let cfg = EncoderConfig::new(64, 48, 24, 1); + let mut encoder = LargeEncoder::with_speed(&cfg, 10).unwrap(); + let short = [0; 1]; + let frame = Frame { y: &short, u: &short, v: &short, y_stride: 64, uv_stride: 32 }; + assert!(encoder.push(&frame, false).is_err()); + assert!(encoder.finish().unwrap().is_empty()); + assert!(encoder.av1c().is_none()); + } +} diff --git a/crates/video/src/av1/encode/mod.rs b/crates/video/src/av1/encode/mod.rs index 3a954cef2..d6632a94d 100644 --- a/crates/video/src/av1/encode/mod.rs +++ b/crates/video/src/av1/encode/mod.rs @@ -23,7 +23,7 @@ mod writer; #[cfg(all(feature = "av1-large-encode", not(target_arch = "wasm32")))] mod large; #[cfg(all(feature = "av1-large-encode", not(target_arch = "wasm32")))] -pub use large::LargeEncoder; +pub use large::{BufferedPacket, LargeEncoder}; use bitw::obu; use craft_media::bitstream::BitWriter;