Manage subtitle tracks

Subtitles are a crucial component of any video content, improving accessibility, engagement, and language support for a diverse audience. Whether you need to add subtitles in multiple languages, update existing captions, or remove outdated subtitle tracks, the FastPix Tracks API provides a streamlined approach to subtitle management.

This guide covers essential operations for handling subtitle tracks:

1. Adding new subtitle tracks to support multiple languages and accessibility.

2. Deleting unnecessary subtitle tracks to optimize content.

3. Updating existing subtitle tracks to ensure accuracy and up-to-date translations.

Additionally, the API supports BCP 47 language codes, ensuring standardized language tagging across different platforms and media systems.

Authentication

All API requests to FastPix require authentication. You must include your access credentials in the Authorization header to verify API requests.

Authorization: Basic Auth YOUR_ACCESS_TOKEN YOUR_SECRET_TOKEN

IMPORTANT

Ensure that your access token and secret token are kept secure and used correctly in each API request.

Language code support

The Tracks API supports language codes strictly in accordance with the BCP 47 standard. When adding or updating subtitle tracks, ensure that the language code is specified in this format. These language tags provide a consistent and standardized way to represent language and locale information, ensuring compatibility across systems and platforms.

Refer to the BCP 47 specification for more details on valid language tags.

1. Add a subtitle track to existing media

This API endpoint allows you to add a new subtitle track to an existing video. You can specify the language, subtitle file URL, and subtitle format. FastPix supports both WebVTT and SRT formats.

Endpoint:

https://v1.fastpix.io/on-demand/{mediaId}/tracks

Request headers:

Content-Type: application/json

Authorization: Basic Auth YOUR_ACCESS_TOKEN YOUR_SECRET_KEY

Request body:

{ 
"tracks": 
  {
    "url": "https://example.com/fr.vtt", 
    "type": "subtitle",  
    "languageCode": "fr",  // Input the language code here, it should BCP 47 supported tag
    "languageName": "French" // Input your language name here
  } 
}

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:

{
  "success": true,
  "data": {
    "id": "22d6607d-b7bc-4756-817c-e959d4dbbb81",
    "type": "subtitle",
    "url": "https://example.com/fr.vtt",
    "languageCode": "fr",
    "languageName": "French"
  }
}

If you want to add subtitle tracks when creating new media, follow here .

2. Delete a subtitle track in existing media

This endpoint allows you to delete an existing subtitle track from an already uploaded video.

Endpoint:

https://v1.fastpix.io/on-demand/{mediaId}/tracks/{trackId}

Request headers:

Authorization: Basic Auth YOUR_ACCESS_TOKEN YOUR_SECRET_KEY

Response example:

{ 
  "success": true
}

NOTES

Deleting a subtitle track is permanent and cannot be undone.

Ensure you provide the correct trackId associated with the subtitle you want to remove.

3. Update a subtitle track in existing media

This endpoint allows you to modify an existing subtitle track by changing the subtitle file or updating the language information.

Endpoint:

https://v1.fastpix.io/on-demand/{mediaId}/tracks/{trackId}

Request headers:

Content-Type: application/json
Authorization: Basic Auth YOUR_ACCESS_TOKEN YOUR_SECRET_KEY

Request body:

{
  "url": "https://example.com/de.srt",
  "languageCode": "de",
  "languageName": "german"
}

PLEASE NOTE

Only .vtt and .srt formats are supported.

Use the correct trackId for the subtitle you want to update.

Ensure the languageCode follows BCP 47 standards.

Response example:

{  
  "success": true,  
  "data": {  
    "id": "455d0ab6-853d-469c-b07d-d16b7d5f0966",  
    "type": "subtitle",  
    "url": "https://example.com/de.srt",  
    "languageCode": "de",  
    "languageName": "german"  
  }  
}

Add subtitles while creating new media

FastPix allows adding subtitle tracks directly when creating new media, either by uploading a subtitle file or providing a URL. You can include subtitle objects in the payload for both Create Media by Direct Upload and Create Media by URL endpoints.

Key parameters:

type: Defines the input type (subtitle for subtitle tracks).
url: Direct link to the subtitle file (must be .vtt or .srt format).
languageCode: Follows BCP 47 language tags (e.g., en, fr).
languageName: Full name of the language for display purposes.

Add subtitles when uploading media directly from device

Method: POST

URL: v1.fastpix.io/on-demand/uploads

{
   "corsOrigin": "*",
   "time": null,
   "pushMediaSettings": {
     "accessPolicy": "public",
     "inputs": [
       {
         "type": "subtitle",
         "url": "https://example.com/en-US.vtt",
         "languageCode": "en-US",
         "languageName": "english"
       },
       {
         "type": "subtitle",
         "url": "https://example.com/en.vtt",
         "languageCode": "en",
         "languageName": "japanese"
       },
       {
         "type": "subtitle",
         "url": "https://example.com/fr.vtt",
         "languageCode": "fr",
         "languageName": "french"
       }
     ]
   }
 }

Add subtitles when uploading media from URL

Method: POST

URL: v1.fastpix.io/on-demand

{
  "inputs": [
       {
         "type": "subtitle",
         "url": "https://example.com/en-US.vtt",
         "languageCode": "en-US",
         "languageName": "english"
       },
       {
         "type": "subtitle",
         "url": "https://example.com/en.vtt",
         "languageCode": "en",
         "languageName": "japanese"
       },
       {
         "type": "subtitle",
         "url": "https://example.com/fr.vtt",
         "languageCode": "fr",
         "languageName": "french"
       }
     ],
  "accessPolicy": "public"
}

Generate subtitles automatically

Instead of manually uploading subtitle files, FastPix also supports automatic subtitle generation when creating media. This feature allows the system to analyze video content and generate machine-generated captions for supported languages.

To enable this feature, refer to the add auto-generated subtitles guide.