[Summary view]

   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  }