Repository navigation
Commands
Run ./converter with no arguments to print help. Media inputs are auto-discovered from SRC_DIR (default: the Output/ folder); scanning is non-recursive.
| Command | Description |
|---|---|
-full, -run
|
Full production pipeline: image deliverables, audio deliverables (WAV/M4A/MP3 + RF64/BW64 archival companions), main MP4, and four portrait shorts (fitted and centre-cut, each with a _FullSong companion) |
-album |
Album version of the full run: 2+ .mp3/.wav/.flac tracks (natural numeric filename order), each normalized to -12 LUFS, joined into one RF64 album.wav, then the full-run pipeline |
Full run inputs: exactly 1 source audio (.flac/.wav/.mp3) plus either exactly 1 source image or direct Horizontal_8K.png (+ optional Vertical_8K.png). See Full Run Contract.
| Command | Description |
|---|---|
-short |
Exactly 1 image (.png/.jpg/.jpeg) + exactly 1 audio-only file supported by ffmpeg -> ALAC portrait shorts capped at 58 s: _8K_Short.mp4 fits the image with black padding, _8K_Short_CenterCut.mp4 crops the centre of the 8K master to fill the frame; each gains a _FullSong full-length companion when the audio is longer |
-nfttoshort |
Any single audio-only file supported by ffmpeg + image resolution that prefers Vertical_8K.png, then an existing *_NFT8K.png, then NFT artwork derived from a landscape *_8K.png or source image; centered with black top/bottom padding; preserves source loudness -> ALAC _8K_Short.mp4 plus _8K_Short_CenterCut.mp4 filling the frame from the centre of the 8K master, both capped at 58 s, each with a _FullSong full-length variant when the audio is longer |
-m4atomp4 |
Exactly 1 *_8K.png + exactly 1 .m4a -> main MP4 |
-mp4toshort |
One or more .mp4 -> _Short.mp4 portrait clips capped at 58 s |
-mp3toshort is no longer a valid name — see If you are upgrading. All short outputs preserve source audio loudness. The standard short clips are capped at min(SHORT_MP4_CLIP_SECONDS, 58) seconds; when the source audio is longer, -short, -nfttoshort, and the full run additionally render _FullSong companions with the same portrait graphics. Every short is produced in two framings — fitted (_8K_Short) and centre-cut (_8K_Short_CenterCut), the latter filling the frame from the middle of the 8K master with no black padding.
| Command | Description |
|---|---|
--hash |
Rename .wav/.flac/.mp3/.mp4 files to CRC32-based filenames after preflight |
-bass [FREQ_HZ GAIN_DB] |
Same-format _bass copies; default boosts 0-80 Hz by 5 dB; negative gain reduces bass |
-loudscan |
Report average, lowest, highest, and top-3 loudest average loudness |
-loudness [TARGET_LUFS] |
Same-format normalized copies (default -12 LUFS, static gain only, peak-constrained when needed) |
-master |
Same-format _mastered copies; stages through the internal WAV and remediates loudness to the mastering target (two-pass loudnorm with one-pass fallback) when the source is out of policy |
-fade [SECONDS] |
Tail-fade same-format copies with settings-specific suffixes such as _faded_5s (default 10 s; -fadeflac alias) |
-fadecut CUT FADE |
Remove CUT seconds from the end, then fade the final FADE seconds; writes _fadecut_<CUT>s_<FADE>s
|
-fadeout START DURATION |
Fade from START for DURATION and truncate (accepts M:SS/HH:MM:SS); writes _fadeout_<START>s_<DUR>s
|
-fadewav |
Faded RF64 WAV files |
-noise [SECONDS] |
Noise lead-in/tail padding around 2 s silence gaps (default 30 s, noise at -12 LUFS) |
-silence [SECONDS] |
Silent lead-in/tail padding (default 30 s; .wav/.flac/.mp4) |
-mp3clean |
Rewrite MP3s as audio-only, removing artwork/junk streams/metadata |
| Format conversions |
-flactowav, -flactomp3, -flactom4a, -flactoalbum, -flactohash, -m4atowav, -m4atomp3, -m4atoflac, -mp3toflac, -mp3towav, -mp3tom4a, -mp3toalbum, -mp3tohash, -wavtom4a, -wavtomp3, -wavtoflac, -wavtoalbum, -wavtohash
|
Album build actions (-flactoalbum, -mp3toalbum, -wavtoalbum) read track order from album.txt in the project root where applicable.
| Command | Description |
|---|---|
-run_pix |
Full image-only pipeline from source images |
-aipix |
_8K.png and _4K.png variants from .png inputs |
-jpgtopng |
.jpg/.jpeg -> .png
|
-pngtojpg |
.png -> .jpg
|
-pngtonft |
*_8K.png -> _NFT8K/_NFT3K/_NFT2K.png
|
-pngto3k, -pngto2k
|
*_8K.png -> square _3K.png / _2K.png
|
-pngto3k1mb, -pngto3k5mb
|
*_3K.png -> _1MB.jpg / _5MB.jpg
|
-pngtojpg1mb, -pngtojpg2mb, -pngtojpg20mb
|
*_8K.png -> sized _1MB/_2MB/_20MB.jpg
|
-visualsubs |
Generated dot-grid PNG (--num-dots N, --dot-size N) |
| Command | Description |
|---|---|
-doctor |
Validate toolchain, config, encoder/filter support, directories, and optionally current source media |
-clean |
Remove transient/temp files from OUT_DIR
|
-matrix |
Print the supported conversion matrix |
-list |
List available actions |
--config FILE, --profile NAME, --src-dir DIR, --out-dir DIR, --output-dir DIR, --output-file FILE (must resolve directly inside OUT_DIR), --overwrite, --keep-full-name, --lowercase-prefix, --continue-on-error, --trailing-silence, --sharpness FLOAT, --sleep-seconds FLOAT, --num-dots N, --dot-size N, --max-attempts N, --seed N, --open, --debug.
These names no longer exist. Each is rejected with a message naming its replacement, so an old script fails immediately instead of quietly doing something else.
| Old name | Use instead |
|---|---|
-mp3toshort |
-nfttoshort |
-jpegtopng |
-jpgtopng |
-pngtojpeg |
-pngtojpg |
--recursive |
withdrawn — discovery is always non-recursive |
--image, --audio
|
withdrawn — inputs are discovered from SRC_DIR by type |
--album-file |
withdrawn — use album.txt or -album
|
Environment variables: SRC_DIR, OUT_DIR, OUTPUT_DIR, CONFIG_FILE, DEBUG, CONVERTER_ROOT, CONVERTER_NAME, and CONVERTER_AUTO_INSTALL_DEPS=1 to opt into dependency auto-install (off by default — see Installing).
Batch actions fail on the first error by default; pass --continue-on-error to process everything possible and receive a summary of what failed.