Receive captions via a WebSocket connection
Get access to captions via our API
This functionality is currently being rolled out and may not be available in your account yet
When a stream is running you can receive new captions via a WebSocket connection. This functionality is currently in beta.
Workflow
- Create a new project with SRT or RTMP source
- Select the WebSocket API output
- Configure the maximum latency for your captions. A minimum of 5 seconds is recommended.
- Use our SDK to subscribe to new captions
Target latency
The target latency setting in a WebSocket project determines the maximum latency of your captions. If you’re delaying your broadcast with 10s, your maximum latency should be 10 seconds. Setting a maximum latency doesn’t mean that captions always arrive after 10s - we send them once finished.
The primary trade-off here is between speed and quality: the lower the latency, the less time there is for Timbra to run transcription and natural captions.
Keeping sync
The WebSocket API contain the captions. Depending on the source, it contains 2 or 3 pairs of timestamps:
- Audio time is based on the audio you’ve sent us. If you’ve sent us 10 seconds of audio, the word that starts at 10.5 seconds will have a audio_time of
10.5- even if 15 seconds have elapsed since the start.
- Approximate wall-clock capture time. This is the time of the caption based on when it was received. Useful to determine when something was said, and to understand the latency between you and Timbra.
- SEI timestamp. If an SEI timestamp is present in the source stream, we’ll expose it as well. This will allow you to sync captions to your internal workflow.
Message delivery
Timbra uses Pusher for highly-available message delivery. A dedicated channel is created for your project, and you can subscribe to it using the CaptionHub SDK (NodeJS), any of Pusher’s client SDKs, or implement your own.
Example code
The following is an example of how to create a project, start the flow, and listen to WebSocket messages, using the captionhub-node-sdk (TypeScript):
import { CaptionHub } from '@captionhub/captionhub-node-sdk';
const captionhub = new CaptionHub("YOUR_API_KEY");
const flow = await captionhub.timbra.createFlow({
name: `My first SRT project`,
source: 'srt_push',
output: 'websocket',
});
captionhub.timbra.startFlow(flow.flow_id);
// Start streaming to `flow.srt_details.full_url`
const websocketConnection = captionhub.timbra.subscribe({
flowId: 'FLOW_ID',
onCaption: (event) => {
console.log("Received captions:", event);
}
});