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 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]

Originally Posted by 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:

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]

Originally Posted by rainbaby

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]

Originally Posted by tebasuna51

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]

Originally Posted by tebasuna51

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

It is now supported in Cavernize.

[tebasuna51]

Thanks for the installer!
Last updated: 17th August 2025.
Now support TrueHD decode, BTW there are also a portable version here

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]

Originally Posted by 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?

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.

[tormento]

Can someone much more expert than me tell what is the correct path to convert THD+ATMOS to DDP+ATMOS?

Before, I used Dolby Player to export ATMOS to discrete channel configuration and then encoded them with dee (usually 9.1.6 or 5.1.2).

Now that TrueHDD is out, would be better to use it to have dynamic objects? What is the correct path not to have channel misplacement?

[Gatorman3385]

TrueHDD + DEE + Deezy seems to work for me. Without an Atmos speaker setup I can't test it. However, Cavern does show objects moving through a 9.1.6 virtual space.

It may be possible without Deezy, but I don't know the correct DEE syntax.

[tebasuna51]

What is Deezy?

[TR-9970X]

Originally Posted by tebasuna51

What is Deezy?

https://jessielw.github.io/DeeZy/installation.html

[tebasuna51]

Then:
[QUOTE=Gatorman3385;2023345]TrueHDD + DEE + Deezy seems to work for me...QUOTE]
It's for recode THD-Atmos to Eac3-Atmos, I will try it next month.

[SquallMX]

Originally Posted by Gatorman3385

TrueHDD + DEE + Deezy seems to work for me. Without an Atmos speaker setup I can't test it. However, Cavern does show objects moving through a 9.1.6 virtual space.

It may be possible without Deezy, but I don't know the correct DEE syntax.

Thanks, works perfectly!

[UsedUser]

Originally Posted by rainbaby

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...

Are you familiar with ffmpeg's implementation to understand what's getting decoded in a downmix differently than TrueHDD will apply, given (A) ffmpeg's decoder doesn't support the Atmos object-based audio (meaning, I thought that meant it was only decoding bed channels), and (B) there may only be an LFE bed channel available to decode?

Does it go back to the matrix decoding you mentioned in your other post, applied to some substream(s)?

Edit:
Having seen more info from the fantastic TrueHDD, asked another way, if I have a Dolby Atmos .thd file with the following presentations:

TrueHD Stream Information
=========================

Stream Information
  Format Sync               F8726FBA
  Sampling rate             48000 Hz
  Variable rate             true
  Peak data rate            9849 kbps
  Number of substreams      4
  Dolby Atmos               true

Presentation Information
  Presentation 0
    Number of channels      2
    Presentation type       Downmix of presentation 1
    Channel format          Stereo
    DRC on by default       true
    Dialogue Level          -37 dBFS
    Mix Level                99 dB
  Presentation 1
    Number of channels      6
    Presentation type       Downmix of presentation 2
    Dolby Surround EX       Not indicated
    Channel assignment      L, R, C, LFE, Ls, Rs
    DRC on by default       false
    Dialogue Level          -31 dBFS
    Mix Level               105 dB
  Presentation 2
    Number of channels      8
    Presentation type       Downmix of presentation 3
    Channel assignment      L, R, C, LFE, Ls, Rs, Lb, Rb
    DRC on by default       false
    Dialogue Level          -31 dBFS
    Mix Level               105 dB
  Presentation 3
    Number of elements      16
    Presentation type       Independent
    Bed configuration       LFE
    Dialogue Level          -31 dBFS
    Mix Level               105 dB

and if ffmpeg is not able to "decode Atmos", is it still able to decode presentations 0-2 properly, folding down all 16 elements into the mix as intended, even though only 1 of those is a bed channel (LFE) and the rest are dynamic objects?

When I convert that same thd file to w64 in ffmpeg, it seems to automatically default to Presentation 2, as I get 8 channels.

And then I've used a pan filter like so, to downmix to stereo to my liking:

-af pan="stereo| FL = FL + 0.707*FC + 0.5*LFE + 0.707*SL + 0.707*BL | FR = FR + 0.707*FC + 0.5*LFE + 0.707*SR + 0.707*BR"

Using DD+ streams (prior to your tool becoming available), I've heard elements missing in a stereo downmix using ffmpeg and the pan filter above, but when I use Cavern, while I can hear those elements, I get an overall very hollow-sounding downmix compared to ffmpeg, in a way that seems like more than just reverb coming from the surround channels.

I'd ultimately like to understand what's happening in ffmpeg vs TrueHDD CLI vs Cavern, and then would especially like to be able to exert more control over how the elements are downmixed.

For example, I'd like to be able to raise vocals in a mix (when captured in a center channel or object) or include the LFE in a mix (when Dolby traditionally indicates the LFE channel is meant to be dropped altogether when downmixing to stereo).

Maybe that says I should be using TrueHDD to decode Presentation 1 or 2, and then applying a pan filter to my liking with ffmpeg? Or maybe I should be testing using TrueHDD to decode Presentation 0, because the dynamic matrices used in the downmix will now be applied correctly in a way that ffmpeg doesn't allow (since it decodes Presentation 2)?

Thank you for the wonderful work. I appreciate any insights you can offer.

[Fuso]

So, in a few words, if I figure it out how to set up all of the above mentioned software will I be able to convert Dolby TrueHD 7.1 + Atmos to Dolby Digital Plus 7.1 + Atmos and also to remove DialNorm from the "factory" Dolby Digital Plus Atmos?

[powerpan]

found that trueHDD could not decode more than 8 channels...