> 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）     |
| `是否静音`         | `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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
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=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.