> 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` 该组件控制角色的声音在场景中的播放方式。请将其与 `ConvaiAudio` 上的门面 `ConvaiManager` 用于通过脚本在运行时控制静音状态、每个角色的音量以及音频事件。

### 角色音频输出

添加 `ConvaiAudioOutput` 与……在同一个 GameObject 上 `ConvaiCharacter`。一个 `AudioSource` 必须位于同一个 GameObject 上。

**检查器字段：**

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

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

### 音频门面

若要通过脚本控制音频，请使用 `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:

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

The question should be specific, self-contained, and written in natural language.
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.