Skip to main content
skill CX Codex

promo-director — Claude Code skill: generate social media videos from audio

promo-director generates 15-second vertical videos for Instagram, TikTok and Twitter from a mastered track. Combines album artwork, intelligent clip selection, and waveform visualization.

CC0-1.0 259 installs ★ 686 updated 2026-10-22

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add bitwize-music-studio/claude-ai-music-skills --skill promo-director -a claude-code
Open on GitHub

What promo-director does

This skill creates vertical video clips at 1080×1920 pixels (9:16 aspect ratio) right after your mastering is done. It scans the track for the most dynamic 15-second segment, overlays the album artwork, and animates a waveform visualization in your chosen style — ranging from a simple line graph to intricate circular patterns. Colors are extracted from the artwork itself, ensuring visual cohesion.

You'll need FFmpeg with showwaves, showfreqs, drawtext, and gblur filters, plus Python packages Pillow, librosa, and PyYAML. FFmpeg is not optional; without it, the skill will fail. Generate individual track videos or build an album sampler from all tracks with crossfades between them.

Nine visualization styles are available: pulse for electronic music, bars for pop and rock, line for acoustic, mirror for ambient, mountains for EDM, colorwave for indie, neon for synthwave, dual for experimental, and circular for abstract. The skill reads settings from ~/.bitwize-music/config.yaml and recommends a style based on your genre.

What it helps with

  • Generate a 15-second promo video with waveform animation from finished audio
  • Layer album artwork over sound visualization with color matching
  • Detect and extract the most energetic segment instead of using a fixed start point
  • Build an album preview from multiple tracks that stays under Twitter's 140-second limit
  • Apply different waveform styles depending on music genre

Example prompts for the agent

  • Generate promo videos for sample-album in pulse style
  • Create an album sampler with 12 seconds per track and crossfade
  • Make a promo for track 01-intro.wav with neon visualization

How to install promo-director

1Skills CLI (Vercel)

npx skills add bitwize-music-studio/claude-ai-music-skills --skill promo-director -a claude-code

2Manually: put the files in place

~/.claude/skills/promo-director/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/promo-director/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about promo-director

How do I install promo-director in Claude Code?

Run npx skills add bitwize-music-studio/claude-ai-music-skills --skill promo-director -a claude-code, then open ~/.claude/skills/promo-director/SKILL.md. Other platforms use different commands: Cursor uses -a cursor, GitHub Copilot uses gh skill install.

What do I need before using promo-director?

Install FFmpeg (macOS: brew install ffmpeg, Linux: apt install ffmpeg) and verify it includes the showwaves, showfreqs, drawtext, and gblur filters. Install Python packages: Pillow, librosa, and PyYAML. Have a mastered audio file and album artwork ready in your project folder.

What happens if FFmpeg is not installed?

The skill will not run and will return an error. FFmpeg is required, not optional. Install it via brew install ffmpeg on macOS or apt install ffmpeg on Linux.

Source text

SKILL.md · CC0-1.0
---
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:**
```bash
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 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](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

© bitwize-music-studio · CC0-1.0 · bitwize-music-studio/claude-ai-music-skills

Similar skills

All skills for Automation and no-code: n8n, Zapier, Make →

From the same set52

The whole set →

Project sponsors

Companies that keep this analytics open