# Multimedia Player

Questions or comments?

## Purpose

Provides an accessible multimedia player for embedding video and audio into web pages.

## Examples

- English video example
- French video example
- English audio example
- French audio example
- English YouTube example
- French YouTube example

## How to implement

The multimedia player requires the use of a few HTML5 tags and a link to the media source you wish to embed.

### Media Formats

The media player supports several formats, listed below; however, we recommend at a minimum you provide any video media in MPEG4 (using the H264 and AAC codecs) to be able to reach every audience, as all mobile players and most browsers are able to play this format. We also recommend you provide media in the WebM format (using the VP8 codec) in addition to MPEG4 in order to take advantage of native browser support, for example Firefox.

#### Compatible Formats

- Video: MPEG4 (H264+AAC), WebM (VP8)
- Audio: MP3, Ogg Vorbis
- Captions: TTML, HTML5 Data

### Required Elements

1. Each multimedia player must be placed in its own `<figure>` using the `wb-mltmd` class:

       <figure class="wb-mltmd">

2. Each container should contain one `<video>` or `<audio>` tag.
3. Optional: Add a "Share this video" or "Share this audio file" link by adding the following to the `figure` element:

       data-wb-mltmd='{"shareUrl": "url"}'

4. Add a `figcaption` element to the `figure` element with the title of the video or audio file. If a transcript is required, then also include either a link to the transcript or a details/summary containing the transcript.

       <figcaption>
       	<p>Looking for a Job</p>
       </figcaption>

       <figcaption>
       	<p>Looking for a Job (<a href="cpts-lg-en.html">Transcript</a>)</p>
       </figcaption>

       <figcaption>
       	<details id="inline-captions">
       		<summary>Looking for a Job - HTML5 Transcript/Captions</summary>
       		<p class="wet-boew-vd"><strong>(Animated pen draws a red line that leads into the text Looking for A Job)</strong></p>
       		<p class="wet-boew-vd"><strong>(Cut to a medium shot of the Host. LINE DRAWING GRAPHIC: Stick person appears and waves.)</strong></p>
       		<p><span class="wb-tmtxt" data-begin="2.50s" data-dur="3.84s">Hi, my name is Eric, and I'm a Service Canada employee.</span></p>
       		...
       	</details>
       </figcaption>

#### Video

1. Add a `poster` attribute to the `video` element with the value being the URL for the thumbnail image.
2. Add a `title` attribute to the `video` element with the value being the title of the video.
3. Add one or more `source` elements to the `video` element with the `src` attribute value being the URL of the media file and the `type` attribute being the media file MIME type.
   Note: If you list multiple media sources for the video, the player will play the first media source file that works (is available, compatible, etc.).

       <source type="video/webm" src="http://video2.servicecanada.gc.ca/video/boew-wet/te-lj-eng.webm" />
       <source type="video/mp4" src="http://video2.servicecanada.gc.ca/video/boew-wet/te-lj-eng.mp4" />

