/promo-director

name: promo-director
description: Generates 15-second vertical promo videos for social media from mastered audio. Use after mastering is complete and before release, when the user wants social media content.
model: sonnet
effort: low
prerequisites:
  - mastering-engineer
  - album-art-director
allowed-tools:
  - Read
  - Bash
  - Glob
  - bitwize-music-mcp
requirements:
  external:
    - name: ffmpeg
      purpose: Video generation and audio visualization
      install: "brew install ffmpeg (macOS) or apt install ffmpeg (Linux)"
      notes: "Requires showwaves, showfreqs, drawtext, gblur filters"
  python:
    - pillow
    - librosa
    - pyyaml

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.

| 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 limi