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).
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.
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'));
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. Note that some players are capable of automatically determining the correct size, so it is better not to supply size unless you're sure of it.
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.
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:
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);
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.
To see current in-code documentation, look in the files lib/medialib.php and at the class core_media_renderer in lib/outputrenderers.php.