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 this
1:
<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
}); Result
1:
<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();
Result
1:
<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 players
2. 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:
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. 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. Chainable: No. Example:
$.fn.media.mapFormat('mp3', 'quicktime');
