Real-time Transcription

Transcribe a live audio or video stream as it happens

Real-time transcription turns a live audio or video stream into a Trint transcript while it is still playing. You provide a stream for Trint to read, Trint creates a Trint (transcript) document, and the transcript fills in continuously until you stop it. Authenticate every request with Basic Authentication using your API key ID and secret.

There are two ways to feed Trint a stream:

  • Pull — you host the stream and give Trint a streamUrl. Start it with Begin real-time transcription.
  • Push — Trint hosts an RTMP or SRT endpoint and you push media to it. Get the endpoint from Create a push stream, then start sending media to it.

SRT is in beta for both pull and push. See SRT streams.

Once a transcript is running you can poll its status and stop it when the broadcast ends.

Real-time must be enabled on your account

If real-time transcription is not enabled for your account, the pull and push endpoints return 402 with Realtime functionality has not been enabled for your account, please speak to your Customer Success Account Manager. SRT must also be enabled for your organisation: without it, an SRT request returns 403 with SRT streaming not enabled for user. Contact your account manager to turn on either one.

Begin real-time transcription

Start a new real-time transcript from a stream you host. Pass the streamUrl Trint should read, and optionally a title, language and transcriptDelay (how many seconds Trint waits before emitting transcript text). The response contains the _id of the newly created Trint, which you use to check its status.

Begin realtime transcription

puthttps://api.trint.com/transcripts/realtime/

Start new Realtime transcript

Body parameters

titlestringoptional

Transcript title

languagestringoptional

Transcription language

streamUrlstringoptional

This will be your media url, for example rtmps://encoder.example.com/live/<stream key> (RTMPS) or https://cdn.example.com/live/stream.m3u8 (HLS). For SRT: srt://<host>:<port>, with ?passphrase=<passphrase> if your listener is encrypted, and streamid=<id> if your listener needs one. If you send mode, it must be caller. Trint drops all other query parameters.

transcriptDelaystringoptional

numbers 1 - 10

workspaceIdstringoptional

ID of the Workspace / Shared Drive in which to create the new Trint (optional)

folderIdstringoptional

ID of the Shared Drive Folder in which to create the new Trint (optional)

timezoneOffsetinteger (int32)optional

specifies the timezone offset from UTC in milliseconds, e.g., 3600000 for UTC+1

metadatastringoptional

Metadata to be included in the callback event

streamingProtocolstringoptional

Streaming protocol (optional). Defaults to RTMP when not passed. SRT is in beta and must be enabled for your organisation. Required for an srt:// streamUrl.

Allowed: RTMP, SRT

PUT /
curl --request PUT \  --url 'https://api.trint.com/transcripts/realtime/' \
  --header 'Authorization: Basic YOUR_BASE64_KEY_ID_AND_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{}'

Response 200

200 response
{
  "_id": "<newly created trintId>"
}
200200
400400
402Realtime functionality has not been enabled for your account, please speak to your Customer Success Account Manager.
403SRT streaming not enabled for user (streamingProtocol: SRT only)

Create a push stream

