Text Track Uploads

Text tracks, as the name implies, are bits of text, i.e. WORDS, you associate with your video:

  • Subtitles provide viewers with a video’s dialogue in written form.
  • Captions include subtitles plus a written description of what is occurring in the videos for viewers who might not be able to hear or understand the sound.

To upload text tracks using our API, all you need to do is:

  1. Create a resource.
  2. Upload the file.
  3. Mark it as "active"

Note: If you are using one of our official libraries, the libraries take care of constructing the HTTP requests for you. Refer to the text tracks upload examples for each library for more information.

Step 1: Create the resource

Before you can upload, you need to create a resource (see the example below) using the texttracks_uri you received in the response when you uploaded the video (located in metadata.connections.texttracks.uri).

Request

POST https://api.vimeo.com{texttracks_uri}
Field Required Description
type Yes captions or subtitles
language Yes See the /languages endpoint for more details
name No A descriptive name for your own use

Once our API receives this request, it returns an HTTP response that includes the URL where you can upload the file. The URL is contained in the link parameter passed back in the JSON response.

Step 2: Get the upload link and send the file

To upload, make a PUT request to the link returned from Step 1 with the content of the text track file in the request body.

<?php
$file_path = '/path/to/your/texttrack.tt';
$texttrack_resource = fopen($file_path, 'r');
$curl_opts = [
    CURLOPT_HEADER => 1,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 240,
    CURLOPT_UPLOAD => true,
    CURLOPT_CUSTOMREQUEST => 'PUT',
    CURLOPT_READDATA => $texttrack_resource
];

$curl = curl_init($upload_url);
curl_setopt_array($curl, $curl_opts);
$response = curl_exec($curl);
$curl_info = curl_getinfo($curl);
if (!$response) {
    $error = curl_error($curl);
    throw new Exception($error);
}

curl_close($curl);

Step 3: Make your uploaded text track the active track

Since you can upload more than one text track, you need to pick one and make it active. This takes just a single API call, except this time you’ll also set the active parameter to true in the request body:

Request

POST https://api.vimeo.com{texttracks_uri}
Field Required Description
active Yes Must be set to true to activate this text track