Awesome

VOICEVOX

VOICEVOX のエディターです。

（エンジンは VOICEVOX ENGINE 、コアは VOICEVOX CORE 、全体構成はこちらに詳細があります。）

ユーザーの方へ

こちらは開発用のページになります。利用方法に関してはVOICEVOX 公式サイトをご覧ください。

プロジェクトに貢献したいと考えている方へ

VOICEVOXプロジェクトは興味ある方の参画を歓迎しています。貢献手順について説明したガイドをご用意しております。

貢献というとプログラム作成と思われがちですが、ドキュメント執筆、テスト生成、改善提案への議論参加など様々な参加方法があります。初心者歓迎タスクもありますので、皆様のご参加をお待ちしております。

VOICEVOX のエディタは Electron・TypeScript・Vue・Vuex などが活用されており、全体構成がわかりにくくなっています。
コードの歩き方で構成を紹介しているので、開発の一助になれば幸いです。

Issue を解決するプルリクエストを作成される際は、別の方と同じ Issue に取り組むことを避けるため、 Issue 側で取り組み始めたことを伝えるか、最初に Draft プルリクエストを作成してください。

VOICEVOX 非公式 Discord サーバーにて、開発の議論や雑談を行っています。気軽にご参加ください。

デザインガイドライン

UX・UI デザインの方針をご参照ください。

環境構築

.node-version に記載されているバージョンの Node.js をインストールしてください。
Node.js の管理ツール（nvsやVoltaなど）を利用すると簡単にインストールでき、Node.js の自動切り替えもできます。

Node.js をインストール後、このリポジトリを Fork して git clone してください。

依存ライブラリをインストールする

次のコマンドを実行することで依存ライブラリがインストール・アップデートされます。

npm ci

実行

エンジンの準備

.env.productionをコピーして.envを作成し、VITE_DEFAULT_ENGINE_INFOS内のexecutionFilePathに製品版 VOICEVOX 内のvv-engine/run.exeを指定すれば動きます。

Windows でインストール先を変更していない場合はC:/Users/(ユーザー名)/AppData/Local/Programs/VOICEVOX/vv-engine/run.exeを指定してください。
パスの区切り文字は\ではなく/なのでご注意ください。

macOS 向けのVOICEVOX.appを利用している場合は/path/to/VOICEVOX.app/Resources/MacOS/vv-engine/runを指定してください。

Linux の場合は、Releasesから入手できる tar.gz 版に含まれるvv-engine/runコマンドを指定してください。 AppImage 版の場合は$ /path/to/VOICEVOX.AppImage --appimage-mountでファイルシステムをマウントできます。

VOICEVOX エディタの実行とは別にエンジン API のサーバを立てている場合はexecutionFilePathを指定する必要はありませんが、代わりにexecutionEnabledをfalseにしてください。これは製品版 VOICEVOX を起動している場合もあてはまります。

エンジン API の宛先エンドポイントを変更する場合はVITE_DEFAULT_ENGINE_INFOS内のhostを変更してください。

Electron の実行

# 開発しやすい環境で実行
npm run electron:serve

# ビルド時に近い環境で実行
npm run electron:serve -- --mode production

音声合成エンジンのリポジトリはこちらです https://github.com/VOICEVOX/voicevox_engine

Storybook の実行

Storybook を使ってコンポーネントを開発することができます。

npm run storybook

main ブランチの Storybook はVOICEVOX/preview-pagesから確認できます。
https://voicevox.github.io/preview-pages/preview/branch-main/storybook/index.html

ブラウザ版の実行（開発中）

別途音声合成エンジンを起動し、以下を実行して表示された localhost へアクセスします。

npm run browser:serve

また、main ブランチのビルド結果がVOICEVOX/preview-pagesにデプロイされています。
https://voicevox.github.io/preview-pages/preview/branch-main/editor/index.html
今はローカル PC 上で音声合成エンジンを起動する必要があります。

ビルド

npm run electron:build

Github Actions でビルド

fork したリポジトリで Actions を ON にし、workflow_dispatch でbuild.ymlを起動すればビルドできます。成果物は Release にアップロードされます。

テスト

単体テスト

./tests/unit/ 以下にあるテストと、Storybookのテストを実行します。

npm run test:unit
npm run test-watch:unit # 監視モード
npm run test-ui:unit # VitestのUIを表示
npm run test:unit -- --update # スナップショットの更新

[!NOTE]
./tests/unit 下のテストは、ファイル名によってテストを実行する環境が変化します。

.node.spec.ts：Node.js 環境

.browser.spec.ts：ブラウザ環境（Chromium）

.spec.ts：ブラウザ環境（happy-domによるエミュレート）

ブラウザ End to End テスト

Electron の機能が不要な、UI や音声合成などの End to End テストを実行します。

[!NOTE] 一部のエンジンの設定を書き換えるテストは、CI(Github Actions)上でのみ実行されるようになっています。

