# 화자 맵

> 카메라 자체 마이크로 각 화자가 어느 카메라에 잡히는지 알아냅니다. 표를 직접 채우지 않아도 멀티캠 편집이 알맞은 사람으로 전환됩니다.

Source: https://nodaro.ai/ko/docs/nodes/audio/speaker-map

**화자 맵** 노드는 카메라 자체 마이크로 각 화자가 어느 카메라에 잡히는지 알아냅니다. 그러면 누구도 표를 채우지 않아도 멀티캠 편집이 알맞은 사람으로 전환됩니다. 결과를 [카메라 전환](https://nodaro.ai/docs/nodes/video/camera-switch)의 **화자 맵** 입력에 연결하세요. 카메라 전환은 각 컷을 말하는 사람의 카메라에 둡니다.

멀티캠 팟캐스트나 인터뷰에서는 보통 게스트마다 자신의 카메라가 있고, 카메라마다 자체 마이크가 있습니다. 게스트가 말하는 동안 그 게스트를 향한 카메라가 목소리를 가장 크게 듣습니다. 화자 맵은 화자 라벨이 있는 녹취록을 받아, 각 화자가 말하는 동안 카메라마다 소리를 듣고, 어느 카메라가 누구의 것인지 정합니다.

노드는 AI 모델이나 공급자 키 없이 로컬에서 실행되므로 모든 에디션에서 동작합니다.

## 사용 시기
- 게스트마다 카메라가 있는 멀티캠 팟캐스트에서, **화자** 표를 채우지 않고 어느 카메라가 누구의 것인지 카메라 전환에 알려 줄 때.
- 게스트가 세션마다 자리를 바꾸는 인터뷰에서 세션마다 카메라를 다시 지정할 때.

## 빠른 시작
### 노드 추가
캔버스에서 Tab을 누르고 **오디오 › 분석 › 화자 맵**을 선택하세요.

### 녹음 연결
녹음 2~6개를 **카메라** 입력에 연결하세요. 카메라와, 있다면 마스터 녹음과 와이드 샷입니다.

### 녹취록과 오프셋 연결
**화자 분리**를 켜고 실행한 [음성 텍스트 변환](https://nodaro.ai/docs/nodes/audio/transcribe) 노드를 **녹취록** 입력에 연결하세요. 녹음을 따로따로 시작했다면 [오디오 동기화](https://nodaro.ai/docs/nodes/audio/audio-sync)의 **오프셋** 출력을 **오프셋** 입력에 연결하세요.

### 마스터와 와이드 샷 지정 후 실행
설정 패널을 여세요. 있다면 **마스터 녹음**과 **와이드 샷**을 선택하세요. **실행**을 클릭하세요. 노드에 각 화자가 어느 카메라에 잡히는지 표시됩니다.

Workflow: 오디오 동기화가 카메라를 맞추고, 음성 텍스트 변환이 화자에 라벨을 붙이며, 화자 맵이 어느 카메라가 누구의 것인지 카메라 전환에 알려 줍니다.

- 동영상 업로드 → 오디오 동기화 (소스)
- 동영상 업로드 → 화자 맵 (카메라)
- 오디오 동기화 → 화자 맵 (오프셋)
- 음성 텍스트 변환 → 화자 맵 (녹취록)
- 화자 맵 → 카메라 전환 (화자 맵)

## 입력
| 입력 | 받는 것 | 하는 일 |
| --- | --- | --- |
| **카메라** | 동영상 및 오디오 노드, 2~6개 | 모든 녹음: 카메라와, 있다면 마스터 녹음과 와이드 샷. 각 녹음은 연결된 노드로 식별되며, 이 ID는 편집 계획이 같은 녹음에 주는 ID와 같습니다. 그래서 맵이 그대로 카메라 전환에 맞습니다. 필수입니다. |
| **오프셋** | 데이터 | 같은 녹음에 대한 [오디오 동기화](https://nodaro.ai/docs/nodes/audio/audio-sync) 결과. 녹음이 이미 하나의 시계를 공유하면 연결하지 마세요. 오디오 동기화의 기준은 어느 녹음이든 될 수 있습니다. 선택 사항입니다. |
| **녹취록** | 데이터 | 화자 분리를 켜고 실행한 음성 텍스트 변환 노드에서 얻은, 화자 라벨이 있는 단어 단위 녹취록. 마스터 녹음, 없으면 첫 번째 녹음의 녹취록이며, 발화 구간은 그 녹음의 시계로 읽습니다. 필수입니다. |

## 출력
| 출력 | 전달하는 것 |
| --- | --- |
| **화자 맵** | 각 화자가 어느 카메라에 잡히는지. 카메라 전환의 **화자 맵** 입력에 연결하세요. |
| **편집(EDL)** | 마스터 시계에 맞춘 하나의 편집으로 묶은 녹음. 오프셋이 적용되고, 마스터와 와이드 샷이 표시되며, 각 카메라의 화자가 맵에 따라 설정됩니다. |

**화자 맵** 출력은 다음과 같습니다.

```json
{
"version": 1,
"speakerMap": { "speaker_0": "camA", "speaker_1": "camB", "speaker_2": "" },
"confidence": {
"speaker_0": { "camera": "camA", "marginDb": 9.4 },
"speaker_1": { "camera": "camB", "marginDb": 6.1 },
"speaker_2": { "camera": "", "marginDb": 1.2 }
},
"notes": ["\"speaker_2\": no clear camera (the loudest led by 1.2 dB) — shown on the wide shot; set the map to override."]
}
```

| 필드 | 의미 |
| --- | --- |
| `speakerMap` | 각 화자 라벨과 그 사람의 카메라 ID. `""`는 뚜렷한 카메라가 없다는 뜻이며, 그 화자는 와이드 샷으로, 없으면 화면이 있는 아무 카메라로 보여 줍니다. |
| `confidence` | 화자마다 받은 카메라와, 가장 큰 카메라가 다음 카메라보다 몇 dB 앞섰는지. 두 대 미만의 카메라만 그 화자를 들었다면 `null`입니다. |
| `edl` | **편집(EDL)** 출력과 같은 편집. 녹음을 읽을 수 있고 마스터가 아닌 녹음에 화면이 있을 때 들어 있습니다. |
| `notes` | 알기 쉬운 말로 쓴 경고: 뚜렷한 카메라가 없는 화자, 두 대 미만의 카메라만 들은 화자, 오디오 트랙이 없는 카메라, 발화를 하나도 듣지 못한 카메라. |

## 설정
| 설정 | 하는 일 |
| --- | --- |
| **카메라** | 연결된 녹음을 연결한 순서대로 보여 줍니다. |
| **마스터 녹음** | 모두의 목소리를 듣는 녹음, 예를 들어 메인 마이크. 누구의 카메라도 아니며, 편집은 이 녹음의 시계로 진행됩니다. 기본값은 **없음**입니다. |
| **와이드 샷** | 모두를 찍는 카메라. 누구의 카메라도 아니며, 뚜렷한 카메라가 없는 화자는 이 카메라로 보여 줍니다. 소리만 있는 녹음이 아니라 카메라여야 합니다. 기본값은 **없음**입니다. |
| **필요한 차이** | 화자에게 카메라를 주려면 가장 큰 카메라가 다음 카메라보다 얼마나 더 커야 하는지입니다. 기본값은 3dB이고, 설정 패널에서 1~12dB을 고를 수 있습니다. 값이 낮을수록 더 많은 화자가 카메라를 받습니다. 값이 높을수록 뚜렷한 화자만 남습니다. |

### 카메라를 정하는 방식
화자마다, 그 화자의 모든 발화에 걸쳐 판단합니다.

- **가장 큰 카메라가 선택됩니다.** 화자의 목소리를 가장 크게 듣는 카메라가 다음 카메라보다 **필요한 차이** 이상 앞서면 그 카메라가 그 사람의 카메라입니다.
- **뚜렷한 카메라 없음.** 화자가 두 카메라 사이에 앉아 있는 등의 이유로 그만큼 앞서는 카메라가 없으면, 그 화자는 뚜렷한 카메라를 받지 못합니다. 카메라 전환은 그 화자를 와이드 샷으로, 와이드 샷이 없으면 화면이 있는 아무 카메라로 보여 줍니다. 메모에는 그 화자와, 가장 큰 카메라가 얼마나 앞섰는지가 적힙니다.
- **와이드 샷과 마스터 녹음은 선택되지 않습니다.** 모두의 목소리를 들으므로 누구의 카메라도 아닙니다.
- **소리가 없는 카메라는 실패가 아닙니다.** 오디오 트랙이 없거나, 마이크가 음소거되었거나, 발화를 하나도 듣지 못한 카메라는 어떤 화자에게도 선택되지 않을 뿐이며, 메모에 그 카메라가 적힙니다.

## 크레딧
화자 맵은 녹음의 길이나 개수와 관계없이 실행당 고정 가격 하나입니다. 노드의 **실행** 버튼에 가격이 표시됩니다. 셀프 호스팅 Community Edition과 Business 에디션은 크레딧을 쓰지 않습니다.

다음은 크레딧이 청구되기 전에 거부됩니다.

- 녹음이 2개 미만이거나 6개를 넘을 때, 또는 같은 ID를 가진 녹음이 두 개일 때.
- 오디오 노드처럼 소리만 있는 녹음을 와이드 샷으로 지정했을 때.
- 녹취록이 없을 때, 또는 화자 라벨이 전혀 없는 녹취록일 때. 음성 텍스트 변환에서 화자 분리를 켜고 다시 실행하세요.

캔버스에서는 녹음 중 어느 것도 아닌 마스터나 와이드 샷은 무시됩니다. API에서는 거부됩니다.

## 팁
- **메인 마이크와 와이드 샷을 지정하세요.** 지정하지 않으면 그 소리가 카메라의 소리와 경쟁하고, 모두의 목소리를 듣는 와이드 샷이 화자에게 선택될 수 있습니다.
- **녹음을 따로 시작했다면 오프셋을 연결하세요.** 오프셋이 없으면 각 카메라를 녹취록의 시간으로 읽으므로, 늦게 시작한 카메라는 엉뚱한 순간에 듣게 됩니다.
- **메모를 읽으세요.** 뚜렷한 카메라가 없는 화자는 대개 두 카메라 사이에 앉아 있거나, 카메라 마이크의 설정이 크게 달랐습니다. 그 화자의 카메라를 카메라 전환의 **화자** 표에서 설정하세요. 그곳에서 설정한 카메라가 맵보다 우선합니다.
- **차이를 조정하세요.** 맵이 아주 조금 더 큰 카메라를 고를 때는 **필요한 차이**를 높이세요. 뚜렷한 카메라가 없는 화자가 너무 많을 때는 낮추세요.
- **화자별 화면 배치에 맡기세요.** [화자별 화면 배치](https://nodaro.ai/docs/nodes/video/speaker-layout)는 오디오 동기화, 음성 텍스트 변환, 화자 맵, 카메라 전환을 대신 실행하고, 각 화자를 자신의 카메라로 프레이밍합니다.

## 문제 해결
| 문제 | 해결 방법 |
| --- | --- |
| 녹취록에 화자 라벨이 없어 실행이 거부됩니다 | 음성 텍스트 변환에서 화자 분리를 켜고 다시 실행한 뒤 새 녹취록을 연결하세요. |
| 뚜렷한 카메라가 없는 화자가 있습니다 | 마스터와 와이드 샷을 지정하거나, **필요한 차이**를 낮추거나, 카메라 전환에서 그 화자의 카메라를 설정하세요. |
| 와이드 샷이 화자에게 선택됩니다 | 그 카메라를 **와이드 샷**에서 선택해 누구의 카메라도 되지 않게 하세요. |
| 늦게 시작한 카메라의 맵이 틀립니다 | 오디오 동기화의 **오프셋** 출력을 **오프셋** 입력에 연결하세요. |

## API에서 사용
`POST /v1/speaker-map`은 `sources`(고유한 `id`, `url`, 선택적 `kind`를 가진 객체 2~6개의 목록)와 `transcript`를 받습니다. 선택적으로 `offsets`(오디오 동기화 결과), `masterSourceId`, `wideSourceId`, 0~30의 `marginDb`도 받습니다. `kind: "audio"`는 메인 마이크처럼 소리만 있는 녹음을 표시하며, 그 녹음은 누구의 카메라도 되지 않습니다.

형식이 잘못된 요청은 `400 validation_error`로, 화자 라벨이 없는 녹취록은 `422 no_speakers`로 응답하며, 둘 다 크레딧이 예약되기 전입니다. 완료된 작업의 `output_data.json`은 위의 **화자 맵** 결과이고, `output_data.edl`은 편집입니다.

SDK 메서드는 `client.edit.speakerMap`, CLI 명령은 `nodaro edit speaker-map`, MCP 도구는 `speaker_map`입니다. 결과를 카메라 전환에 넘기려면 SDK에서는 `speakerMapResult`, CLI에서는 `--speaker-map-result`, MCP에서는 `speaker_map_result`를 쓰세요. [보이스 및 미디어](https://nodaro.ai/docs/developers/api/voice-and-media), [SDK에서 편집](https://nodaro.ai/docs/developers/sdk/editing), [MCP 도구 레퍼런스](https://nodaro.ai/docs/mcp/tools)를 참조하세요.

## 자주 묻는 질문

### 화자 맵은 무엇을 하나요?

화자 맵은 멀티캠 녹화에서 각 화자가 어느 카메라에 잡히는지 알아냅니다. 화자가 말하는 동안 그 사람을 향한 카메라가 목소리를 가장 크게 들으므로, 그 카메라가 그 사람의 카메라가 됩니다. 그다음 카메라 전환이 각 컷을 말하는 사람의 카메라에 둡니다.

### 화자 맵에는 무엇을 연결해야 하나요?

화자 맵에는 한 대화의 녹음 2~6개와, 화자 분리를 켠 음성 텍스트 변환에서 얻은 화자 라벨이 있는 녹취록이 필요합니다. 녹음을 따로따로 시작했다면 오디오 동기화의 오프셋 출력도 연결하세요.

### 어느 카메라도 화자를 뚜렷하게 듣지 못하면 어떻게 되나요?

그 화자는 뚜렷한 카메라를 받지 못하며, 카메라 전환은 그 화자를 와이드 샷으로 보여 줍니다. 와이드 샷이 없으면 화면이 있는 아무 카메라로 보여 줍니다. 메모에는 그 화자와, 가장 큰 카메라가 얼마나 앞섰는지가 적힙니다.

### 화자 맵은 크레딧이 얼마나 드나요?

화자 맵은 녹음의 길이나 개수와 관계없이 실행당 고정 가격 하나입니다. 노드의 실행 버튼에 가격이 표시됩니다. 셀프 호스팅 Community Edition과 Business 에디션은 크레딧을 쓰지 않습니다.

### 화자 맵에 AI 모델이나 공급자 키가 필요한가요?

아니요. 화자 맵은 각 녹음의 소리를 로컬에서 읽으므로, 공급자 키가 없는 Community Edition 설치를 포함해 모든 에디션에서 동작합니다.