VOICEVOX Narration System

Complete workflow for converting Miyabi development progress into Yukkuri-style voice narration using VOICEVOX Engine API.

When to Use

• User requests "create voice narration", "generate audio guide", "create development report"
• After significant development milestones (weekly/daily reports)
• When preparing YouTube content for development updates
• For team communication in audio format

Workflow Steps

1. VOICEVOX Engine Status Check

# Check if VOICEVOX Engine is running
curl -s http://127.0.0.1:50021/version

# If not running, start it (optional with -s flag)
cd /Users/a003/dev/voicevox_engine
uv run run.py --enable_mock --host 127.0.0.1 --port 50021

2. Generate Script from Git Commits

cd /Users/a003/dev/miyabi-private/tools

# Basic execution (last 3 days)
python3 yukkuri-narration-generator.py

# Custom time range
python3 yukkuri-narration-generator.py --days 7

# Outputs:
# - script.md: Yukkuri-style dialogue script (Reimu & Marisa)
# - voicevox_requests.json: API request data

3. Synthesize Audio with VOICEVOX

# Generate WAV files from script
python3 voicevox-synthesizer.py

# Outputs:
# - audio/speaker0_000.wav (Reimu)
# - audio/speaker1_001.wav (Marisa)
# - ... (multiple audio files)

4. Unified Execution (Recommended)

# All-in-one script with options
./miyabi-narrate.sh

# With custom options
./miyabi-narrate.sh --days 7 --output ~/Desktop/narration --start-engine

# Options:
#   -d, --days N         Past N days of commits (default: 3)
#   -o, --output DIR     Output directory (default: ./output)
#   -s, --start-engine   Auto-start VOICEVOX Engine
#   -k, --keep-engine    Keep Engine running after completion

5. Verify Output

# Check generated files
ls -lh output/

# Play audio (macOS)
afplay output/audio/speaker0_000.wav

# Read script
cat output/script.md

Project-Specific Considerations

Git Commits Parsing

The system parses Conventional Commits format:

• Type: feat, fix, docs, security, test, refactor
• Scope: Module name (e.g., design, web-ui)
• Issue Number: Extracted from #XXX format
• Phase: Extracted from "Phase X.X" format

Example commit message:

feat(design): complete Phase 0.4 - Issue #425

VOICEVOX Speaker IDs

Default configuration:

• Speaker ID 0: Reimu (霊夢) - Explanation role
• Speaker ID 1: Marisa (魔理沙) - Reaction role

To customize speakers:

1. Check available speakers:

   curl http://127.0.0.1:50021/speakers | python -m json.tool

2. Edit tools/yukkuri-narration-generator.py:

   self.reimu_speaker_id = 3   # Change to desired speaker
   self.marisa_speaker_id = 6  # Change to desired speaker

Output Structure

output/
├── script.md                   # Yukkuri-style dialogue script
├── voicevox_requests.json      # VOICEVOX API request data
├── SUMMARY.md                  # Execution summary report
└── audio/                      # Audio files (WAV format)
    ├── speaker0_000.wav        # Reimu (intro)
    ├── speaker1_001.wav        # Marisa (response)
    ├── speaker0_002.wav        # Reimu (commit 1)
    └── ...

Common Issues

Issue: VOICEVOX Engine Connection Failed

Symptoms:

❌ VOICEVOX Engineに接続できません

Solutions:

1. Check if Engine is running:

   curl http://127.0.0.1:50021/version

2. Start Engine manually:

   cd /Users/a003/dev/voicevox_engine
   uv run run.py --enable_mock

3. Or use auto-start option:

   ./miyabi-narrate.sh --start-engine

Issue: No Audio Files Generated

Symptoms:

• audio/ directory is empty
• VOICEVOX API errors

Solutions:

1. Verify voicevox_requests.json exists:

   cat voicevox_requests.json

2. Check speaker IDs are valid:

   curl http://127.0.0.1:50021/speakers

3. Re-run synthesis:

   python3 voicevox-synthesizer.py

Issue: No Git Commits Found

Symptoms:

0件のコミットを取得しました

Solutions:

1. Verify you're in a Git repository:

   git log --oneline --since="3 days ago"

2. Check if commits exist in the time range:

   git log --oneline --since="7 days ago"

3. Run from correct directory:

   cd /Users/a003/dev/miyabi-private
   tools/yukkuri-narration-generator.py

Success Criteria

All checks must pass:

• ✅ VOICEVOX Engine is running (http://127.0.0.1:50021)
• ✅ Git commits are successfully parsed
• ✅ script.md is generated with dialogue
• ✅ voicevox_requests.json contains API requests
• ✅ Audio files are created in audio/ directory
• ✅ All files are copied to output/ directory

Output Format

Report results in this format:

🎤 Miyabi開発進捗 → ゆっくり解説音声ガイド

✅ VOICEVOX Engine: 接続確認OK
✅ Git commits: XX件のコミットを取得
✅ 台本生成: script.md (XX行)
✅ 音声合成: XX件のファイルを生成 (XX MB)

📁 出力: output/
  - script.md
  - voicevox_requests.json
  - SUMMARY.md
  - audio/*.wav (XX files)

Ready for YouTube production ✓

Integration with Miyabi

Command Integration

Use the /narrate command for simplified execution:

/narrate
/narrate --days 7
/narrate --output ~/reports --start-engine

See .claude/commands/narrate.md for full documentation.

Agent Integration

The NarrationAgent (narration-agent.md) provides automated workflow:

• Automated Git history analysis
• Context-aware dialogue generation
• Quality validation
• YouTube metadata generation

GitHub Actions Integration

Automated daily execution:

# .github/workflows/miyabi-narration.yml
on:
  schedule:
    - cron: '0 9 * * *'  # Daily at 18:00 JST

See tools/GITHUB_ACTIONS.md for CI/CD setup.

Related Skills

• Agent Execution: For running NarrationAgent
• Git Workflow: For commit history management
• Content Marketing Strategy: For YouTube content planning

References

• VOICEVOX Engine: https://github.com/VOICEVOX/voicevox_engine
• VOICEVOX API: https://voicevox.github.io/voicevox_engine/api/
• Conventional Commits: https://www.conventionalcommits.org/
• Documentation: tools/README.md, tools/PROJECT_SUMMARY.md