オーディオデザインガイド

これは単一のレシピではなく、Yuminaのオーディオシステムを使って完全なサウンドスケープを作るためのテクニック集です：シーン変更に追従するBGM、キーワードでトリガーする効果音、ループするアンビエント、滑らかなクロスフェード、カスタムUIとAIナレーションからミュージックをコントロールするあらゆる方法。

概要

Yuminaのオーディオシステムには、異なるレベルでサウンドをコントロールする複数のエントリポイントがあります：

コントロール方法	設定場所	特徴
プレイリスト自動再生	Audio タブ	最もシンプル — プレイヤーがワールドに入るとすぐにBGMが再生開始
条件付きBGM	Audio タブ	変数/キーワード/ターン数の条件が満たされると自動的にトラックを切り替え、ビヘイビア不要
ビヘイビア + Play Audio アクション	Behaviors タブ	シーン遷移時のクロスフェード、変数変更とエントリ切り替えを組み合わせ
AIオーディオディレクティブ	AIが返信内に`[audio: ...]`を書く	AIが何をいつ再生するか決める — 最も柔軟、しかし最も予測しにくい
Root ComponentオーディオAPI	Custom UI セクション	カスタムボタンからトリガー、ジュークボックススタイルのインタラクティブUIに最適

このガイドでは7つのパターンを1つずつカバーします。必要なものを選ぶか、組み合わせてください。

パターン1：基本的なBGMセットアップ

これから作るもの

プレイヤーがワールドに入った瞬間に再生開始するBGM — ループ、追加設定不要。

ステップバイステップ

ステップ1：オーディオトラックをアップロード

エディタ → Audio タブ → 「Add Track」をクリック

フィールド	値	理由
Display Name	Main Theme	自分用の識別名
ID	`main_theme`	すべての参照でこのIDを使用
Type	BGM	バックグラウンドミュージック
Audio File	`.mp3` または `.ogg` ファイルをアップロード	一般的なオーディオフォーマットをサポート
Loop	On	BGMは通常ループが必要
Volume	`0.7`	大きすぎないように — SFXとアンビエントの余地を残す
Fade In	`2` 秒	段階的にフェードインして不快感を避ける

複数のトラックが欲しい？上記のステップを繰り返して追加のトラックを作成 — 例：explore_bgm（探索）、battle_bgm（戦闘）、town_bgm（町）。

ステップ2：プレイリストを設定

引き続きAudioタブで、「BGM Playlist」セクションを見つけます：

フィールド	値	理由
Track List	`main_theme`を選択（複数ある場合はすべて選択）	リスト内のトラックが順番に再生
Play Mode	`loop` または `shuffle`	`loop` = 順番に再生、繰り返し；`shuffle` = ランダム化
Autoplay	On	プレイヤーがワールドに入るとミュージックが開始
Wait for First Message	Off（または好みでOn）	Onにすると、プレイヤーが最初のメッセージを送るまでミュージックが待機
Gap Seconds	`0`（または `2`）	トラック間のポーズ；`0` = シームレスな遷移

結果

プレイヤーがワールドに入る → ミュージックが自動的に開始（2秒のフェードイン付き） → 1つのトラックが終わると次が開始 → 最後のトラック後、最初にループバック。

BGMトラックが1つしかない？

1曲だけならそのトラックのloopをオンにしてプレイリストに単独で入れます。プレイリストを完全にスキップして、代わりに条件付きBGMやAIディレクティブで制御することもできます。

パターン2：シーン遷移時のクロスフェードBGM

これから作るもの

プレイヤーが「Village」から「Dungeon」に移動するとき、村の穏やかな音楽が徐々にフェードアウトし、ダンジョンの不気味な音楽がフェードインします — 両方のトラックが短い重なりで同時に再生され、遷移をスムーズで映画的にします。

仕組み

プレイヤーが「Go to Dungeon」ボタンをクリック
  → ビヘイビアが発火：変数 location = "dungeon" に設定
  → 同じビヘイビアのPlay Audioアクション：dungeon_bgmにクロスフェード
  → 古いトラックがフェードアウト + 新しいトラックがフェードイン、遷移期間2秒

ステップバイステップ

ステップ1：オーディオトラックを準備

