前提条件

macOS環境
VOICEVOXがインストール済み
VOICEVOXアプリが起動している（ローカルサーバー http://127.0.0.1:50021 が稼働）

手順

Step 0: VOICEVOXサーバーの起動確認

音声ファイルを生成する前に、VOICEVOXが正常に稼働しているか確認する。

curl -s http://127.0.0.1:50021/version
# 例: "0.14.7" などバージョンが返ってくれば起動中

応答がない場合は、VOICEVOXアプリを起動してから次のステップへ進む。

Step 1: ディレクトリ作成

mkdir -p ~/.claude/sounds

Step 2: VOICEVOXで音声ファイルを生成

VOICEVOXは2ステップAPIで音声を生成する。

重要: 日本語テキストを扱う場合、-Gフラグと--data-urlencodeを組み合わせる必要がある。

完了通知用

QUERY=$(curl -s -G -X POST "http://127.0.0.1:50021/audio_query" \
  --data-urlencode "text=タスクが完了したのだ" \
  -d "speaker=3")

curl -s -X POST "http://127.0.0.1:50021/synthesis?speaker=3" \
  -H "Content-Type: application/json" \
  -d "$QUERY" \
  --output ~/.claude/sounds/zunda_finished.wav

権限リクエスト用

QUERY=$(curl -s -G -X POST "http://127.0.0.1:50021/audio_query" \
  --data-urlencode "text=許可が必要なのだ" \
  -d "speaker=3")

curl -s -X POST "http://127.0.0.1:50021/synthesis?speaker=3" \
  -H "Content-Type: application/json" \
  -d "$QUERY" \
  --output ~/.claude/sounds/zunda_permission.wav

Step 3: 音声ファイルの動作確認

afplay ~/.claude/sounds/zunda_finished.wav
afplay ~/.claude/sounds/zunda_permission.wav

Step 4: Claude Code設定を編集

~/.claude/settings.json に以下を追加。

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "afplay ~/.claude/sounds/zunda_permission.wav"
          }
        ]
      }
    ],
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "afplay ~/.claude/sounds/zunda_finished.wav"
          }
        ]
      }
    ]
  }
}

フックイベントの説明

イベント	発火タイミング
`Stop`	Claude Codeの応答完了時
`Notification`	権限リクエスト、60秒以上のアイドル時など

ずんだもんスピーカーID一覧

ID	スタイル
3	ノーマル
1	あまあま
7	ツンツン
5	セクシー

好みに応じてspeaker=の値を変更可能。

VOICEVOX API仕様

2ステップ音声生成フロー

audio_query: テキストから音声クエリを生成
synthesis: クエリから音声を合成

[テキスト] → /audio_query → [クエリJSON] → /synthesis → [WAVファイル]

エンドポイント

エンドポイント	メソッド	用途
`/version`	GET	サーバー稼働確認
`/audio_query`	POST	音声クエリ生成
`/synthesis`	POST	音声合成
`/speakers`	GET	利用可能なスピーカー一覧

トラブルシューティング

AudioFileOpen failed ('typ?')

音声ファイルがWAV形式ではなくJSONエラーレスポンスになっている。

確認方法:

file ~/.claude/sounds/zunda_finished.wav
# 正常: RIFF (little-endian) data, WAVE audio
# 異常: JSON data

原因と解決策:

VOICEVOXサーバーが起動していない

curl -s http://127.0.0.1:50021/version
# バージョンが返ってくれば起動中

URLエンコードの問題
- curl -X POST "...?text=日本語..." → 失敗することがある
- curl -G -X POST ... --data-urlencode "text=日本語" → 正しい方法

Exit code 52

サーバーから応答がない。-Gフラグを付け忘れている可能性が高い。

カスタマイズ例

音量調整

afplay --volume 0.5 ~/.claude/sounds/zunda_finished.wav

--volumeは0.0〜1.0で指定。

バックグラウンド再生

afplay ~/.claude/sounds/zunda_finished.wav &

他のメッセージを追加

# エラー通知用
QUERY=$(curl -s -G -X POST "http://127.0.0.1:50021/audio_query" \
  --data-urlencode "text=エラーが発生したのだ" \
  -d "speaker=3")

curl -s -X POST "http://127.0.0.1:50021/synthesis?speaker=3" \
  -H "Content-Type: application/json" \
  -d "$QUERY" \
  --output ~/.claude/sounds/zunda_error.wav