Better sound for your video library, without touching a single frame.

$ python3 trackshepherd.py Series/
(1/3) S01E01 Pilot.mkv                           OK       00:05  2.4x  SQ 5.1(side)/1.0->2.0  17.1dB/17.3dB
(2/3) S01E02 The Return.mkv                      OK       00:02  5.2x  SQ  20.0dB
(3/3) S01E03 Finale.mkv                          OK       00:04  4.9x  HQ  -2.4dB
Total 3/3    3.9x  Elapsed 00:11  Media 00:44

01What TrackShepherd does

Old recordings, DVD rips and TV captures often come with audio that is too quiet, with a 5.1 mix that collapses badly on a laptop, or with a codec that some players refuse. TrackShepherd fixes exactly that part of the file and leaves everything else alone.

For every selected audio track it runs a fixed chain: layout-aware downmix to stereo, level analysis, one constant gain towards a true-peak target, AAC-LC encoding with neroAacEnc, and a check of the encoded result. Then it remuxes the new tracks with the original video into a Matroska file and verifies the timing before it writes the final name.

TrackShepherd is a complete rewrite of Playsheep, a Python 2 tool the author has used for years. The rewrite kept the idea and replaced the implementation. Along the way it found and fixed a downmix defect in the old tool that silently dropped the surround channels of almost every AC-3 and DTS source.

02Why neroAacEnc

Because it sounds best. neroAacEnc 1.5.4.0 is the AAC encoder the author trusts most, and after years of use it is still the one that produces the cleanest results he knows. The encoder has not changed since 2010, and it does not need to.

The default settings reflect the author's listening experience:

At 44.1 kHz, -q 0.36 is very close to transparency. The author has not heard artefacts at this setting. If you want transparency, use quality 0.40 (-Q 0.40).

For SD sources such as DVDs, the SQ profile uses 32 kHz and quality 0.40. A 32 kHz sample rate limits the audio bandwidth to 16 kHz, so this setting is not transparent in the strict sense. For this class of material, a higher sample rate or quality usually adds no audible value.

More background on encoder settings is part of the author's audio tool PyTranscoder on playsheep.de.

03Can and cannot

04Requirements

TrackShepherd is a single Python file. It needs three external programs. It does not install, download or bundle any of them.

How TrackShepherd finds the programs

TrackShepherd searches each program in a fixed order and uses the first match:

1. The path given with --ffmpeg, --ffprobe or --nero.
2. The directory that contains trackshepherd.py.
3. The directories in the PATH environment variable.

The program directory takes precedence over PATH. A common setup is FFmpeg installed system-wide and neroAacEnc placed next to trackshepherd.py.

On Linux, TrackShepherd looks for ffmpeg, ffprobe and neroAacEnc without extension and ignores .exe files. On Windows, it looks for ffmpeg.exe, ffprobe.exe and neroAacEnc.exe.

$ python3 trackshepherd.py --version
TrackShepherd 0.7.2
Dependencies
  Python      OK           3.12.3  [/usr/bin/python3]
  ffmpeg      OK           ffmpeg version 6.1.1  [/usr/bin/ffmpeg]
  ffprobe     OK           ffprobe version 6.1.1  [/usr/bin/ffprobe]
  neroAacEnc  OK           1.5.4.0  [/home/user/tools/neroAacEnc]
  Processing ready

About neroAacEnc

neroAacEnc is closed-source freeware by Nero AG. Its last release, version 1.5.4.0, dates from February 2010. Nero no longer offers the standalone encoder for download. This has three consequences for you:

• TrackShepherd does not include neroAacEnc. The Nero licence does not permit redistribution.
• You must obtain the encoder yourself and accept its licence terms.
• You should verify the file you obtain, because only archive copies and mirrors remain.

Where to look

Search for the archive NeroAACCodec-1.5.4.zip. It contains the Windows and the Linux encoder. These sources list it:

• ReallyRareWares, Nero AAC Encoder and Decoder, the download page linked from the Wikipedia article on the codec
• Internet Archive, Nero AACCodec 1.5.4
• VideoHelp, Nero AAC Codec