Audioタブで、2つ（またはそれ以上）のBGMトラックを作成：

village_bgm — 村の音楽、タイプ BGM、ループオン
dungeon_bgm — ダンジョンの音楽、タイプ BGM、ループオン

village_bgmをデフォルトトラックとしてプレイリストに入れ、自動再生をオンに。

ステップ2：変数を作成

エディタ → Variables タブ → Add Variable

フィールド	値
Display Name	Current Location
ID	`location`
Type	String
Default Value	`village`

ステップ3：ビヘイビアを作成

エディタ → Behaviors タブ → Add Behavior

ビヘイビア名： Go to Dungeon

トリガー： Action → アクションID：go-dungeon

アクション（順番に）：

#	Action Type	設定	目的
1	Set Variable	`location`を`dungeon`に設定	プレイヤーがダンジョンに行ったことを記録
2	Play Audio	トラック`dungeon_bgm`、オペレーション：`crossfade`、フェード期間 `2` 秒	滑らかなトラック切り替え
3	Enable Entry	Dungeon Atmosphere	ダンジョンのロアをオン
4	Disable Entry	Village Atmosphere	村のロアをオフ

逆の動作（village_bgmにクロスフェード、エントリトグルを入れ替え）を行うアクションID go-village の「Return to Village」ビヘイビアを作成。

ステップ4：Root Componentからトリガー

Root Componentのindex.tsx内（<Chat renderBubble>コールバック内、または任意のカスタムボタン上）でexecuteActionを呼び出します：

tsx

<button onClick={() => api.executeAction("go-dungeon")}>
  Go to Dungeon
</button>

ビヘイビアはすべてのアクションを順番に実行 — 変数を変更し、ミュージックを切り替え、エントリをトグルし — すべて1回のボタンクリックから。

クロスフェードとは？ クロスフェード — 古いトラックが徐々に静かになり、新しいトラックが徐々に大きくなる。両方のトラックが短期間同時に再生され、突然のカットではなく映画のシーン遷移のように聞こえます。フェード期間2〜3秒がうまく機能します。

パターン3：キーワードトリガー効果音

これから作るもの

AIが「explosion」と書くと爆発音が自動的に再生。プレイヤーが「open the door」と言うとドアのきしむ音が再生。ビヘイビア不要 — Audioタブの条件付きBGMセクションで直接設定します。

仕組み

条件付きBGMにはai-keyword（AIキーワード）とkeyword（プレイヤーキーワード）というトリガータイプがあります。エンジンが各メッセージのテキストをスキャンし、キーワードが一致すると対応するトラックを再生します。「条件付きBGM」という名前ですが、任意のトラックタイプ — SFXを含む — を指せます。

ステップバイステップ

ステップ1：SFXトラックを作成

Audioタブで効果音トラックを作成：

爆発SFX：

フィールド	値
Display Name	Explosion
ID	`explosion_sfx`
Type	SFX
Loop	Off（効果音は通常1回だけ再生）
Volume	`0.9`

ドア開きSFX：

フィールド	値
Display Name	Door Open
ID	`door_open_sfx`
Type	SFX
Loop	Off
Volume	`0.8`

ステップ2：条件付きBGMルールを作成

引き続きAudioタブで、「Conditional BGM」セクションを見つけ → 「Add Rule」をクリック

ルール1：AIが「explosion」と言ったらSFXを再生

フィールド	値	理由
Name	AI Explosion SFX	自分用の識別名
Trigger Type	AI Keyword (`ai-keyword`)	AIの返信に指定されたキーワードが含まれると発火
Keywords	`explosion`, `blast`, `detonate`	複数の同義語を追加可能 — いずれか1つに一致でトリガー
Target Track	`explosion_sfx`	爆発音を再生
Stop Current BGM	Off	SFXはBGMの上にレイヤー — ミュージックを止めない

ルール2：プレイヤーが「open the door」と言ったらSFXを再生

フィールド	値	理由
Name	Player Door SFX	自分用の識別名
Trigger Type	Player Keyword (`keyword`)	プレイヤーのメッセージに指定されたキーワードが含まれると発火
Keywords	`open the door`, `push the door`, `open door`	複数の同義語
Target Track	`door_open_sfx`	ドアの音を再生
Stop Current BGM	Off	同上

