deew 5.0.0 · how the tools are wired

deew tool chain

deew itself never touches audio. It probes the input, then chains ffmpeg, truehdd, dee_shim and the DEE command line tools through temp files and one pipe, with the options shown below. Placeholders are in capitals: IN, TI (track index), TEMP/NAME, OUT, B (bitrate), P (DRC profile).

external tool file / data deew only in some cases

The whole chain

Three lanes: probing (always), the channel path (DD, DDP, TrueHD, AC4, AAC) and the Atmos path (ddp-atmos, thd-atmos, ac4-atmos). Both paths end in one DEE encoder, wrapped in dee_shim when the format needs it.

JSON -rf64 -i NAME.wav (--input-format wav) pipe writes -i NAME.atmos raw .thd: truehdd reads IN directly container -o IN wav, flac, ac3, thd, mkv, m2ts… ffprobe every input stream info codec, channels, rate deew checks, builds every command ffmpeg pan / downmix / resample → PCM NAME.wav RF64 PCM, TEMP dee_measure_loudness only with -mo or -dn loudness.json → --input-manifest ffmpeg copy track TI mkv / mka / m2ts truehdd decode presentation 3 NAME.atmos + .metadata + .audio (DAMF) DEE encoder dee_ddp_encoder dee_ddpjoc_encoder dee_dthd_encoder dee_ac4(ajoc)_encoder dee_aac_encoder dee_shim wraps it when needed OUT .ac3 .ec3 .eb3 .thd .ac4 .aac

Which blocks each format uses

Left to right, as data flows. Dashed blocks only appear in the case noted.

dd · ddp ≤ 5.1 · ac4 · aacDEE measures while encoding
IN→ffmpeg→NAME.wav→dee_ddp / ac4 / aac_encoder→OUT
any channel format with -dnseparate measurement, deew writes the dialnorm
IN→ffmpeg→NAME.wav→dee_measure_loudness→loudness.json→deew sets dialnorm→ --input-manifest →DEE encoder→OUT
-mono encoder runs
IN→ffmpeg→NAME.wav→dee_measure_loudness→loudness.json→loudness in the bar
ddp 7.1 --ddp-mode blurayBlu-ray profile, native
IN→ffmpeg→NAME.wav→dee_ddp_encoder -e bluray→OUT.eb3
ddp 7.1 standard · ddp 7.0--ddp-mode standard (the default) · 7.0 in both modes
IN→ffmpeg→NAME.wav→dee_shim ddp_encoder--binary →dee_ddp_encoder→OUT
thddee_shim only with DRC none (the default)
IN→ffmpeg→NAME[.thd][.dm2].wav→dee_shim dthd_encoder→dee_dthd_encoder→OUT.thd
ddp-atmos--ddp-atmos-mode streaming (5.1 JOC), standard or bluray (7.1) · raw .thd or a container track
IN.thd→IN.mkv/m2ts→ffmpeg copypipe →truehdd decode→NAME.atmos→dee_shim ddpjoc_encoder--binary →dee_ddpjoc_encoder→OUT.ec3 / .eb3
thd-atmos16 elements, sample-exact objects · raw .thd or a container track
IN.thd→IN.mkv/m2ts→ffmpeg copypipe →truehdd decode→NAME.atmos→dee_shim dthd_encoder--binary →dee_dthd_encoder→OUT.thd
ac4-atmosnative, no dee_shim · raw .thd or a container track
IN.thd→IN.mkv/m2ts→ffmpeg copypipe →truehdd decode→NAME.atmos→dee_ac4ajoc_encoder→OUT.ac4

DDP profiles

--ddp-mode picks the profile of 7.1 DDP (5.1 and below are not affected), --ddp-atmos-mode the profile of ddp-atmos. Without the option deew uses the config's [default_modes].

