Instructions : DNeX FMP256 Flash Audio playhead FREE VERSION

It is important that you read and agree to this License Agreement before using your software.

Many thanks for choosing to use a product from Draftlight Networks. Your software is part of our range of FMP256 Flash Audio Playheads, and plays MP3 format files from an HTTP server or servers. It collects a list of music files by reading a playlist, which can be in either XSPF or Extended-M3U format. All of the startup settings are controlled by an XML configuration file. The playhead itself is a single, small Flash 8 document that can be embedded into your website with ease, and is compatible with any web browser or handheld device that supports the Flash Player 8 plugin.

This free version is limited to playing only the first six tracks in a playlist, and has a simple "play-pause" button rather than the full transport control panel that features on our commercial playheads. The LCD display gives track download status, number of available tracks and current playback time, but does not display track titles.

UPLOADING FILES

You must ONLY upload the '.swf' file, your xml playlist, configuration file and your music tracks. Do NOT upload any files from the DOCUMENTATION folder. Before uploading the configuration file, you'll have to edit it - it's a text file, so you can use any text editor program.

The configuration file

This will be loaded from the same website folder as the SWF file, and using the same name as the playhead (but with an XML extension). For example, if the playhead is available at

http://www.mywebsite.xx/music/fmp256.swf

then the configuration file must be at

http://www.mywebsite.xx/music/fmp256.xml

The file contains XML data that defines all of the startup parameters for the playhead (autostart, volume, etc) and of course the location of the playlist itself. The configuration file must be present, and must have a playlist defined, or the playhead will stop and display an error.

A sample configuration file is shown below:-

• The first two lines are essential, and defines the file XML namespace. Please don't alter them.
• Line 3 defines startup settings, and is required.
• Line 4 defines a playlist URL, and is required.
• Line 5 closes the config structure, and is required.

The <init> tag

The parameters in an init tag are as follows (some may not influence your particular playhead design):-

• autoplay A single digit ["0" or "1"] defines if the playhead starts playing track 1 as soon as it loads. Default is "0".
• volume An integer ["0" to "100"] setting the initial playback volume. Default value "100".
• continue A single digit ["0" or "1"] to define the action when the last track has been played. Default value "0".
• shuffle A single digit ["0" or "1"] sets if the playlist should be shuffled after every use. Default value "0".

The <playlist> tag

This contains a relative or absolute URL linking to a playlist. There should be only one playlist tag per configuration file. The opening tag has two parameters:-

• type Either "m3u" or "xspf", defining the expected playlist contents. Default is "xspf".
• media Either "audio" or "video", defining the expected playlist contents. Default is "audio". This playhead can only play audio files, however other designs support both audio and FLV video playlists therefore the media type must be defined.
• static A single digit ["0" or "1"] defines if the playlist is always the same. Default is "1". If this is set to "0", the Skipjack engine and shuffle-mode are both disabled. If your playlist changes (for example if it is generated by a script) it is vital to set this parameter to 0. Skipjack will fall over and weep if the tracks in the playlist don't match what it expects. Dynamic playlists are recollected after the last entry plays out - static playlists are only downloaded once.

Playlists

The playlist will read details of the MP3 files from a playlist (a text file). It will support two of the most common formats - XSPF and Extended-M3U. The location of the playlist, and the type of file to be read, is defined in the configuration file (see above). The playlist can be loaded from anywhere on the web, provided you ensure the server hosting the playlist has provided a policy file permitting access.

Click here for info on XSPF playlists .. or .. here for info on E-M3U playlists

The free version of the playhead is limited to only six tracks, even if your playlist is longer.

Error codes

The free version of the playhead displays a short error code in the event of a problem, as follows:-

• ERR 1: Configuration file cannot be found
• ERR 2: Configuration file exists but has errors
• ERR 3: Playlist file cannot be found
• ERR 4: Playlist file exists but has errors
• ERR 5: Playlist empty (All MP3 tracks are unavailable or faulty)

See below for details of our extendedReporting engine and how to troubleshoot your setup without needing a copy of the Flash 8 IDE!

What your website users will see and do...

The player will show an error and disable itself if the configuration file or playlist file cannot be opened. If a user has an older version of the Flash player, they will be prompted to update.

When the playhead first starts opening a track, it will begin playback as soon as enough data has loaded - this usually means about 5 seconds of audio. Once the track has downloaded once, it is stored in memory on the user's computer and so is not re-downloaded if they listen to the track repeat (except where the webserver delivers the MP3 file with a special No-Cache header, which frankly is a silly thing to do).

If a track cannot be loaded (the MP3 file is unavailable) the playhead will remove it from the list and try the next file. If it ends up with only one valid track, it will turn on looping and replay that track over and over. If it finds NONE of the MP3 files can be loaded, it reports an error.

If a track has an tag, then a button becomes a clickable link to the website URL given in the tag.

The Skipjack Engine

All our playheads support Skipjack™, our world-leading playback session control system. Whenever a user is listening to a static playlist, Skipjack continually records the exact track and position information. If the user navigates to a different page on your website and reloads the playhead with the same playlist, Skipjack automatically finds the correct track and position, and begins playback. It also remembers volume and mute settings. Skipjack stores information on the client computer, not on your website - so requires no extra work on your part.

