jMediaelement control-element documentation

jMediaelement uses a flexible technique, to create custom stylable, WAI-Aria enhanced control elements without dictating a specific markup. To achieve this, the script has to detect, which control-behavior it has to add to your markup and which of possible multiple media elements is controlled by this markup.

This is achieved by behavior-classes and a common wrapper element/a data-controls attribute.

The method to add control-behavior to your markup, is called jmeControl.

Example: The behavior-class for a play-/pause button is called play-pause. In our example the video-element and our play-pause button are wrapped by a div-container with the class .media-player

									<div class="media-player">
									    <video src="my-video.mp4"></video>
									    <button class="play-pause">play / pause</button>
									</div>
								

Then we have to call jmeControl on this wrapper-element:

									$('div.media-player').jmeControl();
								

If you want to add other controls, for example a mute-unmute button, we only have to add another element with the class mute-unmute:

									<div class="media-player">
									    <video src="my-video.mp4"></video>
									    <button class="play-pause">play / pause</button>
										<button class="mute-unmute">mute / unmute</button>
									</div>
								

This let's you write your markup, how you want, but helps you to add the right control-behavior for your jMediaelement

You can compare this technique to a possible upcomming HTML5.1 / HTML6 feature for creating custom stylable media control elements. An example:

									<player>
										<video src="my-video.webm" poster="my-poster.jpg"></video>
										<button type="play-pause">play / pause</button>
										<label for="time-range">play position</label>
										<input type="time-range" id="time-range" />
										<output type="current-position" />
										<!-- more "HTML6" media control elements -->
									</player>
								

The example above isn't valid HTML5, so jMediaelement uses Classes and the data-* attribute to add valid and custom stylable control elements:

									<div class="player">
										<video src="my-video.webm" poster="my-poster.jpg"></video>
										<button class="play-pause">play / pause</button>
										<div class="timeline-slider">
											<span class="handle-label">video position</span>
										</div>
										<span class="current-position">00:00</span>
										<!-- more jme control elements -->
									</div>
								
									$('div.player').jmeControl();
								

general options of .jmeControl()

jmeControl has three main-options (every control-element/behavior-class can add additional options).

addThemeRoller defauls to true

This option decides wether the script should add jQuery UI Themeroller classes like ‘ui-state-default’ or ‘ui-corner-all’ to your control elements.

												$('div.media-player').jmeControl({
													addThemeRoller: false
												});
											

classPrefix defauls to "" (empty string)

To minimize conflicts with your existing classes, you can specify a prefix for all behavior classes.

												<div class="media-player">
												    <video src="my-video.mp4"></video>
												    <a class="jme-play-pause" href="#">play / pause</a>
													<a class="jme-mute-unmute" href="#">mute / unmute</a>
												</div>
											
												$('div.media-player').jmeControl({
													classPrefix: 'jme-'
												});
											

embed embed options

Options to configure the jmeEmbed-method. jmeControl changes the default embed option 'removeControls' to true.

If you use jmeControl you won't have to additionally use the embed-method (jmeEmbed). To be able to configure your embed-behavior you can use this property. All configuration-options are explained on the embedding-site.

												$('div.media-player').jmeControl({
													embed: {showFallback: true}
												});
											

List of media control elements/behavior-classes

progressbar

The behavior-class progressbar adds jQuery UI Progressbar behavior to the markup, showing the current buffer-progress of your j mediaelement.

												<div class="progressbar"></div>
											

timeline-slider slider-options

The behavior-class timeline-slider adds jQuery UI Slider behavior to your markup, showing and changing the current time position of your jMediaelement.

												 <div class="jme-timeline-slider"></div>
											
video position

All jQuery UI-Options can be configured due to the timeSlider-property.

												$('div.media-player').jmeControl({
												    classPrefix: 'jme-',
												    timeSlider: {
												        animate: true,
												        range: 'min'
												    }
												});
											

volume-slider slider-options

The behavior-class volume-slider adds jQuery UI Slider behavior to your markup, showing and changing the current volume of your jMediaelement.

												 <div class="volume-slider"></div>
											
volume control

All jQuery UI-Options can be configured due to the volumeSlider-property.

												$('div.media-player').jmeControl({
												    volumeSlider: {
												        orientation: 'vertical',
												        range: 'min'
												    }
												});
											

Additional you can use the "mutestate" property (defaults to false). If mutestate is true, the volumeslider is also bound to the mute-state.

												$('div.media-player').jmeControl({
												    volumeSlider: {
												        mutestate: true
												    }
												});
											

or using the markup-API:

												 <div class="volume-slider" data-mutestate="true"gt;</div>
											
volume control

duration

The behavior-class duration adds duration-display behavior to your element. It shows the duration of your jMediaelement in the mm:ss format.

												 <span class="duration"></span>
											

current-time

The behavior-class current-time adds current-time-display behavior to your element. It shows the current time of your jMediaelement in the mm:ss format.

												 <span class="current-time"></span>
											

remaining-time

The behavior-class remaining-time adds remaining-time-display behavior to your element. It shows the remaining time of your jMediaelement in the mm:ss format.

												 <span class="remaining-time"></span>
											

play-pause

The play-pause class adds behavior for toggeling the play/pause-state of your jMediaelement. It also toggles between the classes ui-icon-pause and ui-icon-play.

												<button class="play-pause"><span>play / pause</span></button>
											

mute-unmute

The mute-unmute class adds behavior for toggeling the mute-state of your jMediaelement. It also toggles between the classes ui-icon-volume-off and ui-icon-volume-on.

												 <button class="mute-unmute">mute / unmute</button>
											