OptionModeEncoder--layout-e modeCoded asBitratesExt
--ddp-modestandard (default)dee_shim ddp_encoder7.1/eac3ddpE-AC-3 independent + dependent384–1792.ec3
bluraydee_ddp_encoder—blurayAC-3 core + E-AC-3 dependent768–1664.eb3
standard, 7.0dee_shim ddp_encoder7.0/eac3ddpE-AC-3 independent + dependent384–1792.ec3
bluray, 7.0dee_shim ddp_encoder7.0blurayAC-3 core + E-AC-3 dependent768–1664.eb3
--ddp-atmos-modestreaming (default)dee_shim ddpjoc_encoder5.1ddpjoc5.1 E-AC-3 + JOC384–1024.ec3
standarddee_shim ddpjoc_encoder7.1/eac3bluray7.1 E-AC-3 independent + dependent, Atmos768–2048.ec3
bluraydee_shim ddpjoc_encoder7.1bluray7.1 AC-3 core + E-AC-3 dependent, Atmos1152–1664.eb3
Column / termMeaning
EncoderThe program deew runs. dee_shim …_encoder loads the DEE encoder through dee_shim, dee_ddp_encoder runs DEE directly (no dee_shim needed).
--layoutdee_shim's option, before the --: the output channel layout and how it is coded. /eac3 means an E-AC-3 independent substream instead of an AC-3 core; 7.0 drops the LFE. —: not run through dee_shim, so there is no --layout.
-e modeDEE's own encoder mode, after the --: the part before :drc_profile=P. ddp is plain E-AC-3, bluray is DEE's Blu-ray mode, ddpjoc is E-AC-3 with Atmos objects.
AC-3 core + E-AC-3 dependentThe Blu-ray structure: a 5.1 AC-3 (Dolby Digital) stream that every Dolby decoder can play, plus an E-AC-3 stream with the extra channels for DDP decoders.
E-AC-3 independent + dependentNo AC-3 core: the 5.1 base is E-AC-3 too, plus a dependent E-AC-3 stream with the extra channels. Needs a DDP decoder, but allows lower bitrates.
JOCJoint Object Coding: Atmos objects carried inside a 5.1 E-AC-3 stream, the format of streaming services.
.ec3 / .eb3.ec3 is an E-AC-3 stream; .eb3 marks the Blu-ray structure with an AC-3 core.
7.0A 7.1 input with -dl, or a 7.0 input. It goes through dee_shim in both modes.

The default bitrate of each profile is set in the config (ddp_7_1_standard, ddp_7_1_bluray, ddp_atmos_streaming, ddp_atmos_standard, ddp_atmos_bluray), deew -lb lists every allowed bitrate.

Every block and its options

The exact argument lists deew builds, in order. -la prints the same commands with your real paths.

ffprobe

external · every input

Runs once per input before anything else. Its JSON decides the layout, the bitrate table, the Atmos checks and the progress total.

In

  • the input file

Out → deew

  • audio stream TI: codec, profile (Atmos?), channels, channel layout, sample rate, bit depth
  • duration (progress total, decode length check)
ffprobe -v error -print_format json -show_format -show_streams IN

ffmpeg · convert

external · channel formats

Turns track TI into the PCM wav DEE reads, in DEE's channel order. Skipped when the wav is already in TEMP from a run with -k.

In

  • IN, any format ffmpeg reads

Out

  • TEMP/NAME[.variant].wav, RF64
  • stderr time= → progress bar
ffmpeg -y -drc_scale 0 -i IN
       -map 0:a:TI                                   # when no filter is needed
       -c pcm_s16|24|32le                           # input bit depth, 32 when resampling
       -filter_complex '[a:TI]PAN'                   # reorder / silent LFE / TrueHD downmix
       -filter_complex '[a:TI]PAN,aresample=resampler=soxr'
         -ar 48000|96000 -precision 28 -cutoff 1 -dither_scale 0   # rate change
       -rf64 always TEMP/NAME.wav
CaseFilter (PAN)wav name
mono, stereo, plain 5.1none, -map 0:a:TINAME.wav
7.1 (ffmpeg has back before side)pan=7.1|c0=c0|c1=c1|c2=c2|c3=c3|c4=c6|c5=c7|c6=c4|c7=c5NAME.wav
5.0 inputpan=5.1|c0=c0|c1=c1|c2=c2|c3=0*c0|c4=c3|c5=c4NAME.wav
7.0 inputpan=7.1|c0=c0|c1=c1|c2=c2|c3=0*c0|c4=c5|c5=c6|c6=c3|c7=c4NAME.wav
-dl on TrueHD / AC4 (LFE kept silent)LFE slot becomes 0*c0NAME.dl.wav
TrueHD -dm 6 from 7.1aformat=sample_fmts=dbl,pan=5.1|…|c4=0.5*c4+0.5*c6|c5=0.5*c5+0.5*c7NAME.dm6.wav
TrueHD -dm 2aformat=sample_fmts=dbl,pan=stereo|c0=c0+0.7071*c2+… → per-channel alimiter=limit=0.98855:level=0:latency=1 → joinNAME.dm2.wav
not 48 kHz (DD, DDP, AC4, AAC)soxr to 48000NAME.wav
TrueHD, not 48 / 96 kHzsoxr to 48000 (below 72 kHz) or 96000NAME.thd.wav

