Skip to main content

rff_format/
avc.rs

1//! H.264 bitstream helpers shared by demuxers (FFmpeg's `h264_mp4toannexb`
2//! bitstream filter plus a minimal SPS reader).
3//!
4//! rff's packet contract for H.264 is **Annex-B**: every NAL prefixed with a
5//! `00 00 00 01` start code and SPS/PPS repeated before each keyframe. A
6//! demuxer that reads an `avcC` record hands it out as `Stream::extradata`,
7//! as FFmpeg does, so a decoder or a muxer can be set up before the first
8//! packet; rff's own decoders take extradata only when it is Annex-B and
9//! otherwise rely on the in-band sets. Containers that store AVCC (length-prefixed
10//! NALs + an `avcC` config record) — MP4 and Matroska — use [`parse_avcc`] +
11//! [`avcc_to_annexb`] to normalise, so consumers see one format regardless of
12//! the container. [`sps_dimensions`] recovers coded width/height for containers
13//! whose headers carry none (MPEG-TS).
14
15/// Per-track H.264 config for AVCC→Annex-B conversion, parsed from an `avcC`
16/// (AVCDecoderConfigurationRecord) box.
17pub struct AvcConfig {
18    /// Bytes in each NAL length prefix (1, 2 or 4).
19    pub nal_len: usize,
20    /// The SPS + PPS NALs, already start-code prefixed, ready to prepend to
21    /// keyframe packets.
22    pub headers_annexb: Vec<u8>,
23}
24
25/// Parse an `avcC` box into the NAL length size and Annex-B SPS/PPS headers.
26pub fn parse_avcc(avcc: &[u8]) -> Option<AvcConfig> {
27    if avcc.len() < 6 {
28        return None;
29    }
30    let nal_len = (avcc[4] & 0x03) as usize + 1;
31    let mut headers = Vec::new();
32    let mut i = 5;
33    let num_sps = avcc[i] & 0x1F;
34    i += 1;
35    for _ in 0..num_sps {
36        let len = be16(avcc, i)? as usize;
37        i += 2;
38        let nal = avcc.get(i..i + len)?;
39        headers.extend_from_slice(&[0, 0, 0, 1]);
40        headers.extend_from_slice(nal);
41        i += len;
42    }
43    let num_pps = *avcc.get(i)?;
44    i += 1;
45    for _ in 0..num_pps {
46        let len = be16(avcc, i)? as usize;
47        i += 2;
48        let nal = avcc.get(i..i + len)?;
49        headers.extend_from_slice(&[0, 0, 0, 1]);
50        headers.extend_from_slice(nal);
51        i += len;
52    }
53    Some(AvcConfig {
54        nal_len,
55        headers_annexb: headers,
56    })
57}
58
59/// Convert one AVCC sample (a series of `nal_len`-byte length + NAL) to Annex-B
60/// (each NAL prefixed with a `00 00 00 01` start code), appending to `out`.
61pub fn avcc_to_annexb(sample: &[u8], nal_len: usize, out: &mut Vec<u8>) {
62    let mut i = 0;
63    while i + nal_len <= sample.len() {
64        let mut len = 0usize;
65        for _ in 0..nal_len {
66            len = (len << 8) | sample[i] as usize;
67            i += 1;
68        }
69        if i + len > sample.len() {
70            break;
71        }
72        out.extend_from_slice(&[0, 0, 0, 1]);
73        out.extend_from_slice(&sample[i..i + len]);
74        i += len;
75    }
76}
77
78/// Find the first SPS NAL (type 7) in an Annex-B stream. Returns the NAL
79/// including its header byte, without the start code.
80pub fn find_sps_annexb(data: &[u8]) -> Option<&[u8]> {
81    let mut i = 0;
82    let mut nal_start: Option<usize> = None;
83    while i + 3 <= data.len() {
84        if data[i] == 0 && data[i + 1] == 0 && data[i + 2] == 1 {
85            if let Some(s) = nal_start {
86                // End of the previous NAL (trim the 0 of a 4-byte start code).
87                let end = if i > 0 && data[i - 1] == 0 { i - 1 } else { i };
88                if data[s] & 0x1F == 7 {
89                    return Some(&data[s..end]);
90                }
91            }
92            nal_start = Some(i + 3);
93            i += 3;
94        } else {
95            i += 1;
96        }
97    }
98    let s = nal_start?;
99    (*data.get(s)? & 0x1F == 7).then(|| &data[s..])
100}
101
102/// Decode coded width/height from an SPS NAL (header byte included), applying
103/// the frame cropping rectangle. Handles High-profile chroma/bit-depth fields
104/// and scaling matrices. Returns `None` on any malformed or truncated field.
105pub fn sps_dimensions(nal: &[u8]) -> Option<(u32, u32)> {
106    if nal.first()? & 0x1F != 7 {
107        return None;
108    }
109    // RBSP: strip emulation-prevention bytes (00 00 03 → 00 00).
110    let mut rbsp = Vec::with_capacity(nal.len());
111    let mut zeros = 0u32;
112    for &b in &nal[1..] {
113        if zeros >= 2 && b == 3 {
114            zeros = 0;
115            continue;
116        }
117        zeros = if b == 0 { zeros + 1 } else { 0 };
118        rbsp.push(b);
119    }
120
121    let mut r = Bits::new(&rbsp);
122    let profile_idc = r.bits(8)?;
123    r.bits(16)?; // constraint flags + reserved + level_idc
124    r.ue()?; // seq_parameter_set_id
125
126    let mut chroma_format_idc = 1; // 4:2:0 unless the profile spells it out
127    let mut separate_colour_plane = false;
128    if matches!(
129        profile_idc,
130        100 | 110 | 122 | 244 | 44 | 83 | 86 | 118 | 128 | 138 | 139 | 134 | 135
131    ) {
132        chroma_format_idc = r.ue()?;
133        if chroma_format_idc == 3 {
134            separate_colour_plane = r.bit()? == 1;
135        }
136        r.ue()?; // bit_depth_luma_minus8
137        r.ue()?; // bit_depth_chroma_minus8
138        r.bit()?; // qpprime_y_zero_transform_bypass_flag
139        if r.bit()? == 1 {
140            // seq_scaling_matrix_present: skip each present scaling list.
141            let lists = if chroma_format_idc != 3 { 8 } else { 12 };
142            for i in 0..lists {
143                if r.bit()? == 1 {
144                    skip_scaling_list(&mut r, if i < 6 { 16 } else { 64 })?;
145                }
146            }
147        }
148    }
149
150    r.ue()?; // log2_max_frame_num_minus4
151    match r.ue()? {
152        0 => {
153            r.ue()?; // log2_max_pic_order_cnt_lsb_minus4
154        }
155        1 => {
156            r.bit()?; // delta_pic_order_always_zero_flag
157            r.se()?; // offset_for_non_ref_pic
158            r.se()?; // offset_for_top_to_bottom_field
159            let n = r.ue()?;
160            for _ in 0..n {
161                r.se()?; // offset_for_ref_frame
162            }
163        }
164        _ => {}
165    }
166    r.ue()?; // max_num_ref_frames
167    r.bit()?; // gaps_in_frame_num_value_allowed_flag
168
169    let width_mbs = r.ue()? + 1;
170    let height_map_units = r.ue()? + 1;
171    let frame_mbs_only = r.bit()?;
172    if frame_mbs_only == 0 {
173        r.bit()?; // mb_adaptive_frame_field_flag
174    }
175    r.bit()?; // direct_8x8_inference_flag
176
177    let mut width = width_mbs.checked_mul(16)?;
178    let mut height = (2 - frame_mbs_only)
179        .checked_mul(height_map_units)?
180        .checked_mul(16)?;
181    if r.bit()? == 1 {
182        // frame_cropping: units depend on the chroma sampling (Table 6-1).
183        let (left, right, top, bottom) = (r.ue()?, r.ue()?, r.ue()?, r.ue()?);
184        let chroma_array_type = if separate_colour_plane {
185            0
186        } else {
187            chroma_format_idc
188        };
189        let (sub_w, sub_h) = match chroma_array_type {
190            1 => (2, 2), // 4:2:0
191            2 => (2, 1), // 4:2:2
192            _ => (1, 1), // monochrome / 4:4:4
193        };
194        let crop_y = sub_h * (2 - frame_mbs_only);
195        width = width.checked_sub((left + right).checked_mul(sub_w)?)?;
196        height = height.checked_sub((top + bottom).checked_mul(crop_y)?)?;
197    }
198    (width > 0 && height > 0).then_some((width, height))
199}
200
201/// Split an Annex-B bitstream into NAL units (start codes removed). The
202/// mux-side inverse of [`avcc_to_annexb`], shared by every container that
203/// stores AVCC (MP4, Matroska).
204pub fn split_annexb(data: &[u8]) -> Vec<&[u8]> {
205    let mut nals = Vec::new();
206    let mut i = 0;
207    let mut nal_start: Option<usize> = None;
208    while i + 3 <= data.len() {
209        if data[i] == 0 && data[i + 1] == 0 && data[i + 2] == 1 {
210            if let Some(s) = nal_start {
211                // A leading zero before this start code belongs to a 4-byte code.
212                let end = if i > s && data[i - 1] == 0 { i - 1 } else { i };
213                if end > s {
214                    nals.push(&data[s..end]);
215                }
216            }
217            i += 3;
218            nal_start = Some(i);
219        } else {
220            i += 1;
221        }
222    }
223    if let Some(s) = nal_start {
224        if s < data.len() {
225            nals.push(&data[s..]);
226        }
227    }
228    nals
229}
230
231/// Build an AVCDecoderConfigurationRecord (the `avcC` payload, no box header)
232/// from the SPS and PPS NALs. MP4 wraps it in an `avcC` box; Matroska stores it
233/// raw as CodecPrivate.
234pub fn build_avcc_record(sps: &[u8], pps: &[u8]) -> Vec<u8> {
235    let mut b = Vec::new();
236    b.push(1); // configurationVersion
237    b.push(*sps.get(1).unwrap_or(&0x42)); // AVCProfileIndication
238    b.push(*sps.get(2).unwrap_or(&0)); // profile_compatibility
239    b.push(*sps.get(3).unwrap_or(&30)); // AVCLevelIndication
240    b.push(0xFF); // 6 bits reserved + lengthSizeMinusOne = 3 (4-byte lengths)
241    b.push(0xE1); // 3 bits reserved + numOfSPS = 1
242    b.extend_from_slice(&(sps.len() as u16).to_be_bytes());
243    b.extend_from_slice(sps);
244    b.push(1); // numOfPPS
245    b.extend_from_slice(&(pps.len() as u16).to_be_bytes());
246    b.extend_from_slice(pps);
247    b
248}
249
250/// Consume a `scaling_list()` of `size` entries (we only need the bits gone).
251fn skip_scaling_list(r: &mut Bits, size: u32) -> Option<()> {
252    let mut next = 8i32;
253    for _ in 0..size {
254        if next != 0 {
255            next = (next + r.se()? + 256) % 256;
256        }
257        if next == 0 {
258            break; // remaining entries repeat the last — no more bits follow
259        }
260    }
261    Some(())
262}
263
264/// MSB-first bit reader over an RBSP.
265struct Bits<'a> {
266    d: &'a [u8],
267    pos: usize, // in bits
268}
269
270impl<'a> Bits<'a> {
271    fn new(d: &'a [u8]) -> Bits<'a> {
272        Bits { d, pos: 0 }
273    }
274
275    fn bit(&mut self) -> Option<u32> {
276        let b = *self.d.get(self.pos / 8)?;
277        let v = (b >> (7 - self.pos % 8)) & 1;
278        self.pos += 1;
279        Some(v as u32)
280    }
281
282    fn bits(&mut self, n: u32) -> Option<u32> {
283        let mut v = 0;
284        for _ in 0..n {
285            v = (v << 1) | self.bit()?;
286        }
287        Some(v)
288    }
289
290    /// Unsigned Exp-Golomb (`ue(v)`).
291    fn ue(&mut self) -> Option<u32> {
292        let mut zeros = 0;
293        while self.bit()? == 0 {
294            zeros += 1;
295            if zeros > 31 {
296                return None;
297            }
298        }
299        Some((1u32 << zeros) - 1 + if zeros > 0 { self.bits(zeros)? } else { 0 })
300    }
301
302    /// Signed Exp-Golomb (`se(v)`).
303    fn se(&mut self) -> Option<i32> {
304        let k = self.ue()? as i64;
305        Some(if k % 2 == 1 { (k + 1) / 2 } else { -(k / 2) } as i32)
306    }
307}
308
309fn be16(d: &[u8], i: usize) -> Option<u16> {
310    Some(((*d.get(i)? as u16) << 8) | *d.get(i + 1)? as u16)
311}
312
313#[cfg(test)]
314mod tests {
315    use super::*;
316
317    #[test]
318    fn avcc_roundtrip_to_annexb() {
319        // avcC: ver 1, profile/compat/level, nal_len=4, 1 SPS (3 bytes), 1 PPS (2 bytes).
320        let avcc = [
321            1, 100, 0, 31, 0xFF, 0xE1, 0, 3, 0x67, 0xAA, 0xBB, 1, 0, 2, 0x68, 0xCC,
322        ];
323        let cfg = parse_avcc(&avcc).unwrap();
324        assert_eq!(cfg.nal_len, 4);
325        assert_eq!(
326            cfg.headers_annexb,
327            &[0, 0, 0, 1, 0x67, 0xAA, 0xBB, 0, 0, 0, 1, 0x68, 0xCC]
328        );
329
330        let sample = [0, 0, 0, 2, 0x41, 0x9A, 0, 0, 0, 1, 0x06];
331        let mut out = Vec::new();
332        avcc_to_annexb(&sample, 4, &mut out);
333        assert_eq!(out, &[0, 0, 0, 1, 0x41, 0x9A, 0, 0, 0, 1, 0x06]);
334    }
335
336    #[test]
337    fn finds_sps_between_start_codes() {
338        let data = [
339            0, 0, 0, 1, 0x09, 0xF0, 0, 0, 0, 1, 0x67, 0xAA, 0, 0, 1, 0x68,
340        ];
341        assert_eq!(find_sps_annexb(&data), Some(&[0x67u8, 0xAA][..]));
342        // SPS as the last NAL.
343        let data = [0, 0, 1, 0x67, 0xAA, 0xBB];
344        assert_eq!(find_sps_annexb(&data), Some(&[0x67u8, 0xAA, 0xBB][..]));
345        assert_eq!(find_sps_annexb(&[0, 0, 1, 0x68, 0x00]), None);
346    }
347
348    #[test]
349    fn sps_dimensions_x264_640x360() {
350        // x264 High-profile SPS for 640x360 (360 = 368 coded − 8 crop).
351        let sps = [
352            0x67, 0x64, 0x00, 0x1E, 0xAC, 0xD9, 0x40, 0xA0, 0x2F, 0xF9, 0x70, 0x11, 0x00, 0x00,
353            0x03, 0x00, 0x01, 0x00, 0x00, 0x03, 0x00, 0x30, 0x0F, 0x16, 0x2D, 0x96,
354        ];
355        assert_eq!(sps_dimensions(&sps), Some((640, 360)));
356    }
357
358    #[test]
359    fn sps_dimensions_baseline_176x144() {
360        // Baseline QCIF SPS (no cropping, no High-profile fields).
361        let sps = [
362            0x67, 0x42, 0xC0, 0x0D, 0x8C, 0x8D, 0x41, 0x62, 0x64, 0x0A, 0x60, 0x80,
363        ];
364        assert_eq!(sps_dimensions(&sps), Some((176, 144)));
365    }
366}