jMediaelement API

jMediaelement extends jQuery with a lot of extra methods to let you control your embedded media, without bothering you, which plugin/backend is currently in use. Additionally it fires some interesting events, which you can bind to. This gives you the power to add your own feature set.

All unified methods are called on the native HTML5 media element and all unified events are fireing from the media element.

An example: You have multiple media elements on one site. If someone starts playing a media element and you want to pause all other mediaplayers. Then you should run the following code:

									$(document).bind('play', function(e){
										$('video, audio').not(;

Media Events

All listed events do bubble, except the timechange-event and the progresschange-event (performance reasons). This means, that you can not only use bind/one directly on your media element, but also live and delegate or bind/one on a wrapping element to listen to these events.

Simple events

Simple events just fire the state of the media element. They don't have additional information/data.

  • play

    media was requested to play

  • playing

    media has started to play

  • pause

    media has been paused

  • ended

    media reached end

  • waiting

    media has not enough data and is buffering

  • mediareset

    player is emptied and will load a new media file

Extended events

Extended events provide additional information to the occured event. The additional information/data of the extended events are passed as the second parameter to your event-handler.

									$('video').bind('loadedmeta', function(e, data){
										jmeLog('duration: '+ data.duration);
  • loadedmeta (event, {duration: float in secondes})

    metadata for the current media was loaded. If you bind to the loadedmeta event and the event was just fired earlier, you callback function is called immediately.

  • timechange (event, {time: float in secondes})

    the time position of the media has changed

  • mute (event, {isMuted: boolean})

    The mute state of the player has changed

  • progresschange (event, {relLoaded: float between 0-100})

    The player has loaded some data for the resource

  • volumelevelchange (event, {volumelevel: number between 0-100})

    The volumelevel has changed

  • totalerror

    The player cannot play the given media source

  • jmeBeforeEmbed (event, {options: embedOpts, nodeName: elementName})

    This is called just before jmeEmbed makes a media element cross-browser.

  • jmeEmbed (event, {options: embedOpts, nodeName: elementName})

    This is called immediately after jmeEmbed made a media element cross-browser.

									$('audio, video').bind('volumelevelchange', function(e, data){
										jmeLog('volumelevel: '+ data.volumelevel);

Media Methods

The following methods control directly the behavior of the media player. Similar to jQuerys ready event, these methods are only available when the API is initialzed. To avoid problems you should use the jmeReady-method:

									    //this reffers to the video-element

If you call them earlier, the methods will be queued, till the media API is ready.

With an * signed methods are only available after the loadedmeta-event has fired:

									$('video').bind('loadedmeta', function(){
									    jmeLog( $(this).getDuration() );


Requests a media element to play the current source.



Pauses a media element.



Toggles the play-/pause-state of a media element



Returns true, if a media element is currently playing, false otherwise

												jmeLog( 'isPlaying: '+ $('video').isPlaying() );


Returns the muted-state of a media element or sets the muted-state of a media element.

This method works as a setter and a getter. If you provide a boolean, it will set the mute-state, otherwise it will return the mute state.

												//getting the mute state
												jmeLog( 'muted-state: '+ $('video').muted() );
												//mute the video
												//unmute the video


Toggles the muted-state of a media element.

												//toggle muted-state of all audio elements


Returns the current volumelevel or sets the volume-level of a media element.

This method works as a getter and a setter. If you provide a number (between 0-100) as the first argument, it will set the volume, otherwise it will return the current volumelevel.

												//get the volume level
												jmeLog( 'volume-level: '+ $('video').volume() );
												//set volume to 50


Returns or sets the currentTime as float in seconds for a media element.

currentTime works as a getter and a setter. If you call method with a float as first argument the media element will seek to this position in seconds, otherwise it returns the time-position in seconds.

												jmeLog( 'position: '+ $('video').currentTime() );
												//set currentTime to 10 seconds

Note: Altough setting the currentTime works on most devices, before metadata was loaded, you can not be sure of it. Please wait till loadedmeta event occured before setting currentTime.


Returns the formatted currentTime in mm:ss.

												jmeLog( 'position: '+ $('video').getFormattedTime() );

.relCurrentTime()* [time]

Returns or sets the currentTime/duration on a 0-100 basis

												jmeLog( 'position: '+ $('video').relCurrentTime() );
												//skip half of the video


Returns the duration of a media element in float as seconds.

												jmeLog( 'position: '+ $('video').getDuration() );


Returns the formatted duration of a media element in mm:ss

												jmeLog( 'position: '+ $('video').getFormattedDuration() );


jmeReady takes a callback function and will execute this function, when the API of the media element is ready.

If normal methods are used, they are automatically queued, if the media element is not ready. This is fine for setting the state (i.e.: .muted(true)). But if you want to get the state at the beginning, you should use jmeReady.

													jmeLog( 'muted-state: '+ $(this).muted() );

.loadSrc() [media-srces, poster-src, media-label]

Loads new media-srces and a poster-frame into the media element.

												//load new audio sources into the audio-element
												//and start playing
													.loadSrc( [
													] )

You can also use one file as a string

												$('video').loadSrc( 'path/my-video.mp4' );

You can also use the poster-src argument to load a new poster-frame

												//new video with a new poster
												$('video').loadSrc( 'path/my-video.mp4', 'path/my-poster.jpg' );

If you don´t provide the poster-src argument, but the poster-attribute is still defined in the markup, this source will be used as a poster.

If you want to delete the poster-attribute, you can simply pass false.

												$('video').loadSrc( 'path/my-video.mp4', false );

The code above is equivalent to the following code.

													.attr('srces', 'path/my-video.mp4')
													.loadSrc(  )

With jMediaelement it is extremly easy to create pre rool-/post rool ads or playlist.

													//wait till audio playback is ended...
													.one('ended', function(){
														// then load new source
															.loadSrc( [
															] )
															// and play

The mediaLabel parameter changes the Content of your media-label-element or its media-name-element.


attr methods are always called through jQuery´s attr-method. Pure attr-methods are working directly on the DOM and are used to configure the media-player behavior. They work as getter and setter methods.

									//toggle the loop property of the video element
									$('video').attr('loop', !$('video').attr('loop') );


Sets or gets the autoplay property of a media element

If autoplay is set to true before you have called jmeEmbed or loadSrc. The current media source will be played automatically.

												//set the autoplay property to true
												$('audio').attr('autoplay', true);
												//set the autoplay property to false
												$('audio').attr('autoplay', false);
												//get the autoplay property
												jmeLog( $('audio').attr('autoplay') );


Gets or sets the loop property of a media element.

If loop is set to true before a media element finishes playing, the playback starts again after the ended-event.

												//set the loop property to true
												$('audio').attr('loop', true);
												//set the loop property to false
												$('audio').attr('loop', false);
												//get the loop property
												jmeLog( $('audio').attr('loop') );


Gets or sets the controls-property of a media element.

Currently this attribute is only taken into account, before you have called the jmeEmbed-method.


Sets or gets the src-property of an media element or a source element.

The src-property will always return an absolute path, even if you have used a relative path.


Sets or gets the path to your poster

The poster attribute always returns a absolute path, even if you have used a relative path.


Gets or sets all media sources for a media element (see media-srces).

The srces attribute is a "meta"-attribute and makes it really easy to work with multiple sources for a media element.

Setting media-srces with the srces-attr-method will first remove all found source elements and src attributes and then set the source.

Example: The following HTML

												<audio class="my-audio" src="my-source.mp3"></audio>

will be transormed by this code...


to the following HTML:

												<audio class="my-audio">
													<source src="my-mp3.mp3" />
													<source src="my-ogg.ogg" />

Getting the srces will always return an array of media-src object. Even if used on a media element with only one src-attribute.

												<audio class="my-audio" src="my-source.mp3"></audio>
												// will return 
													[ {
														src: 'absolute-path/my-source.mp3'


media-src/media-srces is a string, an object or an array of these representing all media resources a video-/audio- element can have.

Single media-src as string


Single media-src as object

A media-src can be written as an object. The src-property is required, the media and the type-properties are optional

										src: 'path-to/my-video.mp4', 
										type: 'video/mp4',
										media: 'only screen and (max-width: 490px)'

Multiple media-srces

Multiple media-srces are defined with an array:

											src: 'path-to/my-video.mp4', 
											type: 'video/mp4'
											src: 'path-to/my-video.ogg', 
											type: 'video/ogg'

You can also mix string and object in a media-srces array:

											src: 'path-to/my-video.ogg', 
											type: 'video/ogg'