# Transcripts

> Post-call transcripts: speech-to-text over every participant's microphone, per speaker and language, as JSON, WebVTT, SRT or text.

When a session ends, Synento can transcribe it. Each participant's microphone
is transcribed on its own, so every line of the transcript names who said it,
and each person's language is detected separately: a call where one person
speaks English and another Spanish comes back with both.

Transcripts are written as caption cues into the session's recording, so
replay shows them as captions and they are deleted with the session.

## Turn it on

**For every session in a project.** Turn on automatic transcripts in the
dashboard (Projects → Edit), or:

```bash
curl -X PUT https://api.synento.com/v1/projects/$PROJECT_ID/transcription \
  -H "Authorization: Bearer $SYNENTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": true, "language": "auto" }'
```

A few minutes after a session ends, it is transcribed. The wait lets people
who drop and rejoin finish the call, so one call is usually one run.

**For one session, on demand.** Once a session has ended:

```bash
curl -X POST https://api.synento.com/v1/sessions/$SESSION_ID/transcript \
  -H "Authorization: Bearer $SYNENTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "language": "auto" }'
```

The request is idempotent: asking again returns the transcript already queued,
running or finished (`"is_reused": true`). If people rejoined and spoke after
the last run, only what is new is transcribed.

With the Node SDK: `await synento.requestTranscript(sessionId)`. With the CLI:
`synento transcript <sessionId> --request`. With an agent over MCP:
`request_transcript`.

## Languages

| `language` | What happens |
|------------|--------------|
| `auto` (default) | Each participant's language is detected from their own speech |
| `multi` | For speakers who switch languages mid-sentence; each word is labelled |
| A BCP-47 tag, e.g. `en`, `es`, `pt-BR` | Everyone is transcribed in that language |

Cues are grouped by language: the transcript's `languages` lists them, and the
session has one caption stream per language. A language the speech-to-text
provider does not support fails the transcript with `unsupported_language`.

A session keeps the language setting it was first transcribed with; asking for
a different one is refused with `409`.

## Read it

```bash
curl https://api.synento.com/v1/sessions/$SESSION_ID/transcript \
  -H "Authorization: Bearer $SYNENTO_API_KEY"
```

```json
{
  "data": {
    "session_id": "…",
    "status": "ready",
    "language": "auto",
    "languages": ["en", "es"],
    "speech_seconds": 412.6,
    "origin_ts": 1794593215983,
    "cues": [
      { "start_ms": 1200, "end_ms": 4800, "speaker": "alice", "lang": "en", "text": "Thanks for joining." },
      { "start_ms": 5100, "end_ms": 7900, "speaker": "bob", "lang": "es", "text": "Gracias por la invitación." }
    ]
  },
  "error": null
}
```

- `speaker` is the participant's user id, the one you gave their connection token.
- `start_ms` and `end_ms` count from the start of the recording (`origin_ts`,
  epoch ms). That is where an MP4 export starts too, so the times line up with
  an exported file.
- `?lang=es` returns only one language's cues.
- `?format=vtt`, `srt` or `txt` returns a subtitle file, or plain text grouped
  by speaker, once the transcript is `ready`.

### Status

| `status` | Meaning |
|----------|---------|
| `pending` | Queued |
| `processing` | Being transcribed. Cues already written are returned |
| `ready` | Done |
| `failed` | Gave up. `error_code` says why: `unsupported_language`, `provider_rejected`, `processing_failed` or `unavailable` |
| `skipped` | Not run: the Free plan's transcription minutes are used up (`error_code: allowance`) |

Instead of polling, subscribe a webhook to `transcript.ready`:

```json
{ "type": "transcript.ready", "project_id": "…", "session_id": "…",
  "data": { "languages": ["en", "es"], "speech_seconds": 412 } }
```

## Pricing

Transcription is billed per minute of speech. Silence and muted time are cut
out before anything is sent for transcription, and only what is sent counts,
summed over participants. A call where one person talks at a time comes to
about its own length; a 4-person, 60-minute call is not 240 minutes.

| Plan | Included each month | Past that |
|------|--------------------|-----------|
| Free | 60 minutes | refused (`403 PLAN_LIMIT`, or `skipped` for an automatic run) |
| Pay-as-you-go | 60 minutes | $0.006 a minute |

`speech_seconds` on the transcript is what was billed for it.

## Privacy

Audio is decoded only for a transcript you turned on or asked for. The speech is
sent to [Deepgram](https://deepgram.com) for speech-to-text, with every request
opted out of Deepgram's model improvement programme, so it is not used to train
their models. The transcript lives in the session's
recording: it follows the project's retention, is deleted with the session,
and redacting a participant removes their lines.
