> 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 上是必需的。

**Inspector 字段：**

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

禁用 `_use3DAudio` 用于非位置型场景——例如，自助终端界面中，无论玩家站在什么位置，角色听起来始终都像“在场”。

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

`ConvaiSettings` 提供两个项目范围默认值，它们会一直生效，直到脚本覆盖它们。

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

在 Convai Editor 窗口的 **运行时默认值** 部分中配置这两个字段（**Convai > Settings > Runtime Defaults**），或在等效的 **Edit > Project Settings > Convai SDK > Runtime Defaults** 页面中配置——两处显示的是相同字段。

这些默认值会为 `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.