Saturday, October 1, 2011

jQuery Media Plugin

Overview

The jQuery Media Plugin supports unobtrusive conversion of standard markup into rich media content. It can be used to embed virtually any media type, including Flash, Quicktime, Windows Media Player, Real Player, MP3, Silverlight, PDF and more, into a web page. The plugin converts an element (usually an <a>) into a <div> which holds the object, embed or iframe tags neccessary to render the media content. For example, running this script:
$('.media').media();
For this markup:
<a class="media" href="sample.mov">My Quicktime Movie</a> 
<a class="media" href="sample.swf">My Flash Movie</a> 
<a class="media" href="sample.wma">My Audio File</a> 
will result in this1:
<div class="media"> 
    <object codebase="http://www.apple.com/qtactivex/qtplugin.cab" 
        classid
="clsid:02BF25D5-8C17-4B23-BC80-D3488ABDDC6B"> 
        <param name="src" value="sample.mov"> 
        <embed src="sample.mov" 
            pluginspage
="http://www.apple.com/quicktime/download/"></embed> 
    </object> 
    <div>My Quicktime Movie</div> 
</div> 
 
<div class="media"> 
    <object codebase="http://fpdownload.macromedia.com/pub/shockwave/cabs/flash/swflash.cab#version=7" 
        classid
="clsid:d27cdb6e-ae6d-11cf-96b8-444553540000" 
        type
="application/x-oleobject"> 
        <param name="src" value="sample.swf"> 
        <embed src="sample.swf" 
            type
="application/x-shockwave-flash" 
            pluginspage
="http://www.adobe.com/go/getflashplayer"></embed> 
    </object> 
    <div>My Flash Movie</div> 
</div> 
 
<div class="media"> 
    <object codebase="http://www.apple.com/qtactivex/qtplugin.cab" 
        classid
="clsid:6BF52A52-394A-11d3-B153-00C04F79FAA6" 
        type
="application/x-oleobject"> 
        <param name="url" value="sample.wma"> 
        <embed src="sample.wma" 
            type
="application/x-mplayer2" 
            pluginspage
="http://www.microsoft.com/Windows/MediaPlayer/"></embed> 
    </object> 
    <div>My Audio File</div> 
</div> 
 

Options

The jQuery Media Plugin supports many options which can be used to control how the media is rendered and/or behaves. Options can be provided using an options object or by using the jQuery Metadata Plugin.

Global Defaults

The following global default settings are provide by the plugin: // global defautls; override as needed
$.fn.media.defaults = {
    preferMeta:    1,         // true if markup metadata takes precedence over options object
    autoplay:      0,         // normalized cross-player setting
    bgColor:       '#ffffff'// background color
    params:        {},        // added to object element as param elements; added to embed element as attrs
    attrs:         {},        // added to object and embed elements as attrs
    flashvars:     {},        // added to flash content as flashvars param/attr
    flashVersion:  '7',       // required flash version

    // default flash video and mp3 player
    // @see: http://jeroenwijering.com/?item=Flash_Media_Player
    flvPlayer:     'mediaplayer.swf',
    mp3Player:     'mediaplayer.swf',

    // Silverlight options
    // @see http://msdn2.microsoft.com/en-us/library/bb412401.aspx
    silverlight: {
        inplaceInstallPrompt: 'true'// display in-place install prompt?
        isWindowless:         'true'// windowless mode (false for wrapping markup)
        framerate:            '24',   // maximum framerate
        version:              '0.9',  // Silverlight version
        onError:              null,   // onError callback
        onLoad:               null,   // onLoad callback
        initParams:           null,   // object init params
        userContext:          null    // callback arg passed to the load callback
    }
}; 
Any global settings can be explicitly overridden by simply changing its value. For example: // change default flash player
$.fn.media.defaults.flvPlayer = 'myCoolPlayer.swf';
They can also be overridden by passing an options object to the media method or by adding metadata to the markup and using the metadata plugin.

Using an Options Object

This example shows how to use the options object to set the media dimensions and to enable autoplay/autostart for all media: $('.media').media( { width: 400, height: 300, autoplay: true } ); 

Advanced Example - Options Object

Markup: <a href="myMovie.mov" class="media">Watch my movie!</a>  Script: $('.media').media({
    width:     450,
    height:    250,
    autoplay:  true,
    src:       'myBetterMovie.mov',
    attrs:     { attr1:  'attrValue1',  attr2:  'attrValue2' },  // object/embed attrs
    params:    { param1: 'paramValue1', param2: 'paramValue2' }, // object params/embed attrs
    caption:   false // supress caption text
}); 
Result1: <div class="media">
    <object width="450" height="250" attr1="attrValue1" attr2="attrValue2"
        codebase
="http://www.apple.com/qtactivex/qtplugin.cab"
        classid
