promo-director
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.
Install / Use
npx skills add bitwize-music-studio/claude-ai-music-skills --skill promo-directorInstalls into whichever agent you are using.
SKILL.md
Installable skill definition
Quality Score
Category
MarketingSupported Platforms
Our assessment of promo-director
promo-director scores 90/100 on our quality scale, 266th of 652 Marketing skills we index (top 41%).
Its SKILL.md is 6.6 KB long, well organised into 12 sections with 10 code examples: a thorough specification that gives an agent plenty to work with.
It has 512 GitHub stars, a meaningful sign that others use it.
Maintenance, license and trust
- The repository was last updated about 2 months ago, so promo-director is actively maintained.
- Our last check on 2026-10-30 found the source still online.
- It is released under the CC0-1.0 license, a permissive license that allows use, modification and commercial use with attribution.
- Its trust signals score 100/100, with no cautions. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.
Safety scan
No issues foundOur scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.
AI review by kimi-k2.7-code on 2026-10-05. Automated pattern scan on 2026-10-05. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.
promo-director compared with similar skills
All 4 of these similar skills score higher than promo-director; compare them before choosing.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| promo-director (this skill)by bitwize-music-studio | 90 | 512 | 56d ago | SKILL.md |
| Agent-Reachby Panniantong | 100 | 113.0k | 10d ago | CLAUDE.md |
| hyperframesby heygen-com | 100 | 86.4k | today | CLAUDE.md |
| rufloby ruvnet | 100 | 82.0k | today | CLAUDE.md |
| headroomby headroomlabs-ai | 100 | 80.1k | today | CLAUDE.md |
Frequently asked questions
- How do I install promo-director?
- Run
npx skills add bitwize-music-studio/claude-ai-music-skills --skill promo-director. The install tabs above show the steps for each supported agent. - Which AI agents does promo-director work with?
- It is written for Universal, as a SKILL.md file. Other agents that read the same format can often use it too.
- Is promo-director safe to use?
- Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It is CC0-1.0-licensed and scores 100/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
- Is promo-director still maintained?
- The repository was last updated about 2 months ago, so promo-director is actively maintained.
Skill content
View source on GitHubname: 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 stylepromotion.duration- Default clip durationpromotion.include_sampler- Whether to generate album sampler by defaultpromotion.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
Related Skills
Agent-Reach
113.0kGive your AI agent eyes to see the entire internet. Read & search Twitter, Reddit, YouTube, GitHub, Bilibili, XiaoHongShu — one CLI, zero API fees.
hyperframes
86.4kAI video you can actually edit. HyperFrames is a free, open-source AI video editor. Describe any video and get a real project you can change down to the frame.
ruflo
82.0k🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated
headroom
80.1kCompress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.
Languages
Trust signals
From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.
