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 (embed codes for your site)
• Flashvars (all configuration options):
  • Basic flashvars
  • Color flashvars
  • Display flashvars
  • Fullscreen flashvars
  • Interaction flashvars
  • Playback flashvars
• Playlists (how to create playlists)
• Customization (how to customize the players)
• Support (common pitfalls and support links)

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

• file (url): The location of the file to play. It can be a single file (MP3/FLV/RTMP/JPG/SWF/PNG/GIF) or a playlist for the players. The rotator only accepts playlists.
• image (url): If you play MP3 of FLV files, you can use this flashvar to show a preview image or album cover. It can be a JPG/SWF/PNG/GIF file. You can also assign an image for every item in a playlist.
• displayheight (number): This flashvar is used by the players and sets the height of the display. It defaults to the height of the SWF object minus the controlbar (20px), but if you set it to a smaller height, the playlist will show up. If you set it to exactly the height of the SWF object, the controlbar wil disappear as well.
• transition (fade,bgfade,blocks,circles,fluids,lines,random): This flashvar is only used by the rotator. It sets the transition to use between images. "random" will show all transitions randomly. The default is "fade".
• shownavigation (true,false): Another flashvar only for the rotator. It enables/disables the navigation bar.

COLOR FLASHVARS

• backcolor (color): Backgroundcolor of the player/rotator. In the "extras" folder of this download there's a colorpicker script with which you can pick a color value. The default for the players is 0xFFFFFF (white) and for the rotator 0x000000 (black).
• frontcolor (color): Texts / buttons color of the player/rotator. The default for the players is 0x000000 (black) and for the rotator 0xFFFFFF (white).
• lightcolor (color): Rollover/ active color of the player/rotator. The default for the players is 0x000000 (black) and for the rotator 0xCC0000 (red).

DISPLAY FLASHVARS

• showicons (true,false): Show or hide the play and activity icons in the middle of the display. Defaults to true for the players and false for the rotator.
• overstretch (true,false,fit,none): Defines how to stretch images/movies to make them fit the display. "true" will stretch them proportionally to fill the display, "false" will stretch them to fit. "fit" will stretch them disproportionally to fit both height and width. "none" will show all items in their original dimensions. Defaults to "fit" for the players and "false" for the rotator.
• displaywidth (number of pixels): Instead of the "displayheight", you can set "displaywidth" to a size smaller that the SWF widht, to make the playlist appear at the right side of the display.
• logo (url): Set this flashvar to put a watermark logo in the bottom right corner of the display. If you've set the "link" flashvar as well, the logo will link to there. Again, all image formats are supported, but transparent PNG files give the best results.
• captions (url): You can set this flashvar to the location of a textfile with captions. The players support SMIL's TimedText format and the SRT format used with ripped DVD's. An example of both formats can be found in the "extras" folder of the download. You can also assign captions for every item in a playlist.
• showeq (true,false): Set to true to show a fake equalizer in the display. It adds a nice graphical touch when you are playing MP3 files.
• showdigits (true,false): Set this to false if you don't want the elapsed/total time to display in the controlbar of the players. Quite handy to save some space.
• largecontrols (true,false): Set this to true to make the controlbar twice as large. This is useful to visually impaired users.
• thumbsinplaylist (true,false): If you have a playlist that also includes preview images with the <image> element, you can set this flashvar to "true" to show them in the playlist.
• autoscroll (true,false): By default, the playlist area of the players will have a scrollbar if the number of items is too long. If you set this flashvar to "true", the scrollbar wil disappear and the playlist will scroll automatically, depending upon the mouse position.

FULLSCREEN FLASHVARS