Background on the encoder is in the Hydrogenaudio Knowledgebase.

Verify the binary

TrackShepherd was tested with binaries that have these SHA-256 checksums:

# Linux
sha256sum neroAacEnc

# Windows
certutil -hashfile neroAacEnc.exe SHA256

Linux: 32-bit runtime

The Linux encoder is a 32-bit x86 program. A 64-bit Linux system must provide a 32-bit runtime. Without it, the file exists and is executable, but it does not start. TrackShepherd detects this case and names the cause.

sudo dpkg --add-architecture i386
sudo apt update
sudo apt install libc6:i386 libstdc++6:i386

Other distributions use other package names for the same libraries.

05Quick start

1. Download trackshepherd.py into a directory of your choice.
   Check: the file is about 225 KB.
2. Place neroAacEnc or neroAacEnc.exe in the same directory.
   Check: the checksum matches the table in section 04.
3. On Linux, make the encoder executable: chmod +x neroAacEnc.
4. Install FFmpeg, if it is not installed yet.
5. Run python3 trackshepherd.py --version.
   Check: the last line reads Processing ready. If a component reads MISSING/ERROR, fix that component first.
6. Inspect a file before processing it: python3 trackshepherd.py -i movie.mkv.
   Check: every audio track to be processed shows verified in its content anchor line.
7. Process the file: python3 trackshepherd.py movie.mkv.
   Check: the status line ends with OK or Warning.

The output file appears next to the source file, for example movie hD.mkv. The source file stays unchanged.

06How it works

TrackShepherd processes each input file in nine steps. Each step either succeeds or stops the file with a message. A failed file does not stop a batch.

1. Probe. ffprobe reads all streams, the container start time and the timing anchors of every track.
2. Plan. TrackShepherd selects the audio tracks, resolves each channel layout, builds the downmix matrix and chooses the profile.
3. Spool. With two or more audio tracks, FFmpeg copies the selected audio tracks once into a small audio-only file. The large source file is then not read again for analysis and encoding.
4. Analyse. For each track, FFmpeg decodes, downmixes and resamples the audio and measures sample peak, true peak and a level histogram.
5. Calculate gain. The gain is the true-peak target minus the measured true peak, plus optional overdrive.
6. Encode. FFmpeg applies downmix, resampling and gain and pipes PCM audio to neroAacEnc.
7. Check the peak. TrackShepherd decodes the AAC result and measures its true peak. If the peak exceeds the target by more than the tolerance, it re-encodes with less gain.
8. Mux. FFmpeg combines the source video, the new audio tracks and all other streams into a Matroska candidate file. The audio offset compensates container start times and codec delays.
9. Verify and commit. TrackShepherd checks structure, timing and packet integrity of the candidate. Only after all checks pass does it give the candidate its final name.

Downmix matrix

The matrix is built from the reported channel layout of each track. Relative weights are 1.0 for the front channel of the same side, 0.707 for centre and surround, 0.5 for secondary surround channels and back centre. LFE is discarded. Each output row is then scaled so that its weights add up to 1.0. This prevents clipping in the downmix itself. For 5.1 the result is 0.414 front, 0.293 centre and 0.293 surround, which reproduces the matrix of the original Playsheep tool exactly.

A track with more than two channels and no reported layout is not processed. Declare its layout with --assume-layout.

Normalisation

The peak mode applies one constant gain per track. It does not change the dynamics of the material. The target is a true peak of −1.0 dBTP after AAC decoding. Peak normalisation equalises peaks, not perceived loudness.

Overdrive adds gain beyond the peak target. A small fraction of samples may then exceed full scale and is caught by a limiter. The levels are: light 1 in 100 000 samples, medium 1 in 50 000, hard 1 in 25 000, brutal 1 in 12 500. The extra gain is limited to 6 dB.

