dvb-si

DVB Service Information and MPEG-2 PSI for Rust — a typed parser and builder for every table and descriptor a DVB transport stream carries, cited clause-by-clause to the specs.

dvb-si turns the signalling inside an MPEG transport stream — the PAT/PMT that say what programmes exist, the NIT/SDT/BAT that name networks and services, the EIT that carries the programme guide, the TDT/TOT clock, the AIT that launches HbbTV apps, the DSM-CC carousels that deliver files and software updates — into typed Rust values, and turns those values back into byte-identical wire sections.

At a glance

Standards supported

Status: Full = every code the edition allocates is typed; Partial = some are (the tally counts allocated codes, so a single untyped one shows); Full (scoped) = typed, but only decoded inside the private_data_specifier / registration scope the standard requires (opt in via DescriptorRegistry); Not implemented = bytes are preserved but not typed. Every count above is generated by tools/gen-dvbsi-coverage.py from the crate's dispatch lists and CI fails if it goes stale.

The full per-code reference — every table_id, descriptor tag and tag extension with its standard, verified clause, Rust type and status, plus every code the standards define that is not implemented — is docs/COVERAGE.md.

What it does — and what it does not

It does

• Parse and serialize every DVB SI table (NIT, BAT, SDT, EIT p/f + schedule, TDT, TOT, RST, ST, SAT, DIT, SIT), the MPEG-2 PSI tables (PAT, CAT, PMT, TSDT), and the DVB companion tables (AIT, UNT, INT, MPE / MPE-FEC / MPE-IFEC, container, RCT, CIT, RNT, protection message, DFIS).
• Type every descriptor those tables carry: all of EN 300 468 Table 12, the MPEG-2 systems descriptors, every EN 300 468 extension descriptor, the MPEG-H 3D audio descriptors, the AIT descriptor namespace, and opt-in regional descriptors (NorDig, EACEM/D-Book, China GY/T and T/AI AVS2/AVS3, T/UWA).
• Decode DVB text (EN 300 468 Annex A: default Latin, ISO 8859-n, UCS-2, KS X 1001, GB-2312, Big5, UTF-8) and DVB time (MJD + BCD, including the 2038 wrap rule).
• Pump sections out of a TS (SiDemux: PID filtering, CRC check, version gating), collect multi-section tables (collect), build an EPG (epg::EpgStore), and reassemble DSM-CC data and object carousels into modules and files (carousel).

Who uses it: TS analysers and monitoring probes, set-top-box and middleware stacks, playout and multiplexers that must emit SI, EPG and channel-list tools, test-stream generators, and anything that needs to reason about a broadcast stream's signalling.

It deliberately does not

• Frame TS packets or reassemble/packetise sections itself — that is mpeg-ts, which dvb-si uses.
• Touch elementary-stream payloads (video/audio/subtitles) — see mpeg-pes, dvb-subtitle, dvb-vbi.
• Descramble, talk to a CAM, or interpret CA-system-private ECM/EMM payloads — see dvb-csa, dvb-ci.
• Measure stream conformance (TR 101 290) — that is dvb-conformance.
• Guess. A field whose syntax lives in a standard that is not vendored stays a byte slice and is documented as such; codes a standard allocates but the crate does not type are listed as Not implemented in docs/COVERAGE.md, never silently half-decoded.

Quick start

[dependencies]
dvb-si = "12"

Parse one section, walk it, serialize it back

The bytes below are the PAT of a real French TNT capture (5°W, 12 732 MHz V) committed in this repository.

