> ## Documentation Index
> Fetch the complete documentation index at: https://cometchat-22654f5b-docs-llms-scoped-indexes.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 JavaScript to transcribe calls, show live closed captions, and retrieve transcripts after the call.

<Note>
  **Available since v5.0.5** — transcription and closed captions require CometChat Calls SDK v5.0.5 or later for JavaScript. See [Setup](/calls/javascript/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 `TranscriptRequestBuilder`.

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

```javascript theme={null}
const callSettings = {
  autoStartTranscription: true,
  // ... other settings
};

await CometChatCalls.joinSession(callToken, callSettings, container);
```

**Default:** `false`

### Manual Transcription Control

#### Start Transcription

Begin transcribing during an active call:

```javascript theme={null}
CometChatCalls.startTranscription();
```

#### Stop Transcription

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

```javascript theme={null}
CometChatCalls.stopTranscription();
```

## Built-in UI Controls

### Transcription Button

By default, the transcription button in the control panel's **More** menu is hidden. To show it:

```javascript theme={null}
const callSettings = {
  hideTranscriptionButton: false,
  // ... other settings
};
```

**Default:** `true`

The menu item toggles between **Start Transcription** and **Stop Transcription** based on the current state.

### Closed Caption Button

By default, the closed-caption (CC) button in the control panel is hidden. To show it:

```javascript theme={null}
const callSettings = {
  hideClosedCaptionButton: false,
  // ... other settings
};
```

**Default:** `true`

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

### Closed Caption Settings

When the CC button is visible, the settings dialog gains a **Closed Caption** tab where the user can pick the caption language and enable or disable the on-screen captions. The gear icon on the captions overlay opens the dialog directly on that tab.

## Caption Language

**Property:** `captionLanguage`

Sets the language used for transcription and captions.

```javascript theme={null}
const callSettings = {
  captionLanguage: "en-US",
  // ... other settings
};
```

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

```javascript theme={null}
const request = new CometChatCalls.TranscriptRequestBuilder()
  .setSessionId("v1.us.2547167fe69871fd.alice") // required
  .setLimit(10)                                  // optional
  .build();

const transcripts = await request.fetchNext();
```

| Method | Required | Description |
| - | - | - |
| `setSessionId(sessionId: string)` | Yes | The session ID whose transcripts to fetch. An empty value throws `SESSION_ID_REQUIRED` at `build()`. |
| `setLimit(limit: number)` | No | Page size. Defaults to `30` and is clamped to the range `1`–`1000`. |
| `build()` | Yes | Returns a `TranscriptRequest`. Throws synchronously for pre-flight errors. |

### Paginating

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

```javascript theme={null}
const request = new CometChatCalls.TranscriptRequestBuilder()
  .setSessionId(sessionId)
  .setLimit(10)
  .build();

let page = await request.fetchNext(); // page 1

while (page.length > 0) {
  page.forEach((transcript) => console.log(transcript.transcriptUrl));
  page = await request.fetchNext();   // page 2, 3, ... then [] at the end
}
```

* `fetchNext()` resolves the next page, or `[]` when there are no more pages. A session with no transcripts resolves `[]`.
* `fetchPrevious()` resolves the previous page, or `[]` 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 rejects with `REQUEST_IN_PROGRESS`; the original call is unaffected and still completes.

### Transcript Properties

| Property | Type | Description |
| - | - | - |
| `tid` | String | Transcript ID |
| `mid` | String | Meeting ID |
| `roomName` | String | Room name of the meeting |
| `startTime` | Number | Meeting start time, in epoch **seconds** |
| `endTime` | Number | Meeting end time, in epoch **seconds** |
| `url` | String | Meeting URL |
| `transcriptDate` | String | Transcript date |
| `transcriptUrl` | String | URL of the downloadable transcript JSON |
| `metaData` | Object | Arbitrary metadata |

<Note>
  Every property is optional. The server omits keys whose value is empty, so sparse records are normal and should not be treated as an error.
</Note>

### Reading the Transcript Content

`transcriptUrl` points at the transcript file. Fetch it yourself to read the actual utterances:

```javascript theme={null}
const [transcript] = await request.fetchNext();

if (transcript?.transcriptUrl) {
  const response = await fetch(transcript.transcriptUrl);
  const content = await response.json();
  console.log(content);
}
```

### Error Handling

`build()` throws synchronously; `fetchNext()` and `fetchPrevious()` reject. Both surface a `CometChatCallsException` carrying a `code`:

| Condition | Code | Raised by |
| - | - | - |
| `init()` was not called | `NOT_INITIALIZED` | `build()` |
| `sessionId` missing or empty | `SESSION_ID_REQUIRED` | `build()` |
| No logged-in user | `NOT_LOGGED_IN` | `fetchNext()` / `fetchPrevious()` |
| A fetch is already in flight | `REQUEST_IN_PROGRESS` | `fetchNext()` / `fetchPrevious()` |
| Network failure | `NETWORK_ERROR` | `fetchNext()` / `fetchPrevious()` |
| Missing or malformed response | `BAD_RESPONSE` | `fetchNext()` / `fetchPrevious()` |
| Server-side API error | The server's own code (e.g. `AUTH_ERR_EMPTY_APPID`) | `fetchNext()` / `fetchPrevious()` |

```javascript theme={null}
try {
  const transcripts = await request.fetchNext();
} catch (error) {
  console.error(error.code, error.message);
}
```

## Transcripts in Call Logs

Call logs can be filtered to transcribed calls, which also attaches each call's transcripts to the log:

```javascript theme={null}
const callLogRequest = new CometChatCalls.CallLogRequestBuilder()
  .setLimit(30)
  .setHasTranscriptions(true)
  .build();

const callLogs = await callLogRequest.fetchNext();

callLogs.forEach((callLog) => {
  callLog.getTranscriptions().forEach((transcription) => {
    console.log(transcription.getTid(), transcription.getTranscriptURL());
  });
});
```

`getTranscriptions()` returns an empty array when the server omitted transcripts, so it never needs a null check.

<Accordion title="Transcription Methods">
  | Method | Returns | Description |
  | - | - | - |
  | `getTid()` | String | The transcript ID |
  | `getMid()` | String | The meeting ID |
  | `getRoomName()` | String | The room name of the meeting |
  | `getStartTime()` | Number | Meeting start time, in epoch seconds |
  | `getEndTime()` | Number | Meeting end time, in epoch seconds |
  | `getTranscriptDate()` | String | The transcript date |
  | `getTranscriptURL()` | String | URL of the downloadable transcript JSON |
</Accordion>

## Complete Example

```javascript theme={null}
// 1. Join a session with transcription enabled
const callSettings = {
  sessionType: "VIDEO",
  autoStartTranscription: true,
  hideTranscriptionButton: false,
  hideClosedCaptionButton: false,
  captionLanguage: "en-US",
};

await CometChatCalls.joinSession(callToken, callSettings, container);

// 2. Control transcription during the call
CometChatCalls.startTranscription();
CometChatCalls.stopTranscription();

// 3. Retrieve transcripts after the call
const request = new CometChatCalls.TranscriptRequestBuilder()
  .setSessionId(sessionId)
  .setLimit(10)
  .build();

const transcripts = await request.fetchNext();
```

## Related Documentation

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


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