Initial commit: Speaker Diarization System

.gitattributes

@@ -0,0 +1,8 @@
+*.py text eol=lf
+*.txt text eol=lf
+*.md text eol=lf
+*.yaml text eol=lf
+*.yml text eol=lf
+*.json text eol=lf
+*.html text eol=lf
+Dockerfile text eol=lf

.gitignore

@@ -0,0 +1,11 @@
+.env
+model_cache/
+wires/
+.wires/
+__pycache__/
+*.pyc
+*.wav
+*.mp3
+*.flac
+.venv/
+venv/

Dockerfile

@@ -0,0 +1,21 @@
+FROM python:3.10-slim
+
+# Install system dependencies including ffmpeg
+RUN apt-get update && apt-get install -y \
+    ffmpeg \
+    git \
+    && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+
+# Install Python dependencies
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Copy project files
+COPY . .
+
+# HuggingFace Spaces uses port 7860
+EXPOSE 7860
+
+CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "7860"]

README.md

@@ -0,0 +1,240 @@
+# 🎙 Speaker Diarization System
+### *Who Spoke When — Multi-Speaker Audio Segmentation*
+
+> **Tech Stack:** Python · PyTorch · SpeechBrain · Pyannote.audio · Transformers · FastAPI
+
+---
+
+## Architecture
+
+```
+Audio Input
+    │
+    ▼
+┌─────────────────────────────┐
+│  Voice Activity Detection   │  ← pyannote/voice-activity-detection
+│  (VAD)                      │    fallback: energy-based VAD
+└────────────┬────────────────┘
+             │  speech regions (start, end)
+             ▼
+┌─────────────────────────────┐
+│  Sliding Window Segmentation│  ← 1.5s windows, 50% overlap
+│                             │
+└────────────┬────────────────┘
+             │  segment list
+             ▼
+┌─────────────────────────────┐
+│  ECAPA-TDNN Embedding       │  ← speechbrain/spkrec-ecapa-voxceleb
+│  Extraction                 │    192-dim L2-normalized vectors
+└────────────┬────────────────┘
+             │  embeddings (N × 192)
+             ▼
+┌─────────────────────────────┐
+│  Agglomerative Hierarchical │  ← cosine distance metric
+│  Clustering (AHC)           │    silhouette-based auto k-selection
+└────────────┬────────────────┘
+             │  speaker labels
+             ▼
+┌─────────────────────────────┐
+│  Post-processing            │  ← merge consecutive same-speaker segs
+│  & Output Formatting        │    timestamped JSON / RTTM / SRT
+└─────────────────────────────┘
+```
+
+---
+
+## Project Structure
+
+```
+speaker-diarization/
+├── app/
+│   ├── main.py          # FastAPI app — REST + WebSocket endpoints
+│   └── pipeline.py      # Core end-to-end diarization pipeline
+├── models/
+│   ├── embedder.py      # ECAPA-TDNN speaker embedding extractor
+│   └── clusterer.py     # Agglomerative Hierarchical Clustering (AHC)
+├── utils/
+│   └── audio.py         # Audio loading, chunking, RTTM/SRT export
+├── tests/
+│   └── test_diarization.py  # Unit + integration tests
+├── static/
+│   └── index.html       # Web demo UI
+├── demo.py              # CLI interface
+└── requirements.txt
+```
+
+---
+
+## Installation
+
+```bash
+# 1. Clone / navigate to project
+cd speaker-diarization
+
+# 2. Create virtual environment
+python -m venv .venv
+source .venv/bin/activate  # Windows: .venv\Scripts\activate
+
+# 3. Install dependencies
+pip install -r requirements.txt
+
+# 4. (Optional) Set HuggingFace token for pyannote VAD
+#    Accept terms at: https://huggingface.co/pyannote/voice-activity-detection
+export HF_TOKEN=your_token_here
+```
+
+---
+
+## Usage
+
+### CLI Demo
+
+```bash
+# Basic usage (auto-detect speaker count)
+python demo.py --audio meeting.wav
+
+# Specify 3 speakers
+python demo.py --audio call.wav --speakers 3
+
+# Export all formats
+python demo.py --audio audio.mp3 \
+    --output result.json \
+    --rttm output.rttm \
+    --srt subtitles.srt
+```
+
+**Example output:**
+```
+✅ Done in 4.83s
+   Speakers found : 3
+   Audio duration : 120.50s
+   Segments       : 42
+
+   START       END       DUR  SPEAKER
+   ────────────────────────────────────
+   0.000     3.250    3.250  SPEAKER_00
+   3.500     8.120    4.620  SPEAKER_01
+   8.200    11.800    3.600  SPEAKER_00
+   12.000   17.340    5.340  SPEAKER_02
+   ...
+```
+
+### FastAPI Server
+
+```bash
+# Start the API server
+uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
+
+# Open the web UI
+open http://localhost:8000
+
+# Swagger documentation
+open http://localhost:8000/docs
+```
+
+### REST API
+
+**POST /diarize** — Upload audio file
+```bash
+curl -X POST http://localhost:8000/diarize \
+  -F "file=@meeting.wav" \
+  -F "num_speakers=3"
+```
+
+**Response:**
+```json
+{
+  "status": "success",
+  "num_speakers": 3,
+  "audio_duration": 120.5,
+  "processing_time": 4.83,
+  "sample_rate": 16000,
+  "speakers": ["SPEAKER_00", "SPEAKER_01", "SPEAKER_02"],
+  "segments": [
+    { "start": 0.000, "end": 3.250, "duration": 3.250, "speaker": "SPEAKER_00" },
+    { "start": 3.500, "end": 8.120, "duration": 4.620, "speaker": "SPEAKER_01" }
+  ]
+}
+```
+
+**GET /health** — Service health
+```bash
+curl http://localhost:8000/health
+# {"status":"healthy","device":"cuda","version":"1.0.0"}
+```
+
+### WebSocket Streaming
+
+```python
+import asyncio, websockets, json, numpy as np
+
+async def stream_audio():
+    async with websockets.connect("ws://localhost:8000/ws/stream") as ws:
+        # Send config
+        await ws.send(json.dumps({"sample_rate": 16000, "num_speakers": 2}))
+        
+        # Send audio chunks (raw float32 PCM)
+        with open("audio.raw", "rb") as f:
+            while chunk := f.read(4096):
+                await ws.send(chunk)
+        
+        # Signal end
+        await ws.send(json.dumps({"type": "eof"}))
+        
+        # Receive results
+        async for msg in ws:
+            data = json.loads(msg)
+            if data["type"] == "segment":
+                print(f"[{data['data']['speaker']}] {data['data']['start']:.2f}s – {data['data']['end']:.2f}s")
+            elif data["type"] == "done":
+                break
+
+asyncio.run(stream_audio())
+```
+
+---
+
+## Key Design Decisions
+
+| Component | Choice | Rationale |
+|-----------|--------|-----------|
+| Speaker Embeddings | ECAPA-TDNN (SpeechBrain) | State-of-the-art speaker verification accuracy on VoxCeleb |
+| Clustering | AHC + cosine distance | No predefined k required; works well with L2-normalized embeddings |
+| k-selection | Silhouette analysis | Unsupervised, parameter-free speaker count estimation |
+| VAD | pyannote (energy fallback) | pyannote VAD reduces false embeddings on silence/noise |
+| Embedding window | 1.5s, 50% overlap | Balances temporal resolution vs. embedding stability |
+| Post-processing | Merge consecutive same-speaker | Reduces over-segmentation artifact |
+
+---
+
+## Evaluation Metrics
+
+Standard speaker diarization evaluation uses **Diarization Error Rate (DER)**:
+
+```
+DER = (Miss + False Alarm + Speaker Error) / Total Speech Duration
+```
+
+Export RTTM files for evaluation with `md-eval` or `dscore`:
+```bash
+python demo.py --audio test.wav --rttm hypothesis.rttm
+dscore -r reference.rttm -s hypothesis.rttm
+```
+
+---
+
+## Running Tests
+
+```bash
+pytest tests/ -v
+pytest tests/ -v -k "clusterer"  # run specific test class
+```
+
+---
+
+## Limitations & Future Work
+
+- Long audio (>1hr) should use chunked processing (`utils.audio.chunk_audio`)
+- Real-time streaming requires low-latency VAD (not yet implemented in WS endpoint)
+- Speaker overlap (cross-talk) is assigned to a single speaker
+- Consider fine-tuning ECAPA-TDNN on domain-specific data for call analytics

