2 // This file is part of Moodle - http://moodle.org/
4 // Moodle is free software: you can redistribute it and/or modify
5 // it under the terms of the GNU General Public License as published by
6 // the Free Software Foundation, either version 3 of the License, or
7 // (at your option) any later version.
9 // Moodle is distributed in the hope that it will be useful,
10 // but WITHOUT ANY WARRANTY; without even the implied warranty of
11 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12 // GNU General Public License for more details.
14 // You should have received a copy of the GNU General Public License
15 // along with Moodle. If not, see <http://www.gnu.org/licenses/>.
18 * Base class for media players
21 * @copyright 2016 Marina Glancy
22 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
25 defined('MOODLE_INTERNAL') ||
die();
28 * Base class for media players.
30 * Media players return embed HTML for a particular way of playing back audio
31 * or video (or another file type).
34 * @copyright 2016 Marina Glancy
35 * @author 2011 The Open University
36 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
38 abstract class core_media_player
{
40 * Placeholder text used to indicate where the fallback content is placed
43 const PLACEHOLDER
= '<!--FALLBACK-->';
46 * Placeholder text used to indicate where the link fallback is placed.
47 * No other players will apply to it but it will be converted to the link in the
48 * end (unless prevented by OPTION_NO_LINK).
50 const LINKPLACEHOLDER
= '<!--LINKFALLBACK-->';
53 * Generates code required to embed the player.
55 * The returned code contains a placeholder comment '<!--FALLBACK-->'
56 * (constant core_media_player::PLACEHOLDER) which indicates the location
57 * where fallback content should be placed in the event that this type of
58 * player is not supported by user browser.
60 * The $urls parameter includes one or more alternative media formats that
61 * are supported by this player. It does not include formats that aren't
62 * supported (see list_supported_urls).
64 * The $options array contains key-value pairs. See OPTION_xx constants
65 * for documentation of standard option(s).
67 * @param array $urls URLs of media files
68 * @param string $name Display name; '' to use default
69 * @param int $width Optional width; 0 to use default
70 * @param int $height Optional height; 0 to use default
71 * @param array $options Options array
72 * @return string HTML code for embed
74 public abstract function embed($urls, $name, $width, $height, $options);
77 * Gets the list of file extensions supported by this media player.
79 * Note: This is only required for the default implementations of
80 * list_supported_urls(), get_embeddable_markers() and supports().
81 * If you override these functions to determine
82 * supported URLs in some way other than by extension, then this function
85 * @return array Array of strings (extension not including dot e.g. '.mp3')
87 public function get_supported_extensions() {
92 * Lists keywords that must be included in a url that can be embedded with
93 * this player. Any such keywords should be added to the array.
95 * For example if this player supports FLV and F4V files then it should add
96 * '.flv' and '.f4v' to the array. (The check is not case-sensitive.)
98 * Default handling calls the get_supported_extensions function, so players
99 * only need to override this if they don't implement get_supported_extensions.
101 * This is used to improve performance when matching links in the media filter.
103 * @return array Array of keywords to add to the embeddable markers list
105 public function get_embeddable_markers() {
106 return $this->get_supported_extensions();
110 * Returns human-readable string of supported file/link types for the "Manage media players" page
111 * @param array $usedextensions extensions that should NOT be highlighted
114 public function supports($usedextensions = []) {
116 if ($extensions = $this->get_supported_extensions()) {
117 $video = $audio = $other = [];
118 foreach ($extensions as $key => $extension) {
119 $displayextension = $extension;
120 if (!in_array($extension, $usedextensions)) {
121 $displayextension = '<strong>'.$extension.'</strong>';
123 if (file_extension_in_typegroup('file.'.$extension, 'audio')) {
124 $audio[] = $displayextension;
125 } else if (file_extension_in_typegroup('file.'.$extension, 'video')) {
126 $video[] = $displayextension;
128 $other[] = $displayextension;
132 $out[] = get_string('videoextensions', 'core_media', join(', ', $video));
135 $out[] = get_string('audioextensions', 'core_media', join(', ', $audio));
138 $out[] = get_string('extensions', 'core_media', join(', ', $other));
141 return join('<br>', $out);
145 * Gets the ranking of this player. This is an integer used to decide which
146 * player to use (after applying other considerations such as which ones
147 * the user has disabled).
149 * This function returns the default rank that can be adjusted by the administrator
150 * on the Manage media players page.
152 * @return int Rank (higher is better)
154 public abstract function get_rank();
157 * @deprecated since Moodle 3.2
159 public function is_enabled() {
160 throw new coding_exception('core_media_player::is_enabled() can not be used anymore.');
164 * Given a list of URLs, returns a reduced array containing only those URLs
165 * which are supported by this player. (Empty if none.)
166 * @param array $urls Array of moodle_url
167 * @param array $options Options (same as will be passed to embed)
168 * @return array Array of supported moodle_url
170 public function list_supported_urls(array $urls, array $options = array()) {
171 $extensions = $this->get_supported_extensions();
173 foreach ($urls as $url) {
174 $ext = core_media_manager
::instance()->get_extension($url);
175 if (in_array('.' . $ext, $extensions) ||
in_array($ext, $extensions)) {
183 * Obtains suitable name for media. Uses specified name if there is one,
184 * otherwise makes one up.
185 * @param string $name User-specified name ('' if none)
186 * @param array $urls Array of moodle_url used to make up name
187 * @return string Name
189 protected function get_name($name, $urls) {
190 // If there is a specified name, use that.
195 // Get filename of first URL.
197 $name = core_media_manager
::instance()->get_filename($url);
199 // If there is more than one url, strip the extension as we could be
200 // referring to a different one or several at once.
201 if (count($urls) > 1) {
202 $name = preg_replace('~\.[^.]*$~', '', $name);
209 * @deprecated since Moodle 3.2
211 public static function compare_by_rank() {
212 throw new coding_exception('core_media_player::compare_by_rank() can not be used anymore.');
216 * Utility function that sets width and height to defaults if not specified
217 * as a parameter to the function (will be specified either if, (a) the calling
218 * code passed it, or (b) the URL included it).
219 * @param int $width Width passed to function (updated with final value)
220 * @param int $height Height passed to function (updated with final value)
222 protected static function pick_video_size(&$width, &$height) {
225 $width = $CFG->media_default_width
;
226 $height = $CFG->media_default_height
;
231 * Setup page requirements.
233 * The typical javascript requirements MUST not take action on the content
234 * directly. They are meant to load the required libraries and listen
235 * to events in order to know when to take action. The role of this method
236 * is not to provide a way for plugins to look for content to embed on the
237 * page. The {@link self::embed()} method is meant to be used for that.
239 * @param moodle_page $page The page we are going to add requirements to.
242 public function setup($page) {
243 // Override is need be.