Skip to main content

threers_codec/hevc/
transparent.rs

1//! Transparent HEVC: a 2-layer access unit (color base + `AUX_ALPHA` layer),
2//! muxed into an Apple-compatible `.mov`/`.mp4` that QuickTime/Safari play.
3//!
4//! Both layers are coded with the working `I_PCM` path: the base is 4:2:0 color,
5//! the alpha layer is 4:2:0 with the opacity in luma and constant (128) chroma —
6//! exactly how Apple's `hevcWithAlpha` carries alpha (see [`super::alpha`]). The
7//! [`alpha_channel_info`](super::alpha::alpha_channel_info_sei) SEI in the `hvcC`
8//! tells the decoder to interpret layer 1's luma as alpha (0 transparent, 255
9//! opaque), and the `almo` box marks the track as transparent.
10//!
11//! The multi-layer `VPS` (with `vps_extension`) is taken verbatim from Apple's
12//! reference ([`APPLE_VPS_NAL_64X64`]). It works at **any** resolution: because
13//! each layer's SPS is self-contained (`MultiLayerExtSpsFlag = 0`), the decoder
14//! ignores the VPS `rep_format`, so the same VPS drives 64×64, 128×96, 1080p,
15//! etc. Verified by decoding with AVFoundation (QuickTime/Safari's engine): the
16//! alpha channel round-trips losslessly at multiple sizes.
17
18use crate::hevc::encoder::{pad_plane, Yuv420Frame};
19use crate::hevc::hvcc::{build_hvcc, HvccArray, HvccProfile};
20use crate::hevc::nal::{nal_unit, NalUnitType};
21use crate::hevc::params::{write_pps_ids, write_sps_id, HevcConfig, CTB_SIZE};
22use crate::hevc::slice::{slice_segment_rbsp_pps, PaddedYuv};
23use crate::hevc::{alpha_channel_info_sei, AlphaChannelInfo};
24use crate::mp4::{mux_hevc, Mp4Params};
25
26/// Apple's reference alpha-multilayer `VPS` NAL (2-byte header + EBSP), captured
27/// verbatim from an `AVVideoCodecType.hevcWithAlpha` file. Declares 2 layers with
28/// layer 1 = `AUX_ALPHA`.
29///
30/// Despite the `_64X64` name (the resolution of the source file), this VPS is
31/// resolution-independent for decoding: the `rep_format` it carries is ignored
32/// because both layers use self-contained SPSs, so it drives every size.
33pub const APPLE_VPS_NAL_64X64: [u8; 41] = [
34    0x40, 0x01, 0x0c, 0x11, 0xff, 0xff, 0x01, 0x60, 0x00, 0x00, 0x03, 0x00, 0xb0, 0x00, 0x00, 0x03,
35    0x00, 0x00, 0x03, 0x00, 0x1e, 0x15, 0xc1, 0xbf, 0x00, 0x08, 0x00, 0x08, 0x30, 0x28, 0x53, 0x80,
36    0x50, 0x00, 0x20, 0x50, 0x0c, 0x18, 0xfc, 0x57, 0xa4,
37];
38
39/// Apple's `almo` alpha-mode box payload (4 bytes) that marks a track transparent.
40pub const ALMO_PAYLOAD: [u8; 4] = [0x00, 0x00, 0x01, 0x02];
41
42/// Level `general_level_idc` matching the reference VPS (level 1.0), kept
43/// consistent across VPS/SPS/`hvcC`.
44const LEVEL_IDC: u8 = 30;
45
46/// Encodes transparent frames and muxes them into an Apple-compatible container.
47pub struct TransparentEncoder {
48    width: u32,
49    height: u32,
50    base_cfg: HevcConfig,
51    alpha_cfg: HevcConfig,
52    hvcc: Vec<u8>,
53    samples: Vec<Vec<u8>>,
54}
55
56impl TransparentEncoder {
57    /// New encoder using the reference 64×64 multi-layer VPS.
58    pub fn new(width: u32, height: u32) -> Self {
59        Self::with_vps(width, height, &APPLE_VPS_NAL_64X64)
60    }
61
62    /// New encoder with an explicit multi-layer VPS NAL (for experimenting with
63    /// resolution generalization / a generated `vps_extension`).
64    pub fn with_vps(width: u32, height: u32, vps_nal: &[u8]) -> Self {
65        let base_cfg = HevcConfig::new(width, height).with_level(LEVEL_IDC);
66        // Alpha layer signals full range so 0..255 luma is read as opacity 1:1.
67        let alpha_cfg = HevcConfig::new(width, height)
68            .with_level(LEVEL_IDC)
69            .with_full_range(true);
70
71        // Parameter-set NALs. Base layer id 0 / sps,pps id 0; alpha layer id 1 /
72        // sps,pps id 1.
73        let sps0 = nal_unit(NalUnitType::Sps, 0, 0, &write_sps_id(&base_cfg, 0));
74        let sps1 = nal_unit(NalUnitType::Sps, 1, 0, &write_sps_id(&alpha_cfg, 1));
75        let pps0 = nal_unit(NalUnitType::Pps, 0, 0, &write_pps_ids(0, 0));
76        let pps1 = nal_unit(NalUnitType::Pps, 1, 0, &write_pps_ids(1, 1));
77        let sei = nal_unit(
78            NalUnitType::PrefixSei,
79            0,
80            0,
81            &alpha_channel_info_sei(&AlphaChannelInfo::default()),
82        );
83        let vps = vps_nal.to_vec();
84
85        let hvcc = build_hvcc(
86            &HvccProfile::main_420(LEVEL_IDC),
87            &[
88                HvccArray {
89                    nal_type: 32,
90                    complete: true,
91                    nals: &[vps],
92                },
93                HvccArray {
94                    nal_type: 33,
95                    complete: true,
96                    nals: &[sps0, sps1],
97                },
98                HvccArray {
99                    nal_type: 34,
100                    complete: true,
101                    nals: &[pps0, pps1],
102                },
103                HvccArray {
104                    nal_type: 39,
105                    complete: false,
106                    nals: &[sei],
107                },
108            ],
109        );
110
111        Self {
112            width,
113            height,
114            base_cfg,
115            alpha_cfg,
116            hvcc,
117            samples: Vec::new(),
118        }
119    }
120
121    /// Append one frame: `color` (4:2:0) plus a full-resolution `alpha` plane
122    /// (`width × height`, 0 = transparent, 255 = opaque).
123    pub fn encode_frame(&mut self, color: &Yuv420Frame, alpha: &[u8]) {
124        assert_eq!(
125            (color.width, color.height),
126            (self.width, self.height),
127            "color size"
128        );
129        assert_eq!(
130            alpha.len(),
131            (self.width * self.height) as usize,
132            "alpha size"
133        );
134
135        let base_slice =
136            self.encode_layer_slice(&self.base_cfg, &color.y, &color.u, &color.v, 0, 0);
137        // Alpha layer: opacity in luma, constant chroma.
138        let (cw, ch) = (self.width / 2, self.height / 2);
139        let chroma = vec![128u8; (cw * ch) as usize];
140        let alpha_slice = self.encode_layer_slice(&self.alpha_cfg, alpha, &chroma, &chroma, 1, 1);
141
142        // One MP4 sample = both layers' slices, 4-byte length-prefixed.
143        let mut sample = Vec::with_capacity(8 + base_slice.len() + alpha_slice.len());
144        push_len_prefixed(&mut sample, &base_slice);
145        push_len_prefixed(&mut sample, &alpha_slice);
146        self.samples.push(sample);
147    }
148
149    fn encode_layer_slice(
150        &self,
151        cfg: &HevcConfig,
152        y: &[u8],
153        u: &[u8],
154        v: &[u8],
155        layer_id: u8,
156        pps_id: u32,
157    ) -> Vec<u8> {
158        let (cw, ch) = (cfg.coded_width, cfg.coded_height);
159        let yp = pad_plane(y, self.width, self.height, cw, ch);
160        let up = pad_plane(u, self.width / 2, self.height / 2, cw / 2, ch / 2);
161        let vp = pad_plane(v, self.width / 2, self.height / 2, cw / 2, ch / 2);
162        let padded = PaddedYuv {
163            y: &yp,
164            u: &up,
165            v: &vp,
166            coded_width: cw,
167            coded_height: ch,
168        };
169        let rbsp = slice_segment_rbsp_pps(cfg, &padded, pps_id);
170        nal_unit(NalUnitType::IdrNLp, layer_id, 0, &rbsp)
171    }
172
173    /// Finish, muxing all frames into an Apple-compatible `.mov` byte stream at
174    /// `fps` frames per second.
175    pub fn finish_mov(&self, fps: u32) -> Vec<u8> {
176        debug_assert_eq!(CTB_SIZE, 16);
177        let timescale = 600u32;
178        mux_hevc(&Mp4Params {
179            width: self.width,
180            height: self.height,
181            timescale,
182            frame_duration: timescale / fps.max(1),
183            hvcc_payload: &self.hvcc,
184            almo_payload: Some(&ALMO_PAYLOAD),
185            samples: &self.samples,
186        })
187    }
188}
189
190/// Append `nal` to `out` with a 4-byte big-endian length prefix (MP4 form).
191fn push_len_prefixed(out: &mut Vec<u8>, nal: &[u8]) {
192    out.extend_from_slice(&(nal.len() as u32).to_be_bytes());
193    out.extend_from_slice(nal);
194}