> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://fastpix.com/docs/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://fastpix.com/docs/_mcp/server. # Add subtitles to a video Videos without subtitles exclude deaf and hard-of-hearing viewers, lose engagement in sound-off environments, and miss SEO value from indexable text. FastPix lets you attach WebVTT or SRT subtitle tracks to any media asset through the Tracks API, covering accessibility, multi-language reach, and discoverability in one integration. Add tracks at creation time or after upload, each is tied to a `mediaId` and returns a `trackId` you can update or delete. The API accepts BCP 47 language codes so tracks display correctly across HLS-compatible players. \ ## Prerequisites * A FastPix account with an active workspace ([Activate your account](/getting-started/activate-your-account)) * Your **Access Token ID** and **Secret Key** from the FastPix dashboard * An existing `mediaId` (see [Upload videos from URL](/upload-videos/upload-videos-from-a-url)) or a new media creation request * A publicly accessible `.vtt` or `.srt` subtitle file URL \ ## Captions vs subtitles Subtitles translate spoken dialogue for viewers who understand the audio but need another language. Closed captions also transcribe non-dialogue audio (sound effects, speaker labels) for viewers who cannot hear the audio, which matters for WCAG 2.1 accessibility compliance. FastPix handles both through the same `type: "subtitle"` track object, the distinction lives in the content of your `.vtt` or `.srt` file. \ ## Language code support The Tracks API accepts language codes that follow the BCP 47 standard. Specify the tag in `languageCode` (for example, `en`, `fr`, `pt-BR`) when adding or updating a track. These tags keep language and locale information consistent across systems and players. See the [BCP 47 specification](https://en.wikipedia.org/wiki/IETF_language_tag#List_of_common_primary_language_subtags) for valid tags. \ ## Add a subtitle track to existing media The [add media track endpoint](/video-on-demand-api/manage-videos/add-media-track) attaches a new subtitle track to an existing asset. Supply the language, the subtitle file URL, and the format. FastPix supports both WebVTT and SRT. **Request body**: ```json { "tracks": { "url": "https://static.fastpix.com/subtitle_Spanish.srt", "type": "subtitle", "languageCode": "es", "languageName": "Spanish" } } ``` > **NOTES** > > * FastPix supports **WebVTT (.vtt)** and **SRT (.srt)** formats. > * The `url` must be a publicly accessible **.vtt** or **.srt** file. > * Ensure the `languageCode` is a valid **BCP 47** tag. **Response example**: **`Response`** ```json Response { "id": "606bea3a-21af-4ca2-89a4-b05eb1f410f0", "type": "subtitle", "url": "https://static.fastpix.com/subtitle_Spanish.srt", "languageCode": "es", "languageName": "Spanish" } ``` The returned `id` is the `trackId`. Store it if you plan to update or delete the track later. To add subtitles at creation time, see [Add subtitles when creating new media](#add-subtitles-when-creating-new-media). \ > **TIP:** You can also add a subtitle track from the dashboard, with no code. See [Add tracks to a video from the dashboard](/video-on-demand/add-tracks-from-the-dashboard). \ ## Delete a subtitle track from existing media The [delete media track endpoint](/video-on-demand-api/manage-videos/delete-media-track) removes a subtitle track from an uploaded asset. Pass the `mediaId` and the `trackId` you received when the track was created. **Response example**: **`Response`** ```json Response { "success": true } ``` > **NOTES** > > * Deleting a subtitle track is permanent and cannot be undone. > * Confirm the `trackId` matches the subtitle you want to remove. \ ## Update a subtitle track on existing media The [update media track endpoint](/video-on-demand-api/manage-videos/update-media-track) replaces an existing subtitle file or changes the language metadata on a track. **Request body**: **`Request`** ```json Request { "url": "https://static.fastpix.com/subtitle_Russian.srt", "languageCode": "ru", "languageName": "Russian" } ``` > **NOTE** > > * Only **.vtt** and **.srt** formats are supported. > * Use the correct `trackId` for the subtitle you want to update. > * The `languageCode` must follow **BCP 47**. **Response example**: **`Response`** ```json Response { "success": true, "data": { "id": "5785924d-8d95-4ef9-b801-51b772fe7e8a", "type": "subtitle", "url": "https://static.fastpix.com/subtitle_Russian.srt", "languageCode": "ru", "languageName": "Russian" } } ``` \ ## Add subtitles when creating new media FastPix accepts subtitle tracks inline on media creation requests, so you do not need a follow-up API call. Include one or more subtitle objects in the `inputs` array for [Create Media by Direct Upload](/video-on-demand-api/upload-and-import-videos/direct-upload-video-media) or [Create Media by URL](/video-on-demand-api/upload-and-import-videos/create-media). **Key parameters**: * `type` - set to `subtitle` for subtitle tracks. * `url` - direct link to the subtitle file (must be `.vtt` or `.srt`). * `languageCode` - BCP 47 language tag (for example, `en`, `fr`). * `languageName` - full language name used for display. * `accessPolicy` - controls asset visibility (`public` or `private`). ### Attach subtitles on a direct upload **`Request Body`** ```json Request Body { "corsOrigin": "*", "pushMediaSettings": { "accessPolicy": "public", "inputs": [ { "type": "subtitle", "url": "https://static.fastpix.com/subtitle_Spanish.srt", "languageCode": "es", "languageName": "Spanish" }, { "type": "subtitle", "url": "https://static.fastpix.com/subtitle_Russian.srt", "languageCode": "ru", "languageName": "Russian" }, { "type": "subtitle", "url": "https://static.fastpix.com/subtitle_Portuguese.srt", "languageCode": "pt", "languageName": "Portuguese" } ], "metadata": { "key1": "value1" }, "maxResolution": "1080p" } } ``` ### Attach subtitles on a URL upload **`Request Body`** ```json Request Body { "inputs": [ { "type": "video", "url": "https://static.fastpix.com/fp-sample-video.mp4" }, { "type": "subtitle", "url": "https://static.fastpix.com/subtitle_Spanish.srt", "languageCode": "es", "languageName": "Spanish" }, { "type": "subtitle", "url": "https://static.fastpix.com/subtitle_Russian.srt", "languageCode": "ru", "languageName": "Russian" }, { "type": "subtitle", "url": "https://static.fastpix.com/subtitle_Portuguese.srt", "languageCode": "pt", "languageName": "Portuguese" } ], "metadata": { "key1": "value1" }, "accessPolicy": "public", "maxResolution": "1080p" } ``` \ ## Generate subtitles automatically If you do not have subtitle files on hand, FastPix can generate machine-generated captions from the audio track during media creation. See the [auto-generated subtitles guide](/video-on-demand/generate-subtitles-automatically) to enable this option. \ #### Frequently asked questions Both carry timed text, but WebVTT (`.vtt`) is the modern web standard, it supports styling, positioning, and metadata cues, and it is required by HTML5 `` elements. SRT (`.srt`) is older and simpler, with no styling. FastPix accepts both, so pick WebVTT for browser playback and SRT if that is what your source pipeline already produces. Transcribe the audio, then write each caption as a numbered block: index, timestamp range in `HH:MM:SS,mmm --> HH:MM:SS,mmm` form, and the caption text, separated by blank lines. Tools like Aegisub or any text editor work. For automatic generation, use FastPix's [auto-generated subtitles](/video-on-demand/generate-subtitles-automatically) feature. A WebVTT file starts with `WEBVTT` on the first line, followed by cue blocks: ``` WEBVTT 00:00:01.000 --> 00:00:04.000 Hello and welcome to the video. 00:00:05.000 --> 00:00:08.500 This caption appears five seconds in. ``` Timestamps use a period (`.`) for milliseconds, unlike SRT's comma. Yes, but you do not have to. FastPix accepts either format. If you want to convert, the core change is the header (`WEBVTT` line) and the timestamp separator (comma to period). Many open-source tools handle this in one step. FastPix does not impose a documented limit on subtitle tracks per `mediaId`. Each track needs a distinct `languageCode`. Players expose every attached track in their language selector. \ ## What's next? * [Add auto-generated subtitles to videos](/video-on-demand/generate-subtitles-automatically) * [Upload videos from URL](/upload-videos/upload-videos-from-a-url) * [API Reference: Add media track](/video-on-demand-api/manage-videos/add-media-track) * [API Reference: Update media track](/video-on-demand-api/manage-videos/update-media-track) * [API Reference: Delete media track](/video-on-demand-api/manage-videos/delete-media-track)