media/classes/player.php

   1 <?php
   2 // This file is part of Moodle - http://moodle.org/
   3 //
   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.
   8 //
   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.
  13 //
  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/>.
  16
  17 /**
  18  * Base class for media players
  19  *
  20  * @package   core_media
  21  * @copyright 2016 Marina Glancy
  22  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  23  */
  24
  25 defined('MOODLE_INTERNAL') || die();
  26
  27 /**
  28  * Base class for media players.
  29  *
  30  * Media players return embed HTML for a particular way of playing back audio
  31  * or video (or another file type).
  32  *
  33  * @package   core_media
  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
  37  */
  38 abstract class core_media_player {
  39     /**
  40      * Placeholder text used to indicate where the fallback content is placed
  41      * within a result.
  42      */
  43     const PLACEHOLDER = '<!--FALLBACK-->';
  44
  45     /**
  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).
  49      */
  50     const LINKPLACEHOLDER = '<!--LINKFALLBACK-->';
  51
  52     /**
  53      * Generates code required to embed the player.
  54      *
  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.
  59      *
  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).
  63      *
  64      * The $options array contains key-value pairs. See OPTION_xx constants
  65      * for documentation of standard option(s).
  66      *
  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
  73      */
  74     public abstract function embed($urls, $name, $width, $height, $options);
  75
  76     /**
  77      * Gets the list of file extensions supported by this media player.
  78      *
  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
  83      * is not necessary.
  84      *
  85      * @return array Array of strings (extension not including dot e.g. '.mp3')
  86      */
  87     public function get_supported_extensions() {
  88         return array();
  89     }
  90
  91     /**
  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.
  94      *
  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.)
  97      *
  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.
 100      *
 101      * This is used to improve performance when matching links in the media filter.
 102      *
 103      * @return array Array of keywords to add to the embeddable markers list
 104      */
 105     public function get_embeddable_markers() {
 106         return $this->get_supported_extensions();
 107     }
 108
 109     /**
 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
 112      * @return string
 113      */
 114     public function supports($usedextensions = []) {
 115         $out = [];
 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>';
 122                 }
 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;
 127                 } else {
 128                     $other[] = $displayextension;
 129                 }
 130             }
 131             if ($video) {
 132                 $out[] = get_string('videoextensions', 'core_media', join(', ', $video));
 133             }
 134             if ($audio) {
 135                 $out[] = get_string('audioextensions', 'core_media', join(', ', $audio));
 136             }
 137             if ($other) {
 138                 $out[] = get_string('extensions', 'core_media', join(', ', $other));
 139             }
 140         }
 141         return join('<br>', $out);
 142     }
 143
 144     /**
 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).
 148      *
 149      * This function returns the default rank that can be adjusted by the administrator
 150      * on the Manage media players page.
 151      *
 152      * @return int Rank (higher is better)
 153      */
 154     public abstract function get_rank();
 155
 156     /**
 157      * @deprecated since Moodle 3.2
 158      */
 159     public function is_enabled() {
 160         throw new coding_exception('core_media_player::is_enabled() can not be used anymore.');
 161     }
 162
 163     /**
 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
 169      */
 170     public function list_supported_urls(array $urls, array $options = array()) {
 171         $extensions = $this->get_supported_extensions();
 172         $result = array();
 173         foreach ($urls as $url) {
 174             $ext = core_media_manager::instance()->get_extension($url);
 175             if (in_array('.' . $ext, $extensions) || in_array($ext, $extensions)) {
 176                 $result[] = $url;
 177             }
 178         }
 179         return $result;
 180     }
 181
 182     /**
 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
 188      */
 189     protected function get_name($name, $urls) {
 190         // If there is a specified name, use that.
 191         if ($name) {
 192             return $name;
 193         }
 194
 195         // Get filename of first URL.
 196         $url = reset($urls);
 197         $name = core_media_manager::instance()->get_filename($url);
 198
 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);
 203         }
 204
 205         return $name;
 206     }
 207
 208     /**
 209      * @deprecated since Moodle 3.2
 210      */
 211     public static function compare_by_rank() {
 212         throw new coding_exception('core_media_player::compare_by_rank() can not be used anymore.');
 213     }
 214
 215     /**
 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)
 221      */
 222     protected static function pick_video_size(&$width, &$height) {
 223         global $CFG;
 224         if (!$width) {
 225             $width = $CFG->media_default_width;
 226             $height = $CFG->media_default_height;
 227         }
 228     }
 229
 230     /**
 231      * Setup page requirements.
 232      *
 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.
 238      *
 239      * @param moodle_page $page The page we are going to add requirements to.
 240      * @since Moodle 3.2
 241      */
 242     public function setup($page) {
 243         // Override is need be.
 244     }
 245
 246 }