scenario-audio

シナリオの音声生成

概要

Scenario は、画像と同じループで音声を生成します。現在のカタログには、3 つの生成カテゴリ（音楽、効果音、音声／音声読み上げ）に加え、動画からサウンドトラックを生成するモデルと音声ユーティリティが含まれています。接続方法と基本的な生成ループについては、scenario スキルを参照してください。ここで名前が挙がっている関連スキルが利用可能なスキルにない場合は、ユーザーにインストールを依頼してください （npx skills add scenario-labs/skills --skill <name>）。無人で処理を続ける場合は、ツールスキーマに基づいて進め、不足している点を明記してください。

クイックリファレンス

手順	ツール	メモ
モデルを探す	ユーザー自身の言葉で要件を伝えて recommend を使います。名前がわかっているモデルを探す場合に限り search を使います	capability="txt2audio" は音楽、SFX、TTS を対象とします。指定は任意で、省略した場合はプロンプトから推定されます
入力を確認する	model_schema_get	音声のスキーマは、長さ、歌詞、声、ループなどによって大きく異なります
生成する	model_run	スキーマに準拠したパラメーターを指定します。長時間のジョブでは wait=false を指定してください
待機する	jobs_wait	サーバー側で待機します。タイムアウトした場合は、保留中のジョブ ID を指定して再度呼び出してください
試聴する	asset_display	インラインの音声プレーヤーを表示します
保存する	asset_download	生成されたファイル（WAV、MP3 など）を保存します。mimeType で返される <ext> を使って curl -L -o out.<ext> "<url>" を実行してください。返されない場合は ffprobe を使います

既存の音声アセットを探すには、search の target="assets" と filters={kind: "audio"} を指定します。チームとプロジェクトのスコープ（team_id、project_id）については、scenario スキルを参照してください。

オーディオ機能の対象範囲

• 音楽：テキストから音楽を生成するモデルは、短いBGMやボーカル入りのフル尺の曲を生成します。曲のレーンには、以下に記載する独自の仕様があります。
• 効果音：テキストから効果音を生成するモデルは、説明から短いクリップを生成します。シームレスなループに対応しているものもあります。
• 音声とスピーチ：プリセット音声、多言語出力、感情やペースの制御に対応したテキスト読み上げです。短いクリップから音声をクローンするものもあり、音声間変換では録音の声を別の声に置き換えます。
• 動画から音声へ：無音の動画に楽曲を付けたり、同期した効果音を追加したりするモデルです。
• ユーティリティ：model_scenario-audio-cut、model_scenario-audio-split、model_scenario-audio-extract、model_scenario-compose-video（IDは固定です。各ツールはそれぞれの操作に対応するScenario唯一の決定的なツールであるため、検出しても同じIDを再特定するだけになります）。コンポジターは、scenario-video-assemblyに従って、完成したトラック（楽曲、ナレーション、声を置き換えた音声）をオーディオレイヤーとしてクリップに重ねます。音声からテキストへの文字起こしでは、ユーザー自身の言葉で要件を伝えてrecommendを使用します。
• ステム分離：実行ごとに指定したステムを1つ分離します（recommendで検出）。ボーカルも含まれますが、インストゥルメンタルを選択するオプションはありません。音声分離ではクリアな音声のみが返され、除去した音楽や効果音が2つ目のステムとして返されることはありません。そのため、2ステム分離（音声とそれ以外すべて）は対応していない機能として報告し、対応するツールを探し続ける必要はありません。

ファミリーごとの仕様：scenario-elevenlabs（スピーチ、吹き替え、声の置き換え、音楽、効果音）、scenario-ace-stepおよびscenario-minimax-music（曲）、scenario-sonilo（効果音と動画への楽曲付け）。

使用例：ゲームの効果音

1. capability="txt2audio"を指定し、promptにはユーザー自身の言葉（「ゲームの効果音：重い木製の宝箱がきしみながら開く」）を指定してrecommendを実行します。ランキングには、model_elevenlabs-sound-effects-v2などのtxt2audioモデルが表示されます（あくまで例です）。
2. そのmodel_idを指定してmodel_schema_getを実行します。プロンプトと、長さやループなどの制御項目を含む正確なフィールドが返されます。
3. 同じmodel_idを指定し、parameters={"prompt": "重い木製の宝箱がきしみながら開く、単発の音、ドライ、音楽なし"}としてmodel_runを実行します。
4. アセットなしで返されたjob_id（待機がタイムアウトした場合のin_progress、またはwait=false後のバックエンドによるqueuedまたはin-progress）について、job_ids=["job_xxx"]を指定してjobs_waitを実行します。タイムアウトした場合は、返されたpending_job_idsを指定して再度呼び出します。
5. asset_id="asset_xxx"を指定してasset_displayを実行し、インラインで再生します。
6. formatを指定せずにasset_downloadを実行し、返されたURLからmimeTypeに記載された拡張子でcurl -Lを使って保存します。