app/main.py

@@ -0,0 +1,258 @@
+"""
+Speaker Diarization API - FastAPI Application
+"""
+
+import io
+import time
+import asyncio
+import tempfile
+import traceback
+from pathlib import Path
+from typing import Optional, List
+import os
+
+import torch
+from fastapi import (
+    FastAPI, File, UploadFile, Form, WebSocket,
+    WebSocketDisconnect, HTTPException, Query,
+)
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.staticfiles import StaticFiles
+from fastapi.responses import HTMLResponse
+from pydantic import BaseModel, Field
+from loguru import logger
+
+# ---------------------------------------------------------------------------
+# Schemas
+# ---------------------------------------------------------------------------
+
+class SegmentOut(BaseModel):
+    start: float
+    end: float
+    duration: float
+    speaker: str
+
+
+class DiarizationResponse(BaseModel):
+    status: str = "success"
+    num_speakers: int
+    audio_duration: float
+    processing_time: float
+    sample_rate: int
+    speakers: List[str]
+    segments: List[SegmentOut]
+
+
+class HealthResponse(BaseModel):
+    status: str
+    device: str
+    version: str = "1.0.0"
+
+
+# ---------------------------------------------------------------------------
+# App
+# ---------------------------------------------------------------------------
+
+app = FastAPI(
+    title="Speaker Diarization API",
+    description="Who Spoke When — Speaker diarization using ECAPA-TDNN + AHC Clustering",
+    version="1.0.0",
+)
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+_pipeline = None
+
+def get_pipeline():
+    global _pipeline
+    if _pipeline is None:
+        from app.pipeline import DiarizationPipeline
+        _pipeline = DiarizationPipeline(
+            device="auto",
+            use_pyannote_vad=True,
+            hf_token=os.getenv("HF_TOKEN"),
+            max_speakers=10,
+            cache_dir="./model_cache",
+        )
+    return _pipeline
+
+
+# ---------------------------------------------------------------------------
+# Endpoints
+# ---------------------------------------------------------------------------
+
+@app.get("/health", response_model=HealthResponse, tags=["System"])
+async def health_check():
+    device = "cuda" if torch.cuda.is_available() else "cpu"
+    return HealthResponse(status="healthy", device=device)
+
+
+@app.post("/diarize", response_model=DiarizationResponse, tags=["Diarization"])
+async def diarize_audio(
+    file: UploadFile = File(...),
+    num_speakers: Optional[int] = Form(None, ge=1, le=20),
+):
+    """Diarize an uploaded audio file. Returns timestamped speaker labels."""
+    allowed = {".wav", ".mp3", ".flac", ".ogg", ".m4a", ".webm"}
+    suffix = Path(file.filename).suffix.lower()
+    if suffix not in allowed:
+        raise HTTPException(status_code=415, detail=f"Unsupported format '{suffix}'")
+
+    audio_bytes = await file.read()
+    with tempfile.NamedTemporaryFile(suffix=suffix, delete=False) as tmp:
+        tmp.write(audio_bytes)
+        tmp_path = tmp.name
+
+    try:
+        pipeline = get_pipeline()
+        result = pipeline.process(tmp_path, num_speakers=num_speakers)
+        return DiarizationResponse(
+            num_speakers=result.num_speakers,
+            audio_duration=result.audio_duration,
+            processing_time=result.processing_time,
+            sample_rate=result.sample_rate,
+            speakers=sorted(set(s.speaker for s in result.segments)),
+            segments=[SegmentOut(**s.to_dict()) for s in result.segments],
+        )
+    except Exception as e:
+        logger.error(f"Diarization failed: {traceback.format_exc()}")
+        raise HTTPException(status_code=500, detail=str(e))
+    finally:
+        Path(tmp_path).unlink(missing_ok=True)
+
+
+@app.post("/diarize/url", response_model=DiarizationResponse, tags=["Diarization"])
+async def diarize_from_url(
+    audio_url: str = Query(...),
+    num_speakers: Optional[int] = Query(None, ge=1, le=20),
+):
+    """Diarize audio from a URL."""
+    import httpx
+    try:
+        async with httpx.AsyncClient(timeout=60.0) as client:
+            resp = await client.get(audio_url)
+            resp.raise_for_status()
+    except Exception as e:
+        raise HTTPException(status_code=400, detail=f"Failed to fetch audio: {e}")
+
+    with tempfile.NamedTemporaryFile(suffix=".wav", delete=False) as tmp:
+        tmp.write(resp.content)
+        tmp_path = tmp.name
+
+    try:
+        pipeline = get_pipeline()
+        result = pipeline.process(tmp_path, num_speakers=num_speakers)
+        return DiarizationResponse(
+            num_speakers=result.num_speakers,
+            audio_duration=result.audio_duration,
+            processing_time=result.processing_time,
+            sample_rate=result.sample_rate,
+            speakers=sorted(set(s.speaker for s in result.segments)),
+            segments=[SegmentOut(**s.to_dict()) for s in result.segments],
+        )
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+    finally:
+        Path(tmp_path).unlink(missing_ok=True)
+
+
+@app.websocket("/ws/stream")
+async def stream_diarization(websocket: WebSocket):
+    """Real-time streaming diarization via WebSocket."""
+    await websocket.accept()
+    import numpy as np
+    audio_buffer = bytearray()
+    sample_rate = 16000
+    num_speakers = None
+    chunk_count = 0
+
+    try:
+        config_msg = await websocket.receive_json()
+        sample_rate = config_msg.get("sample_rate", 16000)
+        num_speakers = config_msg.get("num_speakers", None)
+
+        await websocket.send_json({
+            "type": "progress",
+            "data": {"message": "Config received. Send audio chunks.", "chunks_received": 0},
+        })
+
+        while True:
+            try:
+                msg = await asyncio.wait_for(websocket.receive(), timeout=30.0)
+            except asyncio.TimeoutError:
+                await websocket.send_json({"type": "error", "data": {"message": "Timeout"}})
+                break
+
+            if "bytes" in msg:
+                audio_buffer.extend(msg["bytes"])
+                chunk_count += 1
+                await websocket.send_json({
+                    "type": "progress",
+                    "data": {"message": f"Received chunk {chunk_count}", "chunks_received": chunk_count},
+                })
+            elif "text" in msg:
+                import json
+                data = json.loads(msg["text"])
+                if data.get("type") == "eof":
+                    break
+
+        if not audio_buffer:
+            await websocket.send_json({"type": "error", "data": {"message": "No audio received"}})
+            return
+
+        import torch
+        audio_np = np.frombuffer(audio_buffer, dtype=np.float32).copy()
+        audio_tensor = torch.from_numpy(audio_np)
+
+        await websocket.send_json({
+            "type": "progress",
+            "data": {"message": "Running diarization pipeline..."},
+        })
+
+        loop = asyncio.get_event_loop()
+        pipeline = get_pipeline()
+        result = await loop.run_in_executor(
+            None,
+            lambda: pipeline.process(audio_tensor, sample_rate=sample_rate, num_speakers=num_speakers),
+        )
+
+        for seg in result.segments:
+            await websocket.send_json({"type": "segment", "data": seg.to_dict()})
+
+        await websocket.send_json({
+            "type": "done",
+            "data": {
+                "num_speakers": result.num_speakers,
+                "total_segments": len(result.segments),
+                "audio_duration": result.audio_duration,
+                "processing_time": result.processing_time,
+            },
+        })
+
+    except WebSocketDisconnect:
+        logger.info("WebSocket client disconnected")
+    except Exception as e:
+        logger.error(f"WebSocket error: {traceback.format_exc()}")
+        try:
+            await websocket.send_json({"type": "error", "data": {"message": str(e)}})
+        except Exception:
+            pass
+
+
+@app.get("/", response_class=HTMLResponse, include_in_schema=False)
+async def serve_ui():
+    ui_path = Path("static/index.html")
+    if ui_path.exists():
+        return HTMLResponse(ui_path.read_text())
+    return HTMLResponse("<h1>Speaker Diarization API</h1><p><a href='/docs'>API Docs →</a></p>")
+
+
+static_dir = Path("static")
+if static_dir.exists():
+    app.mount("/static", StaticFiles(directory="static"), name="static")

