Trace Wave Video Generator

Generate a YouTube-ready waveform video from any trace music audio file (WAV/MP3) with a single command. The script wraps an ffmpeg pipeline so you can drop in audio, optionally add cover art + titles, and render a clean MP4 in seconds.

Requirements

• macOS (tested) or any system with Python 3.8+ and ffmpeg 4+
• ffmpeg is already installed on this machine (brew install ffmpeg if you need to reinstall later)

Quick Start

python3 generate_trace_video.py path/to/your_audio.wav --title "Artist – Track"

By default this writes your_audio.mp4 next to the source audio with:

• 1920×1080 canvas
• Smooth aurora gradient background (customisable via --gradient-colors)
• Cyan line waveform
• AAC stereo audio at 192 kbps (YouTube friendly)

Useful options

• --output videos/final.mp4 — choose where the video lands
• --background-image cover.jpg — use album art; auto-crops to fill the frame
• --background-style solid|plasma|gradient — pick the generated background look
• --background-color "#111111" — solid color (used with --background-style solid)
• --gradient-colors "#0f172a,#1e293b,#4338ca,#f472b6" — customise the gradient palette (2–5 colours)
• --wave-color "#f97316" — change the waveform colour (hex)
• --mode line|point|bar — different waveform styles
• --title "Song Title" / --font "Arial" / --font-size 96 — caption text
• --encoder-preset faster — pick the libx264 speed/quality preset (ultrafast→slow)
• --filter-complex-threads 4 — optional manual threading for the filter graph
• --fast-render — force a solid background + ultrafast encoding for quick turnarounds
• --dry-run — print the ffmpeg command if you want to tweak it manually

Run python3 generate_trace_video.py -h to see every switch.

GUI mode

Prefer buttons? Launch the Tkinter front-end:

python3 waveform_gui.py

1. Browse for your audio file (the output path auto-fills).
2. Optionally adjust title, colours, or background art.
3. Tick Fast render if you just need a basic solid-background video quickly.
4. Click Render Video to kick things off.
5. Hit Cancel any time to stop ffmpeg without closing the app.

During rendering the window shows a live log, a progress bar, and an ETA estimate that refreshes roughly every 15 seconds so you know how long is left. Once it reaches 100%, the status switches to “Finalizing video…” while ffmpeg writes the MP4 header—expect just a few more seconds. If ffprobe is unavailable the app drops back to a smooth indeterminate bar.

Example workflows

• Cover art + waveform:

  python3 generate_trace_video.py stems/final_mix.wav \
    --background-image artwork/trace_cover.jpg \
    --title "Customer Name – Trace Mix" \
    --wave-color "#00d4ff" \
    --font "Avenir Next" \
    --font-size 84 \
    --output videos/customer_trace.mp4

• Bold, centered bar graph:

  python3 generate_trace_video.py stems/drone.wav \
    --mode bar \
    --background-style solid \
    --wave-color "#facc15" \
    --background-color "#0f172a"

The script overwrites existing files (-y flag). Remove sample.mp4 first if you want to re-render.

Optional macOS drag & drop setup

If you prefer to drop a WAV onto an icon and have the MP4 show up automatically:

1. Open Automator → Application.
2. Add an Run Shell Script action.
3. Set Pass input: as arguments, then paste:

   /usr/bin/python3 "PATH/TO/generate_trace_video.py" "$@" --title "Trace Mix"

   (Edit the title or add other flags as you like.)
4. Save the application (e.g. Trace Video.app) somewhere handy (Desktop / Dock).
5. Drag WAV files onto the app; each renders in the same folder as the source audio.

For batch processing multiple files at once, multiple WAVs can be dropped together and Automator will launch separate renders.

Troubleshooting

• “ffmpeg executable not found” — install or relink ffmpeg (brew install ffmpeg) or point to it via --ffmpeg-path /usr/local/bin/ffmpeg.
• Fontconfig cache warnings — harmless on macOS; they appear when fonts are auto-detected. To silence them, export FONTCONFIG_PATH or specify a --font "Font Name" that is installed.
• Album art looks cropped — the script intentionally covers the whole frame. Use a higher resolution source or tweak the scale=…:force_original_aspect_ratio=decrease logic in generate_trace_video.py.

Next ideas

• Pre-set flag bundles by creating aliases, e.g. add to .zprofile:

  alias tracevideo='python3 /Users/jeffpittman/Desktop/JAWBONE\ FLATS\ RECORDS/generate_trace_video.py --mode line --wave-color "#38bdf8"'