プロンプトのヒント：

• 効果音：音源、素材、動作、音響空間を指定し、含めないもの（「音楽なし」「残響なし」）も明記します。1クリップにつき1つの音にし、バリエーションは別々に生成します。
• 音楽：ジャンル、雰囲気、テンポ、楽器編成を指定します。短いBGMは通常、1つのプロンプトで生成でき、長さやループはスキーマで指定します。
• スピーチ：テキストフィールドには読み上げる言葉だけを入力します。声、言語、感情、ペースは、それぞれ別のスキーマフィールドまたはインラインタグで指定します。

音声と対話

recommend（capability="txt2audio"、ユーザーの言葉、2人の対話の場合は「two-person dialogue」）で音声メンバーを見つけ、その後 model_schema_get でそのメンバーのテキストフィールドの説明を確認します。通常、メンバー自身の読み上げ規則はそこに記載されています。

• タグの構文は、同じファミリー内でもメンバーごとに異なります：角括弧（[whispers]）、山括弧（<sigh>、<short pause>）、丸括弧（(sighs)）、または囲みタグのペア（<whisper>text</whisper>）があり、タグを読み取らないメンバーもいます。誤った構文のタグは音声で読み上げられることがあるため、テキストフィールドの説明にある綴りをそのまま使ってください。そこでタグが示されていない場合は、メンバーのカタログ説明または recommend の注記を参照し、どこにも記載がなければタグを使わないでください。綴りが正しいタグもリクエストにすぎず、必ず反映されるとは限りません。同じ設定で2回生成しても結果が異なった例があるため、最終版を確定する前にユーザーに聴いてもらい、タグが反映されなかったテイクは再生成してください。
• 2つの声を1つのテイクで。 マルチスピーカー配列を持つメンバー（作成時点では、話者ラベルと音声を組み合わせた行を最大2つ設定可能）は、テキストを順番に話者のターンとして読み上げます。各ターンは Name: line の形式で、Name は行のラベルと完全に一致させてください。話者名のない行は直前のターンに続き、シングルボイスのフィールドはこのモードでは無視されます。プリセット音声の名前から性別、年齢、声の調子は判断できないため、どのプリセットを誰に割り当てるかを明示し、有料実行の前にユーザーに確認してください。話者が2人を超えるシーンは、最大2人ずつのテイクに分割し、順番に再生するか、scenario-video-assembly に従って映像に重ねてください。
• テキストには上限があり、料金に影響します。 テキストフィールドには max_length が設定されています（作成時点で、あるメンバーは5000文字）。超過すると400エラーになり、cost_impact はそのフィールドが料金を左右することを示します。長い台本はターンの切れ目で分割し、最初のテイクを dry_run してください。
• スキーマに言語フィールドがある場合は、テキストで言語を指定するのではなく、そのフィールドで言語を固定してください。

ボーカル入りの楽曲

フルレングスの楽曲は、長い音楽ベッドとは異なります。また、楽曲のスキーマはこの分野のほかのものよりばらつきが大きいため、形式は model_schema_get で確認します。スタイルプロンプトと独立した歌詞シートを使う形式、歌詞とスタイルの両方を含む1つの文章プロンプトを使う形式、またはセクションごとにテキストとスタイルを指定する順序付き配列を使う形式があります。

• スタイルフィールドに歌詞を入れないでください。 スキーマで両者が分かれている場合、スタイルフィールドにはジャンル、ムード、テンポ、キー、ボーカルスタイル、楽器編成を記載し、歌詞フィールドには [Verse] や [Chorus] などのセクションタグで構成した歌詞を記載します。
• インストゥルメンタルと自動歌詞生成は、スキーマに用意されている場合はフラグで指定します。 文章でどちらかを依頼しても確実ではなく、フラグがない場合はテキストフィールドだけが指定手段です。再実行時にインストゥルメンタルのフラグを切り替えると、同じ楽曲ではなく別のテイクになります。モデルに seed がある場合も、同じ設定で同一の結果を繰り返すだけです。すでにあるトラックのインストゥルメンタル版が必要な場合は、recommend で見つけた audio2audio のカバーモデルを試してください。すべてのモデルにフラグがあるわけではないため、スキーマを確認してください。
• テキストフィールドには、モデルごと、フィールドごとに文字数上限があります。 超過した場合、切り詰められるのではなく400エラーになります。

