truehdd

A command-line tool for decoding Dolby TrueHD audio streams.

Language: English | 简体中文 | 日本語

⚠️ Experimental

This tool is designed for research and development purposes.
It is not intended for production environments or consumer playback systems.

💡 Got a new idea?

If you have ideas for useful features, please let us know by opening an issue or starting a discussion.

Overview

truehdd is a command-line interface for the truehd library, enabling decoding of Dolby TrueHD audio streams.

Installation

From Source

Requires Rust 1.87.0 or later:

git clone https://github.com/truehdd/truehdd
cd truehdd
cargo build --release

The compiled executable will be located at target/release/truehdd.

Usage

truehdd [OPTIONS] <COMMAND>

Commands:
  decode    Decode the specified TrueHD stream into PCM audio
  info      Print stream information
  help      Print this message or the help of the given subcommand(s)

Options:
      --loglevel <LOGLEVEL>         Set the log level [default: info]
                                    [possible values: off, error, warn, info, debug, trace]
      --strict                      Treat warnings as fatal errors (fail on first warning)
      --log-format <LOG_FORMAT>     Log output format [default: plain]
                                    [possible values: plain, json]
      --progress                    Show progress bars during operations
  -h, --help                        Print help (see a summary with '-h')
  -V, --version                     Print version

Commands

info - Stream Analysis

Analyzes TrueHD streams and displays detailed information about their structure and properties without performing decoding.

Usage: truehdd info [OPTIONS] <INPUT>

Arguments:
  <INPUT>  Input TrueHD bitstream

Options:
...

Examples:

# Analyze a TrueHD file
truehdd info movie.thd

decode - Audio Decoding

Decodes TrueHD streams into PCM audio.

Usage: truehdd decode [OPTIONS] <INPUT>

Arguments:
  <INPUT>  Input TrueHD bitstream (use "-" for stdin)

Options:
      --output-path <PATH>       Output path for audio and metadata files
      --format <FORMAT>          Audio format for output (ignored for presentation 3 which always uses CAF)
                                 [default: caf] [possible values: caf, pcm, w64]
      --presentation <INDEX>     Presentation index (0-3) [default: 3]
      --no-estimate-progress     Disable progress estimation
      --bed-conform              Enable bed conformance for Atmos content
      --warp-mode <WARP_MODE>    Specify warp mode when not present in metadata
                                 [possible values: normal, warping, prologiciix, loro]
...

Output Files:

By default, the maximum available presentation index is chosen for decoding. When --output-path is specified, the tool generates appropriate output files:

• Channel presentation: One of the following files, with presentation index 0, 1, or 2

  • output.caf - PCM data in Core Audio Format
  • output.pcm - Raw PCM (if --format pcm)
  • output.wav - Wave64 format (if --format w64)

• Object presentation: Dolby Atmos master file set, with presentation index 3 (if available)

  1. output.atmos - Essential information about the presentation
  2. output.atmos.audio - Audio for all bed signals and objects in Core Audio format
  3. output.atmos.metadata - 3D positional coordinates for static and dynamic signals

  Note: Presentation 3 always uses CAF format regardless of --format option. Use --bed-conform to convert bed channels to 7.1.2 layout.

Warp Mode Options:

The --warp-mode option controls how Dolby Atmos content handles downmix rendering when the metadata doesn't specify a warp mode:

• normal - Direct render
• warping - Direct render with room balance
• prologiciix - Dolby Pro Logic IIx
• loro - Standard (Lo/Ro)

This option only applies when the original OAMD metadata lacks warp mode information. If warp mode is already present in the metadata, this option is ignored.

Examples:

# Decode a TrueHD file with progress
truehdd decode --progress audio.thd --output-path decoded_audio

# Decode with specific warp mode for content missing this metadata
truehdd decode --warp-mode prologiciix audio.thd --output-path decoded_audio

# Decode from ffmpeg pipe
ffmpeg -i movie.mkv -c copy -f truehd - | truehdd decode - --output-path audio

License

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