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]** → Release

Optional step between mastering-engineer and release-director.

Workflow

1. Setup Verification

Check ffmpeg:

ffmpeg -filters | grep showwaves

Required 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 style
promotion.duration - Default clip duration
promotion.include_sampler - Whether to generate album sampler by default
promotion.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 seconds

If over 140s:

WARNING: Expected duration {duration}s exceeds Twitter limit (140s)

Recommendation: Reduce --clip-duration to {140 / tracks}s

4. 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

promo-director