app/pipeline.py

@@ -0,0 +1,270 @@
+"""
+Speaker Diarization Pipeline
+Combines: Voice Activity Detection → Segmentation → ECAPA-TDNN Embeddings → AHC Clustering
+"""
+
+import torch
+import torchaudio
+import numpy as np
+from pathlib import Path
+from typing import Optional, List, Union, BinaryIO
+from dataclasses import dataclass, field
+from loguru import logger
+
+from models.embedder import EcapaTDNNEmbedder
+from models.clusterer import SpeakerClusterer
+
+
+@dataclass
+class DiarizationSegment:
+    start: float
+    end: float
+    speaker: str
+    duration: float = field(init=False)
+
+    def __post_init__(self):
+        self.duration = round(self.end - self.start, 3)
+
+    def to_dict(self) -> dict:
+        return {
+            "start": round(self.start, 3),
+            "end": round(self.end, 3),
+            "duration": self.duration,
+            "speaker": self.speaker,
+        }
+
+
+@dataclass
+class DiarizationResult:
+    segments: List[DiarizationSegment]
+    num_speakers: int
+    audio_duration: float
+    processing_time: float
+    sample_rate: int
+
+    def to_dict(self) -> dict:
+        speakers = sorted(set(s.speaker for s in self.segments))
+        return {
+            "num_speakers": self.num_speakers,
+            "audio_duration": round(self.audio_duration, 3),
+            "processing_time": round(self.processing_time, 3),
+            "sample_rate": self.sample_rate,
+            "speakers": speakers,
+            "segments": [s.to_dict() for s in self.segments],
+        }
+
+
+class DiarizationPipeline:
+    """
+    End-to-end speaker diarization pipeline.
+    1. Audio loading & preprocessing
+    2. Voice Activity Detection (VAD) via pyannote or energy-based fallback
+    3. Sliding-window segmentation of speech regions
+    4. ECAPA-TDNN speaker embedding extraction per segment
+    5. Agglomerative Hierarchical Clustering
+    6. Post-processing: merge consecutive same-speaker segments
+    """
+
+    SAMPLE_RATE = 16000
+    WINDOW_DURATION = 1.5
+    WINDOW_STEP = 0.75
+    MIN_SEGMENT_DURATION = 0.5
+
+    def __init__(
+        self,
+        device: str = "auto",
+        use_pyannote_vad: bool = True,
+        hf_token: Optional[str] = None,
+        num_speakers: Optional[int] = None,
+        max_speakers: int = 10,
+        cache_dir: str = "./model_cache",
+    ):
+        self.device = self._resolve_device(device)
+        self.use_pyannote_vad = use_pyannote_vad
+        self.hf_token = hf_token
+        self.num_speakers = num_speakers
+        self.max_speakers = max_speakers
+        self.cache_dir = Path(cache_dir)
+
+        self.embedder = EcapaTDNNEmbedder(device=self.device, cache_dir=str(cache_dir))
+        self.clusterer = SpeakerClusterer(max_speakers=max_speakers)
+
+        self._vad_pipeline = None
+        logger.info(f"DiarizationPipeline ready | device={self.device}")
+
+    def _resolve_device(self, device: str) -> str:
+        if device == "auto":
+            return "cuda" if torch.cuda.is_available() else "cpu"
+        return device
+
+    def _load_vad(self):
+        if self._vad_pipeline is not None:
+            return
+        try:
+            from pyannote.audio import Pipeline
+            logger.info("Loading pyannote VAD pipeline...")
+            self._vad_pipeline = Pipeline.from_pretrained(
+                "pyannote/voice-activity-detection",
+                use_auth_token=self.hf_token,
+            )
+            self._vad_pipeline.to(torch.device(self.device))
+            logger.success("Pyannote VAD loaded.")
+        except Exception as e:
+            logger.warning(f"Could not load pyannote VAD: {e}. Falling back to energy-based VAD.")
+            self._vad_pipeline = "energy"
+
+    def _energy_vad(
+        self, audio: torch.Tensor, frame_duration: float = 0.02, threshold_db: float = -40.0
+    ) -> List[tuple]:
+        """Simple energy-based VAD as fallback."""
+        frame_samples = int(frame_duration * self.SAMPLE_RATE)
+        audio_np = audio.numpy()
+        frames = [
+            audio_np[i : i + frame_samples]
+            for i in range(0, len(audio_np) - frame_samples, frame_samples)
+        ]
+
+        energies_db = []
+        for f in frames:
+            rms = np.sqrt(np.mean(f ** 2) + 1e-10)
+            energies_db.append(20 * np.log10(rms))
+
+        is_speech = np.array(energies_db) > threshold_db
+
+        speech_regions = []
+        in_speech = False
+        start = 0.0
+
+        for i, active in enumerate(is_speech):
+            t = i * frame_duration
+            if active and not in_speech:
+                start = t
+                in_speech = True
+            elif not active and in_speech:
+                speech_regions.append((start, t))
+                in_speech = False
+
+        if in_speech:
+            speech_regions.append((start, len(audio_np) / self.SAMPLE_RATE))
+
+        return speech_regions
+
+    def _get_speech_regions(self, audio: torch.Tensor) -> List[tuple]:
+        if self.use_pyannote_vad:
+            self._load_vad()
+
+        if self._vad_pipeline == "energy" or not self.use_pyannote_vad:
+            return self._energy_vad(audio)
+
+        try:
+            audio_dict = {
+                "waveform": audio.unsqueeze(0).to(self.device),
+                "sample_rate": self.SAMPLE_RATE,
+            }
+            vad_output = self._vad_pipeline(audio_dict)
+            regions = [(seg.start, seg.end) for seg in vad_output.get_timeline().support()]
+            logger.info(f"Pyannote VAD: {len(regions)} speech regions found")
+            return regions
+        except Exception as e:
+            logger.warning(f"Pyannote VAD failed: {e}. Using energy VAD.")
+            return self._energy_vad(audio)
+
+    def _sliding_window_segments(self, speech_regions: List[tuple]) -> List[tuple]:
+        segments = []
+        for region_start, region_end in speech_regions:
+            duration = region_end - region_start
+            if duration < self.MIN_SEGMENT_DURATION:
+                continue
+
+            t = region_start
+            while t + self.WINDOW_DURATION <= region_end:
+                segments.append((t, t + self.WINDOW_DURATION))
+                t += self.WINDOW_STEP
+
+            if region_end - t >= self.MIN_SEGMENT_DURATION:
+                segments.append((t, region_end))
+
+        return segments
+
+    def load_audio(self, path: Union[str, Path, BinaryIO]) -> tuple:
+        waveform, sample_rate = torchaudio.load(path)
+        return waveform, sample_rate
+
+    def process(
+        self,
+        audio: Union[str, Path, torch.Tensor],
+        sample_rate: int = None,
+        num_speakers: Optional[int] = None,
+    ) -> DiarizationResult:
+        """Run full diarization pipeline on audio."""
+        import time
+        t_start = time.time()
+
+        if isinstance(audio, (str, Path)):
+            waveform, sample_rate = self.load_audio(audio)
+            audio_tensor = waveform.squeeze(0)
+        else:
+            assert sample_rate is not None, "sample_rate required when passing tensor"
+            audio_tensor = audio.squeeze(0) if audio.dim() > 1 else audio
+
+        audio_duration = len(audio_tensor) / sample_rate
+        logger.info(f"Processing {audio_duration:.1f}s audio at {sample_rate}Hz")
+
+        processed = self.embedder.preprocess_audio(audio_tensor, sample_rate)
+
+        speech_regions = self._get_speech_regions(processed)
+        if not speech_regions:
+            logger.warning("No speech detected in audio.")
+            return DiarizationResult(
+                segments=[], num_speakers=0,
+                audio_duration=audio_duration,
+                processing_time=time.time() - t_start,
+                sample_rate=sample_rate,
+            )
+
+        windows = self._sliding_window_segments(speech_regions)
+        logger.info(f"Generated {len(windows)} embedding windows")
+
+        embeddings, valid_windows = self.embedder.extract_embeddings_from_segments(
+            processed, self.SAMPLE_RATE, windows
+        )
+
+        if len(embeddings) == 0:
+            logger.warning("No valid embeddings extracted.")
+            return DiarizationResult(
+                segments=[], num_speakers=0,
+                audio_duration=audio_duration,
+                processing_time=time.time() - t_start,
+                sample_rate=sample_rate,
+            )
+
+        k = num_speakers or self.num_speakers
+        labels = self.clusterer.cluster(embeddings, num_speakers=k)
+
+        merged = self.clusterer.merge_consecutive_same_speaker(valid_windows, labels)
+
+        speaker_names = {i: f"SPEAKER_{i:02d}" for i in range(self.max_speakers)}
+        segments = [
+            DiarizationSegment(
+                start=start,
+                end=end,
+                speaker=speaker_names[spk_id],
+            )
+            for start, end, spk_id in merged
+        ]
+
+        num_unique = len(set(labels))
+        processing_time = time.time() - t_start
+
+        logger.success(
+            f"Diarization complete: {num_unique} speakers, "
+            f"{len(segments)} segments, {processing_time:.2f}s"
+        )
+
+        return DiarizationResult(
+            segments=segments,
+            num_speakers=num_unique,
+            audio_duration=audio_duration,
+            processing_time=processing_time,
+            sample_rate=sample_rate,
+        )

