vox-actor-plugin

vox-actor

テキストファイルやテキストをVOICEVOXエンジンで音声合成し、読み上げるCLIツールです。

クイックスタート

1. VOICEVOXエンジンを起動する

   • インストーラー版: 公式サイトからダウンロードしてインストール後、アプリを起動する
   • Docker版: docker run --rm -p 50021:50021 voicevox/voicevox_engine:latest

2. vox-actorをインストールする

   GitHub Releasesからビルド済みバイナリをダウンロードして配置します。

   # Linux (x86_64) の場合
   curl -fLo vox-actor.tar.gz https://github.com/canpok1/vox-actor/releases/latest/download/vox-actor_Linux_x86_64.tar.gz
   tar xzf vox-actor.tar.gz
   sudo mv vox-actor /usr/local/bin/
   
   # macOS (Apple Silicon) の場合
   curl -fLo vox-actor.tar.gz https://github.com/canpok1/vox-actor/releases/latest/download/vox-actor_Darwin_arm64.tar.gz
   tar xzf vox-actor.tar.gz
   sudo mv vox-actor /usr/local/bin/
   
   # macOS (Intel) の場合
   curl -fLo vox-actor.tar.gz https://github.com/canpok1/vox-actor/releases/latest/download/vox-actor_Darwin_x86_64.tar.gz
   tar xzf vox-actor.tar.gz
   sudo mv vox-actor /usr/local/bin/
   

3. テキストを読み上げる

   vox-actor say "こんにちは"
   

4. ディレクトリを監視して自動読み上げする

   vox-actor act --watch /path/to/watch-dir
   

   別のターミナルからテキストファイルを配置すると、自動的に読み上げられます。

   echo "こんばんは" > /path/to/watch-dir/sample.txt
   

前提条件

• Go 1.26.1 以上（ソースからビルドする場合）
• VOICEVOX エンジンが起動していること（デフォルト: http://localhost:50021）
  • インストーラー版: 公式サイトからダウンロードしてインストール後、アプリを起動する
  • Docker版: docker run --rm -p 50021:50021 voicevox/voicevox_engine:latest

インストール

• バイナリをダウンロードする場合

  • GitHub Releasesからビルド済みバイナリをダウンロードして配置してください。

• Homebrewを使う場合（macOS/Linux）:

  brew tap canpok1/tap
  brew install --cask vox-actor
  

• Goのinstallコマンドを使う場合

  go install github.com/canpok1/vox-actor@latest
  

• ソースからビルドする場合

  git clone https://github.com/canpok1/vox-actor.git
  cd vox-actor
  make build
  

バージョン確認

vox-actor --version

使い方

テキストの直接読み上げ

vox-actor say "こんにちは"

キャラクターや音声パラメータを指定する場合:

vox-actor say --speaker 3 --speed 1.2 "こんにちは"

テキストファイルの読み上げ

vox-actor act script.txt

VOICEVOXエンジンのURLやキャラクターを指定する場合:

vox-actor act --engine-url http://localhost:50021 --speaker 3 script.txt

話速・音高・抑揚を調整する場合:

vox-actor act --speed 1.2 --pitch 0.1 --intonation 1.5 script.txt

JSON台本モード（感情制御パラメータ付き）

.json ファイルを使うと、セリフごとにキャラクターや感情パラメータを指定できます:

{
  "text": "こんにちは",
  "speaker": 3,
  "speedScale": 1.2,
  "pitchScale": 0.1,
  "intonationScale": 1.5
}

vox-actor act script.json

text のみ必須で、他のパラメータは省略可能です。省略した場合はCLIオプションのデフォルト値が使われます。

ディレクトリを指定した場合、.txt と .json の両方が辞書順で読み上げられます。

ディレクトリ監視モード

ディレクトリを監視し、ファイルが配置されると自動的に読み上げます。処理済みファイルは監視ディレクトリ内の done/ サブディレクトリに移動されます。

vox-actor act --watch /path/to/watch-dir

処理済みファイルを done/ に移動する代わりに削除する場合:

vox-actor act --watch-delete /path/to/watch-dir

--watch と --watch-delete は同時に指定できません。

詳細ログを出力する場合:

vox-actor act --verbose script.txt

オプション一覧

act サブコマンド

オプション	環境変数	デフォルト値	説明
--engine-url	VOX_ENGINE_URL	http://localhost:50021	VOICEVOXエンジンのURL
--speaker	VOX_SPEAKER	3	キャラクターID
--speed	—	1.0	話速
--pitch	—	0.0	音高
--intonation	—	1.0	抑揚
--watch	—	false	ディレクトリ監視モードを有効化
--watch-delete	—	false	ディレクトリ監視モード（処理済みファイルを削除）
--verbose	—	false	詳細ログを出力

say サブコマンド

オプション	環境変数	デフォルト値	説明
--engine-url	VOX_ENGINE_URL	http://localhost:50021	VOICEVOXエンジンのURL
--speaker	VOX_SPEAKER	3	キャラクターID
--speed	—	1.0	話速
--pitch	—	0.0	音高
--intonation	—	1.0	抑揚
--verbose	—	false	詳細ログを出力

オプションの優先順位: CLIフラグ > 環境変数 > デフォルト値

活用方法

claude codeなどのLLMの作業状況を音声で通知する

LLMの作業状況を指定ディレクトリにテキストファイルとして出力し、vox-actorの監視モードで読み上げることで、作業の進捗を音声で把握できます。

claude code向けプラグインを同梱しているので、claude codeでは簡単に導入できます。

1. 環境変数を設定する。

   # テキストファイルの出力先ディレクトリを指定
   export VOX_ACTOR_WORKSPACE=/path/to/directory
   

2. vox-actorを監視モードで起動する。

   vox-actor act --watch $VOX_ACTOR_WORKSPACE
   

3. claude codeにプラグインを導入する。

   # claude code上で実行
   /plugin marketplace add canpok1/vox-actor 
   /plugin install vox-actor-plugin@monologue
   

4. 独り言スキル（monologue）を実行する。

   # claude code上で実行
   /monologue
   

開発

# セットアップ（linter等のインストール）
make setup

# ビルド
make build

# テスト
make test

# E2Eテスト
make test-e2e

# フォーマット
make fmt

# Lint
make lint

# 依存チェック
make depcheck

# ビルド成果物の削除
make clean

ライセンス

MIT License