voicestudio

VoiceStudio

ユーザーが実行中の VoiceStudio バックエンドを使用します。ローカル処理を優先してください。クラウド翻訳、モデルのダウンロード、リモートバックエンドへの接続、外部連携にはユーザーの選択が必要です。インストール済みのモデルはオフラインで実行できますが、設定されたすべてのワークフローがオフラインで利用できるとは限りません。

接続と検出

デフォルトのバックエンドは http://localhost:3900 です。ユーザーが設定したアドレスを使用してください。Electron のレンダラーと開発用プロキシは別個のサービスであり、公開バックエンド API ではありません。

1. GET /health を確認します。
2. 実行中のバージョンの API 仕様を GET /openapi.json で、音声とエンジンを GET /v1/audio/voices で検出します。プロファイル ID をでっち上げたり、カタログの一覧からインストール済みモデルを推測したりしないでください。
3. 利用できない場合は、インストール済みアプリを起動します。既存のソースチェックアウトがある場合は、その Electron README に従ってください（リポジトリのルートから bun install、bun run setup:api、その後 bun run dev を実行します）。2 つ目のバックエンドをインストールしたり、既存のチェックアウトを上書きしたりしないでください。
4. ローカル設定では認証なしの呼び出しが許可される場合がありますが、保護されたデプロイ環境では設定済みの認証情報が必要です。401/403 は認証エラーとして扱い、認証を無効にする根拠にしないでください。トークンを表示したり、プレースホルダーのキーを実際の認証情報として使用したりしないでください。

音声を生成する

この JSON を speech-request.json に保存し、ユーザーが音声を選択した場合は、voice を検出したプロファイル ID に置き換えます。

{"model":"tts-1","voice":"alloy","input":"Every voice has a story. Let's tell yours.","response_format":"wav"}

curl --fail-with-body --show-error http://localhost:3900/v1/audio/speech \
  -H 'Content-Type: application/json' --data-binary @speech-request.json \
  --output speech.wav

tts-1 と tts-1-hd はエイリアスであり、品質を保証するものではありません。OpenAI の音声名は互換性のためのエイリアスであり、各プロバイダーの実際の音声名ではありません。繰り返し使うナレーションでは、検出した保存済みの音声を優先してください。結果を保証する前に、インストール済みエンジンが対応する言語と音声設計機能を確認してください。

HTTP ステータスを確認し、出力をデコードまたはプローブしてから音声として扱ってください。エラーレスポンスが出力先に書き込まれる場合があります。保存先のパスと実際の長さ・形式を報告してください。生成の成功、文字起こし、ジョブの完了を捏造しないでください。

文字起こし

curl --fail-with-body --show-error http://localhost:3900/v1/audio/transcriptions \
  -F [email protected] -F model=whisper-1 -F response_format=verbose_json

プレーンな文字起こしには json または text、タイムスタンプには verbose_json、字幕には実行中のスキーマが対応している場合に srt／vtt を使用します。長時間の録音を処理する前に、文字起こしモデルが利用可能か確認してください。モデルがない場合は、そのことを説明し、黙ってインストールするのではなく、ダウンロードの許可を得てください。

音声のクローン、設計、吹き替え、長時間のワークフロー

インストール済みの OpenAPI スキーマを使用して、プロファイルの作成、参照音声のアップロード、生成、吹き替え、長時間ジョブの操作を検出します。これらのネイティブエンドポイントは OpenAI 互換 API より広範で、互いに独立して変更されます。

• ユーザーに使用権限がある音声だけをクローンします。参照ファイルと既存のプロファイルは保持してください。
• 音声を設計する場合は、希望するトーン、話し方、言語、サンプルテキストを把握し、エンジンが対応しているか確認します。
• 吹き替えでは、元のメディア、話者の割り当て、セグメントのタイミング、背景音声の意図を保持します。翻訳が完了しても、吹き替えのレンダリングが完了したとは限りません。
• 非同期処理では、返されたジョブ ID と文書化された進捗・ステータスエンドポイントを使用します。最終エラーを確認し、タイムアウトした生成をむやみに再送信しないでください。
• 使用可能なファイルと、モデルの不足や利用できない機能を含む正直な制限事項を提示してください。

MCP と自動化

実行中のバックエンドは、http://localhost:3900/mcp に MCP エンドポイントをマウントします。クライアントがサポートする HTTP トランスポートを使用し、実行時にツールを検出してください。別のサービスを起動するのではなく、既存の接続を再利用してください。stdio のみをサポートするクライアントについては、プロジェクトの MCP ガイドで shim を確認してください。

n8n、エージェント、コンテナ、その他のホストから呼び出す場合は、その環境からバックエンドのアドレスに到達できるようにしてください。コンテナ内の localhost は、そのコンテナ自体を指します。認証と明示的なリモートルーティングの選択はそのまま維持してください。インテグレーションディレクトリに一覧があるからといって、そのインテグレーションが接続済みであるとは限りません。

エラーが発生した場合は、レスポンス本文を読み、バックエンドが利用できない場合、モデルが見つからない場合、機能がサポートされていない場合、認証エラー、ハードウェアがビジー状態の場合を区別してください。報告された状態を修正してください。許可なくホスト型プロバイダーに切り替えたり、モデルをダウンロードしたりしないでください。

デスクトップのワークフローと準備状況

Electron アプリには、音声クローンとデザイン、保存済みのプロファイルとギャラリー、ストーリー／オーディオブック、吹き替えプロジェクト、文字起こし、ツール、インテグレーションが含まれています。 重複を作成するよりも、既存のプロジェクト ID と音声 ID を優先してください。 デスクトップを自動化する場合は、実際の UI と現在の Settings のショートカットを確認してください。ホストごとにショートカットの割り当てやマイクのアクセス許可が同じだとは限りません。

音声入力の前に、音声認識モデルがインストールされていることと、入力デバイスが動作することを確認してください。録音中、一時停止中、文字起こし処理中、テキスト完成済みの状態を区別してください。文字起こしのコピーと別のアプリへの挿入は異なる操作です。入力前に意図された対象を確認し、可能な場合はクリップボードの内容を保持してください。文字起こしが完了しただけで、テキストが送信されたと報告してはいけません。

吹き替えでは、書き出しの前に欠落または失敗したセグメントと、タイミングの超過を確認してください。求められた場合は音楽と音声以外の音を保持し、サウンドトラック全体を黙って置き換えないでください。ソースを保持し、出力は別の成果物として作成してください。翻訳スタイルのプロンプトは、選択した翻訳操作に適用されます。また、リモートエージェントによる翻訳では、ユーザーが設定したプロバイダーの選択が必要です。

インテグレーションディレクトリは、インテグレーションの検出と設定の手引きとして利用してください。コネクターが動作している証拠として扱わないでください。接続準備完了と説明する前に、実際の認証情報、エンドポイントへの到達性、サポートされる操作を確認してください。コンテナでのデプロイには、永続データボリュームと、呼び出し元のクライアントから到達可能なバックエンド URL が必要です。