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.

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

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]

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]

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

[Thunderbolt8]

Id like to know what is the best way to get a 2.0 stereo track out of a multi channel 7.1 Atmos file, in terms of original audio quality, and not missing out on sound information from certain channels at the same time. I dont even know if downmix would be the most suitable term here, so Id rather try to describe it this way.

I heard that there is a 2.0 kind of core file in Atmos track at their center around which the other channels are built, is this true? and if so, is this comparable to a fully fledged core file, like e.g. with DTS-HD MA core tracks? Or is this 2.0 core unusable (unextractable) for regular listening purposes?

basically Im wondering whether is a better way to get a 2.0 channel sound other than craping all 8 channels together and then turning it into a big mash with regular/random downmixing programs.

[kurkosdr]

https://github.com/truehdd/truehdd

This is my recent open-source project. It allows decoding a specified TrueHD presentation

Out of curiosity, where did you find specs for TrueHD (and TrueHD+Atmos)?

Wondering if even partial public specs exist, or if your efforts are the result of 100% reverse engineering.

[Thunderbolt8]

Id like to know what is the best way to get a 2.0 stereo track out of a multi channel 7.1 Atmos file, in terms of original audio quality, and not missing out on sound information from certain channels at the same time. I dont even know if downmix would be the most suitable term here, so Id rather try to describe it this way.

I heard that there is a 2.0 kind of core file in Atmos track at their center around which the other channels are built, is this true? and if so, is this comparable to a fully fledged core file, like e.g. with DTS-HD MA core tracks? Or is this 2.0 core unusable (unextractable) for regular listening purposes?

basically Im wondering whether is a better way to get a 2.0 channel sound other than craping all 8 channels together and then turning it into a big mash with regular/random downmixing programs.
anyone able to comment on this? is it better in terms of quality or more accurate in terms of mixing/original channel balance/loudness etc. to use the 2.0 substream representation of an Atmos track or to make a downmix from Atmos --> 2.0 with various tools?

[tebasuna51]

AFAIK the Atmos data are added over the standard cores 7.1 (THD or EAC3) to build the rest of 3D channels, not over a 2.0 layout.

Then, in my opinion, to obtain a 2.0 track you need downmix the 7.1 core by standard methods (ffmpeg, eac3to, BeHappy, ...) well knows.

[Thunderbolt8]

do you specifically mean the additional atmos data which goes beyond the standard 7.1 track for additional channels? or do you generally mean all data of an atmos audio track?

if the 7.1 is core and atmos is added on top then downmixing this core (without atmos on top) shouldnt really add any additional atmos information as it wouldnt be part of the core anyway.

(I hope I understood correctly)

[tebasuna51]

All audio "cores" must have all relevant info about that layout, of course all needed for a 2.0 layout.

[rainbaby]

Out of curiosity, where did you find specs for TrueHD (and TrueHD+Atmos)?

Wondering if even partial public specs exist, or if your efforts are the result of 100% reverse engineering.

No public spec exists for TrueHD. Some patents mention the extended parts for Atmos but are typically far removed from actual implementation, and the official Dolby document (https://web.archive.org/web/https://developer.dolby.com/globalassets/technology/dolby-truehd/dolbytruehdhighlevelbitstreamdescription.pdf) is high-level and incomplete. For the object audio metadata (OAMD) part, partial documentation exists as it shares the same format as EAC3-JOC (a public standard (https://www.etsi.org/deliver/etsi_ts/103400_103499/103420/01.02.01_60/ts_103420v010201p.pdf)).

I started by reading mlpdec.c (https://code.ffmpeg.org/FFmpeg/FFmpeg/src/branch/master/libavcodec/mlpdec.c) from ffmpeg (itself reverse engineered) to get a general sense of the format, then reverse engineered a much more recent decoder. My implementation covers TrueHD including Atmos, but does not support Meridian MLP (legacy FBB format).

[Balling]

There is now an encoder too, but HMAC algorithm has to be reverse engineered still or it will not play on AVRs. https://github.com/raress96/dolby-atmos-encoder/issues