> 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`](/api-docs/zh/cha-jian-yu-ji-cheng/web-plugins/convai-web-sdk.md) 改变麦克风发送的内容。两者彼此独立。

### 前提条件

* 已安装 Convai Web SDK，并且有一个可连接的客户端。参见 [Web SDK 快速入门](/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);  // 角色再次可听见
```

对话不受影响。角色继续说话，回复继续流式传输，转录、情绪和 blendshapes 继续到达。只有声音停止，这意味着 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` 已经展示了一个静音按钮，并且它调用的也是这个同一个方法。因此，你自己的按钮与小部件的图标描述的是同一个共享状态，而不是两个状态。

### 连接前静音

在客户端连接之前发出的调用会被记住，并应用到第一段到达的音频上，因此本应静默开始的会话不会先出现可听见的瞬间。

```ts
client.setCharacterMuted(true);
await client.connect();   // 角色从第一句话起就是静音的
```

该设置在重新连接后也会保留，并且后来加入多角色会话的角色会以静音状态到达，而不是可听见。

### 在多角色会话中使一个角色静音

传入 `membershipId` 以仅针对某个成员。省略它则会设置会话中的所有角色。

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

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

client.isCharacterMuted();                      // false，会话是可听见的
client.isCharacterMuted(second.membershipId);   // true，此成员不是
```

不带 `membershipId` 的调用会设置整个会话，并清除为单个成员所做的设置。这就是为什么 `setCharacterMuted(false)` 总会恢复所有声音：如果没有它，之前单独静音的成员会一直静默，而你的代码里却没有任何说明原因的内容。

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

参见 [多角色会话](/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.