> For the complete documentation index, see [llms.txt](https://docs.convai.com/api-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/getting-started/configure-character-audio.md).

# 配置角色音频

配置单个角色和项目级的语音音量、空间音频和音频反馈，并通过静音与取消静音调用在脚本中控制播放。

该 `ConvaiAudioOutput` 该组件控制角色的声音在场景中的播放方式，而 `ConvaiSettings` 设置项目范围内的默认音量和音频反馈行为。可将任一者与 `ConvaiAudio` 门面位于 `ConvaiManager` 用于通过脚本在运行时控制静音状态、每个角色的音量以及音频事件。

### 角色音频输出

添加 `ConvaiAudioOutput` 到相同的 GameObject 上 `ConvaiCharacter`。一个 `AudioSource` 必须位于同一个 GameObject 上。

**检查器字段：**

| 字段             | 默认值     | 描述            |
| -------------- | ------- | ------------- |
| `音量`           | `1.0`   | 播放音量（0–1）     |
| `IsMuted`      | `false` | 将此角色的音频输出静音   |
| `_use3DAudio`  | `true`  | 启用 Unity 空间音频 |
| `_minDistance` | `1`     | 音频达到最大音量时的距离  |
| `_maxDistance` | `50`    | 音频衰减至零的距离     |

禁用 `_use3DAudio` 用于非位置型场景——例如，一个自助终端界面，在这种情况下，无论玩家站在何处，角色听起来始终都“在场”。

### 项目范围内的音频默认值

`ConvaiSettings` 提供两个项目范围内的默认值，直到脚本将其覆盖为止。

| 字段                     | 默认值    | 描述                  |
| ---------------------- | ------ | ------------------- |
| `CharacterAudioVolume` | `1`    | 角色音频的默认主音量（`0`–`1`) |
| `AudioFeedbackEnabled` | `true` | 默认播放反馈音效，例如聆听指示器    |

在 Convai 编辑器窗口的以下位置配置这两个字段： **运行时默认值** 部分（**Convai > 设置 > 运行时默认值**)，或等效的 **编辑 > 项目设置 > Convai SDK > 运行时默认值** 页面——两处显示的字段相同。

这些默认值会为 `RuntimePreferences` 时自动连接， `ConvaiManager` 构建其运行时。可在会话运行期间通过以下方式读取或更改生效值： `ConvaiManager.ActiveManager.ConvaiRuntime.RuntimePreferences`:

```csharp
// 读取当前项目范围内的默认值
float volume = ConvaiManager.ActiveManager.ConvaiRuntime.RuntimePreferences.CharacterAudioVolume;
bool audioFeedbackOn = ConvaiManager.ActiveManager.ConvaiRuntime.RuntimePreferences.AudioFeedbackEnabled;

// 在运行时覆盖——CharacterAudioVolume 会被限制在 0-1 范围内
ConvaiManager.ActiveManager.ConvaiRuntime.RuntimePreferences.CharacterAudioVolume = 0.5f;
ConvaiManager.ActiveManager.ConvaiRuntime.RuntimePreferences.AudioFeedbackEnabled = false;
```

{% hint style="warning" %}
`CharacterAudioVolume` 不会更改 `ConvaiAudioOutput.Volume` 会自动应用到现有角色。读取 `RuntimePreferences.CharacterAudioVolume` 你自己的音量控制脚本中的值，并将其应用到 `ConvaiAudioOutput` 或音频混音器。
{% endhint %}

### 音频门面

对于脚本化音频控制，请使用 `ConvaiAudio` 通过以下方式访问的门面： `ConvaiManager.Audio`。这是运行时音频管理推荐使用的 API。

#### 麦克风控制

```csharp
// 将本地麦克风静音/取消静音
ConvaiManager.ActiveManager.Audio.SetMicMuted(true);

// 切换并获取新状态
bool isMuted = ConvaiManager.ActiveManager.Audio.ToggleMicMuted();

// 手动开始麦克风采集（如果 ConnectOnStart 为 false）
await ConvaiManager.ActiveManager.Audio.StartListeningAsync();
```

#### 按角色播放控制

```csharp
string characterId = character.CharacterId;

// 将特定角色静音
ConvaiManager.ActiveManager.Audio.MuteCharacter(characterId);

// 取消静音
ConvaiManager.ActiveManager.Audio.UnmuteCharacter(characterId);

// 检查静音状态
bool muted = ConvaiManager.ActiveManager.Audio.IsCharacterMuted(characterId);

// 完全禁用某个角色的远程音频
ConvaiManager.ActiveManager.Audio.SetRemoteAudioEnabled(characterId, false);
```

#### 音频事件

```csharp
void OnEnable()
{
    ConvaiManager.ActiveManager.Audio.OnMicMuteChanged += HandleMicMuteChanged;
}

void OnDisable()
{
    ConvaiManager.ActiveManager.Audio.OnMicMuteChanged -= HandleMicMuteChanged;
}

void HandleMicMuteChanged(bool isMuted)
{
    muteButton.SetIsOnWithoutNotify(isMuted);
}
```

### 使用示例

#### 示例 1：静音切换 UI 按钮

**场景：** 某企业入职培训模拟在屏幕角落包含一个麦克风静音按钮。

```csharp
public class MuteButtonController : MonoBehaviour
{
    [SerializeField] private Toggle _muteToggle;

    void OnEnable()
    {
        _muteToggle.onValueChanged.AddListener(OnMuteToggled);
        ConvaiManager.ActiveManager.Audio.OnMicMuteChanged += OnMicMuteChanged;
    }

    void OnDisable()
    {
        _muteToggle.onValueChanged.RemoveListener(OnMuteToggled);
        ConvaiManager.ActiveManager.Audio.OnMicMuteChanged -= OnMicMuteChanged;
    }

    void OnMuteToggled(bool muted) =>
        ConvaiManager.ActiveManager.Audio.SetMicMuted(muted);

    void OnMicMuteChanged(bool muted) =>
        _muteToggle.SetIsOnWithoutNotify(muted);
}
```

**预期结果：** 该切换开关会与实际麦克风状态保持同步。按下它会使麦克风静音或取消静音。外部更改（例如来自按住说话逻辑）也会自动更新该切换开关。

#### 示例 2：多讲师场景中的按角色音量

**场景：** 某语言学习模拟中有两位 AI 讲师——主教师和对话伙伴。玩家可以独立调节它们的音量。

```csharp
public class CharacterVolumeController : MonoBehaviour
{
    [SerializeField] private ConvaiCharacter _character;
    [SerializeField] private Slider _volumeSlider;

    void Start()
    {
        var audioOutput = _character.GetComponent<ConvaiAudioOutput>();
        _volumeSlider.value = audioOutput.Volume;
        _volumeSlider.onValueChanged.AddListener(v => audioOutput.Volume = v);
    }
}
```

**预期结果：** 每个角色的音量滑块只控制该角色的 `AudioSource` 音量。两个角色可以彼此独立地以不同音量被听到。

### 下一步

配置麦克风设备和平台特定的音频权限。

{% content-ref url="/pages/17d06dd6ce948cddecd226cb498bd300a3508ab9" %}
[配置麦克风](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/getting-started/configure-microphone.md)
{% endcontent-ref %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/getting-started/configure-character-audio.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.