Skip to main content

alpha2_media/
io.rs

1//! Platform-neutral media I/O contracts.
2//!
3//! Adapters translate `FFmpeg`, `WebCodecs`, or other host objects at this boundary;
4//! none of those platform types are part of these contracts.
5
6use std::sync::Arc;
7use std::sync::atomic::{AtomicBool, Ordering};
8use std::{error::Error, fmt};
9
10use alpha2_time::{FrameRate, MediaTime};
11
12use crate::{ColorMetadata, SourceId};
13
14/// Rectangle inside a coded video frame.
15#[derive(Copy, Clone, Debug, Eq, PartialEq)]
16pub struct Rect {
17    /// Horizontal origin in coded pixels.
18    pub x: u32,
19    /// Vertical origin in coded pixels.
20    pub y: u32,
21    /// Visible width.
22    pub width: u32,
23    /// Visible height.
24    pub height: u32,
25}
26
27/// Clockwise rotation to apply when displaying a frame.
28///
29/// Matches `WebCodecs` `VideoFrame.rotation`. `FFmpeg`'s display matrix angle is
30/// counter-clockwise, so bindings report `(-angle) mod 360`.
31#[derive(Copy, Clone, Debug, Default, Eq, Hash, PartialEq)]
32pub enum Rotation {
33    /// No rotation.
34    #[default]
35    Deg0,
36    /// Clockwise quarter turn.
37    Deg90,
38    /// Half turn.
39    Deg180,
40    /// Clockwise three-quarter turn, i.e. a counter-clockwise quarter turn.
41    Deg270,
42}
43
44impl Rotation {
45    /// Clockwise quarter turns, `0..4`.
46    #[must_use]
47    pub const fn quarter_turns(self) -> u32 {
48        match self {
49            Self::Deg0 => 0,
50            Self::Deg90 => 1,
51            Self::Deg180 => 2,
52            Self::Deg270 => 3,
53        }
54    }
55
56    /// The rotation of `quarter_turns` clockwise quarter turns, of any sign.
57    #[must_use]
58    pub const fn from_quarter_turns(quarter_turns: i32) -> Self {
59        match quarter_turns.rem_euclid(4) {
60            0 => Self::Deg0,
61            1 => Self::Deg90,
62            2 => Self::Deg180,
63            _ => Self::Deg270,
64        }
65    }
66
67    /// Whether the rotation exchanges width and height.
68    #[must_use]
69    pub const fn swaps_axes(self) -> bool {
70        matches!(self, Self::Deg90 | Self::Deg270)
71    }
72}
73
74/// How to show a decoded picture upright: mirror left to right when `mirror` is set, then
75/// rotate clockwise by `rotation`.
76///
77/// This covers all eight Exif orientations, display matrices at multiples of 90 degrees, and
78/// Matroska projection poses. `FFmpeg`'s display matrix mirrors after rotating, counter-clockwise,
79/// so bindings must convert it.
80#[derive(Copy, Clone, Debug, Default, Eq, Hash, PartialEq)]
81pub struct Orientation {
82    /// Clockwise rotation, applied after the mirror.
83    pub rotation: Rotation,
84    /// Whether the stored picture is mirrored left to right before it turns.
85    pub mirror: bool,
86}
87
88impl Orientation {
89    /// Shown as stored.
90    pub const UPRIGHT: Self = Self {
91        rotation: Rotation::Deg0,
92        mirror: false,
93    };
94
95    /// A rotation without a mirror.
96    #[must_use]
97    pub const fn rotated(rotation: Rotation) -> Self {
98        Self {
99            rotation,
100            mirror: false,
101        }
102    }
103
104    /// The orientation of an Exif `Orientation` value (1 to 8). 2, 4, 5 and 7 mirror.
105    #[must_use]
106    pub const fn from_exif(value: u16) -> Option<Self> {
107        let (rotation, mirror) = match value {
108            1 => (Rotation::Deg0, false),
109            2 => (Rotation::Deg0, true),
110            3 => (Rotation::Deg180, false),
111            4 => (Rotation::Deg180, true),
112            5 => (Rotation::Deg270, true),
113            6 => (Rotation::Deg90, false),
114            7 => (Rotation::Deg90, true),
115            8 => (Rotation::Deg270, false),
116            _ => return None,
117        };
118        Some(Self { rotation, mirror })
119    }
120
121    /// Whether the picture is shown as stored.
122    #[must_use]
123    pub const fn is_upright(self) -> bool {
124        matches!(self.rotation, Rotation::Deg0) && !self.mirror
125    }
126
127    /// The displayed size of a stored `width` x `height` picture.
128    #[must_use]
129    pub const fn displayed_size(self, width: u32, height: u32) -> (u32, u32) {
130        if self.rotation.swaps_axes() {
131            (height, width)
132        } else {
133            (width, height)
134        }
135    }
136}
137
138/// Reduced pixel-width to pixel-height ratio.
139#[derive(Copy, Clone, Debug, Eq, PartialEq)]
140pub struct SampleAspectRatio {
141    /// Ratio numerator.
142    pub num: u32,
143    /// Ratio denominator, never zero.
144    pub den: u32,
145}
146
147impl Default for SampleAspectRatio {
148    fn default() -> Self {
149        Self { num: 1, den: 1 }
150    }
151}
152
153impl SampleAspectRatio {
154    /// The ratio `num`:`den` in lowest terms, or `None` when either term is zero (`FFmpeg`
155    /// writes an unknown ratio as 0/1).
156    #[must_use]
157    pub fn new(num: u64, den: u64) -> Option<Self> {
158        if num == 0 || den == 0 {
159            return None;
160        }
161        let divisor = greatest_common_divisor(num, den);
162        Some(Self {
163            num: u32::try_from(num / divisor).ok()?,
164            den: u32::try_from(den / divisor).ok()?,
165        })
166    }
167
168    /// The pixel aspect ratio of a `visible` picture shown at `displayed` size, as a `WebCodecs`
169    /// display size gives it.
170    ///
171    /// Display sizes are rounded to whole pixels (128x96 at 4:3 shows 171x96, not 170 2/3), so
172    /// this returns the simplest fraction that rounds to that size. That recovers small declared
173    /// ratios such as 4:3, 64:45 and 10:11 exactly.
174    #[must_use]
175    pub fn of_display(visible: (u32, u32), displayed: (u32, u32)) -> Option<Self> {
176        let [
177            visible_width,
178            visible_height,
179            displayed_width,
180            displayed_height,
181        ] = [visible.0, visible.1, displayed.0, displayed.1].map(u128::from);
182        if visible_width == 0
183            || visible_height == 0
184            || displayed_width == 0
185            || displayed_height == 0
186        {
187            return None;
188        }
189        // A side the display stretched is known to half a pixel; one it kept is exact.
190        let slack = |shown: u128, stored: u128| u128::from(shown != stored);
191        let width_slack = slack(displayed_width, visible_width);
192        let height_slack = slack(displayed_height, visible_height);
193        // ratio = (displayed_width / visible_width) / (displayed_height / visible_height), in
194        // half pixels.
195        let low = (
196            (2 * displayed_width - width_slack) * visible_height,
197            (2 * displayed_height + height_slack) * visible_width,
198        );
199        let high = (
200            (2 * displayed_width + width_slack) * visible_height,
201            (2 * displayed_height - height_slack) * visible_width,
202        );
203        let (num, den) = simplest_fraction_between(low, high)?;
204        Self::new(u64::try_from(num).ok()?, u64::try_from(den).ok()?)
205    }
206
207    /// The square-pixel display size of a stored `width` x `height` picture: the longer pixel
208    /// side stretched, rounded half up, as browser demuxers report it.
209    #[must_use]
210    pub fn square_pixel_size(self, width: u32, height: u32) -> (u32, u32) {
211        let stretch = |side: u32, by: u32, of: u32| {
212            let scaled =
213                (u64::from(side) * u64::from(by) * 2 + u64::from(of)) / (2 * u64::from(of));
214            u32::try_from(scaled).unwrap_or(u32::MAX)
215        };
216        if self.num == 0 || self.den == 0 {
217            return (width, height);
218        }
219        match self.num.cmp(&self.den) {
220            std::cmp::Ordering::Greater => (stretch(width, self.num, self.den), height),
221            std::cmp::Ordering::Less => (width, stretch(height, self.den, self.num)),
222            std::cmp::Ordering::Equal => (width, height),
223        }
224    }
225}
226
227/// The fraction with the smallest denominator in `low..=high`, by continued fractions.
228fn simplest_fraction_between(low: (u128, u128), high: (u128, u128)) -> Option<(u128, u128)> {
229    let ((low_num, low_den), (high_num, high_den)) = (low, high);
230    if low_den == 0 || high_den == 0 || low_num * high_den > high_num * low_den {
231        return None;
232    }
233    let whole = low_num / low_den;
234    if whole * low_den == low_num {
235        return Some((whole, 1));
236    }
237    if (whole + 1) * high_den <= high_num {
238        return Some((whole + 1, 1));
239    }
240    // Both ends lie strictly between `whole` and `whole + 1`: x = whole + 1/y, with y between the
241    // reciprocals of the fractional parts.
242    let (num, den) = simplest_fraction_between(
243        (high_den, high_num - whole * high_den),
244        (low_den, low_num - whole * low_den),
245    )?;
246    Some((whole * num + den, num))
247}
248
249fn greatest_common_divisor(mut a: u64, mut b: u64) -> u64 {
250    while b != 0 {
251        (a, b) = (b, a % b);
252    }
253    a
254}
255
256/// Plane organization delivered by a decoder.
257///
258/// A [`Decoder`] delivers only layouts the renderer consumes directly: [`YuvFormat`] YCbCr,
259/// 8-bit RGBA, and linear half-float RGBA for high-range sources. Decoders must convert any
260/// other layout (packed RGB, palettes and so on) and report it as [`PixelFormat::Rgba8`].
261#[derive(Copy, Clone, Debug, Eq, PartialEq)]
262#[non_exhaustive]
263pub enum PixelFormat {
264    /// Planar or semi-planar YCbCr, one [`Plane`] per stored plane.
265    Yuv(YuvFormat),
266    /// Straight-alpha 8-bit red, green, blue, alpha in one plane.
267    Rgba8,
268    /// Premultiplied linear RGBA in one plane of little-endian half floats, BT.709 primaries,
269    /// `1.0` at SDR white. Values outside `0..=1` are allowed, and the frame's color metadata
270    /// does not apply.
271    LinearRgbaF16,
272}
273
274/// How a planar or semi-planar YCbCr frame stores its samples.
275///
276/// Luma comes first, then separate U and V planes or one interleaved UV plane, each
277/// `ceil(width / 2^chroma_shift_x)` by `ceil(height / 2^chroma_shift_y)`. Samples over eight
278/// bits are little-endian `u16`. With [`alpha`](Self::alpha), a straight full-range alpha plane
279/// at luma size and depth follows.
280#[derive(Copy, Clone, Debug, Eq, Hash, PartialEq)]
281pub struct YuvFormat {
282    /// Log2 of the horizontal chroma subsampling: 0 for 4:4:4, 1 for 4:2:x.
283    pub chroma_shift_x: u8,
284    /// Log2 of the vertical chroma subsampling: 1 for 4:2:0, 0 otherwise.
285    pub chroma_shift_y: u8,
286    /// Significant bits per sample, 8 through 16.
287    pub bit_depth: u8,
288    /// Whether U and V interleave in one plane, as NV12 and P010 do.
289    pub interleaved_chroma: bool,
290    /// Whether samples sit in the high bits of their `u16` (P010) rather than the low bits
291    /// (`yuv420p10le`).
292    pub msb_aligned: bool,
293    /// Whether an alpha plane follows the chroma, as `yuva444p16le`'s does.
294    pub alpha: bool,
295}
296
297impl YuvFormat {
298    /// 8-bit planar 4:2:0 (`yuv420p`).
299    pub const I420: Self = Self::planar(1, 1, 8);
300    /// 8-bit 4:2:0 with interleaved chroma (`nv12`).
301    pub const NV12: Self = Self {
302        interleaved_chroma: true,
303        ..Self::I420
304    };
305    /// 10-bit 4:2:0 with interleaved, high-aligned chroma (`p010le`).
306    pub const P010: Self = Self {
307        bit_depth: 10,
308        msb_aligned: true,
309        ..Self::NV12
310    };
311
312    /// Planar YCbCr with low-aligned samples.
313    #[must_use]
314    pub const fn planar(chroma_shift_x: u8, chroma_shift_y: u8, bit_depth: u8) -> Self {
315        Self {
316            chroma_shift_x,
317            chroma_shift_y,
318            bit_depth,
319            interleaved_chroma: false,
320            msb_aligned: false,
321            alpha: false,
322        }
323    }
324
325    /// The same format with an alpha plane after the chroma.
326    #[must_use]
327    pub const fn with_alpha(self) -> Self {
328        Self {
329            alpha: true,
330            ..self
331        }
332    }
333
334    /// Whether the renderer can sample this format: 8 to 16 bits, chroma subsampling of at most
335    /// four per axis, and high alignment only below 16 bits.
336    #[must_use]
337    pub const fn is_supported(self) -> bool {
338        self.bit_depth >= 8
339            && self.bit_depth <= 16
340            && self.chroma_shift_x <= 2
341            && self.chroma_shift_y <= 2
342            && (!self.msb_aligned || self.bit_depth > 8)
343    }
344
345    /// Bytes each stored sample takes: one up to 8 bits, two above.
346    #[must_use]
347    pub const fn bytes_per_sample(self) -> u32 {
348        if self.bit_depth > 8 { 2 } else { 1 }
349    }
350
351    /// Number of stored planes, alpha included.
352    #[must_use]
353    pub const fn plane_count(self) -> usize {
354        self.color_plane_count() + if self.alpha { 1 } else { 0 }
355    }
356
357    /// Number of luma and chroma planes; the alpha plane, if any, follows them.
358    #[must_use]
359    pub const fn color_plane_count(self) -> usize {
360        if self.interleaved_chroma { 2 } else { 3 }
361    }
362
363    /// Chroma plane dimensions, in sample positions, for a coded frame size.
364    #[must_use]
365    pub const fn chroma_size(self, width: u32, height: u32) -> (u32, u32) {
366        (
367            width.div_ceil(1 << self.chroma_shift_x),
368            height.div_ceil(1 << self.chroma_shift_y),
369        )
370    }
371}
372
373/// Chroma sample location for subsampled YUV.
374#[derive(Copy, Clone, Debug, Default, Eq, PartialEq)]
375pub enum ChromaLocation {
376    /// Adapter could not determine a location.
377    #[default]
378    Unspecified,
379    /// MPEG-2/most video: horizontally left, vertically centered.
380    Left,
381    /// JPEG-style centered chroma.
382    Center,
383    /// Top-left co-sited chroma.
384    TopLeft,
385}
386
387impl ChromaLocation {
388    /// The siting chroma of `format` is read at. An unspecified siting of chroma subsampled
389    /// horizontally only (4:2:2, 4:1:1) is [`Self::Left`], co-sited with even luma columns as
390    /// BT.601 and BT.709 site it; otherwise it is kept (unspecified 4:2:0 reads as centred).
391    #[must_use]
392    pub const fn resolved_for(self, format: YuvFormat) -> Self {
393        match self {
394            Self::Unspecified if format.chroma_shift_x > 0 && format.chroma_shift_y == 0 => {
395                Self::Left
396            }
397            other => other,
398        }
399    }
400}
401
402/// One decoded image plane.
403///
404/// Bytes are shared so decoders can hand over reference-counted memory without copying.
405#[derive(Clone, Debug, Eq, PartialEq)]
406pub struct Plane {
407    /// Plane bytes, including row padding: `stride * height` of them.
408    pub bytes: bytes::Bytes,
409    /// Bytes between adjacent rows.
410    pub stride: u32,
411    /// Plane width in sample positions (a UV pair each for interleaved chroma).
412    pub width: u32,
413    /// Plane height in samples.
414    pub height: u32,
415}
416
417/// Largest frame edge, in pixels, that alpha2 decodes, renders or composes.
418pub const MAX_FRAME_DIMENSION: u32 = 16_384;
419/// Largest frame area, in pixels. Decoders refuse larger frames before allocating.
420pub const MAX_FRAME_PIXELS: u64 = 67_108_864;
421
422/// Whether a `width` x `height` frame is within [`MAX_FRAME_DIMENSION`] and
423/// [`MAX_FRAME_PIXELS`].
424#[must_use]
425pub const fn frame_size_supported(width: u32, height: u32) -> bool {
426    width <= MAX_FRAME_DIMENSION
427        && height <= MAX_FRAME_DIMENSION
428        && (width as u64) * (height as u64) <= MAX_FRAME_PIXELS
429}
430
431/// Host-independent decoded video frame.
432#[derive(Clone, Debug, PartialEq)]
433pub struct DecodedVideoFrame {
434    /// Presentation timestamp.
435    pub pts: MediaTime,
436    /// Optional decode timestamp.
437    pub dts: Option<MediaTime>,
438    /// Nominal frame duration when known.
439    pub duration: Option<MediaTime>,
440    /// The visible crop within the coded picture, in coded pixels.
441    pub visible_rect: Rect,
442    /// Pixel aspect ratio.
443    pub sample_aspect_ratio: SampleAspectRatio,
444    /// How the picture is shown upright.
445    pub orientation: Orientation,
446    /// Plane layout.
447    pub pixel_format: PixelFormat,
448    /// Chroma siting.
449    pub chroma_location: ChromaLocation,
450    /// Declared color: the project's declaration, else the frame or stream tags. When `None`,
451    /// the renderer applies [`crate::ColorMetadata::UNDECLARED`] and reports it.
452    pub color: Option<ColorMetadata>,
453    /// Image planes in the order [`Self::pixel_format`] stores them.
454    pub planes: Vec<Plane>,
455}
456
457/// Most planes an [`AudioBlock`] carries: 24, for 22.2, the largest `FFmpeg` layout. Sources
458/// with more are refused rather than downmixed.
459pub const MAX_AUDIO_CHANNELS: usize = 24;
460
461/// The loudspeaker one plane of an [`AudioBlock`] feeds.
462///
463/// Positions are `FFmpeg`'s named channels (`AVChannel`), a superset of the WAVE mask, Apple
464/// channel labels and ISO/IEC 23001-8. [`Speaker::name`] is `FFmpeg`'s abbreviation.
465#[derive(Copy, Clone, Debug, Eq, Hash, PartialEq)]
466pub enum Speaker {
467    /// Front left (`FL`).
468    FrontLeft,
469    /// Front right (`FR`).
470    FrontRight,
471    /// Front center (`FC`), also a mono source's channel.
472    FrontCenter,
473    /// Low-frequency effects (`LFE`).
474    LowFrequency,
475    /// Back left (`BL`).
476    BackLeft,
477    /// Back right (`BR`).
478    BackRight,
479    /// Front left of center (`FLC`).
480    FrontLeftOfCenter,
481    /// Front right of center (`FRC`).
482    FrontRightOfCenter,
483    /// Back center (`BC`).
484    BackCenter,
485    /// Side left (`SL`).
486    SideLeft,
487    /// Side right (`SR`).
488    SideRight,
489    /// Top center (`TC`).
490    TopCenter,
491    /// Top front left (`TFL`).
492    TopFrontLeft,
493    /// Top front center (`TFC`).
494    TopFrontCenter,
495    /// Top front right (`TFR`).
496    TopFrontRight,
497    /// Top back left (`TBL`).
498    TopBackLeft,
499    /// Top back center (`TBC`).
500    TopBackCenter,
501    /// Top back right (`TBR`).
502    TopBackRight,
503    /// Left of a matrix-encoded stereo downmix (`DL`, Lt).
504    DownmixLeft,
505    /// Right of a matrix-encoded stereo downmix (`DR`, Rt).
506    DownmixRight,
507    /// Wide left (`WL`).
508    WideLeft,
509    /// Wide right (`WR`).
510    WideRight,
511    /// Surround direct left (`SDL`).
512    SurroundDirectLeft,
513    /// Surround direct right (`SDR`).
514    SurroundDirectRight,
515    /// Second low-frequency effects (`LFE2`).
516    LowFrequency2,
517    /// Top side left (`TSL`).
518    TopSideLeft,
519    /// Top side right (`TSR`).
520    TopSideRight,
521    /// Bottom front center (`BFC`).
522    BottomFrontCenter,
523    /// Bottom front left (`BFL`).
524    BottomFrontLeft,
525    /// Bottom front right (`BFR`).
526    BottomFrontRight,
527    /// Side surround left (`SSL`).
528    SideSurroundLeft,
529    /// Side surround right (`SSR`).
530    SideSurroundRight,
531    /// Top surround left (`TTL`).
532    TopSurroundLeft,
533    /// Top surround right (`TTR`).
534    TopSurroundRight,
535    /// Binaural left (`BIL`).
536    BinauralLeft,
537    /// Binaural right (`BIR`).
538    BinauralRight,
539    /// A channel without a loudspeaker position (`UNK`), such as an ambisonic component. The
540    /// fold leaves it out.
541    Unnamed,
542}
543
544impl Speaker {
545    /// Every speaker with its `FFmpeg` name and channel number (`AVChannel`);
546    /// [`Speaker::Unnamed`] is `FFmpeg`'s `AV_CHAN_UNKNOWN`.
547    const TABLE: [(Self, &'static str, u32); 37] = [
548        (Self::FrontLeft, "FL", 0),
549        (Self::FrontRight, "FR", 1),
550        (Self::FrontCenter, "FC", 2),
551        (Self::LowFrequency, "LFE", 3),
552        (Self::BackLeft, "BL", 4),
553        (Self::BackRight, "BR", 5),
554        (Self::FrontLeftOfCenter, "FLC", 6),
555        (Self::FrontRightOfCenter, "FRC", 7),
556        (Self::BackCenter, "BC", 8),
557        (Self::SideLeft, "SL", 9),
558        (Self::SideRight, "SR", 10),
559        (Self::TopCenter, "TC", 11),
560        (Self::TopFrontLeft, "TFL", 12),
561        (Self::TopFrontCenter, "TFC", 13),
562        (Self::TopFrontRight, "TFR", 14),
563        (Self::TopBackLeft, "TBL", 15),
564        (Self::TopBackCenter, "TBC", 16),
565        (Self::TopBackRight, "TBR", 17),
566        (Self::DownmixLeft, "DL", 29),
567        (Self::DownmixRight, "DR", 30),
568        (Self::WideLeft, "WL", 31),
569        (Self::WideRight, "WR", 32),
570        (Self::SurroundDirectLeft, "SDL", 33),
571        (Self::SurroundDirectRight, "SDR", 34),
572        (Self::LowFrequency2, "LFE2", 35),
573        (Self::TopSideLeft, "TSL", 36),
574        (Self::TopSideRight, "TSR", 37),
575        (Self::BottomFrontCenter, "BFC", 38),
576        (Self::BottomFrontLeft, "BFL", 39),
577        (Self::BottomFrontRight, "BFR", 40),
578        (Self::SideSurroundLeft, "SSL", 41),
579        (Self::SideSurroundRight, "SSR", 42),
580        (Self::TopSurroundLeft, "TTL", 43),
581        (Self::TopSurroundRight, "TTR", 44),
582        (Self::BinauralLeft, "BIL", 61),
583        (Self::BinauralRight, "BIR", 62),
584        (Self::Unnamed, "UNK", 0x300),
585    ];
586
587    /// `FFmpeg`'s abbreviation (`FL`, `FR`, `LFE`, ...), `UNK` for [`Speaker::Unnamed`].
588    #[must_use]
589    pub fn name(self) -> &'static str {
590        Self::TABLE
591            .iter()
592            .find(|(speaker, _, _)| *speaker == self)
593            .map_or("UNK", |(_, name, _)| name)
594    }
595
596    /// The speaker `FFmpeg` names `name` (`UNK` is [`Speaker::Unnamed`]).
597    #[must_use]
598    pub fn from_name(name: &str) -> Option<Self> {
599        Self::TABLE
600            .iter()
601            .find(|(_, known, _)| *known == name)
602            .map(|(speaker, _, _)| *speaker)
603    }
604
605    /// `FFmpeg`'s channel number (`enum AVChannel`) for this speaker.
606    #[must_use]
607    pub fn ffmpeg_channel(self) -> u32 {
608        Self::TABLE
609            .iter()
610            .find(|(speaker, _, _)| *speaker == self)
611            .map_or(0x300, |(_, _, channel)| *channel)
612    }
613
614    /// The speaker of `FFmpeg` channel number `channel`, or [`Speaker::Unnamed`] for channels
615    /// without a loudspeaker position.
616    #[must_use]
617    pub fn from_ffmpeg_channel(channel: i64) -> Self {
618        Self::TABLE
619            .iter()
620            .find(|(_, _, number)| i64::from(*number) == channel)
621            .map_or(Self::Unnamed, |(speaker, _, _)| *speaker)
622    }
623}
624
625/// The speakers an [`AudioBlock`]'s planes feed, in plane order (1 to [`MAX_AUDIO_CHANNELS`]).
626///
627/// Providers report the layout their source declares, in plane order, without rematrixing.
628/// Sources that declare none get [`SpeakerLayout::default_for`] their channel count.
629#[derive(Copy, Clone, Eq, Hash, PartialEq)]
630pub struct SpeakerLayout {
631    speakers: [Speaker; MAX_AUDIO_CHANNELS],
632    count: u8,
633}
634
635impl std::fmt::Debug for SpeakerLayout {
636    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
637        formatter
638            .debug_list()
639            .entries(self.speakers().iter().map(|speaker| speaker.name()))
640            .finish()
641    }
642}
643
644impl SpeakerLayout {
645    /// One front-center plane.
646    pub const MONO: Self = Self::fixed(&[Speaker::FrontCenter]);
647    /// Front left and right.
648    pub const STEREO: Self = Self::fixed(&[Speaker::FrontLeft, Speaker::FrontRight]);
649
650    const fn fixed(speakers: &[Speaker]) -> Self {
651        let mut layout = [Speaker::Unnamed; MAX_AUDIO_CHANNELS];
652        let mut index = 0;
653        while index < speakers.len() {
654            layout[index] = speakers[index];
655            index += 1;
656        }
657        #[allow(clippy::cast_possible_truncation)]
658        Self {
659            speakers: layout,
660            count: speakers.len() as u8,
661        }
662    }
663
664    /// The layout of these speakers in plane order, or `None` for zero or more than
665    /// [`MAX_AUDIO_CHANNELS`].
666    #[must_use]
667    pub fn new(speakers: &[Speaker]) -> Option<Self> {
668        if speakers.is_empty() || speakers.len() > MAX_AUDIO_CHANNELS {
669            return None;
670        }
671        let mut layout = Self {
672            speakers: [Speaker::Unnamed; MAX_AUDIO_CHANNELS],
673            count: u8::try_from(speakers.len()).ok()?,
674        };
675        layout.speakers[..speakers.len()].copy_from_slice(speakers);
676        Some(layout)
677    }
678
679    /// `FFmpeg`'s default layout for `channels` (`av_channel_layout_default`), in WAVE order:
680    /// mono through 7.1 up to 8, and 5.1.4, 7.1.4, 9.1.4, 9.1.6 and 22.2 for 10, 12, 14, 16 and
681    /// 24. Other counts are 7.1 plus unnamed channels. `None` for zero or more than
682    /// [`MAX_AUDIO_CHANNELS`].
683    #[must_use]
684    pub fn default_for(channels: usize) -> Option<Self> {
685        /// `FFmpeg`'s native-order channel masks (`AV_CH_LAYOUT_*`).
686        const SEVEN_ONE: u64 = 0x63f;
687        let mask: u64 = match channels {
688            1 => 0x4,
689            2 => 0x3,
690            3 => 0xb,
691            4 => 0x107,
692            5 => 0x37,
693            6 => 0x3f,
694            7 => 0x70f,
695            10 => 0x2_d60f,
696            12 => 0x2_d63f,
697            14 => 0x2_d6ff,
698            16 => 0x30_0002_d6ff,
699            24 => 0x1f8_0003_ffff,
700            8..=MAX_AUDIO_CHANNELS => SEVEN_ONE,
701            _ => return None,
702        };
703        let mut layout = Self::of_mask(mask)?;
704        // No layout for this count: 7.1 plus unnamed channels.
705        layout.count = u8::try_from(channels).ok()?;
706        Some(layout)
707    }
708
709    /// The speakers of a native-order channel mask, in bit order.
710    fn of_mask(mask: u64) -> Option<Self> {
711        let speakers = (0..64_i64)
712            .filter(|bit| mask & (1 << bit) != 0)
713            .map(Speaker::from_ffmpeg_channel)
714            .collect::<Vec<_>>();
715        Self::new(&speakers)
716    }
717
718    /// The declared layout, or [`SpeakerLayout::default_for`] the channel count when it names no
719    /// speaker. The flag reports whether the default was assumed.
720    #[must_use]
721    pub fn declared_or_default(speakers: &[Speaker]) -> Option<(Self, bool)> {
722        if speakers.iter().all(|speaker| *speaker == Speaker::Unnamed) {
723            return Self::default_for(speakers.len()).map(|layout| (layout, true));
724        }
725        Self::new(speakers).map(|layout| (layout, false))
726    }
727
728    /// The speakers, in plane order.
729    #[must_use]
730    pub fn speakers(&self) -> &[Speaker] {
731        &self.speakers[..usize::from(self.count)]
732    }
733
734    /// How many planes the layout has.
735    #[must_use]
736    pub fn channels(&self) -> usize {
737        usize::from(self.count)
738    }
739
740    /// The speakers' `FFmpeg` names joined by `+` (`FL+FR+FC`), as
741    /// `av_channel_layout_from_string` reads them.
742    #[must_use]
743    pub fn describe(&self) -> String {
744        self.speakers()
745            .iter()
746            .map(|speaker| speaker.name())
747            .collect::<Vec<_>>()
748            .join("+")
749    }
750}
751
752/// Planar floating-point audio at the project sample rate.
753///
754/// Positions are sample indices, never ticks, because a tick is not a whole number of samples
755/// at 44.1 kHz. Sample `n` is at `n / sample_rate` seconds on the block's timeline (the
756/// source's for a decoder, the project's for a mixer).
757///
758/// Decoder and [`AudioBlockProvider`] blocks keep the source's channels and speakers; the mixer
759/// folds them into the project layout.
760#[derive(Clone, Debug, PartialEq)]
761pub struct AudioBlock {
762    /// Index of the first sample, at `sample_rate`.
763    pub start_sample: i64,
764    /// Project sample rate used by every returned block.
765    pub sample_rate: u32,
766    /// The speaker each of `channels` feeds, one per plane.
767    pub speakers: SpeakerLayout,
768    /// One vector per channel, all with equal lengths, in `speakers`' order.
769    pub channels: Vec<Vec<f32>>,
770}
771
772impl AudioBlock {
773    /// Samples per channel.
774    #[must_use]
775    pub fn frames(&self) -> usize {
776        self.channels.first().map_or(0, Vec::len)
777    }
778
779    /// Index one past the last sample.
780    #[must_use]
781    pub fn end_sample(&self) -> i64 {
782        self.start_sample
783            .saturating_add(i64::try_from(self.frames()).unwrap_or(i64::MAX))
784    }
785
786    /// The first sample's time, rounded down to the tick grid. Audio positions stay in samples.
787    #[must_use]
788    pub fn start_time(&self) -> MediaTime {
789        MediaTime::from_ticks(sample_ticks_floor(self.start_sample, self.sample_rate))
790    }
791}
792
793/// The tick at or before sample `sample` at `sample_rate`.
794#[must_use]
795pub fn sample_ticks_floor(sample: i64, sample_rate: u32) -> i64 {
796    let ticks = (i128::from(sample) * i128::from(alpha2_time::TICKS_PER_SECOND))
797        .div_euclid(i128::from(sample_rate.max(1)));
798    i64::try_from(ticks).unwrap_or(if ticks < 0 { i64::MIN } else { i64::MAX })
799}
800
801/// Generic color declaration for a host-rasterized texture.
802#[derive(Copy, Clone, Debug, Eq, PartialEq)]
803pub enum RasterColorSpace {
804    /// IEC sRGB encoded RGB.
805    Srgb,
806    /// Linear-light RGB with BT.709/sRGB primaries.
807    LinearSrgb,
808}
809
810/// Alpha representation of host pixels.
811#[derive(Copy, Clone, Debug, Eq, PartialEq)]
812pub enum Premultiplication {
813    /// RGB has already been multiplied by alpha.
814    Premultiplied,
815    /// RGB is straight and must be premultiplied at upload.
816    Straight,
817    /// Pixels are opaque.
818    Opaque,
819}
820
821/// Generic image/video/text texture descriptor owned by a host.
822#[derive(Clone, Debug, Eq, PartialEq)]
823pub struct HostTexture {
824    /// Host-defined cache identity.
825    pub content_version: u64,
826    /// Width in pixels.
827    pub width: u32,
828    /// Height in pixels.
829    pub height: u32,
830    /// Alpha representation.
831    pub premultiplication: Premultiplication,
832    /// RGB encoding.
833    pub color_space: RasterColorSpace,
834}
835
836/// Horizontal alignment applied by a host text layout engine.
837#[derive(Copy, Clone, Debug, Default, Eq, PartialEq)]
838pub enum TextAlign {
839    /// Align each line to its paragraph's leading edge (left for LTR, right for RTL).
840    #[default]
841    Start,
842    /// Center each line in the requested layout width.
843    Center,
844    /// Align each line to its paragraph's trailing edge.
845    End,
846}
847
848/// How a text host draws emoji and other color glyphs.
849#[derive(Copy, Clone, Debug, Default, Eq, PartialEq)]
850pub enum EmojiPolicy {
851    /// Draw color glyphs (COLR, CBDT or sbix) in their own colors. Emoji-presentation graphemes
852    /// try color fonts first, and U+FE0E text presentation tries the others first.
853    #[default]
854    Color,
855    /// Draw every glyph as an outline in the text color, trying fonts without color glyphs first
856    /// for emoji.
857    Monochrome,
858    /// Draw each emoji-presentation grapheme (per UTS #51), with its sequence and modifiers, as
859    /// one U+FFFD. Symbols shown as text by default, such as (c), stay.
860    Replace,
861}
862
863/// Layout facts attached to a host-rasterized text texture.
864///
865/// The compositor treats [`Self::texture`] like any image texture; the metrics serve placement,
866/// cache validation and cross-host tests.
867#[derive(Clone, Debug, PartialEq)]
868pub struct TextTexture {
869    /// Generic texture identity and pixel declaration.
870    pub texture: HostTexture,
871    /// The layout box's left edge in the texture, in pixels. The same margin is added on both
872    /// sides for overhanging ink.
873    pub layout_x: f32,
874    /// The layout box's top edge in the texture, in pixels, with the same margin below.
875    pub layout_y: f32,
876    /// Logical layout width before integer pixel rounding.
877    pub layout_width: f32,
878    /// Logical layout height before integer pixel rounding.
879    pub layout_height: f32,
880    /// Distance from the layout box's top edge to the first alphabetic baseline.
881    pub first_baseline: f32,
882    /// Maximum ink extent above a baseline, at least the nominal ascent.
883    pub ascent: f32,
884    /// Maximum ink extent below a baseline, at least the nominal descent.
885    pub descent: f32,
886    /// Number of laid-out lines.
887    pub line_count: u32,
888}
889
890impl TextTexture {
891    /// Checks dimensions and finite layout metrics at the public boundary.
892    #[must_use]
893    pub fn is_valid(&self) -> bool {
894        self.texture.width > 0
895            && self.texture.height > 0
896            && self.line_count > 0
897            && [
898                self.layout_x,
899                self.layout_y,
900                self.layout_width,
901                self.layout_height,
902                self.first_baseline,
903                self.ascent,
904                self.descent,
905            ]
906            .into_iter()
907            .all(|value| value.is_finite() && value >= 0.0)
908            && self.first_baseline <= self.layout_height
909            && f64::from(self.layout_x) + f64::from(self.layout_width)
910                <= f64::from(self.texture.width)
911            && f64::from(self.layout_y) + f64::from(self.layout_height)
912                <= f64::from(self.texture.height)
913    }
914}
915
916/// RGBA8 pixels returned by an image, video, or text rasterization host.
917#[derive(Clone, Debug, PartialEq)]
918pub struct HostTexturePixels {
919    /// Shared texture descriptor. Text hosts additionally return [`TextTexture`].
920    pub texture: HostTexture,
921    /// Tightly packed top-to-bottom RGBA8 rows.
922    pub rgba8: Vec<u8>,
923}
924
925impl HostTexturePixels {
926    /// Checks that the owned bytes exactly cover the declared texture.
927    #[must_use]
928    pub fn is_valid(&self) -> bool {
929        usize::try_from(self.texture.width)
930            .ok()
931            .and_then(|width| {
932                usize::try_from(self.texture.height)
933                    .ok()
934                    .and_then(|height| width.checked_mul(height))
935            })
936            .and_then(|pixels| pixels.checked_mul(4))
937            == Some(self.rgba8.len())
938    }
939}
940
941/// Media stream domain.
942#[derive(Copy, Clone, Debug, Eq, PartialEq)]
943pub enum StreamKind {
944    /// Video stream.
945    Video,
946    /// Audio stream.
947    Audio,
948}
949
950/// Platform-neutral probe result for one stream.
951#[derive(Clone, Debug, PartialEq)]
952pub struct StreamInfo {
953    /// Demuxer stream index.
954    pub index: usize,
955    /// Stream domain.
956    pub kind: StreamKind,
957    /// Codec short name when available.
958    pub codec: String,
959    /// Stream duration when known.
960    pub duration: Option<MediaTime>,
961    /// Video dimensions.
962    pub dimensions: Option<(u32, u32)>,
963    /// Video frame rate.
964    pub frame_rate: Option<FrameRate>,
965    /// Audio sample rate.
966    pub sample_rate: Option<u32>,
967    /// Audio channel count.
968    pub channels: Option<u32>,
969    /// How the stream's pictures are shown upright.
970    pub orientation: Orientation,
971    /// Sample aspect ratio.
972    pub sample_aspect_ratio: SampleAspectRatio,
973    /// Declared video color.
974    pub color: Option<ColorMetadata>,
975    /// Bytes per decoded picture in the decoder's output format (`av_image_get_buffer_size` at
976    /// the coded size), or `None` when the format is unknown.
977    pub frame_bytes: Option<u64>,
978    /// How a video stream carries alpha, when it does; `None` for an opaque stream.
979    pub alpha: Option<SourceAlpha>,
980    /// The stream's `language` tag, when tagged.
981    pub language: Option<String>,
982    /// The stream's `title` tag, when tagged.
983    pub title: Option<String>,
984}
985
986/// How a video stream carries an alpha channel.
987#[derive(Copy, Clone, Debug, Eq, PartialEq)]
988pub enum SourceAlpha {
989    /// VP9 in Matroska or `WebM` with `alpha_mode` 1: the alpha plane is a second VP9 stream in
990    /// block additions, readable only by libvpx's decoder.
991    Vp9SideData,
992    /// HEVC with an auxiliary alpha layer (Apple's HEVC with alpha). No supported decoder reads
993    /// it, so the base layer decodes opaque.
994    HevcAuxiliaryLayer,
995    /// A pixel format with an alpha plane (`ProRes` 4444, PNG, `QuickTime` Animation).
996    Planar,
997}
998
999impl SourceAlpha {
1000    /// The name used in reports.
1001    #[must_use]
1002    pub const fn as_str(self) -> &'static str {
1003        match self {
1004            Self::Vp9SideData => "vp9-side-data",
1005            Self::HevcAuxiliaryLayer => "hevc-auxiliary-layer",
1006            Self::Planar => "planar",
1007        }
1008    }
1009}
1010
1011/// Kind of decoder cache/refill operation.
1012#[derive(Copy, Clone, Debug, Eq, PartialEq)]
1013pub enum DecodeRequestKind {
1014    /// Normal look-ahead fill.
1015    Prefetch,
1016    /// Exact seek: flush decoder state and begin at/before the requested time.
1017    Seek,
1018    /// Refill after cache eviction.
1019    Evicted,
1020    /// Refill every referenced input after GPU device recovery.
1021    DeviceRecovery,
1022}
1023
1024/// One idempotent decoder request. Hosts discard results with an old generation.
1025#[derive(Clone, Debug, Eq, PartialEq)]
1026pub struct DecodeRequest {
1027    /// Source identity.
1028    pub source: SourceId,
1029    /// Requested source timestamp.
1030    pub time: MediaTime,
1031    /// Why the engine needs the input.
1032    pub kind: DecodeRequestKind,
1033    /// Monotonically increasing seek/recovery generation.
1034    pub generation: u64,
1035}
1036
1037/// Result correlated to a decoder request, safe for out-of-order completion.
1038#[derive(Clone, Debug, PartialEq)]
1039pub struct DecodeResult {
1040    /// Original request.
1041    pub request: DecodeRequest,
1042    /// Decoder outcome.
1043    pub event: DecodeEvent,
1044}
1045
1046/// Decoder output and terminal states.
1047#[derive(Clone, Debug, PartialEq)]
1048pub enum DecodeEvent {
1049    /// Decoded video became available.
1050    Video(DecodedVideoFrame),
1051    /// Decoded audio became available.
1052    Audio(AudioBlock),
1053    /// No exact frame is available yet; retry after feeding more input.
1054    Retry,
1055    /// The selected stream has ended.
1056    EndOfStream,
1057}
1058
1059/// Cancellation flag shared across adapter operations.
1060#[derive(Clone, Debug, Default)]
1061pub struct CancelToken(Arc<AtomicBool>);
1062
1063impl CancelToken {
1064    /// Requests cancellation. The operation must stop at its next adapter boundary.
1065    pub fn cancel(&self) {
1066        self.0.store(true, Ordering::Release);
1067    }
1068
1069    /// Returns whether cancellation was requested.
1070    #[must_use]
1071    pub fn is_cancelled(&self) -> bool {
1072        self.0.load(Ordering::Acquire)
1073    }
1074}
1075
1076/// The message every timed-out GPU wait carries, so hosts that see only error text can classify
1077/// it as `GPU_TIMEOUT`.
1078pub const GPU_TIMEOUT_MESSAGE: &str = "GPU work did not complete within the wait timeout";
1079
1080/// What a failed GPU call says about its device, read from the platform status (`VkResult`,
1081/// `HRESULT` or `CVReturn`) rather than from any message.
1082#[derive(Copy, Clone, Debug, Eq, PartialEq)]
1083#[non_exhaustive]
1084pub enum GpuFault {
1085    /// The device was lost or removed; nothing more runs on it.
1086    DeviceLost,
1087    /// The device was reset because work ran too long (`DXGI_ERROR_DEVICE_HUNG`).
1088    DeviceHung,
1089    /// The device could not allocate memory of its own.
1090    DeviceMemory,
1091    /// The driver could not allocate host (CPU) memory for the call.
1092    HostMemory,
1093    /// GPU work the call waited on did not complete within the wait timeout.
1094    Timeout,
1095}
1096
1097impl GpuFault {
1098    /// A stable name for logs and reports.
1099    #[must_use]
1100    pub const fn as_str(self) -> &'static str {
1101        match self {
1102            Self::DeviceLost => "device-lost",
1103            Self::DeviceHung => "device-hung",
1104            Self::DeviceMemory => "device-memory",
1105            Self::HostMemory => "host-memory",
1106            Self::Timeout => "timeout",
1107        }
1108    }
1109}
1110
1111/// Typed decoder failure.
1112///
1113/// Damage the decoder policy skips is reported through diagnostics, not as an error; damage it
1114/// does not skip is an adapter failure.
1115#[derive(Clone, Debug, Eq, PartialEq)]
1116#[non_exhaustive]
1117pub enum DecodeError {
1118    /// The operation was cancelled.
1119    Cancelled,
1120    /// The requested stream or timestamp is outside the resource.
1121    OutOfRange,
1122    /// The adapter does not support this media representation.
1123    Unsupported(String),
1124    /// Adapter-specific failure, represented as stable text rather than a platform type.
1125    Adapter(String),
1126    /// A GPU call failed; `message` names the call and its platform status.
1127    Gpu {
1128        /// What the status says about the device.
1129        fault: GpuFault,
1130        /// The failed call and its platform status.
1131        message: String,
1132    },
1133}
1134
1135/// Why an encoder did not open, as far as its own status and log say.
1136#[derive(Copy, Clone, Debug, Eq, Hash, PartialEq)]
1137pub enum OpenFailureKind {
1138    /// The machine lacks the device, driver or transform; retrying will not help.
1139    Absent,
1140    /// All sessions are taken (such as an NVENC session limit); retrying after another export
1141    /// ends can succeed.
1142    Busy,
1143    /// The encoder runs here but refuses this output's size, pixels or options.
1144    Unsuitable,
1145    /// Nothing typed says which.
1146    Unknown,
1147}
1148
1149impl OpenFailureKind {
1150    /// A stable name for logs and reports.
1151    #[must_use]
1152    pub const fn as_str(self) -> &'static str {
1153        match self {
1154            Self::Absent => "absent",
1155            Self::Busy => "busy",
1156            Self::Unsuitable => "unsuitable",
1157            Self::Unknown => "unknown",
1158        }
1159    }
1160}
1161
1162/// One encoder that did not open, and why.
1163#[derive(Clone, Debug, Eq, PartialEq)]
1164pub struct EncoderRefusal {
1165    /// The encoder, as `FFmpeg` names it (`h264_nvenc`).
1166    pub encoder: String,
1167    /// Whether it was tried on the GPU.
1168    pub hardware_accelerated: bool,
1169    /// What the refusal is evidence of.
1170    pub kind: OpenFailureKind,
1171    /// The encoder's own words, with the log lines it wrote.
1172    pub reason: String,
1173}
1174
1175impl DecodeError {
1176    /// Returns whether the decoder must be discarded instead of retried.
1177    #[must_use]
1178    pub const fn is_fatal(&self) -> bool {
1179        matches!(
1180            self,
1181            Self::Unsupported(_) | Self::Adapter(_) | Self::Gpu { .. }
1182        )
1183    }
1184}
1185
1186impl fmt::Display for DecodeError {
1187    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
1188        match self {
1189            Self::Cancelled => formatter.write_str("decode was cancelled"),
1190            Self::OutOfRange => formatter.write_str("decode request is out of range"),
1191            Self::Unsupported(message) => write!(formatter, "unsupported media: {message}"),
1192            Self::Adapter(message) | Self::Gpu { message, .. } => {
1193                write!(formatter, "decoder adapter failed: {message}")
1194            }
1195        }
1196    }
1197}
1198
1199impl Error for DecodeError {}
1200
1201/// Stateful media decoder implemented by a platform binding.
1202pub trait Decoder {
1203    /// Returns deterministic stream metadata and stream selection.
1204    fn streams(&self) -> &[StreamInfo];
1205    /// Flushes queued packets and frames without changing stream selection.
1206    ///
1207    /// # Errors
1208    /// Returns a platform-neutral adapter failure when flushing fails.
1209    fn flush(&mut self) -> Result<(), DecodeError>;
1210    /// Seeks and returns what is presented at the request's time.
1211    ///
1212    /// For video this is the last frame at or before the time plus the stream's
1213    /// [`alpha2_time::presentation_slack`], which absorbs timestamp rounding. Finding it
1214    /// decodes the following frame, which the next [`Self::decode_next`] returns. Times before
1215    /// the first frame return the first, times after the last return the last, and a stream
1216    /// without frames is [`DecodeError::OutOfRange`]. For audio it is the block holding the
1217    /// time's sample.
1218    ///
1219    /// # Errors
1220    /// Returns cancellation, range, unsupported-media, or adapter failures.
1221    fn seek(
1222        &mut self,
1223        request: DecodeRequest,
1224        cancel: &CancelToken,
1225    ) -> Result<DecodeResult, DecodeError>;
1226    /// Advances packet draining by one observable event.
1227    ///
1228    /// # Errors
1229    /// Returns cancellation, unsupported-media, or adapter failures.
1230    fn decode_next(&mut self, cancel: &CancelToken) -> Result<DecodeEvent, DecodeError>;
1231}
1232
1233/// A provider's answer to one request: source samples and whether the source extends past them.
1234#[derive(Clone, Copy, Debug, PartialEq)]
1235pub struct AudioSpan<'a> {
1236    /// Source samples at the project rate, read by their own `start_sample`.
1237    pub block: &'a AudioBlock,
1238    /// Whether the source has no samples before `block.start_sample`.
1239    pub starts_source: bool,
1240    /// Whether the source has no samples from `block.end_sample()` on.
1241    pub ends_source: bool,
1242}
1243
1244impl<'a> AudioSpan<'a> {
1245    /// A block holding the source's entire audio.
1246    #[must_use]
1247    pub const fn whole(block: &'a AudioBlock) -> Self {
1248        Self {
1249            block,
1250            starts_source: true,
1251            ends_source: true,
1252        }
1253    }
1254
1255    /// Whether every sample of `[start, end)` is in the block or in silence implied by
1256    /// [`Self::starts_source`] or [`Self::ends_source`].
1257    #[must_use]
1258    pub fn covers(&self, start: i64, end: i64) -> bool {
1259        (self.starts_source || self.block.start_sample <= start)
1260            && (self.ends_source || self.block.end_sample() >= end)
1261    }
1262}
1263
1264/// Retrieves project-rate planar audio without exposing its backing cache.
1265pub trait AudioBlockProvider {
1266    /// Returns source samples `[start_sample, start_sample + frames)` at the
1267    /// project rate, as a span that [covers](AudioSpan::covers) all of them.
1268    ///
1269    /// The block may extend past the request. Outside the source's audio the provider either
1270    /// holds zeros or sets [`AudioSpan::starts_source`] / [`AudioSpan::ends_source`]. A provider
1271    /// that cannot yet cover the request returns `None` or a non-covering span, and the mixer
1272    /// reports the source missing rather than mixing silence.
1273    ///
1274    /// `stream` counts over the source's audio streams in container order; `None` is the stream
1275    /// the host plays by default.
1276    fn block(
1277        &self,
1278        source: &SourceId,
1279        stream: Option<u32>,
1280        start_sample: i64,
1281        frames: usize,
1282    ) -> Option<AudioSpan<'_>>;
1283}
1284
1285/// Receives project-rate planar audio from offline or realtime graph hosts.
1286pub trait AudioBlockSink {
1287    /// Writes one monotonic audio block.
1288    ///
1289    /// # Errors
1290    /// Returns a platform-neutral encode error on cancellation, invalid timing,
1291    /// or host failure.
1292    fn write_audio(&mut self, block: &AudioBlock, cancel: &CancelToken) -> Result<(), EncodeError>;
1293
1294    /// Drains and commits the sink.
1295    ///
1296    /// # Errors
1297    /// Returns cancellation or host failures; success means all delayed
1298    /// samples were committed.
1299    fn finish_audio(&mut self, cancel: &CancelToken) -> Result<(), EncodeError>;
1300
1301    /// Discards partial output.
1302    ///
1303    /// # Errors
1304    /// Returns an error when cleanup fails.
1305    fn abort_audio(&mut self) -> Result<(), EncodeError>;
1306}
1307
1308/// One input accepted by an encoding/mux adapter.
1309#[derive(Clone, Debug, PartialEq)]
1310pub enum EncodeEvent {
1311    /// Premultiplied rendered video.
1312    Video(DecodedVideoFrame),
1313    /// Project-rate planar audio.
1314    Audio(AudioBlock),
1315}
1316
1317/// Typed encoding failure.
1318#[derive(Clone, Debug, Eq, PartialEq)]
1319#[non_exhaustive]
1320pub enum EncodeError {
1321    /// The operation was cancelled; partial output must be removed by policy.
1322    Cancelled,
1323    /// Input timestamps violated monotonic/interleave requirements.
1324    InvalidTimestamp,
1325    /// Adapter failure without leaking a platform error type.
1326    Adapter(String),
1327    /// The output file could not be created or claimed. Nothing was encoded.
1328    Output(String),
1329    /// Another live export, in any process, holds the output's partial file. Nothing was
1330    /// encoded.
1331    OutputInUse(String),
1332    /// The output was encoded but could not be moved to its final path. The finished file is
1333    /// kept beside the target under another name.
1334    Publish {
1335        /// The target, the step that failed and the operating system's error.
1336        message: String,
1337        /// Where the finished file is now; `None` when that move also failed.
1338        kept: Option<std::path::PathBuf>,
1339    },
1340    /// The encoder refused an input frame on a still-usable device; another path may succeed.
1341    EncoderRejected {
1342        /// The encoder that refused, as `FFmpeg` names it (`h264_d3d12va`).
1343        encoder: String,
1344        /// The frame it refused, counted from 0 in the order frames were sent.
1345        frame: u64,
1346        /// The encoder's message and session state.
1347        message: String,
1348    },
1349    /// A GPU call failed; `message` names the call and its platform status.
1350    Gpu {
1351        /// What the status says about the device.
1352        fault: GpuFault,
1353        /// The failed call and its platform status.
1354        message: String,
1355    },
1356    /// No encoder candidate opened. Each refusal's kind tells whether retrying can help.
1357    EncodersRefused {
1358        /// Every candidate's refusal, in the order they were tried.
1359        message: String,
1360        /// The refusals themselves, most preferred candidate first.
1361        refusals: Vec<EncoderRefusal>,
1362    },
1363}
1364
1365impl EncodeError {
1366    /// A timed-out GPU wait for `what`, carrying [`GPU_TIMEOUT_MESSAGE`].
1367    #[must_use]
1368    pub fn gpu_timeout(what: impl fmt::Display) -> Self {
1369        Self::Gpu {
1370            fault: GpuFault::Timeout,
1371            message: format!("{what}: {GPU_TIMEOUT_MESSAGE}"),
1372        }
1373    }
1374}
1375
1376impl fmt::Display for EncodeError {
1377    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
1378        match self {
1379            Self::Cancelled => formatter.write_str("encode was cancelled"),
1380            Self::InvalidTimestamp => formatter.write_str("encode timestamp is invalid"),
1381            Self::Adapter(message)
1382            | Self::Gpu { message, .. }
1383            | Self::EncodersRefused { message, .. } => {
1384                write!(formatter, "encoder adapter failed: {message}")
1385            }
1386            Self::EncoderRejected { message, .. } => formatter.write_str(message),
1387            Self::Output(message) | Self::OutputInUse(message) => {
1388                write!(formatter, "cannot create the output: {message}")
1389            }
1390            Self::Publish {
1391                message,
1392                kept: Some(kept),
1393            } => write!(
1394                formatter,
1395                "cannot publish the output: {message}; the finished render is kept at {}",
1396                kept.display()
1397            ),
1398            Self::Publish {
1399                message,
1400                kept: None,
1401            } => write!(
1402                formatter,
1403                "cannot publish the output: {message}; the finished render could not be kept"
1404            ),
1405        }
1406    }
1407}
1408
1409impl Error for EncodeError {}
1410
1411/// Host encoding and muxing boundary.
1412pub trait EncodeSink {
1413    /// Queues one timestamped media item.
1414    ///
1415    /// # Errors
1416    /// Returns cancellation, invalid timestamp, or adapter failures.
1417    fn write(&mut self, event: EncodeEvent, cancel: &CancelToken) -> Result<(), EncodeError>;
1418    /// Drains encoder delay, interleaves remaining packets, and writes the trailer.
1419    ///
1420    /// # Errors
1421    /// Returns cancellation or adapter failures; success means the trailer exists.
1422    fn finish(&mut self, cancel: &CancelToken) -> Result<(), EncodeError>;
1423    /// Aborts and applies the adapter's partial-output cleanup policy.
1424    ///
1425    /// # Errors
1426    /// Returns an adapter failure if partial output could not be cleaned up.
1427    fn abort(&mut self) -> Result<(), EncodeError>;
1428}
1429
1430#[cfg(test)]
1431mod tests {
1432    use super::SampleAspectRatio;
1433
1434    #[test]
1435    fn a_pixel_aspect_ratio_is_kept_in_lowest_terms_and_shows_as_a_browser_shows_it() {
1436        let ratio = |num, den| SampleAspectRatio { num, den };
1437        assert_eq!(SampleAspectRatio::new(8, 6), Some(ratio(4, 3)));
1438        assert_eq!(SampleAspectRatio::new(0, 1), None);
1439        assert_eq!(SampleAspectRatio::new(1, 0), None);
1440        assert_eq!(SampleAspectRatio::new(u64::from(u32::MAX) + 1, 1), None);
1441        // The declared ratio is the simplest one that rounds to the display size.
1442        let shown = |visible, displayed| SampleAspectRatio::of_display(visible, displayed);
1443        assert_eq!(shown((128, 96), (171, 96)), Some(ratio(4, 3)));
1444        assert_eq!(shown((96, 128), (96, 171)), Some(ratio(3, 4)));
1445        assert_eq!(shown((720, 576), (1024, 576)), Some(ratio(64, 45)));
1446        assert_eq!(shown((720, 480), (655, 480)), Some(ratio(10, 11)));
1447        assert_eq!(shown((720, 480), (720, 524)), Some(ratio(11, 12)));
1448        assert_eq!(shown((1440, 1080), (1920, 1080)), Some(ratio(4, 3)));
1449        assert_eq!(shown((128, 96), (128, 96)), Some(ratio(1, 1)));
1450        // Whatever it finds rounds to the size shown.
1451        for (visible, displayed) in [
1452            ((128, 96), (170, 96)),
1453            ((1000, 999), (1777, 999)),
1454            ((3, 2), (5, 2)),
1455        ] {
1456            let found = shown(visible, displayed).expect("a ratio");
1457            assert_eq!(
1458                found.square_pixel_size(visible.0, visible.1),
1459                displayed,
1460                "{visible:?} {displayed:?}"
1461            );
1462        }
1463        assert_eq!(shown((0, 96), (171, 96)), None);
1464        // Math.round(128 * 4 / 3) = 171, and a narrow pixel stretches the height.
1465        assert_eq!(ratio(4, 3).square_pixel_size(128, 96), (171, 96));
1466        assert_eq!(ratio(64, 45).square_pixel_size(720, 576), (1024, 576));
1467        assert_eq!(ratio(3, 4).square_pixel_size(96, 128), (96, 171));
1468        assert_eq!(ratio(1, 1).square_pixel_size(65, 49), (65, 49));
1469        // Half a pixel rounds up: 3 * 3 / 2 = 4.5.
1470        assert_eq!(ratio(3, 2).square_pixel_size(3, 7), (5, 7));
1471    }
1472
1473    use super::*;
1474
1475    #[test]
1476    fn a_frame_size_is_bounded_on_each_side_and_in_area() {
1477        assert!(frame_size_supported(16_384, 4_096));
1478        assert!(frame_size_supported(8_192, 8_192));
1479        assert!(!frame_size_supported(8_193, 8_192));
1480        assert!(!frame_size_supported(16_385, 1));
1481        assert!(!frame_size_supported(1, 16_385));
1482        assert!(!frame_size_supported(u32::MAX, u32::MAX));
1483    }
1484
1485    #[test]
1486    fn cancellation_is_shared_and_monotonic() {
1487        let token = CancelToken::default();
1488        let other = token.clone();
1489        assert!(!other.is_cancelled());
1490        token.cancel();
1491        assert!(other.is_cancelled());
1492    }
1493
1494    #[test]
1495    fn a_layout_names_each_plane_by_ffmpegs_channel_names() {
1496        let lcr = SpeakerLayout::new(&[
1497            Speaker::FrontCenter,
1498            Speaker::FrontLeft,
1499            Speaker::FrontRight,
1500        ])
1501        .expect("layout");
1502        assert_eq!(lcr.channels(), 3);
1503        assert_eq!(lcr.describe(), "FC+FL+FR");
1504        assert_eq!(format!("{lcr:?}"), r#"["FC", "FL", "FR"]"#);
1505        for (speaker, name, channel) in Speaker::TABLE {
1506            assert_eq!(speaker.name(), name);
1507            assert_eq!(Speaker::from_name(name), Some(speaker));
1508            assert_eq!(speaker.ffmpeg_channel(), channel);
1509            assert_eq!(Speaker::from_ffmpeg_channel(i64::from(channel)), speaker);
1510        }
1511        // Unused (0x200), ambisonic (0x400 and up) and user channels name no speaker.
1512        for channel in [-1, 18, 0x200, 0x400, 0x401, 0x7ff, 1_000] {
1513            assert_eq!(Speaker::from_ffmpeg_channel(channel), Speaker::Unnamed);
1514        }
1515        assert_eq!(Speaker::from_name("front left"), None);
1516        assert!(SpeakerLayout::new(&[]).is_none());
1517        assert!(SpeakerLayout::new(&[Speaker::FrontLeft; MAX_AUDIO_CHANNELS + 1]).is_none());
1518    }
1519
1520    #[test]
1521    fn a_source_that_declares_no_speaker_has_ffmpegs_default_for_its_count() {
1522        let names = |channels| {
1523            SpeakerLayout::default_for(channels)
1524                .expect("a default")
1525                .describe()
1526        };
1527        assert_eq!(names(1), "FC");
1528        assert_eq!(names(3), "FL+FR+LFE");
1529        assert_eq!(names(4), "FL+FR+FC+BC");
1530        assert_eq!(names(8), "FL+FR+FC+LFE+BL+BR+SL+SR");
1531        assert_eq!(names(9), "FL+FR+FC+LFE+BL+BR+SL+SR+UNK");
1532        assert_eq!(names(10), "FL+FR+FC+LFE+SL+SR+TFL+TFR+TBL+TBR");
1533        assert_eq!(SpeakerLayout::default_for(24).expect("22.2").channels(), 24);
1534        assert!(SpeakerLayout::default_for(0).is_none());
1535        assert!(SpeakerLayout::default_for(MAX_AUDIO_CHANNELS + 1).is_none());
1536        let unnamed = [Speaker::Unnamed; 2];
1537        assert_eq!(
1538            SpeakerLayout::declared_or_default(&unnamed),
1539            Some((SpeakerLayout::default_for(2).expect("stereo"), true))
1540        );
1541        let partly = [Speaker::FrontCenter, Speaker::Unnamed];
1542        assert_eq!(
1543            SpeakerLayout::declared_or_default(&partly),
1544            Some((SpeakerLayout::new(&partly).expect("layout"), false))
1545        );
1546    }
1547
1548    #[test]
1549    fn a_span_covers_a_request_only_where_it_holds_samples_or_knows_silence() {
1550        let block = AudioBlock {
1551            start_sample: 100,
1552            sample_rate: 48_000,
1553            speakers: SpeakerLayout::default_for(1).expect("mono"),
1554            channels: vec![vec![0.5; 50]],
1555        };
1556        let partial = AudioSpan {
1557            block: &block,
1558            starts_source: false,
1559            ends_source: false,
1560        };
1561        assert!(partial.covers(100, 150));
1562        assert!(partial.covers(120, 130));
1563        assert!(!partial.covers(99, 150), "a sample before the block");
1564        assert!(!partial.covers(100, 151), "a sample after the block");
1565        let starts = AudioSpan {
1566            starts_source: true,
1567            ..partial
1568        };
1569        assert!(starts.covers(0, 150));
1570        assert!(!starts.covers(0, 151));
1571        assert!(AudioSpan::whole(&block).covers(-5, 1_000));
1572    }
1573
1574    #[test]
1575    fn text_descriptor_and_generic_pixels_validate_without_compositor_types() {
1576        let texture = HostTexture {
1577            content_version: 2,
1578            width: 4,
1579            height: 3,
1580            premultiplication: Premultiplication::Premultiplied,
1581            color_space: RasterColorSpace::Srgb,
1582        };
1583        let text = TextTexture {
1584            texture: texture.clone(),
1585            layout_x: 0.0,
1586            layout_y: 0.0,
1587            layout_width: 4.0,
1588            layout_height: 3.0,
1589            first_baseline: 2.0,
1590            ascent: 2.0,
1591            descent: 1.0,
1592            line_count: 1,
1593        };
1594        assert!(text.is_valid());
1595        assert!(
1596            HostTexturePixels {
1597                texture,
1598                rgba8: vec![0; 4 * 3 * 4],
1599            }
1600            .is_valid()
1601        );
1602    }
1603}