Extension:Player

The Player extension provides a special page, Special:Player, that allows playback of video and other multimedia content uploaded to the wiki. It also provides a custom tag, &lt;player&gt;, that allows multimedia content to be embedded into wiki pages and played on demand (embedded playback requires Ajax; without Ajax, a link to the player page is provided).

Note that this extension is experimental and basically an ugly kluge while waiting for more flexible media file handling facilities in MediaWiki proper.

How it works
Per default, the Player extension relies on browser plugins for playback - this means that if you want to play a movie, your browser has to have a plugin for this type of movie installed. But the Player extension can also be configured to use a server-supplied player that is based on Macromedia Flash or Java. For example, the FlowPlayer Flash scrip (Apache License) can be used to play Flash Video files (FLV), or Flumotion's Cortado Java applet  (GPL) can be used to play OGG files - this way, users need to have Flash resp. Java installed (which is wide spread), instead of having to have codecs for FLV and OGG installed (which is rare - the VLC plugin supports both, though).

If the media file can actually seen by the user depends his/her browser and installed plugins, as well as the operating system, and configuration of all this. The table below shows some combinations that have been tried out. Please add you own experience, especially with idfferent operating systems, browsers or plugins.

Installing
Copy the Player directory into the extensions folder of your MediaWiki installation. Then add the following line to your LocalSettings.php file (near the end): require_once( "$IP/extensions/Player/Player.php" );

Installing Flash/Java-based players
To install third-party players for use by the Player extension, get the files required by the player and put them into the directory you installed the Player extension in. The create a template that uses the player, and assign it to the desired MIME types using the $wgPlayerTemplates setting (see below). In PlayerDefaultSettings.php there are example templates for FlowPlayer and the Cortodo player.

Configuration
The Player extension can be configured in several ways. The Default configuration, along with some notes and documenation, are in the PlayerDefaultSettings.php file. Some important settings are described below:
 * wgUseAjax: this is a global MediaWiki setting. You have to set it to true to enable embedded playback. If not enabled, or if the browser does not support JavaScript or has it disabled, a link to the player page will be provided instead of an embedded player.
 * $wgPlayerTemplates: this is an array that contains a template for each MIME-type that should be handeled by the Player plugin (see Templates below).
 * $wgPlayerMimeOverride: this is a map of mime-type aliases. This allows you to override the mime type that will be passed to the player template. For example, video/ogg is per defautl mapped to application/ogg, since some browser plugins don't recognize video/ogg.
 * $wgPlayerVideoResolutionDetector: this is used to configure the program used to detect the resolution (size) of videos. It can be set to false or null to disable resolution detection, or to a string to use the same detection command, for everything, or to an array mapping mime types to detection commands (using the entry for "*" as a fallback). Each entry in the array by itself be a string specifying a command, or an array containing three fields: command, outpattern and outreplace, where outpattern is a PCRE regular expression, and outreplace is a replacment string for that pattern. This can be used transform the commands output into the form expected by the Player extension, namely the form 400x300. There are two example settings in PlayerDefaultSettings.php, both commented out. One uses mplayer for everything, the otehr uses ogginfo for ogg files and mplayer for the rest. Note that for now, the detector command is run every time a player or placeholder is rendered.

Templates
Player templates are HTML-snippets for embedding something into the HTML output that allows a specific media file to be played (usually, a template would generate an &lt;object&gt;, &lt;embed&gt; or &lt;applet&gt; tag). In a template, placeholders for template parameters are used to adopt the template for a specific media file (see below).

The $wgPlayerTemplates maps the MIME type of a given file to a template. If no template is defined for that type, playback is not allowed. If the "forcegeneric" option is used, the entry for the pseudo-type "generic" is always used, regardles of the file's actual type or the template associated with that type.

PlayerDefaultSettings.php defines several templates for your conveniance:


 * $wgPlayerGenericTemplate: generates a generic &lt;object&gt; tag with fallback to &lt;embed&gt; for old browsers. This is used for almost everything per default.
 * $wgPlayerSvgPluginTemplate: like $wgPlayerGenericTemplate, but works around a problem with some SVG plugins by providing an extra src parameter. Used per default for image/svg+xml
 * $wgPlayerFlashPluginTemplate: generates specialized &lt;object&gt; and &lt;embed&gt; tags for the Macromedia Flash/ShockWave plugin. Used per default for application/x-shockwave-flash
 * $wgPlayerFlowPlayerTemplate: template for embedding the FlowPlayer for playback of FLV files. Not enabled per default; you can enable it by using the line for video/x-flv from PlayerDefaultSettings.php. Requires FlowPlayer from http://flowplayer.sourceforge.net Note that this has been tested successfully only with the "Light" version of FlowPlayer, other versions seemed to have some problem.
 * $wgPlayerCortadoPlayerTemplate: template for embedding the Cortado player for playback of OGG files. Not enabled per default; you can enable it by using the line for audio/ogg, video/ogg and application/ogg from PlayerDefaultSettings.php. Requires Cortado player from http://www.flumotion.net/cortado/

