Download Button Plugin

Introduction

To add the Download Plugin, see Implement using Players module.

Download mp4 example

Download transcript example

Basics

The Download plugin relies on the player’s mediainfo object. This object needs to contain a few sub-properties to work.

tags: The tags attribute contains information about the player’s media info. To initialize the download button plugin, this array needs to include the string “downloadable“ and all other elements are ignored.
```
tags: ["downloadable"]
```
sources: The sources array contains information about different sources pulled in by the player. The download button plugin looks for the highest quality mp4 source within this array; all other elements are ignored. The container property determines the source is an mp4 file, and the size property chooses the mp4 quality.
```
  sources: [{
      avg_bitrate: 2121000,
      codec: "H264",
      container: "MP4",
      duration: 734167,
      height: 720,
      size: 195024286,
      src: "https://examplesource.mp4",
      type: "video/mp4",
      width: 1728
    }]
```
Sources are only used when downloading an mp4 file for the video.
transcripts: The transcripts array lists all of the transcripts tied to the player. The download button plugin looks for a transcript with a language that matches the player’s language. If none correspond, it selects the first transcript in the list. The src_lang property determines the transcript’s language.
```
  transcripts: [{
    default: false,
    id: "95423543d7-8363-49dd-9b1c-ff32365433fc0cda",
    label: "English",
    src: "https://examplesource.txt",
    src_lang: "en-US",
    status: null
    }]
```
Notes:
- Transcripts are not the same thing as captions (text tracks) - you cannot download captions using this plugin. To add transcripts to a video see Ingesting Transcript Files and Requesting Auto Captions (there is an option to request an auto transcript instead of captions). Currently transcripts can only be added or auto-generated using the Dynamic Ingest API.
- Transcripts are only used when downloading a text file for the transcript.

Browser compatibility

The plugin is compatible with the latest versions of these major browsers:

Chrome Desktop
Chrome Mobile (on Android 6+)
Firefox Desktop
Edge
Safari Desktop *
Safari Mobile (iOS 11.2+) *

Implement using Players module

You configure the player manually to enable this function:

Open the PLAYERS module and either create a new player or locate the player to which you wish to add the plugin.
Click the link for the player to open the player's properties.
Click JSON Editor in the left navigation menu.
In the JSON Editor object, add the property download_button.

To configure the player to download the highest quality MP4 file available, use the mp4 value when defining this property. Your code should look similar to this:

To configure the player to download a text file of the transcript that matches the language used on the player (or the first transcript if none match), use the transcript value when defining the download_button property. Your code should look similar to this:

You need to add a transcript for the video in order to add the upload button. For more information, see Ingesting Transcript Files

Please note that if the download_button configuration is missing, or if the value in the configuration is anything other than “mp4” or “transcript”, the download plugin will not be initialized.
Click Save.

In cases where this feature is enabled but an mp4 or transcript is not available, the button still appears but is disabled.

Runtime properties

The download button can be accessed with player.downloadButton. This object has some accessible properties that could be useful.

`player.downloadButton.state`

Type: String

This property describes the current state of the download button. The following are the valid options:

ready: The download button is ready to start a download.
hidden: The download button is hidden. This state occurs when the downloadable tag is missing.
off: The download button is not in the DOM. This state occurs when the source is invalid or missing.

`player.downloadButton.source`

Type: String

This property contains a URL to the source to be downloaded. Depending on the download method, this can be a link to the mp4 file or a transcript text file.

Events

The download button plugin triggers a handful of events for analytic purposes.

download-ready: Fired once the plugin is initialized successfully.
download-hidden: Fired when the plugin is initialized and the button is hidden. This happens when the tags array in mediainfo is missing the ”downloadable” tag.
download-disabled: Fired when the plugin is initialized and the button is disabled. This happens when the mediainfo object is either missing or has invalid sources or transcripts depending on the expected download method.
download-started: Fired when the download button is clicked and a download begins.
download-finished: Fired when a download finished successfully. This event also sends the file name to the listener.
download-failed: Fired when a download fails. This event also sends information about the error to the listener.