The isolated peak guard handles recordings with a few defective full-scale samples. Without it, one click can prevent any gain for the entire recording. The guard ignores a very small number of samples near full scale, provided they lie clearly above the rest of the material. The budget is one sample per million analysed channel samples, rounded down and capped at 256. Short recordings with a budget below one do not use the guard. The histogram identifies rare high samples; it cannot distinguish a defective click from an intentional transient. A limiter catches the amplified peaks. The guard does not remove clicks.

07Options

python3 trackshepherd.py [OPTIONS] INPUT [INPUT ...]

INPUT is a file or a directory. Directories are read without subdirectories. Files with these extensions are processed: .mkv .mp4 .m4v .avi .mov .webm .ts .m2ts.

Everyday options

Track selection

-T, --tracks all | 0,2

Audio tracks to process, counted from 0 among the audio tracks. Default all. Tracks that are not selected are copied unchanged.

-l, --lang ger,eng

Additional filter by language code.

Profile

-p, --profile auto | sq | hq

auto selects SQ for a coded picture up to 720×576 and HQ for everything larger. Default auto. normal is an alias for sq.

-s, --samplerate HZ | source

Overrides the sample rate of the profile. source keeps the sample rate of each track.

-Q, --quality 0..1

Overrides the Nero quality value of the profile.

Audio

-c, --channels 2

Output channels. This version supports 2 only.

--assume-layout TRACK=LAYOUT

Declares the channel layout of an audio track, for example 0=5.1(side). Repeat for several tracks.

--downmix classic | ffmpeg

classic uses the matrix described in section 06. Default classic. ffmpeg uses the FFmpeg standard downmix for comparison.

Normalisation

-n, --normalize peak | off

peak normalises each track to the true-peak target. Default peak. off applies no gain.

--target-tp DBTP

True-peak target after AAC decoding. Default −1.0.

--max-gain DB

Upper limit for positive gain. Default 20.0.

--overdrive-db DB

Manual offset added to the calculated gain. Positive and negative values are allowed. Default 0.0.

--isolated-peak-guard auto | off

Ignores isolated full-scale samples when calculating the gain. Default auto.

--limiter auto | on | off

auto enables the limiter when overdrive or the isolated peak guard adds gain. Default auto.

--peak-tolerance DB

Allowed excess over the true-peak target without re-encoding. Default 0.2.

--peak-retries N

Maximum number of re-encodes per track after the first encode. Default 3.

--peak-warn-limit DB

An excess up to this amount is accepted with a warning instead of a retry or an error. Default 0.6. 0 disables this.

--peak-nonconform error | warn

Result when the target is still missed after all retries. Default error.

Output

--name-template TEMPLATE

Output file name without extension. Default "{stem} {res}{lang}". See section 08.

--keep-temp

Keeps the working directory after a successful run.

--on-incompatible-stream fail | drop

Handling of streams that Matroska cannot hold. Default fail.

--timing-log FILE

Explicitly enables reading and writing the timing log at FILE. Disabled by default.

--no-timing-log

Disables timing-log reads and writes, including an explicit --timing-log.

Tools

--ffmpeg PATH, --ffprobe PATH, --nero PATH

Explicit path to a program. Takes precedence over the program directory and PATH.

Modes and diagnostics

-a, --analyze

With --inspect or --dry-run: also run the level analysis.

-j, --json

With --inspect or --dry-run: output JSON.

--verify fast | full

fast checks structure, timing and the complete AAC stream copy. Default fast. full additionally decodes the complete output.

--serial-audio

Processes audio tracks one after another, without spool and parallel workers. For diagnostics.

--audio-workers N

Maximum parallel audio workers. 0 means CPU cores minus one. Default 0.

--stop-on-error

Stops a batch after the first failed file.

--log FILE

Additional session log. Every output file gets its own log in any case.

--no-progress

Disables the live progress display.

--version

Shows the version and the status of all dependencies.

--license

Prints the licence text.

08Output and display

Output file name

The default template {stem} {res}{lang} builds the name from three parts.

Example: Movie.mkv with a 1920×1080 picture, one German and one English track, becomes Movie 2DE.mkv. If the output name equals the source name, TrackShepherd stops.

Normal display

