> 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` 到与 `ConvaiCharacter`相同的 GameObject 上。还需要在同一个 GameObject 上添加一个 `AudioSource` 。

**Inspector 字段：**

| 字段             | 默认值     | 说明            |
| -------------- | ------- | ------------- |
| `Volume`       | `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" %}
[配置麦克风](https://docs.convai.com/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.
