Manage audio and subtitle tracks

Add subtitles to a video

Manage subtitle tracks with add, update, and delete operations supporting WebVTT and SRT formats.

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)
  • Your Access Token ID and Secret Key from the FastPix dashboard
  • An existing mediaId (see Upload videos from 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 for valid tags.


Add a subtitle track to existing media

The add media track endpoint 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:

1{
2  "tracks": {
3    "url": "https://static.fastpix.com/subtitle_Spanish.srt",
4    "type": "subtitle",
5    "languageCode": "es",
6    "languageName": "Spanish"
7  }
8}

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
1{
2  "id": "606bea3a-21af-4ca2-89a4-b05eb1f410f0",
3  "type": "subtitle",
4  "url": "https://static.fastpix.com/subtitle_Spanish.srt",
5  "languageCode": "es",
6  "languageName": "Spanish"
7}

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.


Delete a subtitle track from existing media

The delete media track endpoint removes a subtitle track from an uploaded asset. Pass the mediaId and the trackId you received when the track was created.

Response example:

Response
1{ 
2  "success": true
3}

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 replaces an existing subtitle file or changes the language metadata on a track.

Request body:

Request
1{
2  "url": "https://static.fastpix.com/subtitle_Russian.srt",
3  "languageCode": "ru",
4  "languageName": "Russian"
5}

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
1{
2  "success": true,
3  "data": {
4    "id": "5785924d-8d95-4ef9-b801-51b772fe7e8a",
5    "type": "subtitle",
6    "url": "https://static.fastpix.com/subtitle_Russian.srt",
7    "languageCode": "ru",
8    "languageName": "Russian"
9  }
10}

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 or Create Media by URL.

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
1{
2  "corsOrigin": "*",
3  "pushMediaSettings": 
4  {
5    "accessPolicy": "public",
6    "inputs": [
7      {
8        "type": "subtitle",
9        "url": "https://static.fastpix.com/subtitle_Spanish.srt",
10        "languageCode": "es",
11        "languageName": "Spanish"
12      },
13      {
14        "type": "subtitle",
15        "url": "https://static.fastpix.com/subtitle_Russian.srt",
16        "languageCode": "ru",
17        "languageName": "Russian"
18      },
19      {
20        "type": "subtitle",
21        "url": "https://static.fastpix.com/subtitle_Portuguese.srt",
22        "languageCode": "pt",
23        "languageName": "Portuguese"
24      }
25    ],
26    "metadata": {
27      "key1": "value1"
28    },
29    "maxResolution": "1080p"
30  }
31}

Attach subtitles on a URL upload

Request Body
1{
2  "inputs": [
3    {
4      "type": "video",
5      "url": "https://static.fastpix.com/fp-sample-video.mp4"
6    },
7    {
8      "type": "subtitle",
9      "url": "https://static.fastpix.com/subtitle_Spanish.srt",
10      "languageCode": "es",
11      "languageName": "Spanish"
12    },
13    {
14      "type": "subtitle",
15      "url": "https://static.fastpix.com/subtitle_Russian.srt",
16      "languageCode": "ru",
17      "languageName": "Russian"
18    },
19    {
20      "type": "subtitle",
21      "url": "https://static.fastpix.com/subtitle_Portuguese.srt",
22      "languageCode": "pt",
23      "languageName": "Portuguese"
24    }
25  ],
26  "metadata": {
27    "key1": "value1"
28  },
29  "accessPolicy": "public",
30  "maxResolution": "1080p"
31}

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 to enable this option.


Frequently asked questions

Which is better, WebVTT or SRT?

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

How do I create an SRT file for subtitles from a video?

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

What does a WebVTT file look like?

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.

Can I convert SRT to WebVTT before uploading?

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.

How many subtitle tracks can I attach to one asset?

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?