mirror of
https://github.com/storytold/craft-libs.git
synced 2026-11-17 16:54:45 +00:00
* craft-media: MPEG-2 transport and program stream demuxer from FilmCraft (feature `mpegts`) Moves filmcraft-mpegts (storytold/filmcraft@4bec22b) into craft_media::mpegts. ByteSource is the crate's trait, Error is written without thiserror so the feature has no dependencies, and Codec::codec_id() and Stream::codec_params() map streams to CodecId. Adds Container::MpegTs and Container::MpegPs, an ffprobe oracle test over ten ffmpeg-made files, and hostile-input tests. * craft-media: module order after merging main
390 lines
12 KiB
Rust
390 lines
12 KiB
Rust
//! Container and codec identifiers and codec parameters shared by the codec crates (craft-audio,
|
|
//! and the video crate to come), so a file's container and codec are named the same way
|
|
//! everywhere, and a codec is configured the same way whatever container its track came from.
|
|
//!
|
|
//! Both enums are `#[non_exhaustive]`: new formats are added as minor changes, so a `match` on them
|
|
//! needs a `_` arm.
|
|
|
|
#![warn(missing_docs)]
|
|
|
|
/// The file or stream format that holds the codec data.
|
|
#[non_exhaustive]
|
|
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
|
|
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
|
|
pub enum Container {
|
|
/// RIFF WAVE, including BWF and RF64/BW64.
|
|
Wav,
|
|
/// AIFF and AIFF-C.
|
|
Aiff,
|
|
/// A native FLAC stream (`fLaC`).
|
|
Flac,
|
|
/// ISO base media file format: MP4, M4A, M4B.
|
|
Mp4,
|
|
/// QuickTime (MOV).
|
|
QuickTime,
|
|
/// Matroska (MKV, MKA).
|
|
Matroska,
|
|
/// WebM (the Matroska subset).
|
|
WebM,
|
|
/// Ogg.
|
|
Ogg,
|
|
/// Apple Core Audio Format.
|
|
Caf,
|
|
/// A raw ADTS AAC stream.
|
|
Adts,
|
|
/// A raw MPEG audio stream (MP1, MP2 or MP3 frames, optionally behind ID3v2 tags).
|
|
MpegAudio,
|
|
/// A raw AC-3 or E-AC-3 stream.
|
|
Ac3,
|
|
/// AVI (RIFF), including OpenDML.
|
|
Avi,
|
|
/// MXF (SMPTE ST 377-1): OP1a, OP-Atom.
|
|
Mxf,
|
|
/// MPEG-2 transport stream (TS, M2TS).
|
|
MpegTs,
|
|
/// MPEG-1/2 program stream (MPG, VOB).
|
|
MpegPs,
|
|
}
|
|
|
|
impl Container {
|
|
/// A short display name: `"WAV"`, `"MP4"`, `"Matroska"`.
|
|
pub fn name(self) -> &'static str {
|
|
match self {
|
|
Container::Wav => "WAV",
|
|
Container::Aiff => "AIFF",
|
|
Container::Flac => "FLAC",
|
|
Container::Mp4 => "MP4",
|
|
Container::QuickTime => "QuickTime",
|
|
Container::Matroska => "Matroska",
|
|
Container::WebM => "WebM",
|
|
Container::Ogg => "Ogg",
|
|
Container::Caf => "CAF",
|
|
Container::Adts => "ADTS",
|
|
Container::MpegAudio => "MPEG audio",
|
|
Container::Ac3 => "AC-3",
|
|
Container::Avi => "AVI",
|
|
Container::Mxf => "MXF",
|
|
Container::MpegTs => "MPEG-TS",
|
|
Container::MpegPs => "MPEG-PS",
|
|
}
|
|
}
|
|
}
|
|
|
|
/// A codec, audio or video.
|
|
#[non_exhaustive]
|
|
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
|
|
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
|
|
pub enum CodecId {
|
|
/// Uncompressed PCM, integer or float.
|
|
Pcm,
|
|
/// ADPCM (IMA, Microsoft, G.722, G.726).
|
|
Adpcm,
|
|
/// G.711 A-law.
|
|
ALaw,
|
|
/// G.711 µ-law.
|
|
MuLaw,
|
|
/// FLAC.
|
|
Flac,
|
|
/// Apple Lossless.
|
|
Alac,
|
|
/// AAC (LC). Containers report every AAC stream as `Aac`; a decoder that finds spectral band
|
|
/// replication reports [`CodecId::HeAac`].
|
|
Aac,
|
|
/// HE-AAC (AAC with spectral band replication, v1 or v2).
|
|
HeAac,
|
|
/// MPEG-1/2 Audio Layer I.
|
|
Mp1,
|
|
/// MPEG-1/2 Audio Layer II.
|
|
Mp2,
|
|
/// MPEG-1/2 Audio Layer III.
|
|
Mp3,
|
|
/// AC-3 (Dolby Digital).
|
|
Ac3,
|
|
/// E-AC-3 (Dolby Digital Plus).
|
|
Eac3,
|
|
/// Opus.
|
|
Opus,
|
|
/// Vorbis.
|
|
Vorbis,
|
|
/// Speex.
|
|
Speex,
|
|
/// H.264 / AVC.
|
|
H264,
|
|
/// H.265 / HEVC.
|
|
Hevc,
|
|
/// AV1.
|
|
Av1,
|
|
/// VP8.
|
|
Vp8,
|
|
/// VP9.
|
|
Vp9,
|
|
/// Apple ProRes.
|
|
ProRes,
|
|
/// Motion JPEG.
|
|
Mjpeg,
|
|
/// MPEG-2 video.
|
|
Mpeg2Video,
|
|
/// MPEG-4 Part 2 video.
|
|
Mpeg4Video,
|
|
/// Theora.
|
|
Theora,
|
|
/// Avid DNxHD / DNxHR.
|
|
Dnxhd,
|
|
/// APV (Advanced Professional Video).
|
|
Apv,
|
|
/// A codec this crate has no identifier for.
|
|
Unknown,
|
|
}
|
|
|
|
impl CodecId {
|
|
/// A short display name: `"AAC"`, `"HE-AAC"`, `"E-AC-3"`, `"H.264"`.
|
|
pub fn name(self) -> &'static str {
|
|
match self {
|
|
CodecId::Pcm => "PCM",
|
|
CodecId::Adpcm => "ADPCM",
|
|
CodecId::ALaw => "A-law",
|
|
CodecId::MuLaw => "µ-law",
|
|
CodecId::Flac => "FLAC",
|
|
CodecId::Alac => "ALAC",
|
|
CodecId::Aac => "AAC",
|
|
CodecId::HeAac => "HE-AAC",
|
|
CodecId::Mp1 => "MP1",
|
|
CodecId::Mp2 => "MP2",
|
|
CodecId::Mp3 => "MP3",
|
|
CodecId::Ac3 => "AC-3",
|
|
CodecId::Eac3 => "E-AC-3",
|
|
CodecId::Opus => "Opus",
|
|
CodecId::Vorbis => "Vorbis",
|
|
CodecId::Speex => "Speex",
|
|
CodecId::H264 => "H.264",
|
|
CodecId::Hevc => "HEVC",
|
|
CodecId::Av1 => "AV1",
|
|
CodecId::Vp8 => "VP8",
|
|
CodecId::Vp9 => "VP9",
|
|
CodecId::ProRes => "ProRes",
|
|
CodecId::Mjpeg => "Motion JPEG",
|
|
CodecId::Mpeg2Video => "MPEG-2",
|
|
CodecId::Mpeg4Video => "MPEG-4",
|
|
CodecId::Theora => "Theora",
|
|
CodecId::Dnxhd => "DNxHD",
|
|
CodecId::Apv => "APV",
|
|
CodecId::Unknown => "unknown",
|
|
}
|
|
}
|
|
|
|
/// Whether this is an audio codec.
|
|
pub fn is_audio(self) -> bool {
|
|
matches!(
|
|
self,
|
|
CodecId::Pcm
|
|
| CodecId::Adpcm
|
|
| CodecId::ALaw
|
|
| CodecId::MuLaw
|
|
| CodecId::Flac
|
|
| CodecId::Alac
|
|
| CodecId::Aac
|
|
| CodecId::HeAac
|
|
| CodecId::Mp1
|
|
| CodecId::Mp2
|
|
| CodecId::Mp3
|
|
| CodecId::Ac3
|
|
| CodecId::Eac3
|
|
| CodecId::Opus
|
|
| CodecId::Vorbis
|
|
| CodecId::Speex
|
|
)
|
|
}
|
|
|
|
/// Whether this is a video codec.
|
|
pub fn is_video(self) -> bool {
|
|
matches!(
|
|
self,
|
|
CodecId::H264
|
|
| CodecId::Hevc
|
|
| CodecId::Av1
|
|
| CodecId::Vp8
|
|
| CodecId::Vp9
|
|
| CodecId::ProRes
|
|
| CodecId::Mjpeg
|
|
| CodecId::Mpeg2Video
|
|
| CodecId::Mpeg4Video
|
|
| CodecId::Theora
|
|
| CodecId::Dnxhd
|
|
| CodecId::Apv
|
|
)
|
|
}
|
|
}
|
|
|
|
/// The layout of uncompressed PCM samples.
|
|
#[non_exhaustive]
|
|
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
|
|
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
|
|
pub struct PcmFormat {
|
|
/// Bits per sample (8, 16, 24, 32 for integers; 32 or 64 for floats).
|
|
pub bits: u16,
|
|
/// IEEE float samples.
|
|
pub float: bool,
|
|
/// Big-endian byte order.
|
|
pub big_endian: bool,
|
|
/// Signed integers (8-bit WAV and `raw ` QuickTime PCM are unsigned).
|
|
pub signed: bool,
|
|
}
|
|
|
|
impl PcmFormat {
|
|
/// Integer samples of `bits` bits.
|
|
pub fn int(bits: u16, signed: bool, big_endian: bool) -> PcmFormat {
|
|
PcmFormat { bits, float: false, big_endian, signed }
|
|
}
|
|
|
|
/// IEEE float samples of `bits` bits (32 or 64).
|
|
pub fn float(bits: u16, big_endian: bool) -> PcmFormat {
|
|
PcmFormat { bits, float: true, big_endian, signed: true }
|
|
}
|
|
}
|
|
|
|
/// What a decoder needs to know about a track, whatever container it came from.
|
|
///
|
|
/// `extradata` is the codec configuration in Matroska's `CodecPrivate` form, which ffmpeg's
|
|
/// extradata also follows:
|
|
///
|
|
/// | Codec | `extradata` |
|
|
/// |---|---|
|
|
/// | AAC | `AudioSpecificConfig` |
|
|
/// | Opus | the `OpusHead` identification header (RFC 7845 §5.1) |
|
|
/// | Vorbis, Theora | the three headers, Xiph-laced |
|
|
/// | Speex | the Speex header |
|
|
/// | FLAC | `fLaC` followed by the metadata blocks (STREAMINFO first) |
|
|
/// | ALAC | the magic cookie (`ALACSpecificConfig`) |
|
|
/// | AC-3 / E-AC-3 | the MP4 `dac3` / `dec3` payload, or empty |
|
|
/// | MP1/MP2/MP3, PCM | empty |
|
|
/// | H.264 / HEVC / AV1 | the `avcC` / `hvcC` / `av1C` record |
|
|
/// | VP9 | the MP4 `vpcC` payload, or Matroska's codec feature metadata |
|
|
/// | APV | the `apvC` record |
|
|
///
|
|
/// `sample_rate` and `channels` are what the container declares (for HE-AAC with implicit
|
|
/// signalling, usually the core rate), except that Opus is always 48 kHz, the rate it decodes at;
|
|
/// `width` and `height` are the coded picture size of a video
|
|
/// track. `tag` is the container's four-character code for the codec when it has one (the MP4
|
|
/// sample entry format, Matroska's ProRes or VfW FourCC), which is how a ProRes profile (`apcn`,
|
|
/// `ap4h`, …) or a DNx variant is told apart.
|
|
///
|
|
/// `#[non_exhaustive]`: build it with [`CodecParams::new`] and the `with_*` methods.
|
|
#[non_exhaustive]
|
|
#[derive(Debug, Clone, PartialEq, Eq)]
|
|
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
|
|
pub struct CodecParams {
|
|
/// The codec.
|
|
pub codec: CodecId,
|
|
/// The codec configuration (see the table above).
|
|
pub extradata: Vec<u8>,
|
|
/// The container's four-character code for the codec, if it has one.
|
|
pub tag: Option<[u8; 4]>,
|
|
/// Audio: samples per second.
|
|
pub sample_rate: Option<u32>,
|
|
/// Audio: channel count.
|
|
pub channels: Option<u16>,
|
|
/// Audio: the sample layout of uncompressed PCM.
|
|
pub pcm: Option<PcmFormat>,
|
|
/// Video: coded picture width in pixels.
|
|
pub width: Option<u32>,
|
|
/// Video: coded picture height in pixels.
|
|
pub height: Option<u32>,
|
|
}
|
|
|
|
impl CodecParams {
|
|
/// Parameters for `codec`, with nothing else known yet.
|
|
pub fn new(codec: CodecId) -> CodecParams {
|
|
CodecParams { codec, extradata: Vec::new(), tag: None, sample_rate: None, channels: None, pcm: None, width: None, height: None }
|
|
}
|
|
|
|
/// Sets `tag`.
|
|
pub fn with_tag(mut self, tag: [u8; 4]) -> CodecParams {
|
|
self.tag = Some(tag);
|
|
self
|
|
}
|
|
|
|
/// The coded picture size; a zero dimension leaves both unknown.
|
|
pub fn with_size(mut self, width: u32, height: u32) -> CodecParams {
|
|
(self.width, self.height) = if width > 0 && height > 0 { (Some(width), Some(height)) } else { (None, None) };
|
|
self
|
|
}
|
|
|
|
/// Sets `extradata`.
|
|
pub fn with_extradata(mut self, extradata: impl Into<Vec<u8>>) -> CodecParams {
|
|
self.extradata = extradata.into();
|
|
self
|
|
}
|
|
|
|
/// Sets `sample_rate`; 0 leaves it unknown.
|
|
pub fn with_sample_rate(mut self, sample_rate: u32) -> CodecParams {
|
|
self.sample_rate = (sample_rate > 0).then_some(sample_rate);
|
|
self
|
|
}
|
|
|
|
/// Sets `channels`; 0 leaves it unknown.
|
|
pub fn with_channels(mut self, channels: u16) -> CodecParams {
|
|
self.channels = (channels > 0).then_some(channels);
|
|
self
|
|
}
|
|
|
|
/// Sets `pcm`.
|
|
pub fn with_pcm(mut self, pcm: PcmFormat) -> CodecParams {
|
|
self.pcm = Some(pcm);
|
|
self
|
|
}
|
|
}
|
|
|
|
/// Xiph lacing of `packets` (Matroska `CodecPrivate` for Vorbis): the count less one, each
|
|
/// length but the last as a run of 255s and a remainder, then the packets. `None` for no packets
|
|
/// or more than 256, which the one-byte count cannot hold.
|
|
pub fn xiph_lace(packets: &[Vec<u8>]) -> Option<Vec<u8>> {
|
|
let mut out = vec![u8::try_from(packets.len().checked_sub(1)?).ok()?];
|
|
for p in packets.iter().take(packets.len().saturating_sub(1)) {
|
|
let mut n = p.len();
|
|
while n >= 255 {
|
|
out.push(255);
|
|
n -= 255;
|
|
}
|
|
out.push(n as u8);
|
|
}
|
|
for p in packets {
|
|
out.extend_from_slice(p);
|
|
}
|
|
Some(out)
|
|
}
|
|
|
|
#[cfg(test)]
|
|
mod tests {
|
|
use super::*;
|
|
|
|
#[test]
|
|
fn audio_and_video_are_disjoint() {
|
|
for c in [CodecId::Aac, CodecId::Opus, CodecId::Pcm, CodecId::Eac3, CodecId::Speex] {
|
|
assert!(c.is_audio() && !c.is_video(), "{c:?}");
|
|
}
|
|
for c in [CodecId::H264, CodecId::Av1, CodecId::ProRes, CodecId::Theora, CodecId::Dnxhd, CodecId::Apv] {
|
|
assert!(c.is_video() && !c.is_audio(), "{c:?}");
|
|
}
|
|
assert!(!CodecId::Unknown.is_audio() && !CodecId::Unknown.is_video());
|
|
}
|
|
|
|
#[test]
|
|
fn params_builder() {
|
|
let p = CodecParams::new(CodecId::Aac).with_extradata([0x12, 0x10]).with_sample_rate(48_000).with_channels(2).with_sample_rate(0);
|
|
assert_eq!((p.codec, p.extradata.as_slice(), p.sample_rate, p.channels), (CodecId::Aac, &[0x12, 0x10][..], None, Some(2)));
|
|
let v = CodecParams::new(CodecId::ProRes).with_tag(*b"apcn").with_size(1920, 1080);
|
|
assert_eq!((v.tag, v.width, v.height), (Some(*b"apcn"), Some(1920), Some(1080)));
|
|
assert_eq!(v.with_size(0, 1080).width, None);
|
|
}
|
|
|
|
#[test]
|
|
fn xiph_lacing() {
|
|
let laced = xiph_lace(&[vec![1; 30], vec![2; 300], vec![3; 5]]).unwrap();
|
|
assert_eq!(&laced[..4], &[2, 30, 255, 45]);
|
|
assert_eq!(laced.len(), 4 + 335);
|
|
assert_eq!(xiph_lace(&[]), None);
|
|
assert_eq!(xiph_lace(&vec![vec![0]; 257]), None);
|
|
assert!(xiph_lace(&vec![vec![0]; 256]).is_some());
|
|
}
|
|
}
|