結果

AIが書く：「BOOM — a deafening explosion rocks the hillside, fire lighting up the entire sky.」
  → エンジンがスキャンして「explosion」に一致 → 自動的にexplosion_sfxを再生
  → プレイヤーはBGMが再生し続ける中で爆発音を聞く

プレイヤーがタイプ：「I walk to the door and open it.」
  → エンジンがスキャンして「open the door」に一致 → 自動的にdoor_open_sfxを再生

SFX vs BGM

SFX（効果音）は1回再生して停止します。BGM（バックグラウンドミュージック）はプレイリストに従ってループまたは継続します。条件付きBGMルールがSFXタイプのトラックをターゲットにすると、1回再生され、現在のバックグラウンドミュージックを置き換えません。ただし、stopPreviousBGMがtrueに設定されている場合、トラックを再生する前に現在のBGMを停止します — SFXには通常不要です。

パターン4：条件付きBGM — 変数駆動の自動切り替え

これから作るもの

ビヘイビア不要 — Audioタブで直接ルールを設定：hpが20を下回ると緊張感のあるクライシスミュージックに自動的に切り替え、hpが20を超えるとデフォルトトラックに戻す。

仕組み

条件付きBGMのvariableトリガータイプは、変数変更のたびに自動的にチェックします。条件満足 → ターゲットトラックに切り替え；条件不満足 → fallback設定に基づいてフォールバック（プレイリストのデフォルトトラックに戻る、または以前再生していたトラックに戻る）。

ステップバイステップ

ステップ1：オーディオトラックを準備

Audioタブに以下があることを確認：

explore_bgm — デフォルトの探索ミュージック（プレイリスト内）
crisis_bgm — クライシスミュージック（条件がトリガーされたときのみ再生；プレイリストに入れる必要なし）

ステップ2：条件付きBGMルールを作成

Audioタブ → Conditional BGM → Add Rule

フィールド	値	理由
Name	Low HP Crisis Music	自分用の識別名
Trigger Type	Variable (`variable`)	変数値に基づいて決定
Condition	`hp` < `20`	HPが20を下回るとトリガー
Condition Logic	All (`all`)	ここでは1つの条件のみ、`all`と`any`は同じ動作
Target Track	`crisis_bgm`	クライシスミュージックに切り替え
Priority	`10`	複数のルールが同時に一致した場合、優先度が高い方が勝つ
Fade In Duration	`1` 秒	新しいトラックが徐々にフェードイン
Fade Out Duration	`1` 秒	古いトラックが徐々にフェードアウト
Stop Current BGM	On	クライシスミュージック再生前に探索ミュージックを停止
Fallback	`default`	条件が満たされなくなったとき（HPが20を超えたとき）、自動的にプレイリストのデフォルトトラックに戻る

結果

プレイヤーが探索中、BGMはexplore_bgm
  → AIが返信：[hp: -15]（hpが30から15に低下）
  → エンジンがhp < 20を検出、条件満足
  → explore_bgmが1秒でフェードアウト、crisis_bgmが1秒でフェードイン
  → 雰囲気が瞬時に緊張する

プレイヤーが回復ポーションを使用
  → AIが返信：[hp: +20]（hpが15から35に戻る）
  → エンジンがhpがもう < 20ではないことを検出、条件不満足
  → fallback: "default" → 自動的にexplore_bgmに戻る

複数条件の組み合わせ

1つのルールに複数の条件を追加できます。例：hp < 20 AND location == "dungeon" → ダンジョンにいてHPが低いときだけクライシスミュージックを再生。条件ロジックをall（すべてが一致）に設定します。

パターン5：アンビエントサウンドループ

これから作るもの

シーンの背景で継続的に再生されるアンビエントサウンド — 雨、風、酒場のざわめき — BGMの上にレイヤーされて没入感を深めます。

仕組み

Ambientは3番目のトラックタイプです。BGMとは独立して再生されます — BGMトラック + アンビエントトラックを同時に再生できます。アンビエントは通常、低音量でループに設定され、常時の雰囲気的なバックドロップとして機能します。

ステップバイステップ

