Crate oximedia_container

Expand description

OxiMedia Container Layer

Container format handling with resilient parsing for:

Matroska (.mkv) / WebM (.webm)
Ogg (.ogg, .opus, .oga)
FLAC (.flac)
WAV (.wav)
MP4 (.mp4) - AV1/VP9 only
MPEG-TS (.ts, .m2ts) - AV1/VP9/VP8/Opus/FLAC only
YUV4MPEG2 (.y4m) - Raw uncompressed video

§Overview

This crate provides demuxers and muxers for media container formats. A demuxer reads a container file and extracts compressed packets, while a muxer combines compressed packets into a container file.

§Key Types

ContainerFormat - Enumeration of supported container formats
probe_format - Detect container format from magic bytes
Packet - Compressed media packet with timestamps
StreamInfo - Information about a stream (codec, dimensions, etc.)
Demuxer - Trait for container demuxers
Muxer - Trait for container muxers

§Demuxing Example

use oximedia_container::{probe_format, demux::MatroskaDemuxer, Demuxer};
use oximedia_io::FileSource;

// Detect format from file header
let mut source = FileSource::open("video.mkv").await?;
let mut buf = [0u8; 12];
source.read(&mut buf).await?;
let format = probe_format(&buf)?;
println!("Format: {:?}", format.format);

// Demux the file
source.seek(std::io::SeekFrom::Start(0)).await?;
let mut demuxer = MatroskaDemuxer::new(source);
demuxer.probe().await?;

for stream in demuxer.streams() {
    println!("Stream {}: {:?}", stream.index, stream.codec);
}

while let Ok(packet) = demuxer.read_packet().await {
    println!("Packet: stream={}, size={}, keyframe={}",
             packet.stream_index, packet.size(), packet.is_keyframe());
}

§Muxing Example

use oximedia_container::mux::{MatroskaMuxer, Muxer, MuxerConfig};

let config = MuxerConfig::new()
    .with_title("My Video");

let mut muxer = MatroskaMuxer::new(sink, config);
muxer.add_stream(video_info)?;
muxer.add_stream(audio_info)?;

muxer.write_header().await?;

for packet in packets {
    muxer.write_packet(&packet).await?;
}

muxer.write_trailer().await?;

§Metadata Editing Example

use oximedia_container::metadata::MetadataEditor;

let mut editor = MetadataEditor::open("audio.flac").await?;

// Read tags
if let Some(title) = editor.get_text("TITLE") {
    println!("Title: {}", title);
}

// Modify tags
editor.set("TITLE", "New Title");
editor.set("ARTIST", "New Artist");

// Save changes
editor.save().await?;

§Wave 4 API Additions

§MP4 Fragment Mode — `Mp4FragmentMode`

mux::mp4::Mp4FragmentMode controls how the MP4 muxer arranges sample data:

Variant	Description
`Progressive`	Classic MP4: single `moov` + `mdat`, optimal for download
`Fragmented { fragment_duration_ms }`	ISOBMFF fragments; each fragment is a self-contained `moof`+`mdat` pair

Mp4Mode is a backward-compatible type alias for Mp4FragmentMode.

use oximedia_container::mux::mp4::{Mp4Muxer, Mp4Config, Mp4FragmentMode};

// Progressive (default)
let config = Mp4Config::new().with_mode(Mp4FragmentMode::Progressive);

// Fragmented — 4-second fragments for DASH/HLS delivery
let config = Mp4Config::new()
    .with_mode(Mp4FragmentMode::Fragmented { fragment_duration_ms: 4000 });

§Sample-Accurate Seek Cursor — `DecodeSkipCursor`

DecodeSkipCursor is returned by the seek_sample_accurate() methods on the Matroska, MP4, and AVI demuxers. It locates the nearest keyframe at or before a target PTS and records how many decoded samples must be discarded to reach the precise presentation position.

Field	Type	Description
`byte_offset`	`u64`	File offset where decoding should start
`sample_index`	`usize`	0-based index of the keyframe sample
`skip_samples`	`u32`	Samples to decode-and-discard after seeking
`target_pts`	`i64`	Requested PTS in track timescale units

use oximedia_container::demux::MatroskaDemuxer;
use oximedia_io::FileSource;

let mut demuxer = MatroskaDemuxer::new(FileSource::open("video.mkv").await?);
demuxer.probe().await?;

// Seek to exactly 30 seconds (in track timescale units)
let cursor = demuxer.seek_sample_accurate(2_700_000).await?;
println!("Start decode at byte {}, skip {} samples",
         cursor.byte_offset, cursor.skip_samples);

§CMAF Chunked Transfer — `CmafChunkMode` / `CmafChunkedConfig`

streaming::mux::CmafChunkMode and streaming::mux::CmafChunkedConfig implement chunked CMAF delivery as defined in ISO/IEC 23000-19, enabling sub-segment delivery for LL-HLS and LL-DASH workflows.

Mode	Description
`Standard`	Whole-segment delivery (default, no chunking)
`Chunked`	Each chunk is one or more complete `moof`+`mdat` pairs
`LowLatencyChunked`	Each chunk is exactly one sample (minimum latency)

CmafChunkedConfig carries additional settings: chunk_duration_ms, max_samples_per_chunk, include_mfra, signal_low_latency (writes cmfl compatible brand in the styp box), and part_target_duration_ms for LL-HLS.

use oximedia_container::streaming::mux::{CmafChunkedConfig, CmafChunkMode};

let config = CmafChunkedConfig::new()
    .with_mode(CmafChunkMode::LowLatencyChunked)
    .with_low_latency(true);

