polyvoice 0.11.0

# polyvoice

[![CI](https://github.com/ekhodzitsky/polyvoice/actions/workflows/ci.yml/badge.svg)](https://github.com/ekhodzitsky/polyvoice/actions/workflows/ci.yml)
[![Crates.io](https://img.shields.io/crates/v/polyvoice)](https://crates.io/crates/polyvoice)
[![Docs.rs](https://docs.rs/polyvoice/badge.svg)](https://docs.rs/polyvoice)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

**Speaker diarization for Rust — who spoke when, on CPU, without Python.**

Beta-quality, ONNX-powered, ~30 MB. Embeds into any Rust app, with Python, C, and
CLI bindings.

```
Speaker_0: 0.0s - 12.3s
Speaker_1: 14.1s - 28.7s
Speaker_0: 31.2s - 45.0s
```

Like-for-like (collar 0, overlap-scored) VoxConverse-test DER is **15.4%**
(v2+VBx default) vs pyannote 3.1's **11.3%** — a few DER points traded for a
CPU-only, MIT, **ungated** engine that needs no Python — see
[Benchmarks](docs/BENCHMARKS.md).

## Install

### Pre-built CLI binary

Download the latest binary for your platform from the [GitHub Releases](https://github.com/ekhodzitsky/polyvoice/releases) page:

```bash
# Linux x86_64
curl -L -o polyvoice https://github.com/ekhodzitsky/polyvoice/releases/latest/download/polyvoice-linux-x86_64
chmod +x polyvoice
sudo mv polyvoice /usr/local/bin/

# Linux ARM64
curl -L -o polyvoice https://github.com/ekhodzitsky/polyvoice/releases/latest/download/polyvoice-linux-aarch64
chmod +x polyvoice
sudo mv polyvoice /usr/local/bin/

# macOS (Apple Silicon)
curl -L -o polyvoice https://github.com/ekhodzitsky/polyvoice/releases/latest/download/polyvoice-macos-arm64
chmod +x polyvoice
sudo mv polyvoice /usr/local/bin/
```

### Docker

```bash
docker run --rm -v "$(pwd):/work" ghcr.io/ekhodzitsky/polyvoice:latest diarize /work/meeting.wav --output /work/meeting.rttm
```

### Rust library

```bash
cargo add polyvoice --features "onnx,download"
```

### Python

```bash
pip install polyvoice
```

### From source

```bash
# CLI (WAV 16 kHz mono input). Feature `cli` includes VBx (default clusterer).
cargo install polyvoice --features cli

# CLI + any-format audio (mp3/flac/ogg/m4a/aac, any sample rate → 16 kHz mono)
cargo install polyvoice --features "cli,audio-io"
```

## Usage

```rust,no_run
use polyvoice::models::ModelRegistry;
use polyvoice::pipeline_v2::{ClustererKind, Pipeline, PipelineConfig};
use polyvoice::types::{Profile, SampleRate};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut cfg = PipelineConfig {
        profile: Profile::Balanced,
        clusterer: ClustererKind::Vbx, // or Ahc { threshold: 0.45 }
        ..PipelineConfig::default()
    };
    // VBx needs PLDA weights: cfg.vbx_plda_dir = Some("data/vbx-plda".into());
    // or POLYVOICE_VBX_PLDA_DIR in the environment.
    let pipeline = Pipeline::builder()
        .config(cfg)
        .with_models_from(ModelRegistry::default()?) // models auto-download on first run
        .build()?;

    // Pipeline-ready mono 16 kHz (with feature `audio-io`, also mp3/flac/… + resample).
    // Without that feature, load_audio accepts 16 kHz WAV only.
    let (samples, sr) = polyvoice::wav::load_audio(std::path::Path::new("meeting.wav"))?;
    let result = pipeline.run(&samples, SampleRate::new(sr).ok_or("bad sample rate")?)?;

    for turn in &result.turns {
        println!("{}: {:.1}s - {:.1}s", turn.speaker, turn.time.start, turn.time.end);
    }
    Ok(())
}
```

```bash
polyvoice download-models --profile balanced
# Default path: pipeline v2 + VBx (needs PLDA)
export POLYVOICE_VBX_PLDA_DIR=/path/to/vbx-plda   # see docs/vbx-plda-release.md
polyvoice diarize meeting.wav --output meeting.rttm
# Without PLDA: --clusterer ahc   |   old path: --legacy
# With a build that includes `audio-io`:
# polyvoice diarize meeting.mp3 --output meeting.rttm
```

Python usage and the full API live on [docs.rs](https://docs.rs/polyvoice).

## Why polyvoice

- **Maintained, pure-Rust, streaming-capable.** The popular `sherpa-rs` bindings
  are archived; polyvoice is an actively-maintained, pure-Rust diarization path
  (ONNX via `ort`, no C++ toolkit) with first-class streaming.
- **One library, four surfaces.** Rust + Python + C FFI + CLI from a single crate.
- **CPU-first, ~30 MB, MIT.** No GPU, no Python runtime, no gated model access.

It is **not** the accuracy leader — like-for-like (collar 0, overlap-scored)
VoxConverse-test DER is **15.4%** (v2+VBx default) versus **11.3%** for
pyannote 3.1. It trades those DER points for deployability: a pure-Rust, CPU,
MIT, **ungated** engine (pyannote's weights are gated behind an HF token) with
four bindings and streaming.

## How it works

```
audio (f32 PCM)
  → VAD / Powerset segmentation
  → WeSpeaker embeddings
  → clustering (AHC / K-means / NME-SC, automatic speaker count)
  → speaker turns
```

Streaming (`OnlineDiarizer`) and batch (`OfflineDiarizer`), with a single-speaker
guard so quiet or single-voice audio does not hallucinate clusters.

## Documentation

- [Benchmarks](docs/BENCHMARKS.md) — collar-disclosed DER numbers and provenance
- [Production readiness](PRODUCTION-READINESS.md) — deployment guidance (GO / NO-GO)
- [Migrating from 0.5](docs/MIGRATING-FROM-0.5.md) · [Glossary](docs/GLOSSARY.md)
- [Contributing](CONTRIBUTING.md) · [Changelog](CHANGELOG.md)

## License

MIT

---

> **Name:** this project is **polyvoice — speaker diarization for Rust**,
> unrelated to ByteDance's "PolyVoice" speech-translation research.