Skip to content

Home

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

Converter

A command-line tool that turns one song and one piece of artwork into a complete, verified upload set for macOS Apple Silicon.

You give it an audio file and an image. It gives you back the image deliverables (8K/4K PNG, NFT squares, sized JPG exports), the audio deliverables (RF64 WAV, ALAC M4A, 320 kbps MP3, archival companions), and the video deliverables (a main MP4 plus four portrait shorts — two framings, each with a full-length companion when the song runs past the 58-second cap).

Every output is verified before it is published. If a render comes out the wrong size, the wrong codec, silent, or drifted in loudness, converter fails rather than handing you a bad file.

First run

brew install ffmpeg imagemagick
./converter -doctor          # confirms the toolchain is usable

Put one audio file (.flac, .wav, or .mp3) and one image (.png, .jpg, or .jpeg) in the Output/ folder, then:

./converter -full

Output/ is both the input and the output folder. Scanning is not recursive — anything in a subfolder is ignored — and it is meant to be cleared out by hand between runs.

Where to go next

Page Use it when
Recipes You know what you want to produce and want the command for it
Commands You want the full list of actions and options
Full Run Contract You want to know exactly what -full and -album consume and produce
Configuration You want to change quality targets, render settings, or profiles
Troubleshooting Converter refused to do something and you want to know why
Installing You need to set up a machine or build the binary yourself

Things worth knowing up front

  • Loudness is preserved, not adjusted. Normal conversions never quietly remaster your audio. Loudness only changes when you explicitly ask with -loudness or -master.
  • Existing outputs are reused, not rebuilt. If a valid output already exists, converter verifies and skips it. Pass --overwrite to force a rebuild.
  • You get four shorts, not one. Two framings — _8K_Short.mp4 fits the image with black padding, _8K_Short_CenterCut.mp4 crops the centre of the 8K master to fill the frame. Both are capped at 58 seconds and both gain a _FullSong companion when the song runs longer.
  • Nothing is installed behind your back. Missing tools produce an error telling you what to brew install. See Installing if you want opt-in auto-install.

Clone this wiki locally