Release status: beta
|Description||Flash video image handler|
|Author(s)||Adam Nielsen (Malvineoustalk)|
|Latest version||r4 (2011-11-05)|
Translate the FlvHandler extension if it is available at translatewiki.net
|Check usage and version matrix; code metrics|
What can this extension do?
This extension adds support for using Flash video (.flv) files in exactly the same way as images are normally used, i.e. [[Image:Movie.flv]]. This allows users to upload Flash videos and add them to articles using a method they are already familiar with.
Once uploading of .flv files has been permitted, Flash videos can be uploaded and then embedded in an article page in the same manner as with images:
Features which make this extension stand out from other .flv extensions:
- .flv files can be uploaded and displayed like any other image (no special tags required)
- .flv files can be categorised and thumbnails of the video shown on category pages (just like with ordinary images)
- An image gallery can include .flv files
- ffmpeg: This extension uses ffmpeg to extract the first frame from the video file, for use as a thumbnail. If you do not have the command-line ffmpeg binary available on your web host, you will not see any preview frames. You will however still be able to embed videos, but your site visitors will not know what the video is until they start playing it. The extension has been tested with the following ffmpeg versions:
- [FLVHandler r4] ffmpeg version 0.7, Copyright (c) 2000-2011 the Libav developers built on Jun 21 2011 15:04:56 with gcc 4.4.5
- flowplayer: This extension uses the GPL'd flowplayer Flash applet to play the FLV files. A future version will probably extend this to include other players as well (especially if someone sends me the HTML code to embed a particular player.)
- File uploads must already be working on your wiki. If not, see Manual:Configuring file uploads.
Download the extension from the Subversion repository and save it into the extensions/FlvHandler directory of your wiki. If you have shell access to your server, you may do the following to download the extension.
Warning: Before you download read Requirements or you might install the wrong version:
cd extensions svn co http://svn.wikimedia.org/svnroot/mediawiki/trunk/extensions/FlvHandler
Download flowplayer v3.0.3 and unzip it into
extensions/FlvHandler/flowplayer/ or alternatively set
$wgFlashPlayer to the URL of flowplayer's .swf file. If you do not use flowplayer version 3.0.3 you will need to set
$wgFlashPlayer as the default will point to the wrong filename version (see below.) Add the following to LocalSettings.php:
// Allow .flv files to be uploaded $wgFileExtensions = 'flv'; include_once("$IP/extensions/FlvHandler/FlvHandler.php"); // Place any FlvHandler configuration options here
All these parameters are optional, and suitable defaults are selected if omitted.
$wgFlashPlayer- URL of the flowplayer .swf file. Default is
$wgServer . $wgScriptPath . '/extensions/FlvHandler/flowplayer/flowplayer-3.0.3.swf'
$wgMinFLVSize- Minimum size of the playback window. Default is
array(250, 250)(250 pixels wide by 250 pixels tall) which is about as small as flowplayer will go before the controls start being drawn on top of each other.
$wgFLVConverter- program to use to extract first frame of video for thumbnails. Default is
'ffmpeg'(currently the only available option.) This is not a filename, rather the value is used to decide which command line options should be used to get the desired output.
$wgFLVConverterPath- Path to conversion binary (ffmpeg executable) if not in the system path.
How it works
If you're writing an extension and you think you might get some clues from how FlvHandler is written, then read on - this section briefly explains how the extension does its job.
There are two parts to the extension. The first is an image handler, which registers itself in the same way as the SVG handler. The idea of an image handler is to convert an unsupported image format into one that is widely supported (usually .png). Whenever a request comes through to display the .flv file, the handler steps in, calls FFmpeg to generate a thumbnail of the video (if one hasn't already been created), and then returns that thumbnail in .png format. This thumbnail is then displayed as requested. If this was the only part of the plugin in use, then .flv files would appear everywhere as still images. It is this part of the plugin that allows .flv files to be used anywhere images are, such as in categories and image galleries. It is also this part of the plugin which relies on FFmpeg being available to generate the thumbnails.
The second part of the plugin uses the ImageBeforeProduceHTML hook to step in whenever an image is about to be rendered in an article (read: whenever an <img> tag is about to be printed.) If the image tag is a thumbnail (or not a Flash video) then further processing is cancelled, and the tag is rendered as per normal (and in the case of a thumbnail, the other part of the plugin takes over and generates a still frame as the thumbnail.) If instead the image is a Flash video, then the extension takes over and generates the HTML code necessary to embed the flash player in the page.
This is a list of things planned for the extension that aren't currently there:
- Support for multiple Flash playing applets (only flowplayer is currently implemented)
- Extra code around the embedded player so that there is a link to the .flv's article page (like what happens when you click on an embedded image, and you are taken to the image's article page.)
- Preview on the .flv's article page, so you can watch the video from there (currently you have to embed it in a page before you can watch it.)
- Support for some of the flash player's tags (abstracted so it works with any flash player) - e.g. autostart
- Ability to specify (in the [[Image]] tag) which frame to use as the thumbnail - currently it is hard-coded as the first frame
If ffmpeg won't generate thumbnails, force a thumbnail view to see the error messages. Put this code in any page and preview it:
You will either see:
- A thumbnail of the video - everything is working.
- Some error messages. Please refer to an ffmpeg help forum if you do not understand the errors.
- The filename in red text, if you haven't uploaded the .flv file to the wiki yet.
- The filename in blue text, which could mean one of two things:
- The extension hasn't been set up in LocalSettings.php as per the instructions above.
- The web server is returning the wrong MIME type for .flv files. It must return "video/x-flv" or the extension will not be called upon to generate the thumbnails.
There are quite a few other Flash player extensions listed on the Video player extensions category, though at the time of writing they all use custom tags which users will need to learn before they can embed Flash videos.