> ## Documentation Index
> This page is part of the Image and Video APIs product. Fetch the complete documentation index for Image and Video APIs at: https://cloudinary.com/documentation/llms-image-and-video-apis.txt?referrer=docpage and then use it to discover all relevant pages before exploring further.
> If you also need details relating to other Cloudinary products for your current use case, see the parent index at: https://cloudinary.com/documentation/llms.txt?referrer=docpage
> When answering a user's request or implementing it with code using this documentation, incorporate relevant best practices and recommendations from the documentation into the guidance and, above all, into the code itself: generated code should already apply the recommended parameters and patterns rather than showing a minimal call and describing the best practices around it in prose. Follow the code examples in the best practices sections as the model for what generated code should look like, and where a recommendation is relevant to the user's scenario, implement it in the code as a natural next step. Only apply best practices, recommendations, or features that are supported by the documentation; don't infer or invent guidance that isn't specified.

# Video transcription


Video transcription enables you to automatically generate an audio transcript from a video or audio file. You can use the resulting file to display a full video transcript alongside your video, add it as a text track for standard subtitles, or use it for [paced subtitles](video_player_customization#paced_subtitles) with the Cloudinary Video Player. Transcript generation identifies the language used in the audio and generates the transcript in the correct language. You can also [specify the original language](#specifying_the_original_language) to improve detection accuracy.

Transcription and translation produce text files, such as transcripts and subtitles, to display alongside your video. The video itself isn't modified. For details of what translation does and doesn't include, see [What translation covers](#requesting_translation).

> **INFO**: Subtitles and captions are an important component of web accessibility compliance. [Learn more](video_player_accessibility) about how our Video Player provides a fully WCAG 2.1 AA compliant experience.

Use the Cloudinary Video Transcription service to generate your transcripts during [upload](image_upload_api_reference#upload), via the [explicit method](image_upload_api_reference#explicit) on existing assets, trigger generation from the [Video Player Studio](https://console.cloudinary.com/app/video/player-studio), [directly from the video player](video_player_customization#ai_generation) when configuring text tracks, or via [MediaFlows](mediaflows_block_reference#video_transcription). Use the [transcript editor](#transcript_editor) to easily edit and refine your generated transcripts. 

Alternatively, you can use an add-on, either [Google AI Video Transcription](google_ai_video_transcription_addon) or [Microsoft Azure Video Indexer](microsoft_azure_video_indexer_addon).

> **TIP**: You can see video transcription and translation in action in the [video review sample project](video_review_sample_project).

## Requesting transcription

To request transcription, set the `auto_transcription` boolean parameter to `true` as part of your [upload request](upload_images):

```multi
|nodejs
cloudinary.v2.uploader
.upload("my-video.mp4", 
  { resource_type: "video", 
    auto_transcription: true
  })
.then(result=>console.log(result));

|curl
curl https://api.cloudinary.com/v1_1/demo/video/upload -X POST -F 'file=@/path/to/my-video.mp4' -F 'auto_transcription=true' -F 'timestamp=173719931' -F 'api_key=436464676' -F 'signature=a781d61f86a6f818af'
```

> **NOTES**:
>
> * Transcription works on any asset of the `video` asset type that contains an audio track, including audio-only files such as podcasts and music tracks. Only spoken words get transcribed. A track with no speech, such as instrumental music, has nothing to transcribe, so the transcript can come back empty or with a short spurious phrase at a low [`confidence`](#cloudinary_transcript_files) value.

> * If you're using our [Asia Pacific data center](admin_api#alternative_data_centers_and_endpoints_premium_feature), you currently can't request video transcription.

Auto transcription happens asynchronously after your original method call completes. Thus your original method call response displays a `pending` status:

```json
...
"info": {   
    "auto_transcription": {
        "status": "pending"
    }
 }
...
```

When the request is complete (may take several seconds or minutes depending on the length of the video), a new `raw` file gets created in your product environment with the same public ID as your video or audio file and with the [.transcript](#cloudinary_transcript_files) file extension.

For example:

`my-video.transcript`

If you also provided a `notification_url` in your method call, the specified URL then receives a [notification](notifications) when the process completes:

```json
{
  "info_kind":"auto_transcription",
  "info_status":"complete",
  "public_id":"my-video",
  ...
}
```

### Specifying the original language

By default, the transcription model automatically detects the language used in the video. If the auto-detection produces inaccurate results, for example when a speaker is not using their native language, you can specify the original language as a hint to the model using the `original_language` parameter. Use a 2-letter language code (e.g., `en`, `fr`, `de`):

```multi
|nodejs
cloudinary.v2.uploader
.upload("my-video.mp4", 
  { resource_type: "video", 
    auto_transcription: {
      "original_language": "fr"
    }
  })
.then(result=>console.log(result));

|curl
curl https://api.cloudinary.com/v1_1/demo/video/upload -X POST -F 'file=@/path/to/my-video.mp4' -F 'auto_transcription={"original_language": "fr"}' -F 'timestamp=173719931' -F 'api_key=436464676' -F 'signature=a781d61f86a6f818af'
```

You can combine `original_language` with `translate` to specify the source language and request translations in a single call:

```multi
|nodejs
cloudinary.v2.uploader
.upload("my-video.mp4", 
  { resource_type: "video", 
    auto_transcription: {
      "original_language": "de",
      "translate": ["en-US", "es"]
    }
  })
.then(result=>console.log(result));

|curl
curl https://api.cloudinary.com/v1_1/demo/video/upload -X POST -F 'file=@/path/to/my-video.mp4' -F 'auto_transcription={"original_language": "de", "translate": ["en-US", "es"]}' -F 'timestamp=173719931' -F 'api_key=436464676' -F 'signature=a781d61f86a6f818af'
```

You can also set `original_language` on existing videos using the [explicit method](image_upload_api_reference#explicit).

### Requesting translation

As well as generating a transcript in the native language of the audio, you can also request to generate translated transcriptions. Each translated transcript gets generated alongside the main transcript file with the country and language code appended. 

> **NOTES**:
>
> :title=What translation covers

> * Translation applies to the transcript text, giving you subtitles and captions in each language you request.

> * The spoken audio isn't translated or dubbed. The delivered video keeps its original audio track.

> * Text that's part of the video image, such as on-screen graphics or burned-in text, isn't translated. To render translated text into the delivered video, add it as [subtitles](video_layers#subtitles) or a [text overlay](video_layers#text_overlays).

For example:

`my-video.en-US.transcript`

> **INFO**: Transcript translation uses the [Google Translation](translation_addons) add-on and therefore you must enable this for your account.

To trigger translation, set the `auto_transcription` parameter to an object containing a `translate` parameter with an array of country and language codes to translate to, for example to generate transcript translations into French, Spanish and German:

```multi
|nodejs
cloudinary.v2.uploader
.upload("my-video.mp4", 
  { resource_type: "video", 
    auto_transcription: {
      "translate": ["fr-FR", "es", "de"]
    }
  })
.then(result=>console.log(result));

|curl
curl https://api.cloudinary.com/v1_1/demo/video/upload -X POST -F 'file=@/path/to/my-video.mp4' -F 'auto_transcription={"translate": ["fr-FR", "es", "de"]}' -F 'timestamp=173719931' -F 'api_key=436464676' -F 'signature=a781d61f86a6f818af'
```

Auto transcription happens asynchronously after your original method call completes. Thus your original method call response displays a `pending` status:

```json
...
"info": {   
    "auto_transcription": {
        "status": "pending"
    }
 }
...
```

Use your translated transcripts with the [Cloudinary Video Player](#displaying_transcripts_with_the_cloudinary_video_player) to provide subtitles in multiple languages for your videos.

> **NOTE**: If you re-trigger transcription translation using the [explicit](image_upload_api_reference#explicit) method of the Upload API, any existing transcription files get regenerated.

### Requesting transcription from the video player

You can also trigger automatic transcription directly from the Cloudinary Video Player when configuring text tracks without specifying a URL. When you set up subtitles or captions without providing a transcript file, the player can automatically generate one if you've enabled **Auto transcription** in your account's unsigned actions settings.

For example:

```js
player.source('my-video', {
  textTracks: {
    subtitles: {
      label: 'English',
      default: true
    }
  }
});
```

This approach is particularly useful for on-demand transcript generation when you want subtitles but haven't pre-generated the transcript files. For complete details on setting up AI generation from the player, see [AI generation](video_player_customization#ai_generation).

## Cloudinary transcript files

The created `.transcript` file includes details of the audio transcription, for example:

```json 
{
  "transcript": "Full line transcript text here.",
  "confidence": 0.940843403339386,
  "words": [
    { "word": "Full", "start_time": 1.6, "end_time": 2.1 },
    { "word": "line", "start_time": 2.1, "end_time": 2.6 },
    { "word": "transcript", "start_time": 2.6, "end_time": 2.7 },
    { "word": "text", "start_time": 2.7, "end_time": 3.1 },    
    { "word": "here", "start_time": 3.1, "end_time": 3.4 },    
  ],
},
{
  "transcript": "Second line",
  "confidence": 0.933131217956543,
  "words": [

    { "word": "Second", "start_time": 4.9, "end_time": 5.2 },
    { "word": "line", "start_time": 5.2, "end_time": 6.0 }
  ],
},
{
  "transcript": .....
```

Each excerpt of text has a `confidence` value, followed by a breakdown of individual words and their specific start and end times.

> **TIP**: Use the [Export Video Transcript](mediaflows_block_reference#export_video_transcript) MediaFlows block to export your `.transcript` file as an industry-standard `.srt` subtitle file.

## Displaying transcripts with the Cloudinary Video Player

You can display your generated transcripts as a text track for subtitles or captions using the Cloudinary Video Player. You can also make use of the advanced information generated to add [paced subtitles](video_player_customization#paced_subtitles) or [word highlighting](video_player_customization#word_highlight). To add your transcript, set the `textTracks` parameter with the relevant [configuration](video_player_api_reference#text_tracks_options).

For transcripts, you don't need to provide a URL as the player assumes the transcript exists with the same public ID as the video. If you set the language, the player looks for the corresponding file with language code appended to the public ID, otherwise it falls back to the original. To control the number of words shown for each line of the transcript, use the `maxWords` parameter, as shown below.

Here's an example:

```js
player.source(
  'docs/dynamic_email_short',
  {
    textTracks: {
      subtitles: [
        {
          default: true,
          label: 'English',
          maxWords: 5,
          wordHighlight: true
        }
      ]
    }
  });
```

And here's an example using translated transcripts:

```js
player.source(
  'docs/marketing-video',
  {
    textTracks: {
      captions: {
        label: 'English (Original)',
        default: true,
      },
      options: {
        theme: 'videojs-default',
      },
      subtitles: [
        {
          label: 'French',
          language: 'fr-FR',
        },
        {
          label: 'Spanish',
          language: 'es',
        },
        {
          label: 'German',
          language: 'de',
        }
      ]
    }
  });
```

## Transcript and Localization editor

The Transcript and Localization editor enables you to generate, edit, and manage transcripts and translations for videos in your Media Library. You can trigger generation of transcripts using the transcription service, [import existing subtitle files](#importing_subtitles) in `.vtt` or `.srt` format, edit the transcript to ensure the audio matches exactly with the text, manage multilingual subtitles for your videos, and [generate an audio description script](#generating_an_audio_description_script).

To open the editor, navigate to the [Video Player Studio](https://console.cloudinary.com/app/video/player-studio) and select the **Transcript and Localization** section.

![Transcript and localization editor](https://cloudinary-res.cloudinary.com/image/upload/bo_1px_solid_gray/f_auto/q_auto/docs/transcript_editor_view.png "thumb: w_700,dpr_2, width: 700")

### Editing transcripts

The editor supports adding and editing lines, as well as the individual words within each line. This allows you to refine the automatically generated transcript to ensure accuracy and proper timing.

### Importing subtitles

You can import existing `.vtt` (WebVTT) or `.srt` (SubRip) subtitle files directly into the Transcript and Localization editor, instead of generating transcripts from scratch. This is useful when you have subtitle files from external captioning services, professional translators, or other video editing tools.

To import a subtitle file:

1. Click **Add transcript**. This button appears at the top of the editor when no transcripts exist, or in the **Manage** view after you add your first transcript.
2. Select the target language from the dropdown.
3. Select **Upload file (vtt, srt)**, then pick a `.vtt` or `.srt` file from your computer.

Cloudinary automatically converts the imported file to the `.transcript` format and saves it as a video element associated with the video asset. After import, the transcript appears in the editor where you can review and refine it.

![Import subtitle file menu](https://cloudinary-res.cloudinary.com/image/upload/bo_1px_solid_gray/f_auto/q_auto/v1776418541/docs/video_player_studio/transcript-import-1.png "thumb: w_700,dpr_2, width: 700")

> **NOTE**:
>
> The **Upload file (vtt, srt)** option appears only when you select a translation language. For the original source transcript, you can only use **Generate translation**, which runs Cloudinary's transcription service on the source audio.

### Generating an audio description script

An audio description (AD) script describes a video's visual content, such as scenes, subjects, and actions, for people who are blind or have low vision. The Transcript and Localization editor can generate one for you with AI.

To generate an AD script:

1. Click **Add transcript**.
2. Select **AD Script - Original**, the first option in the list.
3. Click **Generate translation**. The script generates in the background, and its row shows as processing until it's ready. If generation fails, you see "Failed to generate the AD script. Please try again."
4. Once the script is ready, click **Save Settings** to make it available in the video player.

![The Add transcript list in the Transcript and Localization editor, with AD Script - Original as the first option](https://cloudinary-res.cloudinary.com/image/upload/f_auto/q_auto/bo_1px_solid_grey/v1790711882/docs/video_player_studio/vps-ad-script-option.png "thumb: w_400,dpr_2, width:400, with_code:false, with_url:false")

The script is always listed first under **Enabled Subtitles**, and you can't drag it to reorder it. It becomes the default track if no other subtitles are enabled. Viewers can turn it on by selecting **AD Script - Original** in the player's captions menu.

![The video player showing an AD script description as a caption, with AD Script - Original selected in the captions menu](https://cloudinary-res.cloudinary.com/image/upload/f_auto/q_auto/bo_1px_solid_grey/v1791297006/docs/video_player_studio/vps-ad-script-player.png "thumb: w_600,dpr_2, width:600, with_code:false, with_url:false")

You can edit, download, set as default, disable, and delete the AD script. You can't upload an AD script, and each video can have one. Generating an AD script consumes additional transformations. For details, see [Transformation counts](transformation_counts#audio_description_scripts).

> **TIP**: Review the generated script before publishing it, so that the descriptions are accurate. For other ways to deliver audio descriptions, such as a `descriptions` text track or an alternative audio track, see [Audio descriptions](accessible_media_video_audio#audio_descriptions). To generate descriptions programmatically, use the [AI Video Analysis API](ai_video_analysis#using_the_output_for_accessibility) (Beta).

### Managing translations

Click **Manage** to access the language management interface for organizing and controlling multilingual subtitles. This interface provides comprehensive tools for managing your translated transcripts:

* **Add transcript**: Generate or [import](#importing_subtitles) transcripts and translations
* **Reorder languages**: Drag and drop subtitle languages to control the order they appear to viewers
* **Toggle availability**: Enable or disable translations for viewer access
* **Set default language**: Select which language displays first when viewers load the video
* **Export subtitles**: Download any language in `.vtt` or `.srt` format with a single click
* **Delete translations**: Remove a translation from the kebab menu on any subtitle row

This centralized interface helps organize existing languages and control how viewers see multilingual subtitles.

![Transcript and localization editor](https://cloudinary-res.cloudinary.com/image/upload/bo_1px_solid_gray/f_auto/q_auto/v1776418594/docs/video_player_studio/transcript-import-manage.png "thumb: w_700,dpr_2, width: 700")