Users normally have up to 30 seconds between navigating away and returning before Skipjack erases the track memory. If the playlist is not static, or has changed in the configuration file, then Skipjack is disabled. You should use Skipjack with caution if the server delivering your MP3 files uses No-Cache headers, as users will face a long delay as the track reloads from the beginning. No-Cache headers on MP3 data are pointless unless you're trying to track plays - and in that case you really should be using streaming servers.

INSTALLATION

First, if you want to rename the playhead SWF file then change the name of both the SWF file and the XML configuration file as well - then open the configuration file in a text editor (Notepad, VI, etc. - NOT a word processor) and edit it to define your startup options and playlist as we have described above.

Next, create your playlist (unless you are loading an existing playlist from another website). We suggest using the XSPF format if possible as it provides more information. Playlists in eM3U cannot for example contain links to websites.

Now, all you need to do is upload the SWF and XML files to your webserver, then put the code into your web pages to show the Flash player on your site:-

Embedding the playhead into a web page

We have included an example page, called EXAMPLE.html, which shows you the code for your chosen design. You can edit that file, or copy the entire OBJECT section into your own page. Our example page uses the Flash Stirfry method of defining a Flash object inside HTML, which offers the best compatibility and search engine performance for our software.

ADVANCED INSTRUCTIONS

The following instructions are normally not required for basic use of the playhead. users wishing to change some of the default settings should read on..

Changing the configuration file

By default, the playhead looks for a file called 'XXX.xml' where XXX is the player's own filename. If you generate your configuration files dynamically using PHP or ASP, then you will need to tell the playhead to load this new URL. This is done by adding a special variable to the page code, both in the OBJECT and the EMBED tags. If we wanted to tell 'player01.swf' to open a configuration file called 'dynamic.php', then you need to add this line to the OBJECT param list:-

<param name="flashVars" value="config=dynamic.php" />

and in the EMBED tag, add the variable definition

flashVars="config=dynamic.php"

You can specify any filename, but if you wish to use a URL containing non-alphabetical characters you MUST URLencode the name using RFC2396. For example, if your configuration file is at

http://www.myfiles.com/radioplayhead/config.php?music=madonna

then the URLencoded version is

http%3A%2F%2Fwww.myfiles.com%2Fradioplayhead%2Fconfig.php

There is a simple encoder-decoder available HERE.

With Flash Player 7 and above, enhanced security prevents a Flash document from loading data (XML or M3U) from another website unless that site has given permission. This means that the server hosting your configuration and playlist files must also publish a small XML file called "crossdomain.xml", that informs the Flash Player that they allow others to read their data. If this file is missing, your FMP256 playhead will display an error.

This is only a concern where the PLAYLIST or CONFIGURATION FILE are on a different website domain to your SWF playhead. If they are on the same domain, then a policy file is not needed.

For example, if our playhead is at

http://www.mysite.com/users.smith/fmp256.swf

Then it tries to load a playlist from

• http://www.othersite.com/playlist.m3u - Policy file is needed
• http://mysite.com/playlist.m3u - Policy file is needed
• http://123.456.789.0/playlist.m3u - Policy file is needed even if this points to www.mysite.com
• http://www.mysite.com/playlist.m3u - Policy file is NOT needed

Policy files are not needed to access MP3 data, but are needed for track images. For more information on the format of a Policy file, CLICK HERE.

Dynamically changing the playlist with JavaScript

All our playheads support live updates to the playlist (so a series of playlists can be selected by a listener without navigating to a new web page. To implement live playlist updates, add the following JavaScript to your page AFTER the Flash object:-

To change the playlist, an HTML hyperlink is used with a JavaScript event connected to the click, as below:-

The parameters to this function call are the playlist file name, the type ('xspf' or 'm3u'). The third parameter is not used on the free playhead. The example page supplied with your software shows this process in action - it is important to remember that the JavaScript functions MUST appear later in the page than the playlist's container.

DEBUGGING

All our playheads support the Draftlight extendedReporting engine. If you try to debug the playhead via the Flash 8 IDE, you will usually hit problems with access to your configuration files and media (security sandbox time!). However, the playhead reports all activity and errors via the external API, so a detailed log of progress can be collected by JavaScript - live on your server. To implement extendedReporting, add the following JavaScript to your page's HEAD section:-

Then, somewhere out of the way on your page, add a textarea like this:-

Now you can see exactly what's going on, or what's going wrong! Remember to remove the above code before letting your visitors loose on your page - it's not a security risk, but it may confuse them.

IMPORTANT NOTICE: COPYRIGHT OF AUDIO FILES

You are solely and entirely reponsible for obtaining the permissions, licenses and agreements needed to play audio files on your website. We accept no liability for the music you play, and any license or intellectual property infringements you may make. ALL commercial music is copyrighted and you MUST buy a license from the songwriter, record label and/or Performer Rights agency before you can put music on a website, unless you are the sole owner of all such rights. Normally if you have written the music yourself, including all scores and lyrics, have performed it yourself and have not signed any agreement with a record label, you are the rights owner and need no extra permission. For cover versions or sampled works, you DO need permission. For detailed info on copyright and licenses, see our online guides at http://bandfoundry.draftlight.net/resources/copyright/. Draftlight do not supply licenses on behalf of our clients and will not assist in obtaining them.

All content ©2005-2006 Draftlight Networks all rights reserved. Skipjack™ and the FMP Logo are trademarks of Draftlight Networks.