Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 5 additions & 1 deletion .github/workflows/h264-encoder.yml
Original file line number Diff line number Diff line change
Expand Up @@ -72,7 +72,7 @@ jobs:
components: clippy
- name: Unit tests and opt-in driver
run: |
H264_P_FIXTURE_DIR="$RUNNER_TEMP/p-forced" cargo test --locked --release -p coreav-h264-encoder --features full
H264_VUI_FIXTURE_DIR="$RUNNER_TEMP/vui" H264_P_FIXTURE_DIR="$RUNNER_TEMP/p-forced" cargo test --locked --release -p coreav-h264-encoder --features full
cargo clippy --locked -p coreav-h264-encoder --features full --all-targets -- -D warnings
cargo build --locked --release -p coreav-h264-encoder --features full --example g1
cargo build --locked --release -p coreav-h264-encoder --features full --example p
Expand Down Expand Up @@ -104,6 +104,9 @@ jobs:
run: |
export PATH="$ORACLES:$PATH"
scripts/gen-fixtures.sh "$RUNNER_TEMP/g1-existing-fixtures"
- name: Compare constant cadence and sample aspect ratio
run: |
python3 -I crates/coreav-h264-encoder/tests/vui.py --ffmpeg "$RUNNER_TEMP/g1-oracles/ffmpeg" --fixtures "$RUNNER_TEMP/vui"
- name: Compare every visible plane with all three decoders
run: |
python3 -I scripts/h264_g1_conformance.py \
Expand All @@ -125,6 +128,7 @@ jobs:
name: h264-encoder-conformance
path: |
${{ runner.temp }}/g1-conformance
${{ runner.temp }}/vui
${{ runner.temp }}/deblock-conformance
${{ runner.temp }}/g1-oracles/jm-build.txt
if-no-files-found: ignore
Expand Down
9 changes: 9 additions & 0 deletions crates/coreav-h264-encoder/VUI.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
# Constant cadence and sample aspect ratio

Implement Rec. ITU-T H.264 (08/2024), Annex E.1.1 and E.2.1, Table E-1 and Table E-6.

Add checked `FrameRate` and `SampleAspectRatio` values to public `Settings`. Reduce positive rational inputs before checking the 32-bit timing and 16-bit Extended_SAR bounds. For progressive frames, write `num_units_in_tick = den`, `time_scale = 2 * num`, and `fixed_frame_rate_flag = 1`. When the reduced denominator is even, halve both timing fields so every representable ratio fits. Check the level 5.1 macroblocks-per-second limit against the actual rational cadence.

Use Table E-1 for matching aspect ratios, otherwise Extended_SAR. Explicit square pixels use entry 1. The default aspect ratio preserves the existing absent signalling, which means unspecified in the specification; callers requiring explicit 1:1 use the checked constructor. The default timing remains 30/1, preserving existing encoded bytes.

