Skip to content

usage.md

Latest commit

 

History

History
305 lines (233 loc) · 11.3 KB

usage.md

File metadata and controls

305 lines (233 loc) · 11.3 KB

Usage

Initialize player

You can use this as a standalone library if you wish, or just stick with the full MediaElementPlayer.

Standalone

<script>

    var player = new MediaElement('player', {
    	pluginPath: "/path/to/shims/", 
    	success: function(mediaElement, originalNode) {
            // do things
            
        }
    });

</script>

Automatic start

You can avoid running any startup scripts by adding class="mejs__player" to the <video> or <audio> tag. All the player configuration can be added through data-mejsoptions attribute.

<video src="myvideo.mp4" width="320" height="240" 
		class="mejs__player" 
		data-mejsoptions='{"pluginPath": "/path/to/shims/", "alwaysShowControls": "true"}'></video>

Vanilla JavaScript

<script>

    var player = new MediaElementPlayer('player', {
    	pluginPath: "/path/to/shims/", 
    	success: function(mediaElement, originalNode) {
	        // do things
        }
    });
    
</script>

jQuery

<script>

    $('#mediaplayer').mediaelementplayer({
    	pluginPath: "/path/to/shims/", 
    	success: function(mediaElement, originalNode) {
	        // do things
        }
    });

    // To access player after its creation through jQuery use:
    var playerId = $('#mediaplayer').closest('.mejs__container').attr('id');
    // or $('#mediaplayer').closest('.mejs-container').attr('id') in "legacy" stylesheet
    
    var player = mejs.players[playerId];
    
    // With iOS (iPhone), since it defaults always to QuickTime, you access the player directly;
    // i.e., if you wanna exit fullscreen on iPhone using the player, use this:
    var player = $('#mediaplayer')[0];
    player.webkitExitFullScreen();
    
</script>

NPM/Meteor

// To import only MediaElement class
import 'mediaelement/standalone';

// To import only MediaElementPlayer class and $.fn.mediaelementplayer plugin 
// (includes the HTML5 and Flahs renderers ONLY)
import 'mediaelement/player';

// To import all the plugin (you will have access to the MediaElement and MediaElementPlayer classes,
// $.fn.mediaelementplayer plugin, all the native renderers, YouTube and Flash shims)
import 'mediaelement/full';

// To import renderers (i.e., Vimeo)
import 'mediaelement/build/renderers/vimeo';

// To import languages (i.e., Spanish)
import 'mediaelement/build/lang/es';
// Later on the code you need to use mejs.i18n.language('es') to set the language

IMPORTANT: To ensure you can use the $.fn.mediaelementplayer plugin, you will need to import jQuery as well in your bundle like follows:

  1. Create a jquery-global.js file that contains:
'use strict';

import jquery from 'jquery';
window.jQuery = jquery;
window.$ = jquery;
  1. Import the jquery-global.js along with the desired package
'use strict';

import '/path/to/jquery-global';
import 'mediaelement/full'; // or import `mediaelement/player`;

RequireJS

With RequireJS, you will need the following setup if you are planning to use HLS, M(PEG)-DASH or FLV, given the way the packages are bundled.

To make it work, install via NPM any of the external libraries you will need (i.e., HLS.js).

npm install hls.js

In your code, include a shim for the external library and then assign the exported variable to the global scope.

requirejs.config({
    // Other configuration
    shim: {
    	// Other shims
        'path/to/hls': {deps: ['require'], exports: "Hls"},
    }
});

// Later on the code...
require(['path/to/hls'], function (Hls) {
        window.Hls = Hls;

        require(['path/to/mediaelement-and-player'], function (MediaElementPlayer) {

            var player = new MediaElementPlayer('media-id', {
            	// Player configuration
            });
        });
    });

IMPORTANT NOTE: To keep Flash shims working you MUST setup the path where the shims are via pluginPath, and do not forget to add a slash at the end of the string. Please refer to the examples above. In Meteor, the right path to be used is /packages/johndyer_mediaelement/build/;

Use Renderers

After the MediaElement package has been loaded, include any renderer(s) you are planning to use that not part of the main bundle (mediaelement-and-player.js). For example, to include Vimeo and Twitch support:

<script src="/path/to/mediaelement-and-player.min.js"></script>
<script src="/path/to/renderers/vimeo.min.js"></script>
<script src="/path/to/renderers/twitch.min.js"></script>

By default, all the renderers will be called by their IDs and the plugin will try to detect the best one.

However, if you need to use just a subset of renderers in a specific order, you must list their IDs using renderers option when configuring your player.

// Use globally native M(PEG)-DASH renderer first, then Flash shim 
mejs.Renderers.order = ['native_dash', 'flash_dash'];

$('video, audio').mediaelementplayer({
    renderers: ['native_dash', 'flash_dash'], // Use only M(PEG)DASH renderers
    // More configuration
});

