Promo Director

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"): 1. Individual track promos (15s each) + Album sampler (all tracks) 2. Individual track promos only 3. Album sampler only

Ask: Visualization style?

Default from promotion.default_style or pulse if not set.

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 - Technical Reference

Technical specifications, dependencies, and troubleshooting for the promo-director skill.

---

Technical Details

Output Specifications

Format:

• Resolution: 1080x1920 (9:16 vertical)
• Codec: H.264 (libx264)
• Audio: AAC, 192 kbps
• Pixel format: yuv420p (universal compatibility)
• Frame rate: 30 fps

File sizes:

• Individual promo (15s): ~10-12 MB
• Album sampler (10 tracks, 115s): ~45-50 MB

Visualization Styles

Implementation:

All styles use ffmpeg filter chains:

• showwaves - Time-domain waveform
• showfreqs - Frequency spectrum
• avectorscope - Phase correlation (circular)
• gblur - Gaussian blur for glow effects
• blend - Layer blending for multi-layer glows

Color extraction:

Uses PIL to extract dominant color from album artwork: 1. Resize to 100x100 for speed 2. Filter out very dark/light pixels 3. Quantize color space (32 levels per channel) 4. Pick most saturated of top 5 colors 5. Generate complementary color (rotate 180° on hue wheel) 6. Use for waveform visualization

Segment selection:

With librosa (recommended): 1. Load audio (mono, 22050 Hz) 2. Compute RMS energy over time 3. Find 15s window with highest average energy 4. Usually captures chorus or drop

Without librosa (fallback):

• Start at 20% into track (skips intro, gets to meat)

Platform Compatibility

Instagram Reels:

• ✓ 1080x1920 (9:16)
• ✓ Max 90s (our 15s clips fit easily)
• ✓ H.264 codec

Twitter:

• ✓ 1080x1920 (9:16)
• ✓ Max 2:20 (140s)
• ✓ File size < 512 MB (our files ~10-50 MB)

TikTok:

• ✓ 1080x1920 (9:16)
• ✓ 15-60s (our 15s clips optimal)
• ✓ H.264 codec

Facebook:

• ✓ 1080x1920 (9:16)
• ✓ Various durations accepted
• ✓ H.264 codec

Dependencies

Required

ffmpeg:

• Version: 4.0+
• Filters: showwaves, showfreqs, drawtext, gblur
• Install: brew install ffmpeg (macOS), apt install ffmpeg (Linux)

Python 3.8+

Python packages:

• pillow - Image processing (color extraction)
• pyyaml - Config file reading

Optional

Python packages:

• librosa - Audio analysis (intelligent segment selection)
• numpy - Required by librosa

Graceful degradation:

• If PIL unavailable → Use default cyan color scheme
• If librosa unavailable → Use 20% into track as start point
• If custom font unavailable → Use system default

Invocation Examples

Basic (everything):

/bitwize-music:promo-director my-album

Tracks only:

/bitwize-music:promo-director my-album --tracks-only

Sampler only:

/bitwize-music:promo-director my-album --sampler-only

Custom style:

/bitwize-music:promo-director my-album --style neon

Custom duration:

/bitwize-music:promo-director my-album --duration 30

Integration with Other Skills

Handoff FROM

mastering-engineer:

After mastering complete:

## Mastering Complete

**Next Steps:**
1. [Optional] Generate promo videos: /bitwize-music:promo-director my-album
2. Begin release workflow: /bitwize-music:release-director my-album

Handoff TO

release-director:

After promo generation:

Promo videos generated successfully.

**Optional:** Upload to cloud storage: /bitwize-music:cloud-uploader my-album

Ready for release workflow: /bitwize-music:release-director my-album

Future Enhancements

Not in initial port (defer to future versions):

• Twitter campaign automation (tweet generation, scheduling)
• n8n workflow integration
• Automatic platform uploads (Instagram, Twitter APIs)
• Analytics tracking (view counts, engagement)
• Custom branding overlays (logos, watermarks)
• Platform-specific optimizations (1:1 for Twitter, 16:9 for YouTube)
• Batch processing multiple albums
• Template system for recurring visual styles

Troubleshooting

"ffmpeg not found"

• Install: brew install ffmpeg (macOS) or apt install ffmpeg (Linux)
• Verify: ffmpeg -version

"showwaves filter not found"

• ffmpeg compiled without filter support
• Reinstall with full filters: brew reinstall ffmpeg --with-all

"Font not found"

• Install dejavu fonts: apt install fonts-dejavu (Linux)
• macOS: System fonts should work automatically
• Override with: --font-path /path/to/font.ttf

"Color extraction failed"

• Activate venv: source ~/.bitwize-music/venv/bin/activate
• Install PIL in venv: pip install pillow
• Or accept default cyan color scheme (still works)

"librosa not found" (warning, not error)

• Activate venv: source ~/.bitwize-music/venv/bin/activate
• Install in venv: pip install librosa numpy
• Or continue with fallback (20% into track)
• Quality still good, just less intelligent segment selection

Videos generated but won't play

