api.md

API and Configuration

• Attributes
• Configuration
  • Standalone
  • MediaElementPlayer
• API
  • Properties
  • Methods
  • Events

Attributes

MediaElement supports the following video/audio tag attributes:

Attribute	Description
autoplay	Specifies that the video will start playing as soon as it is ready
class	Specifies one or more class names for an element (refers to a class in a style sheet)
controls	Specifies that video controls should be displayed (such as a play/pause button etc).
id	Specifies a unique id for an element; if not specified, the plugin will create one automatically
height	Sets the height of the video player in pixels; you can also indicate percentages
loop	Specifies that the video will start over again, every time it is finished
muted	Specifies that the audio output of the video should be muted
poster	Specifies an image to be shown while the video is downloading, or until the user hits the play button. Generally, a PNG or JPEG image. If not specified, the player will use the background color specified in the style sheet
preload	Specifies if and how the author thinks the video should be loaded when the page loads; possible values: auto, metadata or none (recommended)
src	Specifies the URL of the video file; this value can also be indicated with source tags (refer to the Multiple Codecs section for more information)
style	Specifies an inline CSS style for an element
tabindex	Specifies the tabbing order of an element. To avoid the keyboard to focus on this element, use -1; otherwise, 0
title	Specifies extra information about an element
width	Sets the width of the video player in pixels; you can also indicate percentages

The following markup displays all the attributes listed above for more clarity:

<video autoplay controls class="player" id="player1" height="360"
	width="100%" loop muted poster="/path/to/poster.jpg"
	preload="none" src="/path/to/media.mp4"
	style="max-width: 100%" tabindex="0" title="MediaElement">
</video>

Configuration

Standalone

As a standalone library, MediaElement.js can be configured using the following settings.

Parameter	Type	Default	Description
renderers	array	[]	List of the renderers to use
fakeNodeName	string	mediaelementwrapper	Name of MediaElement container
pluginPath	string	build/	Path where Flash shims are located
shimScriptAccess	string	sameDomain	Flag in <object> and <embed> to determine whether to use local or CDN files. Possible values: always (CDN version) or sameDomain (local files)
success	callback		Action(s) that will be executed as soon as the source is loaded; passes 2 arguments: media (the wrapper that mimics all the native events/properties/methods for all renderers) and node (the original HTML video, audio or iframe tag where the media was loaded originally; if html5 is being used, media and node are the basically the same)
error	callback		Action(s) that will be executed if source doesn't load for any reason. Passes same arguments as success
dailymotion	object		See Documentation
dash	object		Accepts debug, drm (object to load protected/licensed streaming; read here for more information) and path parameters to indicate dash.js URL/local path
facebook	object		See Documentation (and a custom lang parameter to indicate the FB SDK language)
flv	object		See Documentation (and a custom path parameter to indicate where to load library)
hls	object		See Documentation (and a custom path parameter to indicate where to load library)
youtube	object		See Documentation; also, a custom nocookie parameter to switch to YouTube's no-cookie URL and imageQuality parameter if user decides to use Image API to load a YouTube poster based on YouTube video ID (possible values: default, hqdefault, mqdefault, sddefault and maxresdefault)

Notes

1. Vimeo and Soundcloud don't need any configuration for now since they are pretty straight forward.
2. To use DRM with M(PEG)-DASH, make sure CORS are configured correctly, and also your site MUST be using SSL.
3. Both success and error will be available for both MediaElement and MediaElementPlayer; however, when using MediaElementPlayer, a third argument is passed: instance, which gives access to the methods associated to the MediaElementPlayer class.
4. When using MediaElementPlayer, error arguments will be: error (the details on the error event), media and node.

MediaElementPlayer

Including the above, MediaElementPlayer object allows the following extra configuration elements.