スキーマに長さと料金の両方に上限を設ける duration フィールド（cost_impact の指定あり）がある場合は、そのフィールドで両方が制限されます。そのようなフィールドがない場合は、歌詞シートまたはプロンプトが両方を決めます。いずれの場合も、実行を確定する前に dry_run: true で楽曲の料金を確認し、その後 wait: false で実行してください。どちらも model_run の引数であり、parameters のキーではありません。

再現性とバッチ処理の可否は分野全体ではなくメンバーごとに異なります。作成時点では、リペイント用メンバーは numOutputs（1～4）を受け取り、seed はありませんでした。そのため、同じ歌手を維持する必要があるリペイントはバッチで実行し、その中から選びます。一方、セクション作曲用メンバーには seed があり、numOutputs はありません。どちらかを約束する前に、model_schema_get で両方を確認してください。

曲を延長する

既存のトラックを長くする場合は、より長いテキストから音楽を生成するのではなく、独立した audio2audio のレーンを使います。 ユーザーの言葉で延長の要件を指定して、capability="audio2audio" で recommend を実行します。メンバーの名前がすでに分かっている場合に限り、search を使います。対応するメンバーには曲を audio として渡し、順序付きの sections 配列を渡します（作成時点で最大30個）。各要素では、元の音源の一部を残す（sourceStartSeconds と sourceEndSeconds）か、新しいセクションを生成します（[Verse] 形式のタグを含む text、durationSeconds、配列形式の positiveStyles）。新しいセクションが隣接するセクションにどれほど近づくかは、contextAdherence で決まります。残す部分にも、同じ長さの生成音声と同様に料金がかかるため、まず計画全体を dry_run してください。リペイント、編集、レイヤー追加の各メンバーは元の長さの範囲内で再生成するため、曲を延長することはありません。また、作成時点で「曲を延長する」という要件に対して、recommend は古いテキストから音楽を生成するメンバーを上位にランク付けしました。延長は txt2audio の要件ではないため、その候補は選ばないでください。

よくある間違い

• 生成モデルのIDをハードコードする：利用可能なモデルはチームごとに異なり、変化します。セッションごとに再検出し、要件に応じて recommend を使うか、名前で search してください。上記の固定されたファーストパーティのツールIDだけは変わりません。
• model_schema_get を省略する：あるオーディオモデルのパラメーターは、別のモデルには適合しません（音声、長さ、歌詞のフィールドはそれぞれ異なります）。
• ループ内で job_get をポーリングする：音楽生成ジョブには数分かかることがあります。jobs_wait を使い、タイムアウトした場合は pending_job_ids を指定して再度呼び出してください。
• アセットのURLをそのままチャットに貼り付ける：asset_display を使って音声を再生してください。
• 音声用の asset_download に format を渡す：これは画像形式のみを変換するため、省略してください。WAVは生成時に、メンバーのスキーマに出力形式のフィールドがある場合はそのフィールドで指定します。
• TTSテキストに音声の指示を入れる（「怒って言う」など）：その指示まで読み上げられることがあります。スキーマの感情フィールドまたは音声フィールドを使ってください。
• 1つの音声で両方のパートを読む会話文を書く：複数話者に対応したメンバーでは、話者の行を埋め、各ターンの先頭にラベルを付けてください。行が空だと、メンバーはすべてを1つの音声で読み上げます。
• 歌詞をスタイルフィールドに貼り付ける：モデルは歌うのではなく、曲について説明するようになります。
• 「長くして」という要望にリペイントや新しいテキストから音楽を生成する実行で応える：前者では長さが変わらず、後者では元の曲が失われます。上記の延長レーンなら、ユーザーが選んだセクションを維持できます。
• parameters 内に dry_run または wait を入れる：これらは model_run 自体の引数です。誤って dry_run を入れても課金され、誤って wait を入れると最大180秒間ブロックされます。