Model card: document speaker diarization

README.md

@@ -84,15 +84,43 @@ for word in result["words"]:
     print(word)
 ```
 
-### Speaker Labels
+### Speaker Diarization
+
+`return_speakers=True` adds speaker labels. It first transcribes and aligns words (it implies `return_timestamps=True`). It then splits the audio into speech regions with [TEN VAD](https://github.com/TEN-framework/ten-vad), embeds each region with [ECAPA-TDNN](https://huggingface.co/speechbrain/spkrec-ecapa-voxceleb), and clusters the embeddings into speakers. Each word is assigned to the speaker whose segment it overlaps.
+
+Diarization needs a few extra packages:
+
+```bash
+pip install speechbrain ten-vad scikit-learn scipy
+```
 
 ```python
 result = pipe("meeting.wav", return_speakers=True, num_speakers=2)
-for word in result["words"]:
-    print(word)
+
+print(result["text"])
+
+# Speaker turns
+for seg in result["speaker_segments"]:
+    print(f"{seg['start']:6.2f}-{seg['end']:6.2f}  {seg['speaker']}")
+#   0.00-  2.90  SPEAKER_0
+#   3.36-  6.47  SPEAKER_1
+#   6.93-  9.81  SPEAKER_0
+
+# Words with timestamps and speakers
+for w in result["words"]:
+    print(f"{w['start']:6.2f}-{w['end']:6.2f}  {w['speaker']}  {w['word']}")
+#   0.00-  0.19  SPEAKER_0  Hi,
+#   0.22-  0.69  SPEAKER_0  Daniel.
+#   ...
+```
+
+**Setting the speaker count.** Pass `num_speakers` when you know it. Otherwise the number of speakers is estimated from the audio, and on short clips that estimate tends to split one voice into several speakers. You can also bound the estimate with `min_speakers` / `max_speakers`:
+
+```python
+result = pipe("panel.wav", return_speakers=True, min_speakers=2, max_speakers=4)
 ```
 
-`return_speakers=True` implies `return_timestamps=True`. You can pass `num_speakers`, or `min_speakers` / `max_speakers`, when the speaker count is known.
+If diarization fails (for example, a missing package), transcription still succeeds. The error is returned under `result["diarization_error"]` instead of raising.
 
 ### GPU Inference