Note:

If you want to create a new page for developers, you should create it on the Moodle Developer Resource site.

Media embedding

From MoodleDocs

Moodle 2.3


Note: From Moodle 3.2 onwards this API is no longer used. Developers can create Media players plugins.


From Moodle 2.3, a new API can be used to embed media items. Media items are:

  • Audio files.
  • Video files.
  • Flash files.
  • Audio, video, or similar content embedded from remote websites (currently YouTube and Vimeo).

Automatic embedding

As in previous versions of Moodle, you do not need to do anything special to embed media files in text that users enter. This text is processed by the mediaplugin filter, which (if enabled) will automatically embed media files when users enter a link to the media.

You only need to use the API on this page if you want to embed media files as part of output generated by your plugin, rather than generated by user text.

Embedding media

To embed a media file, use the following code:

$mediarenderer = $PAGE->get_renderer('core', 'media');
echo $mediarenderer->embed_url(new moodle_url('http://example.org/a.mp3'));

Size

You can supply video size in two ways:

  • As parameters to the embed_url function.
  • At the end of the URL as #d=640x480 (d is short for 'dimensions')

A #d in the URL will override the function parameters.

If you don't supply size, you get default behaviour. Some players are capable of automatically determining the correct size (based on the video), so it is better not to supply size unless you're sure of it, for example if the size information was provided by the user or if the size was checked by analysing the video using a server-side tool. (Players that can't determine a size will use hard-coded defaults built into Moodle.)

Name

You can also supply an optional name as a parameter to the embed_url function. The system uses this in various places where a title for the content is required. If you don't supply a name, the filename is used.

If the user does not have any plugins installed that are capable of playing your video, they will see a link containing this text.

Multiple formats

To get the most compatible results, you can supply more than one file in order to provide the same media content in multiple formats. The system automatically sets up appropriate fallbacks so that your file is likely to play.

Note: The best results are obtained if you supply a file that Flash can play (.f4v or .flv), and also an MPEG-4 file which is formatted for mobile devices (.mp4 or .m4v). This combination should play on all common devices and browsers.

$mediarenderer = $PAGE->get_renderer('core', 'media');
$files = array(new moodle_url('http://example.org/a.m4v'), new moodle_url('http://example.org/a.f4v'));
echo $mediarenderer->embed_alternatives($files);

In the media filter, we let users automatically generate these effects using a URL like this:

http://example.org/a.m4v#http://example.org/a.f4v#d=400x300

If you want to support this kind of multi-URL string in your own code, use the core_media::split_alternatives function.

Flash and security

Allowing ordinary users to embed Flash on your website, which other users can then view, creates a serious security risk. By default, the embed code shown above will not embed Flash .swf files; these will be included as a download link instead.

If the media content that you are embedding can only be set up by trusted users such as teachers, then you should use the core_media::OPTION_TRUSTED option when you embed content. This will allow Flash content to be embedded.

$mediarenderer = $PAGE->get_renderer('core', 'media');
$options = array(core_media::OPTION_TRUSTED => true);
echo $mediarenderer->embed_url(new moodle_url('http://example.org/a.mp3'), '', 0, 0, $options);

"Trusted users" are Managers and Teachers by default. site:trustcontent capability is required. See https://docs.moodle.org/23/en/Site_policies#Enable_trusted_content

Other options

Two other options are currently available at time of writing.

  • core_media::OPTION_NO_LINK: Disables the download link fallback. Users who don't have a suitable player plugin will see nothing at all. This option should be used if you always print a visible download link separately, as there is then no need for a fallback link.
  • core_media::OPTION_EMBED_OR_BLANK: Depending on the filetype and server options it might not be possible to embed the file. Normally the system outputs a download link in that case. Using this option causes it to return an empty string. Use the option if you're going to check the return value and do something different if it isn't possible to embed the file. (Note: This option is based on server settings, not on the current user. If the system is able to create embed code for the file, then this code will be returned and not blank, even if the current user doesn't have the right plugin installed.) You can also achieve the same effect by separately calling the $mediarenderer->can_embed_url() function.

Changing media embedding behaviour

If you want to change the media embedding behaviour in all locations within your own Moodle installation, you can do that by overriding the core_media_renderer class.

You can override renderers within a theme.

Changing player list

In your renderer which extends core_media_renderer, you will typically want to override the get_players_raw function to either add new player classes to the array, remove existing ones, or both. For example, if you create a different way to embed FLV files, you could remove the existing flv renderer and add a new one using the following function:

protected function get_players_raw() {
    $original = parent::get_players_raw();
    unset($original['flv']);
    $original['flv'] = new theme_mytheme_myflvplayer();
    return $original;
}

Writing a new player

Writing player classes is easy. Your player class should extend core_media_player if it handles a file type (like FLV), or core_media_player_external if it handles URLs for an external site (like YouTube).

Here is an example player class for a new video format called .frogvideo:

class core_media_player_frogvideo extends core_media_player {
    public function embed($urls, $name, $width, $height, $options) {
        // $urls is a list of the alternative urls supported by this player
        // (i.e. that end in .frogvideo) - you use this list to construct
        // the embed html.

        // Just return the html code to embed this player. Some part of the
        // html should include code that appears if the user doesn't have
        // a suitable plugin installed; put the placeholder at that point.
        return '...HTML code...' . core_media_player::PLACEHOLDER . '...';
    }

    public function get_supported_extensions() {
        return array('frogvideo');
    }

    public function get_rank() {
        // If you want this player to be used in preference to the existing
        // ones, use a bigger rank number than existing players.
        return 111;
    }
}

For more detail about the available functions and more complex use cases, look at the PHP documentation for core_media_player in medialib.php.

Current documentation

To see current in-code documentation, look in the files lib/medialib.php and at the class core_media_renderer in lib/outputrenderers.php.