demo.py

@@ -0,0 +1,67 @@
+"""
+CLI Demo: Run speaker diarization on a local audio file.
+Usage:
+    python demo.py --audio path/to/audio.wav
+    python demo.py --audio path/to/audio.wav --speakers 3
+    python demo.py --audio path/to/audio.wav --output result.json
+"""
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent))
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Speaker Diarization CLI")
+    parser.add_argument("--audio", required=True, help="Path to audio file")
+    parser.add_argument("--speakers", type=int, default=None)
+    parser.add_argument("--output", default=None, help="Save JSON result")
+    parser.add_argument("--rttm", default=None, help="Save RTTM output")
+    parser.add_argument("--srt", default=None, help="Save SRT subtitle file")
+    parser.add_argument("--device", default="auto", choices=["auto", "cpu", "cuda"])
+    args = parser.parse_args()
+
+    audio_path = Path(args.audio)
+    if not audio_path.exists():
+        print(f"❌ Audio file not found: {audio_path}")
+        sys.exit(1)
+
+    print(f"🎙  Speaker Diarization Pipeline")
+    print(f"   Audio  : {audio_path}")
+    print(f"   Speakers: {'auto-detect' if args.speakers is None else args.speakers}")
+    print()
+
+    from app.pipeline import DiarizationPipeline
+    from utils.audio import segments_to_rttm, segments_to_srt
+
+    pipeline = DiarizationPipeline(device=args.device, num_speakers=args.speakers)
+
+    print("⏳ Running diarization...")
+    result = pipeline.process(audio_path, num_speakers=args.speakers)
+
+    print(f"\n✅ Done in {result.processing_time:.2f}s")
+    print(f"   Speakers : {result.num_speakers}")
+    print(f"   Duration : {result.audio_duration:.2f}s")
+    print(f"   Segments : {len(result.segments)}")
+    print()
+    print(f"{'START':>8}  {'END':>8}  {'DUR':>6}  SPEAKER")
+    print("─" * 42)
+    for seg in result.segments:
+        print(f"{seg.start:8.3f}  {seg.end:8.3f}  {seg.duration:6.3f}  {seg.speaker}")
+
+    if args.output:
+        Path(args.output).write_text(json.dumps(result.to_dict(), indent=2))
+        print(f"\n💾 JSON saved to: {args.output}")
+    if args.rttm:
+        Path(args.rttm).write_text(segments_to_rttm(result.segments, audio_path.stem))
+        print(f"💾 RTTM saved to: {args.rttm}")
+    if args.srt:
+        Path(args.srt).write_text(segments_to_srt(result.segments))
+        print(f"💾 SRT saved to:  {args.srt}")
+
+
+if __name__ == "__main__":
+    main()

models/clusterer.py

