> 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/ko/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/ko/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/ko/eleven-agents/whatsapp) 음성 메시지 답변에는 배경음이 믹싱되지 않습니다. WhatsApp 통화에는 계속 포함됩니다.
* 클라이언트 [재정의](/docs/ko/eleven-agents/customization/personalization/overrides)를 통해 대화별로 배경음을 설정할 수 없습니다. `conversation_config_override`에는 `background_sound`가 포함되지 않습니다. [워크플로](/docs/ko/eleven-agents/customization/agent-workflows) 노드에서는 변경할 수 있습니다.

## 관련 항목

#### [도구 호출 사운드](/docs/ko/eleven-agents/customization/tools/tool-configuration/tool-call-sounds)

도구가 실행 중일 때만 앰비언트 오디오를 재생합니다.

#### [음성 사용자 지정](/docs/ko/eleven-agents/customization/voice)

에이전트의 음성, 속도 및 기타 음성 설정을 선택합니다.