• Check codec: Should be H.264, not HEVC
• Check pixel format: Should be yuv420p
• Re-encode if needed: ffmpeg -i bad.mp4 -c:v libx264 -pix_fmt yuv420p fixed.mp4

File sizes too large

• Normal: 10-12 MB per 15s video
• If much larger: Check artwork resolution (should be ≤3000px)
• Reduce artwork size: convert album.png -resize 3000x3000\> album.png

"Expected duration exceeds Twitter limit"

• For samplers with many tracks
• Solution: Reduce --clip-duration to fit 140s limit
• Example: 15 tracks → 140/15 = ~9s per track

Model Recommendation

Sonnet 4.5 - This skill coordinates workflow and runs scripts. Creative output is in the videos themselves (generated by ffmpeg), not by the LLM.

Version History

• v0.12.0 - Initial implementation (ported from ../music/tools/promotion/)
• Individual track promos
• Album sampler generation
• 9 visualization styles
• Config integration
• Automatic color extraction
• Intelligent segment selection

Promo Video Visualization Styles

Guide to the 9 available visualization styles for promo videos. Each style uses ffmpeg filters to create unique audio-reactive visuals.

Style Gallery

1. Pulse (Default)

Best for: Electronic, hip-hop, bass-heavy tracks

Description:

• Oscilloscope/EKG style waveform
• Centered, highly reactive
• Heavy multi-layer glow effect (3 blur layers)
• Clean and professional
• Color extracted from album artwork

Technical:

showwaves → split 3 layers → gblur (sigma 8, 25) → blend with screen mode

Use when:

• Need professional, polished look
• Electronic or hip-hop genre
• Want strong visual impact without being distracting
• Album art has good color palette

---

2. Bars

Best for: Pop, rock, high-energy tracks

Description:

• Fast reactive spectrum bars
• Frequency-domain visualization
• Highly responsive to beat
• Classic club/visualizer aesthetic
• White color (doesn't use artwork colors)

Technical:

showfreqs → line mode → sqrt scale → log frequency scale

Use when:

• Need maximum beat reactivity
• Pop or rock genre
• Want classic "music visualizer" look
• Artwork colors don't fit video aesthetic

---

3. Line

Best for: Acoustic, folk, singer-songwriter

Description:

• Classic clean waveform
• Time-domain, centered
• Minimal processing
• Highly reactive, shows every nuance
• White color (clean and simple)

Technical:

showwaves → cline mode → sqrt scale → centered

Use when:

• Acoustic or folk genre
• Want to show vocal/instrument detail
• Minimal, clean aesthetic preferred
• Let the music speak for itself

---

4. Mirror

Best for: Ambient, chill, downtempo

Description:

• Mirrored waveform (top and bottom symmetrical)
• Soft glow effect
• Meditative, balanced aesthetic
• Creates visual symmetry
• Uses complementary color from artwork

Technical:

showwaves → split → flip bottom → vstack → gblur → blend

Use when:

• Ambient or chill genre
• Want symmetrical, balanced look
• Softer, less aggressive aesthetic
• Calming, meditative vibe

---

5. Mountains

Best for: EDM, bass-heavy, cinematic

Description:

• Dual-channel frequency spectrum
• Looks like mountain ranges
• Mirrored top/bottom
• Soft glow, ethereal
• Uses complementary color from artwork

Technical:

showfreqs → line mode → split → flip → vstack → gblur → blend

Use when:

• EDM or cinematic genre
• Want dramatic, epic visual
• Frequency content is interesting (wide spectrum)
• Prefer smoother motion over sharp reactivity

---

6. Colorwave

Best for: Indie, alternative, dream pop

Description:

• Clean waveform with subtle glow
• Single complementary color
• Softer than pulse, more refined than line
• Balanced opacity blend
• Modern, polished look

Technical:

showwaves → split → gblur (sigma 4) → blend with screen mode at 50% opacity

Use when:

• Indie or alternative genre
• Want refined, polished aesthetic
• Not too aggressive, not too minimal
• Artwork has good complementary color

---

7. Neon

Best for: Synthwave, 80s revival, electronic

Description:

• Sharp waveform with punchy glow
• Bright neon aesthetic
• Tight blur (sigma 2), high intensity
• Addition blend mode (brighter than screen)
• Retro-futuristic vibe

Technical:

showwaves → split → gblur (sigma 2) → blend with addition mode at 60% opacity

Use when:

• Synthwave or 80s genre
• Want bright, punchy, retro aesthetic
• High energy, attention-grabbing
• Artwork has vibrant colors

---

8. Dual

Best for: Experimental, avant-garde, electronic

Description:

• Two separate waveforms (top and bottom)
• Top: complementary color (bright)
• Bottom: dominant color (from artwork)
• Bottom waveform flipped
• Contrasting colors create visual tension

Technical:

Two showwaves → different colors → flip bottom → vstack

Use when:

• Experimental or avant-garde genre
• Want visual contrast and tension
• Artwork has strong color palette
• Prefer unique, distinctive look

---

9. Circular

Best for: Abstract, experimental, glitch

Description:

• Audio vectorscope (Lissajous patterns)
• Creates wild circular/spiral patterns
• Phase correlation visualization
• Unpredictable, mesmerizing
• White on black (doesn't use artwork colors)

Technical:

avectorscope → lissajous_xy mode → sqrt scale → padded to center

Use when:

• Abstract or experimental genre
• Want completely unique aesthetic
• Stereo field is interesting (wide mix)
• Prefer abstract over literal waveform
• Glitch, IDM, or experimental electronic

---

Genre Recommendations

Color Theory

How colors are extracted:

1. Dominant color: Most saturated color from album artwork (filtered to avoid black/white) 2. Complementary color: Opposite on color wheel (180° hue rotation), boosted saturation/lightness 3. Analogous colors: ±30° on color wheel (used in "dual" style)

Which styles use colors:

Artwork colors:

• pulse (complementary)
• mirror (complementary)
• mountains (complementary)
• colorwave (complementary)
• neon (complementary)
• dual (dominant + complementary)

Fixed colors (white):

• bars
• line
• circular

Why use white:

• Universal compatibility (works with any artwork)
• Maximum contrast on dark background
• Classic "visualizer" aesthetic
• Less processing (faster rendering)

Performance Considerations

Rendering speed (slowest to fastest):

1. circular - Most complex (vectorscope calculations) 2. dual - Two waveform passes 3. pulse - Three blur layers + blending 4. mountains - Frequency analysis + multiple processing steps 5. mirror - Split + flip + blur 6. neon - Two layers + blur 7. colorwave - Two layers + blur 8. bars - Frequency analysis only 9. line - Simplest (single waveform pass)

Typical rendering times (15s video):

• Fast (line, bars): ~20-30 seconds
• Medium (colorwave, neon, mirror): ~30-45 seconds
• Slow (pulse, mountains, dual): ~45-60 seconds
• Very slow (circular): ~60-90 seconds

Batch processing (10 tracks):

• Fast styles: ~5-7 minutes total
• Medium styles: ~7-10 minutes total
• Slow styles: ~10-15 minutes total

Customization

To add custom style:

Edit tools/promotion/generate_promo_video.py:

elif style == "custom":
    viz_filter = f"""[0:a]showwaves=s={WIDTH}x{viz_height}:mode=cline:scale=sqrt:colors={color2}:rate={FPS}[wave]"""

Parameters to adjust:

• mode: cline (centered line), line (from bottom), p2p (peak-to-peak)
• scale: sqrt (balanced), lin (linear), log (logarithmic), cbrt (cubic root)
• colors: Hex color (0xRRGGBB)
• rate: Frame rate (30 recommended)
• gblur sigma: Blur amount (2-25, higher = more blur)
• blend mode: screen (additive light), addition (brighter), normal

Platform-Specific Considerations

Instagram Reels:

• Prefer pulse, bars, or neon (high energy)
• Avoid circular (too abstract for Instagram audience)
• Short attention span: reactivity matters

Twitter:

• Prefer pulse or colorwave (professional)
• Avoid overly complex styles (small preview thumbnails)
• Clean, readable aesthetic works best

TikTok:

• Prefer bars, pulse, or neon (gen-z aesthetic)
• High energy, attention-grabbing
• Avoid minimal styles (line, mirror)

Artist website:

• Any style works
• Consider matching to album aesthetic
• Circular or dual for art/experimental projects

Examples by Use Case

"I want maximum attention on Instagram" → Use neon or pulse - High energy, bright, eye-catching

"I want professional, polished promo for Twitter" → Use pulse or colorwave - Clean, refined, modern

"I want to show off my artwork colors" → Use pulse, dual, or colorwave - Extracts colors from art

"I want classic visualizer aesthetic" → Use bars or line - Timeless, recognizable

"I want something unique and different" → Use circular or dual - Stands out, memorable

"I want fast rendering for quick turnaround" → Use line or bars - Fastest render times

"I want ambient, chill vibe" → Use mirror or mountains - Soft, meditative

Testing Recommendations

Before batch-generating all tracks:

1. Generate one test video with your preferred style 2. View on phone (most common viewing device) 3. Check:

• Waveform reactivity (too much/too little?)
• Color scheme (matches album aesthetic?)
• Readability (title/artist clear?)
• Artwork visibility (not obscured by waveform?)

4. Adjust if needed, then batch-generate all tracks

Quick test via MCP:

generate_promo_videos(album_slug, style="pulse", track_filename="01-track-name.wav")

Advanced Techniques

Combine multiple videos:

For variety, use different styles per track:

• Intros/outros: line or mirror (minimal)
• Choruses: pulse or neon (high energy)
• Bridges: colorwave or mountains (transitional)

Style progression:

For album sampler, consider style transitions:

• Start calm: mirror → colorwave
• Build energy: pulse → bars → neon
• Peak intensity: dual or circular
• Wind down: colorwave → line

Match tempo:

Some styles work better with tempo:

• Fast (140+ BPM): bars, neon, pulse
• Medium (90-140 BPM): pulse, colorwave, line
• Slow (<90 BPM): mirror, mountains, line