="clsid:02BF25D5-8C17-4B23-BC80-D3488ABDDC6B">
        <param name="src"      value="myBetterMovie.mov">
        <param name="autoplay" value="true">
        <param name="param1"   value="paramValue1">
        <param name="param2"   value="paramValue2">
        <embed width="450" height="250" src="myBetterMovie.mov" autoplay="true"
            attr1
="attrValue1" attr2="attrValue2" param1="paramValue1" param2="paramValue2"
            pluginspage
="http://www.apple.com/quicktime/download/" > </embed>
    </object>
</div> 



Using the Metadata Plugin

This example shows how to use the metadata plugin to set the media dimensions and to enable autoplay/autostart for all media:
<script type="text/javascript" src="jquery.metadata.js"></script> 
 
... 
 
<a class="media {width: 400, height: 300, autoplay: true}" href="sample.mov">My Quicktime Movie</a> 
<a class="media {width: 400, height: 30,  autoplay: true}" href="sample.wma">My Audio File</a> 

Advanced Example - Metadata Plugin

Markup:
<a href="myMovie.wmv" 
   class
="media {width: 450, height: 250, caption: false, attrs: { attr1: 'attrValue1' } }"> 
   Watch my movie!</a> 
Script:
$('.media').media(); 
Result1:
<div class="media"> 
    <object width="450" height="250" attr1="attrValue1" 
        type
="application/x-oleobject" 
        classid
="clsid:6BF52A52-394A-11d3-B153-00C04F79FAA6"> 
        <param name="url"       value="myMovie.wmv"> 
        <param name="autostart" value="0"> 
        <embed width="450" height="250" src="myMovie.wmv" 
            autostart
="0" attr1="attrValue1" type="application/x-mplayer2" 
            pluginspage
="http://www.microsoft.com/Windows/MediaPlayer/" > </embed> 
    </object> 
</div> 
[1] Note that the plugin generates either <object> or <embed> tags as necessary for the platform; not both.

The 'src' Option

The src option identifies the location of the media file. There is no default value provided in the global defaults. If a src option is not explicitly provided then the Media Plugin will use the value of the href or src attribute of the element.

The 'autoplay' Option

The Media Plugin normalizes the "autoplay" setting so that it can be used consistently across players2. Rather than having to remember that Windows Media Player and Real Player use an attribute called autostart while Flash and Quicktime use autoplay, the Media Plugin lets you always use an autoplay option and handles the renaming automatically.


Players and Formats

The Media Plugin provides default mappings of file formats to media players. They are as follows:
PlayerFile Formats
Quicktimeaif,aiff,aac,au,bmp,gsm,mov,mid,midi,mpg,mpeg,mp4,m4a,psd,qt,qtif,qif,qti,snd,tif,tiff,wav,3g2,3pg
Flashflv, mp3, swf
Windows Media Playerasx, asf, avi, wma, wmv
Real Playerra, ram, rm, rpm, rv, smi, smil
Silverlightxaml
iframehtml, pdf

mediaplayer.swf

As shown in the table above, the MP3 file format is mapped to use Flash by default. The global default setting of $.fn.media.defaults.mp3Player identifies the Flash player for MP3 media as mediaplayer.swf. This file is the Media Player from Jeroen Wijering. It's a very nice little player for both MP3 media and Flash video. You can download it from here.

SWFObject

The embedding of Flash content can be aided with swfobject.js but this file is not required. If swfobject.js is loaded, the Media Plugin will use it. If it's not loaded then the Media Plugin will generate object/embed tags with its default logic (with a little extra muscle to handle flashvars). More information about swfobject.js can be found at http://code.google.com/p/swfobject/
Note: Both swfobject v1.5 and v2 are supported.

iframe Player

An iframe "player" is just a normal iframe. By default the PDF and HTML file types are mapped to the iframe player and so they are displayed in an iframe rather than an object/embed element.

Adding or Reassigning Format Mappings

Adding a new format mapping, or reassigning an existing one, is a trivial operation and is done with the help of the plugin's mapFormat method. For example, to map MP3 files to use Quicktime, rather than Flash, simply add the following to your script:
$.fn.media.mapFormat('mp3','quicktime');
The available player names are: quicktime, flash, realplayer, winmedia, silverlight and iframe. When remapping formats, make sure you map to a player that can play the given file type. For reference, Wikipedia has a comprehensive list of player/format compatibility.

Media Plugin API

The Media Plugin provides three public methods.
media(options, fn1, fn2)
Converts the matched set of elements to <div> elements which contain rich media. The media method accepts three arguments, all of which are optional.
optionsan object literal that is used to override the global defaults.
fn1callback function which is passed the original element and the options, before conversion to media
fn2callback function which is passed the original element, the new <div> element and the options
Chainable: Yes. Example:
$('#myMedia').media();
mapFormat(type, player)
Associates a media type with a specific media player. This can be used to override a default mapping or to add a new media type.
typeany media type, such as swf, mov, mp3, etc
playerone of: flash, quicktime, realplayer, silverlight, winmedia or iframe
Chainable: No. Example:
$.fn.media.mapFormat('mp3''quicktime');