Without -v, TrackShepherd shows one line per file and one line for the whole job. While a file is running, its line shows the current step, the progress and the speed. The job line shows the number of finished files, the average speed, the elapsed time and the estimated remaining time.

(2/30) Episode 02.mkv                           Encoding     42.3%  18:52/44:37  01:13  36.1x
Total 1/30   9.8x  Elapsed 04:31  Remaining 2:12:40

When a file is finished, its line becomes permanent and shows status, duration, speed, profile and the applied gain per track. The job line remains after the program ends.

On a terminal, OK is green, Warning yellow and Failed red. The environment variable NO_COLOR disables colours.

Verbosity levels

Logs

Every output file gets a log with the same name plus .log. If processing fails, the log is named <output>.failed-<time>.log, and an existing log of a previous successful run stays untouched. The working directory of a failed file is kept for diagnostics. TrackShepherd removes working directories of aborted runs at the next start.

09Examples

Process one file

python3 trackshepherd.py "Movie.mkv"

Process a directory with medium overdrive

python3 trackshepherd.py -m /media/video/Series/

Write the results to another directory

python3 trackshepherd.py -o /media/converted /media/video/Series/

Process only the German track

python3 trackshepherd.py -l ger "Movie.mkv"

Use transparent quality for a high-definition source

python3 trackshepherd.py -Q 0.40 "Movie.mkv"

Look before processing

python3 trackshepherd.py -i "S01E01 Pilot.mkv"

Output            S01E01 Pilot sUU.mkv
Audio tracks      2 total, 2 will be encoded

Audio 0  Index 1  ac3  6 channels  48000 Hz  Language none  [processed]
    Layout          5.1(side)  provenance reported
    Content anchor  +0.000333s from presentation, correction +0.005333s, provenance matroska-codecdelay, verified
    Coefficients    FL 0.414  FC 0.293  SL 0.293   (display)
    Note            LFE discarded
    Encoding        AAC-LC, 2 channels, 32000 Hz  Profile SQ (automatic)  Nero q 0.40
    Normalisation   peak  Target -1.0 dBTP  Overdrive off  manual +0.0 dB  Peak-Guard auto

Audio 1  Index 2  mp3  1 channels  44100 Hz  Language none  [processed]
    Layout          mono  provenance reported
    Note            mono is duplicated to stereo

Follow the details of one file

python3 trackshepherd.py -vv "S01E03 Finale.mkv"

INFO  Source: S01E03 Finale.mkv
INFO  Picture: 1920x1080
INFO    Audio 0: mp3, 2 -> 2 channels, 44100 Hz, profile HQ (automatic), Nero q 0.36
INFO  Output: S01E03 Finale 2U.mkv
INFO  Track 0: true peak -0.20 dBTP; excess 0.80 dB above target -1.00 dBTP; retry with -0.90 dB.
INFO  Track 0: true peak -1.00 dBTP, target -1.00 dBTP, compliant.
INFO  Result audio 0: input true peak +0.47 dBTP, gain -2.37 dB, AAC true peak -1.00 dBTP.
INFO  Done and verified. S01E03 Finale 2U.mkv

A track without layout information

python3 trackshepherd.py --assume-layout 0=5.1(side) "Old recording.avi"

Fast run for a large collection

python3 trackshepherd.py -t -m /media/video/

10Verification

TrackShepherd writes every result to a hidden candidate file in the output directory. It renames the candidate to the final name only after all checks have passed. An existing output file is replaced only with --force, and only at that moment. The source file is never written.

Timing

TrackShepherd does not assume that the output is in sync. It measures it. For each processed track it derives the content anchor of the source audio from the container fields, including Matroska CodecDelay and MP4 skip samples. After the mux it reads the same anchors from the output file and compares the offset between audio and video. If an anchor cannot be proven, the file stops with a message. It is not written with a guessed offset.

In the test matrix, measured deviations stayed below 0.5 ms, including AC-3 and MP3 sources with codec delay and sources with a global start offset.

Duration and timestamp tails