ステップ1：Ambientトラックを作成

Audio タブ → Add Track

フィールド	値
Display Name	Rain
ID	`rain_ambient`
Type	Ambient
Loop	On
Volume	`0.3`（アンビエントはBGMより静かであるべき — バックドロップ）
Fade In	`3` 秒（徐々に現れ、不快感がない）
Fade Out	`3` 秒

必要に応じてさらに作成：wind_ambient（風）、tavern_ambient（酒場のざわめき）、forest_ambient（鳥のさえずりと虫の音）。

ステップ2：条件付きBGMでアンビエントを制御

パターン4と同じ — 条件付きBGMルールを使用してアンビエントの再生タイミングを制御します。

ルール：森にいるときに森のアンビエントを再生

フィールド	値
Name	Forest Ambient
Trigger Type	Variable (`variable`)
Condition	`location` == `forest`
Target Track	`forest_ambient`
Stop Current BGM	Off
Fallback	`default`

重要：stopPreviousBGMはOffでなければなりません。 アンビエントはBGMの上にレイヤー — バックグラウンドミュージックを止めるべきではありません。オンにすると、アンビエントトラックの切り替えで現在再生中のBGMも停止します。

ビヘイビア経由でアンビエントを制御することも可能

すでにシーン切り替えビヘイビアがある場合（パターン2のように）、ビヘイビアのアクションリストにアンビエントトラックをターゲットにする「Play Audio」アクションを追加するだけです：

#	Action Type	設定	目的
1	Set Variable	`location`を`forest`に設定	場所を記録
2	Play Audio	`forest_bgm`、オペレーション：crossfade、フェード 2s	BGMを切り替え
3	Play Audio	`forest_ambient`、オペレーション：play、フェードイン 3s	アンビエントサウンドをレイヤー
4	Play Audio	`tavern_ambient`、オペレーション：stop、フェードアウト 3s	古いアンビエントを停止

これで、1つのビヘイビアがBGM切り替えとアンビエントスワップの両方を処理します。

ボリュームの推奨値

BGM：通常0.5-0.7。Ambient：0.2-0.4。SFX：0.7-1.0。これら3つのレイヤーを異なるレベルで配置すると、互いに衝突しません。

パターン6：Root Componentからオーディオを制御

これから作るもの

Root Component内の「ジュークボックス」 — それぞれが異なるトラックを再生するボタンがいくつかと、「Stop」ボタン。これは純粋なUI制御 — ビヘイビアや条件付きルール不要。

仕組み

useYumina()は以下のオーディオAPIを提供します（durationはすべて秒単位）：

api.playAudio?.(trackId, opts) — 指定されたトラックを再生。optsにはvolume、fadeDuration、chainTo、maxDuration、duckBgm、そしてloop（このトラックの loop 設定を今回の再生だけ上書きする）を含められる
api.stopAudio?.(trackId?) — 指定されたトラックを停止（IDを省略するとすべて停止）。要素を破棄する — 後で再開したい場合はpauseAudioを使う
api.pauseAudio?.(trackId) / api.resumeAudio?.(trackId) — その場で一時停止/再開（位置を保持）
api.onAudioEnded?.(cb) — ループしないトラックの再生終了時にcb(trackId)を実行；解除用の関数を返す。自動次曲送りに使う：

tsx

React.useEffect(() => api.onAudioEnded?.((endedId) => {
  if (endedId === currentTrackId && mode !== "single") playNext();
}), [currentTrackId, mode]);

これらのメソッドはRoot Componentのindex.tsx内で直接呼び出せます（<Chat renderBubble>コールバック内、または追加した任意のボタン上）。

ステップバイステップ

ステップ1：オーディオトラックを準備

Audio タブに再生したいトラックがあることを確認します（パターン1のように作成）。たとえば、以下があるとします：

jazz_bgm — ジャズ
rock_bgm — ロック
classical_bgm — クラシック

ステップ2：Root Componentコードを書く

エディタ → Custom UI セクション → index.tsxを開く → 以下を貼り付け（デフォルトのreturn <Chat />を置き換え）：

tsx

