VOICEVOX をインストールして HTTP API を使う

「無料で使える中品質なテキスト読み上げ・歌声合成ソフトウェア」VOICEVOX をインストールし、HTTP API を使用して音声合成をする方法を紹介する。
本記事では、歌声合成は扱わない。

本記事の内容は執筆時点におけるものであり、将来のバージョンアップなどにより変化する可能性がある。

インストール

まず、利用規約を確認する。

ソフトウェア利用規約 | VOICEVOX

トップページの「ダウンロード」を押す。

VOICEVOX | 無料のテキスト読み上げ・歌声合成ソフトウェア

以下のような画面が出るので、OSなどを選択し「ダウンロード」を押す。

ファイルを保存する。
Windows の GPU/CPU 版では、「インストーラー」を選択した場合、ここでのダウンロードサイズは約1.1MBだったが、インストーラーを起動すると以下のような追加の容量を要求する表示が出た。

インストールのために合計 1.60 GB の追加ファイルをダウンロードします。
インストーラーが置かれたドライブには一時的に 3.20 GB 以上の空きが必要です。

「Zip」を選択した場合、ダウンロードサイズは約1.7GBだった。

今回は、インストーラーでインストールを進めた。
起動すると、まず2段階に分かれたデータのダウンロードがあった。
このダウンロード時に表示されるウィンドウは、タスクバーに表示されない上、2段階目のダウンロードが始まる時に位置がリセットされる (というより新しいウィンドウになる？) ため、処理が予期せず止まったと勘違いする可能性がある。
ダウンロードの完了後は、あまり変わった設定項目などは無く、画面に沿って進めるだけだった。

インストール時、「インストール先のドライブ」でも「システムの一時ディレクトリがあるドライブ」でもなく、起動したインストーラがあるドライブの容量の確保が求められる。
また、インストーラを置くドライブを切り替えるため一旦終了すると、その後インストーラを起動してもすぐに終了してしまい、なかなかインストールできなかった。
(現象の発生や解消の条件は不明だが、何度か起動を試みていると、しばらくしたあと起動に成功した。OSの再起動やデータの削除は行わなかった)
インストーラを用いる場合、起動するインストーラを置く位置に注意するべきだろう。

起動

スタートメニューの「VOICEVOX」を選択することで、起動できる。
起動すると、まず利用規約への同意を要求された。
この利用規約はWebページに掲載されているものとは異なり、Google アナリティクスの使用に関するものであった。
とはいえ、1ページに収まる程度に短い、という点は共通していた。

同意すると、キャラクターの紹介の画面になった。
ここでは、各キャラクターの画像が表示され、ボイスを聞くことができるようだった。

「完了」を押すと、利用状況のデータの収集を許可するかを選択する画面になった。
ここでは、プライバシーポリシーとして再び Google アナリティクスの話題が出た。

「許可」を押すと、ここまで使えなかったメニューが使えるようになった。

2回目以降の起動では、ここまでの手順は省略でき、最初からメニューが使えるようだった。

HTTP API の情報

VOICEVOX を起動している間、HTTP API が利用できる。
起動したウィンドウを (×ボタンなどで) 閉じると、VOICEVOX が終了し、HTTP API が利用できなくなる。
最小化であれば利用できる。

HTTP API は、http://localhost:50021 に API のドキュメントにあるパス (/audio_query など) を繋げたパス (http://localhost:50021/audio_query など) でアクセスする。

以下のページに、API のドキュメントがある。
(厳密には VOICEVOX ENGINE OSS のドキュメントなので、公式版とは違うかも)
voicevox_engine API Document

また、API の中に API のドキュメントも含まれている。
VOICEVOX Engine - Swagger UI (VOICEVOX 起動中のみアクセス可)
こちらは上記ページと比べて

• 本編とは別の目次が無い
• 各 API の説明がいちいち開かないと見られない
• 各 API に渡すデータの内容の説明がいちいち Schema を押さないと見られない

などの違いがあって見にくいが、情報の確実性は高いかもしれない。
上記ページを参照していて不具合が出た際に確認するとよさそうだ。

