Narrate a deck into a synced video

Narrate a deck into a synced video

Turn a slidecast/HTML deck into an MP4 where each slide is shown for exactly the length of its narration. The build renders each slide headless (?render=1#N), generates speech per slide via ElevenLabs, and stitches them with ffmpeg.

Prerequisites — check these first

• ELEVENLABS_API_KEY must be exported in the environment (the user brings their own key). If unset, ask the user to run, in this session:

  ! export ELEVENLABS_API_KEY=sk_...
  

• ffmpeg + ffprobe on PATH (brew install ffmpeg / apt install ffmpeg).
• Google Chrome or Chromium (auto-detected; or export CHROME_BIN=/path/to/chrome).
• python3.

Steps

1. Locate the deck. You need the .html deck (from the create-presentation skill or the user's own). Note its absolute path.

2. Ensure narration.json exists next to the deck. If missing, write one — one entry per slide, in order:

   { "voice_id": "<id>", "model": "eleven_multilingual_v2",
     "segments": [ { "slide": 1, "text": "..." }, { "slide": 2, "text": "..." } ] }
   

   Draft natural, spoken narration (2–4 sentences/slide). Spell out numbers and acronyms ("twenty-four", "N-P-S") for clean pronunciation. Template: ${CLAUDE_PLUGIN_ROOT}/templates/narration.example.json.

3. Pick a voice (set voice_id in narration.json). To browse:

   python3 "${CLAUDE_PLUGIN_ROOT}/scripts/list_voices.py"                       # your voices
   python3 "${CLAUDE_PLUGIN_ROOT}/scripts/list_voices.py" --shared --gender female --language en
   

   Use the model that fits: eleven_multilingual_v2 (accents/non-English), eleven_turbo_v2_5 (fast/cheap), eleven_v3 (most expressive).

4. Build the video:

   bash "${CLAUDE_PLUGIN_ROOT}/scripts/build_video.sh" /abs/path/deck.html /abs/path/narration.json /abs/path/out.mp4
   

   The build is idempotent — it reuses any per-slide audio/renders already made (in a .slidecast/ work dir next to the deck). Re-run after editing one slide's text (delete that segment's mp3 first) or set SLIDECAST_FORCE=1 to regenerate all. Tune trailing silence with SLIDECAST_TAIL (seconds); output size with SLIDECAST_WIDTH/SLIDECAST_HEIGHT.

5. Report the final mp4 path and duration. Optionally extract a frame to verify (ffmpeg -ss <t> -i out.mp4 -frames:v 1 frame.png) and confirm audio is non-silent (ffmpeg -i out.mp4 -af volumedetect -f null -).

Cost & privacy

• TTS calls hit the user's ElevenLabs account and consume their character quota. Keep narration concise.
• The API key is read from the environment only; never hard-code or log it.