10 – YouTube Data API – Captions – list function

June 27, 2017 amit YouTube API With PHP 1

This is article 10 of the YouTube API With PHP series.

CAPTIONS

A Caption track is a text based track attached to a video, which is used for displaying captions and/or subtitles. A Video can have zero or multiple Captions tracks. Captions tracks can be for multiple languages. For eg.a Video can have 3 captions for English, German and French. There are five functions available for Captions.

1.list

This retrieves as list of all the Caption tracks associated with a Video. This will not get the actual caption content but only the details of the Tracks.

The Request URL is

GET https://www.googleapis.com/youtube/v3/captions

Parameters

  • key (string) required. Your API key
  • part (string) required. Comma separated. One of or all of the below:
    • “id”
    • “snippet”
  • videoId (string) required. The video id of the video
  • id (string) optional. Comma separated caption ids. The id(s) should match the id(s) of the associated caption tracks.

onBehalfOfContentOwner (string) optional. This is relevant only for YouTube Channel Partners. For this parameter, the API request URL should have user authentication.We will not be exploring this option.

 

Example Requests

Get all Caption tracks for a video id

https://www.googleapis.com/youtube/v3/captions?part=snippet,id&videoId=xxx&key=xxxx;

Response

 A successful request will return the following JSON response:

{
  "kind": "youtube#captionListResponse",
  "etag": etag,
  "items": [
    (Caption Resource)
  ]
}

The Response components are explained below:

  • kind (string) “youtube#captionListResponse.”
  • etag (string) See ETags Explained section
  • items (array) array of Caption Resource items

 

Caption Resource

 The items returned in an Caption list request are an array of Caption Resource objects. The JSON structure is shown below:

{
  "kind": "youtube#caption",
  "etag": etag,
  "id": string,
  "snippet": {
    "videoId": string,
    "lastUpdated": datetime,
    "trackKind": string,
    "language": string,
    "name": string,
    "audioTrackType": string,
    "isCC": boolean,
    "isLarge": boolean,
    "isEasyReader": boolean,
    "isDraft": boolean,
    "isAutoSynced": boolean,
    "status": string,
    "failureReason": string
  }
}

An explanation of the various fields are given below:

  • kind (string) This value is always “youtube#caption”
  • etag (string) See ETags Explained section
  • id (string) unique id of this Caption
  • videoId (string) id of the video that the caption belongs to
  • lastUpdated (datetime) Date and time when this Caption was last updated. (YYYY-MM-DDThh:mm:ss.sZ) format.
  • trackKind (string) . Can be one of the following:
    • “ASR” – A caption track generated using automatic speech recognition
    • “forced” – A caption track that plays when no other track is selected in the player. For example, a video that shows aliens speaking in an alien language might have a forced caption track to only show subtitles for the alien language.
    • “standard” – A regular caption track. This is the default value
  • language (string) – The language of the caption track. The property value is the international two-letter language code
  • name (string) – The name of the caption track. The name is intended to be visible to the user as an option during playback.
  • audioTrackType (string) . Type of audio track associated with the Caption track. Can be one of the following:
    • “commentary” – The caption track corresponds to an alternate audio track that includes commentary, such as directory commentary
    • “descriptive” – The caption track corresponds to an alternate audio track that includes additional descriptive audio.
    • “primary” – The caption track corresponds to the primary audio track for the video, which is the audio track normally associated with the video.
    • “unknown” – This is the default value
  • isCC (boolean) – Indicates whether the track contains closed captions for the deaf and hard of hearing. The default value is false.
  • isLarge (boolean) – Indicates whether the caption track uses large text for the vision-impaired. The default value is false.
  • isEasyReader (boolean) – Indicates whether caption track is formatted for “easy reader,” meaning it is at a third-grade level for language learners. The default value is false.
  • isDraft (boolean) – Indicates whether the caption track is a draft. If the value is true, then the track is not publicly visible. The default value is false.
  • isAutoSynced (boolean) – Indicates whether YouTube synchronized the caption track to the audio track in the video. The value will be true if a sync was explicitly requested when the caption track was uploaded. For example, when calling the captions.insert or captions.updatemethods, you can set the sync parameter to true to instruct YouTube to sync the uploaded track to the video. If the value is false, YouTube uses the time codes in the uploaded caption track to determine when to display captions.
  • status (string) – Caption track status. Possible values are:
    • “failed”
    • “serving”
    • “syncing”
  • failureReason (string) – The reason that YouTube failed to process the caption track. This property is only present if the state property’s value is “failed”. Possible values are:
    • “processingFailed”
    • “unknownFormat”
    • “unsupportedFormat”

 

Code which gets Caption tracks of a Video with a lot of Caption tracks in multiple languages:

<?php
    error_reporting(E_ALL ^ E_NOTICE ^ E_WARNING ^ E_DEPRECATED);
    set_time_limit(60 * 3);
    session_start();

    $clientId = "***";
    $clientSecret = "***";
    $g_youtubeDataAPIKey = "*****";

    $videoId =  "M7FIvfx5J10";
       	 
   	 // make api request
   	 $url = "https://www.googleapis.com/youtube/v3/captions?part=id,snippet&videoId=" . $videoId . "&key=" .
   			 $g_youtubeDataAPIKey ;

   	 $curl = curl_init();
   	 curl_setopt_array($curl, array(
   				 CURLOPT_RETURNTRANSFER => 1,
   				 CURLOPT_URL => $url,
   				 CURLOPT_USERAGENT => 'YouTube API Tester',
   				 CURLOPT_SSL_VERIFYPEER => 1,
   				 CURLOPT_SSL_VERIFYHOST=> 0,
   				 CURLOPT_CAINFO => "../../cert/cacert.pem",
   				 CURLOPT_CAPATH => "../../cert/cacert.pem",
   				 CURLOPT_FOLLOWLOCATION => TRUE
   				 ));
   	 $resp = curl_exec($curl);

   	 curl_close($curl);


   	 
   	 if ($resp) {
   		 $json = json_decode($resp);
   		 if ($json) {
   			 echo("JSON decoded<br>");

   			 $items = $json->items;

   			 foreach($items as $item) {
   				 $videoId = $item->snippet->videoId;
   				 $lastUpdated = $item->snippet->lastUpdated;
   				 $trackKind = $item->snippet->trackKind;
   				 $language = $item->snippet->language;
   				 $name = $item->snippet->name;
   				 $trackType = $item->snippet->audioTrackType;
   				 $isCC = $item->snippet->isCC;
   				 if (!$isCC)
   					 $isCC = "false";
   				 $isLarge = $item->snippet->isLarge;
   				 if (!$isLarge)
   					 $isLarge = "false";
   				 $isEasyReader = $item->snippet->isEasyReader;
   				 if (!$isEasyReader)
   					 $isEasyReader = "false";
   				 $isDraft = $item->snippet->isDraft;
   				 if (!$isDraft)
   					 $isDraft = "false";
   				 $isAutoSynced = $item->snippet->isAutoSynced;
   				 if (!$isAutoSynced)
   					 $isAutoSynced  = "false";
   				 $status = $item->snippet->status;
   				 $failureReason = $item->snippet->failureReason;

   				 echo("Video id:" . $videoId . ", Track Kind:" . $trackKind . " (" . $language . ")<br>");
   				 echo("Name: " . $name . ", Type:" . $trackType . "<br>");
   				 echo("Closed Captions:" . $isCC . "<br>");
   				 echo("Large Captions:" . $isLarge . "<Br>");
   				 echo("Easy Reader:" . $isEasyReader . "<br>");
   				 echo("Draft:" . $isDraft . "<br>");
   				 echo("Autosynced:" . $isAutoSynced . "<br>");
   				 echo("Status:" . $status  . "<br>");
   				 if ($failureReason != null && $failureReason != "")
   					 echo("Failure :" . $failureReason);
   				 echo("<hr>");
   			 } // foreach

   		 }
   		 else
   			 exit("Error. could not parse JSON." . json_last_error_msg());

    } // if resp
?>

Here is the Output:

JSON decoded
Caption Id: 8yMV7mc691ajCze115cxb5goeKsI0BJn Video id:M7FIvfx5J10, Track Kind:standard (bg)
Name: , Type:unknown
Closed Captions:false
Large Captions:false
Easy Reader:false
Draft:false
Autosynced:false
Status:serving
Caption Id: 8yMV7mc691bRtJqxYhDZfwpf4t7J0c3U Video id:M7FIvfx5J10, Track Kind:standard (cs)
Name: , Type:unknown
Closed Captions:false
Large Captions:false
Easy Reader:false
Draft:false
Autosynced:false
Status:serving
Caption Id: 8yMV7mc691Z6Qm0wPgzpAr1n3cTeyVr8 Video id:M7FIvfx5J10, Track Kind:standard (da)
Name: , Type:unknown
Closed Captions:false
Large Captions:false
Easy Reader:false
Draft:false
Autosynced:false
Status:serving
Caption Id: 8yMV7mc691aQLvenWJWCmpp8z8Z9K9Ax Video id:M7FIvfx5J10, Track Kind:standard (de)
Name: , Type:unknown
Closed Captions:false
Large Captions:false
Easy Reader:false
Draft:false
Autosynced:false
Status:serving
Caption Id: 8yMV7mc691YVqd-795pLog4NtMjzJelm Video id:M7FIvfx5J10, Track Kind:standard (el)
Name: , Type:unknown
Closed Captions:false
Large Captions:false
Easy Reader:false
Draft:false
Autosynced:false
Status:serving
Caption Id: 8yMV7mc691aTqjNxZ9zPHOdwpkL_e11j Video id:M7FIvfx5J10, Track Kind:standard (en)
Name: , Type:unknown
Closed Captions:false
Large Captions:false
Easy Reader:false
Draft:false
Autosynced:false
Status:serving

You can request captions for a video which does not belong to you. Most videos allow caption tracks to be listed. It is not necessary that Caption tracks will have a name. Caption tracks can be auto-generated by YouTube or specifically added by the video owner.

Leave a Reply

Your email address will not be published.


*