HTTP API の使用

ここでは、具体的に音声合成に使用する HTTP API を見ていく。

話者のリストを取得する

/speakers エンドポイント に GET リクエストを送ることで、選択可能な話者のリストを取得できる。
パラメータは不要である。

curlを用いた呼び出しの例

curl http://localhost:50021/speakers

以下のようなJSON形式のリストが取得できる。(結果を整形し、一部省略した)
他の API の speaker には、この API で得られる styles の要素の id の値を指定する。

[
  {
    "name": "四国めたん",
    "speaker_uuid": "7ffcb7ce-00ec-4bdc-82cd-45a8889e43ff",
    "styles": [
      {
        "name": "ノーマル",
        "id": 2,
        "type": "talk"
      },
      {
        "name": "あまあま",
        "id": 0,
        "type": "talk"
      },
      /* 省略 */
    ],
    "version": "0.15.9",
    "supported_features": {
      "permitted_synthesis_morphing": "SELF_ONLY"
    }
  },
  {
    "name": "ずんだもん",
    "speaker_uuid": "388f246b-8c41-4ac1-8e2d-5d79f3ff56d9",
    "styles": [
      {
        "name": "ノーマル",
        "id": 3,
        "type": "talk"
      },
      {
        "name": "あまあま",
        "id": 1,
        "type": "talk"
      },
      /* 省略 */
    ],
    "version": "0.15.9",
    "supported_features": {
      "permitted_synthesis_morphing": "SELF_ONLY"
    }
  },
  /* 省略 */
]

パラメータとして用いる適当な値を取得する

/audio_query エンドポイント に POST リクエストを送ることで、音声合成時に指定するパラメータとして用いる適当な値を取得できる。

curlを用いた呼び出しの例

curl -X POST "http://localhost:50021/audio_query?text=hoge&speaker=3"

以下のパラメータを指定する。

パラメータ	意味
text	読み上げるテキスト
speaker	用いる話者を指定する整数

以下のようなJSON形式のデータが取得できる。(結果を整形した)
accent_phrases に合成を行う内容が格納され、speedScale から outputStereo までに音声合成用パラメータが格納される。
音声合成用パラメータの意味は、API ドキュメントを参照してほしい。

{
  "accent_phrases": [
    {
      "moras": [
        {
          "text": "ホ",
          "consonant": "h",
          "consonant_length": 0.0942455306649208,
          "vowel": "o",
          "vowel_length": 0.10275200754404068,
          "pitch": 5.911960601806641
        },
        {
          "text": "オ",
          "consonant": null,
          "consonant_length": null,
          "vowel": "o",
          "vowel_length": 0.11444990336894989,
          "pitch": 5.984631061553955
        },
        {
          "text": "ジュ",
          "consonant": "j",
          "consonant_length": 0.08556792885065079,
          "vowel": "u",
          "vowel_length": 0.17203177511692047,
          "pitch": 5.779711723327637
        }
      ],
      "accent": 1,
      "pause_mora": null,
      "is_interrogative": false
    }
  ],
  "speedScale": 1,
  "pitchScale": 0,
  "intonationScale": 1,
  "volumeScale": 1,
  "prePhonemeLength": 0.1,
  "postPhonemeLength": 0.1,
  "pauseLength": null,
  "pauseLengthScale": 1,
  "outputSamplingRate": 24000,
  "outputStereo": false,
  "kana": "ホ'オジュ"
}

このデータをそのまま音声合成 API に渡すことで音声を合成できる場合もあるが、ここでのテキストの指定では読みを指定しづらく、例えばこの例では「hoge」を「ホゲ」ではなく「ホオジュ」と読もうとしてしまっている。
読みを指定するには、後述の API を用いて合成を行う内容を生成し、それをこの accent_phrases と差し替えればよい。

テキストから合成を行う内容を得る

/accent_phrases エンドポイント に POST リクエストを送ることで、テキストから合成を行う内容を得ることができる。

curlを用いた呼び出しの例

curl -X POST "http://localhost:50021/accent_phrases?text=hoge&speaker=3"

