Skip to content

FilmCraft: An open-source, nonlinear video editor written by scratch in pure Rust

12.7 KB
Raw Blame
//! Clean-room MPEG-2 Systems demuxer (ITU-T H.222.0 | ISO/IEC 13818-1).
//!
//! - **Transport Stream**: 188-byte packets, 192-byte BDAV / AVCHD packets (`.m2ts`, `.mts`:
//!   a 4-byte arrival timestamp before each packet) and 204-byte packets (Reed-Solomon parity).
//!   PAT / PMT (sections reassembled across packets, CRC checked), PES reassembly, PCR, PTS/DTS
//!   (33-bit wrap-around unwrapped), discontinuity indicators.
//! - **Program Stream** (`.mpg`, `.vob`, `.mod`, `.tod`): MPEG-2 and ISO/IEC 11172-1 (MPEG-1)
//!   packs, system headers, program stream maps, DVD private stream 1 sub-streams (AC-3, DTS,
//!   LPCM).
//! - **Elementary streams** are split into access units on open — coded frames for MPEG-1/2
//!   video (picture start codes, field pairs), H.264 and HEVC (access unit delimiters / first
//!   slice of a picture), audio frames for MPEG audio, ADTS / LATM AAC, AC-3 and E-AC-3, PES
//!   packets for LPCM — each with its PTS/DTS (a PES timestamp belongs to the first access unit
//!   that starts in the packet), random-access flag and, for MPEG video, picture type, temporal
//!   reference and field structure. That index is the seeking table.
//! - Units are read back on demand by re-reading the file from the unit's first packet, so the
//!   index costs a few dozen bytes per access unit.
//!
//! The crate does no decoding; `filmcraft-codecs` pairs the streams with decoders.

#![cfg_attr(not(test), deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable))]

mod es;
pub use es::{FrameInfo, frame_bytes, frame_info};
mod pes;
mod ps;
mod ts;

use std::io;

#[derive(Debug, thiserror::Error)]
pub enum Error {
    #[error("not an MPEG transport or program stream")]
    NotMpeg,
    #[error("I/O: {0}")]
    Io(#[from] io::Error),
    #[error("invalid stream: {0}")]
    Invalid(String),
}

pub type Result<T> = std::result::Result<T, Error>;

/// Random-access bytes (a file, a memory buffer).
pub trait ByteSource {
    fn len(&self) -> u64;
    fn read_at(&self, offset: u64, buf: &mut [u8]) -> io::Result<()>;
    fn is_empty(&self) -> bool {
        self.len() == 0
    }
}

impl ByteSource for [u8] {
    fn len(&self) -> u64 {
        <[u8]>::len(self) as u64
    }
    fn read_at(&self, offset: u64, buf: &mut [u8]) -> io::Result<()> {
        let o = usize::try_from(offset).map_err(|_| io::Error::from(io::ErrorKind::UnexpectedEof))?;
        let src = self.get(o..o + buf.len()).ok_or_else(|| io::Error::from(io::ErrorKind::UnexpectedEof))?;
        buf.copy_from_slice(src);
        Ok(())
    }
}

impl ByteSource for Vec<u8> {
    fn len(&self) -> u64 {
        self.as_slice().len() as u64
    }
    fn read_at(&self, offset: u64, buf: &mut [u8]) -> io::Result<()> {
        self.as_slice().read_at(offset, buf)
    }
}

/// Read as much as is available at `offset` (up to `buf.len()`); returns the count.
pub(crate) fn read_some<S: ByteSource + ?Sized>(src: &S, offset: u64, buf: &mut [u8]) -> io::Result<usize> {
    let len = src.len();
    if offset >= len {
        return Ok(0);
    }
    let n = ((len - offset) as usize).min(buf.len());
    src.read_at(offset, &mut buf[..n])?;
    Ok(n)
}

/// The container layout.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum Format {
    /// Transport stream with `packet_size`-byte packets whose 0x47 sync byte is at `sync_offset`
    /// (4 for 192-byte BDAV packets).
    Ts { packet_size: usize, sync_offset: usize },
    /// Program stream (`mpeg1`: ISO/IEC 11172-1 packs).
    Ps { mpeg1: bool },
}

impl Format {
    pub fn name(&self) -> &'static str {
        match self {
            Format::Ts { packet_size: 192, .. } => "MPEG-2 TS (BDAV/AVCHD)",
            Format::Ts { .. } => "MPEG-2 TS",
            Format::Ps { mpeg1: true } => "MPEG-1 System",
            Format::Ps { mpeg1: false } => "MPEG-2 PS",
        }
    }
}