use broadcast_common::{Parse, Serialize};
use dvb_si::tables::pat::PatSection;
use dvb_si::tables::AnyTableSection;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let section: [u8; 36] = [
        0x00, 0xB0, 0x21, 0x00, 0x06, 0xE5, 0x00, 0x00, 0x00, 0x00, 0xE0, 0x10,
        0x06, 0x01, 0xE0, 0x64, 0x06, 0x06, 0xE2, 0x58, 0x06, 0x08, 0xE1, 0xF4,
        0x06, 0x09, 0xE2, 0xBC, 0x06, 0x0A, 0xE0, 0xC8, 0x98, 0xF3, 0xCC, 0x2D,
    ];

    // Typed parse of a section you already know the type of …
    let pat = PatSection::parse(&section)?;
    assert_eq!(pat.transport_stream_id, 6);
    for entry in &pat.entries {
        // program_number 0 points at the NIT, the others at PMTs.
        println!("program {:#06x} -> PID {}", entry.program_number, entry.pid);
    }

    // … or dispatch on table_id when you don't.
    assert!(matches!(AnyTableSection::parse(&section)?, AnyTableSection::PatSection(_)));

    // Every parser has a symmetric serializer: the round trip is byte-identical.
    let mut out = vec![0u8; pat.serialized_len()];
    pat.serialize_into(&mut out)?;
    assert_eq!(out, section);
    Ok(())
}

Pump a whole capture: services, PMT streams, descriptors

use dvb_si::demux::SiDemux;
use dvb_si::descriptors::AnyDescriptor;
use dvb_si::tables::AnyTableSection;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Any aligned 188-byte TS works; this is the capture committed in this repository.
    let ts = std::fs::read(concat!(
        env!("CARGO_MANIFEST_DIR"),
        "/../fixtures/dvb-si/tnt-5w-12732v-isi6-10s.ts"
    ))?;

    // Follows the PAT to every PMT PID; emits each *changed* CRC-valid section once.
    let mut demux = SiDemux::builder().build();
    let mut services = Vec::new();
    for packet in ts.chunks_exact(188) {
        for event in demux.feed(packet) {
            match event.table_section()? {
                AnyTableSection::SdtSection(sdt) => {
                    for service in &sdt.services {
                        for d in service.descriptors.iter().flatten() {
                            if let AnyDescriptor::Service(svc) = d {
                                // Annex A text decodes on demand.
                                services.push(svc.service_name.decode().into_owned());
                            }
                        }
                    }
                }
                AnyTableSection::PmtSection(pmt) => {
                    for stream in &pmt.streams {
                        let tags: Vec<&str> =
                            stream.es_info.iter().flatten().map(|d| d.name()).collect();
                        println!("PID {} {} {:?}", stream.elementary_pid, stream.stream_type, tags);
                    }
                }
                _ => {}
            }
        }
    }
    assert!(!services.is_empty());
    println!("services: {services:?}");
    Ok(())
}

More: examples/build_and_parse_pat.rs, examples/list_services.rs (cargo run -p dvb-si --example list_services), and the dvb-tools CLI (dvb-tools dump file.ts --json) for a complete analyser built on this crate.

Which API do I use?

Private descriptors in their scope

use dvb_si::descriptors::nordig::NordigLogicalChannelV1;
use dvb_si::descriptors::{AnyDescriptor, DescriptorLoop, DescriptorRegistry};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // private_data_specifier = 0x00000029 (NorDig), then a NorDig LCD v1 (tag 0x83):
    // service 0x0001, visible, LCN 5 (NorDig Unified Requirements v3.2.2 Table 12.12).
    let loop_bytes = [0x5F, 0x04, 0x00, 0x00, 0x00, 0x29, 0x83, 0x04, 0x00, 0x01, 0xC0, 0x05];
    let descriptors = DescriptorLoop::new(&loop_bytes);

    // Without opting in, tag 0x83 stays Unknown (it is private) …
    let plain: Vec<_> = descriptors.iter().collect::<Result<_, _>>()?;
    assert!(matches!(plain[1], AnyDescriptor::Unknown { tag: 0x83, .. }));

    // … with the NorDig registry it decodes, because the PDS in front scopes it.
    let mut registry = DescriptorRegistry::new();
    registry.with_nordig_lcn();
    for d in descriptors.iter_with(&registry) {
        if let AnyDescriptor::Other { value, .. } = d? {
            let lcd = value.downcast_ref::<NordigLogicalChannelV1>().ok_or("not NorDig")?;
            assert_eq!(lcd.entries[0].logical_channel_number, 5);
        }
    }
    Ok(())
}

