Add Messaging, Voice, and Authentication to your apps with Vonage Communications APIs
Visit the Vonage API Developer PortalUse the OpenTok live captions API to enable real-time audio captioning of the publishers and subscribers connected to an OpenTok session.
Live captioning must be enabled at the session level via the REST API.
Live captioning is only supported in routed session.
This topic includes the following sections:
A publisher may be initialized with the optional boolean publishCaptions parameter.
The parameter is passed in via the properties object. This parameter
will be false by default.
const publisher = OT.initPublisher({ publishCaptions: true });
After live captions is enabled, a publisher may start or stop sending captions by calling the publishCaptions method. This method accepts a boolean as its parameter.
The code below shows an example of stopping live captions for a publisher.
publisher.publishCaptions(false);
The code below shows an example of starting live captions for a publisher.
publisher.publishCaptions(true);
An OpenTok subscriber may choose to begin or stop receiving live captions.
A subscriber may start or stop receiving captions by calling the asynchronous subscribeToCaptions method. This method accepts a boolean as its parameter.
The method can be called regardless of whether the publisher is currently publishing live captions. The subscriber will start receiving captions data once the publisher begins publishing captions.
The code below shows an example of starting live captions for a subscriber.
try {
await subscriber.subscribeToCaptions(true);
} catch (err) {
console.warn(err);
}
The code below shows an example of stopping live captions for a subscriber.
try {
await subscriber.subscribeToCaptions(false);
} catch (err) {
console.warn(err);
}
Subscribers may verify whether they are actively subscribed to a publisher's live captions using the isSubscribedToCaptions method. This method has no parameters and returns a boolean
const isSubscribed = subscriber.isSubscribedToCaptions()
console.log(`${isSubscribed} states whether or not a given subscriber is subscribing to live captions`).
Subscribers receive captions via events. The OpenTok SDK does not display the text of the captions events.
A subscriber that is actively subscribed to live captions will dispatch captionReceived events. The captionReceived event object has three properties: caption, streamId, and isFinal. streamId is the ID of the stream, while caption is the transcribed text. isFinal indicates whether a caption is finished being transcribed. This value is only relevant when using partial captions. The developer may choose how and where to render the caption's text.
subscriber.on('captionReceived', function(event){
console.log(`Caption received for stream ${event.streamId}`);
console.log(`Caption text: ${event.caption}`);
console.log(`Final text: ${event.isFinal}`);
})
The following shows the console logs when using partial captions and having a publisher say "This is my sentence."
subscriber.on('captionReceived', function(event){
console.log(`The ${event.isFinal ? 'complete' : 'partial'} caption text is: "${event.caption}"`)
})
// The partial caption text is: "This"
// The partial caption text is: "This is"
// The partial caption text is: "This is my"
// The complete caption text is: "This is my sentence"
The Vonage web client SDK does not support a publisher receiving events for its own captions. To render the speaker's own captions, create a hidden subscriber (to the local publisher's stream) to listen for the caption events. This subscriber should not be attached to the DOM and should not subscribe to audio, to avoid echo. You can add the captions can then to the UI.
The following shows the creation of a hidden subscriber for the publisher to receive its own captions.
const captionOnlySub = session.subscribe(
publisher.stream,
document.createElement('div'),
{
audioVolume: 0,
testNetwork: true, // This option is only needed in OpenTok.js versions below 2.25.1
},
);
captionOnlySub.on('captionReceived', (event) => {
// Do something with the event.caption
});
Note: For OpenTok.js 2.25.0 and earlier, you need to set testNetwork to true in the options passed into Session.subscribe(), due to a bug.
The opentok-web-samples Basic-Captions sample uses live captions in a web app built with the Vonage web client SDK.