Merge pull request #1568 from storytold/codex/av1-buffered-output

Support buffered output from tiled AV1 encoder
This commit is contained in:
Dylan M. Taylor authored and GitHub committed 2026-11-15 07:55:24 -05:00
commit 9fda042654
3 files changed
+127 -12

No files matched your search

+4 -3
View File
@@ -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
+122 -8
View File
@@ -12,6 +12,14 @@ pub struct LargeEncoder {
width: usize,
height: usize,
seq_header: Option<Vec<u8>>,
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<Packet, Error> {
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<u8>) -> Result<BufferedPacket, Error> {
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<Vec<BufferedPacket>, 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<Vec<BufferedPacket>, 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<Vec<BufferedPacket>, 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<Packet, Error> {
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<u8>, Option<Vec<u8>>), 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::<Vec<_>>(), [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());
}
}
+1 -1
View File
@@ -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;