> ## Documentation Index
> Fetch the complete documentation index at: https://cometchat-22654f5b-docs-agent-native-development.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Transcription & Closed Captions

> Use CometChat Calls SDK v5 transcription on Android to transcribe calls, show live closed captions, and retrieve transcripts after the call.

<Note>
  **Available since v5.0.4** — transcription and closed captions require CometChat Calls SDK v5.0.4 or later for Android. See [Setup](/calls/android/setup) to install or upgrade.
</Note>

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`.

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

## 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:

<Tabs>
  <Tab title="Kotlin">
    ```kotlin theme={null}
    val sessionSettings = CometChatCalls.SessionSettingsBuilder()
        .enableAutoStartTranscription(true)
        // ... other settings
        .build()
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    SessionSettings sessionSettings = new CometChatCalls.SessionSettingsBuilder()
        .enableAutoStartTranscription(true)
        // ... other settings
        .build();
    ```
  </Tab>
</Tabs>

**Default:** `false`

### Manual Transcription Control

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

#### Start Transcription

<Tabs>
  <Tab title="Kotlin">
    ```kotlin theme={null}
    val callSession = CallSession.getInstance()
    callSession.startTranscription()
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    CallSession callSession = CallSession.getInstance();
    callSession.startTranscription();
    ```
  </Tab>
</Tabs>

#### Stop Transcription

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

<Tabs>
  <Tab title="Kotlin">
    ```kotlin theme={null}
    val callSession = CallSession.getInstance()
    callSession.stopTranscription()
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    CallSession callSession = CallSession.getInstance();
    callSession.stopTranscription();
    ```
  </Tab>
</Tabs>

<Note>
  Always check `isSessionActive()` before calling these actions to ensure there's an active call.
</Note>

## 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:

<Tabs>
  <Tab title="Kotlin">
    ```kotlin theme={null}
    val sessionSettings = CometChatCalls.SessionSettingsBuilder()
        .hideTranscriptionButton(false)
        .build()
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    SessionSettings sessionSettings = new CometChatCalls.SessionSettingsBuilder()
        .hideTranscriptionButton(false)
        .build();
    ```
  </Tab>
</Tabs>

**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:

<Tabs>
  <Tab title="Kotlin">
    ```kotlin theme={null}
    val sessionSettings = CometChatCalls.SessionSettingsBuilder()
        .hideClosedCaptionButton(false)
        .build()
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    SessionSettings sessionSettings = new CometChatCalls.SessionSettingsBuilder()
        .hideClosedCaptionButton(false)
        .build();
    ```
  </Tab>
</Tabs>

**Default:** `true`

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

## 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.

<Tabs>
  <Tab title="Kotlin">
    ```kotlin theme={null}
    val sessionSettings = CometChatCalls.SessionSettingsBuilder()
        .setCaptionLanguage("en-US")
        .build()
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    SessionSettings sessionSettings = new CometChatCalls.SessionSettingsBuilder()
        .setCaptionLanguage("en-US")
        .build();
    ```
  </Tab>
</Tabs>

**Default:** `en-US`

<Accordion title="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) |
</Accordion>

## 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.

<Note>
  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.
</Note>

### Building a Request

<Tabs>
  <Tab title="Kotlin">
    ```kotlin theme={null}
    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}")
        }
    })
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    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());
        }
    });
    ```
  </Tab>
</Tabs>

| 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()`:

<Tabs>
  <Tab title="Kotlin">
    ```kotlin theme={null}
    // 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}")
        }
    })
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    // 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());
        }
    });
    ```
  </Tab>
</Tabs>

* `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 |

<Note>
  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.
</Note>

### Reading the Transcript Content

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

<Tabs>
  <Tab title="Kotlin">
    ```kotlin theme={null}
    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}")
        }
    })
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    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());
        }
    });
    ```
  </Tab>
</Tabs>

### 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

<Tabs>
  <Tab title="Kotlin">
    ```kotlin theme={null}
    // 1. Join a session with transcription enabled
    val sessionSettings = CometChatCalls.SessionSettingsBuilder()
        .setSessionType(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}")
        }
    })
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    // 1. Join a session with transcription enabled
    SessionSettings sessionSettings = new CometChatCalls.SessionSettingsBuilder()
        .setSessionType(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());
        }
    });
    ```
  </Tab>
</Tabs>

## Related Documentation

* [Session Settings](/calls/android/session-settings)
* [Actions](/calls/android/actions)
* [Call Logs](/calls/android/call-logs)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.