Skip to main content

Plugin SDK Audio Description - Basic setup

Updated

This article goes over the basic setup for 3Play Media's Audio Description plugin. This section is in addition to the basic setup of the 3Play Plugin, which described in Plugin SDK Overview.

The *Plugin SDK allows you to customize the audio description using HTML and CSS. JavaScript can be used for more advanced customizations. 
The code for the audio description setup below must be placed inside of the p3sdk-container div.  

 Basic setup code:

Steps 1-3 explain how to load the Audio description snippets and the audio track.
Steps 4-7 explain how to show basic settings for the Audio Description plugin to work.
A sample code is provided at the end of this section.

  1. p3sdk-audio-description-component is the parent component for the Audio Description plugin. Every setting/ feature must be included within this div
  2. The p3sdk-snippets attribute p3sdk-audio-description contains the Audio Description Snippets. The <snippet-json> in the example below is a placeholder, and should be replaced with the actual Audio Description Snippets. Please refer to the Audio Description Snippets Endpoint to understand how to get the snippets
  3. The audio tag with the mycroft-audio-track holds the audio track for the Audio Description. The <audio-description-audio-track-path> in the example below is a placeholder, and should be replaced with the actual path for the audio track for the Audio Description. Please refer to the Audio Description Audio Track Endpoint to understand how to get the path for the audio track.
  4. The mycroft-audio-description-widget div is a wrapper for all Audio Description plugin settings and features.
  5. The button labelled Toggle Audio Description Controls is responsible for toggling the Audio Description track on and off. You can use your icons by updating the classes in the i tag.
    The mycroft-audio-description-snippet-toggle and mycroft-primary classes are however required by the plugin.
  6. The button labelled Mute is responsible for toggling the audio on the Audio Description track. You can use your icons by updating the classes in the i tag.
    The mycroft-audio-description-snippet-toggle mycroft-volume-display, and mycroft-primary classes are however required by the plugin.
  7.  The mycroft-vol-control displays the volume bar for the Audio Description audio track. 

    NOTE: Adding the class debug div within the p3sdk-audio-description-component div allows you extra debugging features in your browser JavaScript Console. 
<div class="p3sdk-audio-description-component">
  <div class="p3sdk-audio-description" p3sdk-snippets="<snippet-json>">
    <audio class="mycroft-audio-track">
      <source src="<audio-description-audio-track-path>" type="audio/mp3">
      Your browser does not support the audio element.
    </audio>
    <div class="mycroft-audio-description-widget">
      <button aria-expanded="true" aria-label="Toggle Audio Description Controls" aria-pressed="true" class="mycroft-audio-description-snippet-toggle glowing-border">
        <i alt="Audio Description Widget" aria-hidden="true" class="mycroft-primary" title="Audio Description Widget"></i>
      </button>
      <button aria-label="Mute" aria-pressed="false" class="mycroft-audio-description-toggle glowing-border">
        <i alt="Mute Audio Description" aria-hidden="true" class="mycroft-volume-display mycroft-primary"></i>
      </button>
      <input class="mycroft-vol-control" max="100" min="0" step="1" style="" title="volume control" type="range">
   </div>
 </div>
 <div class="debug"></div>
</div>

Audio Description Snippets Endpoint

The Audio description snippets can be grabbed via 3Play Media's plugin API, Audio Description Snippet endpoint : https://static.3playmedia.com/p/projects/<project-id>/files/<file-id>/audio_description/snippets
Where <file-id> and <project-id> are the 3Play Media account system's file id and project id the file belongs to.

Eg: https://static.3playmedia.com/projects/10219/files/2072696/audio_description/snippets

A sample valid response would be of the following form:

{
 "status": 200,
 "data": [
     {
       "extended": true,
       "start_time": 495,
       "end_time": 3960,
       "text": "A figure silhouetted against a low wide window and reflected on a glossy black floor. Water falls slowly past the window, which opens onto a large hangar.",
       "delay": 0,
       "audio_snippet_id": 41862,
       "state": "paused",
       "audio_duration": 7911
     },
     {
       "extended": true,
       "start_time": 12536,
       "end_time": 14770,
       "text": "A figure, seen from above, leads a line of white-clad soldiers carrying rifles across a lava field. A line of massive four-legged armored A.T.-A.T. walkers march across an open plain, raising clouds of red dust. ",
       "delay": 4463,
       "audio_snippet_id": 41863,
       "state": "paused",
       "audio_duration": 10826
     },
   ....
  ]
}

The data part of the response, which is an array of snippets object is what the plugin needs.

NOTE: Optionally you can include the service_id param if there are multiple audio description services ordered on the same file. (https://static.3playmedia.com/p/projects/<project-id>/files/<file-id>/audio_description/snippets?service_id=<service-id>)
The code defaults to the extended Audio Description service(if present) in absence of the service_id param.

Audio Description Audio Track Endpoint

The Audio description audio track can be grabbed via 3Play Media's plugin API, Audio Description Snippet endpoint : https://static.3playmedia.com/p/projects/<project-id>/files/<file-id>/audio_description/snippet_audio
Where <file-id> and <project-id> are the 3Play Media account system's file id and project id the file belongs to.

Eg: https://static.3playmedia.com/p/projects/10219/files/2072696/audio_description/snippet_audio

A sample valid response would be of the following form:

{
 "status": 200,
 "data": "https://d1q5sowf7qahc6.cloudfront.net/10219/2072696/2072696-1429-description.mp3"
}

The data part of the response, which is the path to the audio track is what need. 

Customizing the Audio Description Plugin

Now that you've finished setting up a basic Audio Description Plugin, you can head over to the Plugin SDK Audio Description Features page.

*The Plugin SDK is sometimes referred to as "P3SDK".

Related articles