‹‹ homejQuery 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>
[1] Note that the plugin generates either <object> or <embed> tags as necessary for the platform; not both.

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>
[1] Note that the plugin generates either <object> or <embed> tags as necessary for the platform; not both.

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.

[2] Note that not all content is written to respect the autoplay setting.

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');

Demos

Video/Flash Demo

Audio Demo

sIFR Demo

Silverlight Demo

Misc Demo (pdf, html)

Frequently Asked Questions

What version of jQuery is required?
The Media Plugin requires jQuery version 1.1.2 or later.
What happend to the mediaBox functionality???
Simply put, other plugins do it better.
What media players are supported?
Support for the following embedded media players is provided:
  • Flash
  • Quicktime
  • Windows Media Player
  • Microsfot Silverlight
  • Real Player
  • iframe
What video formats are supported?
Any type supported by the players listed above, including:
asx, asf, avi, flv, mov, mpg, mpeg, mp4, qt, ra, smil, swf, wmv, 3g2, 3gp
What audio formats are supported?
Any type supported by the players listed above, including:
aif, aac, au, gsm, mid, midi, mov, mp3, m4a, snd, ra, ram, rm, wav, wma
What other file types are supported?
Any type supported by the players listed above, including:
bmp, html, pdf, psd, qif, qtif, qti, tif, tiff, xaml
How do I add flashvars?
You can add flashvars using an options object: 
$('#myMedia').media({
    flashvars: {
        myVar1: 'myValue1',
        myVar2: 'myValue2'
    }
});
or by using markup metadata: 
<a class="{ flashvars: { myVar1: 'myValue1', myVar2: 'myValue2' } }">My Media</a>
You can also change the flashvars global defaults: 
$.fn.media.defaults.flashvars = { myVar1: 'myValue1', myVar2: 'myValue2' };
How do I add <param> elements?
You can add params using an options object: 
$('#myMedia').media({
    params: {
        myParam1: 'myValue1',
        myParam2: 'myValue2'
    }
});
or by using markup metadata: 
<a class="{ params: { myParam1: 'myValue1', myParam2: 'myValue2' } }">My Media</a>
You can also change the params global defaults: 
$.fn.media.defaults.params = { myVar1: 'myValue1', myVar2: 'myValue2' };
How do I change the player that gets used for a given media type?
Use the mapFormat method. The following example remaps the wav file format to use the Windows Media Player instead of Quicktime: 
$.fn.media.mapFormat('wav', 'winmedia');
See the Players/Formats page for more info.
How do I change the default Flash video player?
The default player for Flash video is a global default. To use a different player just change this setting: 
$.fn.media.defaults.flvPlayer = 'mySnazzyPlayer.swf';
Is the Flash support as extensive as Luke Lutman's Flash plugin?
When used in combination with SWFobject I believe the same capabilities are provided. Without swfobject.js loaded the Media Plugin lacks the Flash detection capabilities found in Luke's plugin. If you are only using Flash media then Luke's plugin is an excellent choice.
What other Media Plugins are available?
After writing this plugin I came across jmedia by Christoph Liell which looks pretty cool. Check it out. Or check out the jQuery Plugin Page for a full list of plugins.

Download

jQuery Media Plugin is available here: jquery.media.js or from the plugin's Github repository.

Support

Support for the Media Plugin is available through the jQuery Google Group. This is a very active group to which many jQuery developers and users subscribe.

The Media Plugin and this documentation are the work of Mike Alsup.