promo-director

Q: How do I install promo-director?

Run npx skills add https://github.com/bitwize-music-studio/claude-ai-music-skills --skill promo-director in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/promo-director/ (personal) or .claude/skills/promo-director/ (project).

by bitwize-music-studioMedia & Creative

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.

Installs: 228
Last 24h: —
Trending rank: —
Security: Not audited

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/bitwize-music-studio/claude-ai-music-skills --skill promo-director

01
Install
Run the command in your project. The CLI asks which agents to install for.
02
Describe the task
Ask your agent for something this skill covers. It loads promo-director automatically when relevant.
03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.

SKILL.md

The instructions your agent reads when the skill is triggered.

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

FAQ

What does the promo-director skill do?

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.

How do I install promo-director?

Run npx skills add https://github.com/bitwize-music-studio/claude-ai-music-skills --skill promo-director in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/promo-director/ (personal) or .claude/skills/promo-director/ (project).

Which AI agents can use promo-director?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is promo-director safe to install?

No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.

Who maintains promo-director?

It is published by bitwize-music-studio in bitwize-music-studio/claude-ai-music-skills. It has 228 recorded installs.