fix: Docker 실행 경로에서 화자 분리가 동작하도록 수정

Docker로 띄우면 화자 분리가 전혀 되지 않았다. 세 가지 문제가 겹쳐 있었다.

1. 베이스 이미지가 Alpine(musl)인데 sherpa-onnx 사전 빌드 바이너리는 glibc에
   링크되어 있어 ld-linux-aarch64.so.1 을 찾지 못했다. node:22-slim 으로 교체.
2. Next 파일 트레이싱이 sherpa-onnx.node 만 복사하고 동반 공유 라이브러리
   (libonnxruntime, libsherpa-onnx-c-api 등 약 33MB)를 놓쳤다.
   outputFileTracingIncludes 로 플랫폼 패키지를 통째로 포함시킨다.
3. models/ 가 이미지에도 볼륨에도 없어 컨테이너 안에서는 항상 미설치 상태였다.
   호스트의 models/ 를 읽기 전용으로 마운트한다.

추가로 app 컨테이너에 LLM_* 환경변수를 전달한다. GEMINI_API_KEY만 넘기고
있어서 OpenAI 호환 프로바이더를 환경변수로 설정할 수 없었다.

컨테이너 안에서 실제 오디오로 화자 분리가 도는 것을 확인했다.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

.env.example

@@ -51,13 +51,3 @@ GEMINI_API_KEY=
 # LLM_BASE_URL=
 # LLM_MODEL=
 # LLM_API_KEY=
-
-# ─────────────────────────────────────────────────────────────
-# 회의 오디오 녹음 저장 위치 (선택)
-# ─────────────────────────────────────────────────────────────
-# 기본값은 <프로젝트>/uploads/recordings 입니다.
-# Docker Compose에서는 uploads 볼륨에 저장되어 컨테이너를 재시작해도 남습니다.
-#
-# ⚠️ 녹음 파일에는 회의 원음이 그대로 들어 있습니다. 디스크 암호화된 위치에
-#    두고, 필요 없어진 녹음은 직접 삭제하세요. SECURITY.md 참고.
-# RECORDINGS_DIR=

.gitignore

@@ -49,3 +49,9 @@ next-env.d.ts
 .env
 !.env.example
 
+
+# 화자 분리 모델 (npm run setup:diarization 으로 내려받음)
+models/
+
+# 로컬 개발용 compose 오버라이드
+docker-compose.override.yml

Dockerfile

@@ -1,4 +1,6 @@
-FROM node:22-alpine AS base
+# sherpa-onnx 사전 빌드 바이너리가 glibc에 링크되어 있어 Alpine(musl)에서는
+# ld-linux-aarch64.so.1 을 찾지 못한다. glibc 계열인 slim 을 쓴다.
+FROM node:22-slim AS base
 
 FROM base AS deps
 WORKDIR /app
@@ -15,8 +17,8 @@ RUN npm run build
 FROM base AS runner
 WORKDIR /app
 ENV NODE_ENV=production
-RUN addgroup --system --gid 1001 nodejs
+RUN groupadd --system --gid 1001 nodejs \
-RUN adduser --system --uid 1001 nextjs
+  && useradd --system --uid 1001 --gid nodejs nextjs
 COPY --from=builder /app/public ./public
 COPY --from=builder /app/.next/standalone ./
 COPY --from=builder /app/.next/static ./.next/static
@@ -24,6 +26,9 @@ COPY --from=builder /app/prisma ./prisma
 
 RUN mkdir -p uploads && chown nextjs:nodejs uploads
 
+# sherpa-onnx의 .so는 표준 검색 경로에 없으므로 명시해준다.
+ENV LD_LIBRARY_PATH=/app/node_modules/sherpa-onnx-linux-arm64:/app/node_modules/sherpa-onnx-linux-x64
+
 USER nextjs
 EXPOSE 3000
 ENV PORT=3000

README.md