Before encoding, TrackShepherd scans decoded audio frame timestamps and sample counts. Forward gaps larger than 5 ms enable silence insertion during resampling, without time stretching. Backward or overlapping timestamps beyond 5 ms stop the file instead of deleting samples. Ordinary continuous audio keeps the original resampling path. Decoder diagnostics produce a warning; damaged audio cannot be reconstructed. For --inspect and --dry-run, the frame scan runs only with --analyze. Without that scan, displayed resampling commands are provisional for timestamp discontinuities.

Some recordings also contain malformed terminal packets with timestamps beyond the last decodable frame. TrackShepherd accepts a large global duration difference only if all of these conditions hold:

• The copied video keeps the same packet time span, and all video packet hashes match, including in turbo mode.
• The encoded AAC track matches the decoded PCM duration.
• The decoded audio ends at about the same time as the picture.
• Every source audio packet has a reported duration. Their sum matches the raw decoded sample duration within the audio-duration tolerance.
• The packet time span exceeds that sum by the reported tail, within the same tolerance.
• The analysed PCM matches the audited frame timeline, including inserted silence, within 5 ms plus one output sample.

The audio-duration tolerance is the greater of 250 ms and twice the normal duration allowance. It accounts for codec framing and padding; it is not proof that every source packet is valid. File 410 contains a one-byte terminal MP3 packet with a reported 24 ms duration. No decoder can recover a complete MP3 frame from that byte. Decoder damage remains visible as a warning. A failed duration or timing check prevents publication of the output.

11Remaining-time estimate and timing log

Before processing, TrackShepherd reads the duration and the number of audio tracks of every input file. It uses these values to estimate the duration of the job.

The built-in model is derived from 402 real files on one machine. The new source-timeline scan adds work not present in those historical measurements. Historical fit is not an independent accuracy guarantee. Only the newest 20,000 log lines are retained in memory; reading time still grows with the log file.

The model distinguishes the number of audio tracks and turbo mode. On this data set it processed one stereo track at about 10× real time, two tracks at about 8×, and one track in turbo mode at about 13×. The actual speed depends on your hardware.

During the job, TrackShepherd compares the measured duration of finished files with the prediction and corrects the estimate for the remaining files. Files that fail immediately do not affect this correction. In a retrospective test on the same data, the median error of the remaining-time estimate was 2.5 %, and 90 % of estimates were within 17 %.

Timing log

Timing logging is disabled by default. TrackShepherd neither reads an existing timing log nor creates or appends one unless you explicitly pass --timing-log FILE. The remaining-time display uses the built-in model and the current job's measured processing times.

With --timing-log FILE, TrackShepherd reads that file and appends processing measurements. After at least eight normal files per category, the log can refine the model on the next start. The log contains durations, phases, track counts, retries and mode flags, but no file names or paths. --no-timing-log disables both reads and writes even if a log path is supplied. Ordinary per-file diagnostic logs remain active.

12Limits

• Stereo output only. neroAacEnc can encode 5.1, and the channel order has been measured, but multichannel output is not implemented. not implemented
• AAC-LC only. HE-AAC, MP3, Vorbis and Opus are not implemented. not implemented
• Peak normalisation only. Loudness normalisation to LUFS is not implemented. not implemented
• Matroska output only. Every output file is .mkv.
• Peak retries cost time. neroAacEnc does not respond linearly to gain changes near full scale. A track can need up to four encodes to meet the target.
• Windows has seen less testing than Linux. Program discovery and process handling are implemented for Windows.
• Unverifiable timing stops the file. TrackShepherd does not guess an offset. Containers without usable timing anchors cannot be processed.
• File systems without hard links. On FAT and exFAT the final commit may fail. Use an output directory on another file system.

13Download

trackshepherd.py

One Python file, version 0.7.2. It contains the complete program and the licence text. It does not contain FFmpeg or neroAacEnc.

sha256: cb5dabe1f66e04f06bc67863b3740df5a17fda2faa34a2aa69390faa67d812e5

sha256sum trackshepherd.py
python3 trackshepherd.py --version
python3 trackshepherd.py --help

How it was built

