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
https://api.trint.com/transcripts/realtime/Start new Realtime transcript
Body parameters
titlestringoptionalTranscript title
languagestringoptionalTranscription language
streamUrlstringoptionalThis 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.
transcriptDelaystringoptionalnumbers 1 - 10
workspaceIdstringoptionalID of the Workspace / Shared Drive in which to create the new Trint (optional)
folderIdstringoptionalID of the Shared Drive Folder in which to create the new Trint (optional)
timezoneOffsetinteger (int32)optionalspecifies the timezone offset from UTC in milliseconds, e.g., 3600000 for UTC+1
metadatastringoptionalMetadata to be included in the callback event
streamingProtocolstringoptionalStreaming 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
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
{
"_id": "<newly created trintId>"
}200200400400402Realtime 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 examplertmps://stream.trint.com/live) and a single-usestreamKeyto authenticate the push, along with thestreamIdandtrintIdfor the new transcript. Your encoder publishes tortmps://stream.trint.com/live/<stream key>. - SRT (beta): a single
streamUrl(for examplesrt://live.trint.com:8890?streamid=publish:live/<stream key>&passphrase=<passphrase>) that already contains the stream ID and passphrase, along with thetrintId. See Push over SRT.
Create Push Stream
https://api.trint.com/transcripts/realtime/pushGenerate a stream key and stream url for a rtmp fed realtime trint, or a stream url for an SRT fed one
Body parameters
titlestringoptionalTranscript title
languagestringoptionalTranscription language
transcriptDelaystringoptionalnumbers 2 - 20
workspaceIdstringoptionalID of the Workspace / Shared Drive in which to create the new Trint (optional)
folderIdstringoptionalID of the Shared Drive Folder in which to create the new Trint (optional)
timezoneOffsetinteger (int32)optionalspecifies the timezone offset from UTC in milliseconds, e.g., 3600000 for UTC+1
metadatastringoptionalMetadata to be included in the callback event
streamingProtocolstringoptionalStreaming protocol (optional). Defaults to RTMP when not passed. SRT is in beta and must be enabled for your organisation.
Allowed: RTMP, SRT
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
{
"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
{
"streamUrl": "srt://live.trint.com:8890?streamid=publish:live/<stream key>&passphrase=<passphrase>",
"title": "trint title",
"trintId": "<newly created trint id>",
"srtPassphrase": "<passphrase>"
}200200400400402Realtime 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
https://api.trint.com/transcripts/realtime/{trint-id}Get the current status of a realtime
Path parameters
trint-idstringrequiredid of the realtime trint
curl --request GET \ --url 'https://api.trint.com/transcripts/realtime/:trint-id' \
--header 'Authorization: Basic YOUR_BASE64_KEY_ID_AND_SECRET'Response 200
{
"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"
}200200400400403403404404Stop 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
https://api.trint.com/transcripts/realtime/Stop a running Realtime transcript. Send one of trintId or streamId.
Body parameters
streamIdstringoptionalDeprecated: use trintId. Not returned for SRT streams.
trintIdstringoptionalID of the realtime Trint. Send this or streamId, not both.
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
{
"data": {
"stopLiveTrint": {
"_id": "<stream id>"
}
}
}200200400400SRT 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
| Setting | Value |
|---|---|
| Codec | H.264 |
| Resolution | 480p (854x480) |
| Frame rate | 25 or 30 fps |
| Bitrate | 1-1.5 Mbps, constant bitrate (CBR) |
| Keyframe interval | 2 seconds (GOP = 2 x frame rate) |
Audio
| Setting | Value |
|---|---|
| Codec | AAC-LC |
| Bitrate | 128 kbps |
| Sample rate | 44.1 kHz |
Transport
| Setting | Value |
|---|---|
| Container | MPEG-TS over SRT |
| Total bitrate | About 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".
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:
{
"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
streamUrlto your encoder. It already contains the stream ID and the passphrase, so do not split it or build it again. srtPassphraseis the same passphrase, for encoders that ask for it in a separate field.- The response has no
streamKeyorstreamIdfield: the stream key is already part ofstreamUrl. Use thetrintIdto get the status and to stop the stream. - If your encoder disconnects, reconnect with the same
streamUrlwithin 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".
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
streamUrlissrt://<host>:<port>. Add?passphrase=<passphrase>if your listener is encrypted, andstreamid=<id>if your listener needs one. If you sendmode, it must becaller. Trint drops all other query parameters. The passphrase must be 10 to 80 bytes. - An
srt://URL without"streamingProtocol": "SRT"returns400. Trint does not take the protocol from the URL. - The response is the same as for RTMP: the
_idof the new Trint.