---
title: "音频"
description: "世界文件里的音轨对象、音轨类型、播放列表、条件音乐规则，以及播放它们的音频指令。"
---

# 音频

音频音轨提供背景音乐、音效和环境音。它们可以通过 AI 指令、规则或自动播放列表触发。

## AudioTrack Schema

```json
{
  "id": "bgm-tavern",
  "name": "Tavern Theme",
  "type": "bgm",
  "url": "@asset:uuid-here",
  "loop": true,
  "volume": 0.4,
  "fadeIn": 2,
  "fadeOut": 1.5,
  "maxDuration": null
}
```

| 字段 | 类型 | 描述 |
|------|------|------|
| `id` | string | 唯一的 kebab-case ID |
| `name` | string | 显示名称 |
| `type` | `"bgm"` \| `"sfx"` \| `"ambient"` | 音轨类型 |
| `url` | string | 音频来源 — `@asset:{id}` 或直接 URL |
| `loop` | boolean | 是否循环播放（通常：BGM/环境音为 true，音效为 false） |
| `volume` | number | 0.0 到 1.0 |
| `fadeIn` | number \| null | 淡入时长，单位秒 |
| `fadeOut` | number \| null | 淡出时长，单位秒 |
| `maxDuration` | number \| null | N 秒后自动停止 |

## AI 音频指令

AI 通过方括号指令触发音频：

```
[audio: bgm-tavern play]
[audio: sfx-sword play]
[audio: bgm-tavern stop]
[audio: bgm-battle crossfade 2.5]
[audio: ambient-rain volume 0.3]
[audio: sfx-magic play chain:bgm-ambient]
```

| 动作 | 描述 |
|------|------|
| `play` | 开始播放音轨 |
| `stop` | 停止音轨 |
| `crossfade <seconds>` | 从当前 BGM 交叉淡入到此音轨 |
| `volume <0-1>` | 更改音轨音量 |
| `play chain:<trackId>` | 播放此音轨，然后自动播放下一首 |

## BGM 播放列表

自动播放一系列 BGM 音轨：

```json
{
  "bgmPlaylist": {
    "tracks": ["bgm-explore-1", "bgm-explore-2", "bgm-explore-3"],
    "playMode": "shuffle",
    "gapSeconds": 0,
    "autoPlay": true,
    "waitForFirstMessage": true
  }
}
```

| 字段 | 类型 | 描述 |
|------|------|------|
| `tracks` | string[] | 要循环播放的音轨 ID 数组 |
| `playMode` | `"loop"` \| `"shuffle"` \| `"sequential"` | 播放顺序模式 |
| `gapSeconds` | number | 音轨之间的静音间隔（默认：0，最大：30） |
| `autoPlay` | boolean | 是否自动开始播放（默认：true） |
| `waitForFirstMessage` | boolean | 等到玩家发送第一条消息后再开始播放 |

## 条件 BGM

当条件满足时播放特定音轨。支持变量检查、关键词匹配、回合计数和会话开始触发器。

```json
{
  "conditionalBGM": [
    {
      "id": "combat-music",
      "name": "Combat Music",
      "targetTrackId": "bgm-battle",
      "triggerType": "variable",
      "conditions": [
        { "variableId": "in-combat", "operator": "eq", "value": true }
      ],
      "conditionLogic": "all",
      "priority": 10,
      "fadeInDuration": 1,
      "fadeOutDuration": 2,
      "stopPreviousBGM": true,
      "fallback": "default"
    }
  ]
}
```

| 字段 | 类型 | 描述 |
|------|------|------|
| `id` | string | 唯一标识符 |
| `name` | string | 显示名称 |
| `targetTrackId` | string | 触发时播放的音轨 |
| `triggerType` | `"variable"` \| `"ai-keyword"` \| `"keyword"` \| `"turn-count"` \| `"session-start"` | 触发条件 BGM 的事件类型 |
| `conditions` | Condition[] | 要检查的变量条件 |
| `conditionLogic` | `"all"` \| `"any"` | 多个条件的组合方式（默认：`"all"`） |
| `keywords` | string[] | 要匹配的关键词（用于 `keyword` / `ai-keyword` 触发器） |
| `matchWholeWords` | boolean | 仅匹配完整单词（用于关键词触发器） |
| `atTurn` | number | 在特定回合触发（用于 `turn-count` 触发器） |
| `everyNTurns` | number | 每隔 N 回合触发（用于 `turn-count` 触发器） |
| `priority` | number | 多个触发器匹配时，优先级高的胜出 |
| `fadeInDuration` | number | 淡入时长，单位秒 |
| `fadeOutDuration` | number | 淡出时长，单位秒 |
| `stopPreviousBGM` | boolean | 是否先停止当前播放的 BGM |
| `fallback` | `"default"` \| `"previous"` \| trackId 字符串 | 条件变为 false 时播放什么 |

条件运算符使用缩写形式：`eq`、`neq`、`gt`、`lt`、`gte`、`lte`、`contains`。

当条件变为 true 时，音轨开始播放。当条件变为 false 时，音轨停止（如果配置了淡出则带淡出效果），并根据 `fallback` 设置回退。
