Crate truehd 

truehd

A low-level parser and decoder for Dolby TrueHD audio bitstreams, implemented in Rust.

⚠️ Experimental:

This crate is intended for internal or research use only.
It is not designed for production or end-user playback systems.

Usage

[dependencies]
truehd = "0.6.3"

Requires Rust 1.88.0 or later.

Decoding runs in three stages: an Extractor finds frames in a byte stream, a Parser turns each frame into an access unit, and a Decoder renders access units to PCM. See the crate documentation for a worked example.

On damaged input, Parser::reset_for_next_major_sync and Decoder::reset_for_next_major_sync drop stream state so decoding can resume at the next major sync. Call both at the same point in the frame sequence, or the two stages will disagree about the stream.

Development Status

Category	Feature	Status	Priority	Criticality	Notes
Parser	FBA sync bitstream (Dolby)	🟢	High	Essential
	FBB sync bitstream (Meridian)	🔴	Low	Nice-to-have	Do you really need it?
	Evolution frame	🟢	High	Essential
	CRC and parity validation	🟢	High	Essential
	SMPTE timestamp	🟢	Medium	Optional
	FBA hires output timing	🟢	Medium	Optional
	Object audio metadata	🟡	High	Essential	Mostly done
	FIFO conformance tests	🟡	Medium	Optional	Partially done
	FBA bitstream seeking	🔴	Low	Nice-to-have	Yes, it’s possible
Decoder	31EA / 31EB sync substream	🟢	High	Essential
	31EC sync substream	🟢	High	Essential	4th / 16ch presentation
	Lossless check	🟢	High	Essential
	Optimize DSP performance	🔴	Medium	Important
	Dynamic range control	🔴	Low	Optional	State parsed, not applied
	Intermediate spatial format	🔴	Low	Out-of-scope	I have no idea
Other TODOs	Documentation	🟡	High	Essential	With kind support from Claude
	Unit tests	🟡	High	Essential	Partially done
	Benchmarking	🔴	Medium	Important
	Metadata interpolation	🔴	Low	Nice-to-have
	Bitstream editing	🔴	Low	Nice-to-have
	Encoding	🔴	Low	Nice-to-have
	Object audio rendering	🔴	Low	Out-of-scope

Legend: 🟢 Completed • 🟡 In Progress • 🔴 Not Started

---

License

Licensed under the Apache License, Version 2.0. See LICENSE for details.

Technical Overview

Parser and decoder for Dolby TrueHD (MLP) bitstreams according to FBA syntax specification.

Bitstream Organization

External Structure: Access units containing MLP Syncs and substream segments. Internal Structure: Blocks with optional restart headers.

Audio Presentations

• 2-channel (stereo, Lt/Rt, binaural, mono)
• 6-channel
• 8-channel
• 16-channel

Data Rate Management

Variable bitrate compression with FIFO buffering. Peak data rates limited to 18 Mbps for FBA streams.

Quick Start

Steps for processing audio streams:

1. Extract access units from a bitstream using process::extract::Extractor
2. Parse access units into structured data using process::parse::Parser
3. Decode audio to PCM samples using process::decode::Decoder

use truehd::process::{extract::Extractor, parse::Parser, decode::Decoder, EXAMPLE_DATA};

// Initialize processing components
let mut extractor = Extractor::default();
let mut parser = Parser::default();
let mut decoder = Decoder::default();

// Push bitstream data
let data = &EXAMPLE_DATA; // Example data
extractor.push_bytes(data);

// Process frames with error recovery
for frame_result in extractor {
    match frame_result {
        Ok(frame) => {
            let access_unit = parser.parse(&frame)?;
             
            // Decode the first presentation
            let decoded = decoder.decode_presentation(&access_unit, 0)?;
             
            // Access PCM data
            let pcm_samples = &decoded.pcm_data;
        }
        Err(extract_error) => {
            // Handle extraction errors - stream continues automatically
            eprintln!("Frame extraction error: {}", extract_error);
        }
    }
}

Modules

process

Processing functionality for audio bitstreams.

structs

Data structures representing TrueHD format components.

utils

Utility functions and supporting infrastructure.

Macros

log_or_err