Tunes
<audio>
and <video>
playlists
HTML5 jQuery plugin that uses JSON and data attributes to make HTML5 audio and video playlists possible.
Tunes (formerly cue) is an opensourceGoals
- Provide semantic storage and performant access to playlist data.
- Provide succinct semantic controls that can be styled in CSS.
- 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.
0.6)
API ([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.
[data-tunes-insert]
[data-tunes-insert]
makes it possible to insert values from the properties in your media object into your HTML.
Caption for the default video. The value of the "caption" property gets inserted here when the video changes.
[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.
To watch this video please updgrade your browser or download the .mp4
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:
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.
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.
MIME types
To play media files, your server must recognize the correct MIME types.
.htaccess
includes these rules (via H5BP)
Make sure your # MIME types for audio and video filesAddType audio/mp4 m4a f4a f4bAddType audio/ogg oga oggAddType video/mp4 mp4 m4v f4v f4pAddType video/ogg ogvAddType video/webm webmAddType 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
- Does your JSON validate? Use: jsonlint.com
- Does your HTML validate? Use: html5.validator.nu
- Did jQuery load? Is it version 1.7 or higher? jQuery must run before tunes.
- Are there any JavaScript errors in the console?
- Is your server configured to serve the correct MIME types? See section above.
- Are your URIs correct? AJAX-loaded playlists must be on the same server.
- 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
MIT
License:Copyright (C) 2013 by Ryan Van Etten