Parameter	Type	Default	Description
classPrefix	string	mejs__	Class prefix for player elements
poster	string	(empty)	Poster URL that overrides poster attribute
showPosterWhenEnded	boolean	false	When the video is ended, show the poster
showPosterWhenPaused	boolean	false	When the video is paused, show the poster
defaultVideoWidth	number	480	Default width if the <video> width is not specified
defaultVideoHeight	number	270	Default height if the <video> height is not specified
videoWidth	number	-1	If set, overrides <video> width
videoHeight	number	-1	If set, overrides <video> height
defaultAudioWidth	number	400	Default width for audio player if the user doesn't specify
defaultAudioHeight	number	30	Default height for audio player if the user doesn't specify
defaultSeekBackwardInterval	function		Default amount to move back when back key is pressed. Default callback is represented like: function(media) {return (media.duration * 0.05);}
defaultSeekForwardInterval	function		Default amount to move forward when forward key is pressed. Default callback is represented like: function(media) {return (media.duration * 0.05);}
setDimensions	boolean	true	Set dimensions via JS instead of CSS
audioWidth	number	-1	Width of audio player
audioHeight	number	-1	Height of audio player
startVolume	number	0.8	Initial volume when the player starts (overrided by user cookie); represented with float values
loop	boolean	false	Whether to loop or not media
autoRewind	boolean	true	Rewind to beginning when media ends
enableAutosize	boolean	true	Resize to media dimensions
timeFormat	string	(empty)	Time format to use. Default: 'mm:ss'. Supported units: h: hour, m: minute, s: second and f: frame count. If use 2 letters, 2 digits will be displayed (hh:mm:ss)
alwaysShowHours	boolean	false	Force the hour marker (##:00:00)
showTimecodeFrameCount	boolean	false	Whether to show frame count in timecode (##:00:00:00)
framesPerSecond	number	25	Used when showTimecodeFrameCount is set to true
autosizeProgress	boolean	true	Automatically calculate the width of the progress bar based on the sizes of other elements
alwaysShowControls	boolean	false	Hide controls when playing and mouse is not over the video
hideVideoControlsOnLoad	boolean	false	Display the video control when media is loading
hideVideoControlsOnPause	boolean	false	Display the video controls when media is paused
clickToPlayPause	boolean	true	Enable click video element to toggle play/pause
controlsTimeoutDefault	number	1500	Time in ms to hide controls
controlsTimeoutMouseEnter	number	2500	Time in ms to trigger the timer when mouse moves
controlsTimeoutMouseLeave	number	1000	Time in ms to trigger the timer when mouse leaves
iPadUseNativeControls	boolean	false	Force iPad's native controls
iPhoneUseNativeControls	boolean	false	Force iPhone's native controls
AndroidUseNativeControls	boolean	false	Force Android's native controls
features	array	[...]	List of features/plugin to use in the player; some will be included in the control bar (by default IN STRICT ORDER: playpause, current, progress, duration, tracks, volume, fullscreen)
useDefaultControls	boolean	false	If set to true, all the default control elements listed in features above will be used, and the features will append any other plugins indicated in features. This approach is used mostly when adding more plugins WITHOUT modifying the elements in the control bar in any capacity
isVideo	boolean	true	Only for dynamic purposes
stretching	string	auto	Stretching modes for video player. If auto is set, player will try to find the max-width and max-height CSS styles to turn it into responsive mode; otherwise, will set the dimensions specified in the tag (same as setting this option as none). The fill mode will try to use the available space to make the video fit and, when window is resized, it will crop the dimensions to center it according to the available space.
enableKeyboard	boolean	true	Turns keyboard support on and off for this instance
pauseOtherPlayers	boolean	true	When focused player starts, it will pause other players
secondsDecimalLength	number	0	Number of decimal places to show if frames are shown
customError	string/callback	null	If error happens, set up customized HTML message through a string or a function. The function has 2 parameters: media (the wrapper that mimics all the native events/properties/methods for all renderers) and node (the original HTML video, audio or iframe tag where the media was loaded originally)
keyActions	array	[...]	Keyboard actions to trigger different actions. Accepts array of objects in format: {keys: [1,2,3...], action: function(player, media) { ... }}. To see the entire list, please check /src/js/mediaelementplayer-player.js
duration	number	-1	Start point to detect changes on media time duration
timeAndDurationSeparator	string	<span> &#124; </span>	Separator between the current time and the total duration of media being played
hideVolumeOnTouchDevices	boolean	true	Touch devices (specially mobile devices) have different way to handle volume, so no need to display it
enableProgressTooltip	boolean	true	Enable/disable tooltip that shows time popup in progress bar
useSmoothHover	boolean	true	Enable smooth behavior when hovering progress bar (like YouTube's)
forceLive	boolean	false	If set to true, the Live Broadcast message will be displayed and progress bar will be hidden, no matter if duration is a valid number
audioVolume	string	horizontal	Position of volume slider on audio element
videoVolume	string	vertical	Position of volume slider on video element
usePluginFullScreen	boolean	true	Flag to activate detection of Pointer events when on fullscreen mode
useFakeFullscreen	boolean	false	Flag to bypass native capabilities on mobile devices and use the fake-fullscreen mode
tracksAriaLive	boolean	false	By default, no WAI-ARIA live region - don't make a screen reader speak captions over an audio track.
hideCaptionsButtonWhenEmpty	boolean	true	Option to remove the [cc] button when no <track kind="subtitles"> are present
toggleCaptionsButtonWhenOnlyOne	boolean	false	If true and we only have one track, change captions to toggle button
startLanguage	string	(empty)	Automatically turn on a <track> element. Note: Will not work when toggleCaptionsButtonWhenOnlyOne is set to true
slidesSelector	string	(empty)	Selector for slides; could be any valid Javascript selector (#id, .class, img, etc.)
tracksText	string	null	Title for Closed Captioning button for WARIA purposes
chaptersText	string	null	Title for Chapters button for WARIA purposes
muteText	string	null	Title for Mute button for WARIA purposes
unmuteText	string	null	Title for Unmute button for WARIA purposes
allyVolumeControlText	string	null	Title for Volume slider for WARIA purposes
fullscreenText	string	null	Title for Fullscreen button for WARIA purposes
playText	string	null	Title for Play/Pause button for WARIA purposes when media is playing
pauseText	string	null	Title for Play/Pause button for WARIA purposes when media is paused

API

MediaElementPlayer is a complete audio and video player, but you can also use just the MediaElement object which replaces <video> and <audio> with a Flash player that mimics the properties, methods, and events of HTML MediaElement API.

Properties

Property	Description	GET	SET
autoplay	Set or return whether the audio/video should start playing as soon as it is loaded	X	X
buffered	Return a TimeRanges object representing the buffered parts of the audio/video	X
controls	Set or return whether the audio/video should display controls (like play/pause etc.)	X	X
currentSrc	Return the URL of the current audio/video	X
currentTime	Set or return the current playback position in the audio/video (in seconds)	X	X
duration	Return the length of the current audio/video (in seconds); to determine it without playing media, preload="auto" must be set	X
ended	Return whether the playback of the audio/video has ended or not	X
error	Return a MediaError object representing the error state of the audio/video	X
loop	Set or return whether the audio/video should start over again when finished	X	X
muted	Set or returns whether the audio/video is muted or not	X	X
paused	Return whether the audio/video is paused or not	X
readyState	Return the current ready state of the audio/video	X
seeking	Return whether the user is currently seeking in the audio/video	X
src	Set or return the current source of the audio/video element	X	X
volume	Set or return the volume of the audio/video	X	X

Methods

Method	Description
load()	Reload the audio/video element; also, it is used to update the audio/video element after changing the source or other settings
play()	Start playing the audio/video
pause()	Halt (pauses) the currently playing audio or video
stop()	Only present to support Flash RTMP streaming in MediaElementPlayer. The equivalent for other scenarios is pause
remove()	Destroy the video/audio player instance
canPlayType(type)	Determine whether current player can/cannot play a specific media type; type is MIME type and each renderer has a whitelist of them
setPlayerSize (width, height)	Set player's width and height also considering the stretching configuration
setPoster (url)	Add a image tag with the poster's url inside the player's layer; you can pass an empty string to clear the poster
setMuted (muted)	Mute/unmute the player; muted is a boolean value
setCurrentTime (time)	Set a new current time for the player; time is either an integer or float number, and if negative, it will start from zero.
getCurrentTime ()	Retrieve the current time of the media being played
setVolume (volume)	Set a volume level for the player; volume is a number between 0 and 1
getVolume ()	Retrieve the current volume level of the media being played
setSrc (src)	Set a new URL/path for the player; each renderer has a different mechanism to set it
getSrc ()	Retrieve the media URL/path currently being played; each renderer has a different mechanism to return it

Events

Event	Action(s) executed when...
loadedmetadata	Meta data (like dimensions and duration) are loaded
progress	Browser is in the process of getting the media data
timeupdate	The playing position has changed (like when the user fast forwards to a different point in the media)
seeking	The seeking attribute is set to true indicating that seeking has started
seeked	The seeking attribute is set to false indicating that seeking has ended
canplay	A file is ready to start playing (when it has buffered enough to begin)
play	The media is ready to start playing
playing	The media actually has started playing
pause	The media is paused either by the user or programmatically
ended	The media has reach the end (a useful event for messages like "thanks for listening")
volumechange	Volume is changed (including setting the volume to "mute")
captionschange	The media has detected that captions have changed

---

Back to Main