ffmpeg · copy to pipe

external · Atmos from a container

truehdd only reads raw TrueHD, so for mkv / mka / m2ts ffmpeg copies the track unchanged and streams it into truehdd's stdin. Not used for a raw .thd.

In

  • IN container, track TI

Out

  • raw TrueHD on stdout → truehdd stdin
  • only the exit code counts (timestamp warnings are ignored)
ffmpeg -v error -nostdin -i IN -map 0:a:TI -c copy -f truehd -

truehdd

external · Atmos formats

Decodes the Atmos presentation into a DAMF master: the object audio plus its metadata. Afterwards deew checks that an Atmos presentation was found and that the decoded length matches ffprobe's duration.

In

  • IN (raw .thd) or - (stdin from ffmpeg)

Out

  • TEMP/NAME.atmos, .atmos.metadata, .atmos.audio
  • NAME.caf instead when there is no Atmos (the job fails)
  • JSON lines on stdout → frame count, progress
truehdd decode --presentation 3 --json --output-path TEMP/NAME IN|-

dee_measure_loudness

DEE · only with -mo or -dn

A separate loudness pass. With -dn, deew then writes your dialnorm into the manifest and hands it to the encoder, which skips its own measurement. Doesn't take 7.1, and has no --temp-dir.

In

  • TEMP/NAME.wav

Out

  • TEMP/NAME.loudness.json
  • its own 0–100% progress step, measured dB
dee_measure_loudness --progress 1 --overwrite 1 --input-format wav -i TEMP/NAME.wav
                     --output-manifest TEMP/NAME.loudness.json

DEE encoders

DEE 6.7 · from the dee folder

Every encode starts with --progress 1 --overwrite 1 and ends with the delay and temp options. DEE's [===>] N % lines drive the bar; [Source loudness] shows the measured dB.

In

  • NAME.wav or NAME.atmos
  • loudness.json with -dn

Out

  • OUT in the output folder
  • AC4: TEMP/NAME.ac4.json manifest
  • TrueHD: .mll / .thd.log.html (removed, log kept with -kl)

DD · DDP (≤ 5.1, and 7.1 with --ddp-mode bluray)

dee_ddp_encoder --progress 1 --overwrite 1 --input-format wav -i TEMP/NAME.wav -o OUT
                -e dd|ddp|bluray:drc_profile=P[:lfe_on=0] --data-rate B
                -c mono|stereo|5.1                      # DEE downmixes (-dm, or 7.1 → 5.1 for DD)
                --loudness-management measure_only [--input-manifest TEMP/NAME.loudness.json]
                [--start S | --add-silence S:0] --temp-dir TEMP/dee-PID-INDEX

AC4

dee_ac4_encoder --progress 1 --overwrite 1 --input-format wav -i TEMP/NAME.wav -o OUT
                --output-manifest TEMP/NAME.ac4.json --data-rate B -e drc_profile=P
                -c stereo|5.1 --loudness-management measure_only [--input-manifest …]
                [--start S | --add-silence S:0] --temp-dir TEMP/dee-PID-INDEX

AAC

dee_aac_encoder --progress 1 --overwrite 1 --input-format wav -i TEMP/NAME.wav -o OUT
                -e aaclc --data-rate B --loudness-management skip     # DEE downmixes to 2.0 itself
                [--start S | --add-silence S:0] --temp-dir TEMP/dee-PID-INDEX

TrueHD (DRC other than none)

dee_dthd_encoder --progress 1 --overwrite 1 --presentation 2ch|6ch|8ch:drc_profile=P
                 --input-format wav -i TEMP/NAME.wav -o OUT
                 [--start S | --add-silence S:0] --temp-dir TEMP/dee-PID-INDEX

