Transcription & Closed Captions

Available since v5.0.4 — transcription and closed captions require CometChat Calls SDK v5.0.4 or later for Android. See Setup to install or upgrade.

Transcribe call sessions in real time and display live closed captions on screen. Transcripts are stored server-side and can be retrieved after the call using TranscriptRequest.

Transcription must be enabled for your CometChat app. Contact support if you need to enable this feature.

How It Works

Transcription and closed captions are two related but separate things:

Concept	What it does
Transcription	Server-side speech-to-text for the session. Starting it brings a transcriber into the call, which produces the transcript that is stored for later retrieval.
Closed captions	The on-screen overlay that renders the live transcript as it arrives. Captions are produced from the running transcription, so they only appear while transcription is active.

Starting transcription is a prerequisite for captions — toggling captions on without an active transcription shows nothing.

Starting Transcription

Auto-Start Transcription

Configure transcription to start automatically when the session begins:

Kotlin
Java

val sessionSettings = CometChatCalls.SessionSettingsBuilder()
    .enableAutoStartTranscription(true)
    // ... other settings
    .build()

SessionSettings sessionSettings = new CometChatCalls.SessionSettingsBuilder()
    .enableAutoStartTranscription(true)
    // ... other settings
    .build();

Default: false

Manual Transcription Control

Transcription can be started and stopped during an active call through the CallSession singleton.

Start Transcription

Kotlin
Java

val callSession = CallSession.getInstance()
callSession.startTranscription()

CallSession callSession = CallSession.getInstance();
callSession.startTranscription();

Stop Transcription

Stops the current transcription. Any captions currently on screen are cleared:

Kotlin
Java

val callSession = CallSession.getInstance()
callSession.stopTranscription()

CallSession callSession = CallSession.getInstance();
callSession.stopTranscription();

Always check isSessionActive() before calling these actions to ensure there’s an active call.

Built-in UI Controls

On Android, both transcription controls live in the control panel’s More menu and are hidden by default.

Transcription Button

To show the Start Transcription / Stop Transcription item:

Kotlin
Java

val sessionSettings = CometChatCalls.SessionSettingsBuilder()
    .hideTranscriptionButton(false)
    .build()

SessionSettings sessionSettings = new CometChatCalls.SessionSettingsBuilder()
    .hideTranscriptionButton(false)
    .build();

Default: true The menu item toggles between Start Transcription and Stop Transcription based on the current state.

Closed Caption Button

To show the Show Captions / Hide Captions item, which toggles the on-screen captions overlay:

Kotlin
Java

val sessionSettings = CometChatCalls.SessionSettingsBuilder()
    .hideClosedCaptionButton(false)
    .build()

SessionSettings sessionSettings = new CometChatCalls.SessionSettingsBuilder()
    .hideClosedCaptionButton(false)
    .build();

Default: true

Even with hideClosedCaptionButton(false), the captions item only appears once transcription is running for the session, because captions are generated from the live transcript.

Caption Language

Method: setCaptionLanguage(String) Sets the language used for transcription and captions. This is fixed for the session — there is no in-call language picker on Android.

Kotlin
Java

val sessionSettings = CometChatCalls.SessionSettingsBuilder()
    .setCaptionLanguage("en-US")
    .build()

SessionSettings sessionSettings = new CometChatCalls.SessionSettingsBuilder()
    .setCaptionLanguage("en-US")
    .build();

Default: en-US

Supported Language Codes

Code	Language
`en-US`	English (United States)
`de-DE`	German (Germany)
`en-GB`	English (United Kingdom)
`es-ES`	Spanish (Spain)
`fr-FR`	French (France)
`hi-IN`	Hindi (India)
`hu-HU`	Hungarian (Hungary)
`it-IT`	Italian (Italy)
`ja-JP`	Japanese (Japan)
`ko-KR`	Korean (South Korea)
`lt-LT`	Lithuanian (Lithuania)
`ms-MY`	Malay (Malaysia)
`nl-NL`	Dutch (Netherlands)
`pt-PT`	Portuguese (Portugal)
`ru-RU`	Russian (Russia)
`sv-SE`	Swedish (Sweden)
`tr-TR`	Turkish (Turkey)
`zh`	Chinese Mandarin (Simplified, China)
`zh-TW`	Chinese Mandarin (Traditional, Taiwan)

Retrieving Transcripts

After a call, use TranscriptRequest to list the transcript artifacts for a session. Each record is a pointer to a downloadable transcript file, not the transcript text itself.

The SDK must be initialized with CometChatCalls.init() and a user must be logged in. The auth token is read from the logged-in user at fetch time, so it automatically tracks re-logins.

Building a Request

Kotlin
Java

val transcriptRequest = TranscriptRequest.TranscriptRequestBuilder()
    .setSessionId("v1.us.2547167fe69871fd.alice") // required
    .setLimit(10)                                  // optional
    .build()

