> This is a page from the ElevenLabs documentation. For a complete page index, fetch https://elevenlabs.io/docs/llms.txt. For the full documentation in a single file, fetch https://elevenlabs.io/docs/llms-full.txt.

# 音频环境

## 概述

音频环境用于控制智能体外发音频在通话者听来是什么效果。可应用两项设置：

* **背景音**会在智能体语音下方循环播放环境音。
* **语音滤镜**会在混音前为智能体语音应用电话风格滤镜。

通话者会听到最终效果。智能体不会听到背景音，背景音也不会被传入语音识别。

这与[工具调用音效](/docs/zh/eleven-agents/customization/tools/tool-configuration/tool-call-sounds)不同，后者仅在工具运行时播放。

## 背景音

背景音会在整个对话期间，将内置预设混入智能体语音下方。用户打断时，声音仍会继续循环；不会随智能体回合结束而停止。

预设包括办公室、餐厅、城市、打字声和电梯音乐。在控制台中，可先预览预设再保存。

使用 `conversation_config.conversation.background_sound` 配置背景音。

### 配置

#### 通过控制台更新

#### 打开音频环境

打开智能体。在智能体页面中，点击 **音色** 旁的 **音频环境**
按钮。

#### 启用背景音

开启 **启用背景音**。在 **背景音** 中选择预设。使用下拉菜单旁的播放
控件进行预览。

#### 设置音量和循环

设置 **音量**。保持 **交叉淡化循环**开启，以避免声音
重复时产生明显的咔嗒声。保存更改。

#### 通过 CLI 更新

#### 拉取智能体配置

```bash
elevenlabs agents pull --agent agent_7101k5zvyjhmfg983brhmhkd98n6
```

#### 编辑 \`agent_configs/\<agent-name>.json\`

设置 `conversation_config.conversation.background_sound`。有效的 `source_id` 值为
`office1`、`office2`、`restaurant`、`city`、`typing`，以及 `elevator1` 到 `elevator4`。

```json
{
  "conversation_config": {
    "conversation": {
      "background_sound": {
        "source_type": "preset",
        "source_id": "office2",
        "volume": 0.15,
        "crossfade_loop": true
      }
    }
  }
}
```

要禁用背景音，请将 `source_type` 和 `source_id` 设为 `null`。请勿省略
`background_sound`，也不要将对象设为 `null`；更新会保留现有设置。

#### 推送智能体配置

```bash
elevenlabs agents push --agent agent_7101k5zvyjhmfg983brhmhkd98n6
```

#### 通过 API 更新

```python
from elevenlabs import ElevenLabs

elevenlabs = ElevenLabs()

elevenlabs.conversational_ai.agents.update(
    agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6",
    conversation_config={
        "conversation": {
            "background_sound": {
                "source_type": "preset",
                "source_id": "office2",
                "volume": 0.15,
                "crossfade_loop": True,
            }
        }
    },
)
```

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

const elevenlabs = new ElevenLabsClient();

await elevenlabs.conversationalAi.agents.update("agent_7101k5zvyjhmfg983brhmhkd98n6", {
  conversationConfig: {
    conversation: {
      backgroundSound: {
        sourceType: "preset",
        sourceId: "office2",
        volume: 0.15,
        crossfadeLoop: true,
      },
    },
  },
});
```

要禁用，请将 `source_type` 和 `source_id` 设为 `null`。更新时省略 `background_sound`
不会将其禁用。

> **Warning**
>
> 在网络状况很差的 WebSocket 连接上，混入背景音可能导致音频断续。

### 参数

有效的 `source_id` 值为 `office1`、`office2`、`restaurant`、`city`、`typing`，以及 `elevator1` 到 `elevator4`。

| 字段               | 类型      | 默认值    | 说明                                     |
| ---------------- | ------- | ------ | -------------------------------------- |
| `source_type`    | string  | 未设置    | 启用声音时必须为 `preset`。需与 `source_id` 一同设置。 |
| `source_id`      | string  | 未设置    | 内置预设的标识符。                              |
| `volume`         | number  | `0.15` | 相对于智能体语音的音量。范围为 `0.01`–`1.0`。          |
| `crossfade_loop` | boolean | `true` | 在循环边界进行交叉淡化，避免声音重复时出现咔嗒声。              |

## 语音滤镜

语音滤镜会调整智能体生成的语音。它不会均衡或降噪背景音。滤镜会先运行，然后将背景音混入处理后的语音下方。

使用 `conversation_config.tts.audio_effects.filter_preset_id` 配置语音滤镜。控制台提供电话预设；通过 CLI 或 API，可设置[音频效果目录](/docs/zh/api-reference/audio-effects/get-catalog)列出的任意滤镜预设。

#### 通过控制台更新

在同一 **音频环境** 面板中，将 **语音滤镜**设为 **关闭**或电话预设，然后
保存。

#### 通过 CLI 更新

在 `agent_configs/<agent-name>.json` 中设置 `conversation_config.tts.audio_effects`，然后推送
智能体配置：

```json
{
  "conversation_config": {
    "tts": {
      "audio_effects": {
        "filter_preset_id": "phone"
      }
    }
  }
}
```

要移除滤镜，请将 `filter_preset_id` 设为 `null`。

#### 通过 API 更新

```python
from elevenlabs import ElevenLabs

elevenlabs = ElevenLabs()

elevenlabs.conversational_ai.agents.update(
    agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6",
    conversation_config={
        "tts": {
            "audio_effects": {
                "filter_preset_id": "phone",
            }
        }
    },
)
```

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

const elevenlabs = new ElevenLabsClient();

await elevenlabs.conversationalAi.agents.update("agent_7101k5zvyjhmfg983brhmhkd98n6", {
  conversationConfig: {
    tts: {
      audioEffects: {
        filterPresetId: "phone",
      },
    },
  },
});
```

要移除滤镜，请将 `filter_preset_id` 设为 `null`。

> **Note**
>
> 智能体音频为单声道。`pan` 对智能体无效，`environment_id` 的混响会
> 下混为单声道。

## 限制

* 仅支持内置预设。无法上传自定义文件，也不能指定任意 URL。
* 智能体处于 **纯文本** 模式时，音频环境控件会隐藏。
* 背景音不会混入 [WhatsApp](/docs/zh/eleven-agents/whatsapp) 语音消息回复中，但 WhatsApp 通话仍会包含背景音。
* 无法通过客户端[覆盖设置](/docs/zh/eleven-agents/customization/personalization/overrides)按对话设置背景音；`conversation_config_override` 不包含 `background_sound`。不过，仍可在 [workflow](/docs/zh/eleven-agents/customization/agent-workflows) 节点中更改。

## 相关内容

#### [工具调用音效](/docs/zh/eleven-agents/customization/tools/tool-configuration/tool-call-sounds)

仅在工具运行时播放环境音频。

#### [语音自定义](/docs/zh/eleven-agents/customization/voice)

为智能体选择音色、语速和其他语音设置。