AC4 Atmos

dee_ac4ajoc_encoder --progress 1 --overwrite 1 -i TEMP/NAME.atmos -o OUT
                    --output-manifest TEMP/NAME.ac4.json --level 3 --data-rate B -e drc_profile=P
                    [--start S | --add-silence S:0]          # no --temp-dir
Delay trim added to -dSamplesat 48 kHz
DD, DDP, DDP Atmos256--start 0.005333
AC4, AC4 Atmos2048--start 0.042667
AAC1600--start 0.033333
TrueHD, TrueHD Atmos0only your -d

dee_shim

external · in front of a DEE encoder

Loads the untouched DEE encoder (--binary) into its own process and patches it in memory. Shim options go before --, DEE's own options after it. deew removes DSHIM_LOG, DSHIM_LOG_LEVEL, DSHIM_LOG_FORMAT, RUST_LOG and DEE_SHIM_* from its environment.

Needed for

  • ddp-atmos, thd-atmos
  • TrueHD with DRC none
  • 7.1 DDP standard profile, 7.0 DDP

Errors

  • exit 2: usage error, 3: lever not applicable (nothing written)
  • deew shows its first error: line

DDP Atmos

dee_shim ddpjoc_encoder --binary dee/dee_ddpjoc_encoder --layout 5.1|7.1/eac3|7.1 --oamd-as-is on --bitrate B --
         --progress 1 --overwrite 1 -e ddpjoc|bluray:drc_profile=P
         --input-format atmos_mezz -i TEMP/NAME.atmos -o OUT [--start S | --add-silence S:0]

TrueHD Atmos

dee_shim dthd_encoder --binary dee/dee_dthd_encoder --oamd-as-is on --as-is on --drc P --
         --progress 1 --overwrite 1 --presentation atmos:number_of_elements=16:legacy_authoring=0
         --input-format atmos_mezz -i TEMP/NAME.atmos -o OUT
         [--start S | --add-silence S:0] --temp-dir TEMP/dee-PID-INDEX

TrueHD, DRC none

dee_shim dthd_encoder --binary dee/dee_dthd_encoder --drc none --
         --progress 1 --overwrite 1 --presentation 2ch|6ch|8ch:drc_profile=film_light   # placeholder, the shim's --drc wins
         --input-format wav -i TEMP/NAME.wav -o OUT [--start S | --add-silence S:0] --temp-dir TEMP/dee-PID-INDEX

7.1 DDP standard · 7.0 DDP

dee_shim ddp_encoder --binary dee/dee_ddp_encoder --layout 7.1/eac3|7.0/eac3|7.0 --bitrate B --
         --progress 1 --overwrite 1 -e ddp|bluray:drc_profile=P
         --input-format wav -i TEMP/NAME.wav -o OUT --loudness-management measure_only
         [--input-manifest TEMP/NAME.loudness.json] [--start S | --add-silence S:0] --temp-dir TEMP/dee-PID-INDEX
Case--layout-e modeCoded asExt
7.1 standard7.1/eac3ddpE-AC-3 independent + dependent.ec3
7.0 standard (-dl or 7.0 input)7.0/eac3ddpE-AC-3 independent + dependent.ec3
7.0 with --ddp-mode bluray7.0blurayAC-3 core + E-AC-3 dependent.eb3
DDP Atmos streaming5.1ddpjocE-AC-3 + JOC.ec3
DDP Atmos standard7.1/eac3blurayE-AC-3 independent + dependent, Atmos.ec3
DDP Atmos bluray7.1blurayAC-3 core + E-AC-3 dependent, Atmos.eb3

deew between the blocks

deew

What deew does with the files and output streams that pass through it.

Reads

  • ffprobe JSON
  • ffmpeg stderr (time=), truehdd JSON lines, DEE stdout (N %, measured_loudness)
  • each tool's exit code and last stderr line

Writes

  • the dialnorm into loudness.json (-dn)
  • progress events to DEEW_EVENTS_FILE (GUI, web)
  • NAME.deew-log.html with -kl

Removes

  • TEMP/dee-PID-INDEX after every job
  • wav / atmos / json temp files unless -k
  • partial output on Ctrl-C