transmux

Any-to-any media container muxing hub. Demux TS, fMP4/CMAF, progressive MP4, MPEG-PS, WebM/Matroska, FLV or RTMP into one neutral in-memory IR (Media / Track / Sample), and mux from it to CMAF/fMP4, progressive MP4, TS, Matroska, FLV, RTMP, HLS (CMAF, TS and low-latency), DASH (including low-latency) or Smooth Streaming.

What it does / what it does not

Does: parse containers into one IR and write that IR into any other container, so every input composes with every output (one documented exception below). Around that it provides streaming segmenters (CMAF, LL-HLS parts, TS-HLS, LL-DASH chunks), IR timeline transforms (rebase, offset, discontinuity gap, splice and concat for SSAI, trick-play track derivation), CENC and CBCS decrypt and encrypt with DASH and HLS DRM signalling, HLS Sample-AES, RTP and RTCP packetising with SDP helpers, KLV metadata, and a structural fMP4/CMAF conformance validator. A cli-gated transmux binary wires it into a packager.

Does not: encode or decode media. It parses codec config headers (SPS/PPS/VPS, AAC AudioSpecificConfig, AC-3 BSI, EBML and box config) only far enough to build container boxes and derive metadata (dimensions, profile, sample rate, the codecs= string). Compressed samples are opaque bytes::Bytes copied through byte for byte. It also does not do ABR ladders, transcoding, DRM licence acquisition, or HLS/DASH delivery (see hls-runtime and multimux). HLS playlist syntax lives in broadcast-hls; transmux's ts_hls and ll_hls segmenters produce container bytes and playlist values and depend on it.

The one exception to any-to-any: WebM's VP8 and Vorbis tracks have no ISOBMFF sample entry in this crate, so they cannot enter the fMP4/CMAF, progressive-MP4, DASH, HLS or Smooth mux path (Error::UnsupportedCodec); only WebM -> WebM or Matroska round-trips them. Other limits per output are in the matrix below.

Standards supported

Editions: where a spec is vendored in private/specs/ the edition is verified against private/specs-md/INDEX.md; otherwise the edition is the one the source module cites, marked "as cited".

Input x output matrix

Rows are the demux (Unpackage) inputs, columns the mux (Package) outputs. A cell is "yes" when every codec the IR can carry from that input reaches that output, or lists the codecs that are rejected or dropped.

Notes. The TS-carriable codecs are AVC, HEVC, MPEG-2 video, AAC, MPEG-1/2 audio, AC-3, E-AC-3, DTS, MPEG-H and opaque Data; VVC, AV1, VP9, Opus, FLAC, AC-4, subtitles, VP8 and Vorbis have no TS mapping in this crate, and TsMux drops such a track rather than erroring. The MKV mux carries AVC, HEVC, VP9, VP8, AV1, AAC, Opus, Vorbis, AC-3 and E-AC-3. FlvMux and RtmpMux carry only AVC video and AAC audio and reject any other codec with FlvError::UnsupportedCodec; SmoothPackager likewise rejects everything but H.264, AAC-LC and text. FlvDemux skips non-AVC video and non-AAC audio with no track and no error, whereas TsDemux never drops a stream (unknown stream types become opaque Data tracks). Where a cell names only some codecs, whether a track outside that set is rejected or dropped is per output (for TS it is dropped); this README does not enumerate it for MKV. Live producers also exist: Segmenter (CMAF), LlHlsSegmenter, StreamingTsHlsSegmenter, LlSegmenter / LlDashPackager.

MPEG-H over TS: the synthesized MPEG-H_3dAudio_descriptor (H.222.0 Table 2-121) writes interactivityEnabled = 0 and compatibleProfileSetsPresent = 1 (no compatible-set list) because the IR carries neither. The descriptor's 6-bit referenceChannelLayout is taken from the mhaC byte; a value above 0x3F cannot be represented there and is written as 0 (unspecified) instead of failing the mux.

Codec matrix

Header parse and the container box only; no encode or decode.

