> 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/web-plugins/convai-web-sdk/mute-the-characters-voice.md).

# 将角色的声音静音

在不停止对话的情况下将角色所说内容静音，构建你自己的静音按钮，并在多角色会话中将某个角色静音。

在对话继续进行时关闭角色的语音。构建自己的静音按钮，或在多角色会话中只想听到某个角色、不想听到另一个角色时，请参阅本页。

这是控制说话者，而不是麦克风。 `setCharacterMuted` 控制用户听到的内容； [`audioControls.muteAudio`](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/web-plugins/convai-web-sdk.md) 控制麦克风发送的内容。两者彼此独立。

### 前提条件

* 已安装 Convai Web SDK，并有一个可连接的客户端。请参阅 [Web SDK 快速入门](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/web-plugins/convai-web-sdk/quickstart.md).

### 静音和取消静音

调用 `setCharacterMuted` 并传入 `true` 以关闭角色语音，传入 `false` 以恢复语音。此方法属于客户端，因此无论使用 `new ConvaiClient(...)` （来自 `@convai/web-sdk/core` ）还是使用 `useConvaiClient(...)` 返回的对象，效果都相同。

```ts
client.setCharacterMuted(true);   // 角色静音
client.setCharacterMuted(false);  // 角色恢复语音
```

对话不会受到影响。角色会继续说话，回复会继续流式传输，转录文本、情绪和混合形状也会继续传来。只有声音会停止，因此 3D 角色在静音时仍会保持唇形同步。

无需与服务器重新协商，因此在句子说到一半时静音、片刻后再取消静音，会从原处继续，而不是重新开始回复。

### 在 WebSocket 传输上静音

`setCharacterMuted` 适用于 WebRTC 和 WebSocket 传输。WebSocket 支持需要 1.9.2 或更高版本；在较早版本中，客户端会报告已静音，但语音仍会播放。在 WebSocket 传输上，静音期间产生的语音会被丢弃，而不会排队，因此取消静音后会从角色当时正在说的内容继续。

### 读取当前状态

`isCharacterMuted` 会返回角色是否处于静音状态。

```ts
client.setCharacterMuted(!client.isCharacterMuted());   // 切换
```

这是一个方法，而不是响应式状态。在 React 中，请在旁边维护自己的状态，以便按钮重新渲染：

```tsx
const [muted, setMuted] = useState(false);

const toggle = () => {
  const next = !muted;
  client.setCharacterMuted(next);
  setMuted(next);
};

return <button onClick={toggle}>{muted ? '取消静音' : '静音'}</button>;
```

`ConvaiWidget` （来自 `@convai/web-widget` ）已经提供静音按钮，并且调用的也是同一个方法。因此，你自己的按钮和组件中的图标显示的是同一个共享状态，而不是两个不同的状态。

### 连接前静音

客户端连接前调用此方法，设置会被记住，并应用于到达的第一段音频，因此需要以静音状态开始的会话不会先短暂地播放声音。

```ts
client.setCharacterMuted(true);
await client.connect();   // 角色从第一个字开始就处于静音状态
```

此设置在重新连接后仍然有效；稍后加入多角色会话的角色也会以静音状态加入，而不是发出声音。

### 在多角色会话中将单个角色静音

传入 `membershipId` 指定名册成员，以便只处理该成员。省略此项则设置会话中的所有角色。

```ts
const [first, second] = client.characters;

client.setCharacterMuted(true, { membershipId: second.membershipId });

client.isCharacterMuted();                      // false, the session is audible
client.isCharacterMuted(second.membershipId);   // true, this member is not
```

不带 `membershipId` 参数的调用会设置整个会话，并清除针对单个成员设置的选项。因此， `setCharacterMuted(false)` 始终会恢复所有语音：否则，之前单独静音的成员仍会保持静音，而你的代码中却没有任何说明。

`isCharacterMuted(membershipId)` 会报告该成员实际生效的状态：如果曾为该成员单独设置，则返回其自身设置；否则返回会话级设置。

有关 [多角色会话](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/web-plugins/convai-web-sdk.md) 中 `membershipId` 的来源，请参阅相关内容。

### 引用

| 方法                  | 签名                                                              | 说明                                    |
| ------------------- | --------------------------------------------------------------- | ------------------------------------- |
| `setCharacterMuted` | `(muted: boolean, options?: { membershipId?: string }) => void` | 将角色语音静音或恢复语音。设置会在重新连接后保留，并应用于之后到达的音频。 |
| `isCharacterMuted`  | `(membershipId?: string) => boolean`                            | 不带参数时返回会话级设置，带参数时返回该成员当前生效的设置。        |


---

# 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/web-plugins/convai-web-sdk/mute-the-characters-voice.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.