@@ -0,0 +1,113 @@
+"""
+Agglomerative Hierarchical Clustering (AHC) for speaker identity assignment.
+Uses cosine similarity on ECAPA-TDNN embeddings to cluster segments by speaker.
+"""
+
+import numpy as np
+from typing import List, Tuple, Optional
+from scipy.cluster.hierarchy import linkage, fcluster
+from scipy.spatial.distance import squareform
+from sklearn.metrics import silhouette_score
+from loguru import logger
+
+
+class SpeakerClusterer:
+    """
+    Agglomerative Hierarchical Clustering for speaker diarization.
+    Supports automatic speaker count estimation via silhouette analysis.
+    """
+
+    def __init__(
+        self,
+        linkage_method: str = "average",
+        distance_threshold: float = 0.7,
+        min_speakers: int = 1,
+        max_speakers: int = 10,
+    ):
+        self.linkage_method = linkage_method
+        self.distance_threshold = distance_threshold
+        self.min_speakers = min_speakers
+        self.max_speakers = max_speakers
+
+    def _cosine_distance_matrix(self, embeddings: np.ndarray) -> np.ndarray:
+        similarity = embeddings @ embeddings.T
+        distance = np.clip(1.0 - similarity, 0.0, 2.0)
+        return distance
+
+    def _estimate_num_speakers(self, embeddings: np.ndarray, linkage_matrix: np.ndarray) -> int:
+        n = len(embeddings)
+        if n <= 2:
+            return n
+
+        best_k = self.min_speakers
+        best_score = -1.0
+        upper_k = min(self.max_speakers, n - 1)
+
+        for k in range(max(2, self.min_speakers), upper_k + 1):
+            labels = fcluster(linkage_matrix, k, criterion="maxclust")
+            if len(np.unique(labels)) < 2:
+                continue
+            try:
+                score = silhouette_score(embeddings, labels, metric="cosine")
+                if score > best_score:
+                    best_score = score
+                    best_k = k
+            except Exception:
+                continue
+
+        logger.info(f"Optimal speaker count: {best_k} (silhouette={best_score:.4f})")
+        return best_k
+
+    def cluster(
+        self,
+        embeddings: np.ndarray,
+        num_speakers: Optional[int] = None,
+    ) -> np.ndarray:
+        """Cluster embeddings into speaker identities."""
+        n = len(embeddings)
+
+        if n == 0:
+            return np.array([], dtype=int)
+        if n == 1:
+            return np.array([0], dtype=int)
+
+        dist_matrix = self._cosine_distance_matrix(embeddings)
+        condensed = squareform(dist_matrix, checks=False)
+        Z = linkage(condensed, method=self.linkage_method)
+
+        if num_speakers is not None:
+            k = max(1, min(num_speakers, n))
+        else:
+            k = self._estimate_num_speakers(embeddings, Z)
+
+        labels = fcluster(Z, k, criterion="maxclust") - 1
+        return labels.astype(int)
+
+    def merge_consecutive_same_speaker(
+        self,
+        segments: List[Tuple[float, float]],
+        labels: np.ndarray,
+        gap_tolerance: float = 0.3,
+    ) -> List[Tuple[float, float, int]]:
+        """Merge consecutive segments assigned to the same speaker."""
+        if not segments:
+            return []
+
+        merged = []
+        current_start, current_end = segments[0]
+        current_label = labels[0]
+
+        for i in range(1, len(segments)):
+            seg_start, seg_end = segments[i]
+            seg_label = labels[i]
+            gap = seg_start - current_end
+
+            if seg_label == current_label and gap <= gap_tolerance:
+                current_end = seg_end
+            else:
+                merged.append((current_start, current_end, int(current_label)))
+                current_start, current_end = seg_start, seg_end
+                current_label = seg_label
+
+        merged.append((current_start, current_end, int(current_label)))
+        return merged

models/embedder.py

@@ -0,0 +1,148 @@
+"""
+Speaker Embedding Extraction using ECAPA-TDNN architecture via SpeechBrain.
+Handles audio preprocessing, feature extraction, and L2-normalized embeddings.
+"""
+
+import os
+import torch
+import torchaudio
+import numpy as np
+from pathlib import Path
+from typing import Union, List, Tuple
+from loguru import logger
+
+
+class EcapaTDNNEmbedder:
+    """
+    Speaker embedding extractor using ECAPA-TDNN architecture.
+    Produces 192-dim L2-normalized speaker embeddings per audio segment.
+    """
+
+    MODEL_SOURCE = "speechbrain/spkrec-ecapa-voxceleb"
+    SAMPLE_RATE = 16000
+    EMBEDDING_DIM = 192
+
+    def __init__(self, device: str = "auto", cache_dir: str = "./model_cache"):
+        self.device = self._resolve_device(device)
+        self.cache_dir = Path(cache_dir)
+        self.cache_dir.mkdir(parents=True, exist_ok=True)
+        self._model = None
+        logger.info(f"EcapaTDNNEmbedder initialized on device: {self.device}")
+
+    def _resolve_device(self, device: str) -> str:
+        if device == "auto":
+            return "cuda" if torch.cuda.is_available() else "cpu"
+        return device
+
+    def _load_model(self):
+        if self._model is not None:
+            return
+
+        try:
+            import speechbrain.utils.fetching as _fetching
+            import shutil as _shutil
+            from pathlib import Path as _Path
+
+            def _patched_link(src, dst, local_strategy):
+                dst = _Path(dst)
+                src = _Path(src)
+                dst.parent.mkdir(parents=True, exist_ok=True)
+                if dst.exists() or dst.is_symlink():
+                    dst.unlink()
+                _shutil.copy2(str(src), str(dst))
+
+            _fetching.link_with_strategy = _patched_link
+
+            from speechbrain.inference.classifiers import EncoderClassifier
+            logger.info(f"Loading ECAPA-TDNN from {self.MODEL_SOURCE}...")
+
+            savedir = str(self.cache_dir / "ecapa_tdnn")
+            import os
+            os.makedirs(savedir, exist_ok=True)
+
+            self._model = EncoderClassifier.from_hparams(
+                source=self.MODEL_SOURCE,
+                savedir=savedir,
+                run_opts={"device": self.device},
+            )
+            self._model.eval()
+            logger.success("ECAPA-TDNN model loaded successfully.")
+        except ImportError:
+            raise ImportError("SpeechBrain not installed. Run: pip install speechbrain")
+
+    def preprocess_audio(
+        self, audio: Union[np.ndarray, torch.Tensor], sample_rate: int
+    ) -> torch.Tensor:
+        """Resample and normalize audio to 16kHz mono float32 tensor."""
+        if isinstance(audio, np.ndarray):
+            audio = torch.from_numpy(audio).float()
+
+        if audio.dim() == 1:
+            audio = audio.unsqueeze(0)
+
+        if audio.shape[0] > 1:
+            audio = audio.mean(dim=0, keepdim=True)
+
+        if sample_rate != self.SAMPLE_RATE:
+            resampler = torchaudio.transforms.Resample(
+                orig_freq=sample_rate, new_freq=self.SAMPLE_RATE
+            )
+            audio = resampler(audio)
+
+        max_val = audio.abs().max()
+        if max_val > 0:
+            audio = audio / max_val
+
+        return audio.squeeze(0)
+
+    def extract_embedding(self, audio: torch.Tensor) -> np.ndarray:
+        """
+        Extract L2-normalized ECAPA-TDNN embedding from a preprocessed audio tensor.
+        Returns L2-normalized embedding of shape (192,)
+        """
+        self._load_model()
+
+        with torch.no_grad():
+            audio_batch = audio.unsqueeze(0).to(self.device)
+            lengths = torch.tensor([1.0]).to(self.device)
+            embedding = self._model.encode_batch(audio_batch, lengths)
+            embedding = embedding.squeeze().cpu().numpy()
+
+        norm = np.linalg.norm(embedding)
+        if norm > 0:
+            embedding = embedding / norm
+
+        return embedding
+
+    def extract_embeddings_from_segments(
+        self,
+        audio: torch.Tensor,
+        sample_rate: int,
+        segments: List[Tuple[float, float]],
+        min_duration: float = 0.5,
+    ) -> Tuple[np.ndarray, List[Tuple[float, float]]]:
+        """Extract embeddings for a list of (start, end) time segments."""
+        processed = self.preprocess_audio(audio, sample_rate)
+        embeddings = []
+        valid_segments = []
+
+        for start, end in segments:
+            duration = end - start
+            if duration < min_duration:
+                continue
+
+            start_sample = int(start * self.SAMPLE_RATE)
+            end_sample = int(end * self.SAMPLE_RATE)
+            segment_audio = processed[start_sample:end_sample]
+
+            if segment_audio.shape[0] == 0:
+                continue
+
+            emb = self.extract_embedding(segment_audio)
+            embeddings.append(emb)
+            valid_segments.append((start, end))
+
+        if not embeddings:
+            return np.empty((0, self.EMBEDDING_DIM)), []
+
+        return np.stack(embeddings), valid_segments

