Skip to content

Recipes

Jump to bottom
André Borchert edited this page Aug 16, 2026 · 4 revisions

Recipes

Task-first reference. Each recipe lists what to put in Output/, what to run, and what you get back.

Publish one track

In: one audio file (.flac/.wav/.mp3) + one image (.png/.jpg/.jpeg)

./converter -full

Out: the full set — 8K/4K/3K/2K PNGs, NFT squares, sized JPGs, RF64 WAV, ALAC M4A, 320 kbps MP3, archival companions, main MP4, portrait short, and a full-song vertical when the track exceeds 58 s.

If you already have finished artwork at exact dimensions, name it Horizontal_8K.png (7680×4320) and it is used as-is for the main video. Add Vertical_8K.png (4320×7680) to control the short's framing instead of letting converter derive it.

Publish an album as one continuous video

In: two or more tracks named so they sort naturally (1 - Sun.mp3, 2 - Rain.wav, 10 - Storm.flac) + the same image inputs as above

./converter -album

Each track is loudness-normalized to −12 LUFS, joined with 2-second gaps into one RF64 album.wav, then run through the full pipeline.

Want the tracks joined in a specific order, without normalization? List them in album.txt in the project root and use -wavtoalbum or -mp3toalbum. Lines starting with # are comments; missing tracks are skipped with a warning.

Make only a vertical short

In: one image + one audio-only file

./converter -short

You get two framings, so you can pick per upload:

  • _8K_Short.mp4 — the whole image fitted into the 4320×7680 frame, padded with black
  • _8K_Short_CenterCut.mp4 — the centre of the landscape 8K master scaled up to cover the frame and cropped, filling it edge to edge with no black

Both are capped at 58 s, and both gain a _FullSong companion when the audio runs longer — four shorts in total.

For NFT-style square artwork centered on black, use -nfttoshort instead. It prefers Vertical_8K.png, then an existing *_NFT8K.png, then derives one.

Already have a finished landscape MP4?

./converter -mp4toshort

Normalize a batch for consistent livestream playback

Measure first:

./converter -loudscan

You get average, lowest, highest, and top-3-loudest LUFS across everything in Output/. Then normalize:

./converter -loudness          # −12 LUFS (default)
./converter -loudness -14      # more dynamic target

Outputs are tagged with the target (_loudness_m12LUFS) so they never overwrite the source or collide with another target.

This applies one static gain — no EQ, no limiter, no compression. If a file has high peaks and a low average, converter caps the boost at the available peak headroom and warns that the result is peak-constrained rather than squashing the dynamics to hit the number.

Master a track to policy

./converter -master

Produces _mastered copies. Files already within policy are re-encoded losslessly; files outside it get two-pass loudnorm, falling back to one-pass. Targets come from MASTERING_TARGET_LUFS and friends — see Configuration.

Mastering only ever runs when you ask for it.

Adjust bass

./converter -bass              # +5 dB around 80 Hz
./converter -bass 60 7.5       # +7.5 dB at 60 Hz
./converter -bass 80 -5        # cut 0–80 Hz by 5 dB

Non-default settings get a settings-specific suffix (_bass_60Hz_7_5dB, _bass_80Hz_m5dB) so variants never overwrite each other.

Fade or trim an ending

./converter -fade 10           # fade the final 10 s, keep full length
./converter -fadecut 5 10      # drop the last 5 s, then fade the new final 10 s
./converter -fadeout 1:30 10   # fade from 1:30 over 10 s, then stop

Times accept seconds, MM:SS, or HH:MM:SS. Each writes a settings-specific suffix.

Pad with noise or silence

./converter -noise             # 30 s noise → 2 s silence → track → 2 s silence → 30 s noise
./converter -silence 45        # 45 s of silence before and after

Noise sections are normalized to −12 LUFS. MP4 inputs keep their video by holding the first and last frames.

Produce the image set on its own

./converter -run_pix           # every image deliverable, per source image
./converter -aipix             # just _8K.png and _4K.png
./converter -pngtonft          # NFT squares from a *_8K.png
./converter -pngtojpg2mb       # a 2 MB JPEG export from a *_8K.png

Rename files to their checksum

./converter --hash

Renames .wav, .flac, .mp3, and .mp4 to CRC-32-based filenames after verifying each one. A file that fails verification stops the run — add --continue-on-error to process what you can and get a summary of what failed.

Convert between formats

./converter -flactomp3
./converter -wavtom4a
./converter -m4atoflac

Every audio path stages through the internal 24-bit / 96 kHz WAV standard, so quality does not depend on which conversion you pick. ./converter -matrix prints the supported combinations.

Work somewhere other than Output/ 

./converter -full --output-dir ~/Projects/single
./converter -loudscan --src-dir ~/Music/masters

--src-dir sets where inputs are read, --out-dir where results are written, --output-dir sets both. --output-file names a single result and must land directly inside the output directory — subfolders are rejected.

Clone this wiki locally