Dub YouTube with Voice.ai

---

name: dub-youtube-with-voiceai description: "Dub YouTube videos with Voice.ai TTS. Turn scripts into publish-ready voiceovers with chapters, captions, and audio replacement for YouTube long-form and Shorts." version: 0.1.2 env: - VOICE_AI_API_KEY required_env: - VOICE_AI_API_KEY credentials: - VOICE_AI_API_KEY setup: "none — single file, runs directly with Node.js" runtime: "node>=20" optional_deps: "ffmpeg"

---

Dub YouTube with Voice.ai

> This skill follows the Agent Skills specification.

Turn any script into a YouTube-ready voiceover — complete with numbered segments, a stitched master, chapter timestamps, SRT captions, and a review page. Drop the voiceover onto an existing video to dub it in one command.

Built for YouTube creators who want studio-quality narration without the studio. Powered by Voice.ai.

---

When to use this skill

| Scenario | Why it fits | |---|---| | YouTube long-form | Full narration with chapter markers and captions | | YouTube Shorts | Quick hooks with punchy delivery | | Course content | Professional narration for educational videos | | Screen recordings | Dub a screencast with clean AI voiceover | | Quick iteration | Smart caching — edit one section, only that segment re-renders | | Batch production | Same voice, consistent quality across every video |

---

The one-command workflow

Have a script and a video? Dub it in one shot:

node voiceai-vo.cjs build \
  --input my-script.md \
  --voice oliver \
  --title "My YouTube Video" \
  --video ./my-recording.mp4 \
  --mux \
  --template youtube

This renders the voiceover, stitches the master audio, and drops it onto your video — all in one command. Output:

out/my-youtube-video/muxed.mp4 — your video dubbed with the AI voiceover

out/my-youtube-video/master.wav — the standalone audio

out/my-youtube-video/review.html — listen and review each segment

out/my-youtube-video/chapters.txt — paste directly into your YouTube description

out/my-youtube-video/captions.srt — upload to YouTube as subtitles

out/my-youtube-video/description.txt — ready-made YouTube description with chapters

Use --sync pad if the audio is shorter than the video, or --sync trim to cut it to match.

---

Requirements

Node.js 20+ — runtime (no npm install needed — the CLI is a single bundled file)

VOICE_AI_API_KEY — set as environment variable or in a .env file in the skill root. Get a key at voice.ai/dashboard.

ffmpeg (optional) — needed for master stitching, MP3 encoding, loudness normalization, and video dubbing. The pipeline still produces individual segments, the review page, chapters, and captions without it.

---

Configuration

Set VOICE_AI_API_KEY as an environment variable before running:

export VOICE_AI_API_KEY=your-key-here

The skill does not read .env files or access any files for credentials — only the environment variable.

Use --mock on any command to run the full pipeline without an API key (produces placeholder audio).

---

Commands

build — Generate a YouTube voiceover from a script

node voiceai-vo.cjs build \
  --input  \
  --voice  \
  --title "My YouTube Video" \
  [--template youtube] \
  [--video input.mp4 --mux --sync shortest] \
  [--force] [--mock]

What it does:

1. Reads the script and splits it into segments (by ## headings for .md, or by sentence boundaries for .txt) 2. Optionally prepends/appends YouTube intro/outro segments 3. Renders each segment via Voice.ai TTS 4. Stitches a master audio file (if ffmpeg is available) 5. Generates YouTube chapters, SRT captions, a review page, and a ready-made description 6. Optionally dubs your video with the voiceover

Full options:

| Option | Description | |---|---| | -i, --input | Script file (.txt or .md) — required | | -v, --voice | Voice alias or UUID — required | | -t, --title