requirements.txt

@@ -0,0 +1,18 @@
+--extra-index-url https://download.pytorch.org/whl/cpu
+torch==2.4.0+cpu
+torchaudio==2.4.0+cpu
+speechbrain>=1.0.0
+pyannote.audio>=3.1.0
+transformers>=4.35.0
+fastapi>=0.104.0
+uvicorn[standard]>=0.24.0
+python-multipart>=0.0.6
+websockets>=12.0
+numpy==1.26.4
+scipy>=1.11.0
+scikit-learn>=1.3.0
+soundfile>=0.12.1
+httpx>=0.25.0
+python-dotenv>=1.0.0
+loguru>=0.7.0
+huggingface_hub==0.23.0

static/index.html

@@ -0,0 +1,623 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0"/>
+  <title>Speaker Diarization System</title>
+  <style>
+    @import url('https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@300;400;500;700&family=Space+Grotesk:wght@300;400;600;700&display=swap');
+
+    :root {
+      --bg: #090c10;
+      --surface: #0f1318;
+      --surface2: #151b23;
+      --border: #1e2730;
+      --accent: #00d4ff;
+      --accent2: #7c3aed;
+      --green: #22d3a0;
+      --yellow: #f59e0b;
+      --red: #ef4444;
+      --text: #e2e8f0;
+      --muted: #64748b;
+      --font-mono: 'JetBrains Mono', monospace;
+      --font-sans: 'Space Grotesk', sans-serif;
+    }
+
+    * { margin: 0; padding: 0; box-sizing: border-box; }
+
+    body {
+      font-family: var(--font-sans);
+      background: var(--bg);
+      color: var(--text);
+      min-height: 100vh;
+      overflow-x: hidden;
+    }
+
+    /* Grid bg */
+    body::before {
+      content: '';
+      position: fixed;
+      inset: 0;
+      background-image:
+        linear-gradient(rgba(0, 212, 255, 0.03) 1px, transparent 1px),
+        linear-gradient(90deg, rgba(0, 212, 255, 0.03) 1px, transparent 1px);
+      background-size: 40px 40px;
+      pointer-events: none;
+      z-index: 0;
+    }
+
+    .container {
+      position: relative;
+      z-index: 1;
+      max-width: 1100px;
+      margin: 0 auto;
+      padding: 2rem 1.5rem;
+    }
+
+    header {
+      text-align: center;
+      margin-bottom: 3rem;
+    }
+
+    .badge {
+      display: inline-block;
+      background: rgba(0, 212, 255, 0.1);
+      border: 1px solid rgba(0, 212, 255, 0.3);
+      color: var(--accent);
+      font-family: var(--font-mono);
+      font-size: 0.72rem;
+      letter-spacing: 0.15em;
+      padding: 4px 12px;
+      border-radius: 100px;
+      margin-bottom: 1rem;
+    }
+
+    h1 {
+      font-size: clamp(2rem, 5vw, 3.2rem);
+      font-weight: 700;
+      letter-spacing: -0.02em;
+      background: linear-gradient(135deg, #fff 30%, var(--accent));
+      -webkit-background-clip: text;
+      -webkit-text-fill-color: transparent;
+      line-height: 1.15;
+    }
+
+    .subtitle {
+      color: var(--muted);
+      font-size: 1rem;
+      margin-top: 0.75rem;
+      font-weight: 300;
+    }
+
+    /* Cards */
+    .card {
+      background: var(--surface);
+      border: 1px solid var(--border);
+      border-radius: 12px;
+      padding: 1.5rem;
+      margin-bottom: 1.5rem;
+    }
+
+    .card-title {
+      font-size: 0.8rem;
+      font-family: var(--font-mono);
+      letter-spacing: 0.12em;
+      color: var(--accent);
+      text-transform: uppercase;
+      margin-bottom: 1.2rem;
+      display: flex;
+      align-items: center;
+      gap: 8px;
+    }
+
+    .card-title::before {
+      content: '▸';
+      font-size: 0.9rem;
+    }
+
+    /* Upload zone */
+    .upload-zone {
+      border: 2px dashed var(--border);
+      border-radius: 10px;
+      padding: 2.5rem;
+      text-align: center;
+      cursor: pointer;
+      transition: all 0.25s;
+      position: relative;
+    }
+
+    .upload-zone:hover, .upload-zone.drag-over {
+      border-color: var(--accent);
+      background: rgba(0, 212, 255, 0.04);
+    }
+
+    .upload-zone input[type="file"] {
+      position: absolute;
+      inset: 0;
+      opacity: 0;
+      cursor: pointer;
+    }
+
+    .upload-icon {
+      font-size: 2.5rem;
+      margin-bottom: 0.75rem;
+      opacity: 0.6;
+    }
+
+    .upload-text {
+      color: var(--muted);
+      font-size: 0.9rem;
+    }
+
+    .upload-text strong {
+      color: var(--accent);
+    }
+
+    /* Controls */
+    .controls {
+      display: grid;
+      grid-template-columns: 1fr 1fr auto;
+      gap: 1rem;
+      margin-top: 1rem;
+      align-items: end;
+    }
+
+    .field label {
+      display: block;
+      font-size: 0.75rem;
+      font-family: var(--font-mono);
+      color: var(--muted);
+      margin-bottom: 6px;
+      letter-spacing: 0.08em;
+    }
+
+    .field input, .field select {
+      width: 100%;
+      background: var(--surface2);
+      border: 1px solid var(--border);
+      color: var(--text);
+      font-family: var(--font-mono);
+      font-size: 0.9rem;
+      padding: 10px 12px;
+      border-radius: 8px;
+      outline: none;
+      transition: border-color 0.2s;
+    }
+
+    .field input:focus, .field select:focus {
+      border-color: var(--accent);
+    }
+
+    .btn-primary {
+      background: var(--accent);
+      color: #000;
+      font-family: var(--font-sans);
+      font-weight: 700;
+      font-size: 0.9rem;
+      border: none;
+      padding: 10px 24px;
+      border-radius: 8px;
+      cursor: pointer;
+      transition: all 0.2s;
+      white-space: nowrap;
+    }
+
+    .btn-primary:hover { filter: brightness(1.1); transform: translateY(-1px); }
+    .btn-primary:disabled { opacity: 0.4; cursor: not-allowed; transform: none; }
+
+    /* Progress */
+    .progress-bar {
+      height: 4px;
+      background: var(--border);
+      border-radius: 99px;
+      overflow: hidden;
+      margin-top: 1rem;
+      display: none;
+    }
+
+    .progress-fill {
+      height: 100%;
+      background: linear-gradient(90deg, var(--accent), var(--accent2));
+      width: 0%;
+      transition: width 0.4s;
+      animation: progress-pulse 1.5s ease-in-out infinite;
+    }
+
+    @keyframes progress-pulse {
+      0%, 100% { opacity: 1; }
+      50% { opacity: 0.6; }
+    }
+
+    /* Stats row */
+    .stats-row {
+      display: grid;
+      grid-template-columns: repeat(4, 1fr);
+      gap: 1rem;
+      margin-bottom: 1.5rem;
+    }
+
+    .stat {
+      background: var(--surface);
+      border: 1px solid var(--border);
+      border-radius: 10px;
+      padding: 1rem 1.2rem;
+    }
+
+    .stat-val {
+      font-family: var(--font-mono);
+      font-size: 1.8rem;
+      font-weight: 700;
+      color: var(--accent);
+    }
+
+    .stat-label {
+      font-size: 0.73rem;
+      color: var(--muted);
+      margin-top: 4px;
+      letter-spacing: 0.06em;
+    }
+
+    /* Timeline */
+    #timeline-container {
+      margin-bottom: 1rem;
+    }
+
+    .timeline-ruler {
+      display: flex;
+      justify-content: space-between;
+      font-family: var(--font-mono);
+      font-size: 0.68rem;
+      color: var(--muted);
+      margin-bottom: 6px;
+      padding: 0 2px;
+    }
+
+    .timeline-track {
+      height: 48px;
+      background: var(--surface2);
+      border-radius: 8px;
+      position: relative;
+      overflow: hidden;
+      border: 1px solid var(--border);
+      margin-bottom: 8px;
+    }
+
+    .track-label {
+      font-family: var(--font-mono);
+      font-size: 0.68rem;
+      color: var(--muted);
+      position: absolute;
+      left: 8px;
+      top: 50%;
+      transform: translateY(-50%);
+      z-index: 2;
+      text-shadow: 0 0 8px var(--bg);
+    }
+
+    .timeline-segment {
+      position: absolute;
+      height: 100%;
+      border-radius: 4px;
+      opacity: 0.9;
+      cursor: pointer;
+      transition: opacity 0.15s, filter 0.15s;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      font-family: var(--font-mono);
+      font-size: 0.65rem;
+      color: rgba(0,0,0,0.85);
+      font-weight: 700;
+      overflow: hidden;
+      white-space: nowrap;
+    }
+
+    .timeline-segment:hover {
+      opacity: 1;
+      filter: brightness(1.15);
+      z-index: 5;
+    }
+
+    /* Segment table */
+    .seg-table {
+      width: 100%;
+      border-collapse: collapse;
+      font-family: var(--font-mono);
+      font-size: 0.82rem;
+    }
+
+    .seg-table th {
+      text-align: left;
+      padding: 8px 12px;
+      font-size: 0.7rem;
+      letter-spacing: 0.1em;
+      color: var(--muted);
+      border-bottom: 1px solid var(--border);
+    }
+
+    .seg-table td {
+      padding: 9px 12px;
+      border-bottom: 1px solid rgba(255,255,255,0.04);
+      vertical-align: middle;
+    }
+
+    .seg-table tr:last-child td { border-bottom: none; }
+    .seg-table tr:hover td { background: rgba(255,255,255,0.02); }
+
+    .speaker-dot {
+      display: inline-block;
+      width: 8px;
+      height: 8px;
+      border-radius: 50%;
+      margin-right: 8px;
+    }
+
+    /* Log */
+    #log {
+      font-family: var(--font-mono);
+      font-size: 0.78rem;
+      color: var(--muted);
+      background: var(--surface2);
+      border-radius: 8px;
+      padding: 1rem;
+      max-height: 160px;
+      overflow-y: auto;
+      line-height: 1.7;
+    }
+
+    .log-info   { color: var(--accent); }
+    .log-success{ color: var(--green); }
+    .log-error  { color: var(--red); }
+    .log-warn   { color: var(--yellow); }
+
+    .hidden { display: none !important; }
+
+    @media (max-width: 640px) {
+      .controls { grid-template-columns: 1fr; }
+      .stats-row { grid-template-columns: 1fr 1fr; }
+    }
+  </style>
+</head>
+<body>
+<div class="container">
+
+  <header>
+    <div class="badge">ECAPA-TDNN + AHC · FASTAPI</div>
+    <h1>Speaker Diarization System</h1>
+    <p class="subtitle">Who spoke when — multi-speaker audio segmentation & labeling</p>
+  </header>
+
+  <!-- Upload Card -->
+  <div class="card">
+    <div class="card-title">Audio Input</div>
+    <div class="upload-zone" id="dropzone">
+      <input type="file" id="audioFile" accept=".wav,.mp3,.flac,.ogg,.m4a,.webm" />
+      <div class="upload-icon">🎙</div>
+      <div class="upload-text"><strong>Drop audio file</strong> or click to browse</div>
+      <div class="upload-text" style="margin-top:4px;font-size:0.78rem;" id="filename-display">WAV · MP3 · FLAC · OGG · M4A</div>
+    </div>
+
+    <div class="controls">
+      <div class="field">
+        <label>API ENDPOINT</label>
+        <input type="text" id="apiUrl" value="http://localhost:8000/diarize" />
+      </div>
+      <div class="field">
+        <label>SPEAKERS (blank = auto)</label>
+        <input type="number" id="numSpeakers" min="1" max="20" placeholder="auto-detect" />
+      </div>
+      <button class="btn-primary" id="runBtn" onclick="runDiarization()" disabled>
+        ▶ Run
+      </button>
+    </div>
+
+    <div class="progress-bar" id="progressBar">
+      <div class="progress-fill" id="progressFill"></div>
+    </div>
+  </div>
+
+  <!-- Results (hidden until run) -->
+  <div id="results" class="hidden">
+
+    <div class="stats-row" id="statsRow"></div>
+
+    <!-- Timeline -->
+    <div class="card">
+      <div class="card-title">Speaker Timeline</div>
+      <div class="timeline-ruler" id="timelineRuler"></div>
+      <div id="timelineTracks"></div>
+    </div>
+
+    <!-- Segment Table -->
+    <div class="card">
+      <div class="card-title">Segments</div>
+      <div style="overflow-x:auto;">
+        <table class="seg-table">
+          <thead>
+            <tr>
+              <th>#</th><th>SPEAKER</th><th>START</th><th>END</th><th>DURATION</th>
+            </tr>
+          </thead>
+          <tbody id="segTableBody"></tbody>
+        </table>
+      </div>
+    </div>
+
+  </div>
+
+  <!-- Log -->
+  <div class="card">
+    <div class="card-title">Log</div>
+    <div id="log"><span class="log-info">// Ready. Upload an audio file to begin.</span></div>
+  </div>
+
+</div>
+
+<script>
+const SPEAKER_COLORS = [
+  '#00d4ff','#7c3aed','#22d3a0','#f59e0b',
+  '#ec4899','#3b82f6','#84cc16','#f97316',
+  '#06b6d4','#a855f7',
+];
+
+let selectedFile = null;
+
+// ── File Handling ──────────────────────────────────────────────────────────
+document.getElementById('audioFile').addEventListener('change', (e) => {
+  const file = e.target.files[0];
+  if (!file) return;
+  selectedFile = file;
+  document.getElementById('filename-display').textContent = `📁 ${file.name} (${(file.size/1024/1024).toFixed(2)} MB)`;
+  document.getElementById('runBtn').disabled = false;
+  log(`File selected: ${file.name}`, 'info');
+});
+
+// Drag & Drop
+const dz = document.getElementById('dropzone');
+dz.addEventListener('dragover', e => { e.preventDefault(); dz.classList.add('drag-over'); });
+dz.addEventListener('dragleave', () => dz.classList.remove('drag-over'));
+dz.addEventListener('drop', e => {
+  e.preventDefault();
+  dz.classList.remove('drag-over');
+  const file = e.dataTransfer.files[0];
+  if (file) {
+    document.getElementById('audioFile').files = e.dataTransfer.files;
+    document.getElementById('audioFile').dispatchEvent(new Event('change'));
+  }
+});
+
+// ── Log ────────────────────────────────────────────────────────────────────
+function log(msg, type = '') {
+  const el = document.getElementById('log');
+  const cls = type ? `log-${type}` : '';
+  const ts = new Date().toLocaleTimeString('en', { hour12: false });
+  el.innerHTML += `<br><span class="${cls}">[${ts}] ${msg}</span>`;
+  el.scrollTop = el.scrollHeight;
+}
+
+// ── Run Diarization ────────────────────────────────────────────────────────
+async function runDiarization() {
+  if (!selectedFile) return;
+
+  const btn = document.getElementById('runBtn');
+  const pb = document.getElementById('progressBar');
+  const pf = document.getElementById('progressFill');
+
+  btn.disabled = true;
+  pb.style.display = 'block';
+  pf.style.width = '20%';
+  document.getElementById('results').classList.add('hidden');
+  log('Uploading audio and running diarization...', 'info');
+
+  const formData = new FormData();
+  formData.append('file', selectedFile);
+  const ns = document.getElementById('numSpeakers').value;
+  if (ns) formData.append('num_speakers', ns);
+
+  const url = document.getElementById('apiUrl').value;
+
+  try {
+    pf.style.width = '50%';
+    const resp = await fetch(url, { method: 'POST', body: formData });
+
+    pf.style.width = '90%';
+
+    if (!resp.ok) {
+      const err = await resp.json().catch(() => ({ detail: resp.statusText }));
+      throw new Error(err.detail || `HTTP ${resp.status}`);
+    }
+
+    const data = await resp.json();
+    pf.style.width = '100%';
+
+    log(`Done — ${data.num_speakers} speaker(s), ${data.segments.length} segments, ${data.processing_time.toFixed(2)}s`, 'success');
+    renderResults(data);
+
+  } catch (e) {
+    log(`Error: ${e.message}`, 'error');
+  } finally {
+    setTimeout(() => { pb.style.display = 'none'; pf.style.width = '0%'; }, 800);
+    btn.disabled = false;
+  }
+}
+
+// ── Render Results ─────────────────────────────────────────────────────────
+function renderResults(data) {
+  document.getElementById('results').classList.remove('hidden');
+
+  // Stats
+  const stats = [
+    { val: data.num_speakers, label: 'SPEAKERS' },
+    { val: data.segments.length, label: 'SEGMENTS' },
+    { val: data.audio_duration.toFixed(1) + 's', label: 'DURATION' },
+    { val: data.processing_time.toFixed(2) + 's', label: 'PROC TIME' },
+  ];
+  document.getElementById('statsRow').innerHTML = stats.map(s =>
+    `<div class="stat">
+      <div class="stat-val">${s.val}</div>
+      <div class="stat-label">${s.label}</div>
+    </div>`
+  ).join('');
+
+  // Build speaker→color map
+  const colorMap = {};
+  data.speakers.forEach((sp, i) => {
+    colorMap[sp] = SPEAKER_COLORS[i % SPEAKER_COLORS.length];
+  });
+
+  // Timeline
+  const duration = data.audio_duration;
+  const ruler = document.getElementById('timelineRuler');
+  const ticks = 8;
+  ruler.innerHTML = Array.from({ length: ticks + 1 }, (_, i) =>
+    `<span>${fmtTime(duration * i / ticks)}</span>`
+  ).join('');
+
+  // One track per speaker
+  const tracksEl = document.getElementById('timelineTracks');
+  tracksEl.innerHTML = '';
+
+  data.speakers.forEach(sp => {
+    const track = document.createElement('div');
+    track.className = 'timeline-track';
+    track.innerHTML = `<span class="track-label">${sp}</span>`;
+
+    const spSegs = data.segments.filter(s => s.speaker === sp);
+    spSegs.forEach(seg => {
+      const left = (seg.start / duration) * 100;
+      const width = (seg.duration / duration) * 100;
+      const seg_el = document.createElement('div');
+      seg_el.className = 'timeline-segment';
+      seg_el.style.cssText = `left:${left}%;width:${Math.max(width, 0.3)}%;background:${colorMap[sp]};`;
+      seg_el.title = `${sp}: ${seg.start.toFixed(2)}s – ${seg.end.toFixed(2)}s`;
+      if (width > 3) seg_el.textContent = fmtTime(seg.duration);
+      track.appendChild(seg_el);
+    });
+
+    tracksEl.appendChild(track);
+  });
+
+  // Segment table
+  const tbody = document.getElementById('segTableBody');
+  tbody.innerHTML = data.segments.map((seg, i) =>
+    `<tr>
+      <td style="color:var(--muted)">${i + 1}</td>
+      <td>
+        <span class="speaker-dot" style="background:${colorMap[seg.speaker]}"></span>
+        ${seg.speaker}
+      </td>
+      <td>${seg.start.toFixed(3)}</td>
+      <td>${seg.end.toFixed(3)}</td>
+      <td>${seg.duration.toFixed(3)}s</td>
+    </tr>`
+  ).join('');
+}
+
+function fmtTime(sec) {
+  const m = Math.floor(sec / 60);
+  const s = (sec % 60).toFixed(1).padStart(4, '0');
+  return `${m}:${s}`;
+}
+</script>
+</body>
+</html>