Tests independently inspect SPS fields and decode complete pictures with the native decoder, which consumes but does not retain timing or aspect metadata. A generated-fixture test compares rate and SAR with the qualified ffprobe pair on Actions. The test prepares MP4 timestamps from each emitted SPS clock, not the expected rate: the pinned raw H.264 demuxer reports a doubled rate and a 25 fps average fallback for both native and oracle-generated streams. No CLI, container cadence, variable frame rate, or decoder API changes.
2 changes: 2 additions & 0 deletions crates/coreav-h264-encoder/examples/g1.rs
Original file line number Diff line number Diff line change
Expand Up @@ -48,6 +48,8 @@ fn run() -> Result<(), Box<dyn std::error::Error>> {
let height = height.parse::<usize>()?;
let frames = frames.parse::<u64>()?;
let settings = Settings {
frame_rate: Default::default(),
sample_aspect_ratio: Default::default(),
width,
height,
rate_mode: coreav_h264_encoder::RateMode::FixedQp(qp.parse()?),
Expand Down
2 changes: 2 additions & 0 deletions crates/coreav-h264-encoder/examples/p.rs
Original file line number Diff line number Diff line change
Expand Up @@ -36,6 +36,8 @@ fn run() -> Result<(), Box<dyn std::error::Error>> {
let height = height.parse::<usize>()?;
let frames = frames.parse::<u64>()?;
let settings = Settings {
frame_rate: Default::default(),
sample_aspect_ratio: Default::default(),
width,
height,
rate_mode: match qp.strip_prefix("crf:") {
Expand Down
95 changes: 93 additions & 2 deletions crates/coreav-h264-encoder/src/api.rs
Original file line number Diff line number Diff line change
Expand Up @@ -46,9 +46,99 @@ pub struct Colour {
pub chroma_location: u8,
}

/// Immutable sequence settings. Timing is always nominal 30/1.
/// A positive constant frame rate, reduced to fit progressive VUI timing.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct FrameRate {
pub(crate) num: u32,
pub(crate) den: u32,
}

impl FrameRate {
/// Reduce frames per second `num / den`; reject zero or 32-bit timing overflow.
pub fn new(num: u32, den: u32) -> Result<Self> {
let (num, den) = ratio(num, den)?;
if den % 2 != 0 {
num.checked_mul(2).ok_or(Error::Settings)?;
}
Ok(Self { num, den })
}

/// Reduced frames per second as (numerator, denominator).
pub fn as_ratio(self) -> (u32, u32) {
(self.num, self.den)
}

pub(crate) fn timing(self) -> (u32, u64) {
if self.den % 2 == 0 {
(self.den / 2, u64::from(self.num))
} else {
(self.den, 2 * u64::from(self.num))
}
}
}

impl Default for FrameRate {
fn default() -> Self {
Self { num: 30, den: 1 }
}
}

/// A sample width-to-height ratio with bounded H.264 VUI signalling.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct SampleAspectRatio {
pub(crate) width: u16,
pub(crate) height: u16,
pub(crate) present: bool,
}

impl SampleAspectRatio {
/// Reduce a positive ratio; reject values exceeding 16 bits after reduction.
/// Square pixels are explicitly signalled with aspect_ratio_idc 1.
pub fn new(width: u32, height: u32) -> Result<Self> {
let (width, height) = ratio(width, height)?;
Ok(Self {
width: u16::try_from(width).map_err(|_| Error::Settings)?,
height: u16::try_from(height).map_err(|_| Error::Settings)?,
present: true,
})
}

/// Reduced sample width and height, including the legacy square-pixel default.
pub fn as_ratio(self) -> (u16, u16) {
(self.width, self.height)
}
}

impl Default for SampleAspectRatio {
/// Preserve legacy bytes by omitting aspect ratio signalling (unspecified).
/// Use `new(1, 1)` when explicit square-pixel signalling is required.
fn default() -> Self {
Self {
width: 1,
height: 1,
present: false,
}
}
}

fn ratio(num: u32, den: u32) -> Result<(u32, u32)> {
if num == 0 || den == 0 {
return Err(Error::Settings);
}
let (mut a, mut b) = (num, den);
while b != 0 {
(a, b) = (b, a % b);
}
Ok((num / a, den / a))
}

/// Immutable sequence settings.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct Settings {
/// Constant progressive cadence; the default is 30/1 frames per second.
pub frame_rate: FrameRate,
/// Sample shape; the default preserves legacy absent signalling.
pub sample_aspect_ratio: SampleAspectRatio,
/// Even visible width, 16 through 1920.
pub width: usize,
/// Even visible height, 16 through 1080.
Expand Down Expand Up @@ -232,7 +322,8 @@ impl Encoder {
let mbs = coded_width * coded_height / 256;
if coded_width * coded_height > limits.coded_pixels
|| mbs > 36_864
|| mbs * 30 > 983_040
|| mbs as u64 * u64::from(settings.frame_rate.num)
> 983_040 * u64::from(settings.frame_rate.den)
|| mbs > 184_320
|| (coded_width / 16).pow(2) > 36_864 * 8
|| (coded_height / 16).pow(2) > 36_864 * 8
Expand Down
2 changes: 2 additions & 0 deletions crates/coreav-h264-encoder/src/inter.rs
Original file line number Diff line number Diff line change
Expand Up @@ -2074,6 +2074,8 @@ mod tests {

fn settings(deblocking: Deblocking) -> Settings {
Settings {
frame_rate: Default::default(),
sample_aspect_ratio: Default::default(),
width: 16,
height: 16,
rate_mode: crate::RateMode::FixedQp(28),
Expand Down
2 changes: 2 additions & 0 deletions crates/coreav-h264-encoder/src/rows.rs
Original file line number Diff line number Diff line change
Expand Up @@ -191,6 +191,8 @@ mod tests {
#[allow(clippy::unwrap_used, clippy::indexing_slicing)]
fn unavailable_wavefront_neighbours_are_refused_before_border_reads() {
let settings = crate::Settings {
frame_rate: Default::default(),
sample_aspect_ratio: Default::default(),
width: 64,
height: 48,
rate_mode: crate::RateMode::FixedQp(28),
Expand Down
34 changes: 31 additions & 3 deletions crates/coreav-h264-encoder/src/syntax.rs
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,34 @@ pub(crate) fn sps(w: &mut Bits, e: &Encoder) -> Result<()> {
w.ue(((e.coded_height - e.settings.height) / 2) as u32)?;
}
w.flag(true)?;
w.flag(false)?;
let sar = e.settings.sample_aspect_ratio;
w.flag(sar.present)?;
if sar.present {
let idc = match sar.as_ratio() {
(1, 1) => 1,
(12, 11) => 2,
(10, 11) => 3,
(16, 11) => 4,
(40, 33) => 5,
(24, 11) => 6,
(20, 11) => 7,
(32, 11) => 8,
(80, 33) => 9,
(18, 11) => 10,
(15, 11) => 11,
(64, 33) => 12,
(160, 99) => 13,
(4, 3) => 14,
(3, 2) => 15,
(2, 1) => 16,
_ => 255,
};
w.u(8, idc)?;
if idc == 255 {
w.u(16, u64::from(sar.width))?;
w.u(16, u64::from(sar.height))?;
}
}
w.flag(false)?;
w.flag(true)?;
w.u(3, 5)?;
Expand All @@ -37,8 +64,9 @@ pub(crate) fn sps(w: &mut Bits, e: &Encoder) -> Result<()> {
w.ue(u32::from(e.settings.colour.chroma_location))?;
w.ue(u32::from(e.settings.colour.chroma_location))?;
w.flag(true)?;
w.u(32, 1)?;
w.u(32, 60)?;
let (tick, scale) = e.settings.frame_rate.timing();
w.u(32, u64::from(tick))?;
w.u(32, scale)?;
w.flag(true)?;
w.flag(false)?;
w.flag(false)?;
Expand Down
Loading
Loading