media-controlsmediaControls-options

Grouping element for a set of other control elements

This control adds some jQuery UI Themeroller classes and WAI-Aria attributes to your markup.

The media-controls element provides two options

  • dynamicTimeslider (defaults to false)

    Setting this to true, the media-control will calculate the available inner width not consumed by his children and will automatically set the width of the timeline-slider to the availabel width.

    This makes it a lot easier to style controls over different sized columns.

  • timeSliderAdjust (defaults to 0)

    Only effects if dynamicTimeslider is set to true. Adjustes the calculated width by the provided number.

  • 													$('div.media-player').jmeControl({
    													    mediaControls: {
    													        dynamicTimeslider: true,
    															//deal with different subpixel rendering:
    													        timeSliderAdjust: -3
    													    }
    													});
    												

media-state click-behavior

A visual element representing the current state of the media element.

This control switches between different state- and api-classes which represent the current state or used api of the media element.

State Classes:

  • idle: media element is in paused or ended state
  • totalerror: media element can not play the current source
  • playing: media element is currently playing
  • waiting: media element has not enough data to play or seek

API Classes:

  • nativ: media element uses the native HTML5 element to play
  • jwPlayer: media element uses JW-Player (Flash-Plugin) to play

Due to the fact, that the media-state control is commonly used as an video-overlay, you can specify a default click behavior, which defaults to 'togglePlay'.

												$('div.media-player').jmeControl({
												    mediaState: {
												        click: 'play' // false || togglePlay || play || toggleMuted
												    }
												});
											
												 <div class="media-state"></div>
											

media-label

The name of your media player. Good for accessibility.

This media-label element will label the common wrapper element.

We suggest that you use both a "role"-name (i.e. audioplayer/videoplayer) and a media-name.

												 <span class="media-label">videoplayer: big buck bunny</span>
											

If you use the loadSrc-method with the mediaName-parameter and only want to change the media-name and not the role-name. Wrap your media-name into an element with the class 'media-name'.

												 <span class="media-label">
												 	videoplayer: <span class="media-name">big buck bunny</span>
												</span>
											

fallback

A element that serves as a fallback message. The fallback element is always a descendant-element of your media element.

Using this markup will override the showFallback-option by the jmeEmbed-method.

												 <video src="my-video.mp4">
												 	<p class="fallback">
												 		Please, install flash
												 	</p>
												 </video>
											

general Informations about some controls

Toggle Buttons (play-pause, mute-unmute)

Toggle buttons always toggle the state of the jMediaelement and reflect this state with toggleing between two classes. Additionally, if you provide a text or a title wich is seperated with / or | it will also toggle this text.

If you want to generate UI Themeroller conform markup, you have to use the class 'ui-icon' and the jme-specific class 'button-text'.

									<button class="mute-unmute"><span class="ui-icon"></span> <span class="button-text">mute / unmute</span></button>
								

Some accessibility information: If you don't use a button element for your toggle buttons (for better cross-browser-styling). jmeControl will automatically add WAI-Aria attributes to make your buttons more accessible.

The follwoing code for example:

									<span class="mute-unmute">mute / unmute</span>
								

will be automatically transformed to the following markup

									<span role="button" tabindex="0" class="mute-unmute">mute / unmute</span>
								

creating accessible WAI-Aria enhanced sliders

jQuery UI does not provide WAI-Aria conform sliders yet. By using the a11y-slider extension for jQuery UI you can easily add accessiblity to your sliders.

To use the a11y-slider extension simply include the JavaScript file. You will find this file in our utils-folder.

To be accessible you have to label the slider-control yourself, to let the user know what he can achieve with the slider.

									 <div class="timeline-slider">
									 	<span class="handle-label">volume control</span>
									 </div>
								
									/* yes display: none is not only accessible in conjunction with 'aria-labelledby elements', it is recommended */
									 .handle-label {display: none;}
								

Note: We have successfully testet the a11y-slider extension with Jaws 11 using IE8+ and FF 3.5+ and with NVDA 2009.1+ using FF 3.5+. But there are some known unfixable issues with Jaws 10 using IE8.

creating a relationship between a control and the controled media element

There are two possibilities to create a control-relationship, between a control element and his media element.

common wrapper

To create a control media element relationship simply call jmeControl on a common wrapper:

									 <div class="my-common-wrapper">
									 	<video src="my-video.mp4" controls="controls"></video>
										<div class="media-controls">
											<button class="play-pause">play / pause</button>
											<!-- a bunch of additional controls -->
										</div>
									 </div>
								
									 $('div.my-common-wrapper').jmeControl();
								

The common wrapper serves also as a media-state-control with shortcut-support, but without a click behavior.

data-controls attribute

Another way to create a control-relationship is to use the data-controls-attribute. The value of this attribute references the id of the media element.

The data-controls attribute can be used directly on the control-element:

								 	<video id="video-ref" src="my-video.mp4" controls="controls"></video>
									<button data-controls="video-ref" class="play-pause">play / pause</button>
								
									 $('button[data-controls]').jmeControl();
								

... or on a wrapper element:

									<div data-controls="video-ref">
										<button class="play-pause">play / pause</button>
										<button class="mute-unmute">mute / unmute</button>
										<!-- a bunch of additional controls -->
									 </div>
								
									 $('div[data-controls]').jmeControl();
								

Tips for rapid development: UI markup helpers & UI behavior helpers

The freedom to let you write your own control-markup and your own UI behavior gives you a great flexibility, but it comes with a downside:

You have to define your controls your own and you have to add extra UI behavior, if you need.

To reduce this downside, jme comes with some demos as a starting point and some markup and UI helpers.