Make your own free website on Tripod.com

FLASH PLAYERS 3.6 README

This readme contains information regarding the installation and configuration of my Flash MP3 Player, Flash Video Player, Flash Media Player and Flash Image Rotator. Contents of this readme:

INSTALLING

The example HTML file in the download works right out of the box. If you look at it's source code (in a text or HTML editor), you can see that the SWF files are inserted in the page with a small javascript. These javascripts use the external ufo.js script by Bobby van der Sluis in order to prevent the annoying "click here to activate" message. If you copy the SWF to your website, make sure you don't forget to copy the ufo.js file as well. The ufo.js is inserted in the HTML page right at the top:

<script type="text/javascript" src="ufo.js"></script>

An insertion javascript allows you to set the location of the SWF, it's width and height, the version and build of Flash that is needed (leave to 7 and 0 for maximum compatibility) and the backgroundcolor of the movie. You can also send a list of Flashvars to the SWF to configure it (for that see the next paragraph). When the HTML page loads, the javascript replaces the element of your HTML with the "id" you provided in the javascript (make sure you have an element with that id!).

<p id="player"><a href="http://www.macromedia.com/go/getflashplayer">Get Flash</a> to see this player.</p>
<script type="text/javascript">
  var FO = { movie:"mediaplayer.swf",width:"300",height:"20",majorversion:"7",build:"0",bgcolor:"#FFFFFF",
             flashvars:"file=playlist.xml&autostart=true" };
  UFO.create(FO,"player");
</script>

If you cannot use javascript on your website (for example if you run the SWF on a profile site like MySpace), you can use an "embed" code instead of the javascript. Your SWF will probably be on another server then. That is OK, but note that your XML playlist (if used) should always reside on the same server than your SWF, or else the security restrictions won't allow the mediaplayer.swf to load it. Having MP3 or JPG or FLV files on a different server is no problem.

<embed src="http://www.myfileserver.com/folder/mediaplayer.swf" width="300" height="200" bgcolor="#FFFFFF"
type="application/x-shockwave-flash" pluginspage="http://www.macromedia.com/go/getflashplayer" 
flashvars="file=http://www.myfileserver.com/folder/playlist.xml&autostart=true" />

FLASHVARS

Flashvars are configuration options you can insert into your HTML code to control both behavior and appearance of the player/rotator. In the code example above, you could already see them: inside the "flashvars" attribute of your embed code, and stacked with the "&" symbol. In the lists below, all flashvars are explained.

Note that you can urlencode your flashvars in order to prevent the use of the ? = & symbols. The urlencoded values for these symbols are: ?%3F, =%3D, &%26. So if your "file" flashvar has the value of getplaylist.php?id=123, you can set it like this: getplaylist.php%3Fid%3D123.

BASIC FLASHVARS

COLOR FLASHVARS

DISPLAY FLASHVARS

FULLSCREEN FLASHVARS

INTERACTION FLASHVARS

PLAYBACK FLASHVARS

PLAYLISTS

You can load a single file as well as an entire playlist of files into the players. The players look at the filename to determine whether a single file or a playlist is loaded. For example, if your file is test.mp3, it will presume you load a single MP3 file, because the extension is "mp3". If your filename is getlist.php, the SWF will see a playlist. If you use dynamic scripts to load a single file (e.g. getmovie.php%3Fid%3D123), you can tell the player which file it loads by using the additional "type" flashvar (set it to either mp3,flv,rtmp,jpg,png,gif,swf or rbs).

The players support three commonly used playlist formats to ensure maximum compatibility: XSPF (much used for CC music), RSS (much-used for Podcasts) and ATOM (much-used by Blogs). The example playlist.xml in this download is in XSPF format. Here is a list of all flashvars and their corresponding XSPF/RSS/ATOM tags that are supported by the player/rotator:

FlashvarXSPF TagRSS TagATOM Tag
file<location><enclosure> or <media:content><link rel="enclosure">
title<title><title><title>
link<info><link><link>
id<identifier><guid><id>
image<image><media:thumbnail> or <itunes:image><link rel="image">
author<creator><author><name>
captions<link rel="captions"><enclosure type="captions"><link rel="captions">
category*<album><category><category>
start**<meta rel="start">--
type***last three characters of <location>or <meta rel="type">mimetype of <enclosure>mimetype of <link rel="enclosure">