export default function MyWorld() {
  const api = useYumina();
  const msgs = api.messages || [];

  const tracks = [
    { id: "jazz_bgm", label: "Jazz", color: "#7c3aed" },
    { id: "rock_bgm", label: "Rock", color: "#dc2626" },
    { id: "classical_bgm", label: "Classical", color: "#0891b2" },
  ];

  return (
    <Chat renderBubble={(msg) => {
      const isLastMsg = msg.messageIndex === msgs.length - 1;
      return (
    <div>
      <div
        style={{ color: "#e2e8f0", lineHeight: 1.7 }}
        dangerouslySetInnerHTML={{ __html: msg.contentHtml }}
      />

      {isLastMsg && (
        <div style={{
          marginTop: "12px",
          padding: "12px",
          background: "rgba(30,41,59,0.5)",
          borderRadius: "8px",
          border: "1px solid #334155",
        }}>
          <div style={{ fontSize: "12px", color: "#94a3b8", marginBottom: "8px" }}>
            Jukebox
          </div>
          <div style={{ display: "flex", gap: "8px", flexWrap: "wrap" }}>
            {tracks.map((t) => (
              <button
                key={t.id}
                onClick={() => api.playAudio?.(t.id, { fadeDuration: 1.5 })}
                style={{
                  padding: "8px 16px",
                  background: t.color,
                  border: "none",
                  borderRadius: "6px",
                  color: "#fff",
                  fontSize: "13px",
                  cursor: "pointer",
                }}
              >
                {t.label}
              </button>
            ))}
            <button
              onClick={() => api.stopAudio?.()}
              style={{
                padding: "8px 16px",
                background: "#475569",
                border: "none",
                borderRadius: "6px",
                color: "#e2e8f0",
                fontSize: "13px",
                cursor: "pointer",
              }}
            >
              Stop
            </button>
          </div>
        </div>
      )}
    </div>
      );
    }} />
  );
}

行ごとの解説：

MyWorld()はRoot Component — ワールドのUIエントリポイント。<Chat renderBubble={...} />はメッセージリスト、入力、スクロールをプラットフォームに任せ、バブルごとのレイアウトのみカスタマイズ
api.playAudio?.(t.id, { fadeDuration: 1.5 }) — 1.5秒のフェードインで指定されたトラックを再生。別のトラックが現在再生中の場合、自動的に最初に停止
api.stopAudio?.() — 引数なしで呼ぶ = 現在再生中のすべてのオーディオを停止
msg.messageIndex === msgs.length - 1 — ジュークボックスを最後のメッセージにのみ表示、各メッセージで繰り返さない

より高度な使い方

変数を読み取ってUI状態を制御できます。例えば、now_playing変数を使って現在のトラックIDを追跡し、ボタンに「Now Playing」インジケータを表示：

tsx

const nowPlaying = String(api.variables.now_playing || "");

// 再生と一緒に変数を更新
onClick={() => {
  api.playAudio?.(t.id, { fadeDuration: 1.5 });
  api.setVariable("now_playing", t.id);
}}

// ボタンにステータスを表示
{nowPlaying === t.id ? "♪ " + t.label : t.label}

パターン7：AI駆動のオーディオ制御

これから作るもの

AIにナレーション中に自然にミュージックを制御させます — 酒場に入るシーンを描写するときに陽気なアコーディオン曲を再生、戦闘が始まるときに激しいバトルBGMに切り替え、キャラクターが負傷したときに痛みの効果音を再生。

仕組み

AIは返信内に[audio: trackId action]ディレクティブを埋め込めます。エンジンはこれらのディレクティブを自動的に認識して実行し、プレイヤーが見るテキストからは取り除きます — 観客は読まないが、スタッフは従う、映画の台本のト書きのようなものです。

ステップバイステップ

ステップ1：AIが使う可能性のあるすべてのトラックを登録

Audio タブで、AIに制御させたいすべてのトラックを作成：

tavern_bgm — 酒場の音楽
battle_bgm — 戦闘の音楽
sword_clash_sfx — 剣のぶつかる効果音
pain_sfx — 痛み/負傷の効果音
rain_ambient — 雨のアンビエント

ステップ2：システムプロンプトでAIに利用可能なトラックを伝える

AIは登録したトラックを自動的には知りません。利用可能なトラックと使用ルールをリストするEntriesタブのエントリを作成する必要があります：

