shiguredo_mp4 Rust MP4 Library Reference

shiguredo_mp4

Sans I/O 設計に基づく MP4 (ISO Base Media File Format) の mux/demux ライブラリ。

特徴

• 依存なし: 外部依存ゼロ (core / alloc のみ)
• no_std 対応: std 非依存 (alloc クレートは必要)
• Sans I/O: I/O を完全に分離した設計。ファイル読み書きは利用側の責務
• 高レベル API: Mp4FileMuxer / Mp4FileDemuxer / Fmp4SegmentMuxer / Fmp4SegmentDemuxer による mux/demux
• ボックス単位の API: 全ボックスが Encode / Decode を実装し、直接エンコード/デコード可能
• C API / WebAssembly API: crates/c-api / crates/wasm で提供

バージョン情報

• crate 名: shiguredo_mp4
• バージョン: 2026.5.0
• Rust Edition: 2024
• 最小 Rust バージョン: 1.93
• ライセンス: Apache-2.0

基本概念

MP4 ファイルは ftyp + 各種ボックス（moov / mdat / moof 等）で構成される。 すべてのボックスは BaseBox トレイトを実装し、Encode / Decode トレイトでバイト列と相互変換できる。

Encode / Decode トレイト

use shiguredo_mp4::{Decode, Encode};

// エンコード: buf に書き込み、書き込んだバイト数を返す
let n = box.encode(&mut buf)?;

// バイト列に変換
let bytes = box.encode_to_vec()?;

// デコード: (値, 消費バイト数) を返す
let (decoded, size) = BoxType::decode(buf)?;

// オフセットを自動で進めるデコード
let value = u32::decode_at(buf, &mut offset)?;

エラー型

• Error: エンコード/デコード時のエラー。kind: ErrorKind (InvalidInput / InvalidData / InsufficientBuffer / Unsupported) と reason / location / box_type を持つ。Display は発生箇所 (at src/xxx.rs:NNN) 付きで表示される
• DemuxError: デマルチプレックス時のエラー。DecodeError / SampleTableError / InvalidState / InputRequired(RequiredInput) (Sans I/O の入力要求)
• MuxError: マルチプレックス時のエラー。EncodeError / EmptyTracks / EmptySamples / PositionMismatch / MissingSampleEntry / AlreadyFinalized / TimescaleMismatch / MixedSampleEntries / NoSyncSamples / Overflow

デマルチプレックス (demux)

Mp4FileDemuxer - MP4 ファイルのデマルチプレックス

通常の MP4 ファイルからトラック情報とサンプルを時系列順に取得する。

Input は { position: u64, data: &[u8] }、RequiredInput は { position: u64, size: Option<usize> }。 required_input() で要求された範囲を供給し、DemuxError::InputRequired が返るまで繰り返す。 ストリーミング用途は想定していない（大きな mdat は要求されないが、moov は全体を渡す必要がある）。

use shiguredo_mp4::demux::{Input, Mp4FileDemuxer};

let mut demuxer = Mp4FileDemuxer::new();
while let Some(required) = demuxer.required_input() {
    // required.position と required.size に基づいてデータを読み込む
    let data: &[u8] = read_data(required.position, required.size);
    demuxer.handle_input(Input { position: required.position, data });
}
let tracks = demuxer.tracks()?;
while let Ok(Some(sample)) = demuxer.next_sample() {
    // sample.track, sample.timestamp, sample.data_offset, sample.data_size
}

Fmp4SegmentDemuxer - fMP4 セグメントのデマルチプレックス

初期化セグメント (ftyp + moov) とメディアセグメント (moof + mdat) を個別に処理する。

Sample.data_offset は handle_media_segment() に渡したバッファ先頭からの相対位置。

use shiguredo_mp4::demux::Fmp4SegmentDemuxer;

let mut demuxer = Fmp4SegmentDemuxer::new();
demuxer.handle_init_segment(&init_segment)?;
let tracks = demuxer.tracks()?;
let samples = demuxer.handle_media_segment(&media_segment)?;

Fmp4FileDemuxer - fMP4 ファイルのインクリメンタルデマルチプレックス

1 つのファイル内に並んだ複数セグメントを順番に処理する。Mp4FileDemuxer と同様に required_input() / handle_input() の Sans I/O ループで使う。

Mp4FileDemuxer と同様に、要求された範囲より多いデータ (ファイル全体など) を渡してもよい。 ただし Mp4FileDemuxer と異なり、ファイル全体を渡す場合も required_input() が Some を返す間は handle_input() を繰り返し呼ぶ必要がある。 入力が要求された範囲の終端より手前で終わっている場合は、入力の終端をファイルの終端とみなす。

制限: tfhd の base_data_offset にファイル先頭からの絶対オフセットを記録した形式には非対応。

Mp4FileKindDetector - MP4 / fMP4 の種別判定

moov 内の mvex ボックスの有無で MP4 か fragmented MP4 かを incremental に判定する。

use shiguredo_mp4::demux::{Mp4FileKind, Mp4FileKindDetector};

let mut detector = Mp4FileKindDetector::new();
while let Some(required) = detector.required_input() {
    // データを読み込んで供給
    detector.handle_input(Input { position: required.position, data });
    if let Some(kind) = detector.file_kind()? {
        match kind {
            Mp4FileKind::Mp4 => { /* 通常 MP4 */ }
            Mp4FileKind::FragmentedMp4 => { /* fMP4 */ }
        }
        break;
    }
}