In PlayerDefaultSettings.php, $wgPlayerGenericTemplate is assigned to most common media types, including mp3, wav, midi, ogg, mpeg, avi, and pdf.

See http://www.mediawiki.org/wiki/Manual:Configuring_file_uploads for information on allowing specific file types for upload. See http://www.mediawiki.org/wiki/Manual:Mime_type_detection for information on MIME type detection.

Template Parameters
Template parameters have the form. They are used as placeholders for values that apply to a specific media file, and will be replaced by the respective values before output. There are several forms of parameters:

This can be used to access global variables like $wgPlayerExtensionPath, $wgServer, $wgJsMimeType, $wgScriptPath, etc.
 * is a simple parameter - it will expand to the value of the option "foo", or be removed if "foo" is not set.
 * is a parameter with default walue - it will expand to the value of the option "foo", or to "quux" if "foo" is not set.
 * is an environment parameter - it will expand to the value of the global variable "wgFoo".
 * is an attribute-parameter - it will expand to foo="baz" (where baz is the value of the "foo" option).
 * is an attribute-parameter with name-alias - it will expand to bar="baz" (where baz is the value of the "foo" option).
 * is an param-tag-parameter - it will expand to &lt;param name="foo" value="baz"/&gt; (where baz is the value of the "foo" option).
 * is an param-tag-parameter with name-alias - &lt;param name="bar" value="baz"/&gt; (where baz is the value of the "foo" option).
 * is a conditional block - the value "some text" will be output only if the "foo"-option is set, otherwise the entire block is ignored. There is limmited support for nesting: ifset blocks can contain other template parameters, but not other ifset or ifunset blocks.
 * is a inverse conditional block - the value "some text" will be output only if the "foo"-option is NOT set, otherwise the entire block is ignored. There is limmited support for nesting: ifunset blocks can contain other template parameters, but not other ifset or ifunset blocks.

The following template parameters are always available:


 * uniq: a unique string, may be used to mark and refer to HTML elements using the id attribute.
 * url: the (local) URL of the media file.
 * fullurl: the full URL of the media file.
 * type: MIME-type media file (subject to $wgPlayerMimeTypeOverride).
 * width: the effective width, in pixels, the player should occupy.
 * height: the effective height, in pixels, the player should occupy.
 * pageurl: the URL of the file's description page in the wiki.
 * filename: plain name of the media file.
 * plainalt: an alternative text suitable for use in HTML attrbutes (such as alt or title). Generally the file name.
 * htmlalt: HTML-text that may be shown instead of the player. Generally a link to the file's description page.

The following global variables (accessible by the syntax) may be particularly interresting:


 * $wgPlayerExtensionPath: The URL path to the extension's installation directory. This may be used to reference secondary files in that directory, such as CSS or JS files, player scripts (SWF or JAR files), etc.
 * $wgScriptPath: URL path to MediaWiki's installation root. Usefull for building URLs.
 * $wgServer: Host- and protocol part of MediaWiki's server. Usefull for building URLs.

Additional parameters may be passed from attributes the user supplies in a &lt;player&gt; tag, or on the Special:Player page. User-supplied parameteres are always HTML-escaped.

Usage
The &lt;player&gt; tag can be used to embed videos and other multimedia content into wiki pages.

&lt;player&gt;Testing.mpg&lt;/player&gt;               this embeds the Testing.mpg file &lt;player&gt;Testing.mpg | some text&lt;/player&gt;   this embeds the Testing.mpg file with a caption &lt;player align="right" width="200"&gt;Testing.mpg&lt;/player&gt;   floating right-aligned, 200 pixels wide.

Tag Attributes
The following attributes can be usedin &lt;player&gt; tags:


 * id: sets the global ID for the resulting HTML structure.
 * class: adds CSS class(es) - same as for normal HTML tags.
 * style: adds CSS styles - same as for normal HTML tags.
 * width: determines the desired width for the player. The aspect ratio is preserved while scaling, if know (see $wgPlayerVideoResolutionDetector). If both width and height are given, a box-fit is applied.
 * height: determines the desired height for the player. The aspect ratio is preserved while scaling, if know (see $wgPlayerVideoResolutionDetector). If both width and height are given, a box-fit is applied.
 * align: determines the alignment. Thre are four possible values:
 * none: (default): the player box creates a paragraph.
 * center: the player box creates a centered paragraph.
 * left: the player box floats on the left side, text flows around it.
 * right: the player box floats on the right side, text flows around it.


 * thumb: determines the thumbnail image (if any). Must be the name of an uploaded image.
 * forcegeneric: use the template registered under the "generic" key, instead of selecting a template by the file's type.

Any additional attributes are passed on as template parameters. So, if you give foo="test" as an attribute, a template may refer to that value using . Note that user parameters are always escaped before being passed to the template, to avoid HTML injection issues.

Some attributes supported by some templates (in the hope the user's plugin will understand them): loop, menu, scale, and quality.