エントリ名： Audio Directive Reference

セクション： System Presets

内容：

[Audio Control System]
You can use the following audio directives in your replies to control music and sound effects. Directives are automatically executed and stripped from the text the player sees.

Available directive formats:
- [audio: trackId play] — play
- [audio: trackId play 2.0] — play with a 2-second fade-in
- [audio: trackId stop] — stop
- [audio: trackId stop 1.5] — stop with a 1.5-second fade-out
- [audio: trackId crossfade 2.0] — crossfade transition, 2-second overlap
- [audio: trackId volume 0.5] — adjust volume to 0.5
- [audio: trackId play chain:nextTrackId] — after this track finishes, automatically start the next one

Available tracks:
- tavern_bgm — lively tavern accordion music (good for social scenes, shopping)
- battle_bgm — intense battle music (good for combat, chase scenes)
- sword_clash_sfx — sword clash sound effect (good for melee action descriptions)
- pain_sfx — pain/injury sound effect (good for when a character gets hurt)
- rain_ambient — rain ambient sound (good for rainy scenes)

Usage guidelines:
- Insert audio directives at natural narrative points
- Use crossfade for scene transitions, with a duration of 1.5-2.5 seconds
- Pair sound effects with action descriptions, placing them near the corresponding text
- Don't overdo it — 2-3 audio directives per response at most

ステップ3：AI応答の例

AIにこれらのルールを伝えた後、返信はこのようになる可能性があります：

You push open the tavern's heavy wooden door, and a rush of warm air hits your face. [audio: tavern_bgm crossfade 2.0]

The tavern is buzzing — someone's playing accordion in the corner, and a dwarf at the bar is shouting over a dice game. You've barely found a seat when a masked figure suddenly draws a blade and lunges at you!

[audio: battle_bgm crossfade 0.5] [audio: sword_clash_sfx play]

You throw yourself sideways on instinct. The table splits in two behind you.

プレイヤーはクリーンなナラティブテキストを見ながら、酒場のミュージックがフェードイン → バトルミュージック + 剣のぶつかる効果音への突然の切り替えを聞きます。

`chain`ディレクティブ — 特別な使い方

chainは、1つのトラックが終了したときに自動的に別のトラックを開始できます：

The sound of war horns echoes through the valley — the battle is about to begin! [audio: war_horn_sfx play chain:battle_bgm]

war_horn_sfxの角笛のブラストが再生終了すると、battle_bgmが自動的に開始 — 直接切り替えるよりも儀式的な、メイントラックへのイントロです。

AIがディレクティブを使うのを忘れる可能性

AIは常にオーディオディレクティブを挿入することを覚えているわけではありません、特に長い会話では。重要なシーンBGM変更（戦闘ゾーンに入るなど）には、フォールバックとして条件付きBGMルール（パターン4）を設定してください。AIディレクティブはケーキの上のアイシング；条件付きBGMはセーフティネットです。

総合クイックリファレンス

トラックタイプ

タイプ	用途	典型的な設定
BGM	バックグラウンドミュージック	ループオン、ボリューム0.5-0.7
SFX	ワンショット効果音	ループオフ、ボリューム0.7-1.0
Ambient	ループするアンビエントサウンド	ループオン、ボリューム0.2-0.4

オーディオを制御する5つの方法

やりたいこと	どの方法	設定場所
ワールドに入ったときにBGMを自動再生	プレイリスト + 自動再生	Audio タブ → BGM Playlist
変数条件が満たされたらトラックを自動切り替え	条件付きBGM（variableトリガー）	Audio タブ → Conditional BGM
AI返信にキーワードが含まれたらSFX再生	条件付きBGM（ai-keywordトリガー）	Audio タブ → Conditional BGM
プレイヤーメッセージにキーワードが含まれたらSFX再生	条件付きBGM（keywordトリガー）	Audio タブ → Conditional BGM
特定のターン番号でトラックを切り替え	条件付きBGM（turn-countトリガー）	Audio タブ → Conditional BGM
シーン遷移時のクロスフェード	ビヘイビア + Play Audio アクション	Behaviors タブ
ボタンクリックから再生/停止	Root Component `api.playAudio?.()` / `api.stopAudio?.()`	Custom UI セクション
AIがナレーション中にオーディオをトリガー	AIオーディオディレクティブ `[audio: trackId action]`	Entries タブ（AIにルールを伝える）

