ECP-0033: Deterministic x264 + CMAF(fMP4) Segment Mode

Summary

Add an optional stream mode that publishes HLS-compatible CMAF-style fragmented MP4 segments (.m4s) encoded with single-threaded libx264 + AAC, alongside a separate init segment (init.mp4). The init segment is published on a dedicated MoQ side-track so subscribers can start playback without out-of-band files.

This is an incremental step toward a MoQ-native media pipeline while keeping browser playback practical via standard HLS fMP4 semantics.

Goals

Provide a "mature codec path" for experimentation: libx264 + AAC.
Make output more browser-friendly than raw MPEG-TS while staying simple.
Preserve deterministic encoding constraints where feasible:
- single-threaded encoder
- +bitexact flags
- fixed GOP
Keep the change reversible:
- default remains raw TS chunk publication
- CMAF mode is opt-in via CLI

Non-Goals

Full CMAF compliance validation across players.
Multi-track audio language selection.
End-to-end determinism across independent antennas (this requires timebase normalization and additional constraints).
MoQ wire-level media standardization (that belongs in a later ECP).

Design

Publisher (ec-node moq-publish) adds --encode {ts|cmaf}.
In cmaf mode:
- ingest bytes from the source (TS file/HDHR/iptv adapter)
- invoke ffmpeg to encode and segment to HLS fMP4:
  - writes init.mp4 and segment_%06d.m4s
- publish:
  - init.mp4 as a single MoQ object on --init-track (default: init)
  - .m4s segments as MoQ objects on the main track
- all MoQ tracks (objects, init, manifests) are created before the broadcast is published to avoid implementation quirks where late-added tracks are not deliverable
- manifests remain per-epoch over the segment objects only (init is out-of-manifest for now)
Subscriber (ec-node moq-subscribe) adds:
- --container {ts|cmaf}
- --subscribe-init to fetch init.mp4 from --init-track
- local output becomes:
  - index.m3u8 with #EXT-X-MAP:URI="init.mp4"
  - init.mp4
  - rolling window of segment_*.m4s

Rationale

fMP4 (CMAF-style) is broadly supported by modern HLS implementations and aligns with future MoQ media layouts.
libx264 is stable and widely available, making it a pragmatic baseline for determinism experiments.
Publishing init as a side-track avoids special cases in the primary segment stream and keeps the UI/receiver model "a stream is a stream".

Risks

MP4 muxers can embed non-deterministic metadata (timestamps/brands). We mitigate by:
- +bitexact flags and single-threaded encoding
- stripping container metadata where feasible (future follow-up may be needed)
Segment boundaries are time-based and depend on timestamps/keyframes; cross-antenna byte equality is not guaranteed yet.

Rollout

Land CMAF mode behind --encode cmaf and --container cmaf.
Add an ignored HDHomeRun E2E test that exercises split-source mesh in CMAF mode.

3 KiB Raw Blame History