/// Recognise a transport stream (five consecutive sync bytes at one of the packet sizes, within
/// the first packets) or a program stream (a pack header).
pub fn sniff(head: &[u8]) -> Option<Format> {
    for (size, off) in [(188usize, 0usize), (192, 4), (204, 0)] {
        for start in 0..size.min(head.len()) {
            let ok = (0..5).all(|k| head.get(start + off + k * size) == Some(&0x47));
            if ok {
                return Some(Format::Ts { packet_size: size, sync_offset: off });
            }
        }
    }
    // a pack header, possibly after a few zero bytes
    let z = head.iter().take(64).take_while(|&&b| b == 0).count();
    let p = z.saturating_sub(2);
    if head.len() >= p + 5 && head[p..p + 4] == [0, 0, 1, 0xBA] {
        return Some(Format::Ps { mpeg1: head[p + 4] >> 6 != 1 });
    }
    None
}

#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum Kind {
    Video,
    Audio,
    Subtitle,
    Other,
}

/// What an elementary stream carries.
#[derive(Clone, Debug, PartialEq, Eq)]
pub enum Codec {
    Mpeg1Video,
    Mpeg2Video,
    H264,
    Hevc,
    /// MPEG-1/2 audio (layers I-III; the layer is in each frame header).
    MpegAudio,
    /// AAC in ADTS frames.
    AacAdts,
    /// AAC in LATM/LOAS frames.
    AacLatm,
    Ac3,
    Eac3,
    Dts,
    TrueHd,
    /// Blu-ray / AVCHD LPCM (a 4-byte header per PES packet, big-endian samples).
    LpcmBluray,
    /// DVD LPCM (program stream private stream 1; format in [`Stream::lpcm`]).
    LpcmDvd,
    Subtitle(&'static str),
    /// Anything else: the stream type.
    Unknown(u8),
}

impl Codec {
    pub fn name(&self) -> String {
        match self {
            Codec::Mpeg1Video => "MPEG-1 Video".into(),
            Codec::Mpeg2Video => "MPEG-2 Video".into(),
            Codec::H264 => "H.264".into(),
            Codec::Hevc => "HEVC".into(),
            Codec::MpegAudio => "MPEG Audio".into(),
            Codec::AacAdts => "AAC (ADTS)".into(),
            Codec::AacLatm => "AAC (LATM)".into(),
            Codec::Ac3 => "AC-3".into(),
            Codec::Eac3 => "E-AC-3".into(),
            Codec::Dts => "DTS".into(),
            Codec::TrueHd => "Dolby TrueHD".into(),
            Codec::LpcmBluray => "LPCM (Blu-ray)".into(),
            Codec::LpcmDvd => "LPCM (DVD)".into(),
            Codec::Subtitle(s) => (*s).into(),
            Codec::Unknown(t) => format!("stream type 0x{t:02x}"),
        }
    }
    pub fn kind(&self) -> Kind {
        match self {
            Codec::Mpeg1Video | Codec::Mpeg2Video | Codec::H264 | Codec::Hevc => Kind::Video,
            Codec::MpegAudio | Codec::AacAdts | Codec::AacLatm | Codec::Ac3 | Codec::Eac3 | Codec::Dts | Codec::TrueHd | Codec::LpcmBluray | Codec::LpcmDvd => {
                Kind::Audio
            }
            Codec::Subtitle(_) => Kind::Subtitle,
            Codec::Unknown(_) => Kind::Other,
        }
    }
}

/// MPEG-1/2 video picture properties of an access unit (its first picture).
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
pub struct PictureInfo {
    /// 1 I, 2 P, 3 B, 4 D.
    pub coding_type: u8,
    pub temporal_reference: u16,
    /// 1 top field, 2 bottom field, 3 frame (two field pictures form one unit).
    pub structure: u8,
    pub top_field_first: bool,
    pub repeat_first_field: bool,
    pub progressive_frame: bool,
    /// A sequence header precedes the picture in this unit.
    pub sequence_header: bool,
    /// A GOP header precedes the picture (and its flags).
    pub gop: bool,
    pub closed_gop: bool,
    pub broken_link: bool,
}

/// One access unit (a coded frame, an audio frame, or an LPCM PES packet).
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct Unit {
    /// Presentation / decoding time stamps, 90 kHz, 33-bit wrap-around unwrapped.
    pub pts: Option<i64>,
    pub dts: Option<i64>,
    /// Decoding can start here (I / IDR / IRAP pictures; every audio frame).
    pub key: bool,
    /// No other unit depends on it (B pictures of MPEG-1/2 video, non-reference H.264/HEVC).
    pub disposable: bool,
    pub size: u32,
    /// TS: byte offset of the packet holding the first byte; PS: byte offset of its PES packet.
    pub(crate) pos: u64,
    /// Offset of the first byte within that packet's elementary-stream payload.
    pub(crate) offset: u32,
    pub picture: Option<PictureInfo>,
}

/// DVD LPCM format (from the private stream 1 header).
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct LpcmFormat {
    pub sample_rate: u32,
    pub channels: u32,
    pub bits: u32,
}

/// Where a stream's PES packets come from.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum StreamId {
    /// Transport stream PID.
    Pid(u16),
    /// Program stream stream_id, and the private stream 1 sub-stream id.
    Ps { stream_id: u8, sub_id: Option<u8> },
}

