Skip to content

Configuration

Jump to bottom
André Borchert edited this page Sep 16, 2026 · 6 revisions

Configuration

Project-wide settings live in config.txt as KEY=value lines. Blank lines and # comments are ignored, and unknown keys are skipped rather than treated as errors.

Settings are resolved in this order, each overriding the one before:

  1. Built-in defaults
  2. The selected profile
  3. config.txt
  4. Environment variables of the same name
  5. Command-line options

Invalid values are rejected at startup with a message naming the key, so a bad setting fails before any media is touched.

Profiles

Built-in profiles: youtube_master (default), youtube_short, archive, fast_preview.

  • PROFILE=youtube_master in config.txt sets the default profile
  • Override with --profile NAME

Key groups

Audio standards

  • WAV: WAV_SAMPLE_RATE=96000, WAV_CODEC=pcm_s24le, WAV_CHANNELS=2, WAV_WRITE_BEXT=1
  • MP3: MP3_SAMPLE_RATE=48000, MP3_BITRATE=320k, MP3_CHANNELS=2, MP3_MIN_BITRATE_BPS=300000
  • FLAC: FLAC_SAMPLE_RATE=48000, FLAC_CHANNELS=2, FLAC_COMPRESSION_LEVEL=12
  • M4A: ALAC lossless (24-bit, 48 kHz, stereo), M4A_SAMPLE_RATE=48000, M4A_CHANNELS=2

Audio QC targets

AUDIO_QC_TARGET_LUFS=-12, AUDIO_QC_LUFS_TOLERANCE=8, AUDIO_QC_MAX_TRUE_PEAK_DBTP=-1, AUDIO_QC_MAX_LOUDNESS_RANGE=20, AUDIO_QC_MAX_DC_OFFSET=0.02, AUDIO_QC_MAX_STEREO_IMBALANCE_DB=2, AUDIO_QC_MAX_CLIPPED_SAMPLES=0, AUDIO_QC_MINIMUM_ANALYSIS_SECONDS=3, plus SHORT_AUDIO_QC_* equivalents for short-form deliverables.

Mastering

Parameters for the explicit -master command (never applied automatically): MASTERING_TARGET_LUFS=-12, MASTERING_MAX_TRUE_PEAK_DBTP=-1, MASTERING_MAX_LOUDNESS_RANGE=20.

Main MP4 render

VIDEO_MP4_ENCODER=hevc_videotoolbox with VIDEO_MP4_ENCODER_FALLBACKS=libx265; 7680x4320, 2 fps input cadence, yuv420p, hvc1 tag, bt709 color metadata, TV range; VideoToolbox quality 70, software preset slow at CRF 18; ALAC audio.

Short MP4 render

SHORT_MP4_CLIP_SECONDS=58 (the effective cap is min(SHORT_MP4_CLIP_SECONDS, 58) s; a full-length _FullSong variant renders when the source audio is longer), 4320x7680 portrait, SHORT_MP4_VIDEO_CODEC=libx264 with h264_videotoolbox fallback, CRF 18 / VT quality 60, yuv420p, ALAC audio.

Image processing

8K/4K dimensions (7680x4320 / 3840x2160), 3K/2K square sizes (3000/2048), Lanczos filter, sharpness 1.2 (overridable via --sharpness), sRGB output colorspace, JPEG quality/sampling settings, and byte targets for sized JPG exports (IMAGE_3K_JPG_1MB_TARGET_BYTES, IMAGE_8K_JPG_20MB_TARGET_BYTES, etc.).

Album and fades

ALBUM_SILENCE_SECS=2, WAV_FADE_DUR=10.

A worked example

Say you want quieter deliveries than the default −12 LUFS, a sharper 8K upscale, and a slightly smaller main video — without typing options on every run. Edit config.txt:

# Delivery QC: −16 LUFS with a tighter tolerance than the default 8 LU
AUDIO_QC_TARGET_LUFS=-16
AUDIO_QC_LUFS_TOLERANCE=4

# Portrait deliverables are judged against their own keys
SHORT_AUDIO_QC_TARGET_LUFS=-16
SHORT_AUDIO_QC_LUFS_TOLERANCE=4

# Sharper 8K upscale (default 1.2)
IMAGE_AIPIX_SHARPNESS=1.4

# Smaller main video (default CRF 18; higher is smaller)
VIDEO_MP4_SOFTWARE_CRF=20

Validate it before you convert anything. -doctor reads every key and names the one that is wrong:

./converter -doctor

Then run as usual — the command line does not change:

./converter -full

For a one-off, leave the project's config.txt alone and point a single run somewhere else, or pick a built-in profile:

./converter -full --config ~/profiles/quiet.txt
./converter -full --profile fast_preview

The full list of shipped keys, with their defaults and comments, is the config.txt in the repository.

Clone this wiki locally