Feature flags

dvb-si = { version = "12", default-features = false }   # no_std + alloc, bring your own sections

Detailed coverage

The generated tables above summarise; the per-code lists live in docs/COVERAGE.md:

• Tables — every table_id with standard, verified clause, Rust type and status.
• Descriptors — MPEG-2 (0x00–0x3F), DVB (0x40–0x7F), DVB extension (0x7F / tag_extension), MPEG-2 extension (0x3F / extension_descriptor_tag), private/regional (with their PDS scope and DescriptorRegistry opt-in), AIT, INT, UNT, DSM-CC carousel and RNT-scoped descriptors.
• DSM-CC carousel, Annex A text charsets, time handling and the higher layers.
• Not implemented — every code the vendored standards allocate that dvb-si does not type.
• Citation cross-check — module docs whose clause number disagrees with the verified edition.

Every count and row is generated by tools/gen-dvbsi-coverage.py from the crate's dispatch lists (declare_tables!, declare_descriptors!, declare_extension_bodies!, declare_ait_descriptors!) and module citations, joined with the hand-transcribed allocation lists in docs/coverage/allocations.tsv. The docs_coverage_drift test fails CI when any of it is stale. The spec transcriptions behind every layout are indexed in docs/README.md.

Design notes

• Zero-copy parse, symmetric serialize. Every wire structure implements broadcast_common::Parse<'a> (borrowing from the input — descriptor loops, names and selector tails are &'a [u8] / DescriptorLoop<'a> / DvbText<'a>) and broadcast_common::Serialize (serialized_len + serialize_into). Every type has a round-trip test (parse → serialize → byte-identical; serialize → parse → equal), and tests/real_capture_byte_identity.rs re-serializes every descriptor found in the real-capture archive and requires byte identity.
• Reserved bits: parse tolerant, serialize preserving. Any value of a reserved / reserved_future_use / reserved_zero_future_use run is accepted on parse, captured in a typed, spec-named field, and re-emitted verbatim — so a sender that deviates from the edition still round-trips byte-identically, with no raw passthrough blob. Values built with new(..) / Default carry the governing edition's fill (ones for reserved, zeros for reserved_zero_future_use, documented per-field exceptions). Evidence per field: docs/reserved-bits-edition-audit.md.
• Checked serializers. A value wider than its wire field is Error::FieldOverflow, never masked into a different, valid-looking value. PIDs are mpeg_ts::pid::Pid.
• One dispatch list per namespace. AnyTableSection, AnyDescriptor, ExtensionBody and AnyAitDescriptor are generated from a single declarative list (declare_*!), with a drift test pinning each code to its type's TABLE_ID_RANGES / TAG / TAG_EXTENSION const — the dispatcher cannot drift from the implemented set, and neither can these docs.
• Labels. Every spec/field enum has name() (the spec token, "reserved" for reserved arms) and a Display generated by broadcast_common::impl_spec_display!; a label_coverage test enforces it.
• #[non_exhaustive] on public structs and enums that can grow, with new(..) constructors, so additions are not breaking.
• no_std + alloc with default features off; never panics on hostile input (fuzzed; bounded collectors and EPG store).
• Spec grounding. Every module's //! doc names the standard, clause and tag; every hex literal outside tests is a named constant.

Related crates

Upgrading

MIGRATION-4.0.md (3.x → 4.0: *Section names, AnyTableSection, table_section(), multi-section collection), MIGRATION-3.1.md, MIGRATION-2.0.md; per-release detail in CHANGELOG.md.

MSRV and licence

MSRV 1.95.0 (the workspace rust-version; CI tests it). Licensed under either of MIT or Apache-2.0, at your option. The vendored TSDuck registry data in registries/ is BSD-2-Clause (see registries/README.md).