#[derive(Clone, Debug)]
pub struct Stream {
    pub id: StreamId,
    /// PMT stream_type (TS), or the equivalent for program streams.
    pub stream_type: u8,
    pub codec: Codec,
    /// ISO 639 language code from the PMT.
    pub language: Option<String>,
    pub units: Vec<Unit>,
    pub lpcm: Option<LpcmFormat>,
    /// PES packets seen.
    pub pes_packets: u64,
    /// Bytes of payload ignored because the stream could not be split (e.g. before the first
    /// frame header).
    pub skipped_bytes: u64,
}

impl Stream {
    pub fn kind(&self) -> Kind {
        self.codec.kind()
    }
    /// First and last presentation timestamps (90 kHz) of the stream's units.
    pub fn pts_range(&self) -> Option<(i64, i64)> {
        let mut it = self.units.iter().filter_map(|u| u.pts);
        let first = it.next()?;
        Some(it.fold((first, first), |(a, b), p| (a.min(p), b.max(p))))
    }
}

/// A demuxed file: its streams with their access-unit tables.
#[derive(Clone, Debug)]
pub struct File {
    pub format: Format,
    pub streams: Vec<Stream>,
    /// Program number of the program the streams belong to (TS).
    pub program: Option<u16>,
    /// First and last PCR (27 MHz, unwrapped) or SCR.
    pub pcr_range: Option<(i64, i64)>,
    /// Problems found while scanning (lost sync, CRC errors, continuity errors…).
    pub warnings: Vec<String>,
}

/// Largest unit `read_unit` returns. The biggest real units are intra pictures (a few MB at
/// 4K/8K broadcast rates); a stream without PES timestamps can make one unit of a whole PID.
pub const MAX_UNIT_BYTES: u32 = 128 << 20;

/// Bytes reserved up front by `read_unit`; the buffer grows beyond this only as data is read.
const UNIT_PREALLOC: usize = 1 << 20;

impl File {
    /// The first stream of `kind` whose codec satisfies `f`.
    pub fn find(&self, kind: Kind, f: impl Fn(&Codec) -> bool) -> Option<usize> {
        self.streams.iter().position(|s| s.kind() == kind && !s.units.is_empty() && f(&s.codec))
    }

    /// Read access unit `i` of stream `s`.
    pub fn read_unit<S: ByteSource + ?Sized>(&self, src: &S, s: usize, i: usize) -> Result<Vec<u8>> {
        let st = self.streams.get(s).ok_or_else(|| Error::Invalid("no such stream".into()))?;
        let u = st.units.get(i).ok_or_else(|| Error::Invalid("no such unit".into()))?;
        if u.size > MAX_UNIT_BYTES {
            return Err(Error::Invalid(format!("unit {i} is {} bytes (limit {MAX_UNIT_BYTES})", u.size)));
        }
        // grow as bytes arrive: a damaged table must not reserve more than the file can supply
        let mut out = Vec::with_capacity((u.size as usize).min(UNIT_PREALLOC));
        match self.format {
            Format::Ts { packet_size, sync_offset } => ts::read(src, packet_size, sync_offset, st, u, &mut out)?,
            Format::Ps { .. } => ps::read(src, st, u, &mut out)?,
        }
        if out.len() < u.size as usize {
            return Err(Error::Invalid(format!("unit {i} truncated ({} of {} bytes)", out.len(), u.size)));
        }
        Ok(out)
    }
}

/// Scan a transport or program stream and index its access units.
pub fn open<S: ByteSource + ?Sized>(src: &S) -> Result<File> {
    let mut head = vec![0u8; 64 * 1024];
    let n = read_some(src, 0, &mut head)?;
    head.truncate(n);
    match sniff(&head).ok_or(Error::NotMpeg)? {
        Format::Ts { packet_size, sync_offset } => ts::scan(src, packet_size, sync_offset),
        Format::Ps { mpeg1 } => ps::scan(src, mpeg1),
    }
}

/// Unwraps 33-bit timestamps into a monotonic-ish i64 timeline (relative to the first one seen).
#[derive(Default, Clone, Copy)]
pub(crate) struct Unwrap {
    last: Option<i64>,
    base: i64,
}

impl Unwrap {
    const WRAP: i64 = 1 << 33;
    pub fn unwrap(&mut self, raw: i64) -> i64 {
        let mut v = raw + self.base;
        if let Some(l) = self.last {
            if v < l - Self::WRAP / 2 {
                self.base += Self::WRAP;
                v += Self::WRAP;
            } else if v > l + Self::WRAP / 2 && self.base > 0 {
                // a timestamp from before the wrap (B pictures, slightly out-of-order audio)
                v -= Self::WRAP;
                return v;
            }
        }
        self.last = Some(v);
        v
    }
}

#[cfg(test)]
mod tests;
#[cfg(test)]
mod work_tests;