dub-youtube-with-voiceai（使用 Voiceai 为 YouTube 配音）

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

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 <script.md or script.txt> \
  --voice <voice-alias-or-uuid> \
  --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:

replace-audio — Dub an existing video

node voiceai-vo.cjs replace-audio \
  --video ./my-video.mp4 \
  --audio ./out/my-video/master.wav \
  [--out ./out/my-video/dubbed.mp4] \
  [--sync shortest|pad|trim]

Requires ffmpeg. If not installed, generates helper shell/PowerShell scripts instead.

Video stream is copied without re-encoding (-c:v copy). Audio is encoded as AAC for YouTube compatibility.

Privacy: Video processing is entirely local. Only script text is sent to Voice.ai for TTS. Your video files never leave your machine.

voices — List available voices

node voiceai-vo.cjs voices [--limit 20] [--query "deep"] [--mock]

Available voices

Use short aliases or full UUIDs with --voice:

The voices command also returns any additional voices available on the API. Voice list is cached for 10 minutes.

Build outputs

After a build, the output directory contains everything you need to publish on YouTube:

out/<title-slug>/
  segments/           # Numbered WAV files (001-intro.wav, 002-section.wav, …)
  master.wav          # Stitched voiceover (requires ffmpeg)
  master.mp3          # MP3 for upload (requires ffmpeg)
  muxed.mp4           # Dubbed video (if --video --mux used)
  chapters.txt        # Paste into YouTube description
  captions.srt        # Upload as YouTube subtitles
  description.txt     # Ready-made YouTube description with chapters
  review.html         # Interactive review page with audio players
  manifest.json       # Build metadata: voice, template, segment list
  timeline.json       # Segment durations and start times

YouTube workflow

1. Run the build command
2. Upload muxed.mp4 (or your original video + master.mp3 as audio)
3. Paste chapters.txt content into your YouTube description
4. Upload captions.srt as subtitles in YouTube Studio
5. Done — professional narration, chapters, and captions in minutes

YouTube template

Use --template youtube to auto-inject a branded intro and outro:

Edit the files in templates/ to customize your channel's branding.

Caching

Segments are cached by a hash of: text content + voice ID + language.

• Unchanged segments are skipped on rebuild — fast iteration
• Modified segments are re-rendered automatically
• Use --force to re-render everything
• Cache manifest is stored in segments/.cache.json

Multilingual dubbing

Voice.ai supports 11 languages — dub your YouTube videos for global audiences:

en, es, fr, de, it, pt, pl, ru, nl, sv, ca

node voiceai-vo.cjs build \
  --input script-spanish.md \
  --voice ellie \
  --title "Mi Video" \
  --language es \
  --video ./my-video.mp4 \
  --mux

The pipeline auto-selects the multilingual TTS model for non-English languages.

Troubleshooting

See references/TROUBLESHOOTING.md for more.

References

• Agent Skills Specification
• Voice.ai
• references/VOICEAI_API.md — API endpoints, audio formats, models
• references/TROUBLESHOOTING.md — Common issues and fixes