npm run test:browser-e2e
npm run test-watch:browser-e2e # 監視モード
npm run test-watch:browser-e2e -- --headed # テスト中の UI を表示
npm run test-ui:browser-e2e # Playwright の UI を表示

Playwright を使用しているためテストパターンを生成することもできます。 ブラウザ版を起動している状態で以下のコマンドを実行してください。

npx playwright codegen http://localhost:5173/  --viewport-size=1024,630

詳細は Playwright ドキュメントの Test generator を参照してください。

Storybook の Visual Regression Testing

Storybook のコンポーネントのスクリーンショットを比較して、変更がある場合は差分を表示します。

[!NOTE] このテストは Windows でのみ実行できます。

npm run test:storybook-vrt
npm run test-watch:storybook-vrt # 監視モード
npm run test-ui:storybook-vrt # Playwright の UI を表示

スクリーンショットの更新

ブラウザ End to End テストと Storybook では Visual Regression Testing を行っています。現在 VRT テストは Windows のみで行っています。以下の手順でスクリーンショットを更新できます：

Github Actions で更新する場合

フォークしたリポジトリの設定で GitHub Actions を有効にします。
リポジトリの設定の Actions > General > Workflow permissions で Read and write permissions を選択します。
[update snapshots] という文字列をコミットメッセージに含めてコミットします。
```
git commit -m "UIを変更 [update snapshots]"
```
Github Workflow が完了すると、更新されたスクリーンショットがコミットされます。
プルした後、空コミットをプッシュしてテストを再実行します。
```
git commit --allow-empty -m "（テストを再実行）"
git push
```

[!NOTE] トークンを作成して Secrets に追加することで、自動的にテストを再実行できます。

Fine-granted Tokens にアクセスします。

適当な名前を入力し、 ユーザー名/voicevox へのアクセス権を与え、 Repository permissions の Contents で Read and write を選択します。 <details> <summary>設定例</summary> <img src="./docs/res/Fine-granted_Tokensの作成.png" width="320"> </details>

トークンを作成して文字列をコピーします。

ユーザー名/voicevox のリポジトリの Settings > Secrets and variables > Actions > New repository secret を開きます。

名前に PUSH_TOKEN と入力し、先ほどの文字列を貼り付けて Secrets を追加します。

ローカルで更新する場合

ローカル PC の OS に対応したもののみが更新されます。

npm run test:browser-e2e -- --update-snapshots

Electron End to End テスト

Electron の機能が必要な、エンジン起動・終了などを含めた End to End テストを実行します。

npm run test:electron-e2e
npm run test-watch:electron-e2e # 監視モード

依存ライブラリのライセンス情報の生成

依存ライブラリのライセンス情報は Github Workflow でのビルド時に自動生成されます。以下のコマンドで生成できます。

# get licenses.json from voicevox_engine as engine_licenses.json

npm run license:generate -- -o voicevox_licenses.json
npm run license:merge -- -o public/licenses.json -i engine_licenses.json -i voicevox_licenses.json

コードフォーマット

コードのフォーマットを整えます。プルリクエストを送る前に実行してください。

npm run fmt

リント（静的解析）

コードの静的解析を行い、バグを未然に防ぎます。プルリクエストを送る前に実行してください。

npm run lint

タイポチェック

typos を使ってタイポのチェックを行っています。

npm run typos

でタイポチェックを行えます。もし誤判定やチェックから除外すべきファイルがあれば設定ファイルの説明に従って_typos.tomlを編集してください。

型チェック

TypeScript の型チェックを行います。

npm run typecheck

Markdownlint

Markdown の文法チェックを行います。

npm run markdownlint

Shellcheck

ShellScript の文法チェックを行います。インストール方法はこちらを参照してください。

shellcheck ./build/*.sh

OpenAPI generator

音声合成エンジンが起動している状態で以下のコマンドを実行してください。

curl http://127.0.0.1:50021/openapi.json >openapi.json

npx openapi-generator-cli generate \
    -i openapi.json \
    -g typescript-fetch \
    -o src/openapi/ \
    --additional-properties "modelPropertyNaming=camelCase,supportsES6=true,withInterfaces=true,typescriptThreePlus=true"

npm run fmt

OpanAPI generator のバージョンアップ

新しいバージョンの確認・インストールは次のコマンドで行えます。

npx openapi-generator-cli version-manager list

VS Code でのデバッグ実行

npm scripts の serve や electron:serve などの開発ビルド下では、ビルドに使用している vite で sourcemap を出力するため、ソースコードと出力されたコードの対応付けが行われます。

.vscode/launch.template.json をコピーして .vscode/launch.json を、 .vscode/tasks.template.json をコピーして .vscode/tasks.json を作成することで、開発ビルドを VS Code から実行し、デバッグを可能にするタスクが有効になります。

ライセンス

LGPL v3 と、ソースコードの公開が不要な別ライセンスのデュアルライセンスです。別ライセンスを取得したい場合は、ヒホに求めてください。
X アカウント: @hiho_karuta