voiceai-creator-voiceover-pipeline

# Voice.ai Creator Voiceover Pipeline

> This skill follows the [Agent Skills specification](https://agentskills.io/specification).

Turn any script into a **publish-ready voiceover** — complete with numbered segments, a stitched master, YouTube chapters, SRT captions, and a beautiful review page. Optionally, replace the audio track on an existing video.

Built for creators who want studio-quality voiceovers without the studio. Powered by [Voice.ai](https://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 the `shortform` template |
| **Podcasts** | Consistent host voice, intro/outro templates |
| **Course content** | Professional narration for educational videos |
| **Quick iteration** | Smart caching — edit one section, only that segment re-renders |
| **Video audio replacement** | Drop AI voiceover onto screen recordings or B-roll |

---

## The one-command workflow

Have a script and a video? Turn them into a finished video with AI voiceover in one shot:

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

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

- `out/my-video/muxed.mp4` — your video with the new voiceover
- `out/my-video/master.wav` — the standalone audio
- `out/my-video/review.html` — listen and review each segment
- `out/my-video/chapters.txt` — YouTube-ready chapter timestamps
- `out/my-video/captions.srt` — SRT captions

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]...

# voiceai-creator-voiceover-pipeline

> Turn scripts into publishable voiceovers with Voice.ai — segments, chapters, captions, review page, and video muxing.

**📖 Skill documentation: [SKILL.md](SKILL.md)**

---

## Quick start

No install needed — just Node.js 20+ and the bundled CLI file.

```bash
# Set your API key
echo 'VOICE_AI_API_KEY=your-key-here' > .env

# Script + video → finished video with AI voiceover
node voiceai-vo.cjs build \
  --input my-script.md \
  --voice oliver \
  --title "My Video" \
  --video ./my-recording.mp4 \
  --mux

# Or just build the voiceover (no video)
node voiceai-vo.cjs build --input examples/youtube_script.md --voice ellie --title "My Video"

# List available voices
node voiceai-vo.cjs voices

# Test without an API key
node voiceai-vo.cjs build --input examples/youtube_script.md --voice ellie --title "My Video" --mock
```

Get your API key at [voice.ai/dashboard](https://voice.ai/dashboard).

## What it produces

```
out/<title>/
  segments/        # Numbered WAV files
  master.wav       # Stitched master (ffmpeg)
  master.mp3       # MP3 encode (ffmpeg)
  review.html      # Interactive review page
  chapters.txt     # YouTube chapters
  captions.srt     # SRT captions
  description.txt  # YouTube description
  manifest.json    # Build metadata
  timeline.json    # Segment timing
```

## Developer setup

To modify the source code:

```bash
git clone https://github.com/gizmoGremlin/VoiceAi-voiceover-creator.git
cd VoiceAi-voiceover-creator

# Install dev dependencies
npm install

# Build TypeScript
npm run build

# Re-bundle the CLI
npx esbuild src/cli.ts --bundle --platform=node --target=node20 --format=cjs --outfile=voiceai-vo.cjs

# Run tests
npm test
```

### FFmpeg (optional but recommended)

```bash
# macOS
brew install ffmpeg

# Ubuntu / Debian
sudo apt install ffmpeg

# Windows
choco install ffmpeg
```

## Learn more

- **[SKILL.md](SKILL.md)** — Full skill documentation: commands, voices, outputs, configuration
- **[ref...