AIオーディオディレクティブリファレンス

ディレクティブ	効果
`[audio: trackId play]`	再生
`[audio: trackId play 2.0]`	2秒のフェードインで再生
`[audio: trackId stop]`	停止
`[audio: trackId stop 1.5]`	1.5秒のフェードアウトで停止
`[audio: trackId crossfade 2.0]`	クロスフェード遷移、2秒の重なり
`[audio: trackId volume 0.5]`	ボリュームを調整
`[audio: trackId play chain:nextId]`	終了後、次のトラックを自動開始

条件付きBGMトリガータイプ

トリガータイプ	発火タイミング	典型的な用途
`variable`	変数条件が満たされたとき	hp < 20 でクライシスミュージック再生
`ai-keyword`	AI返信にキーワードが含まれたとき	AIが「explosion」と書くと爆発SFX再生
`keyword`	プレイヤーメッセージにキーワードが含まれたとき	プレイヤーが「perform」と言うとミュージック再生
`turn-count`	特定のターンに達したとき	ターン10でカウントダウンミュージック再生
`session-start`	セッションが開始したとき	固定のオープニングトラック

ビヘイビアplay-audioアクションのパラメータ

パラメータ	説明
Track ID (`trackId`)	Audioタブで登録されたトラックIDと一致
Operation (`action`)	`play`（再生）、`stop`（停止）、`crossfade`（クロスフェード切り替え）、`volume`（ボリューム調整）
Volume (`volume`)	0-1、任意
Fade Duration (`fadeDuration`)	秒、任意；クロスフェードに1.5-3秒推奨

Root Component オーディオAPI

メソッド	説明
`api.playAudio?.(trackId, opts)`	トラックを再生。optsには`fadeDuration`（秒）、`loop` などを含められる
`api.stopAudio?.(trackId?)`	トラックを停止。IDを省略するとすべて停止
`api.pauseAudio?.(trackId)` / `api.resumeAudio?.(trackId)`	トラックをその場で一時停止/再開（位置を保持）
`api.onAudioEnded?.(cb)`	再生終了イベントを購読；解除用の関数を返す。自動次曲送りに使う

よくある問題

症状	想定される原因	対処
まったく音が出ない	ブラウザが自動再生をブロック	モダンブラウザはオーディオ再生を許可する前にユーザー操作（クリック、タイピング）を要求します。プレイヤーに最初にメッセージを送信させるか、プレイリストで「Wait for First Message」をオンにしてください
BGM遷移が途切れて聞こえる	クロスフェードを使っていない	ビヘイビアの「Play Audio」オペレーションが`crossfade`に設定され、フェード期間が少なくとも1.5秒であることを確認
SFXとBGMが互いに中断	`stopPreviousBGM`が`true`に設定されている	SFXタイプの条件付きBGMルールは「Stop Current BGM」をオフにすべき
AIがオーディオディレクティブを使わない	エントリがAIに伝えていない	利用可能なすべてのトラックIDとディレクティブフォーマットをリストするSystem Presetsエントリを作成（パターン7参照）
アンビエントが大きすぎる	ボリュームが高すぎ	アンビエントは0.2-0.4、BGMは0.5-0.7に設定して分離を保つ
条件付きBGMがトリガーしない	変数値の型が一致しない	条件の値型が変数型と一致することを確認（例：数値変数には数値比較が必要、文字列比較ではない）
複数のルールが競合	同じ優先度	異なる条件付きBGMルールに異なる優先度値を与える — 高い数値が優先

これはRecipe #14：オーディオデザインガイドです

オーディオシステムの設計哲学は：シンプルなものは簡単に動く（プレイリスト + 自動再生）、複雑さは段階的にアンロックされる（条件付きBGM → ビヘイビア制御 → AIディレクティブ → カスタムAPI）。すべてのパターンを一度に学ぶ必要はありません — パターン1から始めて、より細かい制御が必要になったら戻ってきてください。

オーディオデザインガイド ​