• fullscreenpage (url): The players automatically show a fullscreen button if a user has installed a flashplayer capable of true fullscreen (from 9.0.28). With this flashvar, you can also present a sort-of fullscreen for users who have an older version of the Flash plugin. A click on the fullscreen button will jump to the HTML page you specified here. In this HTML page, you can present a full-browser-screen version of the flvplayer/mediaplayer (just like in the download's example).
• fsreturnpage (url): To let the browser know what page to jump to when somebody wants to close the semi-fullscreen, you can set the "normal" page as the fsreturnpage flashvar. It will be passed through to the fullscreen page with a flashcookie.
• fullscreenmode (true,false): Set this flashvar to true for embedding of the player in the fullscreen page. The player will then get the "file","image","id" and "fsreturnpage" flashvars from a cookie and will present the "normal screen" button in the playlist, instead of the "full screen" button.
• showfsbutton (true,false): Set this flashvar to false to hide the fullscreenbutton, even if flash9 is detected.

INTERACTION FLASHVARS

• id (string): The unique identifier of the file to play. It will be sent to serverside callbacks(see below here, and is also used when using RTMP streams. In the latter case, the "file" flashvar points to the rtmp:// stream, and this "id" flashvar to the precise file to play. You can also assign an id for every item in a playlist.
• link (url): If you have set a watermark logo, you can set this flashvar to a web address you want the logo to link to. You can also assign a link for every item in a playlist.
• linkfromdisplay (true,false): Additionally, you can set this flashvar to "true" to make a click on the image/video display result in a jump to the "link" webpage.
• linktarget (frame): The targetframe a link (from logo, display or playlist buttons) will open into. The default is "_self". Set it to "_blank" to open links in a new window.
• callback (url): Set this flashvar to the location of a serverside script (PHP/ASP) that can process callbacks. The players will send a callback every time an item starts/stops, so you can save statistics with the serverside script. More info can be found in this demonstration page. An example callback script is placed in the "extras" folder of the downloads.
• enablejs (true,false): Set this to true to enable javascript interaction. This'll only work online! Javascript interaction includes playback control, asynchroneous loading of media files and return of track information to javascript.An example of all supported javascript functions can be found on this page.
• type (mp3,flv,rtmp,jpg,png,gif,swf,rbs): The players determine the type of file to play based upon the last three characters of the "file" flashvar. This method doesn't work if you use database id's or mod_rewrite to retrieve the files. Therefore you can set this flashvar to tell the players of which filetype the file you want to play is. The type is also assigned to every item in a playlist. If no match is found, the player assumes it loads a playlist.

PLAYBACK FLASHVARS

• autostart (true,false): Set this to "true" to make the player automatically start playing when the page loads.
• volume (number): The default volume for playback of sounds/movies is 80, but you can set another value with this flashvar.
• shuffle (true,false): If you use a playlist, the players and rotator will automatically shuffle the entries to prevent boredom. Set this flashvar to "false" to play all items sequentially.
• repeat (true,false,list): By default, the players will stop playback after every item to preserve bandwidth (repeat=false). You can set this to "list" to playback all items in a playlist once, or to "true" to continously playback your song/movie/playlist. The rotator's default is "true".
• rotatetime (number): Use this flashvar to set the number of seconds you want an image to display. The default is "10" for the mediaplayer and "5" for the rotator.
• bufferlength (number): This sets the number of seconds an FLV should be buffered ahead before the player starts it. Set this smaller for fast connections or short videos. Set this bigger for slow connections. The default is 5 seconds.
• streamscript (url): This flashvar is the URL of an optional script to use for 'fake streaming' FLV files, eg. through PHP, ASP or LigHTTPD. The parameters 'file' and 'pos' are sent to the script. An example file, "stream.php", can be found in the "extras" folder of the downloads. If you use the LigHTTPD FLV module, set this to the value "lighttpd". Note that all FLV files you want to fake-stream should have an array with keyframe-positions in their metadata! More info and a running example can be found at my site.

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:

* 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:

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:

• Note that, due to security restrictions in the Flash Player, javascript interaction will not work when testing locally. Accessing remote media files or jumping to remote URL's also won't work because of this. Both will work fine if you test from your webserver.
• True fullscreen only works if you have the Flash Player 9,0,28,0 or higher installed. If you use the UFO javascript to embed your player, you can force users to download it. Also make sure you have the parameter "allowfullscreen" set to "true" in your embed code!
• If the progressbar isn't running with your FLV file, or if your video dimensions are messed-up, your FLV file doesn't have correct metadata inserted. You can fix this by using the small tool available at www.buraks.com/flvmdi/.
• If the player plays FLV files on your computer but not on your website and your website is running of an IIS server, then the FLV mimetype isn't added to the server yet. You can check this by typing in the direct address to your FLV file in your browser. If you get a 404, you're on IIS without mimetype. Please contact your webserver administrator on this (if you're an admin, here's how to fix it).
• If you get strange display errors on IE (most notably after refreshing), the Stage dimensions are probably not properly set. You can use flashvars "width" and "height" to force specific dimensions to the player/rotator and fix this problem.
• If you encounter too fast or too slow playback of MP3 files or if your progressbar is messed up, your MP3 files contains variable bitrate encoding. Flash isn't very good at handling these, it's best to stick to constant bitrate encoding. Also make sure to stick to a sampling frequency that is a multitude of 11.025kHz (48kHz, for example, also poses problems). The free iTunes software has a basic, decent MP3 encoder.
• The player/rotator will run quite OK inside the Flash Player 7. However, the following features are not supported: display of GIF/PNG images, smoothing of scaled images/video, VP6 encoded video, javascript control, the black stroke around subtitles and the digits in the controlbar.

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.