utils/audio.py

@@ -0,0 +1,68 @@
+"""Audio utility functions for the diarization pipeline."""
+
+import io
+import numpy as np
+import torch
+import torchaudio
+from pathlib import Path
+from typing import Union, Tuple, Iterator
+from loguru import logger
+
+SUPPORTED_FORMATS = {".wav", ".mp3", ".flac", ".ogg", ".m4a", ".webm"}
+TARGET_SAMPLE_RATE = 16000
+
+
+def load_audio(source, target_sr: int = TARGET_SAMPLE_RATE) -> Tuple[torch.Tensor, int]:
+    if isinstance(source, bytes):
+        source = io.BytesIO(source)
+    waveform, sr = torchaudio.load(source)
+    if waveform.shape[0] > 1:
+        waveform = waveform.mean(dim=0, keepdim=True)
+    if sr != target_sr:
+        resampler = torchaudio.transforms.Resample(orig_freq=sr, new_freq=target_sr)
+        waveform = resampler(waveform)
+        sr = target_sr
+    return waveform.squeeze(0), sr
+
+
+def pcm_bytes_to_tensor(data: bytes, dtype=np.float32) -> torch.Tensor:
+    arr = np.frombuffer(data, dtype=dtype).copy()
+    return torch.from_numpy(arr)
+
+
+def chunk_audio(audio, sample_rate, chunk_duration=30.0, overlap=1.0):
+    chunk_samples = int(chunk_duration * sample_rate)
+    step_samples = int((chunk_duration - overlap) * sample_rate)
+    n = len(audio)
+    for start in range(0, n, step_samples):
+        end = min(start + chunk_samples, n)
+        yield audio[start:end], start / sample_rate
+        if end == n:
+            break
+
+
+def format_timestamp(seconds: float) -> str:
+    hours = int(seconds // 3600)
+    minutes = int((seconds % 3600) // 60)
+    secs = seconds % 60
+    return f"{hours:02d}:{minutes:02d}:{secs:06.3f}"
+
+
+def segments_to_rttm(segments, audio_name: str = "audio") -> str:
+    lines = []
+    for seg in segments:
+        duration = seg.end - seg.start
+        lines.append(
+            f"SPEAKER {audio_name} 1 {seg.start:.3f} {duration:.3f} "
+            f"<NA> <NA> {seg.speaker} <NA> <NA>"
+        )
+    return "\n".join(lines)
+
+
+def segments_to_srt(segments) -> str:
+    lines = []
+    for i, seg in enumerate(segments, 1):
+        start = format_timestamp(seg.start).replace(".", ",")
+        end = format_timestamp(seg.end).replace(".", ",")
+        lines.append(f"{i}\n{start} --> {end}\n[{seg.speaker}]\n")
+    return "\n".join(lines)