YouTube Captions Revisited: Various APIs and Services

I did some work over the weekend to improve Able Player’s support for YouTube videos. The changes will be available in the next major release of Able Player, which I’ll be unveiling in my session at CSUN.

The biggest challenge with playing YouTube videos in a third-party player is getting access to captions. I described the issues in a previous blog post, Handling Captions via the YouTube Player API. The biggest problem with the YouTube IFrame API, which is used to embed a YouTube player in a web page, is that the API exposes captions and subtitles only after the onAPIChange event is fired, which doesn’t happen until the video starts playing. This makes it very difficult to construct the player, as we don’t know whether to include a CC button, and whether clicking on that button should display a pop-up menu for selecting available languages.

The workaround I used in Able Player was to autostart the video and play it for just long enough to trigger the onApiChange event, then reset the video back to the start and collect the caption data that had been exposed during the brief moment of playback. This is a clumsy hack, and I’ve been looking for a better way.

A better way: YouTube Data API

The YouTube Data API (v3) enables us to retrieve caption data before constructing the player, so we no longer need to play the video in order to find out what captions or subtitles are available. In order to use this, however, anyone using Able Player to play YouTube videos on their website will need to register their applications with Google and obtain a Google API key. This is explained on the Getting Started page for Google’s API Client Library for JavaScript.

Google’s APIs Explorer lists all of the Google services that have APIs, and (if you click on an API) lists the services and methods that are available through each. The YouTube Data API Explorer page currently lists seventeen services or methods, including five that specifically relate to captions:

  • youtube.captions.delete
  • youtube.captions.insert
  • youtube.captions.list
  • youtube.captions.update

Of these, the only one that can be used with a simple API Key is youtube.captions.list, which enables us to retrieve a list of available caption or subtitle tracks for a particular video. This is the service that has now been incorporated into Able Player, so we can now build the player, including a caption button and associated pop-up menu for selecting an available language, without first playing the video.

Still not perfect

Unfortunately, youtube.captions.list only provides us with a list of caption tracks, not the actual captions. To get the actual captions, we need to use, and that requires OAuth 2.0 credentials. This higher level of authentication gives us direct access to individual user’s YouTube accounts, and is what enables developers including captioning service providers to create full YouTube integrations. This is great, but not great for our use case, as it means we can only download captions if the owner of those captions specifically grants us permission to do so. The person watching a video in our player probably isn’t the owner of the video.

If was protected by a simple API key, not OAuth 2.0, we could download the captions for any video in WebVTT (or in various other caption formats supported by the service). Then we could parse the WebVTT file just like we do for captions that aren’t hosted on YouTube, and integrate them fully into the Able Player interface. Advantages of doing so would be:

  1. We could use the captions to build an interactive transcript.
  2. We could enable full-text search of any video.
  3. We could allow users full control over the display of their captions.

All of these features are already available in Able Player for videos not hosted on YouTube. I’d love to be able to provide the same functionality for YouTube videos as well.

User Preferences and Display of Captions

Both YouTube and Able Player provide users with the ability to customize the appearance of captions, including font style, size, color, background color, and opacity.
If we could access captions from YouTube, we could display them in our designated caption container and users could adjust their display via the Able Player Preferences dialog.

Since we can’t currently access captions, it would be nice if we could at least customize the display of captions on YouTube. Then, if users make a change to their preferences in Able Player, those changes could be applied to the display of captions on YouTube. The YouTube IFrame API does provide a setOption() function that could be used for this purpose, but according to the documentation the only display option that can currently be changed is fontSize. For example, the following command would increase the caption font size to size 3, which is the maximum size supported by YouTube:


This is a helpful start, but it would be even more helpful if font style, color, background color, and opacity were also supported.

Meanwhile, we’re doing our best to support YouTube videos in Able Player, but users still have to settle for less than full functionality.

One reply on “YouTube Captions Revisited: Various APIs and Services”

Comments are closed.