broadcast-common

The foundation crate of the rust-broadcast workspace: the symmetric Parse/Serialize traits, CRC-32/MPEG-2, BCD and MJD time codecs, bit-field I/O, the 33-bit/PCR clock arithmetic, checked field-width helpers, and the container-mux and streaming-stage traits every sibling crate builds on.

What it does / what it does not

Nearly every crate in the workspace depends on broadcast-common, so it holds only the code that must be defined exactly once: the traits that make every wire type parse/serialize symmetric, the small codecs the DVB/MPEG family shares (CRC, BCD, MJD, odd parity, hex), the clock arithmetic that PTS/DTS, PCR, SCTE-35 and SRT all need, the range-checking helpers serializers use instead of silent masking, and the vocabulary traits of the muxing hub (Unpackage/Package/Encrypt/Decrypt) and the incremental Stage driver. Use it directly when you implement a new wire type in the workspace's style or need one of those primitives.

It deliberately has no shared error enum (each crate owns a domain Error, reached through type Error on the traits), no CRC-8 (only dvb-bbframe needs it), no concrete media or codec types, and no heavy dependencies (chrono, serde are optional; hex is the only unconditional one).

Standards supported

This crate implements primitives rather than a wire format, so the table lists the specification each primitive follows.

Feature flags

[dependencies]
broadcast-common = "10"
# embedded (no_std + alloc):
# broadcast-common = { version = "9", default-features = false }

Quick start

use broadcast_common::{bcd, clock33, crc32_mpeg2, Parse, Serialize};

// CRC-32/MPEG-2 over a real PAT section (from the committed m6-single.ts fixture):
// the CRC of the body equals the trailing CRC_32 field.
let section = [
    0x00, 0xB0, 0x0D, 0x00, 0x01, 0xC1, 0x00, 0x00, 0x04, 0x01, 0xE0, 0x64,
    0xF9, 0xB4, 0x63, 0xEF,
];
let crc = crc32_mpeg2::compute(&section[..section.len() - 4]);
assert_eq!(crc, 0xF9B4_63EF);

// BCD and 33-bit clock arithmetic.
assert_eq!(bcd::from_bcd_byte(0x42), Some(42));
assert_eq!(clock33::add(clock33::WRAP_33BIT - 1, 2), 1);
assert_eq!(clock33::signed_distance(clock33::WRAP_33BIT - 10, 5), 15);

// Implement the symmetric contract for your own wire type.
#[derive(Debug, PartialEq)]
struct Toy { tag: u8, value: u16 }

impl<'a> Parse<'a> for Toy {
    type Error = &'static str;
    fn parse(b: &'a [u8]) -> Result<Self, Self::Error> {
        if b.len() < 3 { return Err("short"); }
        Ok(Toy { tag: b[0], value: u16::from_be_bytes([b[1], b[2]]) })
    }
}
impl Serialize for Toy {
    type Error = &'static str;
    fn serialized_len(&self) -> usize { 3 }
    fn serialize_into(&self, buf: &mut [u8]) -> Result<usize, Self::Error> {
        if buf.len() < 3 { return Err("short"); }
        buf[0] = self.tag;
        buf[1..3].copy_from_slice(&self.value.to_be_bytes());
        Ok(3)
    }
}
let wire = [0x42, 0x12, 0x34];
let toy = Toy::parse(&wire)?;
assert_eq!(toy.try_to_bytes()?, wire); // the workspace round-trip invariant
# Ok::<(), &'static str>(())

Runnable examples: cargo run -p broadcast-common --example crc_and_bcd and --example implement_parse_serialize.

What is implemented

Design notes

• Reserved-bit and trailing-byte policy (workspace-wide, issue #1139): parse is tolerant; serialize preserves what was parsed in typed, spec-named fields (no raw passthrough blobs); hand-built values default to the edition value (1 for reserved_future_use, 0 for reserved_zero_future_use); reserved bytes are always written explicitly; trailing bytes are never dropped without a documented decision.
• Round-trip invariant. Every wire type parses to a borrowed struct and serializes back byte-identically; this crate supplies the traits, the helpers and the rule, and each crate carries the round-trip tests.
• Checked widths, not masks. len::fit_* returns FieldOverflow when a value does not fit its field; the & MASK idiom is banned in serializers.
• One clock implementation. PCR/PTS/DTS/pts_time wrap arithmetic lives in clock33; the 2^33 modulus must not be re-derived elsewhere.
• Label convention. impl_spec_display! keeps Display in lockstep with the hand-written name() of every public spec enum.
• #![forbid(unsafe_code)], #![warn(missing_docs)], no_std + alloc without std.

Related crates and license

Versioned independently of the DVB lockstep crates (it ships from its own broadcast-common-v* tag). Every protocol crate depends on it; it depends on none of them. See the workspace README for the crate map.

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