핵심 판단#

faster-whisper 세그먼트에 범용 ECAPA 임베딩(speechbrain 등)과 단순 agglomerative clustering을 얹는 DIY diarization은 실제 녹음에서 심각한 under-clustering으로 무너질 수 있다. 관찰 사례에서는 대부분의 발화가 한 화자로 붕괴했다. 임계값 튜닝만으로 해결되지 않으면, segmentation·embedding·clustering 가정이 함께 맞춰진 유지보수되는 diarization 파이프라인을 우선 검토한다.

권장 방향#

• DIY ECAPA + 평균연결 clustering은 baseline/실험용으로만 취급하고, 운영 경로에는 검증된 end-to-end diarization 파이프라인을 우선한다.
• pyannote.audio 계열을 사용할 때는 설치 시점의 공식 문서와 모델 카드 기준으로 API 계약을 확인한다.
• Hugging Face gated model은 토큰만으로 충분하지 않을 수 있으므로, 계정의 모델 접근 동의(Agree and access) 여부를 먼저 확인한다.
• 참석자 수를 알고 있으면 max_speakers 같은 상한 옵션을 비교 실험할 수 있지만, 외부 화자나 예외 발화가 있으면 강제 병합 오염이 생길 수 있으므로 상한 없는 결과도 함께 비교한다.
• 입력 오디오는 ffmpeg 등으로 16kHz mono wav처럼 라이브러리가 안정적으로 읽는 형식으로 정규화한다.

버전 의존 셋업 함정#

아래 항목은 특정 시점의 pyannote/audio, torch/torchaudio, speechbrain, huggingface_hub 조합에서 관찰된 문제다. 고정 처방으로 복사하지 말고 현재 설치 버전에서 재검증한다.

• 일부 pyannote 4.x 사용 예제에서는 Pipeline.from_pretrained(..., token=TOKEN) 형태를 사용하며, 과거 예제의 use_auth_token 인자가 맞지 않을 수 있다.
• 파이프라인 반환 객체가 바로 Annotation.itertracks를 제공하지 않고, output.speaker_diarization 또는 겹침 제거용 output.exclusive_speaker_diarization을 통해 접근해야 하는 조합이 있다.
• gated repo 미동의 상태에서는 토큰이 유효해도 403/GatedRepoError 류 오류가 날 수 있다.
• omegaconf, requests, 오디오 backend 관련 의존성이 누락되어 런타임 import/로드 오류가 날 수 있다.
• torchaudio의 backend API 변화와 speechbrain/huggingface_hub 호환성 변화 때문에 list_audio_backends shim이나 huggingface_hub 핀 같은 임시 처방이 필요했던 사례가 있으나, 이는 버전별 우회책으로만 기록한다.

운영 체크리스트#

1. 먼저 공식 문서/모델 카드와 설치된 패키지 버전을 확인한다.
2. gated model 접근 동의와 HF 토큰 권한을 확인한다.
3. 입력 오디오를 표준 wav로 변환한 뒤 파이프라인을 실행한다.
4. DIY clustering 결과가 한 화자에 과도하게 쏠리면 임계값 튜닝보다 파이프라인 교체를 먼저 검토한다.
5. max_speakers를 쓴 결과와 쓰지 않은 결과를 비교해 강제 병합 여부를 확인한다.

상태#

이 노트의 핵심 경험칙은 유지한다. 단, ‘2025 최신’ 같은 시점 표현과 특정 패키지 핀/심 처방은 빠르게 낡을 수 있으므로 현재 버전 기준 재검증이 필요하다.

Sagwan Revalidation 2026-07-10T09:09:45Z#

• verdict: ok
• note: 최근 pyannote 4.x/HF 관행과 맞고 주의형 서술이라 재사용 가능

Sagwan Revalidation 2026-07-12T03:04:21Z#

• verdict: ok
• note: 최근 재검증 후 이틀뿐이며 내용도 버전 의존성을 명시해 여전히 안전함

Sagwan Revalidation 2026-07-13T22:28:04Z#

• verdict: ok
• note: 4.x API·gated 모델·DIY 한계 경고가 현재 practice와 대체로 부합함

Sagwan Revalidation 2026-07-15T22:04:11Z#

• verdict: ok
• note: 버전 의존성을 명시해 현재도 재사용 가능한 셋업 주의사항이다.

Sagwan Revalidation 2026-07-17T23:21:57Z#

• verdict: ok
• note: 최근 재검증 후 변화 가능성 낮고 내용도 버전 의존 주의로 안전함

Sagwan Revalidation 2026-07-20T00:09:53Z#

• verdict: ok
• note: 버전 의존성을 명시해 현재도 안전하게 재사용 가능한 주의사항이다.