Zeayii.Infrastructure.Media.Container 0.0.17

Zeayii.Infrastructure.Media.Container

English | 简体中文

Organization: zeayii
Project: vexo

ISO BMFF / MP4 / WebM / EBML structural parsing and fragment modeling library
Targeted for players, downloaders, repackagers, DRM/forensics toolchains

Overview

Zeayii.Infrastructure.Media.Container delivers high-performance, AOT/trimming-friendly media container parsing. It focuses on structural understanding rather than decoding: identifying box/element boundaries, extracting fragment metadata, and feeding reliable structure hints to upper pipelines (download, decrypt, remux, manifest generation).

Highlights

• Streaming MP4 / ISO BMFF parsing: Incremental feed with registered callbacks for moov/moof/mdat/pssh and more; works with fragmented MP4, CMAF, DASH segments.
• Fragment modeling: Track/init/media fragment builders (Fragments directory) that map parsed boxes into consumable metadata.
• EBML/WebM support: EBML primitives (VarInt/UInt/Int) and WebM element models for future Matroska/WebM timeline parsing.
• AOT-first: No reflection or dynamic loading; exception-free hot paths to suit constrained runtimes.
• Zero-copy buffering: ByteQueue relies on ArrayPool<byte> and a sliding window design to minimize GC and large memory moves.
• On-demand segment-duration probing: Added MP4/WebM duration probing (MP4/Probing, WebM/Probing) that runs only when explicitly invoked by callers, not on the default hot path.

Layout

• Common/IO: Foundational I/O utilities (ByteQueue, BytesWriter) providing zero-copy buffers for streaming scenarios.
• Ebml: EBML types, parsing context, and exception model supporting WebM/Matroska structural reads.
• MP4:
  • Boxes: ISO BMFF boxes (File/Track/Fragment/Encryption) grouped by hierarchy for structural detection and field reads.
  • Core: Generic box parser (Parser, ParseContext, ParseBox) with handler registration, container recursion, and mdat events.
  • Fragments: Init/fragment modeling and build states that translate moov/moof/stbl insights into track/sample layouts.
• WebM: WebM elements and cue models built atop EBML primitives.
• Core/Timing: Duration probe result models and an optional container detector (MediaContainerTypeDetector).

Design tenets

• Narrow scope: Structural parsing and metadata building only; no media decode, DRM decryption, or file persistence.
• Streaming-first: Parsers ingest incremental spans; ParseContext tracks global offsets/states (e.g., ParsingBoxes, EmittingSamples) so callers can consume mdat payload as soon as the event fires.
• Pluggable handlers: Parser.Box/FullBox/SampleEntryBox register only the boxes you care about; unregistered types are skipped with zero payload copy.
• Robustness: Strict length/state checks; throws instead of guessing incomplete structures. Encryption-related boxes (pssh/senc/saiz/saio, etc.) retain offsets for downstream decryptors.
• Compatibility: Targets net10.0, trimmable, and free of dynamic code.

Key flow

1. Context setup: Create a ParseContext, configure buffer sizing and callbacks.
2. Register handlers: Choose the boxes you need (moov/moof/mdat/pssh, etc.).
3. Feed data: Repeatedly call Parser.Parse(ReadOnlySpan<byte>) with network/file chunks.
4. React to events:
   • MdatBegin: Discover media data start/length.
   • BoxHandler: Handle payload when a registered box is fully read (zero-copy view).
   • Use ParseChildren to recurse into container boxes.
5. Fragment modeling: Combine Fragments build state to produce init/media fragment descriptions (tracks, timestamps, sample layouts).

Optional Segment Duration Probing

• Mp4SegmentDurationProbe: call TryLoadInit first, then ProbeSegment for media chunks; prioritizes vide tracks and falls back to soun.
• WebMSegmentDurationProbe: optionally call LoadInit, then ProbeSegment; prioritizes video tracks and falls back to audio.
• MediaContainerTypeDetector: intended only as a fallback when callers do not already know the container type, so common download flows avoid extra detection overhead.

Collaboration with other layers

• Task metadata: Works with task/stream/fragment models from Zeayii.Vexo.Assembly.Abstractions.
• Manifest extraction: Zeayii.Infrastructure.Streaming.Manifest consumes this module for fMP4 parsing and sidx/range handling when expanding DASH/HLS manifests.
• Pipeline fit: Typical chain—download → Media.Parser → fragment modeling → decrypt/merge/persist.

Extension tips

• New box: add a definition under MP4/Boxes and register a handler in Parser.
• New EBML element: extend Ebml/Types and WebM/Elements with models and parsing logic.
• Performance tuning: Adjust ByteQueue initial size to your I/O pattern; register only necessary boxes to reduce payload copying.

Development & testing

• Build: dotnet build Zeayii.Vexo.Assembly.sln (use an SDK that supports net10.0).
• Static analysis: Enable IDE analyzers and nullable checks to match project settings.
• Real fixtures: Media.Tests/TestData/real-media-cache now stores raw binary .mp4 fixtures and tests read bytes directly (no Base64 text decoding).
• Samples: Author small console harnesses to validate streaming parsing and event timing.

License

This module follows the repository root LICENSE. Ensure compliance when redistributing or embedding.