MediaElement can call methods from the current renderer's API (if any) by invoking its own API instance, a special object attached to the MediaElement instance. Keep in mind that some methods won't work if they are not bound to an event. An example using native HLS:

$('video').mediaelementplayer({
    pluginPath: '../build/',
    // All the config related to HLS
    hls: {
        debug: true,
        autoStartLoad: false
    },
    
    // More configuration parameters...
    
    success: function(media, node) {
    	
    	// Since it could be that the HLS element is not yet loaded, use a `setInterval()` method to check when 
    	// it's ready and then destroy it; this applies to the native renderers (HLS, DASH and FLV)
    	var interval = setInterval(function () {
        
    		// media.hlsPlayer is the instance of HLS.js in MediaElement
    		// each one of the renderers has a player instance
    		// See `Use of Renderers` above for more information
            if (media.rendererName === 'native_hls' && media.hlsPlayer !== undefined) {
            	
            	// clear interval to stop checking if HLS object is available
                clearInterval(interval);
            	
            	media.hlsPlayer.on(Hls.Events.MEDIA_ATTACHED, function() {
            		// All the code when this event is reached...
                    console.log('Media attached!');
                });
                
                // Manifest file was parsed, invoke loading method
                media.hlsPlayer.on('hlsManifestParsed', function() {
            		// All the code when this event is reached...
            		console.log('Manifest parsed!');
            
                });
                
            	media.hlsPlayer.on(Hls.Events.FRAG_PARSING_METADATA, function (event, data) {
            		// All the code when this event is reached...
            		console.log(data);
                });
            }
            
        }, 500); 
    }
});

Below are listed the renderers with their IDs and player instance to execute other methods from APIs.

Renderer ID API instance Reference MIME Type(s)
Native video/audio html5 --- --- video/mp4, audio/mp4, video/webm, audio/mpeg, audio/mp3, audio/ogg, audio/oga, video/ogg
HLS native native_hls hlsPlayer hls.js API application/x-mpegURL, vnd.apple.mpegURL
M(PEG)-DASH native native_dash dashPlayer dash.js Documentation application/dash+xml
FLV native native_flv flvPlayer flv.js API video/flv
SoundCloud soundcloud_iframe scPlayer SoundCloud Widget API video/soundcloud, video/x-soundcloud
Facebook facebook --- --- video/facebook, video/x-facebook
Vimeo vimeo_iframe vimeoPlayer Vimeo Player API video/vimeo, video/x-vimeo
YouTube youtube_iframe youTubeApi YouTube IFrame Player API video/youtube, video/x-youtube
DailyMotion dailymotion_iframe dmPlayer Dailymotion Player API video/dailymotion, video/x-dailymotion
Twitch twitch_iframe twitchPlayer Twitch Emded API video/twitch, video/x-twitch
Video shim flash_video --- --- video/mp4, video/rtmp, audio/rtmp, rtmp/mp4, audio/mp4
Audio shim flash_audio --- --- audio/mp3
OGG Audio shim flash_audio_ogg --- --- audio/ogg, audio/oga
HLS shim flash_hls --- --- application/x-mpegURL, vnd.apple.mpegURL
M(PEG)-DASH shim flash_dash --- --- application/dash+xml

To know how well-supported are each one of the formats, visit http://caniuse.com/

IMPORTANT: Only renderers prefixed as native, YouTube, and Flash shim, are integrated by default on the player. The rest of the renderers are stored in the build/renderers folder.

Notes

  • Support for wmv and wma has been dropped since most of the major players are not supporting it as well.
  • ogg formats will not play consistently in all browsers so it is strongly recommended a MP3 fallback for audio, or MP4 for video.
  • wav and webm formats will only play on Browsers that support it natively since there is currently no Flash fallback to allow them to play in other browsers.
  • flv and mpd will not work on iOS since it doesn't support MSE; for mpd use a m3u8 fallback.

Destroy player

In order to destroy the player, you must pause the player and then invoke the remove() method.

var player = new MediaElementPlayer('#player');

// Using jQuery:
// var playerId = $('#mediaplayer').closest('.mejs__container').attr('id');
// var player = mejs.players[playerId];


if (!player.paused) {
        player.pause();	
}

player.remove();

// If you wanna destroy COMPLETELY the player (including also the `video` tag) use the above and also the following:
var videos = document.getElementsByTagName('video');
for( var i = 0, total = videos.length; i < total; i++ ){ 
        videos[i].parentNode.removeChild(videos[i]);
}


// Using jQuery:
// $('video').each(function() {
//         $(this).remove();
// });

Same code can be used for <audio> elements.

Responsive grid

Since MediaElement can adapt its size to be responsive, some might be tempted to use CSS or Javascript to create a responsive grid of videos.

So far, right now the best plugin to be used with MediaElement for this task has been Flexr.

Back to Main