Encryption and DRM: cenc and cbcs decrypt (CencDecryptor, KeyMap) and encrypt (CencEncryptor, which fills Track::encryption so protect_init_segment and protect_media_segment emit sinf/senc/saio/saiz). pssh init data for Widevine (protobuf), PlayReady (PRO and WRMHEADER, std) and FairPlay (skd://) in drm. DASH ContentProtection is derived from Track::encryption; HLS EXT-X-KEY comes from broadcast_hls::cenc_ext_x_key. Sample-AES and whole-segment AES-128 are in sample_aes (feature sample-aes).

Features

Quick start

Demux a real H.264 plus AAC broadcast capture once, then mux the same IR to CMAF, a DASH manifest and back to TS:

use broadcast_common::{Package, Unpackage};
use transmux::{CmafMux, DashPackager, Media, TsDemux, TsMux};

let ts = std::fs::read("../fixtures/ts/h264_aac.ts").unwrap();
let media: Media = TsDemux::new().unpackage(&ts[..]).unwrap();
assert!(media.tracks.len() >= 2, "an H.264 video and an AAC audio track");

let cmaf: Vec<u8> = CmafMux::default().package(&media).unwrap();
assert!(cmaf.len() > 1000);

let mpd: String = DashPackager::default().package(&media).unwrap();
assert!(mpd.contains("<MPD"));

// And back: TsMux is the byte-level inverse of TsDemux.
let ts_again: Vec<u8> = TsMux::default().package(&media).unwrap();
let again = TsDemux::new().unpackage(&ts_again[..]).unwrap();
assert_eq!(again.tracks.len(), media.tracks.len());

For a live source Segmenter owns the segment-cutting state machine (push samples, take_ready segments, flush at end of stream); StreamingTsDemux is the incremental demux (feed, poll_event, finish) - drain poll_event after every feed: the event queue is unbounded and only poll_event empties it (opt-in with_max_degraded_events caps the InputDegraded diagnostics). Runnable programs: transmux_any_to_any and ssai_ad_stitch (cargo run -p transmux --example <name>).

Command-line packager (cli feature)

$ cargo install transmux --features cli
$ transmux in.ts -o out.cmaf                                  # TS to CMAF, format inferred
$ transmux in.mp4 -o out.m3u8 -f hls --segment-duration 4     # MP4 to CMAF-HLS, 4 s segments
$ transmux in.ps -o out.mpd -f dash --ll                      # PS to low-latency DASH
$ transmux enc.mp4 -o dec.mp4 -f progressive --decrypt --key <KID>:<KEY>

transmux --help (abridged):

Usage: transmux [OPTIONS] --output <PATH> [IN]

  -i, --input <PATH>          Input media file (alternative to the positional <IN>)
  -o, --output <PATH>         Output path (file, or the playlist/manifest path for HLS/DASH)
  -f, --format <FORMAT>       cmaf | hls | ts-hls | dash | ts | progressive
                              (inferred from the extension: .m3u8 hls, .mpd dash, .ts ts, .cmaf cmaf, .mp4 progressive)
      --segment-duration <SECS>  Target segment duration in seconds [default: 6]
      --ll                    Low-latency variant where supported (LL-DASH)
      --utc-timing-url <URL>  DASH only: advertise MPD/UTCTiming with this URL
      --tracks <IDS>          Restrict to these track IDs (comma-separated)
      --decrypt               Decrypt CENC input (requires the cenc feature)
      --key <KID:KEY>         Content key, repeatable, only with --decrypt

Input detection uses container-probe, which scores structural evidence over the leading bytes (MPEG-TS including 192-byte M2TS and mid-packet captures, ISOBMFF, MPEG-PS, WebM and Matroska, FLV). A container it recognises but this CLI has no demuxer for (MXF, WAV, Ogg, ADTS, MP3, Annex B) is reported as unsupported, and an inconclusive probe asks for the format to be given explicitly.

What is implemented, by area

• Hub IR (ir): Media, Track, TrackSpec, CodecConfig, Sample, DemuxEvent. Sample dts and pts are absolute Option<i64> ticks in the track timescale, duration is Option<u32>, data is bytes::Bytes. 33-bit MPEG-2 and 32-bit RTP wrap is unrolled once at the demux edge. Typed ids TrackId(u32) and ProgramNumber(u16); TrackSpec::source_pid is Option<mpeg_ts::pid::Pid>. TrackSpec::display: Option<DisplayGeometry> carries a video track's display geometry (coded size and the cropped output rectangle output_rect (H.264 frame cropping / H.265 conformance window), plus the H.265 default_display_rect suggestion; the SPS VUI sample aspect ratio as a typed AspectRatioIdc with sample_aspect_ratio() -> Option<(u16, u16)>; overscan_appropriate; and video_signal with video_format, the full-range flag and a typed colour description — ColourPrimaries / TransferCharacteristics / MatrixCoefficients, so a player knows BT.709 from BT.601 without guessing, plus full_range() and the spec's inferred-default accessors), derived by TrackSpec::new from the first SPS in the avcC/hvcC, so an anamorphic SD picture (SAR 64:45 or 16:11) can be shown at its correct shape. The per-picture state is Sample::display: Option<Arc<DisplayInfo>> (every video access unit of the TS and PS demuxers carries the geometry of the SPS its slices activate — None means "not tracked", never "unchanged"), and a change is announced by DemuxEvent::DisplayChanged { display, changed: DisplayChangeSet, dts, pts, random_access, .. }, placed before the first sample that shows the new shape and sharing its Arc, preceded by TrackUpdated when the codec-config bytes changed at the same access unit; both survive batch Media, IR transforms and a media-plane Trunk.
• Demux: TsDemux and StreamingTsDemux (PPS tracked by id, E-AC-3 waits for a whole access unit, open-GOP random access points marked; an E-AC-3 probe resolves early when its frame chain breaks or after 16 chained frames, and a PID still probing after 512 access units no longer holds back later PIDs, so a damaged capture still yields every track), Fmp4Demux, ProgressiveDemux, PsDemux, WebmDemux, FlvDemux, RtmpDemux. Damaged units no longer abort a one-shot demux: they are reported in Media::degraded as InputDegradation::MalformedUnit; a TS with broken sync bytes, garbage between packets, a truncated tail, transport errors or continuity gaps reports SyncLoss, TruncatedPacket, TransportError or ContinuityGap. Media::degraded_at carries the PID and packet index of each entry (TS), so damage on an unused data PID can be told from damage on a kept track. ContinuityGap is per PID, payload-bearing non-null packets only, ISO/IEC 13818-1 §2.4.3.3: a counter jump, a same-counter packet that is not a byte-identical repeat (PCR excepted), or any identical repeat beyond the one legal duplicate (one entry per excess packet); a signalled discontinuity_indicator suppresses the entry.
• Mux and packaging: CmafMux, ProgressiveMux, TsMux, MkvMux, FlvMux, RtmpMux, HlsPackager, TsHlsPackager, DashPackager (static and live, auto ContentProtection), LlDashPackager, SmoothPackager, build_init_segment, build_media_segment.
• Live segmenters: Segmenter, LlHlsSegmenter (parts before the segment closes), StreamingTsHlsSegmenter (rolling playlist, with_start_sequence, TsContinuity), LlSegmenter.
• Transforms: Repackage, rebase_to_zero, apply_offset, insert_discontinuity_gap, concat, splice_insert (keyframe-snapped, returns SpliceResult), derive_iframe_track.
• DASH details: SegmentTimeline::resolve and resolve_in_period (media-timeline S@t less presentationTimeOffset), dash::xs_duration, dash_parse, base_url.
• RTP: RtpPacketiser, RtpDepacketiser, RtpStreamDepacketiser, rtp_sdp helpers, KLV over RTP.
• Validation: validate_init_segment, validate_media_segment, validate_cmaf_track yielding ConformanceIssue.
• Helpers: frag_offsets (the single trun/tfhd sample-offset resolver shared by demux, decrypt and validator), NAL conversion Annex B and length-prefixed, is_keyframe_nal.

Design notes

Container only, never a codec. Sans-IO pull and push APIs, zero-copy sample fan-out (Bytes), symmetric Parse/Serialize for every box with real-fixture round-trip gates, typed errors (#[non_exhaustive], FieldOverflow for checked-width fields, UnsupportedCodec), large boxes written in the 64-bit largesize form past 4 GiB, hostile-input hardening (aggregate trun budget, largesize truncation guards) with fuzz targets, and content keys wiped on drop. A lexical no-hand-roll guard and a 2^33 clock guard apply.

Related crates

Depends on broadcast-common (Package/Unpackage), broadcast-hls, mp4-emsg, mpeg-ts, mpeg-pes, mpeg-ps, rtp-packet, rtcp-packet, dvb-si (typed PMT audio metadata) and optionally container-probe. Consumed by media-plane (IR and TrackId), hls-runtime, rtmp-runtime (dev), multimux and media-doctor. Python bindings (transmux-py) live outside the workspace.

MSRV and licence

MSRV 1.95.0. Licensed under MIT OR Apache-2.0.