mpeg-ts

MPEG-2 Transport Stream framing: TS packets, adaptation fields, PCR, PSI section reassembly and packetisation, byte-stream resync.

What it does / what it does not

mpeg-ts is the lowest layer of the workspace's broadcast stack. It turns a stream of bytes into typed 188-byte transport packets (and back), and it turns the payload of PSI/SI PIDs into complete sections (and back). It is for anyone who needs raw TS framing without the SI/descriptor stack: demuxers, muxers, stream repair tools, analyzers, embedded firmware.

It does:

• parse and serialize the 4-byte TS header and the adaptation field (every bit, including stuffing and reserved bits, so parse -> serialize is byte-exact on real streams);
• reassemble PSI/SI sections from TS payloads (pointer_field, multi-packet, several sections per packet) and packetise sections back, with continuity counters and 0xFF stuffing;
• schedule repeating SI tables into a TS packet stream (SiMux);
• recover packet alignment from a raw byte stream (188- and 204-byte strides);
• accumulate PUSI-delimited payloads on non-PSI PIDs (e.g. DASH emsg);
• provide an owned, mutable packet type for in-place edits (continuity counter, PCR).

It deliberately does not: parse PES (see mpeg-pes), interpret PSI/SI table bodies or descriptors (see dvb-si), descramble (see dvb-csa), check stream conformance (see dvb-conformance), or do any I/O.

Standards supported

Feature flags

serde is opt-in and off by default; enable it explicitly:

mpeg-ts = { version = "0.7", features = ["serde"] }

The crate is #![no_std] + alloc and #![forbid(unsafe_code)]; default-features = false builds on bare-metal targets that have a heap.

[dependencies]
mpeg-ts = "0.7"
# embedded:
# mpeg-ts = { version = "0.5", default-features = false }

Quick start

Parse a real PAT packet (extracted from the committed m6-single.ts fixture) and recover its section:

use mpeg_ts::ts::{SectionReassembler, TsPacket};
use mpeg_ts::pid::well_known;

// PID 0x0000, PUSI set, payload-only; PAT section: transport_stream_id 1, one program.
let mut raw = [0xFFu8; 188];
raw[..21].copy_from_slice(&[
    0x47, 0x40, 0x00, 0x10, // sync, PUSI + PID 0, payload only, CC 0
    0x00,                   // pointer_field
    0x00, 0xB0, 0x0D, 0x00, 0x01, 0xC1, 0x00, 0x00, 0x04, 0x01, 0xE0, 0x64, // PAT
    0xF9, 0xB4, 0x63, 0xEF, // CRC_32
]);

let pkt = TsPacket::parse(&raw)?;
assert_eq!(pkt.header.pid, well_known::PAT);
assert!(pkt.header.pusi);

let mut reasm = SectionReassembler::default();
reasm.feed(pkt.payload.expect("payload"), pkt.header.pusi);
let section = reasm.pop_section().expect("one complete section");
assert_eq!(section[0], 0x00); // table_id = PAT
assert_eq!(u16::from_be_bytes([section[3], section[4]]), 1); // transport_stream_id
# Ok::<(), mpeg_ts::Error>(())

Build and edit packets without manual byte twiddling:

use mpeg_ts::ts::{Pcr, TsPacket};
use mpeg_ts::{pid::{well_known, Pid}, OwnedTsPacket};

let null = OwnedTsPacket::null_packet(3);
assert_eq!(TsPacket::parse(&null)?.header.pid, well_known::NULL);

let mut raw = OwnedTsPacket::serialize_with_payload(Pid::try_new(0x0100).unwrap(), false, 0, &[])?;
OwnedTsPacket::set_continuity_counter(&mut raw, 7);
assert_eq!(TsPacket::parse(&raw)?.header.continuity_counter, 7);

let mut pcr_pkt = [0x47u8; 188];
pcr_pkt[3] = 0x20; // adaptation only
pcr_pkt[4] = 7;    // adaptation_field_length
pcr_pkt[5] = 0x10; // PCR flag
OwnedTsPacket::set_pcr(&mut pcr_pkt, Pcr::from_27mhz(27_000_000))?;
let parsed = TsPacket::parse(&pcr_pkt)?;
assert_eq!(parsed.adaptation_field().unwrap()?.pcr.unwrap().as_27mhz(), 27_000_000);
# Ok::<(), mpeg_ts::Error>(())

Runnable examples: cargo run -p mpeg-ts --example demux, --example iter_packets, --example edit_packet.

What is implemented

Typed PIDs: Pid is used everywhere (TsHeader::pid, the mux types, PusiReassembler, OwnedTsPacket). Pid::try_new / TryFrom<u16> reject values above 0x1FFF; Pid::new / Pid::from_wire_masked mask bits already taken from the wire; there is deliberately no From<u16>. Pid implements UpperHex/LowerHex and is serde(transparent).

Design notes

• Zero-copy, symmetric. Parsed types borrow the input; every wire type has a matching serializer. tests/it/fixture_roundtrip.rs and tests/it/af_extension_roundtrip.rs re-serialize every adaptation field of every committed .ts fixture and require byte-identical output.
• No information dropped. Adaptation-field stuffing, pcr_reserved / opcr_reserved, splice marker bits and every extension reserved bit are carried; the structs are #[non_exhaustive] with new() / Default (reserved bits default to 1, per the spec convention).
• Checked widths. Serializers use broadcast_common::len checked helpers (FieldOverflow), never a silent mask.
• Shared clock arithmetic. PCR and the marker-bit timestamp come from broadcast_common::clock33.
• Label convention. Public field enums expose name() and Display (workspace-guards/tests/guards/label.rs guards it).

Related crates

Depends on broadcast-common. Built on by dvb-si (tables/descriptors), mpeg-pes, dvb-stream, dvb-conformance, ts-fix, media-doctor and transmux. Spec citations: docs/. Users migrating from dvb-si <= 7.x: ts, mux, resync and pid moved here unchanged in name.

MSRV 1.95.0. Licensed under MIT or Apache-2.0, at your option.