TrackShepherd was developed in a review loop between several AI models, GPT "Ada", GPT "Astra" and Claude Opus, with the author in the middle. Each model reviewed the others' work and tried to break it. Defects found and fixed this way include the surround-dropping downmix of the original tool, a timing formula that shifted MP3 and AC-3 sources by their codec delay, a duration check that could have accepted lost audio, and several display defects. Measurements with the real neroAacEnc binary decided every disputed point.

14Licence

TrackShepherd is source-available, not OSI open source. In plain terms: use it for anything, including paid work, copy it, change it, keep the attribution, and ask the author before selling it. The binding text is below. python3 trackshepherd.py --license prints the same text.

Playsheep Source-Available Licence 1.0
Copyright (c) 2026 J. Philipp de Graaff, www.playsheep.de

1. Definitions
   "Software" means the software and its documentation supplied under this
   licence, in source or binary form. The accompanying copyright notice or
   project information identifies the covered software.
   "Derivative" means any work based on the Software or containing a
   substantial part of it.
   "You" means the person or organisation exercising the permissions below.
   Third-party components identified as separately licensed remain governed
   by their own licences. This licence does not restrict the rights granted
   by those licences.

2. Permission to use
   You may use the Software for any purpose, without charge. This expressly
   includes use inside a company, an authority or any other organisation,
   and use as a tool while performing paid work for a third party.

   Documents and other input data do not become subject to this licence
   merely because they are processed with the Software. You may use, copy,
   modify, redistribute and sell documents produced with the Software,
   including formatting styles incorporated by its export function, without
   the restrictions imposed by this licence. This output exception does not
   grant rights in third-party content or permit distribution of the
   application itself as an exported document.

3. Permission to copy, modify and redistribute
   You may copy the Software, modify it and redistribute the original or a
   Derivative, free of charge, provided that:
   a) this licence and the copyright and authorship notices are retained in
      full and remain visible in the source;
   b) modified files are marked as modified, stating who changed them and when;
   c) a Derivative is not presented as the original software, and the software's
      name is not used in a way that suggests the copyright holder endorses it.

4. Restriction on sale and commercial distribution
   Without prior written permission from the copyright holder, you may not:
   a) sell the Software or a Derivative, or licence it for a fee;
   b) distribute the Software or a Derivative as, or as part of, a product or
      service that is offered for payment, where the Software provides a
      substantial part of that product's or service's function or value;
   c) offer the Software or a Derivative as a hosted or managed service.
   Section 4(c) applies whether or not the service is offered for payment.
   Section 2 is not limited by this section. Using the Software as a tool to
   do paid work remains permitted.
   If you would like to do something this section does not allow, please ask.
   Separate commercial licences are available.

5. No trademark or patent licence
   This licence grants no trademark rights in the software's name, the name
   Playsheep, or any logo, and no rights under any patent.

6. No warranty
   The Software is provided "as is", without warranty of any kind, express
   or implied, including but not limited to warranties of merchantability,
   fitness for a particular purpose and non-infringement. The Software may
   contain errors and may produce incomplete or incorrect results.
   Mandatory statutory rights remain unaffected.

7. Limitation of liability
   To the fullest extent permitted by applicable law, the copyright holder
   shall not be liable for any loss of data, loss of profit, business
   interruption or any other direct, indirect, incidental, special or
   consequential damages arising out of the use of or inability to use the
   Software. Liability that cannot be excluded under applicable mandatory
   law remains unaffected. This includes, in particular, liability for intent,
   gross negligence, and culpable injury to life, body or health.

8. Termination
   Your rights under this licence end automatically if you breach it. They
   are reinstated if you cure the breach within 30 days of becoming aware of it.

9. Severability and language
   If any provision is held unenforceable, the remaining provisions stay in
   force. The English text is the binding version. Any translation is provided
   for convenience only.

Contact for commercial licensing and matters not covered by this licence:
license@playsheep.de or via the website https://playsheep.de/

neroAacEnc and FFmpeg are separate programs under their own licences. They are not part of TrackShepherd.