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

bash

# 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

bash

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

bash

# 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)

bash

# 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

bash

# 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:

code

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:

•

Check available speakers:

bash

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

•

Edit tools/yukkuri-narration-generator.py:

python

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

Output Structure

code

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:

code

❌ VOICEVOX Engineに接続できません

Solutions:

•
Check if Engine is running:
bash
```
curl http://127.0.0.1:50021/version
```

•

Start Engine manually:

bash

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

•
Or use auto-start option:
bash
```
./miyabi-narrate.sh --start-engine
```

Issue: No Audio Files Generated

Symptoms:

•audio/ directory is empty
•VOICEVOX API errors

Solutions:

•
Verify voicevox_requests.json exists:
bash
```
cat voicevox_requests.json
```
•
Check speaker IDs are valid:
bash
```
curl http://127.0.0.1:50021/speakers
```
•
Re-run synthesis:
bash
```
python3 voicevox-synthesizer.py
```

Issue: No Git Commits Found

Symptoms:

code

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

Solutions:

•
Verify you're in a Git repository:
bash
```
git log --oneline --since="3 days ago"
```
•
Check if commits exist in the time range:
bash
```
git log --oneline --since="7 days ago"
```

•

Run from correct directory:

bash

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:

code

🎤 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:

code

/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:

yaml

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