transcriptRequest.fetchNext(object : CometChatCalls.CallbackListener<List<Transcript>>() {
    override fun onSuccess(transcripts: List<Transcript>) {
        for (transcript in transcripts) {
            Log.d(TAG, "Transcript ID: ${transcript.tid}")
            Log.d(TAG, "Transcript URL: ${transcript.transcriptUrl}")
        }
    }

    override fun onError(e: CometChatException) {
        Log.e(TAG, "Error: ${e.code} ${e.message}")
    }
})

TranscriptRequest transcriptRequest = new TranscriptRequest.TranscriptRequestBuilder()
    .setSessionId("v1.us.2547167fe69871fd.alice") // required
    .setLimit(10)                                  // optional
    .build();

transcriptRequest.fetchNext(new CometChatCalls.CallbackListener<List<Transcript>>() {
    @Override
    public void onSuccess(List<Transcript> transcripts) {
        for (Transcript transcript : transcripts) {
            Log.d(TAG, "Transcript ID: " + transcript.getTid());
            Log.d(TAG, "Transcript URL: " + transcript.getTranscriptUrl());
        }
    }

    @Override
    public void onError(CometChatException e) {
        Log.e(TAG, "Error: " + e.getCode() + " " + e.getMessage());
    }
});

Method	Required	Description
`setSessionId(String)`	Yes	The session ID whose transcripts to fetch. A null or empty value is reported as `ERROR_INVALID_SESSIONID` on the first fetch.
`setLimit(int)`	No	Page size. Defaults to `30` and is capped at `1000`. A value of `0` or less is reported as `ERROR_NON_POSITIVE_LIMIT` on the first fetch.
`build()`	Yes	Returns a `TranscriptRequest`. Never throws — validation happens at fetch time.

Paginating

A TranscriptRequest is a stateful cursor. Create one per session ID and drive it with fetchNext() and fetchPrevious():

Kotlin
Java

// Fetch next page
transcriptRequest.fetchNext(object : CometChatCalls.CallbackListener<List<Transcript>>() {
    override fun onSuccess(transcripts: List<Transcript>) {
        if (transcripts.isEmpty()) {
            // No more pages
        }
    }

    override fun onError(e: CometChatException) {
        Log.e(TAG, "Error: ${e.message}")
    }
})

// Fetch previous page
transcriptRequest.fetchPrevious(object : CometChatCalls.CallbackListener<List<Transcript>>() {
    override fun onSuccess(transcripts: List<Transcript>) {
        // Handle previous page
    }

    override fun onError(e: CometChatException) {
        Log.e(TAG, "Error: ${e.message}")
    }
})

// Fetch next page
transcriptRequest.fetchNext(new CometChatCalls.CallbackListener<List<Transcript>>() {
    @Override
    public void onSuccess(List<Transcript> transcripts) {
        if (transcripts.isEmpty()) {
            // No more pages
        }
    }

    @Override
    public void onError(CometChatException e) {
        Log.e(TAG, "Error: " + e.getMessage());
    }
});

// Fetch previous page
transcriptRequest.fetchPrevious(new CometChatCalls.CallbackListener<List<Transcript>>() {
    @Override
    public void onSuccess(List<Transcript> transcripts) {
        // Handle previous page
    }

    @Override
    public void onError(CometChatException e) {
        Log.e(TAG, "Error: " + e.getMessage());
    }
});

fetchNext() delivers the next page, or an empty list when there are no more pages. A session with no transcripts delivers an empty list.
fetchPrevious() delivers the previous page, or an empty list when already on the first page. It never requests a page below 1.
Only one fetch may be in flight at a time. Calling fetchNext() or fetchPrevious() while another request is pending reports ERROR_REQUEST_IN_PROGRESS; the original call is unaffected and still completes.
Callbacks are always delivered on the main thread.

Transcript Object

Property	Type	Description
`tid`	String	Transcript ID
`mid`	String	Meeting ID
`roomName`	String	Room name of the meeting
`startTime`	long	Meeting start time, in epoch seconds
`endTime`	long	Meeting end time, in epoch seconds
`url`	String	Meeting URL
`transcriptDate`	String	Transcript date
`transcriptUrl`	String	URL of the downloadable transcript JSON
`metaData`	JSONObject	The full raw record as returned by the server, so any fields not modelled above are still available

Every property is optional. The server omits keys whose value is empty, so String getters may return null and numeric getters 0. Sparse records are normal and should not be treated as an error.

Reading the Transcript Content

transcriptUrl points at the transcript file. Download it with your HTTP client of choice to read the actual utterances:

Kotlin
Java

transcriptRequest.fetchNext(object : CometChatCalls.CallbackListener<List<Transcript>>() {
    override fun onSuccess(transcripts: List<Transcript>) {
        val transcriptUrl = transcripts.firstOrNull()?.transcriptUrl
        if (transcriptUrl != null) {
            // Download the JSON at transcriptUrl using your HTTP client
        }
    }

    override fun onError(e: CometChatException) {
        Log.e(TAG, "Error: ${e.message}")
    }
})

