# Who (`who-1`): Speaker diarization

Who spoke when, from a recording. No transcript needed.

Who splits a recording into turns and labels each one with a speaker (SPEAKER_1, SPEAKER_2...), with start and end times and each person's total talk time. It recognizes the same voice across the whole file, so a speaker who comes back later keeps their label.

Set `num_speakers` when you know how many people are talking. For a transcript with speakers, send `speakers: true` to Scribe instead: it runs Who for you.

- **Price:** $0.0003 per minute. Billed per second of audio, rounded up, at least one second.
- **Languages:** Any (works on voices, not words)

- **Input:** An audio or video file: an https URL, a data URL, or a file in a multipart upload, up to 25 MB and 10 minutes.
- **Batch:** no, one input per call
- **Status:** live
- **Built on:** [pyannote/segmentation-3.0 + WeSpeaker ResNet34 (with our clustering)](https://huggingface.co/pyannote/segmentation-3.0), MIT and CC-BY-4.0, 1.5M + 6.6M

## Request

```bash
curl https://labs.greatwork.company/v1/run \
  -H "Authorization: Bearer $GWL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"who-1","input":"https://labs.greatwork.company/examples/two-voices.m4a"}'
```

Upload a local file with multipart: `curl https://labs.greatwork.company/v1/run -H "Authorization: Bearer $GWL_API_KEY" -F model=who-1 -F input=@file`

## Options

| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| `input` | audio (URL, data URL or upload) | yes | | An audio or video file: an https URL, a data URL, or a file in a multipart upload, up to 25 MB and 10 minutes. |
| `num_speakers` | integer | no |  | Exact number of speakers, if you know it. |
| `max_speakers` | integer | no | `8` | Upper limit when the number isn't known. |
| `threshold` | number | no | `0.5` | How similar two voices must be to count as one speaker. Raise it if two people get merged, lower it if one person gets split. |

## Output

| Field | Type | Description |
|---|---|---|
| `speakers` | integer | How many speakers were found. |
| `segments` | object[] | Turns in order: `speaker`, `start`, `end` (seconds). |
| `speaking_time` | object | Seconds of speech per speaker. |
| `duration` | number | Audio length in seconds. |

The response envelope is always `{"id", "object": "run", "model", "created", "output", "usage": {"units", "unit", "cost_usd", "cost_micros"}, "latency_ms"}`.

## Examples (real outputs from our servers)

### Two people

```json
{
  "model": "who-1",
  "input": "https://labs.greatwork.company/examples/two-voices.m4a"
}
```

```json
{
  "speakers": 2,
  "segments": [
    {
      "speaker": "SPEAKER_1",
      "start": 0,
      "end": 3.89
    },
    {
      "speaker": "SPEAKER_2",
      "start": 4.04,
      "end": 8.91
    },
    {
      "speaker": "SPEAKER_1",
      "start": 9,
      "end": 12.55
    },
    {
      "speaker": "SPEAKER_2",
      "start": 12.69,
      "end": 17.23
    }
  ],
  "speaking_time": {
    "SPEAKER_1": 7.44,
    "SPEAKER_2": 9.41
  },
  "duration": 17.41
}
```

956 ms, $0.00009.

### Known count

```json
{
  "model": "who-1",
  "input": "https://labs.greatwork.company/examples/two-voices.m4a",
  "num_speakers": 2
}
```

```json
{
  "speakers": 2,
  "segments": [
    {
      "speaker": "SPEAKER_1",
      "start": 0,
      "end": 3.89
    },
    {
      "speaker": "SPEAKER_2",
      "start": 4.04,
      "end": 8.91
    },
    {
      "speaker": "SPEAKER_1",
      "start": 9,
      "end": 12.55
    },
    {
      "speaker": "SPEAKER_2",
      "start": 12.69,
      "end": 17.23
    }
  ],
  "speaking_time": {
    "SPEAKER_1": 7.44,
    "SPEAKER_2": 9.41
  },
  "duration": 17.41
}
```

966 ms, $0.00009.

## Good for

- Split meeting recordings by speaker
- Measure talk time on sales calls
- Label podcast hosts and guests
- Find the customer's turns in a support call

## Limits and caveats

- Speakers are numbered, not named.
- Overlapping speech is given to one speaker.
- Very short turns (under a quarter second) are dropped.
- Similar voices (same person on two mics, close relatives) can merge: set `num_speakers` when you know it.