概要 ​

パターン1：基本的なBGMセットアップ ​

これから作るもの ​

ステップバイステップ ​

ステップ1：オーディオトラックをアップロード ​

ステップ2：プレイリストを設定 ​

結果 ​

パターン2：シーン遷移時のクロスフェードBGM ​

これから作るもの ​

仕組み ​

ステップバイステップ ​

ステップ1：オーディオトラックを準備 ​

ステップ2：変数を作成 ​

ステップ3：ビヘイビアを作成 ​

ステップ4：Root Componentからトリガー ​

パターン3：キーワードトリガー効果音 ​

これから作るもの ​

仕組み ​

ステップバイステップ ​

ステップ1：SFXトラックを作成 ​

ステップ2：条件付きBGMルールを作成 ​

結果 ​

パターン4：条件付きBGM — 変数駆動の自動切り替え ​

これから作るもの ​

仕組み ​

ステップバイステップ ​

ステップ1：オーディオトラックを準備 ​

ステップ2：条件付きBGMルールを作成 ​

結果 ​

パターン5：アンビエントサウンドループ ​

これから作るもの ​

仕組み ​

ステップバイステップ ​

ステップ1：Ambientトラックを作成 ​

ステップ2：条件付きBGMでアンビエントを制御 ​

ビヘイビア経由でアンビエントを制御することも可能 ​

パターン6：Root Componentからオーディオを制御 ​

これから作るもの ​

仕組み ​

ステップバイステップ ​

ステップ1：オーディオトラックを準備 ​

ステップ2：Root Componentコードを書く ​

パターン7：AI駆動のオーディオ制御 ​

これから作るもの ​

仕組み ​

ステップバイステップ ​

ステップ1：AIが使う可能性のあるすべてのトラックを登録 ​

ステップ2：システムプロンプトでAIに利用可能なトラックを伝える ​

ステップ3：AI応答の例 ​

chainディレクティブ — 特別な使い方 ​

総合クイックリファレンス ​

トラックタイプ ​

オーディオを制御する5つの方法 ​

AIオーディオディレクティブリファレンス ​

条件付きBGMトリガータイプ ​

ビヘイビアplay-audioアクションのパラメータ ​

Root Component オーディオAPI ​

よくある問題 ​

オーディオデザインガイド

概要

パターン1：基本的なBGMセットアップ

これから作るもの

ステップバイステップ

ステップ1：オーディオトラックをアップロード

ステップ2：プレイリストを設定

結果

パターン2：シーン遷移時のクロスフェードBGM

これから作るもの

仕組み

ステップバイステップ

ステップ1：オーディオトラックを準備

ステップ2：変数を作成

ステップ3：ビヘイビアを作成

ステップ4：Root Componentからトリガー

パターン3：キーワードトリガー効果音

これから作るもの

仕組み

ステップバイステップ

ステップ1：SFXトラックを作成

ステップ2：条件付きBGMルールを作成

結果

パターン4：条件付きBGM — 変数駆動の自動切り替え

これから作るもの

仕組み

ステップバイステップ

ステップ1：オーディオトラックを準備

ステップ2：条件付きBGMルールを作成

結果

パターン5：アンビエントサウンドループ

これから作るもの

仕組み

ステップバイステップ

ステップ1：Ambientトラックを作成

ステップ2：条件付きBGMでアンビエントを制御

ビヘイビア経由でアンビエントを制御することも可能

パターン6：Root Componentからオーディオを制御

これから作るもの

仕組み

ステップバイステップ

ステップ1：オーディオトラックを準備

ステップ2：Root Componentコードを書く

パターン7：AI駆動のオーディオ制御

これから作るもの

仕組み

ステップバイステップ

ステップ1：AIが使う可能性のあるすべてのトラックを登録

ステップ2：システムプロンプトでAIに利用可能なトラックを伝える

ステップ3：AI応答の例

`chain`ディレクティブ — 特別な使い方

総合クイックリファレンス

トラックタイプ

オーディオを制御する5つの方法

AIオーディオディレクティブリファレンス

条件付きBGMトリガータイプ

ビヘイビアplay-audioアクションのパラメータ

Root Component オーディオAPI

よくある問題