transcriptRequest.fetchNext(new CometChatCalls.CallbackListener<List<Transcript>>() {
    @Override
    public void onSuccess(List<Transcript> transcripts) {
        if (!transcripts.isEmpty() && transcripts.get(0).getTranscriptUrl() != null) {
            String transcriptUrl = transcripts.get(0).getTranscriptUrl();
            // Download the JSON at transcriptUrl using your HTTP client
        }
    }

    @Override
    public void onError(CometChatException e) {
        Log.e(TAG, "Error: " + e.getMessage());
    }
});

Error Handling

All errors — including pre-flight validation — are delivered to onError() with a CometChatException carrying a code. build() never throws.

Condition	Code
`init()` was not called	`ERROR_COMETCHAT_CALLS_SDK_INIT`
No logged-in user (no auth token)	`ERROR_AUTH_TOKEN`
`sessionId` missing or empty	`ERROR_INVALID_SESSIONID`
`limit` is `0` or negative	`ERROR_NON_POSITIVE_LIMIT`
A fetch is already in flight	`ERROR_REQUEST_IN_PROGRESS`
Missing or malformed response	`ERROR_JSON_EXCEPTION`
Network failure or server-side API error	The network or server’s own code (e.g. `AUTH_ERR_EMPTY_APPID`)

Complete Example

Kotlin
Java

// 1. Join a session with transcription enabled
val sessionSettings = CometChatCalls.SessionSettingsBuilder()
    .setType(SessionType.VIDEO)
    .enableAutoStartTranscription(true)
    .hideTranscriptionButton(false)
    .hideClosedCaptionButton(false)
    .setCaptionLanguage("en-US")
    .build()

CometChatCalls.joinSession(callToken, sessionSettings, callViewContainer,
    object : CometChatCalls.CallbackListener<CallSession>() {
    override fun onSuccess(callSession: CallSession) {
        // 2. Control transcription during the call
        callSession.startTranscription()
        callSession.stopTranscription()
    }

    override fun onError(e: CometChatException) {
        Log.e(TAG, "Error: ${e.message}")
    }
})

// 3. Retrieve transcripts after the call
val transcriptRequest = TranscriptRequest.TranscriptRequestBuilder()
    .setSessionId(sessionId)
    .setLimit(10)
    .build()

transcriptRequest.fetchNext(object : CometChatCalls.CallbackListener<List<Transcript>>() {
    override fun onSuccess(transcripts: List<Transcript>) {
        transcripts.forEach { Log.d(TAG, "Transcript URL: ${it.transcriptUrl}") }
    }

    override fun onError(e: CometChatException) {
        Log.e(TAG, "Error: ${e.message}")
    }
})

// 1. Join a session with transcription enabled
SessionSettings sessionSettings = new CometChatCalls.SessionSettingsBuilder()
    .setType(SessionType.VIDEO)
    .enableAutoStartTranscription(true)
    .hideTranscriptionButton(false)
    .hideClosedCaptionButton(false)
    .setCaptionLanguage("en-US")
    .build();

CometChatCalls.joinSession(callToken, sessionSettings, callViewContainer,
    new CometChatCalls.CallbackListener<CallSession>() {
    @Override
    public void onSuccess(CallSession callSession) {
        // 2. Control transcription during the call
        callSession.startTranscription();
        callSession.stopTranscription();
    }

    @Override
    public void onError(CometChatException e) {
        Log.e(TAG, "Error: " + e.getMessage());
    }
});

// 3. Retrieve transcripts after the call
TranscriptRequest transcriptRequest = new TranscriptRequest.TranscriptRequestBuilder()
    .setSessionId(sessionId)
    .setLimit(10)
    .build();

transcriptRequest.fetchNext(new CometChatCalls.CallbackListener<List<Transcript>>() {
    @Override
    public void onSuccess(List<Transcript> transcripts) {
        for (Transcript transcript : transcripts) {
            Log.d(TAG, "Transcript URL: " + transcript.getTranscriptUrl());
        }
    }

    @Override
    public void onError(CometChatException e) {
        Log.e(TAG, "Error: " + e.getMessage());
    }
});

Overview

Getting Started

Call Session

Features

Advanced

Migration Guide

Resources

Transcription & Closed Captions

How It Works

Starting Transcription

Auto-Start Transcription

Manual Transcription Control

Start Transcription

Stop Transcription

Built-in UI Controls

Transcription Button

Closed Caption Button

Caption Language

Retrieving Transcripts

Building a Request

Paginating

Transcript Object

Reading the Transcript Content

Error Handling

Complete Example

​How It Works

​Starting Transcription

​Auto-Start Transcription

​Manual Transcription Control

​Start Transcription

​Stop Transcription

​Built-in UI Controls

​Transcription Button

​Closed Caption Button

​Caption Language

​Retrieving Transcripts

​Building a Request

​Paginating

​Transcript Object

​Reading the Transcript Content

​Error Handling

​Complete Example

​Related Documentation

How It Works

Starting Transcription

Auto-Start Transcription

Manual Transcription Control

Start Transcription

Stop Transcription

Built-in UI Controls

Transcription Button

Closed Caption Button

Caption Language

Retrieving Transcripts

Building a Request

Paginating

Transcript Object

Reading the Transcript Content

Error Handling

Complete Example

Related Documentation