Instead of hosting your own stream, generate a Trint-hosted RTMP or SRT endpoint and push media to it. The response depends on streamingProtocol:

  • RTMP (default): a streamUrl (for example rtmps://stream.trint.com/live) and a single-use streamKey to authenticate the push, along with the streamId and trintId for the new transcript. Your encoder publishes to rtmps://stream.trint.com/live/<stream key>.
  • SRT (beta): a single streamUrl (for example srt://live.trint.com:8890?streamid=publish:live/<stream key>&passphrase=<passphrase>) that already contains the stream ID and passphrase, along with the trintId. See Push over SRT.

Create Push Stream

posthttps://api.trint.com/transcripts/realtime/push

Generate a stream key and stream url for a rtmp fed realtime trint, or a stream url for an SRT fed one

Body parameters

titlestringoptional

Transcript title

languagestringoptional

Transcription language

transcriptDelaystringoptional

numbers 2 - 20

workspaceIdstringoptional

ID of the Workspace / Shared Drive in which to create the new Trint (optional)

folderIdstringoptional

ID of the Shared Drive Folder in which to create the new Trint (optional)

timezoneOffsetinteger (int32)optional

specifies the timezone offset from UTC in milliseconds, e.g., 3600000 for UTC+1

metadatastringoptional

Metadata to be included in the callback event

streamingProtocolstringoptional

Streaming protocol (optional). Defaults to RTMP when not passed. SRT is in beta and must be enabled for your organisation.

Allowed: RTMP, SRT

POST /push
curl --request POST \  --url 'https://api.trint.com/transcripts/realtime/push' \
  --header 'Authorization: Basic YOUR_BASE64_KEY_ID_AND_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{}'

Response 200 · RTMP

200 response
{
  "streamId": "<newly created stream id>",
  "streamUrl": "rtmps://stream.trint.com/live",
  "streamKey": "<single use stream key>",
  "title": "trint title",
  "trintId": "<newly created trint id>"
}

Response 200 · SRT

200 response
{
  "streamUrl": "srt://live.trint.com:8890?streamid=publish:live/<stream key>&passphrase=<passphrase>",
  "title": "trint title",
  "trintId": "<newly created trint id>",
  "srtPassphrase": "<passphrase>"
}
200200
400400
402Realtime functionality has not been enabled for your account, please speak to your Customer Success Account Manager.
403SRT streaming not enabled for user (streamingProtocol: SRT only)

Get real-time status

Poll the current status of a running real-time transcript by its Trint ID. The response reports the processing status, any non-critical warnings (such as failed to generate waveform), any critical errors (such as could not detect media), and the started and expires timestamps in ISO 8601 format.

Get realtime status

gethttps://api.trint.com/transcripts/realtime/{trint-id}

Get the current status of a realtime

Path parameters

trint-idstringrequired

id of the realtime trint

GET /{trint-id}
curl --request GET \  --url 'https://api.trint.com/transcripts/realtime/:trint-id' \
  --header 'Authorization: Basic YOUR_BASE64_KEY_ID_AND_SECRET'

Response 200

200 response
{
  "status": "TRANSCRIBING",
  "warnings": [
    "failed to generate waveform"
  ],
  "errors": [
    "could not detect media"
  ],
  "started": "2021-08-20T15:11:33.331Z",
  "expires": "2021-08-20T21:11:33.330Z"
}
200200
400400
403403
404404

Stop real-time transcription

Stop a running real-time transcript and close the session. Send the trintId of the transcript. streamId is still accepted but deprecated, and SRT streams do not return one. Send one of the two, not both. A successful request returns 200.

Stop realtime transcription

deletehttps://api.trint.com/transcripts/realtime/

Stop a running Realtime transcript. Send one of trintId or streamId.

Body parameters

streamIdstringoptional

Deprecated: use trintId. Not returned for SRT streams.

trintIdstringoptional

ID of the realtime Trint. Send this or streamId, not both.

DELETE /
curl --request DELETE \  --url 'https://api.trint.com/transcripts/realtime/' \
  --header 'Authorization: Basic YOUR_BASE64_KEY_ID_AND_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{}'

Response 200

200 response
{
  "data": {
    "stopLiveTrint": {
      "_id": "<stream id>"
    }
  }
}
200200
400400

SRT streams Beta

SRT is in beta

SRT must be enabled for your organisation. Contact your account manager to turn it on.

SRT is an alternative to RTMP that copes better with packet loss on public networks. Both the pull and the push endpoints accept SRT: add "streamingProtocol": "SRT" to the request body. The other request fields are unchanged, with one exception: SRT does not support the multi-language code mlt.

Recommended SRT stream settings

Video

SettingValue
CodecH.264
Resolution480p (854x480)
Frame rate25 or 30 fps
Bitrate1-1.5 Mbps, constant bitrate (CBR)
Keyframe interval2 seconds (GOP = 2 x frame rate)

Audio

SettingValue
CodecAAC-LC
Bitrate128 kbps
Sample rate44.1 kHz

Transport

SettingValue
ContainerMPEG-TS over SRT
Total bitrateAbout 1.2-1.7 Mbps. We recommend at least 2.5 Mbps of stable upload bandwidth.

Push over SRT Beta

Call Create a push stream with "streamingProtocol": "SRT".

bash
curl -X POST https://api.trint.com/transcripts/realtime/push \
  -u "$API_KEY_ID:$API_KEY_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "title": "My SRT stream", "language": "en", "streamingProtocol": "SRT" }'

The response is different from RTMP:

json
{
  "streamUrl": "srt://live.trint.com:8890?streamid=publish:live/<stream key>&passphrase=<passphrase>",
  "title": "My SRT stream",
  "trintId": "<newly created trint id>",
  "srtPassphrase": "<passphrase>"
}
  • Give the whole streamUrl to your encoder. It already contains the stream ID and the passphrase, so do not split it or build it again.
  • srtPassphrase is the same passphrase, for encoders that ask for it in a separate field.
  • The response has no streamKey or streamId field: the stream key is already part of streamUrl. Use the trintId to get the status and to stop the stream.
  • If your encoder disconnects, reconnect with the same streamUrl within 10 minutes and the transcript continues in the same Trint. After 10 minutes the stream ends; create a new push stream.

Pull over SRT Beta

Run an SRT listener and call Begin real-time transcription with its URL and "streamingProtocol": "SRT".

bash
curl -X PUT https://api.trint.com/transcripts/realtime \
  -u "$API_KEY_ID:$API_KEY_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "My SRT stream",
    "language": "en",
    "streamUrl": "srt://encoder.example.com:9000?passphrase=<passphrase>",
    "streamingProtocol": "SRT"
  }'
  • The streamUrl is srt://<host>:<port>. Add ?passphrase=<passphrase> if your listener is encrypted, and streamid=<id> if your listener needs one. If you send mode, it must be caller. Trint drops all other query parameters. The passphrase must be 10 to 80 bytes.
  • An srt:// URL without "streamingProtocol": "SRT" returns 400. Trint does not take the protocol from the URL.
  • The response is the same as for RTMP: the _id of the new Trint.