Repository navigation
Troubleshooting
Converter fails loudly and specifically rather than producing a questionable file. This page maps the errors you are most likely to hit to what to do about them.
Add --debug to any command to see the exact external commands being run.
Missing required Homebrew package(s): ffmpeg. Install them with 'brew install ffmpeg' or set CONVERTER_AUTO_INSTALL_DEPS=1 to auto-install.
Install the tool yourself, or opt into auto-install — see Installing. Auto-install is off by default on purpose.
Directory not found: …
The input directory does not exist. Output/ ships with the repository; if you deleted it, recreate it or point somewhere else with --src-dir.
Not sure whether the machine is set up correctly
./converter -doctorChecks every tool, the ffmpeg filters and encoders the pipeline depends on, directory permissions, and free space. It also preflights your current source media if there is exactly one image and one audio file present.
Full pipeline expects exactly one source audio file (.flac/.wav/.mp3) in '…'.
-full needs exactly one. You most likely have leftovers from a previous run — Output/ is meant to be cleared between runs. Archival companions (*_RF64.*, *_BW64.*) are ignored automatically, and when several files share one stem converter picks the highest-quality member and warns.
Full pipeline expects either Horizontal_8K.png for direct render or exactly one source image (.png/.jpg/.jpeg) in '…'.
Converter collapses a family it derived itself (9_8K.png, 9_4K.png, 9_NFT8K.png …) down to the most source-like member, so rerunning -full in its own output directory is fine. This error means it found two genuinely different images. Leave exactly one source image, or supply finished Horizontal_8K.png artwork.
Short render expects exactly one audio-only file supported by ffmpeg in '…'.
-short and -nfttoshort reject files containing a video stream. If you want a short from an existing MP4, use -mp4toshort.
album.txt builds support .wav and .mp3 tracks only (got 'flac').
-wavtoalbum and -mp3toalbum read album.txt. For FLAC, use -flactoalbum (directory order) or -album (directory order plus normalization).
Image must be 7680x4320. Got '3000x3000' … or Horizontal_8K.png must be 7680x4320 …
The main video needs exact 8K landscape input. Either let the full run derive it from a source image, or run -aipix first to produce *_8K.png. Vertical_8K.png must be exactly 4320×7680, and *_NFT8K.png must be square at 7680×7680.
Audio verification failed: input appears silent or not meaningfully audible: …
The file measures below −70 dB. Usually a truncated export or the wrong file — check it plays.
Audio QC failed for …: integrated loudness −28.40 LUFS outside target −12.00 +/- 8.00
The file is outside the configured QC window. Either it is genuinely far off target, or your AUDIO_QC_* settings are tighter than your material — see Configuration.
Loudness target must be at or below -5 LUFS because ffmpeg loudnorm supports -70 to -5 LUFS.
-loudness accepts targets in that range only. Note the argument is negative: ./converter -loudness -14.
Info: Source already exceeds delivery QC on: … Verifying the render does not worsen these
Not a problem. Converter preserves your source loudness, so a master that already sits outside a delivery ceiling — a loud true peak, a wide stereo image in the intro — cannot meet that ceiling without its audio being altered, which only -loudness, -master and -album (loudness) are allowed to do; the processing actions change audio only in the way their name says. Rather than fail forever or change your audio, converter rebases just the breached limits on what the source actually measures and still checks the render does not make them worse. Limits your source respects are untouched. The measurement covers exactly the stretch the render contains, so a 58-second short is judged on its first 58 seconds.
Warning: Created peak-constrained loudness media without compression
Not a failure. The source lacked headroom to reach the target, so converter applied the largest safe gain instead of compressing. The file is written and usable.
These mean an output was produced but did not survive checking, so it was not published. Your inputs are untouched.
Duration mismatch exceeds tolerance: src=180.02 out=178.41 …
The render lost or gained time. Usually a damaged or variable-bitrate source; re-encode the input to a clean file and retry.
Canonical PCM mismatch for External FLAC: … out_of_tolerance_samples=… max_delta=…
A lossless output did not match its source sample-for-sample within tolerance. This is the check that guarantees archival copies are faithful; a failure means the encode genuinely diverged.
Short MP4 exceeds hard limit 58.000s (got 61.200s)
The 58-second cap is enforced regardless of SHORT_MP4_CLIP_SECONDS. Longer material belongs in the _FullSong companion, which converter renders automatically.
All MP4 encoders failed for track_8K.mp4. libx264: … | h264_videotoolbox: …
Every rung's reason is listed, first failure first — the first one is usually the real cause. A failure that no encoder can fix (an audio QC rejection, for instance) stops the ladder immediately rather than retrying identical work.
Run -doctor to confirm the encoders exist. Note that h264_videotoolbox cannot open a compression session at 4320x7680, so at the default portrait size only libx264 can produce the shorts; VideoToolbox is useful there only for smaller profiles.
Low free space for internal WAV staging of song.flac: avail=… need~…
Every audio path stages through 24-bit / 96 kHz WAV, which is large — roughly 33 MB per stereo minute. Free space or point --out-dir at a bigger volume.
Command timed out after 1800 seconds: …
An external tool hung. Every invocation is bounded so a stuck process cannot stall a run forever. Retry; if it repeats, the input is likely malformed — try it directly in ffmpeg to see what it says.
A short has black bars and you wanted it filled (or vice versa)
Both framings are always produced. _8K_Short.mp4 fits the whole image inside the frame with black padding; _8K_Short_CenterCut.mp4 crops the centre of the landscape 8K master to fill the frame edge to edge. Pick whichever suits the upload — and note the centre cut necessarily loses the sides of the artwork.
"Skip existing …" when you wanted a rebuild
Converter verifies existing outputs and reuses valid ones. Force a rebuild with --overwrite.
Output path must stay directly in '…'
--output-file and album.txt entries must resolve directly inside the output directory. Subfolders and paths escaping the directory are rejected.
A batch stopped on the first bad file
That is the default — batch actions fail closed. Use --continue-on-error to process everything possible and receive a summary of what failed.
Unknown option: -mp3toshort (or another name from an older command set)
The flag was renamed or withdrawn. Each old name is rejected with a message naming its replacement — see Commands → If you are upgrading for the full list.
Hidden .converter-tmp.* files are run-scoped and cleaned automatically, including orphans from a crashed run. A .<name>.publish-backup file is the previous version of an output preserved mid-publish; converter restores or removes it on the next run. To clear transients manually:
./converter -clean