TrueHDD: A new TrueHD decoder with Atmos support

[rainbaby]

https://github.com/truehdd/truehdd

This is my recent open-source project. It allows decoding a specified TrueHD presentation. For Dolby Atmos, the decoded audio is provided as a Dolby Atmos Master Format (DAMF) set.
This makes it possible to re-encode to DDP Atmos while preserving dynamic objects.
I almost forgot that I could post it here. There should be some people interested in trying it, and bug reports are welcome.

It also supports skipping the overlapping segments when decoding a direct binary concat of multiple bitstreams that include seamless branching.

I would also like to ask if there are any other features needed for working with TrueHD bitstreams. I can check whether they can be implemented.

Currently, my to-do list includes:


Exporting with a 7.1.2 bed (for better DAW compatibility, though not necessary for re-encoding) -> done
Adding silent padding to the bitstream

[tebasuna51]

Testing truehdd-0.1.3-x86_64-pc-windows-msvc.zip over a audiosphere.thd (from www.demolandia.net)

We need something in --output-path to obtain some output:

truehdd decode --output-path z aud.thd
[2025-08-10T07:26:54Z INFO truehdd] 0.1.3 (truehd library 0.3.0) Built: 2025-08-03 11:49:34 UTC
[2025-08-10T07:26:54Z INFO truehdd::cli::decode] Decoding TrueHD stream: aud.thd (strict mode: false, presentation: 3)
[2025-08-10T07:26:54Z INFO truehdd::cli::decode] Output path specified: z
[2025-08-10T07:26:54Z INFO truehdd::cli::decode] Creating metadata file: z.atmos.metadata
[2025-08-10T07:26:54Z INFO truehdd::cli::decode] Creating audio file: z.atmos.audio
[2025-08-10T07:26:58Z INFO truehdd::cli::decode] Processing complete: 73300 frames, 2932000 samples
[2025-08-10T07:26:58Z INFO truehdd::cli::decode] Creating DAMF header file: z.atmos
[2025-08-10T07:26:58Z INFO truehdd::cli::decode] Decoding completed successfully
z.atmos and z.atmos.metadata are txt files.
z.atmos.audio is a .caf file:
General
Complete name : C:\tmp\0\z.atmos.audio
Format : CAF
Format/Info : Core Audio Format
Format version : Version 1
File size : 134 MiB
Duration : 28 ms
Overall bit rate : 40,2 Gb/s
FileExtension_Invalid : caf

Audio
Format : PCM
Codec ID : lpcm
Duration : 28 ms
Bit rate : 18,4 Mb/s
Channel(s) : 16 canales
Sampling rate : 48,0 kHz
Bit depth : 24 bits
Stream size : 63,9 KiB (0%)

When try with --format pcm:
truehdd decode --output-path z --format pcm aud.thd
...
[2025-08-10T07:47:39Z INFO truehdd::cli::decode] Atmos audio detected - forcing CAF format instead of PCM
...
But using --presentation 0:
truehdd decode --output-path z --format pcm --presentation 0 aud.thd
Only output a z.pcm stereo than can be converted to a correct wav stereo
With --presentation 1 we obtain a 5.1 and with --presentation 2 a 7.1

