Voices and speakers

Three different things that are easy to confuse:

• A speaker of a recording is the voice number inside one recording: segments[].speaker = 0, 1, 2… In the next recording the same person may sit under another number.
• A project voice is a person's permanent number across all recordings of the project: #100, #101… It appears when "Recognise by voice" is on.
• A name is what you called a project voice: "Azimbek (manager)". A name is optional: an unnamed voice is recognised too.

How voices get numbers

When a recording is processed with "Recognise by voice" on:

1. A voice print is computed for every speaker of the recording.
2. The print is compared with the project's voices. A match: the speaker gets that voice's number, status matched.
3. No match, and the speaker has 10 seconds of speech or more: a new project voice is registered with the next number, status new.
4. Less than 10 seconds of speech: status unknown, no number. A print from a few seconds is unreliable, and we do not open a voice on it.

The link between speakers of the recording and project voices is in voices:

"voices": [
  {"label": "SPEAKER_1", "speaker": 0, "voice_id": 100, "name": null, "status": "new"},
  {"label": "SPEAKER_2", "speaker": 1, "voice_id": 101, "name": "Azimbek", "status": "matched", "score": 0.97}
]

speaker is the number from segments[].speaker, voice_id the project voice number, speaker_id its identifier for the speakers API.

How long a voice lives

Not every voice heard once is worth keeping forever, so a voice has a kind, visible in kind:

Kind	What it is	How long it lives
candidate	Heard in one recording	30 days from the last time it was heard, then it goes
recurring	Heard in three recordings or more	Kept until deleted
named	A voice someone named	Kept until deleted

A candidate heard again refreshes last_seen_at and the count starts over; on the third recording it becomes recurring and the expiry is lifted. A name lifts it at once: name a voice and it stays. So a colleague's voice is better named the first time round than left to a third recording.

expires_at says when the voice will go; for recurring and named it is empty.

Give a name

The cabinet's "Speakers" tab lists every project voice: named ones and "Voice #100" ones recognised automatically. "Name it" turns the number into a name. Through the API: PATCH /v1/speakers/{id} with {"name": "…"}.

Mark pieces as one person

Sometimes speaker separation gets it wrong: one person lands in two numbers, or the other way round. A recording's result has a "Mark one person's pieces" mode: select the utterances that surely belong to one person and say who it is: an existing voice or a new name. A print is computed from the selected utterances and added to that voice. The more speech selected, the more reliable; the cabinet warns below 10 seconds.

Through the API: POST /v1/speakers/{id}/enroll with {"job_id": "…", "segment_indexes": [3, 5, 8]}. The utterance numbers are enough: the print is computed on our side from the stored recording. The prints themselves are not in the result — they are biometric data and hundreds of numbers per voice, with nothing to do with them directly.

Upload a voice sample

On the "Speakers" tab you can upload a short recording of one person (say 20–30 seconds of a manager speaking) and attach it to a voice right away. The recording is recognised as a normal job, so it spends balance like any other.

A voice is biometric data

Add voices only with the person's consent. Deleting a voice deletes all its prints: DELETE /v1/speakers/{id}. A voice keeps at most 10 prints, a project at most 500 voices.