以下のパラメータを指定する。

パラメータ	意味
text	読み上げる内容を指定する文字列
speaker	用いる話者を指定する整数
is_kana	テキストの指定方法を表す論理値

is_kana は、以下を指定する。

指定内容	意味
false または省略	text は普通の日本語
true	text は読みの直接指定 (「AquesTalk 風記法」)

結果はJSON形式で取得できる。
上記の呼び出し例では、以下のように、/audio_query で得られたのと同じ結果が得られた。(結果を整形した)

[
  {
    "moras": [
      {
        "text": "ホ",
        "consonant": "h",
        "consonant_length": 0.0942455306649208,
        "vowel": "o",
        "vowel_length": 0.10275200754404068,
        "pitch": 5.911960601806641
      },
      {
        "text": "オ",
        "consonant": null,
        "consonant_length": null,
        "vowel": "o",
        "vowel_length": 0.11444990336894989,
        "pitch": 5.984631061553955
      },
      {
        "text": "ジュ",
        "consonant": "j",
        "consonant_length": 0.08556792885065079,
        "vowel": "u",
        "vowel_length": 0.17203177511692047,
        "pitch": 5.779711723327637
      }
    ],
    "accent": 1,
    "pause_mora": null,
    "is_interrogative": false
  }
]

さらに、is_kana=true を用いることで、読み方 (カナおよびアクセント) を直接指定でき、システムによる読み間違いの懸念を排除できる。
以下の例では、text として ホ'ゲ をURLエンコードした値を指定している。

curlを用いた呼び出しの例 (is_kana を使用)

curl -X POST "http://localhost:50021/accent_phrases?text=%E3%83%9B'%E3%82%B2&speaker=3&is_kana=1"

以下の結果が得られた。(結果を整形した)

[
  {
    "moras": [
      {
        "text": "ホ",
        "consonant": "h",
        "consonant_length": 0.08319418877363205,
        "vowel": "o",
        "vowel_length": 0.09501688182353973,
        "pitch": 5.961258888244629
      },
      {
        "text": "ゲ",
        "consonant": "g",
        "consonant_length": 0.07631837576627731,
        "vowel": "e",
        "vowel_length": 0.2244843691587448,
        "pitch": 5.87221097946167
      }
    ],
    "accent": 1,
    "pause_mora": null,
    "is_interrogative": false
  }
]

/audio_query エンドポイントでは、is_kana=true パラメータを追加しても、結果に変化はみられなかった。

音声合成を行う

/synthesis エンドポイント に POST リクエストを行うことで、合成を行う内容と音声合成用パラメータをもとに実際の音声合成を行える。

curlを用いた呼び出しの例

# 渡すデータをファイルに保存する
curl -X POST -o data.json "http://localhost:50021/audio_query?text=hoge&speaker=3"
# データを渡し、音声合成を行う
curl -X POST -o voice.wav -H "Content-Type: application/json" -d @data.json "http://localhost:50021/synthesis?speaker=3"

以下のパラメータを指定する。

パラメータ	意味
speaker	用いる話者を指定する整数

また、リクエストボディとして、合成を行う内容と音声合成用パラメータを含む JSON データを指定する。

成功すれば、合成結果の wav ファイルがバイナリでそのまま送られてくる。

音声合成用話者の事前初期化を行う

/initialize_speaker エンドポイント に POST リクエストを行うことで、音声合成用話者の事前初期化を行える。
これにより、VOICEVOX の起動後最初にある話者を用いる際に、音声合成のレイテンシが伸びるのを防ぐことができる。

curlを用いた呼び出しの例

curl -X POST "http://localhost:50021/initialize_speaker?speaker=3&skip_reinit=true

以下のパラメータを指定する。

パラメータ	意味
speaker	初期化する話者を指定する整数
skip_reinit	指定した話者が初期化済みのとき、初期化を省略するか

skip_reinit は以下を指定する。

値	意味
false または省略	初期化済みでも初期化を行う
true	初期化済みの場合は初期化を行わない

成功した場合のレスポンスボディは空である。

JavaScript から HTTP API を呼び出す

