Introduction

Media players are used to automatically embed files in the pages. It is normally video or audio files or links to media sharing sites such as YouTube or Vimeo. However it is also possible to use media players for embedding other contents - diagrams, formulas, etc. Media players usually look at the file extension to match with the player but they can also make a URL match (this can be used for YouTube, Vimeo and similar sites links).

In standard Moodle package media players are used:

- When [Multimedia plugin filter|https://docs.moodle.org/en/Multimedia_plugins_filter] - When using URL or File resources and also in one place in Lesson module

Using media players

Plugin developers can use media players in their plugins for displaying a file or URL.

Via multimedia plugins filters

Multimedia plugins filter is automatically enabled and admins hardly ever disable it. The simplest way to engage media players is to call format_text() on the link to the media file, for example:

echo format_text(html_writer::link($urltofile, 'Text for fallback'), FORMAT_HTML, ['context'=>$context]);

Via media manager

If you want to use advanced options such as specifying alternative URLs/files, setting size or passing other options you can use media manager directly. Below is an example from mod_resource.

Create instance of moodle_url objects to link to the media file.

$moodleurl = new moodle_url(....); // Create instance of moodle_url objects to link to the media file. You can use moodle_url::make_pluginfile_url() to form a link to a plugin file. $mediamanager = core_media_manager::instance(); $embedoptions = array(

   core_media_manager::OPTION_TRUSTED => true, // Only add it for trusted contents if current user has respective capability with RISK_XSS mask.
   core_media_manager::OPTION_BLOCK => true,

);
if ($mediamanager->can_embed_url($moodleurl, $embedoptions)) {

   $code = $mediamanager->embed_url($moodleurl, $title, 0, 0, $embedoptions);

} else {

   // Put your own fallback here, for example a link to the file. Look at example in mod_resource, it has special treatment for images and PDF files.

}

Advanced usage is to use methods can_embed_urls() and embed_urls() that allow to embed one of the alternatives, for example, when video is uploaded in several formats and the player will select the format that it wants.

Developing media players

Plugin structure

Media player plugins are located in media/player/ directory and follow standard structure of Moodle plugins. Additionally they must contain a file classes/plugin.php containing the class media_PLUGINNAME_plugin extending core_media_player.

Class core_media_player contains all methods that can be overridden in individual players. We won't cover all methods from the parent class here since the phpdocs are self-explanatory but there are several things that should be mentioned:

Matching and fallbacks

Admin can enable or disable individual plugins and change their order. Media manager tries to apply all of the enabled plugins respecting the sort order. This is done here. It is possible that several players can handle the specific file type (or one of the alternatives). Sometimes several of them can be applied. This is implemented using the "fallback placeholder". If the player includes core_media_player::PLACEHOLDER in the generated HTML, the next matching player will replace it with it's code. If the placeholder is still present in the text after manager looped over all players it will be replaced with a link (unless there is an option not to do it). Some players (for example media_videojs) may specifically indicate that they don't want any of the other players to apply but they would not mind a link fallback. They can use core_media_player::LINKPLACEHOLDER for that.

Native audio and video players

Since HTML5 browsers natively support videos and audios in some formats. This is done using <video> and <audio> tags. Support of individual formats by individual browsers varies. Common [mis-]understanding is that the browser will display text inside these tags when browser can't play video or audio format of the source file. However this is not exactly true. Text inside <video> and <audio> tags will be displayed only if the browser does not support HTML5 at all and does not understand these tags at all. If user browser supports HTML5 but does not support the file format, no video and no fallback will be displayed. To avoid such situations Moodle offers a method core_useragent::supports_html5($ext) that checks if the user browser actually supports videos and audios in the given format. Still this method only looks at the extension of the file and may make wrong assumptions because videos can have same extensions but use different codecs, the method will return true if at least one codec is supported but it may not be the codec that is actually used.

It is recommended to use core_media_player_native as a base class for players that work with native browser support (examples are media_html5video, media_html5audio, media_videojs).

Playback attributes and tracks

There are multiple additional options for displaying video and audio files that are not part of Media API. For example, <video> tag may have attributes controls, autoplay, poster, etc. There also can be additional <track> elements that contain subtitles, closed captions, chapters, etc. It would be too difficult and not flexible to add properties for each of them to the API, besides it does not really benefit API much since player will not make a decision whether it can play one or another file based on these attributes and tracks.

When original text already contains a <video> or <audio> tag, it will be passed down to media players in the core_media_manager::OPTION_ORIGINAL_TEXT option. Example from media_videojs_plugin::embed($urls, $name, $width, $height, $options) :

if (array_key_exists(core_media_manager::OPTION_ORIGINAL_TEXT, $options) &&

       preg_match('/^<(video|audio)\b/i', $options[core_media_manager::OPTION_ORIGINAL_TEXT], $matches)) {
   // Original text already had media tag - get some data from it.
   $text = $options[core_media_manager::OPTION_ORIGINAL_TEXT];
   $isaudio = strtolower($matches[1]) === 'audio';
   $hastracks = preg_match('/<track\b/i', $text);
   $hasposter = self::get_attribute($text, 'poster') !== null;

}

core_media_player_native class contains useful methods for extracting/substituting properties and tags in the original text.

Javascript in media players

If media players need to load Javascript on the page they need to do so in the setup() method. This method is called when page is initialized regardless of whether the player is actually used on the page. Please note that Moodle may have dynamically loaded contents (for example when part of the page is updated after AJAX request) and JS code should be able to handle dynamic DOM.

Simple test of Javascript-powered media player in AJAX loading: Enable URL to link filter and place it above multimedia filter on Site administration > Plugins > Filters > Manage filters page. Login as a user send another user a message with a URL to a media file. When you views your messages and switches between contacts the conversations are loaded dynamically. Make sure that media will be displayed in the appropriate player in this case.

Documentation

Media players

Contents