4. Add a `track` element with `kind="captions"` to the `video` element to add captions.
   1. Add the `srclang` and `label` attributes to the `track` element to identify the captions language.

          <track srclang="en" label="English" />

   2. Add the `src` and `data-type` attributes to the `track` element to identify the source of the captions.
      - Timed Text Markup Language: `data-type="application/ttml+xml"` and `src` is the URL of the Timed Text Markup Language captions file.
      - HTML captions file: `data-type="text/html"` and `src` is the URL of the HTML captions file.
      - Inline HTML captions: `data-type="text/html"` and `src` is the URL of the inline HTML captions (e.g., `src="#inline-captions"`.

       <track src="cpts-lg-en.html" kind="captions" data-type="text/html" srclang="en" label="English" />

5. Optional: Add buttons to link to cue points within your video.
   - Add a `button` element within the `figure` container.
   - Specify the cue point in seconds (ex. 75s) or time notation (01:15)

       <button class="btn btn-info cuepoint" data-cuepoint="75s">Cue point - 75s</button>

       <button class="btn btn-info cuepoint" data-cuepoint="01:15">Cue point - 01:15</button>

##### Code

    <figure class="wb-mltmd" data-wb-mltmd='{"shareUrl": "https://wet-boew.github.io/v4.0-ci/demos/multimedia/multimedia-en.html"}'>
    	<video poster="demo/video1-en.jpg" title="Looking for a Job">
    		<source type="video/webm" src="http://video2.servicecanada.gc.ca/video/boew-wet/te-lj-eng.webm" />
    		<source type="video/mp4" src="http://video2.servicecanada.gc.ca/video/boew-wet/te-lj-eng.mp4" />
    		<track src="cpts-lg-en.html" kind="captions" data-type="text/html" srclang="en" label="English" />
    	</video>
    	<button class="btn btn-info cuepoint" data-cuepoint="75s">Cue point - 75s</button>
    	<figcaption>
    		<p>Looking for a Job (<a href="cpts-lg-en.html">Transcript</a>)</p>
    	</figcaption>
    </figure>

#### Video (YouTube)

1. Add a `title` attribute to the `video` element with the value being the title of the video.

2. Add a `source` element to the `video` element with `type="video/youtube"` and the `src` attribute being the URL of the video.

       <source type="video/youtube" src="http://www.youtube.com/watch?v=9znKJqnFuuY" />

   or

       <source type="video/youtube" src="https://youtu.be/9znKJqnFuuY" />

3. If captions are not already included for the video, add the captions using the tools provided by YouTube.

##### Code

    <figure class="wb-mltmd">
    	<video title="Suspect">
    		<source type="video/youtube" src="http://www.youtube.com/watch?v=9znKJqnFuuY" />
    	</video>
    	<figcaption>
    		<p>Suspect</p>
    	</figcaption>
    </figure>

#### Audio

1. Add a `title` attribute to the `audio` element with the value being the title of the audio.
2. Add one or more `source` elements to the `audio` element with the `src` attribute value being the URL of the media file and the `type` attribute being the media file MIME type.
   Note: If you list multiple media sources for the audio, the player will play the first media source file that works (is available, compatible, etc.).

       <source src="http://www.archive.org/download/RideOfTheValkyries/ride_of_the_valkyries_2.mp3" type="audio/mp3" />
       <source src="http://www.archive.org/download/RideOfTheValkyries/ride_of_the_valkyries_2.ogg" type="audio/ogg" />

##### Code

    <figure class="wb-mltmd">
    	<audio title="Ride of the Valkyries">
    		<source src="http://www.archive.org/download/RideOfTheValkyries/ride_of_the_valkyries_2.mp3" type="audio/mp3" />
    		<source src="http://www.archive.org/download/RideOfTheValkyries/ride_of_the_valkyries_2.ogg" type="audio/ogg" />
    	</audio>
    	<figcaption>
    		<p>Ride of the Valkyries</p>
    	</figcaption>
    </figure>

## Configuration options

Option | Description | How to configure | Values
--- | --- | --- | ---
`shareUrl` | Adds a "Share this video" or "Share this audio file" link | Add
    data-wb-mltmd='{"shareUrl": "url"}'
to the element with `class="wb-mltmd"`. | URL URL of the video or audio file to share.

## Events

Event | Trigger | What it does
--- | --- | ---
`wb-init.wb-mltmd` | Triggered manually (e.g., `$( ".wb-mltmd" ).trigger( "wb-init.wb-mltmd" );`). | Used to manually initialize the multimedia player. Note: The multimedia player will be initialized automatically unless the multimedia player markup is added after the page has already loaded.
`wb-ready.wb-mltmd` (v4.0.5+) | Triggered automatically after a multimedia player initializes. | Used to identify which multimedia player initialized (target of the event)
    $( document ).on( "wb-ready.wb-mltmd", ".wb-mltmd", function( event ) {
    });
    $( ".wb-mltmd" ).on( "wb-ready.wb-mltmd", function( event ) {
    });
`wb-ready.wb` (v4.0.5+) | Triggered automatically when WET has finished loading and executing. | Used to identify when all WET plugins and polyfills have finished loading and executing.
    $( document ).on( "wb-ready.wb", function( event ) {
    });

## Source code

Multimedia player source code on GitHub

Date modified:
  2018-04-18