Skip to content

Home

Jump to bottom
André Borchert edited this page Sep 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.

Install

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

-doctor checks the tools, the ffmpeg filters and encoders the pipeline depends on, directory permissions and free space. Installing covers the prebuilt binary, building it yourself, and opt-in dependency auto-install.

A complete run, start to finish

1. Put two files in Output/ — one song and one landscape image. The filenames do not matter; the image's orientation is what counts.

Output/
├── demo_song.flac      # the song:  .flac, .wav or .mp3
└── demo_art.png        # landscape artwork: .png (preferred), .jpg or .jpeg

2. Run the pipeline.

./converter -full

That is the whole workflow. On a 12-second test track it takes about a minute. It produced exactly these 27 files on the run this page was written from:
Your original 1_source.flac — renamed, never modified
Audio 1.wav · 1.m4a · 1.mp3
Archival 1_RF64.wav · 1_RF64.flac · 1_BW64.wav
Image 1_8K.png · 1_4K.png · 1_3K.png · 1_2K.png
NFT squares 1_NFT8K.png · 1_NFT3K.png · 1_NFT2K.png
Sized JPEGs 1_8K_1MB.jpg · 1_8K_2MB.jpg · 1_8K_20MB.jpg · 1_3K_1MB.jpg · 1_3K_5MB.jpg
Portrait stills 1_Short_8K.png · 1_Short_CenterCut_8K.png, each with _1MB.jpg and _2MB.jpg
Video 1_8K.mp4 — main, 7680×4320
Shorts 1_8K_Short.mp4 — image fitted with black padding
1_8K_Short_CenterCut.mp4 — frame filled, no padding

3. Collect and upload. The artwork is never renamed.

That demo song is only 12 seconds, so it has no _FullSong shorts. A song longer than min(SHORT_MP4_CLIP_SECONDS, 58) seconds also gets 1_8K_Short_FullSong.mp4 and 1_8K_Short_FullSong_CenterCut.mp4 — four shorts in total.

Your source is never written to. The full run renames the source audio to 1_source.flac and names every deliverable 1.*, so the release prefix is predictable and the untouched original always sits beside its outputs. Batch actions name each output after its own source file instead.

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, -master or -album (per-track normalization); the processing actions (-bass, -fade, -fadecut, -fadeout, -fadewav, -noise, -silence, -mp3clean) change the audio only in the way their name says.
  • 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 min(SHORT_MP4_CLIP_SECONDS, 58) seconds and both gain a _FullSong companion when the song runs longer.
  • Source images are picked by orientation, not filename. A landscape image becomes the 8K master; add a portrait image and it is used for the fitted shorts.
  • 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