Skip to content

Recipes

Jump to bottom
André Borchert edited this page Sep 14, 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, four portrait shorts (two framings, each with a full-song companion when the track exceeds 58 s), and both short framings saved as stills (*_Short_8K.png, *_Short_CenterCut_8K.png, each with _1MB.jpg/_2MB.jpg).

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. A listed track that cannot be used is an error — the build fails instead of publishing a shorter album; with --continue-on-error the usable tracks are still joined and the failures are reported in the summary.

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 min(SHORT_MP4_CLIP_SECONDS, 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