Sign in

    moonav1

    Pure MoonBit AV1 and AVIF decoder for native, JavaScript, and WebAssembly GC.

    av1
    avif
    decoder
    image
    wasm
    Download zip
    Author
    Version
    0.2.0
    License
    Apache-2.0
    Last updated
    24 days ago
    Downloads
    40

    No dependencies

    #MoonAV1

    纯 MoonBit AV1/AVIF 解码基础库,面向 native、JavaScript 和 wasm-gc。核心解码不调用浏览器图片解码器,不通过 FFI 调用 libaom、dav1d 或 libavif;这些工具仅用于生成独立测试参考。

    #能力与边界

    • AV1:8/10/12-bit,单色及 4:2:0、4:2:2、4:4:4;帧内/帧间重建、参考与熵状态、多个 tile、量化、环路滤波和 film grain。
    • AVIF:主图、辅助 alpha、grid、静态/动画的 prem 关联,以及带独立颜色/alpha 轨道的动画。
    • 输出原生 8/10/12-bit 像素平面、straight RGBA8 或 RGBA16,包含静态图和动画的高位深 alpha。
    • 提供分块 AV1 输入、惰性 AVIF 动画、错误诊断、解码限额、显示变换和可复用输出缓冲区。
    • 支持 IVF、MP4/fMP4、WebM/Matroska 的 AV1 轨道读取、分块容器输入和时间定位。
    • 提供 ICC 输入色彩转换、PQ/HLG 转 SDR,以及带透明度处理的分数裁剪和重采样。
    • 库仅负责解码,不包含 AV1/AVIF 编码、图像滤镜、浏览器 UI 或文件系统。

    RGBA 使用源 primaries/transfer、最近邻色度上采样及最终裁剪/舍入;未指定矩阵采用 BT.601。XYZ 转为 BT.709/sRGB。这里不进行 HDR 色调映射或显示器色域适配。PQ 参考中的四个通道严格匹配独立高精度 H.273 金值,并限定与 zimg 的差值不超过 1;不能将这一特例描述成与 zimg 全部字节相同。见 颜色参考。

    #安装

    在 MoonBit 项目中添加依赖:

    moon add 0717lee/moonav1@0.2.0

    在调用方的 moon.pkg 中导入:

    import {
    "0717lee/moonav1",
    }

    随后可通过 @moonav1 调用下方接口。native、JavaScript 和 wasm-gc 共用同一个包。

    #快速运行

    安装 MoonBit 后克隆源码,在仓库根目录运行:

    git clone https://github.com/0717lee/moonav1.git cd moonav1 moon run examples/decode --target js

    预期输出 64x64 AV1 -> RGBA8 OK。示例解码内嵌的 10-bit AV1 样本,核对输出尺寸和像素,并检查空输入被拒绝;不需要下载图片或安装外部解码器。也可使用 --target wasm-gc 或 --target native。

    moon run examples/native_pixels --target js 演示高位深平面、RGBA16 和动画选帧;moon run examples/extensions --target js 演示流式输入、元数据和缓冲区复用。两个示例同样支持 native 和 wasm-gc。

    moon run examples/containers --target js 演示 IVF 整文件及分块解码,并按时间戳取帧;同样支持 native 和 wasm-gc。

    moon run examples/color_video --target js 演示 ICC、HDR、分数裁剪以及三种视频容器;同样支持 native 和 wasm-gc。

    #库接口

    消费端导入后可通过 @moonav1 调用:

    fn decode_image(bytes : Array[Byte]) -> @moonav1.Image? {
    @moonav1.avif_decode_rgba(bytes)
    }

    用途接口
    AVIF 主图与 alpha/gridavif_decode_rgba
    AVIF 主图,不合成辅助 alphaavif_decode
    AVIF 动画与时间选择avif_decode_animation、avif_animation_frame_at
    原始 AV1 首个呈现av1_decode
    跨 temporal unit 的解码状态av1_video_decoder、av1_video_decode_temporal_unit
    容器/序列信息avif_container_parse、av1_sequence_info
    原生像素与动画av1_decode_native、avif_decode_native、avif_decode_animation_native
    RGBA16 输出av1_decode_rgba16、avif_decode_rgba16、Av1NativeFrame::to_rgba16
    流式与惰性解码Av1StreamDecoder、AvifAnimationDecoder
    诊断与资源限额av1_decode_native_result、avif_decode_native_result、DecodeLimits
    容器解码与定位Av1ContainerDecoder、Av1ContainerStreamDecoder、Av1PresentationTimeline
    色彩管理与 HDRIccProfile、IccTransformOptions、Av1NativeFrame::to_sdr_rgba16
    分数裁剪与重采样AvifMetadata::resample_rgba8、resample_rgba16

    解码接口通过 None 拒绝无效或不支持的输入。状态化接口的 Some([]) 表示合法但无显示帧的单元;隐藏帧仍更新参考状态。完整接口以 pkg.generated.mbti 为准。

    新增 Result 接口返回错误类别、上下文和可定位的字节偏移。像素布局、精度、所有权、流式边界和限额计数分别见 原生像素、RGBA16、调用者接口和解码限额。

    容器支持范围见 IVF/MP4/WebM,分块状态与 MP4 索引回放见容器流式接口,时间单位与 edit-list 映射见时间定位。

    ICC、HDR和重采样均通过显式接口调用,保留基础解码的既有颜色和像素语义。

    #本地构建与验证

    使用与 CI 相同的 MoonBit 编译器 0.10.14+7d59c7ec9;native 目标需要 C 工具链。从 GitHub 克隆源码后,在仓库根目录执行:

    moon version --all moon check moon build moon test --target js moon test --target wasm-gc moon test --target native

    普通测试使用随库提交的独立参考,不需要外部解码器。tests/fixtures/ 中的说明和 manifest 记录样本来源、工具版本和像素约定。生成器位于 scripts/,外部参考工具只在重新生成或复核参考时使用。

    #扩展验证与基准

    文件消费、真实媒体和长视频工具见验证指南,基准复现见性能指南。大型输入及独立像素参考按版本保存在 Release 下载包中,可通过 python scripts/fetch-fixtures.py --list 选择恢复;普通测试无需下载。

    #许可证

    项目采用 Apache-2.0。算法、表和参考工具的声明见 THIRD_PARTY_NOTICES.md。

    Av1CdefConfig

    pub(all) struct Av1CdefConfig {
    bits : Int
    damping : Int
    y_primary : Array[Int]
    y_secondary : Array[Int]
    uv_primary : Array[Int]
    uv_secondary : Array[Int]
    }

    Raw frame-level CDEF parameters. Primary strengths remain in 8-bit units; secondary syntax value 3 has already been remapped to strength 4. Monochrome configurations have empty UV arrays. A missing configuration in a frame header means CDEF is disabled by the frame/sequence gates.

    Av1CdefParams

    pub(all) struct Av1CdefParams {
    primary_strength : Int
    secondary_strength : Int
    damping : Int
    direction : Int
    }

    Effective CDEF parameters for one luma 8x8 block (chroma 4x4 in 4:2:0). Strengths use 8-bit units: primary is already variance-adjusted and secondary is decoded to 0, 1, 2 or 4. Damping is CdefDamping (3..6).

    Av1ContainerDecoder

    pub struct Av1ContainerDecoder {
    // private fields
    }

    Owned compressed packets with lazy pixel reconstruction. Container tables are checked at construction, while AV1 syntax/entropy failures may occur later. Such failures remain sticky until reset(). Existing frames survive advancing, reset and destruction of this session.

    Av1ContainerDecoder::format

    Av1ContainerDecoder::new

    fn Av1ContainerDecoder::new(data : Array[Byte], format? : Av1ContainerFormat?, track_id? : Int64?, limits? : DecodeLimits) -> Result[Av1ContainerDecoder, DecodeError]

    Av1ContainerDecoder::next_frame

    Read the next displayed picture. Hidden-only packets share this call's work budget with the eventual displayed picture. Timestamps stay in the demuxer's media timeline; container presentation edits are not implicit.

    Av1ContainerDecoder::packet_count

    fn Av1ContainerDecoder::packet_count(self : Av1ContainerDecoder) -> Int

    Av1ContainerDecoder::position

    fn Av1ContainerDecoder::position(self : Av1ContainerDecoder) -> Int

    Index of the next encoded packet, not a count of displayed pictures.

    Av1ContainerDecoder::presentation_timeline

    fn Av1ContainerDecoder::presentation_timeline(self : Av1ContainerDecoder) -> Result[Av1PresentationTimeline, DecodeError]

    Return the explicit presentation mapping for this track. The decoder's default next_frame/seek_timestamp APIs continue to expose raw media timestamps; callers opt into MP4 edits through this value.

    Av1ContainerDecoder::reset

    fn Av1ContainerDecoder::reset(self : Av1ContainerDecoder) -> Unit

    Av1ContainerDecoder::seek_timestamp

    fn Av1ContainerDecoder::seek_timestamp(self : Av1ContainerDecoder, requested_timestamp : Int64) -> Result[Av1ContainerSeekResult, DecodeError]

    Seek to the first selected presentation encountered in container decode order whose known raw-media PTS is at least requested_timestamp. Exact reports equality, Next reports a later PTS, End reports that no selected picture qualifies, and UnknownTimestamp reports the first selected picture that has no timestamp and therefore cannot be compared.

    Av1ContainerDecoder::timescale

    fn Av1ContainerDecoder::timescale(self : Av1ContainerDecoder) -> Int64

    Av1ContainerFormat

    pub(all) enum Av1ContainerFormat {
    Ivf
    Mp4
    WebM
    } derive(Eq,
    Debug
    )

    File containers carrying AV1 low-overhead temporal units.

    Av1ContainerFrame

    pub struct Av1ContainerFrame {
    packet_index : Int
    timestamp : Int64?
    duration : Int64?
    timescale : Int64
    frame : Av1NativeFrame
    }

    A presentation and its original container time, expressed in timescale ticks. packet_index identifies the encoded sample; packets without a presentation are consumed but do not produce a frame.

    Av1ContainerFrameBatch

    pub struct Av1ContainerFrameBatch {
    frames : Array[Av1ContainerFrame]
    status : Av1ContainerStreamStatus
    }

    Av1ContainerPacketBatch

    pub struct Av1ContainerPacketBatch {
    packets : Array[Av1Packet]
    status : Av1ContainerStreamStatus
    }

    Av1ContainerSeekOutcome

    pub(all) enum Av1ContainerSeekOutcome {
    Exact
    Next
    End
    UnknownTimestamp
    } derive(Eq,
    Debug
    )

    Result classification for a timestamp seek. Next means the selected presentation is the first one in container decode order whose known PTS is later than the request; it does not assert that the media has a gap.

    Av1ContainerSeekResult

    pub struct Av1ContainerSeekResult {
    requested_timestamp : Int64
    outcome : Av1ContainerSeekOutcome
    frame : Av1ContainerFrame?
    }

    A timestamp seek result. frame is present for Exact, Next and UnknownTimestamp; End has no frame. Timestamps use the track's raw media timescale. MP4 edit lists are applied only through the explicit Av1PresentationTimeline API.

    Av1ContainerStream

    pub struct Av1ContainerStream {
    // private fields
    }

    Incremental container demux. max_input_bytes bounds retained compressed input/metadata and each feed; max_frames bounds the selected track's total packet count. A whole file may exceed max_input_bytes. Expanded sample tables are additionally bounded by max_frames. No file or network IO occurs.

    Av1ContainerStream::bytes_received

    fn Av1ContainerStream::bytes_received(self : Av1ContainerStream) -> Int64

    Av1ContainerStream::feed

    Av1ContainerStream::finish

    Av1ContainerStream::new

    fn Av1ContainerStream::new(format? : Av1ContainerFormat?, track_id? : Int64?, limits? : DecodeLimits) -> Result[Av1ContainerStream, DecodeError]

    Av1ContainerStream::packet_count

    fn Av1ContainerStream::packet_count(self : Av1ContainerStream) -> Int

    Av1ContainerStream::peak_pending_bytes

    fn Av1ContainerStream::peak_pending_bytes(self : Av1ContainerStream) -> Int

    High-water mark since reset, including both passes of a tail-moov replay.

    Av1ContainerStream::pending_bytes

    fn Av1ContainerStream::pending_bytes(self : Av1ContainerStream) -> Int

    Av1ContainerStream::replay

    fn Av1ContainerStream::replay(self : Av1ContainerStream) -> Result[Unit, DecodeError]

    After an index-at-tail MP4 completes its metadata-only first pass, replay the original file from byte zero using the retained index. No media bytes from the first pass were retained or emitted.

    Av1ContainerStream::reset

    fn Av1ContainerStream::reset(self : Av1ContainerStream) -> Unit

    Av1ContainerStream::track_info

    Copies variable-size metadata, so mutating a result cannot change parsing.

    Av1ContainerStreamDecoder

    pub struct Av1ContainerStreamDecoder {
    // private fields
    }

    Stateful native decoding over bounded container input. All pictures decoded during one feed/finish share a reconstruction budget, including hidden ones.

    Av1ContainerStreamDecoder::feed

    Av1ContainerStreamDecoder::finish

    Av1ContainerStreamDecoder::new

    fn Av1ContainerStreamDecoder::new(format? : Av1ContainerFormat?, track_id? : Int64?, limits? : DecodeLimits) -> Result[Av1ContainerStreamDecoder, DecodeError]

    Av1ContainerStreamDecoder::peak_pending_bytes

    fn Av1ContainerStreamDecoder::peak_pending_bytes(self : Av1ContainerStreamDecoder) -> Int

    Av1ContainerStreamDecoder::pending_bytes

    fn Av1ContainerStreamDecoder::pending_bytes(self : Av1ContainerStreamDecoder) -> Int

    Av1ContainerStreamDecoder::replay

    Av1ContainerStreamDecoder::reset

    Av1ContainerStreamDecoder::track_info

    Av1ContainerStreamInfo

    pub struct Av1ContainerStreamInfo {
    format : Av1ContainerFormat
    track_id : Int64
    width : Int
    height : Int
    timescale : Int64
    movie_timescale : Int64?
    edits : Array[Av1TrackEdit]
    codec_initialization : Array[Byte]
    }

    Owned metadata for the selected track. Packet payloads are delivered only in batches and are not retained in this value.

    Av1ContainerStreamStatus

    pub(all) enum Av1ContainerStreamStatus {
    NeedMoreInput
    Ready
    ReplayRequired
    Finished
    } derive(Eq,
    Debug
    )

    Av1DemuxedTrack

    pub struct Av1DemuxedTrack {
    format : Av1ContainerFormat
    track_id : Int64
    width : Int
    height : Int
    timescale : Int64
    movie_timescale : Int64?
    edits : Array[Av1TrackEdit]
    codec_initialization : Array[Byte]
    packets : Array[Av1Packet]
    }

    Selected AV1 video track. codec_initialization contains low-overhead OBUs, without the four-byte av1C record header; prepend it to the first packet when initializing a fresh AV1 decoder. Buffers do not alias the input. max_frames in the demux policy limits packet count, not decoded pictures.

    Av1FilmGrainParams

    pub(all) struct Av1FilmGrainParams {
    apply_grain : Bool
    grain_seed : Int
    num_y_points : Int
    point_y_value : Array[Int]
    point_y_scaling : Array[Int]
    chroma_scaling_from_luma : Bool
    num_cb_points : Int
    point_cb_value : Array[Int]
    point_cb_scaling : Array[Int]
    num_cr_points : Int
    point_cr_value : Array[Int]
    point_cr_scaling : Array[Int]
    grain_scaling_minus8 : Int
    ar_coeff_lag : Int
    ar_coeffs_y : Array[Int]
    ar_coeffs_cb : Array[Int]
    ar_coeffs_cr : Array[Int]
    ar_coeff_shift_minus6 : Int
    grain_scale_shift : Int
    cb_mult : Int
    cb_luma_mult : Int
    cb_offset : Int
    cr_mult : Int
    cr_luma_mult : Int
    cr_offset : Int
    overlap_flag : Bool
    clip_to_restricted_range : Bool
    }

    Av1FrameCdfs

    pub(all) struct Av1FrameCdfs {
    tables : Array[Array[Array[Int]]]
    }

    Av1FrameHeaderInfo

    pub(all) struct Av1FrameHeaderInfo {
    frame_width : Int
    upscaled_width : Int
    frame_height : Int
    superres_denom : Int
    header_bytes : Int
    tile_payload : Array[Byte]
    base_q_idx : Int
    quant_matrix : Av1QuantMatrix?
    delta_lf_res : Int
    delta_lf_multi : Bool
    tile_cols : Int
    tile_rows : Int
    tile_cols_log2 : Int
    tile_rows_log2 : Int
    tile_col_starts_sb : Array[Int]
    tile_row_starts_sb : Array[Int]
    tile_size_bytes : Int
    context_update_tile_id : Int
    tx_mode_select : Bool
    reduced_tx_set : Bool
    coded_lossless : Bool
    cdef : Av1CdefConfig?
    loop_filter : Av1LoopFilterConfig?
    restoration : Av1RestorationConfig?
    disable_cdf_update : Bool
    allow_screen_content_tools : Bool
    film_grain : Av1FilmGrainParams?
    quant_deltas : Av1QuantDeltas
    delta_q_present : Bool
    delta_q_res : Int
    delta_lf_present : Bool
    segmentation : Av1SegmentationParams
    frame_type : Int
    frame_is_intra : Bool
    show_frame : Bool
    show_existing_frame : Bool
    frame_to_show_map_idx : Int
    error_resilient : Bool
    showable_frame : Bool
    disable_frame_end_update_cdf : Bool
    force_integer_mv : Int
    current_frame_id : Int
    order_hint : Int
    primary_ref_frame : Int
    refresh_frame_flags : Int
    ref_frame_idx : Array[Int]
    order_hints : Array[Int]
    ref_frame_sign_bias : Array[Int]
    allow_high_precision_mv : Bool
    interpolation_filter : Int
    is_motion_mode_switchable : Bool
    use_ref_frame_mvs : Bool
    allow_warped_motion : Bool
    reference_select : Bool
    skip_mode_present : Bool
    skip_mode_frame : Array[Int]
    gm_type : Array[Int]
    gm_params : Array[Array[Int]]
    prev_gm_params : Array[Array[Int]]
    loop_filter_ref_deltas : Array[Int]
    loop_filter_mode_deltas : Array[Int]
    allow_intrabc : Bool
    render_width : Int
    render_height : Int
    }

    Av1FrameInfo

    pub(all) struct Av1FrameInfo {
    key_frame : Bool
    show_frame : Bool
    payload_size : Int
    }

    Header facts available before tile entropy decoding. Reduced still-picture headers imply a key frame and one displayed frame by construction.

    Av1FrameMap

    pub(all) struct Av1FrameMap {
    slots : Array[Av1RefFrame?]
    valid : Array[Bool]
    order_hints : Array[Int]
    frame_types : Array[Int]
    frame_ids : Array[Int]
    upscaled_widths : Array[Int]
    frame_widths : Array[Int]
    frame_heights : Array[Int]
    render_widths : Array[Int]
    render_heights : Array[Int]
    saved_gm_params : Array[Array[Array[Int]]]
    saved_loop_filter_ref_deltas : Array[Array[Int]]
    saved_loop_filter_mode_deltas : Array[Array[Int]]
    saved_segmentation : Array[Av1SegmentationParams]
    saved_segment_ids : Array[Array[Int]]
    saved_film_grain : Array[Av1FilmGrainParams?]
    saved_showable : Array[Bool]
    current_frame_id : Int
    has_frame_id : Bool
    saved_cdfs : Av1FrameCdfs?
    }

    The eight-slot reference buffer plus the derived slot metadata the frame header reads before any pixels exist.

    Av1InterBlock

    pub(all) struct Av1InterBlock {
    mi_row : Int
    mi_col : Int
    width4 : Int
    height4 : Int
    block_width : Int
    block_height : Int
    size_index : Int
    avail_u : Bool
    avail_l : Bool
    skip : Int
    skip_mode : Bool
    segment_ref : Int
    segment_skip : Bool
    segment_global : Bool
    is_inter : Bool
    y_mode : Int
    ref_frame : Int
    ref_frame1 : Int
    mv_row : Int
    mv_col : Int
    mv_row1 : Int
    mv_col1 : Int
    interintra : Int
    interintra_mode : Int
    wedge_interintra : Int
    wedge_index_ii : Int
    compound_type : Int
    compound_idx : Int
    comp_group_idx : Int
    wedge_index : Int
    wedge_sign : Int
    mask_type : Int
    interp_vertical : Int
    interp_horizontal : Int
    ref_mv_idx : Int
    motion_mode : Int
    warp : Array[Av1WarpModel]
    }

    One block's decoded inter syntax, in the fields the reconstruction and the neighbour contexts of later blocks need.

    Av1InterFrame

    pub(all) struct Av1InterFrame {
    field : Av1MotionField
    frame : Av1MvFrame
    refs : Array[Av1RefFrame?]
    interpolation_filter : Int
    enable_dual_filter : Bool
    skip_mode_present : Bool
    skip_mode_frame : Array[Int]
    reference_select : Bool
    enable_interintra_compound : Bool
    ref_distances : Array[Int]
    enable_masked_compound : Bool
    enable_jnt_comp : Bool
    mi_cols : Int
    mi_rows : Int
    }

    The frame-level half of the inter state, shared by every tile of one frame. The motion field spans the whole coded frame, because a block's candidates are read from whatever was decoded before it in raster order.

    Av1LoopFilterBlockMap

    pub(all) struct Av1LoopFilterBlockMap {
    cols : Int
    rows : Int
    segment_ids : Array[Int]
    deltas : Array[Int]
    segmentation : Av1SegmentationParams
    }

    Filter metadata assembled on the frame's luma 4x4 grid. Each MI has four accumulated delta-LF values in Y-vertical, Y-horizontal, U, V order; a single-delta stream broadcasts its value to all four entries when decoded. Every covered MI retains its coding block's segment id and SB delta values.

    Av1LoopFilterConfig

    pub(all) struct Av1LoopFilterConfig {
    levels : Array[Int]
    sharpness : Int
    delta_enabled : Bool
    ref_deltas : Array[Int]
    mode_deltas : Array[Int]
    }

    Frame-level AV1 loop-filter parameters. Reduced still frames begin with default reference deltas; lossless frames omit this configuration entirely.

    Av1MotionField

    pub(all) struct Av1MotionField {
    cols : Int
    rows : Int
    width4 : Array[Int]
    height4 : Array[Int]
    y_modes : Array[Int]
    is_inter : Array[Bool]
    written : Array[Bool]
    skips : Array[Int]
    skip_modes : Array[Int]
    tx_width : Array[Int]
    tx_height : Array[Int]
    tx_types : Array[Int]
    interp_v : Array[Int]
    interp_h : Array[Int]
    refs : Array[Int]
    mv_rows : Array[Int]
    mv_cols : Array[Int]
    compound_idxs : Array[Int]
    comp_group_idxs : Array[Int]
    }

    Per-4x4 motion state of one frame. Every tile shares it: the candidate scans read neighbours decoded earlier in raster order, including the row above.

    Av1MotionFieldGrid

    pub(all) struct Av1MotionFieldGrid {
    refs : Array[Int]
    mv_rows : Array[Array[Int]]
    mv_cols : Array[Array[Int]]
    w8 : Int
    h8 : Int
    }

    The estimated grid: one pair of motion vectors per 8x8 luma cell per reference name, with av1_mv_invalid marking a cell no projection reached.

    Av1MotionRequest

    pub(all) struct Av1MotionRequest {
    reference : Av1RefFrame
    frame_width : Int
    frame_height : Int
    plane : Int
    x : Int
    y : Int
    width : Int
    height : Int
    mv_row : Int
    mv_col : Int
    filter_vertical : Int
    filter_horizontal : Int
    compound : Bool
    }

    Everything the kernel needs about one block's prediction. x/y are the block origin in the target plane's own units, and the motion vector is in eighth-pel of the reference frame.

    Av1MvBlock

    pub(all) struct Av1MvBlock {
    mi_row : Int
    mi_col : Int
    width4 : Int
    height4 : Int
    block_width : Int
    block_height : Int
    refs : Array[Int]
    tile_row_start : Int
    tile_row_end : Int
    tile_col_start : Int
    tile_col_end : Int
    }

    The block being predicted, plus the tile bounds that limit the scans.

    Av1MvFrame

    pub(all) struct Av1MvFrame {
    allow_high_precision_mv : Bool
    use_ref_frame_mvs : Bool
    force_integer_mv : Int
    is_motion_mode_switchable : Bool
    allow_warped_motion : Bool
    gm_type : Array[Int]
    gm_params : Array[Array[Int]]
    ref_frame_sign_bias : Array[Int]
    frame_width : Int
    frame_height : Int
    temporal : Av1MotionFieldGrid?
    }

    The frame-level state the candidate derivation reads. Naming it explicitly keeps the derivation independent of the rest of the frame frame.

    Av1MvStack

    pub(all) struct Av1MvStack {
    mv_rows : Array[Int]
    mv_cols : Array[Int]
    weights : Array[Int]
    count : Int
    newmv_count : Int
    found_match : Int
    close_matches : Int
    total_matches : Int
    zero_mv_context : Int
    newmv_context : Int
    refmv_context : Int
    drl_contexts : Array[Int]
    global_rows : Array[Int]
    global_cols : Array[Int]
    }

    The derived candidate stack and the contexts the inter mode tree consumes.

    Av1NativeFrame

    pub struct Av1NativeFrame {
    width : Int
    height : Int
    bit_depth : Int
    subsampling_x : Bool
    subsampling_y : Bool
    full_range : Bool
    matrix_coefficients : Int
    color_primaries : Int
    transfer_characteristics : Int
    planes : FixedArray[Av1PixelPlane]
    }

    A displayed AV1 picture after reconstruction, filters, super-resolution and signaled film grain, before color conversion or range expansion. planes contains Y alone for monochrome, otherwise Y, U, V. Matrix 0 identifies G, B, R in those same slots. Chroma dimensions round up on subsampled axes. There is no coded padding in any output plane.

    Color identifiers retain their bitstream values (2 means unspecified). AVIF output also applies the existing nclx metadata rules. Samples retain the original 8/10/12-bit precision and full/limited range. All buffers are independent of decoder references, other returned pictures and input data.

    Av1NativeFrame::copy_plane_into

    fn Av1NativeFrame::copy_plane_into(self : Av1NativeFrame, plane : Int, destination : FixedArray[Byte], row_bytes : Int, packing : PixelPacking, offset? : Int) -> Result[Unit, DecodeError]

    Copy one native plane into a reusable byte buffer. row_bytes and offset are in bytes; row padding and bytes outside the visible rectangle are untouched. Invalid arguments/samples reject before any destination write. This export does not expose or reuse the decoder's reference buffers.

    Av1NativeFrame::to_rgba16

    fn Av1NativeFrame::to_rgba16(self : Av1NativeFrame) -> Image16?

    Convert an owned native frame to opaque RGBA16 without decoding again. Nearest chroma and source color/transfer conventions match RGBA8; XYZ is converted to BT.709/sRGB. No HDR tone mapping is performed. Malformed caller-edited planes or unsupported color metadata return None.

    Av1NativeFrame::to_rgba16_into

    fn Av1NativeFrame::to_rgba16_into(self : Av1NativeFrame, destination : FixedArray[UInt16], row_stride : Int, offset? : Int) -> Result[Unit, DecodeError]

    Write straight RGBA16 directly into caller storage. Stride and offset count UInt16 channels, not bytes. Argument rejection leaves the destination intact; an unexpected numerical conversion failure may leave a partial destination. This removes output allocation; reconstruction/validation costs still apply.

    Av1NativeFrame::to_sdr_rgba16

    fn Av1NativeFrame::to_sdr_rgba16(self : Av1NativeFrame, options? : HdrToneMapOptions) -> Result[Image16, DecodeError]

    Convert an owned native AV1 frame to straight SDR RGBA16. PQ samples are interpreted as absolute luminance up to 10,000 nits; HLG samples use the BT.2100 scene-to-display OOTF. The conversion is performed directly from native-depth planes and returns a newly owned buffer.

    Av1Packet

    pub struct Av1Packet {
    data : Array[Byte]
    presentation_timestamp : Int64?
    decode_timestamp : Int64?
    duration : Int64?
    sync_sample : Bool?
    }

    One encoded temporal unit in container/decode order. Timestamps and duration use the enclosing track's timescale. Unknown timing/sync fields remain None instead of being inferred from presentation order. The payload is owned and may be passed to the existing AV1 video decoder.

    Av1PixelPlane

    pub struct Av1PixelPlane {
    width : Int
    height : Int
    data : FixedArray[Int]
    }

    One visible native-depth plane, tightly packed in row-major order. data[y * width + x] is an unshifted sample, not a serialized byte pair. On return, data.length() == width * height and every sample is in 0..<(1 << frame.bit_depth). The caller owns this mutable buffer.

    Av1PresentationPoint

    pub(all) enum Av1PresentationPoint {
    Empty
    Media(Av1RationalTime)
    End
    } derive(Eq,
    Debug
    )

    Mapping a movie presentation tick through an explicit MP4 edit list. Empty edits intentionally carry no media time. End is returned after the final edit; an edit list is interpreted as half-open movie intervals.

    Av1PresentationTimeline

    pub struct Av1PresentationTimeline {
    // private fields
    }

    An explicit presentation timeline for one demuxed track. An empty edit list is retained as raw media timing and does not synthesize a default MP4 edit. For an explicit edit list, movie ticks are mapped to media ticks with exact rational arithmetic and unit playback rate.

    Av1PresentationTimeline::edit_count

    fn Av1PresentationTimeline::edit_count(self : Av1PresentationTimeline) -> Int

    Av1PresentationTimeline::has_edits

    fn Av1PresentationTimeline::has_edits(self : Av1PresentationTimeline) -> Bool

    True when the source supplied an edit list. False means raw media timing is intentionally in force, even if the movie has a movie timescale.

    Av1PresentationTimeline::map_movie_time

    fn Av1PresentationTimeline::map_movie_time(self : Av1PresentationTimeline, movie_time : Int64) -> Result[Av1PresentationPoint, DecodeError]

    Map one movie tick to the exact media timestamp selected by the edit list. For an empty edit the result is Empty; after the final edit it is End. With no edits, the input is already a raw media tick and is returned as an integer rational, preserving the decoder's default media-timeline policy.

    Av1PresentationTimeline::media_timescale

    fn Av1PresentationTimeline::media_timescale(self : Av1PresentationTimeline) -> Int64

    Av1PresentationTimeline::movie_timescale

    fn Av1PresentationTimeline::movie_timescale(self : Av1PresentationTimeline) -> Int64?

    Av1PresentationTimeline::new

    Construct the explicit presentation mapping for a demuxed track. The demuxer already validates MP4 edit syntax and currently emits unit-rate edits; this layer validates the timescale relationship and retains each edit, including repeated and empty entries, without rewriting it.

    Av1QuantDeltas

    pub(all) struct Av1QuantDeltas {
    y_dc : Int
    u_dc : Int
    u_ac : Int
    v_dc : Int
    v_ac : Int
    }

    Per-plane quantizer deltas from quantization_params (AV1 §5.9.14). Each is added to base_q_idx and clamped to [0, 255] before the Dc/Ac_Qlookup read. Luma has a DC delta only; V reuses U's deltas unless the sequence enables separate_uv_delta_q, which codes its own pair.

    Av1QuantMatrix

    pub(all) struct Av1QuantMatrix {
    y : Int
    u : Int
    v : Int
    } derive(Eq,
    Debug
    )

    Per-plane matrix levels signalled by quantization_params. Levels 0..14 select the normative inverse matrix; level 15 selects uniform weights. U and V select independently from the common chroma matrix family.

    Av1RationalTime

    pub struct Av1RationalTime {
    numerator : Int64
    denominator : Int64
    } derive(Eq,
    Debug
    )

    An exact, unreduced rational timestamp. denominator is always positive; callers can compare two values by checked cross multiplication or retain the fraction when a movie tick does not land on an integer media tick.

    Av1RefFrame

    pub(all) struct Av1RefFrame {
    planes : Array[Array[Int]]
    coded_width : Int
    coded_height : Int
    width : Int
    height : Int
    sub_x : Int
    sub_y : Int
    bit_depth : Int
    frame_width : Int
    upscaled_width : Int
    frame_height : Int
    render_width : Int
    render_height : Int
    order_hint : Int
    frame_type : Int
    frame_id : Int
    order_hints : Array[Int]
    gm_params : Array[Array[Int]]
    loop_filter_ref_deltas : Array[Int]
    loop_filter_mode_deltas : Array[Int]
    cdfs : Av1FrameCdfs?
    mf_refs : Array[Int]
    mf_mvs : Array[Int]
    mi_cols : Int
    mi_rows : Int
    saved_order_hints : Array[Int]
    }

    One decoded picture in the reference buffer. Geometry is flattened out of the private Av1FramePlanes layout so this stays a describable public type.

    Av1ReferenceState

    pub(all) struct Av1ReferenceState {
    images : Array[Image?]
    frame_types : Array[Int]
    }

    Bounded eight-slot AV1 reference-frame image state.

    This stores decoded RGBA images for the show-existing branch. Inter prediction and motion compensation remain outside this small state layer.

    Av1RestorationConfig

    pub(all) struct Av1RestorationConfig {
    modes : Array[Av1RestorationType]
    unit_sizes : Array[Int]
    }

    Av1RestorationLayout

    pub(all) struct Av1RestorationLayout {
    config : Av1RestorationConfig
    frame_width : Int
    upscaled_width : Int
    frame_height : Int
    superres_denom : Int
    unit_cols : Array[Int]
    unit_rows : Array[Int]
    }

    Exact restoration grid for one frame, mirroring av1_alloc_restoration_struct. Plane dimensions exclude coded MI padding: luma is the full upscaled width and frame height, chroma rounds each up to its subsampled size. superres_denom is retained for the tile pre-SB corner mapping.

    Av1RestorationPlaneStripes

    pub(all) struct Av1RestorationPlaneStripes {
    count : Int
    width : Int
    height : Int
    starts : Array[Int]
    ends : Array[Int]
    top : Array[Array[Int]]
    bottom : Array[Array[Int]]
    }

    Saved deblocked rows at every internal stripe boundary of one plane. top[k] holds the two rows above stripe k's start (k >= 1) and bottom[k] the two rows at or after stripe k's end (non-last stripe), each as 2 * width native samples: the first saved row occupies [0, width), the second [width, 2*width). Outer boundaries are empty; the source view repeats the frame edge rows there. All rows are stored at the upscaled plane width.

    Av1RestorationSourceView

    pub(all) struct Av1RestorationSourceView {
    store : Av1RestorationStripeStore
    frame : Array[Array[Int]]
    frame_strides : Array[Int]
    }

    Immutable view over the post-CDEF/upscaled frame plus the saved stripe rows. Samples resolve under the stripe rules: inside the stripe read the frame; above an internal start read the saved top pair as [top0, top0, top1] at offsets -3, -2, -1; below a non-last end read the saved bottom pair as [bottom0, bottom1,bottom1] at offsets 0, 1, 2; at the frame top/bottom repeat the frame edge rows. x is clamped to the visible plane width, so coded MI padding never surfaces.

    Av1RestorationStripeStore

    pub(all) struct Av1RestorationStripeStore {
    planes : Array[Av1RestorationPlaneStripes]
    }

    Per-plane stripe stores for one frame.

    Av1RestorationTileState

    pub(all) struct Av1RestorationTileState {
    cdf_switchable : Array[Int]
    cdf_wiener : Array[Int]
    cdf_sgr : Array[Int]
    ref_wiener : Array[Array[Array[Int]]]
    ref_sgr : Array[Array[Int]]
    units : Array[Av1RestorationUnitRecord]
    }

    Per-tile loop-restoration entropy state. The three CDF rows are shared across planes (AV1 spec §5.11.57); coefficient references are separate per plane and filter family and survive superblock rows.

    Av1RestorationType

    pub(all) enum Av1RestorationType {
    Av1RestorationNone
    Av1RestorationWiener
    Av1RestorationSgrproj
    Av1RestorationSwitchable
    } derive(Eq,
    Debug
    )

    Av1RestorationUnit

    pub(all) enum Av1RestorationUnit {
    Av1RestorationUnitNone
    Av1RestorationUnitWiener(Array[Int], Array[Int])
    Av1RestorationUnitSgrproj(Int, Array[Int])
    }

    One decoded restoration unit. Wiener keeps the three coded taps per axis in read order (vertical first, then horizontal); SGR keeps the parameter version ep and the two coded projections.

    Av1RestorationUnitRecord

    pub(all) struct Av1RestorationUnitRecord {
    plane : Int
    unit_row : Int
    unit_col : Int
    unit : Av1RestorationUnit
    }

    One unit's decoded parameters with its global grid identity. Records are collected per tile and assembled into a frame unit map that must distinguish decoded-None units from unread positions.

    Av1SbBlock

    pub(all) struct Av1SbBlock {
    row : Int
    col : Int
    width : Int
    height : Int
    }

    A coding-block rectangle in pixels. Dimensions retain the coded block size at frame edges; sample reconstruction is responsible for clipping.

    Av1SbPartition

    pub(all) enum Av1SbPartition {
    Av1SbPartitionNone
    Av1SbPartitionHorz
    Av1SbPartitionVert
    Av1SbPartitionSplit
    Av1SbPartitionHorzA
    Av1SbPartitionHorzB
    Av1SbPartitionVertA
    Av1SbPartitionVertB
    Av1SbPartitionHorz4
    Av1SbPartitionVert4
    }

    AV1 partition symbols. Only SPLIT creates more partition syntax; every other symbol produces one or more terminal coding blocks.

    Av1SbPartitionNode

    pub(all) struct Av1SbPartitionNode {
    row : Int
    col : Int
    size : Int
    frame_width : Int
    frame_height : Int
    }

    A square node at which AV1 partition syntax is evaluated.

    Av1SbPartitionNode::edge_forces_split

    fn Av1SbPartitionNode::edge_forces_split(self : Av1SbPartitionNode) -> Bool

    True when the node has no complete lower or right half. AV1 forces a split in this case, avoiding a partition symbol that would address pixels outside the frame.

    Av1SbPartitionNode::has_cols

    fn Av1SbPartitionNode::has_cols(self : Av1SbPartitionNode) -> Bool

    Whether the right half of this block lies inside the frame (AV1 hasCols).

    Av1SbPartitionNode::has_rows

    fn Av1SbPartitionNode::has_rows(self : Av1SbPartitionNode) -> Bool

    Whether the lower half of this block lies inside the frame (AV1 hasRows).

    Av1SegmentationParams

    pub(all) struct Av1SegmentationParams {
    enabled : Bool
    update_map : Bool
    temporal_update : Bool
    update_data : Bool
    feature_enabled : Array[Array[Bool]]
    feature_data : Array[Array[Int]]
    seg_id_pre_skip : Bool
    last_active_seg_id : Int
    }

    The parsed segmentation_params (AV1 §6.10.9). enabled without a map update or an active feature changes nothing about the decode.

    Av1SequenceInfo

    pub(all) struct Av1SequenceInfo {
    profile : Int
    width : Int
    height : Int
    bit_depth : Int
    monochrome : Bool
    subsampling_x : Bool
    subsampling_y : Bool
    reduced_still_picture_header : Bool
    use_128x128_superblock : Bool
    enable_filter_intra : Bool
    enable_intra_edge_filter : Bool
    enable_superres : Bool
    enable_cdef : Bool
    enable_restoration : Bool
    full_range : Bool
    separate_uv_delta_q : Bool
    film_grain_params_present : Bool
    color_primaries : Int
    transfer_characteristics : Int
    matrix_coefficients : Int
    still_picture : Bool
    enable_order_hint : Bool
    order_hint_bits : Int
    enable_ref_frame_mvs : Bool
    enable_warped_motion : Bool
    enable_dual_filter : Bool
    enable_jnt_comp : Bool
    enable_masked_compound : Bool
    enable_interintra_compound : Bool
    seq_force_screen_content_tools : Int
    seq_force_integer_mv : Int
    frame_id_numbers_present : Bool
    delta_frame_id_length_minus_2 : Int
    additional_frame_id_length_minus_1 : Int
    decoder_model_info_present : Bool
    equal_picture_interval : Bool
    buffer_delay_length_minus_1 : Int
    buffer_removal_time_length_minus_1 : Int
    frame_presentation_time_length_minus_1 : Int
    operating_points_cnt_minus_1 : Int
    operating_point_idc : Array[Int]
    decoder_model_present_for_this_op : Array[Bool]
    frame_width_bits_minus_1 : Int
    frame_height_bits_minus_1 : Int
    }

    Parsed AV1 sequence configuration shared by still and video decoding.

    Av1ShowExistingFrameConfig

    pub(all) struct Av1ShowExistingFrameConfig {
    decoder_model_info_present : Bool
    equal_picture_interval : Bool
    frame_presentation_time_length_minus_1 : Int
    frame_id_numbers_present : Bool
    additional_frame_id_len_minus1 : Int
    delta_frame_id_length_minus2 : Int
    reference_frame_types : Array[Int]
    }

    Sequence-level syntax needed by show_existing_frame (§5.9.2).

    Av1ShowExistingFrameEnvelope

    pub(all) struct Av1ShowExistingFrameEnvelope {
    show_existing_frame : Bool
    frame_to_show_map_idx : Int
    reference_frame_type : Int
    frame_presentation_time : Int64?
    display_frame_id : Int?
    header_bits : Int
    header_bytes : Int
    }

    Parsed fields from an AV1 show_existing_frame header.

    frame_presentation_time and display_frame_id are optional because the corresponding sequence features are optional. reference_frame_type is metadata from the caller's reference-frame state; it does not decode any pixels.

    Av1Stage1Input

    pub(all) struct Av1Stage1Input {
    width : Int
    frame_width : Int
    superres_denom : Int
    height : Int
    bit_depth : Int
    monochrome : Bool
    header_bytes : Int
    base_q_idx : Int
    disable_cdf_update : Bool
    allow_screen_content_tools : Bool
    tx_mode_select : Bool
    reduced_tx_set : Bool
    cdef : Av1CdefConfig?
    loop_filter : Av1LoopFilterConfig?
    restoration : Av1RestorationConfig?
    tile_cols : Int
    tile_rows : Int
    tile_cols_log2 : Int
    tile_rows_log2 : Int
    tile_col_starts_sb : Array[Int]
    tile_row_starts_sb : Array[Int]
    tile_size_bytes : Int
    enable_filter_intra : Bool
    enable_intra_edge_filter : Bool
    full_range : Bool
    matrix_coefficients : Int
    use_128x128_superblock : Bool
    tile_payload : Array[Byte]
    film_grain : Av1FilmGrainParams?
    quant_deltas : Av1QuantDeltas
    }

    The bounded input handed to the next AV1 tile-decoding stage. This is a data boundary rather than an image: tile bytes are still entropy-coded and must be reconstructed before an Image exists.

    Av1StreamBatch

    pub struct Av1StreamBatch {
    frames : Array[Av1NativeFrame]
    status : Av1StreamStatus
    }

    Every picture owns its buffers. Always consume frames, including when status is Finished. FramesReady may coexist with a pending partial unit.

    Av1StreamDecoder

    pub struct Av1StreamDecoder {
    // private fields
    }

    Low-overhead AV1 byte-stream adapter. Temporal delimiters close units; finish() or end_temporal_unit() closes an externally delimited final unit. No network/file IO is performed. A failure is sticky until reset().

    Av1StreamDecoder::end_temporal_unit

    fn Av1StreamDecoder::end_temporal_unit(self : Av1StreamDecoder) -> Result[Av1StreamBatch, DecodeError]

    Explicit sample/TU boundary for inputs whose transport supplies framing instead of temporal-delimiter OBUs. References survive between samples.

    Av1StreamDecoder::feed

    fn Av1StreamDecoder::feed(self : Av1StreamDecoder, chunk : Array[Byte]) -> Result[Av1StreamBatch, DecodeError]

    max_input_bytes caps each supplied chunk and complete temporal unit. The retained buffer allows sixteen extra bytes to recognize the next delimiter. Picture/pixel budgets are shared by all units decoded during this call.

    Av1StreamDecoder::finish

    Complete the input, rejecting truncated final OBUs. Idempotent after success.

    Av1StreamDecoder::new

    fn Av1StreamDecoder::new(limits? : DecodeLimits, allow_monochrome? : Bool) -> Result[Av1StreamDecoder, DecodeError]

    Av1StreamDecoder::pending_bytes

    fn Av1StreamDecoder::pending_bytes(self : Av1StreamDecoder) -> Int

    Retained compressed bytes, including at most sixteen lookahead header bytes.

    Av1StreamDecoder::reset

    fn Av1StreamDecoder::reset(self : Av1StreamDecoder) -> Unit

    Av1StreamStatus

    pub(all) enum Av1StreamStatus {
    NeedMoreInput
    FramesReady
    Finished
    } derive(Eq,
    Debug
    )

    Av1TilePayload

    pub(all) struct Av1TilePayload {
    index : Int
    row : Int
    col : Int
    offset : Int
    length : Int
    bytes : Array[Byte]
    }

    A validated tile payload and its position in a row-major tile group.

    Av1TrackEdit

    pub struct Av1TrackEdit {
    duration : Int64
    media_time : Int64
    media_rate : Int
    }

    An ISO BMFF movie edit. duration uses movie_timescale; media_time uses the track timescale and -1 denotes an empty edit. media_rate is signed 16.16 fixed-point (65536 means normal playback). Demuxing retains edits separately so that encoded preroll/reference packets are never discarded.

    Av1TxDepthState

    pub struct Av1TxDepthState {
    cdf8 : Array[Array[Int]]
    cdf16 : Array[Array[Int]]
    cdf32 : Array[Array[Int]]
    cdf64 : Array[Array[Int]]
    }

    Mutable intra tx_depth CDFs retained for the lifetime of a tile. Each of the four maximum-depth categories has three neighbour contexts; these tables are independent of the inter variable-transform split contexts.

    Av1TxLeaf

    pub(all) struct Av1TxLeaf {
    node : Av1TxNode
    depth : Int
    }

    A transform-tree leaf together with the depth selected by the frame's tx_depth symbol. AV1 signals one depth for an intra block and derives the geometry by repeatedly applying the split transform size; keeping the depth on each leaf makes that relationship explicit for residual readers.

    Av1TxNode

    pub(all) struct Av1TxNode {
    row : Int
    col : Int
    width : Int
    height : Int
    }

    A rectangular transform node in pixel coordinates.

    Av1TxPartition

    pub(all) enum Av1TxPartition {
    Av1TxNone
    Av1TxSplit
    Av1TxHorz
    Av1TxVert
    }

    AV1 transform-tree geometry for square and supported rectangular leaves.

    This stage models transform partition geometry independently from entropy symbols. Leaves are emitted in raster order and are later consumed by the coefficient decoder.

    Av1TxTraversalState

    pub struct Av1TxTraversalState {
    cols : Int
    rows : Int
    above_width : Array[Int]
    left_height : Array[Int]
    }

    Neighbour transform dimensions collected while walking a tile in raster order. Entries are indexed in 4x4 units; -1 means that no block has been decoded at that edge yet. Keeping unavailable edges explicit avoids manufacturing neighbour sizes for the first block in a tile.

    Av1TxType

    pub(all) enum Av1TxType {
    Av1TxDctDct
    Av1TxAdstDct
    Av1TxDctAdst
    Av1TxAdstAdst
    Av1TxFlipadstDct
    Av1TxDctFlipadst
    Av1TxFlipadstFlipadst
    Av1TxAdstFlipadst
    Av1TxFlipadstAdst
    Av1TxIdentityIdentity
    Av1TxIdentityDct
    Av1TxDctIdentity
    Av1TxVerticalDct
    Av1TxHorizontalDct
    Av1TxVerticalAdst
    Av1TxHorizontalAdst
    Av1TxVerticalFlipadst
    Av1TxHorizontalFlipadst
    }

    Av1VideoDecoder

    pub(all) struct Av1VideoDecoder {
    sequence : Av1SequenceInfo?
    map : Av1FrameMap
    }

    A decoder that keeps presentation state across temporal units.

    Av1WarpModel

    pub(all) struct Av1WarpModel {
    matrix : Array[Int]
    coefficients : Array[Int]
    }

    A derived warp model: the fitted matrix plus the four coefficients the prediction consumes. A model this decoder cannot represent (a shear, or a singular fit) is not built at all - the block then decodes with its own motion vector, which is what AV1 specifies for an identity model.

    AvifAlphaExtent

    pub struct AvifAlphaExtent {
    offset : Int
    length : Int
    construction_method : Int
    }

    Bounded metadata for an AVIF auxiliary alpha item.

    This API only identifies the auxiliary item and validates its BMFF extents. Pixel reconstruction is performed by avif_decode_alpha, including grids; native alpha precision is retained until the assembled plane is normalized.

    AvifAlphaItemDescriptor

    pub struct AvifAlphaItemDescriptor {
    item_id : Int
    width : Int
    height : Int
    bit_depth : Int
    auxiliary_property : Bool
    premultiplied : Bool
    extents : Array[AvifAlphaExtent]
    }

    A validated auxl/auxC item descriptor extracted from an AVIF container.

    AvifAnimationDecoder

    pub struct AvifAnimationDecoder {
    // private fields
    }

    A lazy, independently owned AVIF animation session. Container/timing and OBU envelopes are checked at construction; entropy/pixels are checked only when consumed. Returned pictures survive next_frame(), seek_frame(), reset().

    AvifAnimationDecoder::frame_count

    fn AvifAnimationDecoder::frame_count(self : AvifAnimationDecoder) -> Int

    AvifAnimationDecoder::frame_timing

    fn AvifAnimationDecoder::frame_timing(self : AvifAnimationDecoder, index : Int) -> Result[AvifAnimationFrame, DecodeError]

    AvifAnimationDecoder::is_keyframe

    fn AvifAnimationDecoder::is_keyframe(self : AvifAnimationDecoder, index : Int) -> Result[Bool, DecodeError]

    AvifAnimationDecoder::metadata

    AvifAnimationDecoder::nearest_keyframe

    fn AvifAnimationDecoder::nearest_keyframe(self : AvifAnimationDecoder, index : Int) -> Result[Int?, DecodeError]

    Nearest conservatively indexed independent sample, shared by color/alpha. None means seeking must replay from sample zero to preserve dependencies.

    AvifAnimationDecoder::new

    fn AvifAnimationDecoder::new(data : Array[Byte], limits? : DecodeLimits) -> Result[AvifAnimationDecoder, DecodeError]

    AvifAnimationDecoder::next_frame

    Ok(None) is end of sequence. A later corrupt sample can fail after earlier frames were delivered; failure remains sticky until reset(). Work limits apply to this operation, shared by the color and alpha reconstruction.

    AvifAnimationDecoder::position

    fn AvifAnimationDecoder::position(self : AvifAnimationDecoder) -> Int

    AvifAnimationDecoder::reset

    fn AvifAnimationDecoder::reset(self : AvifAnimationDecoder) -> Unit

    AvifAnimationDecoder::seek_frame

    fn AvifAnimationDecoder::seek_frame(self : AvifAnimationDecoder, index : Int) -> Result[AvifNativeAnimationFrame, DecodeError]

    Decode from the nearest common independent key sample (or zero). All replay work counts against one operation budget. The next read returns index + 1.

    AvifAnimationDescriptor

    pub struct AvifAnimationDescriptor {
    timescale : Int
    frames : Array[AvifAnimationFrame]
    }

    AvifAnimationFrame

    pub struct AvifAnimationFrame {
    index : Int
    offset : Int
    length : Int
    timestamp : Int
    duration : Int
    timescale : Int
    }

    AvifAnimationPixelFrame

    pub struct AvifAnimationPixelFrame {
    index : Int
    timestamp : Int
    duration : Int
    timescale : Int
    image : Image
    }

    A successfully decoded animation sample with its track timing.

    AvifAnimationPixels

    pub struct AvifAnimationPixels {
    timescale : Int
    frames : Array[AvifAnimationPixelFrame]
    }

    Decoded animation samples. Samples are supplied in the order returned by avif_animation_descriptor; each sample is passed to the pure AV1 decoder.

    AvifCleanAperture

    pub(all) struct AvifCleanAperture {
    width_n : Int64
    width_d : Int64
    height_n : Int64
    height_d : Int64
    horizontal_n : Int64
    horizontal_d : Int64
    vertical_n : Int64
    vertical_d : Int64
    } derive(Eq,
    Debug
    )

    Exact clap fractions. Sizes/denominators are unsigned 32-bit values; offsets are signed 32-bit numerators. No floating-point rounding is applied.

    AvifContainer

    pub struct AvifContainer {
    width : Int
    height : Int
    bit_depth : Int
    monochrome : Bool
    subsampling_x : Bool
    subsampling_y : Bool
    yuv420 : Bool
    has_alpha : Bool
    av1c : Array[Byte]
    payload : Array[Byte]
    operating_point : Int
    spatial_layer : Int?
    nclx_primaries : Int?
    nclx_transfer : Int?
    nclx_matrix : Int?
    nclx_full_range : Bool?
    }

    AvifDisplayTransform

    pub(all) enum AvifDisplayTransform {
    Crop(AvifCleanAperture)
    Rotate(Int)
    Mirror(Int)
    } derive(Eq,
    Debug
    )

    Rotation is anticlockwise in quarter turns. Mirror mode 0 exchanges top and bottom; mode 1 exchanges left and right (HEIF mode, not the old axis).

    AvifGridDescriptor

    pub struct AvifGridDescriptor {
    item_id : Int
    rows : Int
    columns : Int
    output_width : Int
    output_height : Int
    tiles : Array[AvifGridTile]
    }

    AvifGridExtent

    pub struct AvifGridExtent {
    offset : Int
    length : Int
    construction_method : Int
    }

    AvifGridTile

    pub struct AvifGridTile {
    item_id : Int
    extents : Array[AvifGridExtent]
    }

    Bounded AVIF grid and animation metadata extraction.

    This module only parses ISO BMFF structure and returns item/sample extents. It never invokes a browser codec or an external decoder. Pixel reconstruction remains in the AV1 pipeline; callers can feed the returned extents to it.

    AvifMetadata

    pub struct AvifMetadata {
    primary_item_id : Int?
    track_id : Int?
    icc : FixedArray[Byte]?
    exif : FixedArray[Byte]?
    exif_tiff_offset : Int?
    xmp : FixedArray[Byte]?
    pixel_aspect_ratio : (Int64, Int64)?
    transforms : FixedArray[AvifDisplayTransform]
    }

    Owned metadata for a primary item or a selected picture track. Exif is the item payload after its four-byte offset field; exif_tiff_offset locates TIFF inside it. ICC/Exif/XMP are opaque bytes, not an ICC engine or an XML parser. Transforms retain property-association order. Pixel aspect ratio is metadata only; applying raster transforms does not resample nonsquare pixels.

    AvifMetadata::apply_rgba16

    fn AvifMetadata::apply_rgba16(self : AvifMetadata, image : Image16) -> Result[Image16, DecodeError]

    Explicit, exact raster permutation/crop. Color and alpha move together; ICC, Exif orientation and pixel aspect ratio are not applied implicitly. The result owns a new buffer even for an empty transform chain.

    AvifMetadata::apply_rgba8

    fn AvifMetadata::apply_rgba8(self : AvifMetadata, image : Image) -> Result[Image, DecodeError]

    AvifMetadata::display_size

    fn AvifMetadata::display_size(self : AvifMetadata, width : Int, height : Int) -> Result[(Int, Int), DecodeError]

    Validate the transform chain and report resulting raster dimensions.

    AvifMetadata::resample_rgba16

    fn AvifMetadata::resample_rgba16(self : AvifMetadata, image : Image16, width : Int, height : Int) -> Result[Image16, DecodeError]

    Fractional crop/resize/display transform for straight RGBA16.

    AvifMetadata::resample_rgba8

    fn AvifMetadata::resample_rgba8(self : AvifMetadata, image : Image, width : Int, height : Int) -> Result[Image, DecodeError]

    Fractional crop/resize/display transform for straight RGBA8.

    The output owns a fresh buffer. If the transform chain is an exact integer crop/permutation and the requested dimensions match it, this uses the exact display path so identity and rotation/mirror cases retain their byte-for-byte behavior.

    AvifNativeAnimation

    pub struct AvifNativeAnimation {
    timescale : Int
    frames : FixedArray[AvifNativeAnimationFrame]
    }

    A completely decoded AVIF animation in presentation order. On return, frames is nonempty, index equals the array position, durations are positive, and timestamps are contiguous from zero, in units of timescale per second. The total duration fits in a positive Int. All frames share this timescale.

    AvifNativeAnimation::frame_at

    fn AvifNativeAnimation::frame_at(self : AvifNativeAnimation, timestamp : Int) -> AvifNativeAnimationFrame?

    Select a frame without decoding again. timestamp uses this animation's timescale, not milliseconds, and loops modulo the total duration. Intervals include their start and exclude their end; negative timestamps or caller-reordered/noncontiguous timing return None. Returns the stored frame: its buffers alias frames[index], with no copy.

    AvifNativeAnimationFrame

    pub struct AvifNativeAnimationFrame {
    index : Int
    timestamp : Int
    duration : Int
    timescale : Int
    image : AvifNativeImage
    }

    One presented animation sample with timing in the primary track's units. Color and alpha retain their original precision, range and prem association. Its buffers are independent of every other decoded sample and input data.

    AvifNativeImage

    pub struct AvifNativeImage {
    color : Av1NativeFrame
    alpha : Av1NativeFrame?
    premultiplied : Bool
    }

    An AVIF image: a primary image/grid or an animation sample, with validated alpha. Alpha, when present, is a single native-depth plane with the same size and bit depth as color. Its own full_range flag describes its raw samples; limited-range alpha has not been expanded. None means opaque. premultiplied reports the color-to-alpha prem association. Color samples have not been unpremultiplied. Use avif_decode_rgba for straight RGBA8.

    AvifNativeImage::to_rgba16

    fn AvifNativeImage::to_rgba16(self : AvifNativeImage) -> Image16?

    Convert a static image or animation sample to straight RGBA16. Limited alpha is expanded at its original depth; prem is undone with native alpha before final RGB16 rounding. This does not quantize through RGBA8. The returned buffer shares no mutable data with this image or prior outputs.

    AvifNativeImage::to_rgba16_into

    fn AvifNativeImage::to_rgba16_into(self : AvifNativeImage, destination : FixedArray[UInt16], row_stride : Int, offset? : Int) -> Result[Unit, DecodeError]

    Native alpha and premultiplication use the same precision and order as to_rgba16(). Row padding and surrounding destination channels are untouched.

    AvifNativeImage::to_sdr_rgba16

    fn AvifNativeImage::to_sdr_rgba16(self : AvifNativeImage, options? : HdrToneMapOptions) -> Result[Image16, DecodeError]

    Convert an AVIF native image to straight SDR RGBA16, preserving native alpha precision and undoing color premultiplication before tone mapping.

    DecodeError

    pub struct DecodeError {
    kind : DecodeErrorKind
    byte_offset : Int64?
    context : String
    message : String
    } derive(Eq,
    Debug
    )

    Zero-based checked field or failing payload start, not a bit-level entropy position. Incremental input uses absolute stream offsets. None is used when an assembled AVIF payload cannot be mapped to one container byte location.

    DecodeErrorKind

    pub(all) enum DecodeErrorKind {
    InvalidData
    TruncatedInput
    Unsupported
    MissingSequence
    MissingReference
    LimitExceeded
    InvalidState
    InvalidBuffer
    NoPresentation
    } derive(Eq,
    Debug
    )

    InvalidData includes failures for which the decoder cannot identify a more specific cause. Unsupported is never guessed from an opaque syntax failure.

    DecodeLimits

    pub(all) struct DecodeLimits {
    max_input_bytes : Int
    max_frame_pixels : Int
    max_total_pixels : Int
    max_frames : Int
    }

    Optional work limits for a single high-level decode call. max_input_bytes also caps each assembled item/sample payload, including repeated extents. Pixel counts are luma-grid areas, not bytes or a process-memory guarantee. Every reconstructed or show-existing picture counts, including hidden pictures and alpha tracks. Grid canvases also consume pixels. Reference state persists between video calls, but the work budget restarts for each call. All fields must be positive; max_frame_pixels cannot exceed 100,000,000.

    DecodeLimits::av1_decode

    fn DecodeLimits::av1_decode(self : DecodeLimits, data : Array[Byte]) -> Image?

    Apply this policy to av1_decode; None also reports invalid/exceeded limits.

    DecodeLimits::av1_decode_alpha

    fn DecodeLimits::av1_decode_alpha(self : DecodeLimits, data : Array[Byte]) -> Array[Byte]?

    Apply this policy to av1_decode_alpha; None also reports invalid/exceeded limits.

    DecodeLimits::av1_decode_native

    fn DecodeLimits::av1_decode_native(self : DecodeLimits, data : Array[Byte]) -> Av1NativeFrame?

    Apply this policy to av1_decode_native; None also reports invalid/exceeded limits.

    DecodeLimits::av1_decode_rgba16

    fn DecodeLimits::av1_decode_rgba16(self : DecodeLimits, data : Array[Byte]) -> Image16?

    Apply this policy to av1_decode_rgba16; None also reports invalid/exceeded limits.

    DecodeLimits::av1_video_decode_frame

    fn DecodeLimits::av1_video_decode_frame(self : DecodeLimits, decoder : Av1VideoDecoder, data : Array[Byte], allow_monochrome? : Bool) -> Image?

    Apply this policy to av1_video_decode_frame; None also reports invalid/exceeded limits.

    DecodeLimits::av1_video_decode_temporal_unit

    fn DecodeLimits::av1_video_decode_temporal_unit(self : DecodeLimits, decoder : Av1VideoDecoder, data : Array[Byte], allow_monochrome? : Bool) -> Array[Image]?

    Apply this policy to av1_video_decode_temporal_unit; None also reports invalid/exceeded limits.

    DecodeLimits::av1_video_decode_temporal_unit_native

    fn DecodeLimits::av1_video_decode_temporal_unit_native(self : DecodeLimits, decoder : Av1VideoDecoder, data : Array[Byte], allow_monochrome? : Bool) -> Array[Av1NativeFrame]?

    Apply this policy to av1_video_decode_temporal_unit_native; None also reports invalid/exceeded limits.

    DecodeLimits::avif_alpha_item_descriptor

    fn DecodeLimits::avif_alpha_item_descriptor(self : DecodeLimits, data : Array[Byte]) -> AvifAlphaItemDescriptor?

    Apply this policy to avif_alpha_item_descriptor; None also reports invalid/exceeded limits.

    DecodeLimits::avif_alpha_item_payload

    fn DecodeLimits::avif_alpha_item_payload(self : DecodeLimits, data : Array[Byte]) -> Array[Byte]?

    Apply this policy to avif_alpha_item_payload; None also reports invalid/exceeded limits.

    DecodeLimits::avif_container_parse

    fn DecodeLimits::avif_container_parse(self : DecodeLimits, data : Array[Byte]) -> AvifContainer?

    Apply this policy to avif_container_parse; None also reports invalid/exceeded limits.

    DecodeLimits::avif_decode

    fn DecodeLimits::avif_decode(self : DecodeLimits, data : Array[Byte]) -> Image?

    Apply this policy to avif_decode; None also reports invalid/exceeded limits.

    DecodeLimits::avif_decode_alpha

    fn DecodeLimits::avif_decode_alpha(self : DecodeLimits, data : Array[Byte]) -> Array[Byte]?

    Apply this policy to avif_decode_alpha; None also reports invalid/exceeded limits.

    DecodeLimits::avif_decode_animation

    fn DecodeLimits::avif_decode_animation(self : DecodeLimits, data : Array[Byte]) -> AvifAnimationPixels?

    Apply this policy to avif_decode_animation; None also reports invalid/exceeded limits.

    DecodeLimits::avif_decode_animation_frame

    fn DecodeLimits::avif_decode_animation_frame(self : DecodeLimits, data : Array[Byte], timestamp : Int) -> Image?

    Apply this policy to avif_decode_animation_frame; None also reports invalid/exceeded limits.

    DecodeLimits::avif_decode_animation_frames

    fn DecodeLimits::avif_decode_animation_frames(self : DecodeLimits, descriptor : AvifAnimationDescriptor, samples : Array[Array[Byte]]) -> AvifAnimationPixels?

    Apply this policy to avif_decode_animation_frames; None also reports invalid/exceeded limits.

    DecodeLimits::avif_decode_animation_native

    fn DecodeLimits::avif_decode_animation_native(self : DecodeLimits, data : Array[Byte]) -> AvifNativeAnimation?

    Apply this policy to avif_decode_animation_native; None also reports invalid/exceeded limits.

    DecodeLimits::avif_decode_animation_samples

    fn DecodeLimits::avif_decode_animation_samples(self : DecodeLimits, timescale : Int, timestamps : Array[Int], durations : Array[Int], samples : Array[Array[Byte]]) -> AvifAnimationPixels?

    Apply this policy to avif_decode_animation_samples; None also reports invalid/exceeded limits.

    DecodeLimits::avif_decode_grid

    fn DecodeLimits::avif_decode_grid(self : DecodeLimits, data : Array[Byte], descriptor : AvifGridDescriptor) -> Image?

    Apply this policy to avif_decode_grid; None also reports invalid/exceeded limits.

    DecodeLimits::avif_decode_grid_auto

    fn DecodeLimits::avif_decode_grid_auto(self : DecodeLimits, data : Array[Byte]) -> Image?

    Apply this policy to avif_decode_grid_auto; None also reports invalid/exceeded limits.

    DecodeLimits::avif_decode_grid_tiles

    fn DecodeLimits::avif_decode_grid_tiles(self : DecodeLimits, rows : Int, columns : Int, output_width : Int, output_height : Int, samples : Array[Array[Byte]]) -> Image?

    Apply this policy to avif_decode_grid_tiles; None also reports invalid/exceeded limits.

    DecodeLimits::avif_decode_native

    fn DecodeLimits::avif_decode_native(self : DecodeLimits, data : Array[Byte]) -> AvifNativeImage?

    Apply this policy to avif_decode_native; None also reports invalid/exceeded limits.

    DecodeLimits::avif_decode_rgba

    fn DecodeLimits::avif_decode_rgba(self : DecodeLimits, data : Array[Byte]) -> Image?

    Apply this policy to avif_decode_rgba; None also reports invalid/exceeded limits.

    DecodeLimits::avif_decode_rgba16

    fn DecodeLimits::avif_decode_rgba16(self : DecodeLimits, data : Array[Byte]) -> Image16?

    Apply this policy to avif_decode_rgba16; None also reports invalid/exceeded limits.

    DecodeLimits::default

    fn DecodeLimits::default() -> DecodeLimits

    An opt-in starting policy: 64 MiB input, 16 Mi pixels per padded picture, 128 Mi cumulative pixels and 256 pictures. Ordinary free functions preserve their original policy. Applications can construct stricter limits.

    HdrToneMapOptions

    pub(all) struct HdrToneMapOptions {
    peak_luminance_nits : Double
    reference_white_nits : Double
    exposure_stops : Double
    }

    Parameters for to_sdr_rgba16.

    peak_luminance_nits is the nominal display peak used for HLG's reference display OOTF and as the extended-Reinhard shoulder. reference_white_nits is the linear-light normalization anchor. Both values are absolute cd/m2 (nits), and reference_white_nits must not exceed the peak. exposure_stops is a base-2 gain applied before tone mapping. The default is a 1000-nit HLG reference-display peak and tone-map shoulder, with a 100-nit reference white and zero exposure. The output remains normalized SDR.

    HdrToneMapOptions::default

    IccProfile

    pub struct IccProfile {
    // private fields
    }

    A validated, immutable ICC input/display profile.

    IccProfile::apply_rgba16

    fn IccProfile::apply_rgba16(self : IccProfile, image : Image16) -> Result[Image16, DecodeError]

    Convert straight RGBA16 to a fresh sRGB RGBA16 image, preserving alpha.

    IccProfile::apply_rgba16_with_options

    fn IccProfile::apply_rgba16_with_options(self : IccProfile, image : Image16, options : IccTransformOptions) -> Result[Image16, DecodeError]

    Convert straight RGBA16 using an explicitly selected ICC policy.

    IccProfile::apply_rgba8

    fn IccProfile::apply_rgba8(self : IccProfile, image : Image) -> Result[Image, DecodeError]

    Convert straight RGBA8 to a fresh sRGB RGBA8 image, preserving alpha.

    IccProfile::apply_rgba8_with_options

    fn IccProfile::apply_rgba8_with_options(self : IccProfile, image : Image, options : IccTransformOptions) -> Result[Image, DecodeError]

    Convert straight RGBA8 using an explicitly selected ICC policy.

    IccProfile::parse

    fn IccProfile::parse(bytes : Array[Byte]) -> Result[IccProfile, DecodeError]

    Parse and validate a pure RGB or Gray ICC v2/v4 input/display profile.

    IccRenderingIntent

    pub(all) enum IccRenderingIntent {
    Perceptual
    RelativeColorimetric
    Saturation
    AbsoluteColorimetric
    }

    ICC rendering intents understood by the policy-aware entry points.

    IccTransformOptions

    pub struct IccTransformOptions {
    intent : IccRenderingIntent
    black_point_compensation : Bool
    }

    Rendering and black-point policy for an ICC conversion.

    The legacy apply_rgba8 and apply_rgba16 methods use RelativeColorimetric with black-point compensation disabled. Use this value with the *_with_options methods to select an ICC intent and, when requested, LittleCMS-compatible black-point compensation.

    IccTransformOptions::new

    fn IccTransformOptions::new(intent : IccRenderingIntent, black_point_compensation : Bool) -> IccTransformOptions

    IccTransformOptions::relative_colorimetric

    fn IccTransformOptions::relative_colorimetric() -> IccTransformOptions

    Image

    pub(all) struct Image {
    width : Int
    height : Int
    data : FixedArray[Byte]
    }

    An 8-bit RGBA raster image.

    Pixels are stored row-major in data, four bytes per pixel in R, G, B, A order, so data.length() == width * height * 4. This layout matches the browser ImageData.data buffer, which lets a <canvas> hand its pixels to the library without any conversion step.

    Image::copy

    fn Image::copy(self : Image) -> Image

    Returns a deep copy that shares no mutable state with the original.

    Image::from_bytes

    fn Image::from_bytes(width : Int, height : Int, data : FixedArray[Byte]) -> Image

    Wraps an existing RGBA buffer. Aborts if data does not hold exactly width * height * 4 bytes, so a malformed buffer fails fast instead of producing silently corrupt output.

    Image::get_pixel

    fn Image::get_pixel(self : Image, x : Int, y : Int) -> (Byte, Byte, Byte, Byte)

    Reads the (R, G, B, A) channels of the pixel at (x, y).

    Aborts when the coordinates are outside the image bounds or when a host supplies an Image record whose backing buffer does not match its size.

    Image::new

    fn Image::new(width : Int, height : Int) -> Image

    Creates a fully transparent black image of the given size.

    Image::pixel_count

    fn Image::pixel_count(self : Image) -> Int

    The number of pixels (not bytes) in the image.

    Image::set_pixel

    fn Image::set_pixel(self : Image, x : Int, y : Int, r : Byte, g : Byte, b : Byte, a : Byte) -> Unit

    Writes the (R, G, B, A) channels of the pixel at (x, y).

    Aborts when the coordinates are outside the image bounds or when a host supplies an Image record whose backing buffer does not match its size.

    Image16

    pub struct Image16 {
    width : Int
    height : Int
    data : FixedArray[UInt16]
    }

    Straight RGBA UNORM16, row-major R/G/B/A, four UInt16 samples per pixel. Each channel spans 0..65535; alpha 65535 is opaque. This is an integer buffer, not half-float or serialized bytes. The caller owns its data.

    Image16::copy_bytes_into

    fn Image16::copy_bytes_into(self : Image16, destination : FixedArray[Byte], row_bytes : Int, big_endian? : Bool, offset? : Int) -> Result[Unit, DecodeError]

    Serialize straight UNORM16 channels, preserving the exact values.

    PixelPacking

    pub(all) enum PixelPacking {
    U8
    U16LE
    U16BE
    High16LE
    High16BE
    } derive(Eq,
    Debug
    )

    Native samples: U16 stores unshifted values; High16 left-aligns the original sample bits. U8 is valid only for eight-bit pictures. No range/RGB conversion.

    AV1_INTRA_DC

    let AV1_INTRA_DC : Int

    AV1_INTRA_H

    let AV1_INTRA_H : Int

    AV1_INTRA_PAETH

    let AV1_INTRA_PAETH : Int

    AV1_INTRA_SMOOTH

    let AV1_INTRA_SMOOTH : Int

    AV1_INTRA_SMOOTH_H

    let AV1_INTRA_SMOOTH_H : Int

    AV1_INTRA_SMOOTH_V

    let AV1_INTRA_SMOOTH_V : Int

    AV1_INTRA_V

    let AV1_INTRA_V : Int

    av1_apply_alpha

    fn av1_apply_alpha(image : Image, alpha : Array[Byte]) -> Image?

    Compose a decoded alpha plane onto an RGBA image without changing RGB.

    av1_apply_film_grain_planes

    fn av1_apply_film_grain_planes(planes : Array[Array[Int]], width : Int, height : Int, bit_depth : Int, monochrome : Bool, subsampling_x : Bool, subsampling_y : Bool, matrix_coefficients : Int, fg : Av1FilmGrainParams) -> Unit?

    Apply film grain to already-cropped, tightly packed planes.

    planes holds one (monochrome) or three planes at their visible sizes; the arrays are modified in place. Returns None for unsupported geometry.

    av1_cdef_filter_plane

    fn av1_cdef_filter_plane(width : Int, height : Int, plane : Array[Int], params : Array[Av1CdefParams], bit_depth? : Int) -> Array[Int]?

    Apply CDEF to a plane using one parameter record per 8x8 block. Frame-edge taps are excluded and the input plane remains unchanged.

    av1_cdef_filter_yuv420

    fn av1_cdef_filter_yuv420(width : Int, height : Int, y : Array[Int], u : Array[Int], v : Array[Int], y_params : Array[Av1CdefParams], uv_params : Array[Av1CdefParams], bit_depth? : Int) -> (Array[Int], Array[Int], Array[Int])?

    Filter 4:2:0 planes. Both parameter arrays follow the luma 8x8 grid; each UV record controls the corresponding chroma 4x4 block. Chroma uses the normative damping decrement of one.

    av1_coeff_base_default

    fn av1_coeff_base_default(q_context : Int, tx_context : Int, plane : Int, coeff_context : Int) -> Array[Int]

    av1_coeff_base_eob_default

    fn av1_coeff_base_eob_default(q_context : Int, tx_context : Int, plane : Int, eob_context : Int) -> Array[Int]

    av1_coeff_br_default

    fn av1_coeff_br_default(q_context : Int, tx_context : Int, plane : Int, br_context : Int) -> Array[Int]

    av1_coeff_dc_sign_default

    fn av1_coeff_dc_sign_default(q_context : Int, plane : Int, sign_context : Int) -> Array[Int]

    av1_coeff_eob1024_default

    fn av1_coeff_eob1024_default(q_context : Int, plane : Int) -> Array[Int]

    av1_coeff_eob_extra_default

    fn av1_coeff_eob_extra_default(q_context : Int, tx_context : Int, plane : Int, eob_context : Int) -> Array[Int]

    av1_coeff_eob_small_default

    fn av1_coeff_eob_small_default(kind : Int, q_context : Int, plane : Int, tx_class : Int) -> Array[Int]

    av1_decode

    fn av1_decode(data : Array[Byte]) -> Image?

    Decode an AV1 OBU stream with fresh reference state and return its first displayed frame after native-depth filtering and final color conversion.

    av1_decode_alpha

    fn av1_decode_alpha(data : Array[Byte]) -> Array[Byte]?

    Decode the first displayed monochrome frame through shared AV1 reconstruction. Alpha represents coverage, so its final conversion always uses full UNORM.

    av1_decode_alpha_tile

    fn av1_decode_alpha_tile(width : Int, height : Int, tile_payload : Array[Byte], base_q_idx : Int, use_128x128_superblock? : Bool, allow_screen_content_tools? : Bool, bit_depth? : Int, disable_cdf_update? : Bool, tx_mode_select? : Bool, reduced_tx_set? : Bool, enable_filter_intra? : Bool, enable_intra_edge_filter? : Bool, cdef? : Av1CdefConfig?, loop_filter? : Av1LoopFilterConfig?, restoration? : Av1RestorationConfig?, upscaled_width? : Int, quant_deltas? : Av1QuantDeltas) -> Array[Byte]?

    Decode a complete monochrome intra tile, including AC, lossless transforms and supported intra modes. Frame filters run before quantizing alpha to eight bits. Width is coded; optional upscaled_width is applied before alpha conversion.

    av1_decode_dc_tile

    fn av1_decode_dc_tile(width : Int, height : Int, tile_payload : Array[Byte], base_q_idx : Int, disable_cdf_update? : Bool, full_range? : Bool, matrix_coefficients? : Int, use_128x128_superblock? : Bool, bit_depth? : Int, allow_screen_content_tools? : Bool, tx_mode_select? : Bool, reduced_tx_set? : Bool, enable_filter_intra? : Bool, enable_intra_edge_filter? : Bool, cdef? : Av1CdefConfig?, loop_filter? : Av1LoopFilterConfig?, restoration? : Av1RestorationConfig?, upscaled_width? : Int, superres_denom? : Int) -> Image?

    Decode one intra tile. Width is the coded width; a nonzero upscaled_width requests final horizontal superres after native-depth frame filtering.

    av1_decode_native

    fn av1_decode_native(data : Array[Byte]) -> Av1NativeFrame?

    Decode raw low-overhead AV1 OBUs with fresh reference state and return the first selected presentation. Monochrome is accepted. None means rejection or no displayed picture. No RGBA conversion is performed.

    av1_decode_native_result

    fn av1_decode_native_result(data : Array[Byte], limits? : DecodeLimits) -> Result[Av1NativeFrame, DecodeError]

    av1_decode_partition_leaves

    fn av1_decode_partition_leaves(tile_payload : Array[Byte], frame_width : Int, frame_height : Int, disable_cdf_update? : Bool, use_128x128_superblock? : Bool) -> Array[Av1SbBlock]?

    Decode an isolated partition-only probe, with fresh CDFs and unavailable external neighbours. Payloads contain partition symbols only: real tile mode and residual syntax must be consumed by the shared callback walker. The root is fixed at 64 pixels, or 128 when use_128x128_superblock is true. This probe accepts at most one root's frame extent and returns complete coded rectangles, including the MI padding beyond visible frame pixels.

    av1_decode_result

    fn av1_decode_result(data : Array[Byte], limits? : DecodeLimits) -> Result[Image, DecodeError]

    av1_decode_rgba16

    fn av1_decode_rgba16(data : Array[Byte]) -> Image16?

    Decode raw AV1 and convert its first selected presentation to RGBA16.

    av1_decode_rgba16_result

    fn av1_decode_rgba16_result(data : Array[Byte], limits? : DecodeLimits) -> Result[Image16, DecodeError]

    av1_decode_show_existing_frame

    fn av1_decode_show_existing_frame(frame_payload : Array[Byte], state : Av1ReferenceState, config : Av1ShowExistingFrameConfig) -> Image?

    Resolve a show-existing frame header directly to a copy of its stored RGBA image. This is the bounded inter-frame entry; motion-compensated blocks are intentionally handled by a later planar decoder stage.

    av1_decode_split_tile_64x64

    fn av1_decode_split_tile_64x64(tile_payload : Array[Byte], base_q_idx : Int, disable_cdf_update? : Bool, full_range? : Bool, matrix_coefficients? : Int, use_128x128_superblock? : Bool, allow_screen_content_tools? : Bool) -> Image?

    Decode a 64x64 root whose first partition symbol is SPLIT.

    av1_decode_tile_group

    fn av1_decode_tile_group(width : Int, height : Int, tile_cols : Int, tile_rows : Int, tile_payload : Array[Byte], tile_size_bytes : Int, base_q_idx : Int, disable_cdf_update? : Bool, full_range? : Bool, matrix_coefficients? : Int, use_128x128_superblock? : Bool, bit_depth? : Int, allow_screen_content_tools? : Bool, tx_mode_select? : Bool, reduced_tx_set? : Bool, enable_filter_intra? : Bool, enable_intra_edge_filter? : Bool, cdef? : Av1CdefConfig?, loop_filter? : Av1LoopFilterConfig?, restoration? : Av1RestorationConfig?, upscaled_width? : Int, superres_denom? : Int) -> Image?

    Decode a complete tile group into a raster image when every tile is a bounded intra tile supported by the current pixel path. Tile-local MSAC state is reset for each payload. Frame filtering and nonzero upscaled_width operate on assembled native planes, preserving samples across tile seams.

    av1_decode_tile_group_with_boundaries

    fn av1_decode_tile_group_with_boundaries(width : Int, height : Int, tile_col_starts_sb : Array[Int], tile_row_starts_sb : Array[Int], superblock_pixels : Int, tile_payload : Array[Byte], tile_size_bytes : Int, base_q_idx : Int, disable_cdf_update? : Bool, full_range? : Bool, matrix_coefficients? : Int, use_128x128_superblock? : Bool, bit_depth? : Int, allow_screen_content_tools? : Bool, tx_mode_select? : Bool, reduced_tx_set? : Bool, enable_filter_intra? : Bool, enable_intra_edge_filter? : Bool, cdef? : Av1CdefConfig?, loop_filter? : Av1LoopFilterConfig?, restoration? : Av1RestorationConfig?, upscaled_width? : Int, monochrome? : Bool, superres_denom? : Int) -> Image?

    Decode tiles whose superblock boundaries are explicitly known, including non-uniform tile_info() layouts. Each tile keeps one entropy state across its superblocks; frame filters run on the assembled native-depth planes. Width and boundaries refer to coded pixels; upscaled_width selects the final display width after filtering (zero preserves the coded width).

    av1_decode_tx_partition_tree_payload

    fn av1_decode_tx_partition_tree_payload(payload : Array[Byte], root : Av1TxNode, max_depth : Int, disable_cdf_update? : Bool) -> Array[Av1TxLeaf]?

    Decode an isolated transform tree with fresh default CDFs and unavailable external neighbours. Internal leaf dimensions and CDF updates are retained throughout the walk. Coordinates are pixels and must be 4-pixel aligned; root geometry must be a legal AV1 transform size. max_depth accepts 0..2; use 2 for the AV1 variable-transform recursion limit. Payloads exceeding the symbol decoder's 14-bit padding budget are rejected. This probe does not parse tile syntax, resolve inter/skip edge metadata, clip frame-edge blocks, or carry CDF state across payload calls.

    av1_demux

    fn av1_demux(data : Array[Byte], format? : Av1ContainerFormat?, track_id? : Int64?, limits? : DecodeLimits) -> Result[Av1DemuxedTrack, DecodeError]

    Detect IVF, ISO BMFF or EBML from their file headers, or use an explicit format. Only AV1 video tracks are selected. Parsing does not decode pixels.

    av1_demux_ivf

    fn av1_demux_ivf(data : Array[Byte], limits? : DecodeLimits) -> Result[Av1DemuxedTrack, DecodeError]

    Read AV01 IVF records. The header time base is scale/rate seconds; timestamps become pts*scale ticks with timescale=rate, checked in Int64. IVF carries neither DTS, duration nor sync flags, so those remain None. A zero declared record count means unspecified; a nonzero count is checked.

    av1_demux_mp4

    fn av1_demux_mp4(data : Array[Byte], track_id? : Int64?, limits? : DecodeLimits) -> Result[Av1DemuxedTrack, DecodeError]

    Demux an AV1 av01 track from an ISO BMFF/MP4 byte buffer.

    Samples are returned in decode order. presentation_timestamp and decode_timestamp are raw media timestamps in timescale units; no movie-level edit-list offset is applied. Selected-track edits are exposed in the result; encryption, external data references, or sample-entry switches return Unsupported.

    av1_demux_webm

    fn av1_demux_webm(data : Array[Byte], track_id? : Int64?, limits? : DecodeLimits) -> Result[Av1DemuxedTrack, DecodeError]

    Parse a WebM/Matroska file carrying a V_AV1 video track.

    track_id selects Matroska TrackNumber (not TrackUID). If omitted, the first AV1 video TrackEntry is selected. All returned packet buffers and the AV1 initialization OBUs own their bytes independently of data.

    av1_extract_tile_payloads

    fn av1_extract_tile_payloads(payload : Array[Byte], tile_cols : Int, tile_rows : Int, tile_size_bytes : Int) -> Array[Av1TilePayload]?

    Extract tile payloads from a tile-group byte range.

    tile_size_bytes is the AV1 tile_size_bytes value (1..4). Every tile except the last is preceded by a little-endian tile_size_minus_1 field of that width; the last tile consumes the remaining bytes. A zero value is accepted only for a single tile and means that the caller supplied the already isolated legacy payload. All arithmetic is checked before slicing so malformed prefixes cannot expose out-of-range data.

    av1_find_mv_stack

    fn av1_find_mv_stack(field : Av1MotionField, block : Av1MvBlock, frame : Av1MvFrame, is_compound : Bool) -> Av1MvStack?

    Build the candidate stack and the inter-mode contexts for one block (AV1 §7.10.2). Motion-vector reference storage (use_ref_frame_mvs) adds a temporal scan between the near weighting and the corner scan; it reads the frame's projected 8x8 grid, and a frame that asks for it without one is refused rather than decoded with a candidate list that lost its temporal half.

    av1_frame_info

    fn av1_frame_info(data : Array[Byte]) -> Av1FrameInfo?

    Returns the reduced-still frame header envelope when a frame OBU follows a supported sequence header. Tile payload bytes are retained only as a size check; they are not interpreted as pixels by this milestone.

    av1_frame_map

    fn av1_frame_map() -> Av1FrameMap

    An empty reference buffer. Every slot starts invalid with identity motion and neutral loop-filter deltas, matching setup_past_independence.

    av1_frame_map_show

    fn av1_frame_map_show(map : Av1FrameMap, slot : Int) -> Av1RefFrame?

    Resolve a show-existing envelope against the buffer. A buffered frame carries no tile data, so this is the whole reconstruction step for it.

    av1_frame_tile_payloads

    fn av1_frame_tile_payloads(frame : Av1FrameHeaderInfo) -> Array[Av1TilePayload]?

    Return validated tile payload slices for a parsed frame header. The frame parser has already consumed the optional tile-group range header; this boundary applies the checked size-prefix handling to the remaining bytes.

    av1_inter_frame_of

    fn av1_inter_frame_of(header : Av1FrameHeaderInfo, sequence : Av1SequenceInfo, map : Av1FrameMap) -> Av1InterFrame?

    Bind the frame's named references to its decoded buffers and size the motion field (AV1 §7.8). A name whose slot was never refreshed has no buffer, and the block stage refuses to predict from it.

    av1_inter_frame_supported

    fn av1_inter_frame_supported(header : Av1FrameHeaderInfo, sequence : Av1SequenceInfo) -> Bool

    Validate frame-level prerequisites for inter reconstruction. Warp eligibility is decided for each prediction and does not invalidate a legal frame.

    av1_intra_predict

    fn av1_intra_predict(mode : Int, width : Int, height : Int, above : Array[Int], left : Array[Int], top_left : Int, bit_depth : Int, have_above? : Bool, have_left? : Bool) -> Array[Int]?

    Produce one AV1 intra-predicted block. Modes implemented are DC, V, H, PAETH, SMOOTH, SMOOTH_V and SMOOTH_H. Width and height must be powers of two from 4 through 64. Samples are clipped to bit_depth (8..12).

    av1_inverse_dct

    fn av1_inverse_dct(input : Array[Int], n : Int, clamp_bits : Int) -> Array[Int]?

    Exact AV1 inverse DCT. n is log2(length), and clamp_bits is the intermediate range r from §7.13.2.3 (normally BitDepth+8 or +6).

    av1_inverse_dct_2d

    fn av1_inverse_dct_2d(dequant : Array[Int], width : Int, height : Int, bit_depth : Int, lossless? : Bool) -> Array[Int]?

    2D DCT_DCT inverse transform (§7.13.3), row-major coefficients/output. Width and height are legal AV1 transform dimensions (4,8,16,32,64).

    av1_inverse_dct_dc

    fn av1_inverse_dct_dc(dc : Int, n : Int, clamp_bits : Int) -> Array[Int]?

    Exact DC-only specialization. It uses the same normative butterfly path, making the result bit-identical to a block with all AC coefficients zero.

    av1_inverse_transform_2d

    fn av1_inverse_transform_2d(tx_type : Av1TxType, dequant : Array[Int], width : Int, height : Int, bit_depth : Int, lossless? : Bool) -> Array[Int]?

    Dispatch a coded transform type. DCT_DCT and lossless WHT are implemented; other AV1 transform types remain explicit unsupported boundaries.

    av1_motion_field

    fn av1_motion_field(cols : Int, rows : Int) -> Av1MotionField

    An empty motion field. Intra blocks leave is_inter false, which is what the candidate scans test before considering a neighbour at all.

    av1_motion_field_estimation

    fn av1_motion_field_estimation(sequence : Av1SequenceInfo, order_hint : Int, order_hints : Array[Int], refs : Array[Av1RefFrame?], mi_cols : Int, mi_rows : Int) -> Av1MotionFieldGrid

    motion_field_estimation (§7.9.1). Builds the per-reference 8x8 grids for a frame that sets use_ref_frame_mvs.

    av1_motion_field_store

    fn av1_motion_field_store(field : Av1MotionField, row : Int, col : Int, width4 : Int, height4 : Int, y_mode : Int, refs : Array[Int], mv_rows : Array[Int], mv_cols : Array[Int], skip? : Int, skip_mode? : Int, interp? : Array[Int], compound_idx? : Int, comp_group_idx? : Int) -> Unit

    Record one decoded block over its 4x4 footprint. The specification writes this before transform sizing and before prediction, so a block's own entries are already visible when motion compensation reads them back.

    av1_msac_decode_first

    fn av1_msac_decode_first(data : Array[Byte], cdf : Array[Int]) -> Int?

    Decode one symbol from a fresh tile state. This small probe is also useful for conformance tests; full tile decoding keeps the decoder instance alive and calls symbol repeatedly.

    av1_msac_read_first

    fn av1_msac_read_first(data : Array[Byte], probability : Int) -> Int?

    Reads one boolean from an isolated MSAC payload. This small public probe is also useful for conformance tests while the full tile decoder is developed.

    av1_mv_block_position

    fn av1_mv_block_position(x8 : Int, y8 : Int, proj_mv_row : Int, proj_mv_col : Int, dst_sign : Int, mi_cols : Int, mi_rows : Int) -> (Int, Int, Bool)

    get_block_position for both axes. The width limit uses av1_mv_max_offset_width and the height limit av1_mv_max_offset_height, which are deliberately asymmetric in the specification.

    av1_mv_div_mult_size

    let av1_mv_div_mult_size : Int

    Div_Mult has exactly 32 entries, and the temporal projection indexes it with Min(MAX_FRAME_DISTANCE, denominator). That is what bounds MAX_FRAME_DISTANCE to at most 31 — see HANDOFF.md addendum 25.

    av1_mv_frame_of

    fn av1_mv_frame_of(hf : Av1FrameHeaderInfo, temporal? : Av1MotionFieldGrid?) -> Av1MvFrame

    Project a parsed frame header onto what motion derivation needs. A frame that sets use_ref_frame_mvs also carries the 8x8 grid its temporal scan reads; av1_inter_frame_of supplies it.

    av1_mv_invalid

    let av1_mv_invalid : Int

    The invalid motion vector that fills an un-projected MotionFieldMvs cell.

    av1_mv_max_frame_distance

    let av1_mv_max_frame_distance : Int

    MAX_FRAME_DISTANCE. Bounds both the numerator and the denominator of a projection, and indexes av1_mv_div_mult, which has 32 entries — so the bound must be at most 31, and go-av1's value is exactly that.

    av1_mv_max_offset_height

    let av1_mv_max_offset_height : Int

    av1_mv_max_offset_width

    let av1_mv_max_offset_width : Int

    MAX_OFFSET_WIDTH / MAX_OFFSET_HEIGHT, the half-width of the window get_block_position accepts around a projected 8x8 location.

    av1_mv_projection

    fn av1_mv_projection(mv_row : Int, mv_col : Int, numerator : Int, denominator : Int) -> (Int, Int)

    get_mv_projection for both components at once.

    av1_mv_projection_component

    fn av1_mv_projection_component(component : Int, numerator : Int, denominator : Int) -> Int

    get_mv_projection( mv, numerator, denominator ) for one component: scale a saved motion vector from the frame distance it was measured over to another.

    A zero denominator maps to Div_Mult[0], which is zero, so a division by zero projects to a zero vector rather than failing.

    av1_mv_refmvs_limit

    let av1_mv_refmvs_limit : Int

    The motion-field magnitude limit: a saved vector larger than this in either axis is not recorded as a temporal candidate.

    av1_mv_stack_stamp

    let av1_mv_stack_stamp : Int

    MFMV_STACK_SIZE - 2: how many reference frames beyond LAST the projection is allowed to consume.

    av1_parse_show_existing_frame

    fn av1_parse_show_existing_frame(frame_payload : Array[Byte], config : Av1ShowExistingFrameConfig) -> Av1ShowExistingFrameEnvelope?

    Parse the minimal show_existing_frame prefix of an AV1 frame header.

    The first bit must be one. The parser then consumes the three-bit map index, the conditional temporal-point timing field, and the conditional frame ID, rejecting truncation, invalid field widths, and map indices for which the supplied reference state has no slot. Remaining frame-header syntax is intentionally outside this envelope and is not interpreted.

    av1_parse_show_existing_frame_envelope

    fn av1_parse_show_existing_frame_envelope(frame_payload : Array[Byte], config : Av1ShowExistingFrameConfig) -> Av1ShowExistingFrameEnvelope?

    Explicitly named alias for callers that prefer the envelope terminology.

    av1_parse_stage1_frame

    fn av1_parse_stage1_frame(frame_payload : Array[Byte], sequence : Av1SequenceInfo, allow_monochrome? : Bool, allow_highbd? : Bool, map? : Av1FrameMap, frame_header_obu? : Bool, tile_groups? : Array[Array[Byte]], temporal_id? : Int, spatial_id? : Int) -> Av1FrameHeaderInfo?

    Parses a frame header and returns its entropy-coded tile group. Unsupported syntax is rejected before any bytes are exposed to the reconstruction stage. A general (non reduced-still) sequence reads and updates the reference buffer, so map is required for one.

    av1_partition_children

    fn av1_partition_children(node : Av1SbPartitionNode, partition : Av1SbPartition) -> Array[Av1SbBlock]

    Return coding-block rectangles in AV1 syntax order. SPLIT rectangles are square recursive nodes; all other results are terminal blocks. Origins outside the MI grid are omitted, while partial edge blocks keep their full coded dimensions. Invalid geometry or partition combinations return [].

    av1_partition_context

    fn av1_partition_context(current_size : Int, above_size : Int?, left_size : Int?) -> Int

    AV1 partitionCtx: above_size is the above coding block's width; left_size is the left coding block's height. Unavailable tile neighbours are None.

    av1_partition_leaves

    fn av1_partition_leaves(root : Av1SbPartitionNode, partitions : Array[Av1SbPartition]) -> Array[Av1SbBlock]?

    Walk signalled partition decisions in AV1 syntax order. Implied 4x4 NONE and forced frame-edge SPLIT decisions consume no entries. Only SPLIT recurses; rectangular and A/B partition blocks are terminal.

    av1_partition_node

    fn av1_partition_node(row : Int, col : Int, size : Int, frame_width : Int, frame_height : Int) -> Av1SbPartitionNode

    Creates a square partition node. Invalid geometry is rejected by the child and edge predicates rather than clamped silently.

    av1_reconstruct_split_64x64

    fn av1_reconstruct_split_64x64(y_coeffs : Array[Array[Int]], u_coeffs : Array[Array[Int]], v_coeffs : Array[Array[Int]], y_modes : Array[Int], u_modes : Array[Int], v_modes : Array[Int], full_range? : Bool, matrix_coefficients? : Int) -> Image?

    reconstruct a 64x64 RGBA image from four split luma children.

    av1_reconstruct_split_yuv420

    fn av1_reconstruct_split_yuv420(y_coeffs : Array[Array[Int]], u_coeffs : Array[Array[Int]], v_coeffs : Array[Array[Int]], y_modes : Array[Int], u_modes : Array[Int], v_modes : Array[Int]) -> (Array[Byte], Array[Byte], Array[Byte])?

    four-way 64x64 split reconstruction returning planar 8-bit YUV420.

    y_coeffs contains four 32x32 dequantised coefficient blocks in the order returned by av1_partition_children(SPLIT). U and V contain four 16x16 blocks; an empty array means that the corresponding chroma plane is neutral. Modes are intra mode numbers (DC/V/H/PAETH/SMOOTH variants). This bounded path rejects non-four-way geometry and malformed block lengths.

    av1_reconstruct_split_yuv420_with_types

    fn av1_reconstruct_split_yuv420_with_types(y_coeffs : Array[Array[Int]], u_coeffs : Array[Array[Int]], v_coeffs : Array[Array[Int]], y_modes : Array[Int], u_modes : Array[Int], v_modes : Array[Int], y_types : Array[Av1TxType], u_types : Array[Av1TxType], v_types : Array[Av1TxType]) -> (Array[Byte], Array[Byte], Array[Byte])?

    Reconstruct a four-way 4:2:0 split while carrying transform types per plane and child. This is the typed counterpart to the legacy DCT_DCT API.

    av1_reconstruct_tx_chroma

    fn av1_reconstruct_tx_chroma(leaves : Array[Av1TxLeaf], coefficients : Array[Array[Int]], mode : Int, types : Array[Av1TxType], size? : Int, bit_depth? : Int) -> Array[Int]?

    Reconstruct one 4:2:0 chroma plane from 16×16 transform leaves.

    av1_reconstruct_tx_luma

    fn av1_reconstruct_tx_luma(width : Int, height : Int, leaves : Array[Av1TxLeaf], coefficients : Array[Array[Int]], mode : Int, types : Array[Av1TxType], bit_depth? : Int) -> Array[Int]?

    Reconstruct luma from raster-ordered transform leaves.

    av1_reconstruct_tx_rgba

    fn av1_reconstruct_tx_rgba(width : Int, height : Int, y_leaves : Array[Av1TxLeaf], y_coefficients : Array[Array[Int]], u_leaves : Array[Av1TxLeaf], u_coefficients : Array[Array[Int]], v_leaves : Array[Av1TxLeaf], v_coefficients : Array[Array[Int]], y_mode : Int, uv_mode : Int, y_types : Array[Av1TxType], u_types : Array[Av1TxType], v_types : Array[Av1TxType], bit_depth : Int, full_range? : Bool, matrix_coefficients? : Int) -> Image?

    Compose typed transform leaves for Y/U/V into an RGBA image.

    av1_reference_show_existing

    fn av1_reference_show_existing(state : Av1ReferenceState, envelope : Av1ShowExistingFrameEnvelope) -> Image?

    Resolve a parsed show-existing envelope against stored reference pixels.

    av1_reference_state

    fn av1_reference_state() -> Av1ReferenceState

    Create an empty eight-slot reference state.

    av1_reference_store

    fn av1_reference_store(state : Av1ReferenceState, slot : Int, image : Image, frame_type : Int) -> Bool

    Store a decoded image in one AV1 reference slot.

    av1_relative_dist

    fn av1_relative_dist(sequence : Av1SequenceInfo, a : Int, b : Int) -> Int

    The signed circular distance between two order hints (AV1 §5.9.3). Zero is returned when the sequence disables order hints, which makes every sign bias forward.

    av1_restoration_active

    fn av1_restoration_active(config : Av1RestorationConfig) -> Bool

    True when any actual plane requests a filter. Unit sizes remain valid for an all-None configuration; they are simply never applied.

    av1_seg_level_alt_q

    let av1_seg_level_alt_q : Int

    SEG_LVL_ALT_Q: the one per-segment feature this decoder applies. It only shifts the block's quantizer index, so the residual reading applies it with no further plumbing. Every other level changes the loop filter, the block's reference or its prediction mode, and the block stage refuses a frame that enables one (see av1_inter_frame_supported).

    av1_seg_level_ref_frame

    let av1_seg_level_ref_frame : Int

    SEG_LVL_REF_FRAME: features at or above it set SegIdPreSkip.

    av1_segment_levels

    let av1_segment_levels : Int

    SEG_LVL_MAX: the eight per-segment features.

    av1_segmentation_features_supported

    fn av1_segmentation_features_supported(segmentation : Av1SegmentationParams) -> Bool

    Validate all eight segment feature ranges. Quantization, four loop-filter deltas, forced references, skip and global motion each have tile consumers.

    av1_segmentation_supported

    fn av1_segmentation_supported(segmentation : Av1SegmentationParams) -> Bool

    Frame parsing resolves inherited feature tables from the primary reference; tile decoding resolves unchanged or temporally predicted segment maps from the saved frame state. This check validates the resulting feature data.

    av1_segments

    let av1_segments : Int

    MAX_SEGMENTS: how many segment ids a frame may assign.

    av1_sequence_info

    fn av1_sequence_info(data : Array[Byte]) -> Av1SequenceInfo?

    Parses a raw AV1 low-overhead bitstream and returns its reduced sequence header. The input is OBU data (the AVIF av1C configuration is not needed).

    av1_tx_children

    fn av1_tx_children(node : Av1TxNode, partition : Av1TxPartition) -> Array[Av1TxNode]

    Return valid children for one transform-tree partition.

    av1_tx_depth_context_for_node

    fn av1_tx_depth_context_for_node(state : Av1TxTraversalState, node : Av1TxNode) -> Int

    Derive tx_depth context at the immediate above/left 4x4 positions of this coding block. Recorded dimensions are effective neighbour sizes: transform sizes for intra neighbours, coding-block sizes for inter neighbours. Coordinates are tile-local; missing edges contribute zero.

    av1_tx_depth_context_from_neighbors

    fn av1_tx_depth_context_from_neighbors(above_depth : Int, left_depth : Int) -> Int

    Legacy coarse depth-flag helper. The normative tx_depth context requires effective neighbour dimensions and is computed by the size-based helpers; neighbour depths alone do not determine the AV1 CDF context.

    av1_tx_depth_context_from_sizes

    fn av1_tx_depth_context_from_sizes(above_width : Int, left_height : Int, max_tx_width : Int, max_tx_height : Int) -> Int

    Derive the tx_depth context from the transform dimensions recorded for the neighbouring blocks (AV1 spec section 8.3). The syntax context is a pair of independent flags: one for an above neighbour whose transform width reaches the current maximum width, and one for a left neighbour whose transform height reaches the current maximum height. A negative dimension denotes an unavailable edge and contributes zero.

    av1_tx_leaves

    fn av1_tx_leaves(root : Av1TxNode, partitions : Array[Av1TxPartition]) -> Array[Av1TxNode]?

    Walk a transform tree and return its leaf nodes in raster order.

    av1_tx_rect_supported

    fn av1_tx_rect_supported(width : Int, height : Int) -> Bool

    Legal AV1 rectangular transform dimensions (up to a 4:1 aspect ratio).

    av1_tx_traversal_record

    fn av1_tx_traversal_record(state : Av1TxTraversalState, node : Av1TxNode) -> Unit

    Record a decoded block's effective dimensions for subsequent neighbours.

    av1_tx_traversal_state

    fn av1_tx_traversal_state(width : Int, height : Int) -> Av1TxTraversalState

    Create empty neighbour state for one tile. The state is intentionally independent from the entropy CDF state so callers can reuse it across blocks without resetting tx_depth adaptation.

    av1_video_decode_frame

    fn av1_video_decode_frame(decoder : Av1VideoDecoder, data : Array[Byte], allow_monochrome? : Bool) -> Image?

    Decode a temporal unit and return its first displayed image. All frames in the unit update the reference map. Use av1_video_decode_temporal_unit to receive one presentation per temporal unit, including show-existing. OP0's highest spatial layer actually present is selected independently per unit.

    av1_video_decode_temporal_unit

    fn av1_video_decode_temporal_unit(decoder : Av1VideoDecoder, data : Array[Byte], allow_monochrome? : Bool) -> Array[Image]?

    Decode temporal units in bitstream order, selecting the highest spatial layer actually present in OP0 for each unit. Input may contain several TD-delimited units; an ISOBMFF sample implicitly ends its single unit. Some([]) denotes a valid unit containing only hidden frames or metadata; None denotes malformed syntax or a missing reference. Failure does not roll back reference updates; discard the decoder after None. Native output is available through av1_video_decode_temporal_unit_native and can be interleaved with this entry point on the same decoder.

    av1_video_decode_temporal_unit_native

    fn av1_video_decode_temporal_unit_native(decoder : Av1VideoDecoder, data : Array[Byte], allow_monochrome? : Bool) -> Array[Av1NativeFrame]?

    Decode temporal units using the same state and presentation policy as av1_video_decode_temporal_unit, returning owned native-depth pictures. Some([]) means valid input with no presentation; hidden frames still update references. None means rejection. State is not rolled back on failure; discard the decoder after None. Monochrome is opt-in, matching the RGBA video entry point. The two APIs can share one decoder in order.

    av1_video_decode_temporal_unit_native_result

    fn av1_video_decode_temporal_unit_native_result(decoder : Av1VideoDecoder, data : Array[Byte], allow_monochrome? : Bool, limits? : DecodeLimits) -> Result[Array[Av1NativeFrame], DecodeError]

    Valid hidden-only input returns Ok([]). Any Err requires discarding/resetting the decoder: reference updates are not transactional, as in the Option API.

    av1_video_decoder

    fn av1_video_decoder() -> Av1VideoDecoder

    Create an idle video decoder with an empty reference buffer.

    av1_warp_from_global_motion

    fn av1_warp_from_global_motion(matrix : Array[Int]) -> Av1WarpModel?

    The warp model a frame-level global-motion entry stands for, or None when the model cannot be represented on the prediction grid (a pure shear, or one whose coefficients the grid clips). The matrix is read, never written: the prediction half only reads it.

    av1_warp_samples_scan_limit

    let av1_warp_samples_scan_limit : Int

    The largest block the 64x64-superblock profile can code is 64x64, i.e. 16 units of 4x4 per axis. find_warp_samples scans at most w4 / miStep positions above and h4 / miStep to the left, and miStep is Min(w4, srcW) with the smallest codable block being 8x8 = 2 units, so each axis contributes at most 8. The top-left and top-right corners add two more. A limit of 18 therefore never truncates that profile's scan, which makes the result independent of the unknown LEAST_SQUARES_SAMPLES_MAX there.

    av1_wedge_mask

    fn av1_wedge_mask(width : Int, height : Int, index : Int, sign : Int) -> Array[Int]?

    The width x height wedge mask for one block, indexed [y][x], or None when the block size cannot code a wedge. The sign chooses each of the two mirrored variants: the mask whose average is at least 32, or its complement (AV1 §7.11.3.11). Valid indices are 0 through 15; invalid indices also return None.

    av1_wedge_shape_ok

    fn av1_wedge_shape_ok(width : Int, height : Int) -> Bool

    Whether a block size can code a wedge.

    av1_yuv420_highbd_to_rgba

    fn av1_yuv420_highbd_to_rgba(width : Int, height : Int, y : Array[Int], u : Array[Int], v : Array[Int], bit_depth : Int, full_range? : Bool, matrix_coefficients? : Int, color_primaries? : Int, transfer_characteristics? : Int) -> Image?

    4:2:0 convenience wrapper over av1_yuv_highbd_to_rgba.

    av1_yuv420_to_rgba

    fn av1_yuv420_to_rgba(width : Int, height : Int, y : Array[Byte], u : Array[Byte], v : Array[Byte]) -> Image?

    Converts an 8-bit planar YUV420 frame to PixelForge RGBA using the limited range BT.601 matrix. The AV1 tile decoder can call this after reconstruction; it performs no codec fallback and rejects malformed plane lengths.

    av1_yuv420_to_rgba_color

    fn av1_yuv420_to_rgba_color(width : Int, height : Int, y : Array[Byte], u : Array[Byte], v : Array[Byte], full_range? : Bool, matrix_coefficients? : Int, color_primaries? : Int, transfer_characteristics? : Int) -> Image?

    Converts 8-bit planar YUV420 using color range and AV1 matrix coefficients. This byte-plane adapter shares the native-depth CICP conversion and its source-RGB convention; see av1_yuv_highbd_to_rgba for matrix metadata.

    av1_yuv420_to_rgba_range

    fn av1_yuv420_to_rgba_range(width : Int, height : Int, y : Array[Byte], u : Array[Byte], v : Array[Byte], full_range? : Bool) -> Image?

    Converts 8-bit planar YUV420 using the AV1 color range flag.

    av1_yuv_highbd_to_rgba

    fn av1_yuv_highbd_to_rgba(width : Int, height : Int, y : Array[Int], u : Array[Int], v : Array[Int], bit_depth : Int, subsampling_x? : Bool, subsampling_y? : Bool, full_range? : Bool, matrix_coefficients? : Int, color_primaries? : Int, transfer_characteristics? : Int) -> Image?

    High-bit-depth planar YUV conversion for the staged AV1 path.

    The public Image type stores 8-bit channels; coded 8..12-bit samples are converted with the high-bit-depth matrix and narrowed only for final RGBA storage. Codec reconstruction remains integer-only; this adapter performs no browser or FFI fallback.

    subsampling_x/subsampling_y select 4:4:4, 4:2:2 or 4:2:0; the defaults keep the historical 4:2:0 behaviour of av1_yuv420_highbd_to_rgba. Chroma uses nearest-neighbour replication. Output is source-primary, source-transfer nonlinear RGB, clipped and rounded once to RGBA8. There is no display tone mapping or gamut conversion, except that XYZ primaries (10) are explicitly converted to BT.709/sRGB. Unspecified matrix (2) uses the AVIF/libavif BT.601 default; matrices needing primaries or a transfer reject unspecified metadata rather than guessing those parameters.

    avif_alpha_item_descriptor

    fn avif_alpha_item_descriptor(data : Array[Byte]) -> AvifAlphaItemDescriptor?

    Extract the first alpha item associated with the primary image through auxl and the alpha auxC URN. None also represents malformed input for this public Option API; composition uses the checked internal query instead.

    avif_alpha_item_payload

    fn avif_alpha_item_payload(data : Array[Byte]) -> Array[Byte]?

    Return the validated raw auxiliary alpha item bytes in extent order. The bytes are still AV1 payload data and are not interpreted as pixels.

    avif_animation_descriptor

    fn avif_animation_descriptor(data : Array[Byte]) -> AvifAnimationDescriptor?

    Metadata for the selected primary AV1 picture track.

    avif_animation_frame_at

    fn avif_animation_frame_at(animation : AvifAnimationPixels, timestamp : Int) -> Image?

    Select the frame visible at a media timestamp. Playback loops at the track duration; negative timestamps are rejected.

    avif_animation_sample_payloads

    fn avif_animation_sample_payloads(data : Array[Byte]) -> (AvifAnimationDescriptor, Array[Array[Byte]])?

    Extract sample payloads from the selected primary animation track.

    avif_container_parse

    fn avif_container_parse(data : Array[Byte]) -> AvifContainer?

    avif_container_parse_result

    fn avif_container_parse_result(data : Array[Byte], limits? : DecodeLimits) -> Result[AvifContainer, DecodeError]

    avif_decode

    fn avif_decode(data : Array[Byte]) -> Image?

    Decode the AVIF primary item's selected frame or grid with fresh AV1 reference state. The RGBA entry point additionally composes auxiliary alpha.

    avif_decode_alpha

    fn avif_decode_alpha(data : Array[Byte]) -> Array[Byte]?

    Decode the validated auxiliary alpha item from a complete AVIF container. The result is a row-major 8-bit alpha plane, rounded from its native depth.

    avif_decode_animation

    fn avif_decode_animation(data : Array[Byte]) -> AvifAnimationPixels?

    Parse and decode all animation samples from a self-contained BMFF buffer.

    avif_decode_animation_frame

    fn avif_decode_animation_frame(data : Array[Byte], timestamp : Int) -> Image?

    Decode an AVIF sequence and select the image visible at timestamp in track timescale units. The full sequence is validated before selection; malformed timing or pixel samples therefore cannot produce a partial frame.

    avif_decode_animation_frames

    fn avif_decode_animation_frames(descriptor : AvifAnimationDescriptor, samples : Array[Array[Byte]]) -> AvifAnimationPixels?

    Decode an ordered set of AV1 animation samples using the native decoder. A malformed or unsupported sample rejects the whole sequence so callers do not accidentally present a partial animation.

    avif_decode_animation_native

    fn avif_decode_animation_native(data : Array[Byte]) -> AvifNativeAnimation?

    Decode the entire AVIF animation at 8/10/12-bit native precision. Each color/alpha track keeps its own AV1 reference state. Track association, exact time alignment, metadata and rejection follow avif_decode_animation; color conversion and alpha range expansion/unpremultiplication are omitted. None rejects the whole animation, including a malformed later sample.

    avif_decode_animation_samples

    fn avif_decode_animation_samples(timescale : Int, timestamps : Array[Int], durations : Array[Int], samples : Array[Array[Byte]]) -> AvifAnimationPixels?

    Convenience entrypoint for callers that already extracted sample timing tables. The arrays must match the sample order and length.

    avif_decode_grid

    fn avif_decode_grid(data : Array[Byte], descriptor : AvifGridDescriptor) -> Image?

    Decode a grid directly from a BMFF buffer and its parsed descriptor. Each tile may contain one or more iloc extents; extents are concatenated before passing the sample to the pure AV1 decoder.

    avif_decode_grid_auto

    fn avif_decode_grid_auto(data : Array[Byte]) -> Image?

    Decode and compose a grid directly from a BMFF buffer. This convenience entrypoint performs descriptor extraction and pixel reconstruction as one operation, so callers cannot accidentally skip the dimg ordering or extent validation step.

    avif_decode_grid_tiles

    fn avif_decode_grid_tiles(rows : Int, columns : Int, output_width : Int, output_height : Int, samples : Array[Array[Byte]]) -> Image?

    Decode ordered AV1 grid tile samples and compose them into one image. The samples must be in row-major grid order; unsupported tile syntax rejects the whole image instead of returning a partial reconstruction.

    avif_decode_native

    fn avif_decode_native(data : Array[Byte]) -> AvifNativeImage?

    Decode AVIF primary color and optional alpha at native precision. Grid assembly, layer selection and metadata follow avif_decode_rgba. Invalid or unsupported color/alpha input returns None, never partial color. This is the primary-item API; it does not return an animation timeline.

    avif_decode_native_result

    fn avif_decode_native_result(data : Array[Byte], limits? : DecodeLimits) -> Result[AvifNativeImage, DecodeError]

    avif_decode_rgba

    fn avif_decode_rgba(data : Array[Byte]) -> Image?

    Decode a primary AVIF image and compose its validated auxiliary alpha item. A valid image without an alpha item keeps the existing opaque result; an alpha item that cannot be decoded is reported as None rather than dropped.

    avif_decode_rgba16

    fn avif_decode_rgba16(data : Array[Byte]) -> Image16?

    Decode an AVIF primary image/grid with optional alpha to straight RGBA16.

    avif_decode_rgba16_result

    fn avif_decode_rgba16_result(data : Array[Byte], limits? : DecodeLimits) -> Result[Image16, DecodeError]

    avif_decode_rgba_result

    fn avif_decode_rgba_result(data : Array[Byte], limits? : DecodeLimits) -> Result[Image, DecodeError]

    avif_grid_descriptor

    fn avif_grid_descriptor(data : Array[Byte]) -> AvifGridDescriptor?

    Extract the primary grid and its ordered, validated item extents.

    avif_metadata

    fn avif_metadata(data : Array[Byte], limits? : DecodeLimits) -> Result[AvifMetadata, DecodeError]

    Read primary-item metadata without reconstructing pixels. Input and total exposed metadata are bounded by max_input_bytes. Transform metadata remains available even when its crop cannot be represented by an integer raster.

    avif_reconstruct_grid

    fn avif_reconstruct_grid(rows : Int, columns : Int, output_width : Int, output_height : Int, tiles : Array[Image]) -> Image?

    Compose decoded grid tiles into one RGBA image.

    Tile bytes are decoded by the caller through the normal AV1 path. This helper only performs bounded placement and crops tiles at the output edge.

    avif_stage1_input

    fn avif_stage1_input(data : Array[Byte]) -> Av1Stage1Input?

    Extracts the first supported AV1 tile payload from an AVIF container.

    The function validates the container, reduced-still sequence header, and bounded frame envelope. It does not decode entropy symbols or fabricate pixels; callers in the next milestone consume tile_payload with the intra tile reconstruction pipeline.

    clamp_byte

    fn clamp_byte(value : Int) -> Byte

    Clamps an integer into the [0, 255] range and narrows it to a Byte. Channel math is done in Int to avoid wrap-around, then funnelled through this helper before being stored back into a pixel buffer.

    Source Files