§Matroska v4 Block Addition Mapping — `BlockAdditionMapping`

demux::matroska::matroska_v4::BlockAdditionMapping represents a Matroska v4 BlockAdditionMapping element (EBML ID 0x41CB), which carries auxiliary per-block data channels such as HDR10+ metadata, Dolby Vision RPU data, or depth maps.

Field	Description
`id_name`	Human-readable channel name (e.g., `"hdr10plus"`, `"dovi_rpu"`)
`id_type`	Numeric type per the Matroska Block Addition Mapping Registry
`id_extra_data`	Codec-specific configuration payload

Access via StreamInfo::block_addition_mappings after probing a Matroska track.

Re-exports§

pub use container_probe::DetailedContainerInfo;
pub use container_probe::DetailedStreamInfo;
pub use container_probe::MultiFormatProber;
pub use dash::emit_mpd;
pub use dash::DashAdaptationSet;
pub use dash::DashManifestConfig;
pub use dash::DashRepresentation;
pub use dash::DashSegmentTemplate;
pub use dash::DashSegmentTimeline;
pub use dash::DashSegmentTimelineEntry;
pub use demux::mpegts::scte35::parse_splice_info_section;
pub use demux::mpegts::scte35::BreakDuration;
pub use demux::mpegts::scte35::Scte35Config;
pub use demux::mpegts::scte35::Scte35Parser;
pub use demux::mpegts::scte35::SpliceCommand;
pub use demux::mpegts::scte35::SpliceDescriptor;
pub use demux::mpegts::scte35::SpliceInfoSection;
pub use demux::mpegts::scte35::SpliceInsert;
pub use demux::mpegts::scte35::SpliceTime;
pub use demux::mpegts::scte35::SCTE35_DEFAULT_PID;
pub use demux::Demuxer;
pub use metadata::batch::BatchMetadataUpdate;
pub use metadata::batch::BatchResult;
pub use mux::mpegts::scte35::emit_splice_insert;
pub use mux::mpegts::scte35::emit_splice_null;
pub use mux::mpegts::scte35::emit_time_signal;
pub use mux::mpegts::scte35::SpliceInsertConfig;
pub use mux::Muxer;
pub use mux::MuxerConfig;

Modules§

attach: Embedded file attachments.
bitrate_stats: Container-level bitrate statistics and analysis.
box_header: ISO Base Media File Format (ISOBMFF / MP4) box header parsing.
caf: Core Audio Format (CAF) container support.
chapters: Chapter marker support.
chunk_map: ISOBMFF stsc (Sample-to-Chunk) table abstraction.
container_probe: Higher-level container probing beyond magic-byte detection.
cue: Cue point support for seeking optimization.
dash: MPEG-DASH manifest emitter.
data: Generic data track support.
demux: Demuxer implementations.
edit: Edit list and composition time support.
edit_list: ISO Base Media File Format edit list (elst) abstraction.
fragment: Fragmented container support.
media_header: ISOBMFF mdhd (Media Header Box) parsing and writing.
metadata: Unified metadata reading and writing for container formats.
mkv_cluster: Matroska cluster parsing.
multi_angle: Multi-angle support for Matroska containers.
mux: Muxer implementations.
ogg_page: OGG page format parsing and serialization.
preroll: Pre-roll seeking types for sample-accurate seek operations.
pts_dts: PTS/DTS timestamp utilities and repair helpers.
pts_dts_batch: Batch PTS/DTS timestamp rewriting and processing.
riff: RIFF chunk write helpers shared across RIFF-based muxers (WAV, AVI).
sample_entry: Sample entry / codec configuration record parsing for ISO BMFF containers.
sample_table: ISO Base Media File Format sample table abstractions.
segment_index: Segment index (sidx) and random-access point (SAP) index for fragmented ISO BMFF containers.
stream_index: Container stream index for fast, O(log n) seeking.
streaming: Streaming demuxing and muxing.
subtitle_mux: Subtitle multiplexer for embedding subtitle tracks into Matroska containers.
timecode: Professional timecode support.
track_header: ISO Base Media File Format track header (tkhd) abstraction.
track_info: High-level track type and collection helpers.
tracks: Multi-track management.

Structs§

CodecParams: Codec-specific parameters.
DecodeSkipCursor: A shared decode-and-skip cursor for sample-accurate seek planning.
Metadata: Stream and container metadata.
MultiTrackSeeker: Multi-track sample-accurate seeker with a per-track PTS→byte-offset index.
Packet: A compressed media packet from a container.
PacketFlags: Flags indicating packet properties.
ProbeResult: Result of format probing.
PtsSeekResult: The result of a MultiTrackSeeker::seek_to_pts operation.
SampleAccurateSeeker: Performs sample-accurate seeking on a single media track.
SampleIndexEntry: A compact index entry describing a single sample within a track.
SeekFlags: Flags controlling seek behavior.
SeekIndex: Index of sample positions for fast seeking.
SeekIndexEntry: An entry in the seek index representing one sample/frame.
SeekPlan: A plan for executing a sample-accurate seek.
SeekResult: The result of a sample-accurate seek operation.
SeekTarget: Target for a seek operation.
StreamInfo: Information about a stream in a container.
TrackIndex: A lightweight index of keyframe positions within a single track.

Enums§

ContainerFormat: Supported container formats (patent-free).
MultiTrackSeekerError: Error type returned by MultiTrackSeeker operations.
SeekAccuracy: Desired accuracy level for seeking.

Functions§

probe_format: Probe the container format from raw bytes.