devstack 0.1.0

package/vendor/skills/skills/promo-video/voiceover.md

@@ -0,0 +1,358 @@
+# Voiceover Generation Guide
+
+Generate professional AI voiceover using ElevenLabs, precisely timed and content-matched to video scenes.
+
+## Requirements
+
+- `ELEVEN_LABS_API_KEY` environment variable
+- `ffmpeg` installed for audio processing
+- `whisper` CLI or Python package for timing verification
+- Python 3.x for the generation script
+
+## Critical Workflow: Scene-Voiceover Alignment
+
+**The #1 problem with promo video voiceovers is misalignment between what's being said and what's on screen.** Follow this precise workflow:
+
+### Step 1: Extract Scene Timings from Remotion
+
+First, read the main composition file to extract exact scene timings:
+
+```javascript
+// Example from AIVoicePromo.jsx - extract these values:
+const OPENING_DURATION = 150; // 5 seconds (frames / 30fps)
+const PAIN_POINT_DURATION = 120; // 4 seconds each
+const SOLUTION_INTRO_DURATION = 120;
+const FEATURE_DURATION = 150; // 5 seconds each
+const RESULTS_DURATION = 180; // 6 seconds
+const CLOSING_DURATION = 240; // 8 seconds
+```
+
+Calculate cumulative timestamps:
+
+```
+Scene              | Start | End  | Duration
+-------------------|-------|------|----------
+Opening            | 0s    | 5s   | 5s
+Pain Point 1       | 5s    | 9s   | 4s
+Pain Point 2       | 9s    | 13s  | 4s
+Pain Point 3       | 13s   | 17s  | 4s
+Solution Intro     | 17s   | 21s  | 4s
+Feature 1          | 21s   | 26s  | 5s
+Feature 2          | 26s   | 31s  | 5s
+Feature 3          | 31s   | 36s  | 5s
+Feature 4          | 36s   | 41s  | 5s
+Feature 5          | 41s   | 46s  | 5s
+Results            | 46s   | 52s  | 6s
+Closing            | 52s   | 60s  | 8s
+```
+
+### Step 2: Extract Scene Content for Script Matching
+
+Read each scene component to understand what's visually displayed:
+
+```bash
+# For each scene, extract:
+# - Title text
+# - Subtitle text
+# - Stats displayed
+# - Key visual elements
+```
+
+**The voiceover MUST reference what's on screen.** Example mapping:
+
+| Scene                            | Visual Content                                               | Voiceover Should Say                                                                              |
+| -------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------- |
+| Opening                          | "Every Missed Call Costs You Money", stats: $650K, 38%, 4hrs | "Every missed call costs you money. With six hundred and fifty thousand dollars lost annually..." |
+| Pain Point 1                     | "Missed Calls = Lost Revenue", stat: 500+                    | "Your dealership handles over five hundred service calls every month..."                          |
+| Feature 1: Smart Voicemail Queue | Shows queue UI mockup                                        | "The Smart Voicemail Queue transcribes every message instantly..."                                |
+
+### Step 3: Write Time-Aligned Script
+
+Structure your script with EXACT scene boundaries:
+
+```
+[0-5s - Opening - Visual: "Every Missed Call Costs You Money"]
+Every missed call costs you money. With six hundred and fifty thousand dollars lost annually...
+
+[5-9s - Pain Point 1 - Visual: "Missed Calls = Lost Revenue", 500+ stat]
+Your dealership handles over five hundred service calls every month...
+
+[17-21s - Solution Intro - Visual: ShopLoader logo reveal]
+Introducing ShopLoader AI Voice. Turn voicemails into appointments in minutes.
+```
+
+**Content Rules:**
+
+- Reference the title/stat shown on screen
+- Don't describe something not visible
+- Time the "reveal" moment (e.g., "Introducing ShopLoader" exactly when logo appears)
+
+### Step 4: Generate Voiceover Sections
+
+Use the generation script with precise start times that leave ~1s buffer before scene transitions:
+
+```python
+sections = [
+    (1, "Every missed call costs you money."),      # Scene starts at 0s, speak at 1s
+    (6, "Your dealership handles..."),              # Scene starts at 5s, speak at 6s
+    (18, "Introducing ShopLoader AI Voice."),       # Scene starts at 17s, speak at 18s
+    # ...
+]
+```
+
+### Step 5: Verify Timing with Whisper Transcription
+
+**CRITICAL STEP - Do not skip!**
+
+After generating the voiceover, transcribe it to verify actual timing:
+
+```bash
+# Using Whisper CLI
+whisper voiceover.mp3 --model tiny --output_format srt
+
+# Or using Python
+python3 -c "
+import whisper
+model = whisper.load_model('tiny')
+result = model.transcribe('voiceover.mp3')
+for s in result['segments']:
+    print(f\"{s['start']:.1f}s - {s['end']:.1f}s: {s['text']}\")
+"
+```
+
+### Step 6: Compare and Validate
+
+Compare Whisper output against scene timings:
+
+```
+Expected vs Actual Timing Analysis:
+-----------------------------------
+Scene: Solution Intro (17-21s)
+  Expected: "Introducing ShopLoader" starts at 18s
+  Actual:   "Introducing ShopLoader" starts at 17.2s ✓ (within scene)
+
+Scene: Feature 1 (21-26s)
+  Expected: "Smart Voicemail Queue" at 22s
+  Actual:   "Smart Voicemail Queue" at 20.8s ✗ (OVERLAPS with previous scene!)
+```
+
+**If overlap detected:** Increase delay for that section and regenerate.
+
+### Step 7: FIX ALL OVERLAPS (Mandatory)
+
+**If ANY overlap is detected, you MUST fix it before proceeding. Do not ask the user.**
+
+Overlap fixes (in order of preference):
+
+1. **Shorten the text** - Make it punchier. Cut filler words. "The Smart Voicemail Queue transcribes every message instantly" → "Voicemails transcribed instantly"
+2. **Add a beat** - Insert "..." in the text to create a natural pause
+3. **Increase gap** - Push the next section's start time 1-2s later
+
+Other timing fixes:
+
+- **Speech ends after scene**: Shorten the text, remove unnecessary words
+- **Too much silence**: Decrease start time or add more content
+- **Wrong content timing**: Adjust start time to match visual reveal
+
+**After ANY fix: Regenerate and verify with Whisper again. Repeat until ZERO overlaps.**
+
+---
+
+## Script Writing Guidelines
+
+### Content-Scene Matching Rules
+
+1. **Reference what's visible**: If the screen shows "500+ calls", say "five hundred"
+2. **Match reveal timing**: Product name first spoken when logo appears
+3. **Describe features when shown**: Talk about "SMS Quick Response" during SMS mockup scene
+4. **Complete the thought with benefit**: Don't just name features, explain why they matter
+
+### DO:
+
+- Write complete thoughts, not fragments
+- Allow 1s buffer at scene start before speaking
+- Allow 0.5s buffer before scene end
+- Match spoken stats to visual stats
+- Use conversational, natural language
+
+### DON'T:
+
+- Don't reference visuals not yet shown
+- Don't continue speaking into the next scene
+- Don't make it too dense (audio needs breathing room)
+- Don't skip the emotional hook in the opening
+
+---
+
+## Script Template (60 seconds)
+
+```
+[0-5s - Opening - Visual: Hook headline + 3 stats]
+[Start speaking at 1s]
+Every missed call costs you money. With [stat from screen] and [stat from screen], your [consequence].
+
+[5-9s - Pain Point 1 - Visual: Title + stat]
+[Start speaking at 6s]
+[Reference the title shown]. [Expand with the stat displayed].
+
+[9-13s - Pain Point 2 - Visual: Title + stat]
+[Start speaking at 10s]
+[Reference the title shown]. [Emotional consequence].
+
+[13-17s - Pain Point 3 - Visual: Title + stat]
+[Start speaking at 14s]
+[Reference the title shown]. [What happens as a result].
+
+[17-21s - Solution Intro - Visual: Product logo reveal]
+[Start speaking at 18s - TIME THIS TO LOGO APPEARANCE]
+Introducing [Product Name]. [One-line value prop].
+
+[21-26s - Feature 1 - Visual: Feature title + UI mockup]
+[Start speaking at 22s]
+[Feature name from screen] [what it does], so [benefit to user].
+
+[26-31s - Feature 2]
+[Start speaking at 27s]
+[Feature name from screen] [what it does], so [benefit to user].
+
+[31-36s - Feature 3]
+[Start speaking at 32s]
+[Feature name from screen] [what it does], so [benefit to user].
+
+[36-41s - Feature 4]
+[Start speaking at 37s]
+[Feature name from screen] [what it does], so [benefit to user].
+
+[41-46s - Feature 5]
+[Start speaking at 42s]
+[Feature name from screen] [what it does], so [benefit to user].
+
+[46-52s - Results - Visual: Outcome stats]
+[Start speaking at 47s]
+[Stat from screen]. [Stat from screen]. [Emotional benefit].
+
+[52-60s - Closing - Visual: CTA + branding]
+[Start speaking at 53s]
+[Product Name]. [Tagline from screen]. [CTA].
+```
+
+---
+
+## ElevenLabs Voice Settings
+
+### Recommended Voice: Matilda
+
+- **Voice ID**: `XrExE9yKIg1WjnnlVkGX`
+- **Characteristics**: American, Professional, Knowledgeable, Clear
+
+### Voice Settings for Professional Delivery:
+
+```json
+{
+  "model_id": "eleven_multilingual_v2",
+  "voice_settings": {
+    "stability": 0.65,
+    "similarity_boost": 0.85,
+    "style": 0.2,
+    "use_speaker_boost": true
+  }
+}
+```
+
+**Adjustments:**
+
+- If too breathy: Increase `stability` to 0.70-0.75
+- If too robotic: Decrease `stability` to 0.55-0.60
+- If speech too fast: Decrease `style`, or add "..." pauses in text
+
+---
+
+## Generation & Verification Workflow
+
+### Full Pipeline:
+
+```bash
+# 1. Generate voiceover sections
+python ${SKILL_DIR}/scripts/generate_voiceover.py
+
+# 2. Transcribe to verify timing
+whisper voiceover.mp3 --model tiny --output_format srt
+
+# 3. Review SRT file against scene timings
+cat voiceover.srt
+
+# 4. If timing issues found, adjust sections[] start times and regenerate
+# 5. Normalize audio
+ffmpeg -y -i voiceover.mp3 -af "loudnorm=I=-16:TP=-1.5:LRA=11" voiceover-normalized.mp3
+
+# 6. Add background music
+ffmpeg -y -i voiceover-normalized.mp3 -i music.mp3 \
+  -filter_complex "[1:a]volume=0.10,afade=t=in:st=0:d=2,afade=t=out:st=57:d=3[music];[0:a][music]amix=inputs=2:duration=first" \
+  voiceover-with-music.mp3
+
+# 7. Combine with video
+ffmpeg -y -i video.mp4 -i voiceover-with-music.mp3 -c:v copy -map 0:v:0 -map 1:a:0 final.mp4
+
+# 8. Watch final video to confirm alignment
+```
+
+---
+
+## Troubleshooting
+
+**CRITICAL: Never accept overlaps. Fix them immediately and regenerate.**
+
+| Issue                                  | Cause                   | Solution                                                            |
+| -------------------------------------- | ----------------------- | ------------------------------------------------------------------- |
+| **Voiceover overlaps itself**          | Sections too close      | **FIX NOW**: Shorten text OR increase gap, regenerate, verify again |
+| **Even 0.4s overlap**                  | Text too long for scene | **FIX NOW**: Make text punchier, cut words, regenerate              |
+| Speech doesn't match screen            | Script not aligned      | Re-read scene components, match text to visuals                     |
+| "Introducing X" before logo            | Start time too early    | Delay to 1s after scene start                                       |
+| Feature description during wrong scene | Timing drift            | Use Whisper to find actual timestamps, adjust                       |
+| Voice too fast                         | Too much text           | Shorten text or add "..." for pauses                                |
+| Awkward cuts between scenes            | No buffer               | Leave 0.5-1s silence before scene transitions                       |
+
+**The loop: Generate → Whisper verify → Fix overlaps → Regenerate → Verify again → Repeat until clean**
+
+---
+
+## Background Music
+
+### Auto-Download Royalty-Free Tracks (Verified Working)
+
+```bash
+# Bensound - "Inspire" (corporate/uplifting) - RECOMMENDED
+curl -sL "https://www.bensound.com/bensound-music/bensound-inspire.mp3" -o background-music.mp3
+
+# Bensound - "Creative Minds" (light/positive)
+curl -sL "https://www.bensound.com/bensound-music/bensound-creativeminds.mp3" -o background-music.mp3
+
+# Pixabay - Corporate background (256kbps, high quality)
+curl -sL "https://cdn.pixabay.com/download/audio/2022/03/15/audio_8cb749d484.mp3" -o background-music.mp3
+
+# Verify download worked
+ls -lah background-music.mp3 && file background-music.mp3
+```
+
+### Mixing Settings
+
+- **Volume**: 10% of voice level (`volume=0.10`)
+- **Fade in**: 2 seconds at start (`afade=t=in:st=0:d=2`)
+- **Fade out**: 3 seconds before video end (`afade=t=out:st=57:d=3` for 60s video)
+- **Style**: Subtle corporate/tech underscore, no lyrics
+
+### Mix Command
+
+```bash
+ffmpeg -y -i voiceover-normalized.mp3 -i background-music.mp3 \
+  -filter_complex "[1:a]volume=0.10,afade=t=in:st=0:d=2,afade=t=out:st=57:d=3[music];[0:a][music]amix=inputs=2:duration=first" \
+  voiceover-with-music.mp3
+```
+
+### Other Sources (if auto-download fails)
+
+- Bensound.com - Free with attribution
+- Mixkit.co - Free, no attribution needed
+- Pixabay.com/music - Free
+- Epidemic Sound (subscription)
+- Artlist (subscription)