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:

Check available speakers:

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

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:

Check if Engine is running:

curl http://127.0.0.1:50021/version

Start Engine manually:

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

Or use auto-start option:

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

Issue: No Audio Files Generated

Symptoms:

• audio/ directory is empty

• VOICEVOX API errors

Solutions:

Verify voicevox_requests.json exists:

cat voicevox_requests.json

Check speaker IDs are valid:

curl http://127.0.0.1:50021/speakers

Re-run synthesis:

python3 voicevox-synthesizer.py

Issue: No Git Commits Found

Symptoms:

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

Solutions:

Verify you're in a Git repository:

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

Check if commits exist in the time range:

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

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