Usage Guide
Complete CLI reference for Music Video Creator.
Basic Syntax
python main.py <input.wav> [options]
Quick Start Examples
# Simple rendering with default style
python main.py song.wav -o output.mp4
# GPU style (fast)
python main.py song.wav -o output.mp4 --style reactive_disk_gpu --pipe
# YouTube-optimized (1440p upscale for VP9 codec)
python main.py song.wav -o output.mp4 --youtube --style sphere_3d_gpu
# Short preview
python main.py song.wav -o preview.mp4 --style terrain_3d_gpu --max-duration 10 --pipe
Common Options
Output Control
| Option |
Description |
Example |
-o, --output |
Output file path |
-o video.mp4 |
--max-duration |
Limit duration (seconds) |
--max-duration 30 |
--start-time |
Start offset (seconds) |
--start-time 60 |
Visual Style
| Option |
Description |
Example |
--style |
Visual style name |
--style sphere_3d_gpu |
--preset |
Config preset |
--preset youtube |
Rendering Mode
| Option |
Description |
When to Use |
--pipe |
FFmpeg pipe (recommended) |
Most cases |
--parallel |
Multi-core rendering |
Long videos, Matplotlib styles |
--youtube |
1440p upscale + VP9 |
YouTube uploads |
Scene System
| Option |
Description |
--scenes |
Enable automatic scene detection |
--genre |
Genre preset (electronic, rock, pop, ambient, blues) |
--list-scenes |
Preview detected scenes without rendering |
--scene-timestamps |
Manual scene markers |
Beat Effects
| Option |
Description |
--beat-zoom |
Enable zoom on beats |
--no-beat-zoom |
Disable zoom |
--beat-flash |
Enable brightness flash |
--beat-shake |
Enable camera shake |
GIF Output
| Option |
Description |
--gif |
Output as GIF instead of MP4 |
--gif-preset |
Platform preset (discord, twitter, etc.) |
--gif-width |
Custom width in pixels |
--gif-fps |
Custom frame rate |
Lyrics & Subtitles
| Option |
Description |
--lyrics |
Auto-transcribe with Whisper |
--subtitle-file |
Use existing ASS/SRT file |
--whisper-model |
Whisper model (tiny, base, small, medium, large) |
HUD Overlays
| Option |
Description |
--title |
Title text to display |
--show-bpm |
Show tempo display |
--show-progress |
Show progress bar |
--title-duration |
Title visibility duration |
Post-Processing
| Option |
Description |
--post-fx |
Enable bloom, vignette, grain |
--preset cinematic |
Full post-processing preset |
Full Examples
YouTube Music Video
python main.py song.wav -o youtube_video.mp4 \
--youtube \
--style sphere_3d_gpu \
--scenes --genre electronic \
--beat-zoom --beat-flash \
--title "Song Title - Artist Name" \
--show-bpm
Discord GIF Preview
python main.py song.wav -o preview.gif \
--gif --gif-preset discord \
--style reactive_disk_gpu \
--max-duration 10 \
--start-time 30
TikTok/Reels Vertical
python main.py song.wav -o vertical.mp4 \
--vertical \
--auto-short 30 \
--style terrain_3d_gpu \
--beat-zoom
Scene Preview (No Render)
python main.py song.wav --list-scenes
# Output:
# Scene 1: intro (0:00 - 0:15)
# Scene 2: verse (0:15 - 0:45)
# Scene 3: build (0:45 - 1:00)
# Scene 4: drop (1:00 - 1:30)
# ...
With Custom Lyrics
python main.py song.wav -o output.mp4 \
--style sphere_3d_gpu \
--subtitle-file lyrics.ass \
--pipe
Real-Time Preview
python main.py song.wav --preview --style reactive_disk_gpu
# Controls: SPACE=play/pause, S=change style, Q=quit
Available Styles
GPU (Fast)
sphere_3d_gpu, sphere_3d_calm_gpu, terrain_3d_gpu, tunnel_3d_gpu, reactive_disk_gpu, spectrum_texture_gpu, frequency_bars_gpu, circular_gpu, particles_gpu, waveform_gpu
Matplotlib (Detailed)
waveform_spectrogram, spectrogram_only, waveform_only, frequency_bars, particles, geometric, circular_spectrum, beat_pulse, beat_rings
Available Presets
| Preset |
Description |
default |
Balanced settings |
fast_preview |
Quick low-res preview |
high_quality |
4K/60fps |
youtube |
1440p, VP9 optimized |
youtube_4k |
4K YouTube |
pipe |
Memory-efficient |
reactive_disk |
Optimized for disk style |
cinematic |
With post-processing |
full_effects |
All beat effects enabled |
Available Genres
electronic, rock, pop, ambient, blues
GIF Presets
discord, twitter, slack, reddit, preview, high_quality