Promo Director Skill
Generate professional promo videos for social media from mastered audio. Creates 15-second vertical videos (9:16, 1080x1920) optimized for Instagram Reels, Twitter, and TikTok.
Purpose
After mastering audio, generate promotional videos that combine:
- Album artwork
- Audio waveform visualization (9 styles available)
- Track title + artist name
- Automatic color scheme extracted from artwork
- Intelligent segment selection (finds the most energetic 15 seconds)
When to Use
- After mastering complete, before release
- User says "generate promo videos" or "create promo videos for [album]"
- When album has mastered audio + artwork ready
Position in Workflow
Generate → Master → **[Promo Videos]** → ReleaseOptional step between mastering-engineer and release-director.
Workflow
1. Setup Verification
Check ffmpeg:
ffmpeg -filters | grep showwavesRequired filters: showwaves, showfreqs, drawtext, gblur
If missing:
Error: ffmpeg not found or missing required filters
Install ffmpeg:
macOS: brew install ffmpeg
Linux: apt install ffmpeg
After installing, run this command again.Check Python dependencies:
Call get_python_command() to verify the venv exists. If venv_exists is false, show the warning and suggest /bitwize-music:setup.
2. Album Detection
Resolve audio path via MCP:
Call resolve_path("audio", album_slug) — returns the full audio directory path including artist folder.
Example result: ~/bitwize-music/audio/artists/bitwize/albums/electronic/sample-album/
Verify contents:
- ✓ Mastered audio files (.wav,.mp3,.flac,.m4a)
- ✓ Album artwork (album.png or album.jpg)
If artwork missing:
Error: No album artwork found in {audio_root}/artists/{artist}/albums/{genre}/{album}/
Expected: album.png or album.jpg
Options:
1. Use /bitwize-music:import-art to place artwork
2. Specify path manually: --artwork /path/to/art.png
Which option?3. User Preferences
Check config defaults first:
Read promotion section from ~/.bitwize-music/config.yaml for defaults:
promotion.default_style- Default visualization stylepromotion.duration- Default clip durationpromotion.include_sampler- Whether to generate album sampler by defaultpromotion.sampler_clip_duration- Seconds per track in sampler
If config section doesn't exist, use built-in defaults (pulse, 15s, sampler enabled, 12s clips).
Ask: What to generate?
Options (default from config or "both"):
- Individual track promos (15s each) + Album sampler (all tracks)
- Individual track promos only
- Album sampler only
Ask: Visualization style?
Default from promotion.default_style or pulse if not set.
| Style | Best For | Description |
|---|---|---|
pulse | Electronic, hip-hop | Oscilloscope/EKG style with heavy glow (default) |
bars | Pop, rock | Fast reactive spectrum bars |
line | Acoustic, folk | Classic clean waveform |
mirror | Ambient, chill | Mirrored waveform with symmetry |
mountains | EDM, bass-heavy | Dual-channel spectrum (looks like mountains) |
colorwave | Indie, alternative | Clean waveform with subtle glow |
neon | Synthwave, 80s | Sharp waveform with punchy neon glow |
dual | Experimental | Two separate waveforms (dominant + complementary colors) |
circular | Abstract, experimental | Vectorscope (wild circular patterns) |
Default recommendation:
- Electronic/Hip-Hop →
pulse - Rock/Pop →
bars - Folk/Acoustic →
line - Ambient/Chill →
mirror
Ask: Custom duration?
Default: 15 seconds (optimal for Instagram/Twitter)
Options:
- 15s (recommended, Instagram Reels sweet spot)
- 30s (longer preview)
- 60s (full clip, less common)
For sampler:
Default: 12 seconds per track
Calculate total:
Total duration = (tracks * clip_duration) - ((tracks - 1) * crossfade)
Twitter limit: 140 secondsIf over 140s:
WARNING: Expected duration {duration}s exceeds Twitter limit (140s)
Recommendation: Reduce --clip-duration to {140 / tracks}s4. Generation
Individual track promos:
generate_promo_videos(album_slug, style="pulse", duration=15)Single track only:
generate_promo_videos(album_slug, style="pulse", track_filename="01-track-name.wav")Album sampler:
generate_album_sampler(album_slug, clip_duration=12, crossfade=0.5)Handle errors:
Common issues:
- ffmpeg filter error → Check ffmpeg install includes filters
- Font not found → Install dejavu fonts or specify custom font
- Artwork extraction fails → Use default cyan color scheme
- librosa unavailable → Fall back to 20% into track for segment selection
- Audio file corrupt → Skip track, report, continue with others
5. Results Summary
Report generated files:
## Promo Videos Generated
**Location:** {audio_root}/artists/{artist}/albums/{genre}/{album}/
**Individual Track Promos:**
- {audio_root}/artists/{artist}/albums/{genre}/{album}/promo_videos/
- 10 videos generated
- Format: 1080x1920 (9:16), H.264, 15s each
- Style: pulse
- File size: ~10-12 MB per video
**Album Sampler:**
- {audio_root}/artists/{artist}/albums/{genre}/{album}/album_sampler.mp4
- Duration: 114.5s (under Twitter 140s limit ✓)
- Format: 1080x1920 (9:16), H.264
- File size: 45.2 MB
**Next Steps:**
1. Review videos: Open promo_videos/ folder
2. Test on phone: Transfer one video and verify quality
3. Populate social copy: Fill in promo/ templates (twitter.md, instagram.md, etc.)
4. [Optional] Upload to cloud: /bitwize-music:cloud-uploader {album}
5. Ready for release workflow: /bitwize-music:release-director {album}Technical Reference
See technical-reference.md for:
- Output specifications (resolution, format, bitrate)
- Visualization styles (pulse, bars, line, etc.)
- Platform compatibility (Instagram, Twitter, TikTok)
- Dependencies (required and optional)
- Troubleshooting common issues