demux の共通型

• TrackInfo: { track_id: u32, kind: TrackKind, duration: u64, timescale: NonZeroU32 }
  • duration / timestamp はタイムスケール単位。秒は timescale で割る
  • fMP4 では duration は init segment 由来で 0 になることが多い
• Sample<'a>: { track: &'a TrackInfo, sample_entry: Option<&'a SampleEntry>, keyframe: bool, timestamp: u64, duration: u32, data_offset: u64, data_size: usize, composition_time_offset: Option<i64> }
  • sample_entry は前のサンプルから変更がない場合 None (最初のサンプルは常に Some)
  • timestamp は DTS。PTS は timestamp + composition_time_offset
  • data_offset は file demuxer ではファイル先頭からの絶対位置、segment demuxer では入力バッファ先頭からの相対位置

マルチプレックス (mux)

Mp4FileMuxer - MP4 ファイルのマルチプレックス

複数トラックのサンプルを統合して MP4 ファイルを生成する。

基本的な使用フロー:

1. new() または with_options(Mp4FileMuxerOptions) でインスタンス生成
2. initial_boxes_bytes() のバイト列をファイルに書き込む (ftyp + 予約領域 + mdat ヘッダー)
3. サンプルデータをファイルに追記し、append_sample(&Sample) でメタデータを通知
4. finalize() で完了し、FinalizedBoxes::offset_and_bytes_pairs() の内容をファイルの該当オフセットに書き込む

Sample のフィールド (mux::Sample):

注意点:

• MP4 はサンプルのタイムスタンプを直接指定できず、累積尺で表現する。タイムスタンプのギャップは利用側で補完する (映像: 黒画像や尺調整 / 音声: 無音補完)
• 映像トラックの全サンプルが keyframe = false だと finalize() が NoSyncSamples を返す
• composition_time_offset は ctts ボックスに書き出される
• 詳細な制御が必要な場合は muxer を使わずボックスを直接構築する

use shiguredo_mp4::mux::{Mp4FileMuxer, Sample};

let mut muxer = Mp4FileMuxer::new()?;
let initial_bytes = muxer.initial_boxes_bytes();
// file.write_all(initial_bytes)?;

let sample = Sample {
    track_kind: TrackKind::Video,
    sample_entry: Some(sample_entry),
    keyframe: true,
    timescale: NonZeroU32::MIN.saturating_add(30 - 1),
    duration: 1,
    composition_time_offset: None,
    data_offset: initial_bytes.len() as u64,
    data_size: 1024,
};
muxer.append_sample(&sample)?;

let finalized = muxer.finalize()?;
for (offset, bytes) in finalized.offset_and_bytes_pairs() {
    // file.seek(SeekFrom::Start(offset))?;
    // file.write_all(bytes)?;
}

faststart 対応

Mp4FileMuxerOptions::reserved_moov_box_size に予約サイズを指定すると、moov をファイル先頭付近に配置する faststart 形式になる (FinalizedBoxes::is_faststart_enabled() で判定)。 estimate_maximum_moov_box_size(&[sample_count_per_track]) で概算サイズを計算できる。 予約サイズより moov が大きい場合は moov はファイル末尾に配置され、faststart は無効になる。

Mp4FileMuxerOptions のフィールド:

• reserved_moov_box_size: usize - faststart 用の moov 予約サイズ (デフォルト 0 = 無効)
• creation_timestamp: Duration - 作成時刻 (デフォルト UNIX エポック)
• audio_track / video_track / subtitle_track: TrackMetadata - mdhd.language / hdlr.name のメタデータ

TrackMetadata は { language: LanguageCode, name: Utf8String }。

Fmp4SegmentMuxer - fMP4 セグメントのマルチプレックス

初期化セグメント (ftyp + moov) とメディアセグメント (moof + mdat) を生成する。

注意点:

• Sample.data_offset は「ファイル全体の絶対位置」ではなく「今回のセグメントの mdat payload 領域の先頭からの相対位置」
• 同一セグメント内の同一トラックのサンプルは data_offset 昇順で連続配置する必要がある (1 track = 1 traf = 1 trun 前提)
• composition_time_offset は trun に書くため i32::MIN..=i32::MAX の範囲に限られる。負値と > i32::MAX の値の混在はエラー
• 映像トラックの全サンプルが keyframe = false でも NoSyncSamples にはならない (trun の SampleFlags と sidx の SAP 判定に使われる)
• mfra_bytes() は、実際にファイル先頭に配置する init segment を確定させた後で呼ぶこと (tfra の moof_offset は init segment のサイズ基準で計算される)

use shiguredo_mp4::mux::{Fmp4SegmentMuxer, Sample};

let mut muxer = Fmp4SegmentMuxer::new()?;
let segment = muxer.create_media_segment_metadata(&samples)?;
let init_segment = muxer.init_segment_bytes()?;
let mfra = muxer.mfra_bytes()?;

ボックス群 (boxes)

shiguredo_mp4::boxes モジュールに全ボックスが定義されている。 各ボックスは Encode / Decode / BaseBox を実装し、フィールドがすべて pub なので直接構築・参照できる。