Like you can know when read my thread Surround 3D (https://forum.doom9.org/showthread.php?t=186285) I'm interested in a 5.1.2 presentation. Please add it to your todo list to recode TrueHD to m4a (or eac3, even opus) for use 3D surround with AVR's without Atmos support.

Now I'll make test comparing your free decoder with the Dolby Reference Player decoder.

Thanks for your job!

[tebasuna51]

truehdd doesn't seem to apply DRC, which restores the original volume, while Dolby Reference Player forces the audio to be normalized to restore the volume. Thank you very much.

After normalizing, the 5.1 and 7.1 DRP decodes compared to truehdd's presentations 1 and 2 are very similar.

However, the 16 channels reveal differences in the channel order and some content, as shown in the following figure:

[rainbaby]

truehdd doesn't seem to apply DRC, which restores the original volume, while Dolby Reference Player forces the audio to be normalized to restore the volume. Thank you very much.

After normalizing, the 5.1 and 7.1 DRP decodes compared to truehdd's presentations 1 and 2 are very similar.

However, the 16 channels reveal differences in the channel order and some content, as shown in the following figure:

This is because the decoded 16ch presentation (presentation 3) is not a fixed speaker layout like 9.1.6, but rather discrete channels whose positions are defined by metadata (the .atmos.metadata YAML text file). This is the whole point of the project, as DRP renders the channels using this metadata to match a specific speaker layout, which means that re-encoding based on rendered audio would lose the positional information. The .atmos* file set is a native format that can be imported into DAWs with an integrated Dolby Atmos Renderer, or used as input for encoders such as DEE.

[tebasuna51]

This is because the decoded 16ch presentation (presentation 3) is not a fixed speaker layout like 9.1.6, but rather discrete channels whose positions are defined by metadata (the .atmos.metadata YAML text file). This is the whole point of the project, as DRP renders the channels using this metadata to match a specific speaker layout,

I understand that, but my goal is to decode Atmos for a single speaker configuration, which is the only one I find useful for playing 3D audio on a home theater.

which means that re-encoding based on rendered audio would lose the positional information. The .atmos* file set is a native format that can be imported into DAWs with an integrated Dolby Atmos Renderer, or used as input for encoders such as DEE.

That's right, I'm not trying to recode Atmos but simply its equivalent for a standard setup with non-proprietary formats.

In your to-do list I see a 7.1.2 output, please better a 5.1.2 to be compatible with many more players/codecs. Thanks.

[rainbaby]

In your to-do list I see a 7.1.2 output, please better a 5.1.2 to be compatible with many more players/codecs. Thanks.

Sorry, I didn’t make myself clear earlier. For most TrueHD Atmos tracks, the 16ch presentation’s bed contains only the LFE, because spatial coding was applied before encoding. However, a Dolby Atmos master typically requires a 7.1.2 bed. While these current non-standard files don’t affect re-encoding, they can cause issues when importing into a DAW or converting to the IAB format.
I’m not planning to implement a renderer, that’s currently out of scope and I think Cavern has already done an excellent job in that area. It’s now preparing to integrate truehdd.

[tebasuna51]

Ok, thanks for the info. I wait until Cavern do the job.

[rainbaby]

Ok, thanks for the info. I wait until Cavern do the job.

It is now supported in Cavernize (https://sbence.hu/content/downloads/cavernize.exe?e).

[tebasuna51]

Thanks for the installer!
Last updated: 17th August 2025.
Now support TrueHD decode, BTW there are also a portable version here (https://cavern.sbence.hu/cavern/downloads.php)

Thats change my thread about Surround 3D

EDIT: It create temporary files:

18/08/2025 14:19 519 _extracted.thd.atmos
18/08/2025 14:32 14.198.937.188 _extracted.thd.atmos.audio (CAF file)
18/08/2025 14:32 5.081.694 _extracted.thd.atmos.metadata

like your truehdd...

[j7n]

Since you built the software from scratch, can you tell me what the internal format of TrueHD with Atmos? I understand that you get a 7.1 downmix that includes all sounds. If we drop Atmos, all the content is still there. Is the rest of the stream a difference from this to enable lifting of individual channels out of the downmix? How do they manage to make the encoding relatively small? Could channels in the Atmos layer theoretically be listened to?

[rainbaby]

Since you built the software from scratch, can you tell me what the internal format of TrueHD with Atmos? I understand that you get a 7.1 downmix that includes all sounds. If we drop Atmos, all the content is still there. Is the rest of the stream a difference from this to enable lifting of individual channels out of the downmix? How do they manage to make the encoding relatively small? Could channels in the Atmos layer theoretically be listened to?

TrueHD can store multiple presentations with different channel layouts efficiently because they are usually arranged in a hierarchy.
A common structure is: 2.0 <- 5.1 <- 7.1 <- Atmos (up to 16 elements), where each earlier stage is a downmix of the next.

Since downmixing and upmixing can be described using matrices, matrix processing is part of TrueHD’s codec, the information can be split across multiple substreams while still allowing decoding at different levels in the hierarchy.

In the example above, four substreams might contain 2, 4, 2, and 8 channels of data respectively, each also carrying the matrix coefficients needed to reconstruct its corresponding presentation.

If you only need 2.0, you decode just the first substream.
For 7.1, you decode the first three.

The fourth substream, which carries Atmos information, follows the same principle but, as a TrueHD extension, it redefines how the matrices are stored. Instead of a static matrix (as is common up to 7.1), it uses interpolation to represent a dynamic matrix.

As a result, the channels in the fourth substream are not directly listenable on their own. They must be combined with the data from the first three substreams using matrix operations to produce up to 16 channels. Most of these channels, except usually one LFE channel, are dynamic audio objects whose positions and other properties are defined in separate metadata.

It is important to note that TrueHD also allows independent presentations. In the earlier example, if an independent 5.1 presentation is added, the structure becomes 2.0 <- 5.1; 7.1 <- Atmos. In this case, the second substream would independently contain all the audio data required to decode the 5.1 presentation. If you instead add an independent 7.1 presentation, then the Atmos presentation also becomes independent. In these cases the efficiency will drop significantly.