たとえば、以下のようにすることで、JavaScript から HTTP API を用いて音声合成を行うことができる。

const endpoint = "http://localhost:50021";
const speakerId = 3;
const text = "ハ'ロオ、ワ'アルド";
const isKana = true;

// パラメータを得る
const params = await (await fetch(
  endpoint + "/audio_query?text=&speaker=" + speakerId,
  {
    method: "POST",
  }
)).json();

// 合成を行う内容を得る
const data = await (await fetch(
  endpoint + "/accent_phrases?text=" + encodeURIComponent(text) +
    "&speaker=" + speakerId + (isKana ? "&is_kana=true" : ""),
  {
    method: "POST",
  }
)).json();
params.accent_phrases = data;

// 合成を行う (Blob オブジェクトを得る)
const wav = await (await fetch(
  endpoint + "/synthesis?speaker=" + speakerId,
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
    },
    body: JSON.stringify(params),
  }
)).blob();

このコードでは、簡単のため最低限の処理のみを行い、エラー処理などを省いている。

合成内容は別に生成するため、/audio_query に渡す text は空でよい。
ただし、このパラメータは省略できない。(省略するとエラーになった)

もう少しきちんと実装を行い、Webページの形にしたサンプルを用意した。
JavaScript から VOICEVOX を呼び出すサンプル

このサンプルで API を呼び出す際は、事前に VOICEVOX で CORS の許可設定 (後述) を行うこと。

VOICEVOX の設定を行う

音声合成に GPU を用いる

VOICEVOX のメニュー「設定 → オプション」を開き、「エンジンモード」を「GPU」にすることで、(対応環境では) 音声合成に GPU を使用するようになる。
切り替え後、エンジンの再起動は行わなくても設定が反映された。

筆者の環境 (13th Gen Intel(R) Core(TM) i7-13700H、NVIDIA GeForce RTX 4060 Laptop GPU) では、前述の「ハ'ロオ、ワ'アルド」を再生するサンプルの /synthesis の呼び出しにおける待機時間が、CPU モードでは 430ms 前後、GPU モードでは 300ms 前後となり、GPU を用いたほうが速く処理できた。

localhost 以外のWebページから使用可能にする

デフォルトの設定では、localhost 系のWebページからであれば JavaScript で HTTP API にアクセスできるが、それ以外のWebページから同様にアクセスしようとするとエラーが返ってしまう。
このブロックを解除し、localhost 系以外のWebページからでも HTTP API にアクセスできるようにする設定がある。

まず、
VOICEVOX Engine 設定 (VOICEVOX 起動中のみアクセス可)
をWebブラウザで開く。すると以下のような画面になる。

一部のWebページからのアクセスを許可する場合は、下の Allow Origin に許可するWebページのオリジン (プロトコル・ホスト・ポート番号の組み合わせ。ポート番号はデフォルトであれば省略可能。https://example.com など) を入力する。
入力欄のフォーカスを外したタイミングで設定が保存される。

全てのWebページからのアクセスを許可する場合は、上の CORS Policy Mode の設定を all にする。

いずれの場合も、設定の保存後に VOICEVOX のエンジンの再起動を行うことで、設定を反映させる。
エンジンの再起動は、VOICEVOX のメニューの「エンジン → 再起動」で行うことができる。

エンジンの再起動を忘れないように注意！

localhost へのアクセスは S なしの HTTP でも安全とみなされるためか、HTTPS のWebページからのアクセスでも mixed contents による拒否は行われないようであった。

まとめ

VOICEVOX をインストールして起動後、以下の手順を行うことで、HTTP API により音声合成を行い、合成結果のwavファイルのデータを取得できる。

1. /audio_query エンドポイント で合成パラメータを取得する
2. /accent_phrases エンドポイント で合成内容を取得し、1 で作成したデータの accent_phrases メンバに入れる
3. /synthesis エンドポイント に 2 で作成したデータを渡し、音声合成を行う

localhost 以外のWebページから HTTP API を利用する場合は、http://localhost:50021/setting をWebブラウザで開いて許可設定を行う。