@r4ai/voicevox-cli

v0.3.0

Published

a day ago

[![CI](https://github.com/r4ai/voicevox-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/r4ai/voicevox-cli/actions/workflows/ci.yml) [![Publish](https://github.com/r4ai/voicevox-cli/actions/workflows/publish.yml/badge.svg)](https://github.com/r

0High
0Medium
0Low

r4ai

voicevox-cli

VOICEVOX の CLI ツールと MCP サーバー。

必要環境

Node.js 24+
VOICEVOX ENGINE

[!important] 本 CLI を使うには、VOICEVOX ENGINE が http://localhost:50021 で起動している必要があります。 URL は --host オプションで変更可能です。
Docker で起動する方法：VOICEVOX ENGINE / ユーザーガイド / Docker イメージ

インストール

# npm
npm install -g @r4ai/voicevox-cli

# pnpm
pnpm add -g @r4ai/voicevox-cli

インストールなしで使う方法：

# npm
npx @r4ai/voicevox-cli

# pnpm
pnpx @r4ai/voicevox-cli

CLI

`voicevox speak <text>`

テキストを音声合成して WAV ファイルに保存します。

voicevox speak "こんにちは"
voicevox speak "こんにちは" --speaker 3 --output hello.wav
voicevox speak "こんにちは" --play                          # 合成後に再生
voicevox speak "こんにちは" --morph-target 3               # スピーカー 1 と 3 をモーフィング
voicevox speak "こんにちは" --morph-target 3 --morph-rate 0.8

| オプション | 短縮形 | デフォルト | 説明 | | ---------------- | ------ | ------------------------ | ------------------------------------------------ | | --speaker | -s | 1 | スピーカー ID | | --preset | | | プリセット ID（--speaker より優先） | | --output | -o | output.wav | 出力ファイルパス | | --host | | http://localhost:50021 | VOICEVOX ENGINE の URL | | --play | -p | false | 合成後に再生 | | --morph-target | | | モーフィング先スピーカー ID | | --morph-rate | | 0.5 | モーフィング率（0.0 = ベース、1.0 = ターゲット） |

`voicevox speakers`

利用可能なスピーカーの一覧を表示します。

voicevox speakers
voicevox speakers --json        # JSON で出力
voicevox speakers --info        # バージョン・モーフィング対応・スタイル種別も表示

| オプション | デフォルト | 説明 | | ---------- | ------------------------ | ------------------------------------------------ | | --host | http://localhost:50021 | VOICEVOX ENGINE の URL | | --json | false | JSON で出力 | | --info | false | バージョン・モーフィング対応・スタイル種別を表示 |

`voicevox singers`

歌唱用キャラクターの一覧を表示します。

voicevox singers
voicevox singers --json   # JSON で出力

| オプション | デフォルト | 説明 | | ---------- | ------------------------ | ---------------------- | | --host | http://localhost:50021 | VOICEVOX ENGINE の URL | | --json | false | JSON で出力 |

`voicevox speaker-info <uuid>`

スピーカーの詳細情報（利用ポリシー・アイコン・音声サンプル）を表示します。

voicevox speaker-info <speaker-uuid>
voicevox speaker-info <speaker-uuid> --json   # JSON で出力

`voicevox initialize-speaker <id>`

スピーカーの音声モデルをメモリに読み込みます。合成前に未初期化のスピーカーを使用する場合に呼び出します。

voicevox initialize-speaker 1
voicevox initialize-speaker 1 --skip-reinit   # 初期化済みならスキップ

| オプション | デフォルト | 説明 | | --------------- | ------------------------ | ------------------------------------ | | --skip-reinit | false | 初期化済みの場合は再初期化をスキップ | | --host | http://localhost:50021 | VOICEVOX ENGINE の URL |

`voicevox is-initialized-speaker <id>`

スピーカーが初期化済みかどうかを確認します。

voicevox is-initialized-speaker 1   # true または false を出力

| オプション | デフォルト | 説明 | | ---------- | ------------------------ | ---------------------- | | --host | http://localhost:50021 | VOICEVOX ENGINE の URL |

`voicevox query <text>`

テキストの AudioQuery JSON を表示します。

voicevox query "こんにちは"
voicevox query "こんにちは" --speaker 3

| オプション | 短縮形 | デフォルト | 説明 | | ----------- | ------ | ------------------------ | ---------------------- | | --speaker | -s | 1 | スピーカー ID | | --host | | http://localhost:50021 | VOICEVOX ENGINE の URL |

`voicevox accent-phrases <text>`

テキストのアクセント句 JSON を表示します。audio_query を直接編集せず、アクセント句単位で音声の抑揚や長さを調整したい場合に使用します。

voicevox accent-phrases "こんにちは"
voicevox accent-phrases "こんにちは" --speaker 3
voicevox accent-phrases "コンニチワ" --is-kana

| オプション | 短縮形 | デフォルト | 説明 | | ----------- | ------ | ------------------------ | ---------------------- | | --speaker | -s | 1 | スピーカー ID | | --is-kana | | false | テキストがカナかどうか | | --host | | http://localhost:50021 | VOICEVOX ENGINE の URL |

`voicevox dict`

ユーザー辞書を管理します。

voicevox dict                          # 辞書の一覧を表示
voicevox dict --json                   # JSON で出力
voicevox dict add <surface> <読み>     # 単語を追加
voicevox dict update <uuid> [options]  # 単語を更新
voicevox dict delete <uuid>            # 単語を削除
voicevox dict export <file.json>       # JSON ファイルにエクスポート
voicevox dict import <file.json>       # JSON ファイルからインポート

`voicevox dict add <surface> <pronunciation>`

| オプション | 短縮形 | デフォルト | 説明 | | --------------- | ------ | ------------------------ | ---------------------------------------------------------------------- | | --accent-type | -a | 0 | アクセント型 | | --word-type | -t | COMMON_NOUN | 品詞 (PROPER_NOUN / COMMON_NOUN / VERB / ADJECTIVE / SUFFIX) | | --priority | -p | 5 | 優先度 (0–10) | | --host | | http://localhost:50021 | VOICEVOX ENGINE の URL |

`voicevox dict update <uuid>`

| オプション | 短縮形 | 説明 | | ----------------- | ------ | ---------------------- | | --surface | -s | 表層形 | | --pronunciation | -r | 読み (カタカナ) | | --accent-type | -a | アクセント型 | | --word-type | -t | 品詞 | | --priority | -p | 優先度 (0–10) | | --host | | VOICEVOX ENGINE の URL |

`voicevox dict export <file>`

| オプション | デフォルト | 説明 | | ---------- | ------------------------ | ---------------------- | | --indent | 2 | JSON インデント幅 | | --host | http://localhost:50021 | VOICEVOX ENGINE の URL |

`voicevox dict import <file>`

| オプション | 短縮形 | デフォルト | 説明 | | ------------ | ------ | ------------------------ | ---------------------- | | --override | -f | false | 既存エントリを上書き | | --host | | http://localhost:50021 | VOICEVOX ENGINE の URL |

`voicevox presets`

プリセットを管理します。

voicevox presets                    # プリセット一覧を表示
voicevox presets --json             # JSON で出力
voicevox presets add --name <name> --speaker-uuid <uuid> [options]
voicevox presets update <id> [options]
voicevox presets delete <id>

`voicevox presets add`

| オプション | 短縮形 | デフォルト | 説明 | | ----------------------- | ------ | ------------------------ | ----------------------- | | --name | -n | | プリセット名（必須） | | --speaker-uuid | -u | | スピーカー UUID（必須） | | --style-id | -s | 0 | スタイル ID | | --speed | | 1.0 | 話速 | | --pitch | | 0.0 | 音高 | | --intonation | | 1.0 | 抑揚 | | --volume | | 1.0 | 音量 | | --pre-phoneme-length | | 0.1 | 開始無音時間 | | --post-phoneme-length | | 0.1 | 終了無音時間 | | --host | | http://localhost:50021 | VOICEVOX ENGINE の URL |

`voicevox presets update <id>`

| オプション | 短縮形 | 説明 | | ----------------------- | ------ | ---------------------- | | --name | -n | プリセット名 | | --speaker-uuid | -u | スピーカー UUID | | --style-id | -s | スタイル ID | | --speed | | 話速 | | --pitch | | 音高 | | --intonation | | 抑揚 | | --volume | | 音量 | | --pre-phoneme-length | | 開始無音時間 | | --post-phoneme-length | | 終了無音時間 | | --host | | VOICEVOX ENGINE の URL |

`voicevox validate-kana <text>`

テキストが AquesTalk 風記法に従っているか検証します。

voicevox validate-kana "コンニチワ"

| オプション | デフォルト | 説明 | | ---------- | ------------------------ | ---------------------- | | --host | http://localhost:50021 | VOICEVOX ENGINE の URL |

`voicevox morphable-targets`

エンジンからスピーカー一覧を取得し、各スタイルのモーフィング可否を表示します。

voicevox morphable-targets
voicevox morphable-targets --json   # JSON で出力

`voicevox version`

エンジンバージョンとコアバージョンを表示します。

voicevox version
voicevox version --host http://localhost:50021

| オプション | デフォルト | 説明 | | ---------- | ------------------------ | ---------------------- | | --host | http://localhost:50021 | VOICEVOX ENGINE の URL |

`voicevox info`

エンジンマニフェストと対応デバイス情報を表示します。

voicevox info
voicevox info --json   # JSON で出力

`voicevox setting`

エンジン設定を表示・更新します。

voicevox setting                                      # 現在の設定を表示
voicevox setting --json                               # JSON で出力
voicevox setting set --cors-policy-mode all           # CORS ポリシーを変更
voicevox setting set --allow-origin http://localhost  # 許可 Origin を設定
voicevox setting set --allow-origin ""                # 許可 Origin をクリア

`voicevox setting set`

| オプション | 説明 | | -------------------- | ---------------------------------------- | | --cors-policy-mode | CORS ポリシーモード: localapps / all | | --allow-origin | 許可する Origin（空文字列でクリア） | | --host | VOICEVOX ENGINE の URL |

`voicevox mcp`

MCP サーバーを stdio モードで起動します。

voicevox mcp
voicevox mcp --host http://localhost:50021

`voicevox complete <shell>`

シェル補完スクリプトを生成します。対応シェル: bash / zsh / fish / powershell

voicevox complete bash
voicevox complete zsh
voicevox complete fish
voicevox complete powershell

セットアップ

Bash

# 現在のセッションで有効化
source <(voicevox complete bash)

# 永続化（~/.bashrc に追記）
echo 'source <(voicevox complete bash)' >> ~/.bashrc

Zsh

# 現在のセッションで有効化
source <(voicevox complete zsh)

# 永続化（~/.zshrc に追記）
echo 'source <(voicevox complete zsh)' >> ~/.zshrc

Fish

voicevox complete fish > ~/.config/fish/completions/voicevox.fish

PowerShell

# $PROFILE に追記して永続化
voicevox complete powershell >> $PROFILE

詳しくは @gunshi/plugin-completion を参照してください。

MCP サーバー

voicevox mcp で MCP サーバーを起動すると、以下のツールが利用できます。

| ツール名 | -------------------------------- | list_speakers | get_speaker_info | initialize_speaker | is_initialized_speaker | audio_query | synthesize | get_accent_phrases | get_mora_data | get_mora_length | get_mora_pitch | get_user_dict | export_user_dict | add_user_dict_word | update_user_dict_word | delete_user_dict_word | list_presets | create_audio_query_from | validate_kana | get_morphable_targets | get_engine_info | get_engine_licenses | get_engine_update_history | get_setting | update_setting | list_singers | sing | multi_synthesize | synthesis_morphing | connect_waves | cancellable_synthesize | 説明 | | ---------------------------------------------------------------------------------------------------- | | 利用可能なスピーカーの一覧を返す（include_supported_features でモーフィング許可情報を追加取得） | | sections で取得範囲を指定してスピーカー情報を取得する（デフォルト: ポリシーとスタイルアイコン） | | スピーカーの音声モデルをメモリに読み込む | | スピーカーが初期化済みかどうかを確認する | | テキストの AudioQuery JSON を返す | | テキストを音声合成して WAV ファイルを保存し、パスを返す | | テキストからアクセント句を取得する | | アクセント句から音素の長さと音高を取得する | | アクセント句から音素の長さを取得する | | アクセント句から音高を取得する | | ユーザー辞書の単語を返す（search / word_type でフィルタ、limit / offset でページネーション） | | ユーザー辞書全体を import_user_dict で再インポート可能な JSON 形式でエクスポートする | | ユーザー辞書に単語を追加する | | ユーザー辞書の単語を更新する | | ユーザー辞書の単語を削除する | | プリセット一覧を返す | _preset | プリセットを使って AudioQuery を作成する | | AquesTalk 風かな表記が正しいか検証する | | 指定スタイルからモーフィング可能なスタイル ID のリストを取得する | | エンジン情報（バージョン・マニフェスト概要・対応デバイス）を取得する（icon・依存ライセンス等は除外） | | エンジンの依存ライブラリのライセンス一覧を取得する | | エンジンの更新履歴を取得する | | エンジン設定を取得する | | エンジン設定を更新する | | 歌唱用キャラクターの一覧を返す（include_supported_features でモーフィング許可情報を追加取得） | | 楽譜データから歌唱音声を合成して WAV ファイルを保存し、パスを返す | | 複数テキストを一括音声合成して ZIP ファイルを保存し、パスを返す | | 2スタイル間をモーフィングした音声を合成して WAV ファイルを保存する | | 複数の WAV ファイルを結合して1つの WAV ファイルを保存し、パスを返す | | キャンセル可能な合成エンドポイントでテキストを音声合成して WAV ファイルを保存する |

Claude Code への設定例

.mcp.json に以下を追加します。

{
  "mcpServers": {
    "voicevox": {
      "command": "npx",
      "args": ["@r4ai/voicevox-cli", "mcp"]
    }
  }
}

Claude Desktop への設定例

claude_desktop_config.json に以下を追加します。

{
  "mcpServers": {
    "voicevox": {
      "command": "npx",
      "args": ["@r4ai/voicevox-cli", "mcp"]
    }
  }
}

開発

.tool-versions を使う場合は asdf install または mise install で Node.js を揃えてください。

pnpm install
pnpm build

pnpm dev        # ウォッチモードでビルド
pnpm build      # ビルド
pnpm typecheck  # 型チェック
pnpm test       # ユニットテストを実行

E2E テストを実行するには VOICEVOX ENGINE が起動している必要があります。

VOICEVOX_HOST=http://localhost:50021 pnpm test:e2e

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

voicevox-cli

必要環境

インストール

CLI

voicevox speak <text>

voicevox speakers

voicevox singers

voicevox speaker-info <uuid>

voicevox initialize-speaker <id>

voicevox is-initialized-speaker <id>

voicevox query <text>

voicevox accent-phrases <text>

voicevox dict

voicevox dict add <surface> <pronunciation>

voicevox dict update <uuid>

voicevox dict export <file>

voicevox dict import <file>

voicevox presets

voicevox presets add

voicevox presets update <id>

voicevox validate-kana <text>

voicevox morphable-targets

voicevox version

voicevox info

voicevox setting

voicevox setting set

voicevox mcp

voicevox complete <shell>

セットアップ

MCP サーバー

Claude Code への設定例

Claude Desktop への設定例

開発

`voicevox speak <text>`

`voicevox speakers`

`voicevox singers`

`voicevox speaker-info <uuid>`

`voicevox initialize-speaker <id>`

`voicevox is-initialized-speaker <id>`

`voicevox query <text>`

`voicevox accent-phrases <text>`

`voicevox dict`

`voicevox dict add <surface> <pronunciation>`

`voicevox dict update <uuid>`

`voicevox dict export <file>`

`voicevox dict import <file>`

`voicevox presets`

`voicevox presets add`

`voicevox presets update <id>`

`voicevox validate-kana <text>`

`voicevox morphable-targets`

`voicevox version`

`voicevox info`

`voicevox setting`

`voicevox setting set`

`voicevox mcp`

`voicevox complete <shell>`