142 lines
3.4 KiB
Markdown
142 lines
3.4 KiB
Markdown
# NPC Voice Skill
|
|
|
|
Text-to-Speech for bringing NPCs and narration to life using ElevenLabs AI voices.
|
|
|
|
## Quick Start
|
|
|
|
```bash
|
|
# Test it out
|
|
node .claude/skills/npc-voice/speak-npc.js \
|
|
--text "Hello, adventurer!" \
|
|
--voice merchant \
|
|
--npc "Shopkeeper"
|
|
```
|
|
|
|
## Installation
|
|
|
|
1. **Get API Key**: Sign up at [ElevenLabs](https://elevenlabs.io) and get your API key from [settings](https://elevenlabs.io/app/settings/api-keys)
|
|
|
|
2. **Configure**: Copy `.env.example` to `.env` and add your API key:
|
|
```bash
|
|
cp .env.example .env
|
|
# Edit .env and add: ELEVENLABS_API_KEY=your_key_here
|
|
```
|
|
|
|
3. **Install Dependencies**:
|
|
```bash
|
|
cd .claude/skills/npc-voice && npm install
|
|
```
|
|
|
|
## Usage
|
|
|
|
### Basic Command
|
|
|
|
```bash
|
|
node .claude/skills/npc-voice/speak-npc.js \
|
|
--text "Your dialogue here" \
|
|
--voice <preset> \
|
|
--npc "Character Name"
|
|
```
|
|
|
|
### Voice Presets
|
|
|
|
Run `--list` to see all available voices:
|
|
|
|
```bash
|
|
node .claude/skills/npc-voice/speak-npc.js --list
|
|
```
|
|
|
|
**Popular Presets:**
|
|
- `narrator` - Storytelling, scene descriptions
|
|
- `merchant` - Friendly shopkeeper
|
|
- `villain` - Menacing antagonist
|
|
- `wizard` - Wise spellcaster
|
|
- `warrior` - Gruff fighter
|
|
- `goblin` - Sneaky creature
|
|
- `dwarf` - Deep, gruff
|
|
- `elf` - Elegant
|
|
|
|
### Examples
|
|
|
|
**D&D Session:**
|
|
```bash
|
|
# DM narration
|
|
node .claude/skills/npc-voice/speak-npc.js \
|
|
--text "You enter a dimly lit tavern. The smell of ale and pipe smoke fills the air." \
|
|
--voice narrator
|
|
|
|
# NPC dialogue
|
|
node .claude/skills/npc-voice/speak-npc.js \
|
|
--text "Welcome to my shop! Looking for potions?" \
|
|
--voice merchant \
|
|
--npc "Albus the Alchemist"
|
|
|
|
# Villain monologue
|
|
node .claude/skills/npc-voice/speak-npc.js \
|
|
--text "You fools! You cannot stop me now!" \
|
|
--voice villain \
|
|
--npc "Dark Wizard Malakar"
|
|
```
|
|
|
|
## How It Works
|
|
|
|
1. **Text Input**: You provide dialogue/narration text
|
|
2. **Voice Selection**: Choose from preset character voices
|
|
3. **AI Generation**: ElevenLabs generates natural-sounding speech
|
|
4. **Auto-Play**: Audio plays automatically through your system
|
|
5. **Cleanup**: Temporary files are removed
|
|
|
|
## Technical Details
|
|
|
|
- **Model**: ElevenLabs eleven_flash_v2_5
|
|
- **Audio Format**: MP3, 44.1kHz, 128kbps
|
|
- **Audio Player**:
|
|
- macOS: `afplay`
|
|
- Linux: `mpg123`
|
|
- **Dependencies**:
|
|
- `@elevenlabs/elevenlabs-js`
|
|
- `dotenv`
|
|
|
|
## Use Cases
|
|
|
|
- **D&D/TTRPG**: Voice NPCs and narrate scenes
|
|
- **Storytelling**: Read passages from books with character voices
|
|
- **Content Creation**: Generate voiceovers for videos/podcasts
|
|
- **Accessibility**: Convert text to speech for easier consumption
|
|
- **Game Development**: Prototype character voices
|
|
|
|
## Files
|
|
|
|
- `speak-npc.js` - Main TTS script
|
|
- `skill.md` - Skill documentation for Claude
|
|
- `package.json` - Node.js dependencies
|
|
- `.env.example` - Environment variable template
|
|
- `.env` - Your API key (git-ignored)
|
|
|
|
## Troubleshooting
|
|
|
|
**"API key not configured"**
|
|
- Make sure `.env` file exists with valid `ELEVENLABS_API_KEY`
|
|
|
|
**"Audio player exited with code 1"**
|
|
- macOS: `afplay` should work by default
|
|
- Linux: Install `mpg123` with `sudo apt install mpg123`
|
|
|
|
**"401 Unauthorized"**
|
|
- Check your API key is correct and active
|
|
- Verify you have credits remaining in your ElevenLabs account
|
|
|
|
## Cost
|
|
|
|
ElevenLabs pricing (as of 2024):
|
|
- Free tier: 10,000 characters/month
|
|
- Paid tiers: Starting at $5/month for 30,000 characters
|
|
|
|
Short NPC dialogues typically use 50-200 characters each.
|
|
|
|
---
|
|
|
|
**Created by**: Sahar Carmel
|
|
**License**: MIT
|
|
**ElevenLabs**: https://elevenlabs.io
|