@@ -24,6 +24,7 @@ docker compose up -d
 
 - [✨ 주요 기능](#-주요-기능)
   - [🎤 실시간 녹음 & 전사](#-실시간-녹음--전사)
+  - [🗣️ 화자 분리](#️-화자-분리)
   - [🤖 AI 회의록 (6 템플릿 × 3 강도)](#-ai-회의록-6-템플릿--3-강도)
   - [⚡ 실시간 롤링 요약](#-실시간-롤링-요약)
   - [💾 회의록 저장/조회/검색](#-회의록-저장조회검색)
@@ -51,29 +52,10 @@ docker compose up -d
 
 **특징**
 - 즉시 시작 — 별도 STT 서버나 키 없이 작동
-- **오디오 원본 동시 녹음** — 전사와 무관하게 회의 원음을 파일로 보관
 - **자동 재연결** — 네트워크 끊김 시 최대 8회 재시도, 누적 transcript 보존
 - 확정 전 텍스트는 회색 이탤릭 + 깜빡이는 커서로 시각화
 - 녹음 중 `🔴 N단어 · M개 구간` 실시간 카운터
 
-> ⚠️ **Web Speech API는 발화를 상당량 놓칩니다.** 원거리·다인 대면 회의에서
-> 실측 포착률이 10% 안팎이었습니다(46분 회의 / 489어절). 회의 전사용으로
-> 설계된 엔진이 아니라 근접 음성 명령용입니다. 그래서 **오디오 원본을 반드시
-> 함께 남깁니다** — 놓친 발화는 나중에 서버 STT로 다시 살릴 수 있습니다.
-
-### 🎧 오디오 원본 보관
-
-녹음을 시작하면 전사와 **별개로** 마이크 입력을 오디오 파일로 저장합니다.
-
-- 15초마다 조각을 서버에 이어 붙여 **탭이나 서버가 죽어도 그때까지의 오디오는 남습니다**
-- 서버 저장이 실패해도 녹음은 중단되지 않고, 브라우저 사본을 **⬇️ 내려받기**로 회수할 수 있습니다
-- 한 조각도 못 받았으면 "보관됨"이라고 하지 않고 오류를 띄웁니다
-- 저장 위치: `uploads/recordings/` (Docker에서는 `uploads` 볼륨 → 재시작해도 유지)
-
-**캡처 설정** — 브라우저 기본값은 전화 통화용 튜닝이라 멀리 앉은 화자를
-노이즈로 지워버립니다. 그래서 노이즈 억제·에코 제거를 끄고 AGC만 남깁니다
-(`src/lib/recording.ts`의 `RECORDING_AUDIO_CONSTRAINTS`).
-
 **사용**
 1. 홈에서 **🎤 녹음 시작** 클릭
 2. 마이크 권한 허용
@@ -120,6 +102,42 @@ docker compose up -d
 
 ---
 
+### 🗣️ 화자 분리
+
+누가 무슨 말을 했는지 구분해 기록합니다. 회의 환경에 따라 두 가지 방식을 씁니다.
+
+| 모드 | 방식 | 정확도 | 준비물 |
+|---|---|---|---|
+| **원격 회의** | 내 마이크와 시스템(탭) 오디오를 **별도 트랙**으로 받아 트랙별로 전사 | **100%** — 추론 없음 | 없음 |
+| **대면 회의** | 마이크 한 트랙을 **내 PC에서** 분석해 화자를 나눔 | DER 12~15% | 모델 1회 설치 |
+
+**원격 회의**는 트랙이 곧 화자라 틀릴 수가 없습니다. 시작할 때 화면 공유 대화상자에서
+**"탭 오디오 공유"를 반드시 켜야** 합니다. 켜지 않으면 마이크 단독 녹음으로 넘어가고
+화자 라벨이 붙지 않습니다 (틀린 라벨을 붙이지 않습니다).
+
+**대면 회의**는 `pyannote-segmentation-3.0` + `3D-Speaker CAM++` ONNX 모델을 로컬
+Next.js 프로세스에서 실행합니다. **오디오가 외부로 나가지 않습니다.** GPU도 파이썬
+런타임도 필요 없고, 노트북 CPU에서 실시간의 수십 배 속도로 처리됩니다.
+
+```bash
+# 최초 1회 — 모델 약 34MB 내려받기
+npm run setup:diarization
+```
+
+> Docker로 실행하실 때도 **호스트에서** 위 명령을 먼저 실행하세요. `models/` 디렉터리가
+> 컨테이너에 읽기 전용으로 마운트됩니다. 받지 않으면 대면 모드만 비활성화되고 나머지는
+> 정상 동작합니다.
+
+> 💡 **참석자 수를 정확히 입력하세요.** 자동 추정은 화자 수를 잘못 세는 것이 주 실패
+> 모드입니다. 실측에서 4인 오디오가 자동 모드로는 5명, 참석자 수를 알려주면 4명으로
+> 정확히 나왔습니다.
+
+대면 모드는 녹음이 끝난 뒤 **전체 오디오에 한 번** 분석을 돌립니다. 구간을 잘라
+반복 실행하면 실행마다 화자 번호가 달라져 이어 붙일 수 없기 때문입니다. 따라서
+녹음 중 실시간 화자 표시는 없고, 종료 시 원문 전체에 화자가 붙습니다.
+
+---
+
 ### ⚡ 실시간 롤링 요약
 
 녹음 중 **30초마다** Gemini가 그동안의 발화를 분석해 중간 회의록을 자동 갱신합니다.
@@ -354,7 +372,8 @@ npm run test:coverage     # 커버리지 리포트
 | DB | PostgreSQL 16 + Prisma 7 (driver adapter `@prisma/adapter-pg`) |
 | Markdown | `marked` + `isomorphic-dompurify` |
 | 스타일 | Tailwind CSS v4 |
-| 테스트 | Vitest 4 (jsdom, 141 tests) |
+| 화자 분리 | pyannote-segmentation-3.0 + CAM++ (ONNX Runtime, CPU) |
+| 테스트 | Vitest 4 (jsdom, 184 tests) |
 | 배포 | Docker Compose + standalone Next.js 빌드 |
 
 ---
@@ -502,9 +521,8 @@ prisma/
 
 | 제약 | 설명 | 대응 |
 |---|---|---|
-| **Chrome 전용** | Web Speech API는 비표준 — Safari / Firefox는 제한적 | 서버 사이드 STT 전환 예정 |
+| **Chrome 전용** | Web Speech API는 비표준 — Safari / Firefox는 제한적 | Phase 4에서 서버 사이드 전사 검토 |
-| **전사 포착률 낮음** | 원거리·다인 대면 회의 실측 10% 안팎 | 오디오 원본 보관 → 서버 STT 재전사 (진행 예정) |
+| **화자 구분 없음** | 의도적 비지원 (Non-goal) | — |
-| **화자 구분 없음** | 미구현 (PR #16 / #17 검토 중) | — |
 | **Gemini 무료 등급 한도** | 15 RPM / 1000 RPD | 한도 초과 시 자동 쿨다운, 단순 변환 폴백 |
 | **단일 사용자** | 인증 없음, 데이터 격리 없음 | 1인 1인스턴스로 운용 |
 | **마크다운 검색** | PostgreSQL `ILIKE` (수천 건 이상에서 느려질 수 있음) | 필요 시 `tsvector` 인덱스 추가 |

SECURITY.md

@@ -52,6 +52,7 @@
 | 액션 아이템 | PostgreSQL (`action_items`) | 외부 송출 없음 |
 | API 키 | 브라우저 LocalStorage 또는 `.env` | 요청 시 선택한 프로바이더에만 전송 |
 | 음성 데이터 | 메모리 (실시간), `/app/uploads` (파일 업로드) | **Chrome Web Speech API → Google 서버** ⚠️ |
+| 화자 분리용 PCM | 서버 프로세스 메모리 (녹음 중에만) | **외부 송출 없음** — 로컬에서 분석하고 분석 후 즉시 폐기 |
 
 ### ⚠️ 주의: Web Speech API의 음성 외부 전송
 
@@ -77,6 +78,21 @@ Chrome의 `SpeechRecognition` API는 **음성 데이터를 Google 서버로 전
 - 중계 라우터는 요청을 대신 전달하는 구조상 **평문 프롬프트를 볼 수 있는 주체가 한 곳 늘어납니다.** 로깅·보관 정책은 각 서비스 약관을 직접 확인하세요.
 - 사내 컴플라이언스가 외부 전송을 제한한다면 **로컬 모델** 프리셋을 사용하세요.
 
+### 화자 분리 오디오는 로컬에만 머뭅니다
+
+대면 회의 화자 분리는 `pyannote-segmentation-3.0` + `CAM++` ONNX 모델을 로컬
+Next.js 프로세스에서 실행합니다. 외부 API를 호출하지 않으므로 **오디오가 네트워크로
+나가지 않습니다.**
+
+- 녹음 중 PCM 조각이 서버 프로세스 **메모리**에 쌓입니다 (디스크에 쓰지 않음)
+- 분석이 끝나면 즉시 폐기하며, 6시간 지난 세션은 자동 정리됩니다
+- 세션 최대 길이는 3시간으로 제한됩니다
+- 단일 사용자 로컬 실행 전제입니다. 여러 사용자가 붙는 환경이라면 세션 ID를
+  추측해 다른 사람의 오디오에 접근할 수 있으므로, 노출 배포 시 인증이 선행되어야 합니다
+
+전사 텍스트는 여전히 Web Speech API를 거치므로 Google로 갑니다. 화자 분리만
+로컬이라는 점에 유의하세요.
+
 ### base URL은 서버가 대신 호출합니다 (SSRF 주의)
 
 OpenAI 호환 프리셋의 base URL은 브라우저가 아니라 **Next.js Route Handler(서버)** 가 fetch 합니다.
@@ -132,26 +148,6 @@ OpenAI 호환 프리셋의 base URL은 브라우저가 아니라 **Next.js Route
 - 추가 보호가 필요하면 reverse proxy(nginx, Caddy)에 Basic Auth 추가
 - 회사 환경에서는 SSO 통합이 필요하지만 현재 비목표
 
-### MEDIUM — 회의 원음이 디스크에 평문으로 남습니다
-
-**현황**: 실시간 녹음을 시작하면 회의 오디오 원본이 `uploads/recordings/`에 저장됩니다
-(Docker에서는 `uploads` 볼륨). 암호화하지 않은 평문 오디오이며, 회의에서 오간
-말이 그대로 들어 있습니다. **전사 텍스트보다 민감도가 높습니다** — 텍스트는
-Web Speech가 대부분 놓치지만 오디오에는 전부 남습니다.
-
-이 저장은 의도된 설계입니다. Web Speech의 포착률이 낮아(실측 10% 안팎) 원음을
-남기지 않으면 놓친 발화를 복구할 방법이 없습니다.
-
-**완화**:
-- 디스크 암호화(FileVault / BitLocker)가 켜진 머신에서 운용
-- 불필요해진 녹음은 `uploads/recordings/`에서 직접 삭제
-- `RECORDINGS_DIR` 환경변수로 저장 위치를 별도 암호화 볼륨으로 지정 가능
-- 녹음 파일 자동 만료/삭제는 **미구현** — 수동 관리가 필요합니다
-
-**세션 ID 추측**: 녹음 조회·추가 API는 128비트 난수 ID만으로 접근을 가릅니다.
-인증이 없으므로, 같은 머신에서 앱에 접근 가능한 주체는 ID를 알면 오디오를
-내려받을 수 있습니다. 단일 사용자 로컬 실행 전제입니다.
-
 ### MEDIUM — 파일 업로드 매직 바이트 미검증
 **현황**: `audio-validation.ts`는 `file.type`(클라이언트 제공)과 파일명 확장자만 검사. 매직 바이트 검증 없음.
 

docker-compose.yml

@@ -43,8 +43,17 @@ services:
     environment:
       DATABASE_URL: postgresql://${POSTGRES_USER:?required}:${POSTGRES_PASSWORD:?required}@db:5432/${POSTGRES_DB:?required}
       GEMINI_API_KEY: ${GEMINI_API_KEY:-}
+      # OpenAI 호환 프로바이더 (선택) — 없으면 브라우저에 저장된 설정을 쓴다
+      LLM_PROVIDER: ${LLM_PROVIDER:-}
+      LLM_BASE_URL: ${LLM_BASE_URL:-}
+      LLM_MODEL: ${LLM_MODEL:-}
+      LLM_API_KEY: ${LLM_API_KEY:-}
+      DIARIZATION_MODEL_DIR: /app/models/diarization
     volumes:
       - uploads:/app/uploads
+      # 화자 분리 모델 — 호스트에서 npm run setup:diarization 으로 받은 것을 읽기 전용으로 마운트.
+      # 없으면 빈 디렉터리가 되고 대면 화자 분리만 비활성화된다 (앱은 정상 동작).
+      - ./models:/app/models:ro
     depends_on:
       db:
         condition: service_healthy

docs/ROADMAP.md

@@ -155,64 +155,6 @@
 
 ---
 
-## 🔴 실사용 진단 (2026-09-08 대면 회의)
-
-46분 대면 회의를 실제로 녹음해 본 결과다. 로드맵의 우선순위를 바꾼 근거.
-
-| 지표 | 값 |
-|---|---|
-| 회의 길이 | 46분 6초 |
-| 총 청크 | 122개 |
-| 총 어절 | **489** |
-| 분당 어절 | **10.6** (한국어 대화 통상 100~150) |
-| 추정 포착률 | **7~10%** |
-| 30초 이상 공백 | 26곳 / 합계 26분 29초 (회의의 57%) |
-| 빈 텍스트 청크 | 19개 (16%) |
-
-**빈 청크 19개가 결정적 증거다.** Chrome이 `isFinal: true`에 `transcript: ""`를
-준 경우로, "소리는 감지했으나 인식 실패"를 뜻한다. 마이크 입력 문제가 아니라
-Web Speech가 원거리·다인 한국어를 못 알아듣고 버린 것이다.
-
-**결론: Web Speech API는 회의 전사에 쓸 수 없다.** 재시작 갭을 메우고 interim을
-flush해서 7%를 20~30%로는 올려도 90%로는 못 간다. 구현 결함이 아니라 엔진의 한계다.
-
----
-
-## 🎯 P0 — 유실을 멈춘다
-
-- [x] **오디오 원본 녹음** — `MediaRecorder`로 회의 원음을 파일로 보관
-  - [x] 15초 조각 단위로 서버에 append → 탭/서버가 죽어도 그때까지는 남음
-  - [x] 서버 실패해도 녹음 계속 + 브라우저 사본 내려받기
-  - [x] 0바이트일 때 "보관됨"이라고 하지 않음
-  - [x] 캡처 제약에서 노이즈 억제·에코 제거 해제 (원거리 화자 보존)
-  - [x] 회의록 저장 시 `audioFileName`/`audioMimeType`/`audioDuration` 연결
-- [ ] **서버 STT 파이프라인** — 녹음 파일 → Whisper / Gemini audio → transcript
-  - [ ] `/api/upload`를 막다른 길에서 본선 경로로 승격
-  - [ ] 프로바이더 레이어에 `/v1/audio/transcriptions` 추가 (#12 구조 확장)
-  - [ ] Web Speech는 "녹음 중 실시간 미리보기"로 강등, 확정본은 종료 후 재전사
-  - [ ] 같은 오디오로 Web Speech vs STT 포착률 실측 비교
-- [ ] **빈 청크 필터링** — 빈 발화 19개가 요약 프롬프트를 오염시키고 있음
-- [ ] **타임스탬프 실측화** — `useSpeechRecognition.ts`의 `startTime: now - 2` 하드코딩 제거
-- [ ] **10만 자 하드 실패 → 분할 요약** — 긴 회의가 마지막에 통째로 실패함
-
-## 🎯 P1 — 입력단 개선
-
-- [ ] 대면 회의용 USB 전방향 마이크 도입 (코드로 못 푸는 물리적 한계)
-- [ ] 원격 회의용 `echoCancellation` 재활성 경로 분리
-
-## 🎯 P2 — 화자 분리 재설계
-
-- [ ] **PR #17은 현재 형태로 머지 보류** — 실사용에서 46분 회의를 화자 1명으로
-      판정했고, 5개 청크는 배정조차 실패했다. `assignSpeakers()`가 쓰는 시간축이
-      가짜(`now - 2`)라 diarization의 실제 타임라인과 맞지 않는다
-- [ ] 서버 STT 도입 후 재설계 — Whisper의 단어 단위 실제 타임스탬프 위에서
-      diarization을 돌리면 그때 비로소 겹침 기반 배정이 의미를 갖는다
-- [ ] #17의 sherpa-onnx 래퍼·모델 셋업 스크립트는 그때 재활용
-- [ ] 참석자 수 힌트는 유지 (#17 실측에서 효과 확인됨)
-- [ ] PR #16(dual-stream)은 원격 회의 전용으로 분리 검증
-
----
-
 ## 🎯 Phase 3 — 참석자 + 태그 (3~5일)
 
 ### Issues
@@ -257,6 +199,7 @@ flush해서 7%를 20~30%로는 올려도 90%로는 못 간다. 구현 결함이
 
 다음 기능은 개인 사용 목적에 부합하지 않아 **의도적으로 범위 밖**:
 
+- **화자 구분 (Speaker Diarization)** — 유료 API 비용/복잡도 대비 개인용에 과함
 - **실시간 공동 편집 (CRDT)** — Yjs/Liveblocks 도입 복잡도 대비 이득 없음
 - **권한 관리 / 워크스페이스** — 단일 사용자 가정
 - **모바일 네이티브 앱** — 웹 PWA로 충분

next.config.ts

@@ -12,6 +12,13 @@ const securityHeaders = [
 
 const nextConfig: NextConfig = {
   output: "standalone",
+  // sherpa-onnx-node는 네이티브 애드온이라 번들링하면 안 된다.
+  serverExternalPackages: ["sherpa-onnx-node"],
+  // 트레이싱은 .node 파일만 잡고 동반 공유 라이브러리(.so/.dylib)를 놓친다.
+  // 플랫폼 패키지를 통째로 포함시켜야 standalone 빌드에서 로드된다.
+  outputFileTracingIncludes: {
+    "/api/diarize": ["./node_modules/sherpa-onnx-*/**"],
+  },
   async headers() {
     return [
       {

package-lock.json

@@ -16,7 +16,8 @@
         "pg": "^8.13.1",
         "prisma": "^7.7.0",
         "react": "19.2.4",
-        "react-dom": "19.2.4"
+        "react-dom": "19.2.4",
+        "sherpa-onnx-node": "^1.13.7"
       },
       "devDependencies": {
         "@tailwindcss/postcss": "^4",
@@ -8422,6 +8423,98 @@
         "node": ">=8"
       }
     },
+    "node_modules/sherpa-onnx-darwin-arm64": {
+      "version": "1.13.7",
+      "resolved": "https://registry.npmjs.org/sherpa-onnx-darwin-arm64/-/sherpa-onnx-darwin-arm64-1.13.7.tgz",
+      "integrity": "sha512-5NCE50hAvr3n2pdett0SgfPBJXaFZE0bqHwbHyiq+IKZ8Ids0l4M0VrG+ImGYIafCwie+oC3uAJ+pKj9xg/k+w==",
+      "cpu": [
+        "arm64"
+      ],
+      "license": "Apache-2.0",
+      "optional": true,
+      "os": [
+        "darwin"
+      ]
+    },
+    "node_modules/sherpa-onnx-darwin-x64": {
+      "version": "1.13.7",
+      "resolved": "https://registry.npmjs.org/sherpa-onnx-darwin-x64/-/sherpa-onnx-darwin-x64-1.13.7.tgz",
+      "integrity": "sha512-N3o+T+wn9WaQmsKV5DD8bTHdo+WN2+sXwmZcGJZiDjtOMR2zFz7uVCZnYCmEAMgvChC+oHcF5RvEEKcRCAu6Pw==",
+      "cpu": [
+        "x64"
+      ],
+      "license": "Apache-2.0",
+      "optional": true,
+      "os": [
+        "darwin"
+      ]
+    },
+    "node_modules/sherpa-onnx-linux-arm64": {
+      "version": "1.13.7",
+      "resolved": "https://registry.npmjs.org/sherpa-onnx-linux-arm64/-/sherpa-onnx-linux-arm64-1.13.7.tgz",
+      "integrity": "sha512-TFCVpXyTh69buhOtTS8KIfkRXOVKY4Y1qjAktSItrKS4A0chnnrlXO5bKWoNAPeI6fMxTF/uvMYbYgcvjEMfNg==",
+      "cpu": [
+        "arm64"
+      ],
+      "license": "Apache-2.0",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/sherpa-onnx-linux-x64": {
+      "version": "1.13.7",
+      "resolved": "https://registry.npmjs.org/sherpa-onnx-linux-x64/-/sherpa-onnx-linux-x64-1.13.7.tgz",
+      "integrity": "sha512-npmxn5WwmAmlthgBhmbZ33t3i2j4mJwQt46dMEb3j7d41y1/uJrjrVAfa/DkvV+vn49ZWfcQ2UEWDipaZBVhuw==",
+      "cpu": [
+        "x64"
+      ],
+      "license": "Apache-2.0",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/sherpa-onnx-node": {
+      "version": "1.13.7",
+      "resolved": "https://registry.npmjs.org/sherpa-onnx-node/-/sherpa-onnx-node-1.13.7.tgz",
+      "integrity": "sha512-0XGV7arGngBCnol0m8OLyqlnaUm19Q1KmetVj1DDBdymXa1upmAHZDwNdN47gjsEhqE5hXUEyc1vRQoXrNhNVg==",
+      "license": "Apache-2.0",
+      "optionalDependencies": {
+        "sherpa-onnx-darwin-arm64": "^1.13.7",
+        "sherpa-onnx-darwin-x64": "^1.13.7",
+        "sherpa-onnx-linux-arm64": "^1.13.7",
+        "sherpa-onnx-linux-x64": "^1.13.7",
+        "sherpa-onnx-win-ia32": "^1.13.7",
+        "sherpa-onnx-win-x64": "^1.13.7"
+      }
+    },
+    "node_modules/sherpa-onnx-win-ia32": {
+      "version": "1.13.7",
+      "resolved": "https://registry.npmjs.org/sherpa-onnx-win-ia32/-/sherpa-onnx-win-ia32-1.13.7.tgz",
+      "integrity": "sha512-sTwtpxPQ76XLn0giAbvknIDEDKD3XXi2mo2AVROEucf1pIK1DjQl+LjLkalTeFoQqbC4J3xGx/g+xgcHQD1dsw==",
+      "cpu": [
+        "ia32"
+      ],
+      "license": "Apache-2.0",
+      "optional": true,
+      "os": [
+        "win32"
+      ]
+    },
+    "node_modules/sherpa-onnx-win-x64": {
+      "version": "1.13.7",
+      "resolved": "https://registry.npmjs.org/sherpa-onnx-win-x64/-/sherpa-onnx-win-x64-1.13.7.tgz",
+      "integrity": "sha512-wBV1o+/zgsMrOjfCFIgGrH6S28xq6CqRCLSavCOjTZ6cqr80yGc07DUHxqsHFPZvfoJU+2JF5L2l3gyWFWoWdQ==",
+      "cpu": [
+        "x64"
+      ],
+      "license": "Apache-2.0",
+      "optional": true,
+      "os": [
+        "win32"
+      ]
+    },
     "node_modules/side-channel": {
       "version": "1.1.0",
       "resolved": "https://registry.npmjs.org/side-channel/-/side-channel-1.1.0.tgz",

package.json

@@ -9,7 +9,8 @@
     "lint": "eslint",
     "test": "vitest run",
     "test:watch": "vitest",
-    "test:coverage": "vitest run --coverage"
+    "test:coverage": "vitest run --coverage",
+    "setup:diarization": "node scripts/setup-diarization.mjs"
   },
   "dependencies": {
     "@prisma/adapter-pg": "^7.7.0",
@@ -20,7 +21,8 @@
     "pg": "^8.13.1",
     "prisma": "^7.7.0",
     "react": "19.2.4",
-    "react-dom": "19.2.4"
+    "react-dom": "19.2.4",
+    "sherpa-onnx-node": "^1.13.7"
   },
   "devDependencies": {
     "@tailwindcss/postcss": "^4",

public/pcm-worklet.js

@@ -0,0 +1,38 @@
+/**
+ * 마이크 오디오를 Int16 PCM 조각으로 잘라 메인 스레드로 넘긴다.
+ *
+ * AudioContext를 16kHz로 열면 브라우저가 리샘플링해주므로 여기서는
+ * float32 → int16 변환과 버퍼링만 한다. 화자 분리 모델이 16kHz 모노를 받는다.
+ */
+const CHUNK_SAMPLES = 16000 * 4 // 4초
+
+class PcmCollector extends AudioWorkletProcessor {
+  constructor() {
+    super()
+    this.buffer = new Int16Array(CHUNK_SAMPLES)
+    this.offset = 0
+  }
+
+  flush() {
+    if (this.offset === 0) return
+    const out = this.buffer.slice(0, this.offset)
+    this.port.postMessage(out, [out.buffer])
+    this.buffer = new Int16Array(CHUNK_SAMPLES)
+    this.offset = 0
+  }
+
+  process(inputs) {
+    const channel = inputs[0] && inputs[0][0]
+    if (!channel) return true
+
+    for (let i = 0; i < channel.length; i++) {
+      const clamped = Math.max(-1, Math.min(1, channel[i]))
+      this.buffer[this.offset++] = clamped * 32767
+      if (this.offset === CHUNK_SAMPLES) this.flush()
+    }
+
+    return true
+  }
+}
+
+registerProcessor('pcm-collector', PcmCollector)

scripts/setup-diarization.mjs

@@ -0,0 +1,98 @@
+#!/usr/bin/env node
+/**
+ * 화자 분리 모델 내려받기.
+ *
+ * 두 모델 모두 CPU에서 도는 ONNX 파일이며 GPU나 파이썬 런타임이 필요 없다.
+ * 라이선스 문제로 저장소에 포함하지 않고 최초 1회 내려받는다.
+ *
+ *   npm run setup:diarization
+ */
+import { createWriteStream } from 'node:fs'
+import { mkdir, rename, rm, stat } from 'node:fs/promises'
+import { pipeline } from 'node:stream/promises'
+import path from 'node:path'
+import { spawn } from 'node:child_process'
+
+const DEST = path.join(process.cwd(), 'models', 'diarization')
+
+const MODELS = [
+  {
+    name: 'segmentation.onnx',
+    // pyannote/segmentation-3.0 (MIT) — 발화 구간 분할
+    url: 'https://github.com/k2-fsa/sherpa-onnx/releases/download/speaker-segmentation-models/sherpa-onnx-pyannote-segmentation-3-0.tar.bz2',
+    archiveEntry: 'sherpa-onnx-pyannote-segmentation-3-0/model.onnx',
+    approxMB: 6,
+  },
+  {
+    name: 'embedding.onnx',
+    // 3D-Speaker CAM++ — 화자 임베딩
+    url: 'https://github.com/k2-fsa/sherpa-onnx/releases/download/speaker-recongition-models/3dspeaker_speech_campplus_sv_zh-cn_16k-common.onnx',
+    approxMB: 28,
+  },
+]
+
+async function exists(p) {
+  try {
+    await stat(p)
+    return true
+  } catch {
+    return false
+  }
+}
+
+async function download(url, dest) {
+  const res = await fetch(url, { redirect: 'follow' })
+  if (!res.ok) throw new Error(`${res.status} ${res.statusText} — ${url}`)
+  await pipeline(res.body, createWriteStream(dest))
+}
+
+function run(cmd, args, cwd) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(cmd, args, { cwd, stdio: 'inherit' })
+    child.on('error', reject)
+    child.on('exit', (code) =>
+      code === 0 ? resolve() : reject(new Error(`${cmd} 실패 (exit ${code})`)),
+    )
+  })
+}
+
+async function main() {
+  await mkdir(DEST, { recursive: true })
+
+  for (const model of MODELS) {
+    const target = path.join(DEST, model.name)
+
+    if (await exists(target)) {
+      console.log(`✓ ${model.name} — 이미 있음`)
+      continue
+    }
+
+    console.log(`↓ ${model.name} (약 ${model.approxMB}MB) 내려받는 중...`)
+
+    if (!model.archiveEntry) {
+      await download(model.url, target)
+      console.log(`✓ ${model.name}`)
+      continue
+    }
+
+    const archive = path.join(DEST, 'tmp.tar.bz2')
+    await download(model.url, archive)
+    await run('tar', ['xjf', archive], DEST)
+    await rename(path.join(DEST, model.archiveEntry), target)
+    await rm(archive)
+    await rm(path.join(DEST, path.dirname(model.archiveEntry)), {
+      recursive: true,
+      force: true,
+    })
+    console.log(`✓ ${model.name}`)
+  }
+
+  console.log(`\n완료. 모델 위치: ${DEST}`)
+  console.log('이제 녹음 화면에서 "대면 회의 화자 분리"를 쓸 수 있습니다.')
+}
+
+main().catch((err) => {
+  console.error(`\n✗ 실패: ${err.message}`)
+  console.error('네트워크를 확인하고 다시 실행해주세요.')
+  process.exit(1)
+})

src/__tests__/recording-store.test.ts

@@ -1,164 +0,0 @@
-import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'
-import { mkdtemp, rm, readFile } from 'fs/promises'
-import { tmpdir } from 'os'
-import path from 'path'
-
-type Store = typeof import('@/lib/recording-store')
-
-let dir: string
-let store: Store
-
-beforeEach(async () => {
-  dir = await mkdtemp(path.join(tmpdir(), 'recordings-'))
-  process.env.RECORDINGS_DIR = dir
-  vi.resetModules()
-  store = await import('@/lib/recording-store')
-})
-
-afterEach(async () => {
-  delete process.env.RECORDINGS_DIR
-  await rm(dir, { recursive: true, force: true })
-})
-
-describe('createRecording', () => {
-  it('세션 메타를 만들고 확장자를 붙인다', async () => {
-    const meta = await store.createRecording('audio/webm;codecs=opus')
-
-    expect(meta.id).toMatch(/^[0-9a-f]{32}$/)
-    expect(meta.fileName).toBe(`${meta.id}.webm`)
-    expect(meta.finalizedAt).toBeNull()
-    expect(meta.durationMs).toBeNull()
-  })
-
-  it('매번 다른 id를 준다', async () => {
-    const a = await store.createRecording('audio/webm')
-    const b = await store.createRecording('audio/webm')
-    expect(a.id).not.toBe(b.id)
-  })
-})
-
-describe('appendChunk', () => {
-  it('조각을 받은 순서대로 이어 붙인다', async () => {
-    const { id } = await store.createRecording('audio/webm')
-
-    await store.appendChunk(id, Buffer.from('AAA'))
-    await store.appendChunk(id, Buffer.from('BBB'))
-    const last = await store.appendChunk(id, Buffer.from('CC'))
-
-    expect(last).toEqual({ ok: true, bytes: 8 })
-
-    const meta = await store.getRecording(id)
-    const written = await readFile(path.join(dir, meta!.fileName), 'utf-8')
-    expect(written).toBe('AAABBBCC')
-  })
-
-  it('동시에 들어와도 순서가 섞이지 않는다', async () => {
-    const { id } = await store.createRecording('audio/webm')
-
-    // 클라이언트가 직렬로 보내도 서버에서 겹칠 수 있다. 겹쳐도 파일이
-    // 깨지지 않아야 한다 — 순서가 어긋나면 컨테이너를 못 읽는다.
-    await Promise.all([
-      store.appendChunk(id, Buffer.from('1')),
-      store.appendChunk(id, Buffer.from('2')),
-      store.appendChunk(id, Buffer.from('3')),
-      store.appendChunk(id, Buffer.from('4')),
-    ])
-
-    const meta = await store.getRecording(id)
-    const written = await readFile(path.join(dir, meta!.fileName), 'utf-8')
-    expect(written).toHaveLength(4)
-    expect(written.split('').sort().join('')).toBe('1234')
-  })
-
-  it('없는 세션은 404로 거절한다', async () => {
-    const result = await store.appendChunk('f'.repeat(32), Buffer.from('x'))
-    expect(result).toEqual({
-      ok: false,
-      error: '녹음 세션을 찾을 수 없습니다.',
-      status: 404,
-    })
-  })
-
-  it('누적 크기를 정확히 보고한다', async () => {
-    const { id } = await store.createRecording('audio/webm')
-    await store.appendChunk(id, Buffer.from('keep'))
-
-    const result = await store.appendChunk(id, Buffer.alloc(1024))
-    expect(result).toEqual({ ok: true, bytes: 4 + 1024 })
-  })
-})
-
-describe('finalizeRecording', () => {
-  it('길이를 확정하고 최종 크기를 돌려준다', async () => {
-    const { id } = await store.createRecording('audio/webm')
-    await store.appendChunk(id, Buffer.from('0123456789'))
-
-    const status = await store.finalizeRecording(id, 46_000)
-
-    expect(status?.bytes).toBe(10)
-    expect(status?.durationMs).toBe(46_000)
-    expect(status?.finalizedAt).not.toBeNull()
-  })
-
-  it('확정 정보가 디스크에도 남는다', async () => {
-    const { id } = await store.createRecording('audio/webm')
-    await store.finalizeRecording(id, 1_234)
-
-    const reloaded = await store.getRecording(id)
-    expect(reloaded?.durationMs).toBe(1_234)
-  })
-
-  it('길이가 숫자가 아니면 null로 둔다', async () => {
-    const { id } = await store.createRecording('audio/webm')
-    const status = await store.finalizeRecording(id, null)
-    expect(status?.durationMs).toBeNull()
-  })
-
-  it('없는 세션은 null', async () => {
-    expect(await store.finalizeRecording('e'.repeat(32), 1)).toBeNull()
-  })
-})
-
-describe('getRecording', () => {
-  it('잘못된 id는 파일을 찾아보지도 않는다', async () => {
-    expect(await store.getRecording('../../etc/passwd')).toBeNull()
-    expect(await store.getRecording('..')).toBeNull()
-  })
-})
-
-describe('openRecording', () => {
-  it('조각이 하나도 없으면 null', async () => {
-    const { id } = await store.createRecording('audio/webm')
-    expect(await store.openRecording(id)).toBeNull()
-  })
-
-  it('저장된 바이트를 그대로 읽어준다', async () => {
-    const { id } = await store.createRecording('audio/webm')
-    await store.appendChunk(id, Buffer.from('hello'))
-
-    const opened = await store.openRecording(id)
-    expect(opened?.bytes).toBe(5)
-    expect(opened?.meta.mimeType).toBe('audio/webm')
-
-    const chunks: Buffer[] = []
-    for await (const chunk of opened!.stream) {
-      chunks.push(Buffer.from(chunk as Buffer))
-    }
-    expect(Buffer.concat(chunks).toString()).toBe('hello')
-  })
-})
-
-describe('크래시 내성', () => {
-  it('종료 처리 없이 중단돼도 그때까지의 오디오는 남는다', async () => {
-    const { id } = await store.createRecording('audio/webm')
-    await store.appendChunk(id, Buffer.from('part1'))
-    await store.appendChunk(id, Buffer.from('part2'))
-    // finalize 없이 프로세스가 죽었다고 치고 모듈을 새로 읽는다.
-    vi.resetModules()
-    const reloaded: Store = await import('@/lib/recording-store')
-
-    const status = await reloaded.getRecordingStatus(id)
-    expect(status?.bytes).toBe(10)
-    expect(status?.finalizedAt).toBeNull()
-  })
-})

src/__tests__/recording.test.ts

@@ -1,149 +0,0 @@
-import { describe, it, expect } from 'vitest'
-import {
-  PREFERRED_MIME_TYPES,
-  RECORDING_AUDIO_CONSTRAINTS,
-  extensionForMimeType,
-  formatBytes,
-  formatDuration,
-  isValidRecordingId,
-  pickRecorderMimeType,
-  recordingDownloadName,
-} from '@/lib/recording'
-
-describe('pickRecorderMimeType', () => {
-  it('가장 앞선 후보를 고른다', () => {
-    const picked = pickRecorderMimeType(() => true)
-    expect(picked).toBe(PREFERRED_MIME_TYPES[0])
-  })
-
-  it('지원하지 않는 후보는 건너뛴다', () => {
-    const picked = pickRecorderMimeType((type) => type === 'audio/mp4')
-    expect(picked).toBe('audio/mp4')
-  })
-
-  it('아무것도 지원하지 않으면 null', () => {
-    expect(pickRecorderMimeType(() => false)).toBeNull()
-  })
-})
-
-describe('extensionForMimeType', () => {
-  it('코덱 파라미터를 떼고 판단한다', () => {
-    expect(extensionForMimeType('audio/webm;codecs=opus')).toBe('webm')
-    expect(extensionForMimeType('audio/ogg; codecs=opus')).toBe('ogg')
-  })
-
-  it('주요 컨테이너를 매핑한다', () => {
-    expect(extensionForMimeType('audio/webm')).toBe('webm')
-    expect(extensionForMimeType('audio/mp4')).toBe('m4a')
-    expect(extensionForMimeType('audio/mpeg')).toBe('mp3')
-    expect(extensionForMimeType('audio/wav')).toBe('wav')
-  })
-
-  it('대소문자를 가리지 않는다', () => {
-    expect(extensionForMimeType('AUDIO/WEBM')).toBe('webm')
-  })
-
-  it('모르는 형식은 bin으로 떨어진다', () => {
-    expect(extensionForMimeType('application/octet-stream')).toBe('bin')
-  })
-})
-
-describe('isValidRecordingId', () => {
-  const valid = 'a'.repeat(32)
-
-  it('32자 hex만 통과시킨다', () => {
-    expect(isValidRecordingId(valid)).toBe(true)
-    expect(isValidRecordingId('0123456789abcdef0123456789abcdef')).toBe(true)
-  })
-
-  it('경로 조작 시도를 막는다', () => {
-    expect(isValidRecordingId('../../etc/passwd')).toBe(false)
-    expect(isValidRecordingId(`${valid}/../x`)).toBe(false)
-    expect(isValidRecordingId('..')).toBe(false)
-    expect(isValidRecordingId(`../${valid}`)).toBe(false)
-  })
-
-  it('길이나 문자셋이 어긋나면 거부한다', () => {
-    expect(isValidRecordingId('a'.repeat(31))).toBe(false)
-    expect(isValidRecordingId('a'.repeat(33))).toBe(false)
-    expect(isValidRecordingId('A'.repeat(32))).toBe(false)
-    expect(isValidRecordingId('g'.repeat(32))).toBe(false)
-    expect(isValidRecordingId('')).toBe(false)
-  })
-
-  it('문자열이 아니면 거부한다', () => {
-    expect(isValidRecordingId(null)).toBe(false)
-    expect(isValidRecordingId(undefined)).toBe(false)
-    expect(isValidRecordingId(123)).toBe(false)
-  })
-})
-
-describe('recordingDownloadName', () => {
-  const at = new Date(2026, 8, 8, 14, 5)
-
-  it('날짜와 제목을 붙인다', () => {
-    expect(recordingDownloadName('주간 회의', at, 'audio/webm')).toBe(
-      '20260908-1405_주간_회의.webm',
-    )
-  })
-
-  it('제목이 없으면 날짜만 쓴다', () => {
-    expect(recordingDownloadName('   ', at, 'audio/webm')).toBe(
-      '20260908-1405.webm',
-    )
-  })
-
-  it('파일명에 못 쓰는 문자를 지운다', () => {
-    const name = recordingDownloadName('a/b\\c:d*e?f"g<h>i|j', at, 'audio/webm')
-    expect(name).toBe('20260908-1405_abcdefghij.webm')
-    expect(name).not.toMatch(/[\\/:*?"<>|]/)
-  })
-
-  it('아주 긴 제목을 자른다', () => {
-    const name = recordingDownloadName('가'.repeat(200), at, 'audio/webm')
-    expect(name.length).toBeLessThan(90)
-  })
-})
-
-describe('formatBytes', () => {
-  it('단위를 바꿔가며 표기한다', () => {
-    expect(formatBytes(512)).toBe('512B')
-    expect(formatBytes(2048)).toBe('2KB')
-    expect(formatBytes(5 * 1024 * 1024)).toBe('5.0MB')
-  })
-
-  it('비정상 값은 0으로 떨어진다', () => {
-    expect(formatBytes(-1)).toBe('0B')
-    expect(formatBytes(NaN)).toBe('0B')
-  })
-})
-
-describe('formatDuration', () => {
-  it('한 시간 미만은 분:초', () => {
-    expect(formatDuration(0)).toBe('00:00')
-    expect(formatDuration(65_000)).toBe('01:05')
-    expect(formatDuration(46 * 60_000 + 6_000)).toBe('46:06')
-  })
-
-  it('한 시간 이상은 시:분:초', () => {
-    expect(formatDuration(3_600_000)).toBe('1:00:00')
-    expect(formatDuration(3_725_000)).toBe('1:02:05')
-  })
-
-  it('음수는 0으로 본다', () => {
-    expect(formatDuration(-5_000)).toBe('00:00')
-  })
-})
-
-describe('RECORDING_AUDIO_CONSTRAINTS', () => {
-  it('원거리 화자를 지우는 전처리를 끈다', () => {
-    // 46분 대면 회의에서 포착률이 10% 안팎에 그친 원인 중 하나.
-    // 이 값이 다시 true로 돌아가면 회귀다.
-    expect(RECORDING_AUDIO_CONSTRAINTS.noiseSuppression).toBe(false)
-    expect(RECORDING_AUDIO_CONSTRAINTS.echoCancellation).toBe(false)
-  })
-
-  it('조용한 화자를 끌어올리는 AGC는 남긴다', () => {
-    expect(RECORDING_AUDIO_CONSTRAINTS.autoGainControl).toBe(true)
-  })
-})

src/__tests__/speakers.test.ts

@@ -0,0 +1,62 @@
+import { describe, it, expect } from 'vitest'
+import {
+  LOCAL_SPEAKER,
+  REMOTE_SPEAKER,
+  diarizedSpeakerId,
+  listAttendees,
+  resolveSpeakerName,
+} from '@/lib/speakers'
+
+describe('resolveSpeakerName', () => {
+  it('기본 화자에 한국어 표기를 붙인다', () => {
+    expect(resolveSpeakerName(LOCAL_SPEAKER)).toBe('나')
+    expect(resolveSpeakerName(REMOTE_SPEAKER)).toBe('상대')
+  })
+
+  it('사용자가 지정한 이름이 우선한다', () => {
+    const names = { [REMOTE_SPEAKER]: '김지훈' }
+    expect(resolveSpeakerName(REMOTE_SPEAKER, names)).toBe('김지훈')
+    expect(resolveSpeakerName(LOCAL_SPEAKER, names)).toBe('나')
+  })
+
+  it('공백뿐인 이름은 무시한다', () => {
+    expect(resolveSpeakerName(LOCAL_SPEAKER, { [LOCAL_SPEAKER]: '   ' })).toBe('나')
+  })
+
+  it('diarization 화자 번호를 한국어 표기로 바꾼다', () => {
+    expect(resolveSpeakerName('spk_1')).toBe('화자 1')
+    expect(resolveSpeakerName('spk_3')).toBe('화자 3')
+  })
+
+  it('diarization 화자에도 지정 이름이 우선한다', () => {
+    expect(resolveSpeakerName('spk_2', { spk_2: '박지연' })).toBe('박지연')
+  })
+
+  it('그 밖의 식별자는 그대로 돌려준다', () => {
+    expect(resolveSpeakerName('unknown')).toBe('unknown')
+  })
+})
+
+describe('listAttendees', () => {
+  it('중복을 제거하고 순서를 유지한다', () => {
+    expect(
+      listAttendees([REMOTE_SPEAKER, LOCAL_SPEAKER, REMOTE_SPEAKER]),
+    ).toEqual(['상대', '나'])
+  })
+
+  it('지정된 이름을 반영한다', () => {
+    expect(
+      listAttendees([LOCAL_SPEAKER, REMOTE_SPEAKER], {
+        [LOCAL_SPEAKER]: '배철승',
+        [REMOTE_SPEAKER]: '김지훈',
+      }),
+    ).toEqual(['배철승', '김지훈'])
+  })
+})
+
+describe('diarizedSpeakerId', () => {
+  it('0-based 번호를 1-based 식별자로 바꾼다', () => {
+    expect(diarizedSpeakerId(0)).toBe('spk_1')
+    expect(diarizedSpeakerId(3)).toBe('spk_4')
+  })
+})

src/__tests__/transcript-formatter.test.ts

@@ -2,6 +2,8 @@ import { describe, it, expect } from 'vitest'
 import {
   formatTranscriptChunks,
   mergeAdjacentChunks,
+  mergeSpeakerChunks,
+  assignSpeakers,
   type TranscriptChunk,
 } from '@/lib/transcript-formatter'
 
@@ -55,3 +57,141 @@ describe('mergeAdjacentChunks', () => {
     expect(result).toEqual([])
   })
 })
+
+describe('화자 표기', () => {
+  it('speaker가 있으면 이름을 붙여 출력한다', () => {
+    const out = formatTranscriptChunks([
+      { text: '안녕하세요', startTime: 0, endTime: 2, isFinal: true, speaker: 'local' },
+      { text: '네 반갑습니다', startTime: 3, endTime: 5, isFinal: true, speaker: 'remote' },
+    ])
+    expect(out).toBe('[00:00] 나: 안녕하세요\n[00:03] 상대: 네 반갑습니다')
+  })
+
+  it('지정된 화자 이름을 사용한다', () => {
+    const out = formatTranscriptChunks(
+      [{ text: '안녕하세요', startTime: 0, endTime: 2, isFinal: true, speaker: 'remote' }],
+      { remote: '김지훈' },
+    )
+    expect(out).toBe('[00:00] 김지훈: 안녕하세요')
+  })
+
+  it('speaker가 없으면 기존 형식을 유지한다', () => {
+    const out = formatTranscriptChunks([
+      { text: '안녕하세요', startTime: 0, endTime: 2, isFinal: true },
+    ])
+    expect(out).toBe('[00:00] 안녕하세요')
+  })
+})
+
+describe('mergeSpeakerChunks', () => {
+  const local = [
+    { text: '먼저 말함', startTime: 1, endTime: 2, isFinal: true, speaker: 'local' },
+    { text: '나중에 말함', startTime: 9, endTime: 10, isFinal: true, speaker: 'local' },
+  ]
+  const remote = [
+    { text: '중간에 답함', startTime: 4, endTime: 6, isFinal: true, speaker: 'remote' },
+  ]
+
+  it('여러 트랙을 시간순으로 합친다', () => {
+    expect(mergeSpeakerChunks(local, remote).map((c) => c.text)).toEqual([
+      '먼저 말함',
+      '중간에 답함',
+      '나중에 말함',
+    ])
+  })
+
+  it('같은 시각이면 넘긴 순서를 유지한다', () => {
+    const a = [{ text: 'A', startTime: 5, endTime: 6, isFinal: true, speaker: 'local' }]
+    const b = [{ text: 'B', startTime: 5, endTime: 6, isFinal: true, speaker: 'remote' }]
+    expect(mergeSpeakerChunks(a, b).map((c) => c.text)).toEqual(['A', 'B'])
+  })
+
+  it('빈 트랙을 섞어도 동작한다', () => {
+    expect(mergeSpeakerChunks([], remote, [])).toEqual(remote)
+    expect(mergeSpeakerChunks()).toEqual([])
+  })
+})
+
+describe('mergeAdjacentChunks — 화자 경계', () => {
+  it('화자가 다르면 간격이 좁아도 합치지 않는다', () => {
+    const merged = mergeAdjacentChunks(
+      [
+        { text: '그건', startTime: 0, endTime: 1, isFinal: true, speaker: 'local' },
+        { text: '어렵습니다', startTime: 1, endTime: 2, isFinal: true, speaker: 'remote' },
+      ],
+      5,
+    )
+    expect(merged).toHaveLength(2)
+  })
+
+  it('같은 화자면 기존대로 합친다', () => {
+    const merged = mergeAdjacentChunks(
+      [
+        { text: '그건', startTime: 0, endTime: 1, isFinal: true, speaker: 'local' },
+        { text: '가능합니다', startTime: 1, endTime: 2, isFinal: true, speaker: 'local' },
+      ],
+      5,
+    )
+    expect(merged).toHaveLength(1)
+    expect(merged[0].text).toBe('그건 가능합니다')
+    expect(merged[0].speaker).toBe('local')
+  })
+})
+
+describe('assignSpeakers', () => {
+  const id = (n: number) => `spk_${n + 1}`
+
+  const chunks: TranscriptChunk[] = [
+    { text: '안녕하세요', startTime: 0, endTime: 3, isFinal: true },
+    { text: '네 반갑습니다', startTime: 5, endTime: 8, isFinal: true },
+    { text: '그럼 시작하죠', startTime: 10, endTime: 12, isFinal: true },
+  ]
+
+  it('시간이 가장 많이 겹치는 화자를 붙인다', () => {
+    const out = assignSpeakers(
+      chunks,
+      [
+        { start: 0, end: 4, speaker: 0 },
+        { start: 4.5, end: 9, speaker: 1 },
+        { start: 9.5, end: 13, speaker: 0 },
+      ],
+      id,
+    )
+    expect(out.map((c) => c.speaker)).toEqual(['spk_1', 'spk_2', 'spk_1'])
+  })
+
+  it('겹치는 구간이 없으면 화자를 비워 둔다', () => {
+    const out = assignSpeakers(
+      chunks,
+      [{ start: 100, end: 110, speaker: 0 }],
+      id,
+    )
+    expect(out.every((c) => c.speaker === undefined)).toBe(true)
+  })
+
+  it('부분적으로만 겹치면 더 많이 겹치는 쪽을 고른다', () => {
+    const out = assignSpeakers(
+      [{ text: '경계에 걸침', startTime: 0, endTime: 10, isFinal: true }],
+      [
+        { start: 0, end: 3, speaker: 0 },
+        { start: 3, end: 10, speaker: 1 },
+      ],
+      id,
+    )
+    expect(out[0].speaker).toBe('spk_2')
+  })
+
+  it('segments가 비면 원본을 그대로 돌려준다', () => {
+    const out = assignSpeakers(chunks, [], id)
+    expect(out).toEqual(chunks)
+  })
+
+  it('기존 화자 라벨은 새 결과로 덮어쓴다', () => {
+    const out = assignSpeakers(
+      [{ text: 'x', startTime: 0, endTime: 2, isFinal: true, speaker: 'spk_9' }],
+      [{ start: 0, end: 2, speaker: 0 }],
+      id,
+    )
+    expect(out[0].speaker).toBe('spk_1')
+  })
+})

src/__tests__/use-audio-recorder.test.ts

@@ -1,239 +0,0 @@
-import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'
-import { act, renderHook, waitFor } from '@testing-library/react'
-import { useAudioRecorder } from '@/hooks/useAudioRecorder'
-
-/**
- * jsdom에는 MediaRecorder도 getUserMedia도 없다. 훅이 다루는 것은
- * "조각이 언제 오고 어디로 가는가"이므로 그 둘만 흉내 내면 충분하다.
- */
-
-class FakeMediaRecorder {
-  static isTypeSupported = () => true
-
-  state: 'inactive' | 'recording' = 'inactive'
-  ondataavailable: ((event: { data: Blob }) => void) | null = null
-  onerror: (() => void) | null = null
-  private listeners: Record<string, Array<() => void>> = {}
-
-  constructor(
-    public stream: MediaStream,
-    public options?: MediaRecorderOptions,
-  ) {
-    instances.push(this)
-  }
-
-  start() {
-    this.state = 'recording'
-  }
-
-  stop() {
-    this.state = 'inactive'
-    // 실제 MediaRecorder는 stop() 시 남은 버퍼를 한 번 더 내보낸 뒤 stop을 쏜다.
-    for (const fn of this.listeners.stop ?? []) fn()
-  }
-
-  addEventListener(type: string, fn: () => void) {
-    ;(this.listeners[type] ??= []).push(fn)
-  }
-
-  emit(bytes: number) {
-    this.ondataavailable?.({ data: new Blob([new Uint8Array(bytes)]) })
-  }
-}
-
-let instances: FakeMediaRecorder[] = []
-let stopTracks: ReturnType<typeof vi.fn>
-let fetchMock: ReturnType<typeof vi.fn>
-
-function jsonResponse(body: unknown, ok = true, status = 200) {
-  return { ok, status, json: async () => body }
-}
-
-beforeEach(() => {
-  instances = []
-  stopTracks = vi.fn()
-
-  vi.stubGlobal('MediaRecorder', FakeMediaRecorder)
-  vi.stubGlobal('navigator', {
-    mediaDevices: {
-      getUserMedia: vi.fn(async () => ({
-        getTracks: () => [{ stop: stopTracks }],
-      })),
-    },
-  })
-
-  fetchMock = vi.fn(async (url: string) => {
-    if (url === '/api/recordings') {
-      return jsonResponse({ id: 'a'.repeat(32), mimeType: 'audio/webm' }, true, 201)
-    }
-    if (url.endsWith('/chunk')) return jsonResponse({ bytes: 1024 })
-    return jsonResponse({ bytes: 1024 })
-  })
-  vi.stubGlobal('fetch', fetchMock)
-})
-
-afterEach(() => {
-  vi.unstubAllGlobals()
-})
-
-async function startedHook() {
-  const view = renderHook(() => useAudioRecorder())
-  await waitFor(() => expect(view.result.current.isSupported).toBe(true))
-  await act(async () => {
-    await view.result.current.startRecording()
-  })
-  return view
-}
-
-describe('useAudioRecorder — 캡처 제약', () => {
-  it('원거리 화자를 지우는 전처리를 끄고 마이크를 연다', async () => {
-    await startedHook()
-
-    expect(navigator.mediaDevices.getUserMedia).toHaveBeenCalledWith({
-      audio: expect.objectContaining({
-        noiseSuppression: false,
-        echoCancellation: false,
-        autoGainControl: true,
-      }),
-    })
-  })
-})
-
-describe('useAudioRecorder — 조각 업로드', () => {
-  it('조각이 생길 때마다 서버로 올린다', async () => {
-    const view = await startedHook()
-
-    await act(async () => {
-      instances[0].emit(2048)
-    })
-
-    await waitFor(() => {
-      const chunkCalls = fetchMock.mock.calls.filter((c) =>
-        String(c[0]).endsWith('/chunk'),
-      )
-      expect(chunkCalls).toHaveLength(1)
-    })
-
-    expect(view.result.current.localBytes).toBe(2048)
-  })
-
-  it('빈 조각은 올리지 않는다', async () => {
-    await startedHook()
-
-    await act(async () => {
-      instances[0].emit(0)
-    })
-
-    const chunkCalls = fetchMock.mock.calls.filter((c) =>
-      String(c[0]).endsWith('/chunk'),
-    )
-    expect(chunkCalls).toHaveLength(0)
-  })
-
-  it('업로드가 끝내 실패하면 뒤 조각을 이어 붙이지 않고 경고한다', async () => {
-    // 중간이 빈 파일은 짧은 파일보다 나쁘다 — 재생도 전사도 안 된다.
-    fetchMock.mockImplementation(async (url: string) => {
-      if (url === '/api/recordings') {
-        return jsonResponse({ id: 'a'.repeat(32) }, true, 201)
-      }
-      if (url.endsWith('/chunk')) return jsonResponse({ error: 'nope' }, false, 500)
-      return jsonResponse({})
-    })
-
-    const view = await startedHook()
-
-    await act(async () => {
-      instances[0].emit(1024)
-    })
-
-    // 500은 일시 장애일 수 있으므로 백오프를 두고 3회까지 재시도한다.
-    await waitFor(
-      () => {
-        expect(view.result.current.uploadWarning).toContain('서버 저장이 중단')
-      },
-      { timeout: 5_000 },
-    )
-
-    const callsAfterBreak = fetchMock.mock.calls.filter((c) =>
-      String(c[0]).endsWith('/chunk'),
-    ).length
-
-    await act(async () => {
-      instances[0].emit(1024)
-    })
-
-    expect(
-      fetchMock.mock.calls.filter((c) => String(c[0]).endsWith('/chunk')).length,
-    ).toBe(callsAfterBreak)
-  })
-
-  it('세션 생성이 실패해도 녹음은 계속된다', async () => {
-    fetchMock.mockImplementation(async (url: string) => {
-      if (url === '/api/recordings') {
-        return jsonResponse({ error: 'down' }, false, 500)
-      }
-      return jsonResponse({})
-    })
-
-    const view = await startedHook()
-
-    expect(view.result.current.isRecording).toBe(true)
-    expect(view.result.current.uploadWarning).toContain('내려받아')
-
-    await act(async () => {
-      instances[0].emit(4096)
-    })
-    expect(view.result.current.localBytes).toBe(4096)
-  })
-})
-
-describe('useAudioRecorder — 종료', () => {
-  it('오디오를 한 조각도 못 받았으면 보관됐다고 말하지 않는다', async () => {
-    const view = await startedHook()
-
-    await act(async () => {
-      await view.result.current.stopRecording()
-    })
-
-    expect(view.result.current.recording).toBeNull()
-    expect(view.result.current.error).toContain('한 조각도 캡처되지 않았습니다')
-    expect(view.result.current.isRecording).toBe(false)
-  })
-
-  it('받은 조각이 있으면 결과를 넘기고 마이크를 놓는다', async () => {
-    const view = await startedHook()
-
-    await act(async () => {
-      instances[0].emit(1024)
-    })
-    await act(async () => {
-      await view.result.current.stopRecording()
-    })
-
-    expect(view.result.current.recording?.blob.size).toBe(1024)
-    expect(view.result.current.recording?.recordingId).toBe('a'.repeat(32))
-    expect(stopTracks).toHaveBeenCalled()
-    expect(view.result.current.isRecording).toBe(false)
-  })
-
-  it('서버 사본이 로컬보다 짧으면 경고한다', async () => {
-    fetchMock.mockImplementation(async (url: string) => {
-      if (url === '/api/recordings') {
-        return jsonResponse({ id: 'a'.repeat(32) }, true, 201)
-      }
-      if (url.endsWith('/chunk')) return jsonResponse({ bytes: 10 })
-      return jsonResponse({ bytes: 10 })
-    })
-
-    const view = await startedHook()
-
-    await act(async () => {
-      instances[0].emit(4096)
-    })
-    await act(async () => {
-      await view.result.current.stopRecording()
-    })
-
-    expect(view.result.current.uploadWarning).toContain('서버 사본이 로컬보다 짧습니다')
-  })
-})

src/app/api/diarize/chunk/route.ts

@@ -0,0 +1,30 @@
+import { NextRequest } from 'next/server'
+import { appendAudio } from '@/lib/audio-session'
+
+export const dynamic = 'force-dynamic'
+
+/** 녹음 중 몇 초짜리 PCM 조각을 이어 붙인다. 본문은 16kHz 모노 Int16 raw PCM. */
+export async function POST(request: NextRequest) {
+  const sessionId = request.nextUrl.searchParams.get('session')?.trim()
+  if (!sessionId) {
+    return Response.json({ error: 'session 파라미터가 필요합니다.' }, { status: 400 })
+  }
+
+  const buffer = await request.arrayBuffer()
+  if (buffer.byteLength === 0) {
+    return Response.json({ error: '오디오가 비어 있습니다.' }, { status: 400 })
+  }
+  if (buffer.byteLength % 2 !== 0) {
+    return Response.json(
+      { error: 'Int16 PCM이 아닙니다 (홀수 바이트).' },
+      { status: 400 },
+    )
+  }
+
+  const result = appendAudio(sessionId, new Int16Array(buffer))
+  if (!result.ok) {
+    return Response.json({ error: result.error }, { status: 413 })
+  }
+
+  return Response.json({ seconds: Math.round(result.seconds) })
+}

src/app/api/diarize/route.ts

@@ -0,0 +1,55 @@
+import { NextRequest } from 'next/server'
+import { clearSession, collectSamples, sessionSeconds } from '@/lib/audio-session'
+import { diarize, modelsInstalled } from '@/lib/diarization'
+
+export const dynamic = 'force-dynamic'
+
+export async function GET() {
+  return Response.json({ available: modelsInstalled() })
+}
+
+/**
+ * 누적된 오디오 전체에 화자 분리를 돌린다.
+ *
+ * 창을 잘라 반복 실행하면 실행마다 화자 번호가 달라져 이어 붙일 수 없다.
+ * 전역 클러스터링을 위해 녹음 종료 시 한 번만 돌린다.
+ */
+export async function POST(request: NextRequest) {
+  try {
+    const body = await request.json().catch(() => ({}))
+    const sessionId = typeof body.session === 'string' ? body.session.trim() : ''
+
+    if (!sessionId) {
+      return Response.json({ error: 'session이 필요합니다.' }, { status: 400 })
+    }
+
+    const samples = collectSamples(sessionId)
+    if (!samples) {
+      return Response.json({ error: '누적된 오디오가 없습니다.' }, { status: 400 })
+    }
+
+    const numSpeakers =
+      typeof body.numSpeakers === 'number' && body.numSpeakers > 1
+        ? Math.floor(body.numSpeakers)
+        : undefined
+
+    const seconds = sessionSeconds(sessionId)
+    const result = await diarize(samples, { numSpeakers })
+
+    if (!result.success) {
+      const status = result.reason === 'models-missing' ? 503 : 500
+      return Response.json({ error: result.error, reason: result.reason }, { status })
+    }
+
+    clearSession(sessionId)
+
+    return Response.json({
+      segments: result.segments,
+      seconds: Math.round(seconds),
+      speakers: new Set(result.segments.map((s) => s.speaker)).size,
+    })
+  } catch (err) {
+    const message = err instanceof Error ? err.message : '알 수 없는 오류'
+    return Response.json({ error: `화자 분리 실패: ${message}` }, { status: 500 })
+  }
+}

src/app/api/meetings/route.ts

@@ -79,9 +79,6 @@ export async function POST(request: NextRequest) {
       customPrompt,
       attendees,
       tags,
-      audioFileName,
-      audioMimeType,
-      audioDuration,
     } = body
 
     if (!title || typeof title !== 'string' || title.trim().length === 0) {
@@ -115,14 +112,6 @@ export async function POST(request: NextRequest) {
         tags: Array.isArray(tags)
           ? tags.filter((t) => typeof t === 'string')
           : [],
-        audioFileName:
-          typeof audioFileName === 'string' ? audioFileName : null,
-        audioMimeType:
-          typeof audioMimeType === 'string' ? audioMimeType : null,
-        audioDuration:
-          typeof audioDuration === 'number' && Number.isFinite(audioDuration)
-            ? Math.max(0, Math.round(audioDuration))
-            : null,
         status: 'COMPLETED',
         actionItems: {
           create: parsed.map((item, index) => ({

src/app/api/recordings/[id]/chunk/route.ts

@@ -1,55 +0,0 @@
-import { NextRequest } from 'next/server'
-import { appendChunk } from '@/lib/recording-store'
-import { MAX_CHUNK_BYTES, isValidRecordingId } from '@/lib/recording'
-
-export const dynamic = 'force-dynamic'
-
-interface RouteContext {
-  params: Promise<{ id: string }>
-}
-
-/**
- * 녹음 조각 하나를 이어 붙인다.
- *
- * 본문은 MediaRecorder가 준 바이트 그대로다. JSON이나 multipart로 감싸면
- * base64 팽창이나 파싱 비용만 늘어난다.
- */
-export async function POST(request: NextRequest, context: RouteContext) {
-  try {
-    const { id } = await context.params
-
-    if (!isValidRecordingId(id)) {
-      return Response.json(
-        { error: '잘못된 녹음 세션 ID입니다.' },
-        { status: 400 },
-      )
-    }
-
-    const buffer = Buffer.from(await request.arrayBuffer())
-
-    if (buffer.byteLength === 0) {
-      return Response.json({ error: '빈 조각입니다.' }, { status: 400 })
-    }
-
-    if (buffer.byteLength > MAX_CHUNK_BYTES) {
-      return Response.json(
-        { error: '조각이 너무 큽니다.' },
-        { status: 413 },
-      )
-    }
-
-    const result = await appendChunk(id, buffer)
-
-    if (!result.ok) {
-      return Response.json({ error: result.error }, { status: result.status })
-    }
-
-    return Response.json({ bytes: result.bytes })
-  } catch (err) {
-    const message = err instanceof Error ? err.message : '알 수 없는 오류'
-    return Response.json(
-      { error: `녹음 조각 저장 실패: ${message}` },
-      { status: 500 },
-    )
-  }
-}

src/app/api/recordings/[id]/route.ts

@@ -1,86 +0,0 @@
-import { NextRequest } from 'next/server'
-import { Readable } from 'stream'
-import { finalizeRecording, getRecordingStatus, openRecording } from '@/lib/recording-store'
-import { extensionForMimeType, isValidRecordingId } from '@/lib/recording'
-
-export const dynamic = 'force-dynamic'
-
-interface RouteContext {
-  params: Promise<{ id: string }>
-}
-
-/** 녹음 파일 내려받기. 헤더에는 사용자 입력을 넣지 않는다. */
-export async function GET(_request: NextRequest, context: RouteContext) {
-  const { id } = await context.params
-
-  if (!isValidRecordingId(id)) {
-    return Response.json({ error: '잘못된 녹음 세션 ID입니다.' }, { status: 400 })
-  }
-
-  const opened = await openRecording(id)
-  if (!opened) {
-    return Response.json({ error: '녹음을 찾을 수 없습니다.' }, { status: 404 })
-  }
-
-  const { meta, bytes, stream } = opened
-  const stamp = meta.startedAt.slice(0, 16).replace(/[-:]/g, '').replace('T', '-')
-  const fileName = `meeting-${stamp}.${extensionForMimeType(meta.mimeType)}`
-
-  return new Response(Readable.toWeb(stream as Readable) as ReadableStream, {
-    headers: {
-      'Content-Type': meta.mimeType,
-      'Content-Length': String(bytes),
-      'Content-Disposition': `attachment; filename="${fileName}"`,
-      'Cache-Control': 'no-store',
-    },
-  })
-}
-
-/** 녹음 종료. 길이를 확정하고 최종 상태를 돌려준다. */
-export async function POST(request: NextRequest, context: RouteContext) {
-  try {
-    const { id } = await context.params
-
-    if (!isValidRecordingId(id)) {
-      return Response.json(
-        { error: '잘못된 녹음 세션 ID입니다.' },
-        { status: 400 },
-      )
-    }
-
-    const body = await request.json().catch(() => ({}))
-    const durationMs =
-      typeof body.durationMs === 'number' ? body.durationMs : null
-
-    const status = await finalizeRecording(id, durationMs)
-    if (!status) {
-      return Response.json(
-        { error: '녹음을 찾을 수 없습니다.' },
-        { status: 404 },
-      )
-    }
-
-    return Response.json(status)
-  } catch (err) {
-    const message = err instanceof Error ? err.message : '알 수 없는 오류'
-    return Response.json(
-      { error: `녹음 종료 처리 실패: ${message}` },
-      { status: 500 },
-    )
-  }
-}
-
-/** 현재까지 저장된 크기 확인용. */
-export async function HEAD(_request: NextRequest, context: RouteContext) {
-  const { id } = await context.params
-
-  if (!isValidRecordingId(id)) return new Response(null, { status: 400 })
-
-  const status = await getRecordingStatus(id)
-  if (!status) return new Response(null, { status: 404 })
-
-  return new Response(null, {
-    status: 200,
-    headers: { 'Content-Length': String(status.bytes) },
-  })
-}

src/app/api/recordings/route.ts

@@ -1,31 +0,0 @@
-import { NextRequest } from 'next/server'
-import { createRecording } from '@/lib/recording-store'
-import { PREFERRED_MIME_TYPES } from '@/lib/recording'
-
-export const dynamic = 'force-dynamic'
-
-/** 브라우저가 고른 mimeType만 허용한다. 임의 문자열이 확장자로 새어들면 안 된다. */
-const ALLOWED_MIME_TYPES: readonly string[] = PREFERRED_MIME_TYPES
-
-export async function POST(request: NextRequest) {
-  try {
-    const body = await request.json().catch(() => ({}))
-    const { mimeType } = body
-
-    if (typeof mimeType !== 'string' || !ALLOWED_MIME_TYPES.includes(mimeType)) {
-      return Response.json(
-        { error: '지원하지 않는 오디오 형식입니다.' },
-        { status: 400 },
-      )
-    }
-
-    const meta = await createRecording(mimeType)
-    return Response.json(meta, { status: 201 })
-  } catch (err) {
-    const message = err instanceof Error ? err.message : '알 수 없는 오류'
-    return Response.json(
-      { error: `녹음 세션 생성 실패: ${message}` },
-      { status: 500 },
-    )
-  }
-}

src/app/page.tsx

@@ -1,11 +1,9 @@
 'use client'
 
-import { useCallback, useMemo, useState } from 'react'
+import { useMemo, useState } from 'react'
 import Link from 'next/link'
 import { AudioUploader } from '@/components/upload/AudioUploader'
 import { LiveRecorder } from '@/components/recorder/LiveRecorder'
-import type { CompletedRecording } from '@/hooks/useAudioRecorder'
-import { extensionForMimeType } from '@/lib/recording'
 import { MinutesViewer } from '@/components/minutes/MinutesViewer'
 import { getProviderRequestPayload } from '@/lib/api-key-storage'
 import {
@@ -45,7 +43,6 @@ export default function HomePage() {
   const [loading, setLoading] = useState(false)
   const [error, setError] = useState<string | null>(null)
   const [uploadedFile, setUploadedFile] = useState<File | null>(null)
-  const [audio, setAudio] = useState<CompletedRecording | null>(null)
 
   const templateList = useMemo(
     () => [
@@ -149,19 +146,6 @@ export default function HomePage() {
     generateMinutes(text, summaryMode)
   }
 
-  const handleRecordingReady = useCallback((recording: CompletedRecording) => {
-    setAudio(recording)
-  }, [])
-
-  // 회의록과 함께 저장할 오디오 정보. 서버 사본이 없으면 붙일 게 없다.
-  const audioMeta = audio?.recordingId
-    ? {
-        audioFileName: `${audio.recordingId}.${extensionForMimeType(audio.mimeType)}`,
-        audioMimeType: audio.mimeType,
-        audioDuration: Math.round(audio.durationMs / 1000),
-      }
-    : undefined
-
   const liveSummaryActive =
     summaryMode === 'gemini' && activeTemplateMeta.live && tab === 'record'
 
@@ -344,8 +328,6 @@ export default function HomePage() {
           {tab === 'record' ? (
             <LiveRecorder
               onTranscriptReady={handleTranscriptReady}
-              onRecordingReady={handleRecordingReady}
-              title={title}
               liveSummaryEnabled={liveSummaryActive}
               template={template}
               depth={depth}
@@ -409,7 +391,6 @@ export default function HomePage() {
             depth={depth}
             customPrompt={template === 'custom' ? customPrompt : undefined}
             summaryMode={summaryMode}
-            audio={audioMeta}
           />
         )}
       </div>

src/components/minutes/MinutesViewer.tsx

@@ -22,12 +22,6 @@ interface MinutesViewerProps {
   depth?: SummaryDepth
   customPrompt?: string
   summaryMode?: 'simple' | 'gemini'
-  /** 이 회의록의 원본 오디오. 서버에 보관된 녹음이 있을 때만 붙는다. */
-  audio?: {
-    audioFileName: string
-    audioMimeType: string
-    audioDuration: number
-  }
 }
 
 type SaveState =
@@ -44,7 +38,6 @@ export function MinutesViewer({
   template,
   depth,
   customPrompt,
-  audio,
   summaryMode,
 }: MinutesViewerProps) {
   const [renderedView, setRenderedView] = useState<'rendered' | 'raw'>(
@@ -117,7 +110,6 @@ export function MinutesViewer({
           template,
           depth,
           customPrompt,
-          ...audio,
         }),
       })
       const data = await res.json()

src/components/recorder/LiveRecorder.tsx

@@ -1,17 +1,28 @@
 'use client'
 
-import { useEffect, useRef } from 'react'
+import { useEffect, useMemo, useRef, useState } from 'react'
 import { useSpeechRecognition } from '@/hooks/useSpeechRecognition'
+import { useDualStreamCapture } from '@/hooks/useDualStreamCapture'
+import { useDiarization } from '@/hooks/useDiarization'
 import { useLiveSummary } from '@/hooks/useLiveSummary'
-import { useAudioRecorder, type CompletedRecording } from '@/hooks/useAudioRecorder'
+import {
-import { formatTranscriptChunks } from '@/lib/transcript-formatter'
+  assignSpeakers,
-import { formatBytes, formatDuration } from '@/lib/recording'
+  formatTranscriptChunks,
+  mergeSpeakerChunks,
+  type TimeSpan,
+} from '@/lib/transcript-formatter'
+import {
+  LOCAL_SPEAKER,
+  REMOTE_SPEAKER,
+  diarizedSpeakerId,
+  resolveSpeakerName,
+} from '@/lib/speakers'
 import type { SummaryDepth, TemplateId } from '@/lib/templates'
 
+type SeparationMode = 'off' | 'remote' | 'in-person'
+
 interface LiveRecorderProps {
   onTranscriptReady: (transcript: string) => void
-  onRecordingReady?: (recording: CompletedRecording) => void
-  title: string
   liveSummaryEnabled: boolean
   template: TemplateId
   depth: SummaryDepth
@@ -20,38 +31,68 @@ interface LiveRecorderProps {
 
 export function LiveRecorder({
   onTranscriptReady,
-  onRecordingReady,
-  title,
   liveSummaryEnabled,
   template,
   depth,
   customPrompt,
 }: LiveRecorderProps) {
+  const [mode, setMode] = useState<SeparationMode>('off')
+  const [attendeeCount, setAttendeeCount] = useState(2)
+  const [pendingStart, setPendingStart] = useState(false)
+  const [speakerNames, setSpeakerNames] = useState<Record<string, string>>({})
+  const [segments, setSegments] = useState<TimeSpan[] | null>(null)
+  const timeOriginRef = useRef(0)
+
+  const capture = useDualStreamCapture()
+  const diarization = useDiarization()
+
+  const speakerSeparation = mode !== 'off'
+
+  // 화자 분리를 켜면 트랙마다 인식기를 붙인다. 트랙이 곧 화자가 되므로
+  // 추론 없이 화자가 갈린다.
+  // 두 트랙을 실제로 확보했을 때만 화자를 라벨링한다.
+  // 마이크만 잡힌 상태에서 라벨을 붙이면 상대 발언이 내 것으로 기록된다.
+  const isSeparating = capture.mode === 'dual-stream'
+
+  const local = useSpeechRecognition({
+    audioTrack: speakerSeparation ? capture.micTrack : null,
+    speaker: isSeparating ? LOCAL_SPEAKER : undefined,
+    timeOrigin: timeOriginRef.current || undefined,
+  })
+
+  const remote = useSpeechRecognition({
+    audioTrack: capture.systemTrack,
+    speaker: REMOTE_SPEAKER,
+    timeOrigin: timeOriginRef.current || undefined,
+  })
+
   const {
     isListening,
     isSupported,
-    chunks,
     interimText,
     error: recognitionError,
     startListening,
-    stopListening,
+  } = local
-    resetChunks,
-  } = useSpeechRecognition()
 
-  const {
+  const chunks = useMemo(() => {
-    isRecording,
+    if (isSeparating) return mergeSpeakerChunks(local.chunks, remote.chunks)
-    isSupported: isRecordingSupported,
+    if (segments) return assignSpeakers(local.chunks, segments, diarizedSpeakerId)
-    error: recordingError,
+    return local.chunks
-    uploadWarning,
+  }, [isSeparating, segments, local.chunks, remote.chunks])
-    elapsedMs,
+
-    localBytes,
+  // 캡처가 끝나 트랙이 준비되면 그때 인식기를 시작한다.
-    uploadedBytes,
+  useEffect(() => {
-    recording,
+    if (!pendingStart) return
-    startRecording,
+    if (capture.mode === 'idle') return
-    stopRecording,
+
-    downloadRecording,
+    setPendingStart(false)
-    reset: resetRecording,
+    local.startListening()
-  } = useAudioRecorder()
+    if (capture.systemTrack) remote.startListening()
+    if (mode === 'in-person' && capture.micTrack) {
+      diarization.start(capture.micTrack)
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [pendingStart, capture.mode, capture.systemTrack, capture.micTrack])
 
   const {
     summary,
@@ -80,11 +121,6 @@ export function LiveRecorder({
     summaryEndRef.current?.scrollIntoView({ behavior: 'smooth', block: 'end' })
   }, [summary])
 
-  // 녹음이 끝나 파일이 확정되면 상위로 올려 회의록과 함께 저장되게 한다.
-  useEffect(() => {
-    if (recording) onRecordingReady?.(recording)
-  }, [recording, onRecordingReady])
-
   if (isSupported === null) {
     return (
       <div className="rounded-2xl border border-neutral-200 bg-neutral-50 p-6 text-center text-sm text-neutral-400">
@@ -105,21 +141,45 @@ export function LiveRecorder({
   }
 
   async function handleStart() {
-    resetRecording()
+    timeOriginRef.current = Date.now()
-    // 오디오 녹음을 먼저 건다. 전사가 실패하더라도 원본은 남아야 한다.
+    setSegments(null)
-    await startRecording()
+
-    startListening()
+    if (mode === 'off') {
+      startListening()
+      return
+    }
+
+    setPendingStart(true)
+    await capture.start({ withSystemAudio: mode === 'remote' })
   }
 
   async function handleStop() {
-    stopListening()
+    local.stopListening()
+    remote.stopListening()
 
-    const transcript = formatTranscriptChunks(chunks)
+    // 대면 모드는 녹음이 끝난 뒤 전체 오디오에 한 번 화자 분리를 돌린다.
+    let finalChunks = chunks
+    if (mode === 'in-person') {
+      const result = await diarization.finish(attendeeCount)
+      if (result.length > 0) {
+        setSegments(result)
+        finalChunks = assignSpeakers(local.chunks, result, diarizedSpeakerId)
+      }
+    }
+
+    capture.stop()
+
+    const transcript = formatTranscriptChunks(finalChunks, speakerNames)
     if (transcript.length > 0) {
       onTranscriptReady(transcript)
     }
+  }
 
-    await stopRecording()
+  function handleReset() {
+    local.resetChunks()
+    remote.resetChunks()
+    diarization.reset()
+    setSegments(null)
   }
 
   const lastUpdatedLabel = lastUpdatedAt
@@ -180,21 +240,9 @@ export function LiveRecorder({
           </button>
         )}
 
-        {recording && !isListening && (
-          <button
-            onClick={() => downloadRecording(title)}
-            className="flex items-center gap-2 rounded-full border border-emerald-300 bg-emerald-50 px-4 py-2 text-sm font-medium text-emerald-700 hover:bg-emerald-100 transition-colors"
-          >
-            ⬇️ 오디오 내려받기 ({formatBytes(recording.blob.size)})
-          </button>
-        )}
-
         {chunks.length > 0 && !isListening && (
           <button
-            onClick={() => {
+            onClick={handleReset}
-              resetChunks()
-              resetRecording()
-            }}
             className="rounded-full border border-neutral-300 px-4 py-2 text-sm text-neutral-600 hover:bg-neutral-50 transition-colors"
           >
             초기화
@@ -208,35 +256,145 @@ export function LiveRecorder({
           </div>
         )}
 
-        {isRecording && (
+        {isListening && capture.mode === 'dual-stream' && (
-          <div className="flex items-center gap-2 rounded-full bg-neutral-100 px-4 py-1.5 text-xs text-neutral-600">
+          <div className="flex items-center gap-1.5 rounded-full bg-purple-50 px-4 py-1.5 text-xs text-purple-700">
-            <span className="text-sm">🎧</span>
+            <span className="h-2 w-2 rounded-full bg-purple-500" />
-            오디오 {formatDuration(elapsedMs)} · 저장 {formatBytes(uploadedBytes)}
+            화자 분리 중
-            {localBytes > 0 && uploadedBytes < localBytes && (
-              <span className="text-amber-600">
-                (전송 대기 {formatBytes(localBytes - uploadedBytes)})
-              </span>
-            )}
           </div>
         )}
       </div>
 
-      {isRecordingSupported === false && (
+      {!isListening && chunks.length === 0 && (
-        <div className="rounded-xl border border-amber-200 bg-amber-50 p-4 text-sm text-amber-800">
+        <div className="rounded-xl border border-neutral-200 bg-white p-4">
-          이 브라우저는 오디오 녹음을 지원하지 않습니다. 전사만 진행되며,
+          <p className="mb-3 text-sm font-medium text-neutral-800">화자 분리</p>
-          <strong> 놓친 발화를 나중에 복구할 수 없습니다.</strong> Chrome을 사용해주세요.
+
+          <div className="flex flex-wrap gap-2">
+            {(
+              [
+                { id: 'off', label: '사용 안 함' },
+                { id: 'remote', label: '원격 회의' },
+                { id: 'in-person', label: '대면 회의' },
+              ] as const
+            ).map((option) => (
+              <button
+                key={option.id}
+                onClick={() => setMode(option.id)}
+                disabled={option.id === 'in-person' && diarization.available === false}
+                className={`rounded-lg border px-3 py-2 text-sm font-medium transition-all disabled:opacity-40 ${
+                  mode === option.id
+                    ? 'border-purple-400 bg-purple-50 text-purple-700'
+                    : 'border-neutral-200 bg-white text-neutral-600 hover:border-neutral-300'
+                }`}
+              >
+                {option.label}
+              </button>
+            ))}
+          </div>
+
+          {mode === 'remote' && (
+            <>
+              <p className="mt-3 text-xs text-neutral-500">
+                내 마이크와 상대 목소리를 별도 트랙으로 받아 구분합니다. 추론이 없어
+                정확합니다. 시작 시{' '}
+                <strong>화면 공유 대화상자에서 &ldquo;탭 오디오 공유&rdquo;를 반드시 켜주세요.</strong>
+              </p>
+              <p className="mt-1.5 text-xs text-amber-700">
+                노트북 한 대를 두고 마주 앉은 대면 회의에서는 동작하지 않습니다.
+                그 경우 &ldquo;대면 회의&rdquo;를 선택하세요.
+              </p>
+              <div className="mt-4 grid gap-3 sm:grid-cols-2">
+                {(
+                  [
+                    { id: LOCAL_SPEAKER, label: '내 이름', placeholder: '나' },
+                    { id: REMOTE_SPEAKER, label: '상대 이름', placeholder: '상대' },
+                  ] as const
+                ).map((field) => (
+                  <label key={field.id} className="block">
+                    <span className="mb-1 block text-xs text-neutral-500">
+                      {field.label}
+                    </span>
+                    <input
+                      type="text"
+                      value={speakerNames[field.id] ?? ''}
+                      onChange={(e) =>
+                        setSpeakerNames((prev) => ({
+                          ...prev,
+                          [field.id]: e.target.value,
+                        }))
+                      }
+                      placeholder={field.placeholder}
+                      className="w-full rounded-lg border border-neutral-300 px-3 py-2 text-sm focus:border-purple-400 focus:outline-none"
+                    />
+                  </label>
+                ))}
+              </div>
+            </>
+          )}
+
+          {mode === 'in-person' && (
+            <>
+              <p className="mt-3 text-xs text-neutral-500">
+                마이크 하나에 섞여 들어온 목소리를 내 PC에서 분석해 화자를 나눕니다.
+                외부로 오디오를 보내지 않습니다.{' '}
+                <strong>녹음이 끝난 뒤 한 번에 분석</strong>하므로 실시간 화자 표시는 없습니다.
+              </p>
+              <label className="mt-4 block max-w-40">
+                <span className="mb-1 block text-xs text-neutral-500">참석자 수</span>
+                <input
+                  type="number"
+                  min={2}
+                  max={8}
+                  value={attendeeCount}
+                  onChange={(e) =>
+                    setAttendeeCount(Math.max(2, Math.min(8, Number(e.target.value) || 2)))
+                  }
+                  className="w-full rounded-lg border border-neutral-300 px-3 py-2 text-sm focus:border-purple-400 focus:outline-none"
+                />
+                <span className="mt-1 block text-xs text-neutral-500">
+                  정확한 수를 넣을수록 결과가 좋아집니다. 자동 추정은 화자 수를 잘못 세는
+                  경우가 많습니다.
+                </span>
+              </label>
+            </>
+          )}
+
+          {diarization.available === false && (
+            <p className="mt-3 text-xs text-amber-700">
+              대면 회의 화자 분리를 쓰려면 모델이 필요합니다 —{' '}
+              <code className="rounded bg-amber-50 px-1">npm run setup:diarization</code>{' '}
+              을 실행한 뒤 서버를 다시 시작하세요.
+            </p>
+          )}
         </div>
       )}
 
-      {recordingError && (
+      {diarization.status.state === 'analyzing' && (
+        <div className="rounded-xl border border-purple-200 bg-purple-50 p-4 text-sm text-purple-700">
+          화자를 분석하는 중입니다... 회의가 길수록 시간이 걸립니다.
+        </div>
+      )}
+
+      {diarization.status.state === 'done' && (
+        <div className="rounded-xl border border-green-200 bg-green-50 p-4 text-sm text-green-700">
+          화자 {diarization.status.speakers}명을 구분했습니다.
+        </div>
+      )}
+
+      {diarization.status.state === 'error' && (
         <div className="rounded-xl border border-red-200 bg-red-50 p-4 text-sm text-red-700">
-          <strong>오디오 녹음 오류:</strong> {recordingError}
+          <strong>화자 분리 오류:</strong> {diarization.status.message}
         </div>
       )}
 
-      {uploadWarning && (
+      {capture.error && (
+        <div className="rounded-xl border border-red-200 bg-red-50 p-4 text-sm text-red-700">
+          <strong>오디오 캡처 오류:</strong> {capture.error}
+        </div>
+      )}
+
+      {capture.warning && (
         <div className="rounded-xl border border-amber-200 bg-amber-50 p-4 text-sm text-amber-800">
-          <strong>⚠️ 서버 저장 문제:</strong> {uploadWarning}
+          ⚠️ {capture.warning}
         </div>
       )}
 
@@ -246,23 +404,6 @@ export function LiveRecorder({
         </div>
       )}
 
-      {recording && !isListening && (
-        <div className="rounded-xl border border-emerald-200 bg-emerald-50 p-4 text-sm text-emerald-800">
-          <strong>
-            🎧 오디오 {formatDuration(recording.durationMs)} ·{' '}
-            {formatBytes(recording.blob.size)} 확보
-          </strong>
-          {' — '}
-          {recording.recordingId
-            ? `서버에 ${formatBytes(recording.uploadedBytes)} 저장됨.`
-            : '서버 저장 실패 — 브라우저 사본만 있습니다.'}{' '}
-          전사가 놓친 발화는 이 오디오로 다시 살릴 수 있습니다.
-          {!recording.recordingId && (
-            <strong> 지금 내려받아 보관해주세요.</strong>
-          )}
-        </div>
-      )}
-
       {isListening && !hasTranscript && (
         <div className="rounded-2xl border border-dashed border-blue-300 bg-blue-50/50 p-6 text-center">
           <p className="text-sm text-blue-700">
@@ -300,7 +441,20 @@ export function LiveRecorder({
               {hasTranscript ? (
                 <div className="space-y-1 text-sm font-mono leading-relaxed text-neutral-700">
                   {chunks.map((chunk, i) => (
-                    <p key={i}>{chunk.text}</p>
+                    <p key={i}>
+                      {chunk.speaker && (
+                        <span
+                          className={`mr-1.5 font-semibold ${
+                            chunk.speaker === LOCAL_SPEAKER
+                              ? 'text-purple-600'
+                              : 'text-teal-600'
+                          }`}
+                        >
+                          {resolveSpeakerName(chunk.speaker, speakerNames)}:
+                        </span>
+                      )}
+                      {chunk.text}
+                    </p>
                   ))}
                   {interimText && (
                     <p className="text-neutral-400 italic">

src/hooks/useAudioRecorder.ts

@@ -1,390 +0,0 @@
-'use client'
-
-import { useCallback, useEffect, useRef, useState } from 'react'
-import {
-  AUDIO_BITS_PER_SECOND,
-  CHUNK_INTERVAL_MS,
-  RECORDING_AUDIO_CONSTRAINTS,
-  pickRecorderMimeType,
-  recordingDownloadName,
-} from '@/lib/recording'
-
-export interface CompletedRecording {
-  /** 서버 세션 id. 세션 생성에 실패했으면 null이고 로컬 사본만 있다. */
-  recordingId: string | null
-  mimeType: string
-  blob: Blob
-  durationMs: number
-  startedAt: Date
-  /** 서버에 실제로 저장된 바이트. 0이거나 blob보다 작으면 일부가 못 올라갔다. */
-  uploadedBytes: number
-}
-
-export interface AudioRecorderHook {
-  isRecording: boolean
-  isSupported: boolean | null
-  /** 녹음을 시작조차 못하게 만든 오류. */
-  error: string | null
-  /** 녹음은 되고 있으나 서버 사본에 문제가 있을 때의 경고. */
-  uploadWarning: string | null
-  elapsedMs: number
-  localBytes: number
-  uploadedBytes: number
-  recording: CompletedRecording | null
-  startRecording: () => Promise<void>
-  stopRecording: () => Promise<void>
-  downloadRecording: (title: string) => void
-  reset: () => void
-}
-
-const MAX_CHUNK_RETRIES = 3
-
-function describeCaptureError(err: unknown): string {
-  const name = err instanceof Error ? err.name : ''
-
-  switch (name) {
-    case 'NotAllowedError':
-    case 'SecurityError':
-      return '마이크 권한이 거부되어 녹음할 수 없습니다. 주소창 왼쪽 자물쇠 아이콘에서 마이크를 허용해주세요.'
-    case 'NotFoundError':
-      return '마이크를 찾을 수 없습니다. 장치가 연결되어 있는지 확인해주세요.'
-    case 'NotReadableError':
-      return '다른 프로그램이 마이크를 사용 중입니다. 해당 프로그램을 종료하고 다시 시도해주세요.'
-    default:
-      return err instanceof Error
-        ? `마이크를 열 수 없습니다: ${err.message}`
-        : '마이크를 열 수 없습니다.'
-  }
-}
-
-/**
- * 회의 오디오를 파일로 남긴다.
- *
- * 전사와 독립적으로 동작한다. Web Speech가 발화를 놓치든 네트워크가 끊기든
- * 오디오만은 남아야 나중에 서버 STT로 다시 살릴 수 있다. 그래서 서버 업로드가
- * 실패해도 녹음을 중단하지 않고, 브라우저 안의 사본을 끝까지 들고 간다.
- */
-export function useAudioRecorder(): AudioRecorderHook {
-  const [isSupported, setIsSupported] = useState<boolean | null>(null)
-  const [isRecording, setIsRecording] = useState(false)
-  const [error, setError] = useState<string | null>(null)
-  const [uploadWarning, setUploadWarning] = useState<string | null>(null)
-  const [elapsedMs, setElapsedMs] = useState(0)
-  const [localBytes, setLocalBytes] = useState(0)
-  const [uploadedBytes, setUploadedBytes] = useState(0)
-  const [recording, setRecording] = useState<CompletedRecording | null>(null)
-
-  const recorderRef = useRef<MediaRecorder | null>(null)
-  const streamRef = useRef<MediaStream | null>(null)
-  const partsRef = useRef<Blob[]>([])
-  const sessionIdRef = useRef<string | null>(null)
-  const mimeTypeRef = useRef<string | null>(null)
-  const startedAtRef = useRef<Date | null>(null)
-  const uploadChainRef = useRef<Promise<void>>(Promise.resolve())
-  const uploadBrokenRef = useRef(false)
-
-  useEffect(() => {
-    setIsSupported(
-      typeof window !== 'undefined' &&
-        typeof window.MediaRecorder !== 'undefined' &&
-        typeof navigator !== 'undefined' &&
-        !!navigator.mediaDevices?.getUserMedia,
-    )
-  }, [])
-
-  // 녹음 중에는 1초마다 경과 시간을 갱신한다. 이 시각이 나중에 전사 청크를
-  // 오디오 타임라인에 맞추는 기준이 된다.
-  useEffect(() => {
-    if (!isRecording) return
-
-    const timer = setInterval(() => {
-      if (startedAtRef.current) {
-        setElapsedMs(Date.now() - startedAtRef.current.getTime())
-      }
-    }, 1000)
-
-    return () => clearInterval(timer)
-  }, [isRecording])
-
-  // 녹음 중 탭을 닫으면 아직 못 올린 조각이 사라진다. 확인을 한 번 받는다.
-  useEffect(() => {
-    if (!isRecording) return
-
-    function warn(event: BeforeUnloadEvent) {
-      event.preventDefault()
-    }
-
-    window.addEventListener('beforeunload', warn)
-    return () => window.removeEventListener('beforeunload', warn)
-  }, [isRecording])
-
-  /**
-   * 조각을 순서대로 올린다.
-   *
-   * 순서가 곧 파일의 순서이므로 병렬로 보내지 않는다. 한 조각이 끝내 실패하면
-   * 그 뒤를 이어 붙여봐야 중간이 비어 재생도 전사도 안 되는 파일이 되므로,
-   * 그 시점에 업로드를 멈추고 로컬 사본을 쓰라고 알린다.
-   */
-  const queueUpload = useCallback((chunk: Blob) => {
-    const id = sessionIdRef.current
-    if (!id || uploadBrokenRef.current) return
-
-    uploadChainRef.current = uploadChainRef.current.then(async () => {
-      if (uploadBrokenRef.current) return
-
-      for (let attempt = 1; attempt <= MAX_CHUNK_RETRIES; attempt++) {
-        try {
-          const res = await fetch(`/api/recordings/${id}/chunk`, {
-            method: 'POST',
-            headers: { 'Content-Type': 'application/octet-stream' },
-            body: chunk,
-          })
-
-          if (res.ok) {
-            const data = await res.json()
-            setUploadedBytes(data.bytes)
-            return
-          }
-
-          // 4xx는 재시도해도 같은 답이 온다.
-          if (res.status >= 400 && res.status < 500) break
-        } catch {
-          // 네트워크 오류 — 아래에서 재시도한다.
-        }
-
-        if (attempt < MAX_CHUNK_RETRIES) {
-          await new Promise((resolve) => setTimeout(resolve, 500 * attempt))
-        }
-      }
-
-      uploadBrokenRef.current = true
-      setUploadWarning(
-        '서버 저장이 중단되었습니다. 녹음은 계속되고 있으니 종료 후 반드시 오디오를 내려받아 주세요.',
-      )
-    })
-  }, [])
-
-  const startRecording = useCallback(async () => {
-    if (recorderRef.current) return
-
-    setError(null)
-    setUploadWarning(null)
-    setRecording(null)
-    setElapsedMs(0)
-    setLocalBytes(0)
-    setUploadedBytes(0)
-    partsRef.current = []
-    sessionIdRef.current = null
-    uploadBrokenRef.current = false
-    uploadChainRef.current = Promise.resolve()
-
-    if (isSupported !== true) {
-      setError('이 브라우저는 오디오 녹음을 지원하지 않습니다. Chrome을 사용해주세요.')
-      return
-    }
-
-    const mimeType = pickRecorderMimeType((type) =>
-      MediaRecorder.isTypeSupported(type),
-    )
-    if (!mimeType) {
-      setError('브라우저가 지원하는 녹음 형식을 찾지 못했습니다.')
-      return
-    }
-
-    let stream: MediaStream
-    try {
-      stream = await navigator.mediaDevices.getUserMedia({
-        audio: RECORDING_AUDIO_CONSTRAINTS,
-      })
-    } catch (err) {
-      setError(describeCaptureError(err))
-      return
-    }
-
-    // 서버 세션은 있으면 좋고 없어도 녹음은 간다. 여기서 포기하면
-    // 오디오를 남기려던 목적 자체를 잃는다.
-    try {
-      const res = await fetch('/api/recordings', {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({ mimeType }),
-      })
-
-      if (res.ok) {
-        const meta = await res.json()
-        sessionIdRef.current = meta.id
-      } else {
-        uploadBrokenRef.current = true
-        setUploadWarning(
-          '서버에 녹음 세션을 만들지 못했습니다. 브라우저에만 저장되니 종료 후 반드시 내려받아 주세요.',
-        )
-      }
-    } catch {
-      uploadBrokenRef.current = true
-      setUploadWarning(
-        '서버에 연결하지 못했습니다. 브라우저에만 저장되니 종료 후 반드시 내려받아 주세요.',
-      )
-    }
-
-    const recorder = new MediaRecorder(stream, {
-      mimeType,
-      audioBitsPerSecond: AUDIO_BITS_PER_SECOND,
-    })
-
-    recorder.ondataavailable = (event) => {
-      if (event.data.size === 0) return
-      partsRef.current.push(event.data)
-      setLocalBytes((prev) => prev + event.data.size)
-      queueUpload(event.data)
-    }
-
-    recorder.onerror = () => {
-      setError('녹음 중 오류가 발생했습니다. 지금까지의 오디오는 보존되어 있습니다.')
-    }
-
-    streamRef.current = stream
-    recorderRef.current = recorder
-    mimeTypeRef.current = mimeType
-    startedAtRef.current = new Date()
-
-    recorder.start(CHUNK_INTERVAL_MS)
-    setIsRecording(true)
-  }, [isSupported, queueUpload])
-
-  const stopRecording = useCallback(async () => {
-    const recorder = recorderRef.current
-    if (!recorder) return
-    recorderRef.current = null
-
-    // stop()은 남은 버퍼를 dataavailable로 한 번 더 내보낸 뒤 stop을 쏜다.
-    // 그 마지막 조각까지 받아야 회의 끝부분이 잘리지 않는다.
-    if (recorder.state !== 'inactive') {
-      await new Promise<void>((resolve) => {
-        recorder.addEventListener('stop', () => resolve(), { once: true })
-        recorder.stop()
-      })
-    }
-
-    streamRef.current?.getTracks().forEach((track) => track.stop())
-    streamRef.current = null
-
-    await uploadChainRef.current
-
-    const startedAt = startedAtRef.current ?? new Date()
-    const durationMs = Date.now() - startedAt.getTime()
-    const mimeType = mimeTypeRef.current ?? 'audio/webm'
-    const id = sessionIdRef.current
-
-    const blob = new Blob(partsRef.current, { type: mimeType })
-
-    // 한 바이트도 못 받았으면 보관됐다고 말하면 안 된다. 이 기능의 요점은
-    // 오디오가 남는 것인데, 남지 않았는데 남았다고 알리면 사용자는 회의가
-    // 끝난 뒤에야 아무것도 없다는 걸 알게 된다.
-    if (blob.size === 0) {
-      setError(
-        '오디오가 한 조각도 캡처되지 않았습니다. 마이크 입력 장치를 확인하고 다시 녹음해주세요.',
-      )
-      setElapsedMs(durationMs)
-      setIsRecording(false)
-      return
-    }
-
-    let serverBytes = 0
-    if (id && !uploadBrokenRef.current) {
-      try {
-        const res = await fetch(`/api/recordings/${id}`, {
-          method: 'POST',
-          headers: { 'Content-Type': 'application/json' },
-          body: JSON.stringify({ durationMs }),
-        })
-        if (res.ok) {
-          serverBytes = (await res.json()).bytes ?? 0
-        }
-      } catch {
-        setUploadWarning(
-          '녹음 종료 처리에 실패했습니다. 저장된 조각은 남아 있지만, 로컬 사본도 내려받아 두시길 권합니다.',
-        )
-      }
-    }
-
-    // 서버 사본이 로컬보다 짧으면 조각이 새어나간 것이다. 조용히 넘기지 않는다.
-    if (id && !uploadBrokenRef.current && serverBytes < blob.size) {
-      setUploadWarning(
-        `서버 사본이 로컬보다 짧습니다 (${serverBytes} / ${blob.size} bytes). 오디오를 내려받아 보관해주세요.`,
-      )
-    }
-
-    setElapsedMs(durationMs)
-    setUploadedBytes(serverBytes)
-    setRecording({
-      recordingId: uploadBrokenRef.current ? null : id,
-      mimeType,
-      blob,
-      durationMs,
-      startedAt,
-      uploadedBytes: serverBytes,
-    })
-    setIsRecording(false)
-  }, [])
-
-  const downloadRecording = useCallback((title: string) => {
-    const parts = partsRef.current
-    if (parts.length === 0) return
-
-    const mimeType = mimeTypeRef.current ?? 'audio/webm'
-    const blob = new Blob(parts, { type: mimeType })
-    const url = URL.createObjectURL(blob)
-
-    const anchor = document.createElement('a')
-    anchor.href = url
-    anchor.download = recordingDownloadName(
-      title,
-      startedAtRef.current ?? new Date(),
-      mimeType,
-    )
-    document.body.appendChild(anchor)
-    anchor.click()
-    anchor.remove()
-
-    setTimeout(() => URL.revokeObjectURL(url), 1_000)
-  }, [])
-
-  const reset = useCallback(() => {
-    partsRef.current = []
-    sessionIdRef.current = null
-    startedAtRef.current = null
-    uploadBrokenRef.current = false
-    setRecording(null)
-    setElapsedMs(0)
-    setLocalBytes(0)
-    setUploadedBytes(0)
-    setError(null)
-    setUploadWarning(null)
-  }, [])
-
-  // 언마운트 시 마이크를 놓아준다. 탭 표시등이 켜진 채 남지 않도록.
-  useEffect(() => {
-    return () => {
-      const recorder = recorderRef.current
-      if (recorder && recorder.state !== 'inactive') {
-        recorder.stop()
-      }
-      streamRef.current?.getTracks().forEach((track) => track.stop())
-    }
-  }, [])
-
-  return {
-    isRecording,
-    isSupported,
-    error,
-    uploadWarning,
-    elapsedMs,
-    localBytes,
-    uploadedBytes,
-    recording,
-    startRecording,
-    stopRecording,
-    downloadRecording,
-    reset,
-  }
-}

src/hooks/useDiarization.ts

@@ -0,0 +1,169 @@
+'use client'
+
+import { useCallback, useEffect, useRef, useState } from 'react'
+import type { TimeSpan } from '@/lib/transcript-formatter'
+
+export type DiarizationStatus =
+  | { state: 'idle' }
+  | { state: 'unavailable'; message: string }
+  | { state: 'recording'; seconds: number }
+  | { state: 'analyzing' }
+  | { state: 'done'; speakers: number; segments: TimeSpan[] }
+  | { state: 'error'; message: string }
+
+interface UseDiarizationResult {
+  /** 모델 설치 여부. null이면 확인 중. */
+  available: boolean | null
+  status: DiarizationStatus
+  /** 오디오 수집 시작. 마이크 트랙을 넘긴다. */
+  start: (track: MediaStreamTrack) => Promise<void>
+  /** 수집을 멈추고 전체 오디오에 화자 분리를 돌린다. */
+  finish: (numSpeakers?: number) => Promise<TimeSpan[]>
+  reset: () => void
+}
+
+function newSessionId(): string {
+  return `s_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`
+}
+
+/**
+ * 대면 회의용 화자 분리.
+ *
+ * 녹음 중에는 4초짜리 PCM 조각을 서버에 쌓아두기만 하고, 녹음이 끝나면
+ * 전체 오디오에 한 번 분리를 돌린다. 창을 잘라 반복 실행하면 실행마다
+ * 화자 번호가 달라져 이어 붙일 수 없기 때문이다.
+ */
+export function useDiarization(): UseDiarizationResult {
+  const [available, setAvailable] = useState<boolean | null>(null)
+  const [status, setStatus] = useState<DiarizationStatus>({ state: 'idle' })
+
+  const sessionRef = useRef<string>('')
+  const contextRef = useRef<AudioContext | null>(null)
+  const nodeRef = useRef<AudioWorkletNode | null>(null)
+  const secondsRef = useRef(0)
+
+  useEffect(() => {
+    let cancelled = false
+    fetch('/api/diarize')
+      .then((r) => r.json())
+      .then((d) => {
+        if (!cancelled) setAvailable(!!d.available)
+      })
+      .catch(() => {
+        if (!cancelled) setAvailable(false)
+      })
+    return () => {
+      cancelled = true
+    }
+  }, [])
+
+  const teardown = useCallback(() => {
+    nodeRef.current?.port.close()
+    nodeRef.current?.disconnect()
+    nodeRef.current = null
+    contextRef.current?.close().catch(() => {})
+    contextRef.current = null
+  }, [])
+
+  const start = useCallback(
+    async (track: MediaStreamTrack) => {
+      sessionRef.current = newSessionId()
+      secondsRef.current = 0
+
+      try {
+        // 16kHz로 열면 브라우저가 리샘플링해준다 — 모델이 받는 샘플레이트.
+        const context = new AudioContext({ sampleRate: 16_000 })
+        contextRef.current = context
+
+        await context.audioWorklet.addModule('/pcm-worklet.js')
+
+        const source = context.createMediaStreamSource(new MediaStream([track]))
+        const node = new AudioWorkletNode(context, 'pcm-collector')
+        nodeRef.current = node
+
+        node.port.onmessage = (event) => {
+          const pcm = event.data as Int16Array
+          secondsRef.current += pcm.length / 16_000
+          setStatus({
+            state: 'recording',
+            seconds: Math.round(secondsRef.current),
+          })
+
+          // 실패해도 녹음을 막지 않는다. 그 구간만 화자 분리에서 빠진다.
+          fetch(`/api/diarize/chunk?session=${sessionRef.current}`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/octet-stream' },
+            // 워크릿이 매번 새 버퍼를 transfer 하므로 buffer 전체가 곧 이 조각이다.
+            body: pcm.buffer as ArrayBuffer,
+          }).catch(() => {})
+        }
+
+        source.connect(node)
+        setStatus({ state: 'recording', seconds: 0 })
+      } catch (err) {
+        teardown()
+        setStatus({
+          state: 'error',
+          message:
+            err instanceof Error
+              ? `오디오 수집 실패: ${err.message}`
+              : '오디오 수집에 실패했습니다.',
+        })
+      }
+    },
+    [teardown],
+  )
+
+  const finish = useCallback(
+    async (numSpeakers?: number): Promise<TimeSpan[]> => {
+      teardown()
+
+      if (!sessionRef.current || secondsRef.current < 1) {
+        setStatus({ state: 'idle' })
+        return []
+      }
+
+      setStatus({ state: 'analyzing' })
+
+      try {
+        const res = await fetch('/api/diarize', {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({ session: sessionRef.current, numSpeakers }),
+        })
+        const data = await res.json()
+
+        if (!res.ok) {
+          setStatus({
+            state: 'error',
+            message: data.error ?? '화자 분리에 실패했습니다.',
+          })
+          return []
+        }
+
+        const segments: TimeSpan[] = data.segments ?? []
+        setStatus({ state: 'done', speakers: data.speakers ?? 0, segments })
+        return segments
+      } catch (err) {
+        setStatus({
+          state: 'error',
+          message:
+            err instanceof Error ? err.message : '화자 분리 요청에 실패했습니다.',
+        })
+        return []
+      }
+    },
+    [teardown],
+  )
+
+  const reset = useCallback(() => {
+    teardown()
+    sessionRef.current = ''
+    secondsRef.current = 0
+    setStatus({ state: 'idle' })
+  }, [teardown])
+
+  useEffect(() => teardown, [teardown])
+
+  return { available, status, start, finish, reset }
+}

src/hooks/useDualStreamCapture.ts

@@ -0,0 +1,121 @@
+'use client'
+
+import { useCallback, useEffect, useRef, useState } from 'react'
+
+export type CaptureMode = 'idle' | 'mic-only' | 'dual-stream'
+
+interface DualStreamCapture {
+  mode: CaptureMode
+  /** 내 목소리 트랙 (마이크) */
+  micTrack: MediaStreamTrack | null
+  /** 상대 목소리 트랙 (시스템·탭 오디오). 화면 공유를 거부하거나 오디오를 안 켜면 null */
+  systemTrack: MediaStreamTrack | null
+  error: string | null
+  /** 시스템 오디오 없이 마이크만 잡힌 경우의 안내 */
+  warning: string | null
+  start: (options?: { withSystemAudio?: boolean }) => Promise<void>
+  stop: () => void
+}
+
+function describeCaptureError(err: unknown): string {
+  if (!(err instanceof Error)) return '오디오 캡처에 실패했습니다.'
+
+  switch (err.name) {
+    case 'NotAllowedError':
+      return '오디오 캡처 권한이 거부되었습니다. 마이크와 화면 공유를 모두 허용해주세요.'
+    case 'NotFoundError':
+      return '사용할 수 있는 마이크를 찾을 수 없습니다.'
+    case 'NotReadableError':
+      return '다른 앱이 마이크를 사용 중입니다. 해당 앱을 종료하고 다시 시도해주세요.'
+    default:
+      return `오디오 캡처 실패: ${err.message}`
+  }
+}
+
+/**
+ * 화자 분리를 위한 2트랙 캡처.
+ *
+ * 내 마이크와 시스템(탭) 오디오를 **별도 트랙으로** 잡는다. 트랙이 곧 화자이므로
+ * 추론 없이 정확도 100%로 화자가 갈린다. 원격 1:1 회의를 겨냥한 경로다.
+ *
+ * 시스템 오디오는 Chrome/Windows와 Chrome 141+/macOS 14.2+ 에서만 캡처된다.
+ * 실패하면 마이크 단독 모드로 떨어지며, 그 경우 화자 분리는 되지 않는다.
+ */
+export function useDualStreamCapture(): DualStreamCapture {
+  const [mode, setMode] = useState<CaptureMode>('idle')
+  const [micTrack, setMicTrack] = useState<MediaStreamTrack | null>(null)
+  const [systemTrack, setSystemTrack] = useState<MediaStreamTrack | null>(null)
+  const [error, setError] = useState<string | null>(null)
+  const [warning, setWarning] = useState<string | null>(null)
+
+  const streamsRef = useRef<MediaStream[]>([])
+
+  const stop = useCallback(() => {
+    for (const stream of streamsRef.current) {
+      for (const track of stream.getTracks()) track.stop()
+    }
+    streamsRef.current = []
+    setMicTrack(null)
+    setSystemTrack(null)
+    setMode('idle')
+  }, [])
+
+  const start = useCallback(
+    async (options?: { withSystemAudio?: boolean }) => {
+      const withSystemAudio = options?.withSystemAudio ?? true
+
+      setError(null)
+      setWarning(null)
+
+      let micStream: MediaStream
+      try {
+        micStream = await navigator.mediaDevices.getUserMedia({ audio: true })
+      } catch (err) {
+        setError(describeCaptureError(err))
+        return
+      }
+      streamsRef.current.push(micStream)
+      const mic = micStream.getAudioTracks()[0] ?? null
+      setMicTrack(mic)
+
+      if (!withSystemAudio) {
+        setMode('mic-only')
+        return
+      }
+
+      try {
+        // 오디오만 필요해도 video:true를 함께 요청해야 한다 (스펙 요구사항).
+        const displayStream = await navigator.mediaDevices.getDisplayMedia({
+          video: true,
+          audio: true,
+        })
+        streamsRef.current.push(displayStream)
+
+        // 영상은 쓰지 않으므로 즉시 끊어 자원과 프라이버시 노출을 줄인다.
+        for (const track of displayStream.getVideoTracks()) track.stop()
+
+        const system = displayStream.getAudioTracks()[0] ?? null
+        if (!system) {
+          setWarning(
+            '시스템 오디오가 공유되지 않아 화자 분리가 비활성화됩니다. 공유 대화상자에서 "탭 오디오 공유"를 켜주세요.',
+          )
+          setMode('mic-only')
+          return
+        }
+
+        setSystemTrack(system)
+        setMode('dual-stream')
+      } catch (err) {
+        setWarning(
+          `${describeCaptureError(err)} 마이크만으로 계속 녹음합니다 (화자 분리 없음).`,
+        )
+        setMode('mic-only')
+      }
+    },
+    [],
+  )
+
+  useEffect(() => stop, [stop])
+
+  return { mode, micTrack, systemTrack, error, warning, start, stop }
+}

src/hooks/useSpeechRecognition.ts

@@ -3,6 +3,22 @@
 import { useState, useRef, useCallback, useEffect } from 'react'
 import type { TranscriptChunk } from '@/lib/transcript-formatter'
 
+export interface UseSpeechRecognitionOptions {
+  /**
+   * 전사할 오디오 트랙. 지정하면 기본 마이크 대신 이 트랙을 인식한다.
+   * 트랙마다 인식기를 붙이면 화자가 트랙으로 확정된다.
+   */
+  audioTrack?: MediaStreamTrack | null
+  /** 이 인식기가 만든 청크에 붙일 화자 식별자. */
+  speaker?: string
+  /**
+   * 타임스탬프 기준 시각(ms). 여러 인식기를 병합하려면 같은 값을 넘겨야
+   * 한 시간축 위에 놓인다. 생략하면 startListening 호출 시각을 쓴다.
+   */
+  timeOrigin?: number
+  lang?: string
+}
+
 interface SpeechRecognitionHook {
   isListening: boolean
   isSupported: boolean | null
@@ -30,7 +46,10 @@ function describeError(code: string): string {
   }
 }
 
-export function useSpeechRecognition(): SpeechRecognitionHook {
+export function useSpeechRecognition(
+  options: UseSpeechRecognitionOptions = {},
+): SpeechRecognitionHook {
+  const { audioTrack, speaker, timeOrigin, lang = 'ko-KR' } = options
   const [isListening, setIsListening] = useState(false)
   const [chunks, setChunks] = useState<TranscriptChunk[]>([])
   const [interimText, setInterimText] = useState('')
@@ -40,6 +59,12 @@ export function useSpeechRecognition(): SpeechRecognitionHook {
   const startTimeRef = useRef<number>(0)
   const networkRetryRef = useRef<number>(0)
 
+  // start()/onend 콜백이 항상 최신 값을 보도록 ref로 들고 있는다.
+  const configRef = useRef({ audioTrack, speaker, timeOrigin, lang })
+  useEffect(() => {
+    configRef.current = { audioTrack, speaker, timeOrigin, lang }
+  }, [audioTrack, speaker, timeOrigin, lang])
+
   const MAX_NETWORK_RETRIES = 8
 
   useEffect(() => {
@@ -59,12 +84,15 @@ export function useSpeechRecognition(): SpeechRecognitionHook {
     const SpeechRecognitionAPI =
       window.SpeechRecognition || window.webkitSpeechRecognition
 
+    const { audioTrack: track, speaker: speakerId, timeOrigin: origin, lang: language } =
+      configRef.current
+
     const recognition = new SpeechRecognitionAPI()
-    recognition.lang = 'ko-KR'
+    recognition.lang = language
     recognition.continuous = true
     recognition.interimResults = true
 
-    startTimeRef.current = Date.now()
+    startTimeRef.current = origin ?? Date.now()
     networkRetryRef.current = 0
     setError(null)
 
@@ -88,6 +116,7 @@ export function useSpeechRecognition(): SpeechRecognitionHook {
               startTime: Math.max(0, now - 2),
               endTime: now,
               isFinal: true,
+              ...(speakerId ? { speaker: speakerId } : {}),
             },
           ])
           setInterimText('')
@@ -103,8 +132,14 @@ export function useSpeechRecognition(): SpeechRecognitionHook {
       const delay = networkRetryRef.current > 0 ? 1500 : 0
       setTimeout(() => {
         if (recognitionRef.current !== recognition) return
+        // 트랙이 끝났으면(화면 공유 중단 등) 재시작하지 않는다.
+        if (track && track.readyState !== 'live') {
+          setIsListening(false)
+          recognitionRef.current = null
+          return
+        }
         try {
-          recognition.start()
+          recognition.start(track ?? undefined)
         } catch {
           setIsListening(false)
           recognitionRef.current = null
@@ -141,7 +176,7 @@ export function useSpeechRecognition(): SpeechRecognitionHook {
 
     recognitionRef.current = recognition
     try {
-      recognition.start()
+      recognition.start(track ?? undefined)
       setIsListening(true)
     } catch (err) {
       setError(

src/lib/audio-session.ts

@@ -0,0 +1,93 @@
+/**
+ * 녹음 중 들어오는 PCM 조각을 세션별로 모아 둔다.
+ *
+ * 화자 분리는 녹음이 끝난 뒤 전체 오디오에 한 번 돌린다. 누적분을 매번
+ * 다시 보내면 1시간 회의에서 100MB가 넘는 요청이 되므로, 녹음 중에는
+ * 몇 초짜리 조각만 올리고 서버가 이어 붙인다.
+ *
+ * 단일 사용자 로컬 실행을 전제로 한 메모리 저장소다. 여러 사용자가 붙는
+ * 환경이라면 디스크나 외부 저장소로 옮겨야 한다.
+ */
+
+export const SAMPLE_RATE = 16_000
+
+/** 세션당 최대 녹음 길이. 초과분은 거부한다. */
+export const MAX_SESSION_SECONDS = 3 * 60 * 60
+
+/** 마지막 갱신 이후 이 시간이 지난 세션은 정리한다. */
+const SESSION_TTL_MS = 6 * 60 * 60 * 1000
+
+interface Session {
+  chunks: Int16Array[]
+  totalSamples: number
+  updatedAt: number
+}
+
+const sessions = new Map<string, Session>()
+
+function sweep(): void {
+  const cutoff = Date.now() - SESSION_TTL_MS
+  for (const [id, session] of sessions) {
+    if (session.updatedAt < cutoff) sessions.delete(id)
+  }
+}
+
+export type AppendResult =
+  | { ok: true; totalSamples: number; seconds: number }
+  | { ok: false; error: string }
+
+export function appendAudio(sessionId: string, pcm: Int16Array): AppendResult {
+  sweep()
+
+  const session = sessions.get(sessionId) ?? {
+    chunks: [],
+    totalSamples: 0,
+    updatedAt: Date.now(),
+  }
+
+  const nextTotal = session.totalSamples + pcm.length
+  if (nextTotal > MAX_SESSION_SECONDS * SAMPLE_RATE) {
+    return {
+      ok: false,
+      error: `녹음이 최대 길이(${MAX_SESSION_SECONDS / 3600}시간)를 초과했습니다.`,
+    }
+  }
+
+  session.chunks.push(pcm)
+  session.totalSamples = nextTotal
+  session.updatedAt = Date.now()
+  sessions.set(sessionId, session)
+
+  return {
+    ok: true,
+    totalSamples: nextTotal,
+    seconds: nextTotal / SAMPLE_RATE,
+  }
+}
+
+/** 누적된 PCM을 모델이 받는 [-1, 1] float32로 펼친다. */
+export function collectSamples(sessionId: string): Float32Array | null {
+  const session = sessions.get(sessionId)
+  if (!session || session.totalSamples === 0) return null
+
+  const out = new Float32Array(session.totalSamples)
+  let offset = 0
+
+  for (const chunk of session.chunks) {
+    for (let i = 0; i < chunk.length; i++) {
+      out[offset + i] = chunk[i] / 32768
+    }
+    offset += chunk.length
+  }
+
+  return out
+}
+
+export function clearSession(sessionId: string): void {
+  sessions.delete(sessionId)
+}
+
+export function sessionSeconds(sessionId: string): number {
+  const session = sessions.get(sessionId)
+  return session ? session.totalSamples / SAMPLE_RATE : 0
+}

src/lib/diarization.ts

@@ -0,0 +1,135 @@
+import path from 'node:path'
+import { existsSync } from 'node:fs'
+
+/**
+ * 로컬 화자 분리 (speaker diarization).
+ *
+ * pyannote-segmentation-3.0 + 3D-Speaker 임베딩을 ONNX Runtime으로 돌린다.
+ * GPU도 파이썬 런타임도 필요 없고, 노트북 CPU에서 실시간의 수십 배 속도로 처리된다.
+ *
+ * 마이크 하나에 여러 사람이 섞여 들어오는 대면 회의용 경로다. 원격 회의처럼
+ * 트랙이 이미 나뉘어 있으면 이 모듈을 쓰지 않는 편이 정확하다.
+ */
+
+export interface SpeakerSegment {
+  /** 발화 시작 (초) */
+  start: number
+  /** 발화 종료 (초) */
+  end: number
+  /** 0부터 시작하는 화자 번호 */
+  speaker: number
+}
+
+export type DiarizationResult =
+  | { success: true; segments: SpeakerSegment[] }
+  | { success: false; error: string; reason: 'models-missing' | 'failed' }
+
+export interface DiarizeOptions {
+  /**
+   * 참석자 수. 알면 반드시 넘길 것.
+   *
+   * 자동 추정은 화자 수를 과다·과소 계수하는 것이 주 실패 모드다.
+   * 실측에서 4인 오디오가 자동 모드로는 5명, 힌트를 주면 4명으로 나왔다.
+   */
+  numSpeakers?: number
+  /** 자동 추정 시 클러스터 분리 임계값. 낮을수록 화자를 많이 잡는다. */
+  threshold?: number
+}
+
+const MODEL_DIR = process.env.DIARIZATION_MODEL_DIR ?? 'models/diarization'
+const SEGMENTATION_MODEL = 'segmentation.onnx'
+const EMBEDDING_MODEL = 'embedding.onnx'
+
+export function resolveModelPaths(): {
+  segmentation: string
+  embedding: string
+} {
+  const root = path.isAbsolute(MODEL_DIR)
+    ? MODEL_DIR
+    : path.join(process.cwd(), MODEL_DIR)
+
+  return {
+    segmentation: path.join(root, SEGMENTATION_MODEL),
+    embedding: path.join(root, EMBEDDING_MODEL),
+  }
+}
+
+export function modelsInstalled(): boolean {
+  const { segmentation, embedding } = resolveModelPaths()
+  return existsSync(segmentation) && existsSync(embedding)
+}
+
+/**
+ * 모델 로딩이 수백 ms 걸리므로 프로세스당 한 번만 만들고 재사용한다.
+ * 클러스터링 설정은 요청마다 바뀔 수 있어 setConfig로 갈아끼운다.
+ */
+type Diarizer = {
+  process: (samples: Float32Array) => SpeakerSegment[]
+  setConfig: (config: {
+    clustering: { numClusters?: number; threshold?: number }
+  }) => void
+}
+
+let cached: Diarizer | null = null
+
+async function getDiarizer(): Promise<Diarizer> {
+  if (cached) return cached
+
+  const { segmentation, embedding } = resolveModelPaths()
+  const { OfflineSpeakerDiarization } = await import('sherpa-onnx-node')
+
+  cached = new OfflineSpeakerDiarization({
+    segmentation: {
+      pyannote: { model: segmentation },
+      numThreads: 2,
+    },
+    embedding: { model: embedding, numThreads: 2 },
+    clustering: { threshold: 0.5 },
+  }) as unknown as Diarizer
+
+  return cached
+}
+
+export async function diarize(
+  samples: Float32Array,
+  options: DiarizeOptions = {},
+): Promise<DiarizationResult> {
+  if (samples.length === 0) {
+    return { success: true, segments: [] }
+  }
+
+  if (!modelsInstalled()) {
+    return {
+      success: false,
+      reason: 'models-missing',
+      error:
+        '화자 분리 모델이 설치되지 않았습니다. `npm run setup:diarization`을 실행해주세요.',
+    }
+  }
+
+  try {
+    const diarizer = await getDiarizer()
+
+    // 참석자 수를 알면 클러스터 개수를 고정한다. 정확도가 크게 오른다.
+    diarizer.setConfig({
+      clustering:
+        options.numSpeakers && options.numSpeakers > 0
+          ? { numClusters: options.numSpeakers }
+          : { threshold: options.threshold ?? 0.5 },
+    })
+
+    const segments = diarizer.process(samples)
+
+    return {
+      success: true,
+      segments: segments.map((s) => ({
+        start: s.start,
+        end: s.end,
+        speaker: s.speaker,
+      })),
+    }
+  } catch (err) {
+    const message = err instanceof Error ? err.message : '알 수 없는 오류'
+    return { success: false, reason: 'failed', error: `화자 분리 실패: ${message}` }
+  }
+}

src/lib/recording-store.ts

@@ -1,195 +0,0 @@
-/**
- * 녹음 조각을 디스크에 이어 붙이는 서버 저장소.
- *
- * 메모리에 모아 뒀다가 종료 시 한 번에 쓰지 않는다. 그러면 탭이나 서버가
- * 죽는 순간 회의 전체가 사라진다. 조각이 도착할 때마다 곧바로 append 하므로
- * 어느 시점에 중단되든 그때까지의 오디오는 파일로 남아 있다.
- *
- * MediaRecorder가 timeslice 모드에서 내보내는 조각은 첫 조각에 컨테이너
- * 헤더가 들어 있고 이후에는 클러스터만 이어진다. 받은 순서대로 이어 붙이면
- * 그대로 재생·전사 가능한 파일이 된다. 단 헤더의 duration 필드는 비어 있어
- * 플레이어에 따라 탐색(seek)이 부정확할 수 있다 — 재전사에는 영향이 없다.
- */
-
-import { randomBytes } from 'crypto'
-import { createReadStream } from 'fs'
-import type { Readable } from 'stream'
-import { appendFile, mkdir, readFile, stat, writeFile } from 'fs/promises'
-import path from 'path'
-import {
-  MAX_RECORDING_BYTES,
-  extensionForMimeType,
-  isValidRecordingId,
-} from './recording'
-
-/** 별도 볼륨에 두고 싶으면 `RECORDINGS_DIR`로 덮어쓴다. */
-export const RECORDINGS_DIR =
-  process.env.RECORDINGS_DIR ?? path.join(process.cwd(), 'uploads', 'recordings')
-
-export interface RecordingMeta {
-  id: string
-  mimeType: string
-  /** `uploads/recordings/` 기준 상대 파일명. */
-  fileName: string
-  startedAt: string
-  finalizedAt: string | null
-  durationMs: number | null
-}
-
-export interface RecordingStatus extends RecordingMeta {
-  bytes: number
-}
-
-/**
- * id별 직렬화 큐.
- *
- * 조각의 순서가 곧 파일의 순서다. 두 요청이 겹쳐 들어오면 컨테이너가
- * 깨지므로 같은 녹음에 대한 쓰기는 한 줄로 세운다.
- */
-const queues = new Map<string, Promise<unknown>>()
-
-function enqueue<T>(id: string, task: () => Promise<T>): Promise<T> {
-  const previous = queues.get(id) ?? Promise.resolve()
-  const next = previous.then(task, task)
-
-  // 앞 작업이 실패해도 뒤 작업은 돌아야 하므로, 큐에는 절대 거부되지 않는
-  // 프로미스를 넣는다. 실패는 호출자가 받는 `next`로만 전달된다.
-  const settled = next.then(
-    () => undefined,
-    () => undefined,
-  )
-
-  // 큐가 무한정 자라지 않도록, 마지막 작업이 끝나면 항목을 지운다.
-  queues.set(id, settled)
-  settled.then(() => {
-    if (queues.get(id) === settled) queues.delete(id)
-  })
-
-  return next
-}
-
-function metaPath(id: string): string {
-  return path.join(RECORDINGS_DIR, `${id}.json`)
-}
-
-function audioPath(meta: RecordingMeta): string {
-  return path.join(RECORDINGS_DIR, meta.fileName)
-}
-
-async function fileSize(filePath: string): Promise<number> {
-  try {
-    return (await stat(filePath)).size
-  } catch {
-    return 0
-  }
-}
-
-/** 새 녹음 세션을 만든다. 오디오 파일은 첫 조각이 도착할 때 생긴다. */
-export async function createRecording(
-  mimeType: string,
-): Promise<RecordingMeta> {
-  const id = randomBytes(16).toString('hex')
-  const meta: RecordingMeta = {
-    id,
-    mimeType,
-    fileName: `${id}.${extensionForMimeType(mimeType)}`,
-    startedAt: new Date().toISOString(),
-    finalizedAt: null,
-    durationMs: null,
-  }
-
-  await mkdir(RECORDINGS_DIR, { recursive: true })
-  await writeFile(metaPath(id), JSON.stringify(meta, null, 2), 'utf-8')
-
-  return meta
-}
-
-export async function getRecording(id: string): Promise<RecordingMeta | null> {
-  if (!isValidRecordingId(id)) return null
-
-  try {
-    const raw = await readFile(metaPath(id), 'utf-8')
-    return JSON.parse(raw) as RecordingMeta
-  } catch {
-    return null
-  }
-}
-
-export async function getRecordingStatus(
-  id: string,
-): Promise<RecordingStatus | null> {
-  const meta = await getRecording(id)
-  if (!meta) return null
-
-  return { ...meta, bytes: await fileSize(audioPath(meta)) }
-}
-
-export type AppendResult =
-  | { ok: true; bytes: number }
-  | { ok: false; error: string; status: number }
-
-/** 조각 하나를 파일 끝에 이어 붙이고 누적 크기를 돌려준다. */
-export async function appendChunk(
-  id: string,
-  chunk: Buffer,
-): Promise<AppendResult> {
-  const meta = await getRecording(id)
-  if (!meta) {
-    return { ok: false, error: '녹음 세션을 찾을 수 없습니다.', status: 404 }
-  }
-
-  return enqueue(id, async () => {
-    const filePath = audioPath(meta)
-    const current = await fileSize(filePath)
-
-    if (current + chunk.byteLength > MAX_RECORDING_BYTES) {
-      return {
-        ok: false as const,
-        error: `녹음이 상한(${Math.round(
-          MAX_RECORDING_BYTES / 1024 / 1024,
-        )}MB)을 넘었습니다.`,
-        status: 413,
-      }
-    }
-
-    await appendFile(filePath, chunk)
-    return { ok: true as const, bytes: current + chunk.byteLength }
-  })
-}
-
-/** 녹음을 닫는다. 이후 조각은 더 오지 않는다고 보고 길이를 확정한다. */
-export async function finalizeRecording(
-  id: string,
-  durationMs: number | null,
-): Promise<RecordingStatus | null> {
-  const meta = await getRecording(id)
-  if (!meta) return null
-
-  return enqueue(id, async () => {
-    const updated: RecordingMeta = {
-      ...meta,
-      finalizedAt: new Date().toISOString(),
-      durationMs:
-        typeof durationMs === 'number' && Number.isFinite(durationMs)
-          ? Math.max(0, Math.round(durationMs))
-          : null,
-    }
-
-    await writeFile(metaPath(id), JSON.stringify(updated, null, 2), 'utf-8')
-    return { ...updated, bytes: await fileSize(audioPath(updated)) }
-  })
-}
-
-/** 다운로드용 읽기 스트림. 파일이 없으면 null. */
-export async function openRecording(
-  id: string,
-): Promise<{ meta: RecordingMeta; bytes: number; stream: Readable } | null> {
-  const meta = await getRecording(id)
-  if (!meta) return null
-
-  const filePath = audioPath(meta)
-  const bytes = await fileSize(filePath)
-  if (bytes === 0) return null
-
-  return { meta, bytes, stream: createReadStream(filePath) }
-}

src/lib/recording.ts

@@ -1,139 +0,0 @@
-/**
- * 회의 오디오 녹음 — 브라우저·서버가 공유하는 상수와 순수 함수.
- *
- * 녹음의 목적은 재생이 아니라 **재전사**다. Web Speech가 놓친 발화를 나중에
- * 서버 STT로 되살리려면 원본 오디오가 남아 있어야 한다. 그래서 전사와
- * 무관하게, 전사가 실패하더라도 오디오만은 반드시 파일로 남긴다.
- */
-
-/** MediaRecorder에 우선순위대로 시도할 컨테이너/코덱. */
-export const PREFERRED_MIME_TYPES = [
-  'audio/webm;codecs=opus',
-  'audio/webm',
-  'audio/ogg;codecs=opus',
-  'audio/mp4',
-] as const
-
-/**
- * 대면 회의 기준 캡처 제약.
- *
- * 브라우저 기본값은 세 가지가 모두 켜져 있고 전화 통화용으로 튜닝돼 있다.
- * 노이즈 억제는 멀리 앉은 화자의 목소리를 노이즈로 오판해 지워버릴 수 있고,
- * 에코 제거는 스피커 출력이 없는 대면 회의에서는 얻을 게 없다. 둘 다 끈다.
- * 반면 AGC는 조용한 화자의 레벨을 끌어올려 주므로 남긴다.
- *
- * 원격 회의(스피커 출력이 마이크로 되먹임되는 경우)에는 echoCancellation을
- * 다시 켜야 한다. 그 경로는 dual-stream 캡처와 함께 다룬다.
- */
-export const RECORDING_AUDIO_CONSTRAINTS: MediaTrackConstraints = {
-  channelCount: 1,
-  echoCancellation: false,
-  noiseSuppression: false,
-  autoGainControl: true,
-}
-
-/**
- * 서버로 조각을 올리는 간격.
- *
- * 짧을수록 탭이 죽었을 때 잃는 양이 적고, 길수록 요청 수가 준다. 15초면
- * 최악의 경우에도 15초치만 잃는다.
- */
-export const CHUNK_INTERVAL_MS = 15_000
-
-/** 음성 전용이므로 128kbps면 STT에 충분하고도 남는다. */
-export const AUDIO_BITS_PER_SECOND = 128_000
-
-/** 회의 하나의 상한. 128kbps 기준 약 8.6시간. */
-export const MAX_RECORDING_BYTES = 500 * 1024 * 1024
-
-/** 조각 하나의 상한. 15초 × 128kbps면 240KB 남짓이라 넉넉하다. */
-export const MAX_CHUNK_BYTES = 8 * 1024 * 1024
-
-/** 브라우저가 지원하는 첫 번째 후보를 고른다. 없으면 null. */
-export function pickRecorderMimeType(
-  isTypeSupported: (type: string) => boolean,
-): string | null {
-  for (const type of PREFERRED_MIME_TYPES) {
-    if (isTypeSupported(type)) return type
-  }
-  return null
-}
-
-/** `audio/webm;codecs=opus` → `webm` */
-export function extensionForMimeType(mimeType: string): string {
-  const base = mimeType.split(';')[0].trim().toLowerCase()
-
-  switch (base) {
-    case 'audio/webm':
-      return 'webm'
-    case 'audio/ogg':
-      return 'ogg'
-    case 'audio/mp4':
-    case 'audio/x-m4a':
-      return 'm4a'
-    case 'audio/mpeg':
-      return 'mp3'
-    case 'audio/wav':
-    case 'audio/x-wav':
-      return 'wav'
-    case 'audio/flac':
-      return 'flac'
-    default:
-      return 'bin'
-  }
-}
-
-/**
- * 녹음 세션 식별자 검증.
- *
- * 이 값이 그대로 파일 경로가 되므로 `..`이나 구분자가 섞이면 안 된다.
- * 경로 조립 전에 반드시 통과시킨다.
- */
-const RECORDING_ID_PATTERN = /^[0-9a-f]{32}$/
-
-export function isValidRecordingId(id: unknown): id is string {
-  return typeof id === 'string' && RECORDING_ID_PATTERN.test(id)
-}
-
-/** 사용자가 내려받을 때 보게 될 파일 이름. */
-export function recordingDownloadName(
-  title: string,
-  startedAt: Date,
-  mimeType: string,
-): string {
-  const stamp = [
-    startedAt.getFullYear(),
-    String(startedAt.getMonth() + 1).padStart(2, '0'),
-    String(startedAt.getDate()).padStart(2, '0'),
-    '-',
-    String(startedAt.getHours()).padStart(2, '0'),
-    String(startedAt.getMinutes()).padStart(2, '0'),
-  ].join('')
-
-  const safeTitle = title
-    .trim()
-    .replace(/[\\/:*?"<>|]/g, '')
-    .replace(/\s+/g, '_')
-    .slice(0, 60)
-
-  const stem = safeTitle.length > 0 ? `${stamp}_${safeTitle}` : stamp
-  return `${stem}.${extensionForMimeType(mimeType)}`
-}
-
-export function formatBytes(bytes: number): string {
-  if (!Number.isFinite(bytes) || bytes < 0) return '0B'
-  if (bytes < 1024) return `${bytes}B`
-  if (bytes < 1024 * 1024) return `${Math.round(bytes / 1024)}KB`
-  return `${(bytes / 1024 / 1024).toFixed(1)}MB`
-}
-
-export function formatDuration(ms: number): string {
-  const total = Math.max(0, Math.floor(ms / 1000))
-  const h = Math.floor(total / 3600)
-  const m = Math.floor((total % 3600) / 60)
-  const s = total % 60
-  const mm = String(m).padStart(2, '0')
-  const ss = String(s).padStart(2, '0')
-
-  return h > 0 ? `${h}:${mm}:${ss}` : `${mm}:${ss}`
-}

src/lib/speakers.ts

@@ -0,0 +1,55 @@
+/**
+ * 화자 식별자.
+ *
+ * dual-stream 캡처에서는 트랙이 곧 화자이므로 추론이 개입하지 않는다.
+ * 단일 트랙에서 화자를 추정하는 경로가 생기면 'spk_1' 같은 식별자가 추가된다.
+ */
+export const LOCAL_SPEAKER = 'local'
+export const REMOTE_SPEAKER = 'remote'
+
+export type SpeakerNames = Readonly<Record<string, string>>
+
+/** diarization이 매긴 화자 번호를 식별자로 바꾼다. 0-based → 1-based. */
+export function diarizedSpeakerId(index: number): string {
+  return `spk_${index + 1}`
+}
+
+const DEFAULT_NAMES: SpeakerNames = {
+  [LOCAL_SPEAKER]: '나',
+  [REMOTE_SPEAKER]: '상대',
+}
+
+/** 화자 식별자를 표시용 이름으로 바꾼다. 사용자가 지정한 이름이 우선한다. */
+export function resolveSpeakerName(
+  speaker: string,
+  names?: SpeakerNames,
+): string {
+  const custom = names?.[speaker]?.trim()
+  if (custom) return custom
+
+  const preset = DEFAULT_NAMES[speaker]
+  if (preset) return preset
+
+  // spk_1 → "화자 1"
+  const diarized = /^spk_(\d+)$/.exec(speaker)
+  if (diarized) return `화자 ${diarized[1]}`
+
+  return speaker
+}
+
+/** 회의록에 저장할 참석자 목록. 지정된 이름이 없으면 기본 표기를 쓴다. */
+export function listAttendees(
+  speakers: readonly string[],
+  names?: SpeakerNames,
+): string[] {
+  const seen = new Set<string>()
+  const result: string[] = []
+
+  for (const speaker of speakers) {
+    if (seen.has(speaker)) continue
+    seen.add(speaker)
+    result.push(resolveSpeakerName(speaker, names))
+  }
+
+  return result
+}

src/lib/transcript-formatter.ts

@@ -1,8 +1,12 @@
+import { resolveSpeakerName, type SpeakerNames } from './speakers'
+
 export interface TranscriptChunk {
   text: string
   startTime: number
   endTime: number
   isFinal: boolean
+  /** 화자 식별자. 단일 트랙 녹음에서는 없다. */
+  speaker?: string
 }
 
 function formatTimestamp(seconds: number): string {
@@ -16,14 +20,42 @@ function formatTimestamp(seconds: number): string {
   return `[${String(m).padStart(2, '0')}:${String(s).padStart(2, '0')}]`
 }
 
-export function formatTranscriptChunks(chunks: readonly TranscriptChunk[]): string {
+export function formatTranscriptChunks(
+  chunks: readonly TranscriptChunk[],
+  names?: SpeakerNames,
+): string {
   if (chunks.length === 0) return ''
 
   return chunks
-    .map((chunk) => `${formatTimestamp(chunk.startTime)} ${chunk.text}`)
+    .map((chunk) => {
+      const stamp = formatTimestamp(chunk.startTime)
+      if (!chunk.speaker) return `${stamp} ${chunk.text}`
+      return `${stamp} ${resolveSpeakerName(chunk.speaker, names)}: ${chunk.text}`
+    })
     .join('\n')
 }
 
+/**
+ * 여러 트랙에서 나온 청크를 하나의 시간축으로 합친다.
+ *
+ * 각 인식기가 독립적으로 동작하므로 도착 순서가 발화 순서와 다를 수 있다.
+ * 모든 트랙이 같은 timeOrigin을 공유한다는 전제 아래 startTime으로 정렬한다.
+ */
+export function mergeSpeakerChunks(
+  ...streams: readonly (readonly TranscriptChunk[])[]
+): TranscriptChunk[] {
+  const merged = streams.flat()
+
+  return merged
+    .map((chunk, index) => ({ chunk, index }))
+    .sort((a, b) => {
+      const diff = a.chunk.startTime - b.chunk.startTime
+      // 같은 시각이면 원래 순서를 유지해 결과가 흔들리지 않게 한다.
+      return diff !== 0 ? diff : a.index - b.index
+    })
+    .map(({ chunk }) => chunk)
+}
+
 export function mergeAdjacentChunks(
   chunks: readonly TranscriptChunk[],
   gapThreshold: number,
@@ -36,12 +68,19 @@ export function mergeAdjacentChunks(
     const current = chunks[i]
     const last = result[result.length - 1]
 
+    // 화자가 다르면 붙이지 않는다 — 서로 다른 사람의 발화가 한 덩어리가 되면 안 된다.
+    if (current.speaker !== last.speaker) {
+      result.push({ ...current })
+      continue
+    }
+
     if (current.startTime - last.endTime <= gapThreshold) {
       result[result.length - 1] = {
         text: `${last.text} ${current.text}`,
         startTime: last.startTime,
         endTime: current.endTime,
         isFinal: current.isFinal,
+        ...(last.speaker ? { speaker: last.speaker } : {}),
       }
     } else {
       result.push({ ...current })
@@ -50,3 +89,64 @@ export function mergeAdjacentChunks(
 
   return result
 }
+
+export interface TimeSpan {
+  start: number
+  end: number
+  speaker: number
+}
+
+function overlap(
+  aStart: number,
+  aEnd: number,
+  bStart: number,
+  bEnd: number,
+): number {
+  return Math.max(0, Math.min(aEnd, bEnd) - Math.max(aStart, bStart))
+}
+
+/**
+ * diarization 결과를 전사 청크에 붙인다.
+ *
+ * 청크마다 시간이 가장 많이 겹치는 화자 구간을 고른다. 겹치는 구간이 없으면
+ * 화자를 비워 둔다 — 틀린 화자를 붙이는 것보다 없는 편이 낫다.
+ *
+ * Web Speech API가 주는 청크 타임스탬프는 근사값이므로 이 매칭도 근사다.
+ */
+export function assignSpeakers(
+  chunks: readonly TranscriptChunk[],
+  segments: readonly TimeSpan[],
+  speakerId: (index: number) => string,
+): TranscriptChunk[] {
+  if (segments.length === 0) return chunks.map((chunk) => ({ ...chunk }))
+
+  return chunks.map((chunk) => {
+    let best: TimeSpan | null = null
+    let bestOverlap = 0
+
+    for (const segment of segments) {
+      const value = overlap(
+        chunk.startTime,
+        chunk.endTime,
+        segment.start,
+        segment.end,
+      )
+      if (value > bestOverlap) {
+        bestOverlap = value
+        best = segment
+      }
+    }
+
+    if (!best) {
+      // 겹치는 구간이 없으면 이전 라벨도 남기지 않는다.
+      return {
+        text: chunk.text,
+        startTime: chunk.startTime,
+        endTime: chunk.endTime,
+        isFinal: chunk.isFinal,
+      }
+    }
+
+    return { ...chunk, speaker: speakerId(best.speaker) }
+  })
+}

src/types/sherpa-onnx-node.d.ts

@@ -0,0 +1,36 @@
+/**
+ * sherpa-onnx-node는 JSDoc만 제공하고 .d.ts를 배포하지 않는다.
+ * 이 프로젝트가 실제로 쓰는 화자 분리 API만 선언한다.
+ */
+declare module 'sherpa-onnx-node' {
+  export interface SherpaSpeakerSegment {
+    start: number
+    end: number
+    speaker: number
+  }
+
+  export interface FastClusteringConfig {
+    numClusters?: number
+    threshold?: number
+  }
+
+  export interface OfflineSpeakerDiarizationConfig {
+    segmentation?: {
+      pyannote?: { model?: string; windowShiftRatio?: number }
+      numThreads?: number
+      provider?: string
+      debug?: boolean | number
+    }
+    embedding?: { model?: string; numThreads?: number; provider?: string }
+    clustering?: FastClusteringConfig
+    minDurationOn?: number
+    minDurationOff?: number
+  }
+
+  export class OfflineSpeakerDiarization {
+    constructor(config: OfflineSpeakerDiarizationConfig)
+    readonly sampleRate: number
+    process(samples: Float32Array): SherpaSpeakerSegment[]
+    setConfig(config: { clustering: FastClusteringConfig }): void
+  }
+}

src/types/speech-recognition.d.ts

@@ -5,7 +5,11 @@ interface SpeechRecognition extends EventTarget {
   onresult: ((event: SpeechRecognitionEvent) => void) | null
   onend: (() => void) | null
   onerror: ((event: SpeechRecognitionErrorEvent) => void) | null
-  start(): void
+  /**
+   * audioTrack을 넘기면 기본 마이크 대신 그 트랙을 전사한다 (Chrome 한정).
+   * 트랙별로 인식기를 붙이면 화자가 트랙 번호로 확정된다.
+   */
+  start(audioTrack?: MediaStreamTrack): void
   stop(): void
   abort(): void
 }