Tunes

HTML5 <audio> and <video> playlists

Tunes (formerly cue) is an opensource jQuery plugin that uses JSON and data attributes to make HTML5 audio and video playlists possible.

Goals

1. Provide semantic storage and performant access to playlist data.
2. Provide succinct semantic controls that can be styled in CSS.
3. Be minimal, but extensible.

Types

Compatibility: the more filetypes, the better

Full coverage in modern browsers requires 2+ types

• audio: Use .mp3 and .ogg (Converters: media.io)
• video: Use .mp4 and .webm (Converters: ffmpeg, Miro (issues))

URIs

• To simplify the examples, most of the file URIs shown are relative. In production you probably want to use full URIs.
• AJAX-loaded .json files must be on the same domain due to cross-domain restrictions.

API (0.6)

[data-tunes]

[data-tunes] is the data attribute in which the JSON playlist is stored. It is designed to be placed on a container element that holds the media element and related informational elements such as credits or captions. It can contain inline JSON or the filename of a .json file to load via AJAX. Inline JSON is more performant and more stable than loading AJAX requests.

<div data-tunes="playlist.json">
    <video controls>
        <source src="default.mp4" type="video/mp4">
        <source src="default.webm" type="video/webm">
    </video>
</div>

[data-tunes-insert]

[data-tunes-insert] makes it possible to insert values from the properties in your media object into your HTML.

<figure data-tunes="playlist.json">
    <video controls>
        <source src="default.mp4">
        <source src="default.webm">
    </video>
    <figcaption data-tunes-insert="caption">
        Caption for the default video. The value of the "caption"
        property gets inserted here when the video changes.
    </figcaption>
</figure>

[data-tunes-attr]

[data-tunes-attr] makes it possible to update arbitrary HTML attributes based on the properties in your media object. It takes a JSON object that maps attribute names to the property names from the media object that should fill them.

<figure data-tunes="playlist.json">
    <video controls>
        <source src="default.mp4">
        <source src="default.webm">
        <p>
            To watch this video please <a href="http://browsehappy.com">updgrade your browser</a>
            or <a href="default.mp4" data-tunes-attr='{"href": "mp4"}'>download the .mp4</a>
        </p>
    </video>
</figure>

JSON

The format for the JSON playlist data is an array of media objects containing data about each media file. Please validate your JSON to prevent syntax errors. The media objects provide several capabilities. A simple <video> example would look something like this:

[{
    "mp4": "identity.mp4"
  , "webm": "identity.webm"
 },{
    "mp4": "supremacy.mp4"
  , "webm": "supremacy.webm"
 },{
    "mp4": "ultimatum.mp4"
  , "webm": "ultimatum.webm"
}]

Alternate syntax: You can achieve the same as above by setting the src property to an array of URIs. If you mix the 2 syntaxes, the named extension props take precedence over the src prop. In either case tunes will choose the most appropriate file based on the feature detection.

[{
    "src": ["identity.mp4", "identity.webm"]
 },{
    "src": ["supremacy.mp4", "supremacy.webm"]
 },{
    "src": ["ultimatum.mp4", "ultimatum.webm"]
}]

In your media objects, you can include whatever extra properties you want for use with [data-tunes-insert] and/or [data-tunes-attr]. The purpose of these attributes is to enable you to include relavent credits, captions, or links.

[{
    "mp4": "identity.mp4"
  , "webm": "identity.webm"
  , "title": "The Bourne Identity"
  , "imbd": "http://www.imdb.com/title/tt0258463/"
 },{
    "mp4": "supremacy.mp4"
  , "webm": "supremacy.webm"
  , "title": "The Bourne Supremacy"
  , "imdb": "http://www.imdb.com/title/tt0372183/"
 },{
    "mp4": "ultimatum.mp4"
  , "webm": "ultimatum.webm"
  , "title": "The Bourne Ultimatum"
  , "imdb": "http://www.imdb.com/title/tt0440963/"
}]

MIME types

To play media files, your server must recognize the correct MIME types.

Make sure your .htaccess includes these rules (via H5BP)

# MIME types for audio and video files
AddType audio/mp4                      m4a f4a f4b
AddType audio/ogg                      oga ogg
AddType video/mp4                      mp4 m4v f4v f4p
AddType video/ogg                      ogv
AddType video/webm                     webm
AddType video/x-flv                    flv

Fallbacks

Fallbacks and graceful degradation for pre-HTML5 browsers are possible through smart use of [data-tunes-insert] and [data-tunes-attr]. It's a vanilla diet approach and no Flash is used.

Troubleshoot

1. Does your JSON validate? Use: jsonlint.com
2. Does your HTML validate? Use: html5.validator.nu
3. Did jQuery load? Is it version 1.7 or higher? jQuery must run before tunes.
4. Are there any JavaScript errors in the console?
5. Is your server configured to serve the correct MIME types? See section above.
6. Are your URIs correct? AJAX-loaded playlists must be on the same server.
7. Ask @ryanve or submit an issue.

Dependencies

Requires jQuery 1.7+ or an ender build that implements compatible versions of:

• $()
• $.ajax() *needed only for AJAX playlists
• $.contains()
• $.get() *needed only for AJAX playlists
• $.fn.on()
• $.fn.addClass()
• $.fn.attr()
• $.fn.children()
• $.fn.empty()
• $.fn.find()
• $.fn.html()
• $.fn.insertAfter()
• $.fn.ready()
• $.fn.removeAttr()
• $.fn.removeClass()

Resources

• html5rocks.com: HTML5 Video
• dev.opera.com: HTML5 Video and Audio
• MDN: Media Formats
• MDN: Media Events
• MDN: HTMLMediaElement

License: MIT

Copyright (C) 2013 by Ryan Van Etten