* If you set the "category" element to "commercial", the interface will block for the duration of that item, to prevent skipping commercials. Use this with care and only embed short commercial clips!

** The "start" element is only supported by XSPF playlists, and only works with streaming files (HTTP or RTMP). Use it to specify the starting position in seconds.

*** If the XSPF "location" url doesn't contain a useful extension (e.g. "mp3" or "flv"), use the "meta" element to tell the player which filetype it is (e.g. <meta rel='"type">mp3</meta> ). For RSS and ATOM, the filetype is automatically extracted from the mimetype.

Note that, if you play a single file, you can send each item in this table as a flashvar to the SWF. This way, you can add an image, title, id, link, etc. to a single file as well. So if you have, for example, the flvplayer and a single file "video.flv" and want to display a preview image too, you can set the flashvars "file=video.flv&image=preview.jpg". For refering to RTMP streams, the additional "id" flashvar has to be sent as well. Example: "&file=rtmp://my.streaming.server/mypath&id=video_one". You can also insert streams into playlists with this file/id pair (see below).

I'd like to point out two common pitfalls users encounter when using playlists. First, a playlist should always reside on the same server as the SWF file, due to security restrictions of the Flash Player (there is a small workaround, the "external_feed.php" in the "extras" folder of this download). Second, always try to use full URL's (including the http:// part) when referring to files, links or images in your playlists. It will save you a lot of troubles with unresponsive SWF's or "file not found" errors!

I've included some additional playlist-related files in the "extras" folder of this download. First, the "force_download.php" script will enable you to force a download of your mediafiles instead of opening them in Windows Mediaplayer or any other program. If you copy this script to your website and fill out the "link" tags of your playlist like this: "force_download.php?file=path_to_my_file.mp3", the small link buttons of the playlist will act like download buttons for your files. Second, the "extras" folder contains a PHP example of how to create a playlist on-the-fly, either by pulling data off a database (php_mysql_playlist.php) or scanning a certain directory for mediafiles(php_readdir_playlist.php). In both cases you can feed the php file to the mediaplayer with the "file" flashvar.

CUSTOMIZATION

I receive a lot of requests for creating customized versions of my players. In most cases however, a clever setting of the flashvars already fulfilled the requests, so please make sure you check the list of flashvars first! Additionally, I do not design or program any particular (paid-for) customizations (I just don't have time for it), but interesting features will be plugged into the next update of the players.

If you are familiar with actionscripting yourself, you should find that changing or adding to the players is quite simple. To get started, check out this schematic overview of the player's code. Note that from version 3.4 the flvplayer, mp3player and mediaplayer are identical in terms of code:

schematic overview of the players

A player starts by instantiating either the ImageRotator or Mediaplayer class, which loads all config and file variables and sets up the MCV cycle. The fileArray and configArray variables are used by each member of the MCV cycle for setup. Another file can be loaded through the loadFile() function, which is available both in actionscript and javascript (javascript example).

Communication between the MCV's members is strictly defined (with the updates, changes and events). Creating a complete new look for any of the players can be done by creating a new class that extends the AbstractPlayer and classes that extend the AbstractView. The ControlbarView class is a good AbstractView extension to copy and modify for this purpose (it contains all controlbar graphics).

Placing the player/rotator into another Flash file is also possible. Just copy-paste the player or rotator symbol from the FLA file in the download to your FLA file. Also make sure you copy the "com" directory to the directory of your FLA file as well; it contains all scripting. If that's done, you can set all flashvars as variables in the root timeline and start the player from there as well. Make sure you set the "width" and "height" flashvar too, or the player/rotator will stretch to your entire stage! Here's an example:

// Set the flashvars
var width = "320";
var height = "240";
var file = "my_video.flv";
var autostart = "true";

// Start the player
var mpl = new com.jeroenwijering.players.MediaPlayer(this.player);

SUPPORT

Here's a small list with frequently-encountered problems:

An up-to-date list of third-party plugins for each list can be found on my website, at the respective player's page. If you have written or seen an unlisted plugin, please report so in my forum!

For tips, tricks, additional info and bug reports, you can always have a look at my Support Forum.

For more info about the embedding of Flash in HTML, have a look at my Embedding Flash article.

For more info about Flash Video and some compression tips, check out my Flash Video Compression article.