XSPF/PHP Installation guide

Welcome to the 0.14 release of xspf/php released May 1^st 2009
Available here: http://www.trbailey.org/files/xspfphp.zip

This version has several improvements including playlist caching to / from a MySql database.

• Autogen finds directories with mp3 files and creates xsfp.dir
• Significant improvement in player.php makes it easier to customize player and playlist URL
• Info element can be configured in xspf.dir OR set to use file url, provides download button in the player. See xspf.settings.php
• Esoteric <link rel=".."> element can be added for entire playlist
• Mysql caching. significantly reduces playlist generation time, especially on large playlists.
• Updated xspf stylesheet applies html formatting to the raw playlist for easier reading.

Quick install:

1. Create a new web accessible directory on your server. EXAMPLE: /home/user/public_html/music

2. Unpack the archive to a local directory

3. Create xspf.dir, a list of your music directories on the server with their companion URL and an optional info element URL
This version includes an autogen for the xspf.dir file. Use it if you have a music directory containing many subdirectories or don't want to mess with editing via ftp.

Autogen Usage:
Upload xspf.autogen.php to your web accessible music directory.
Navigate to it in a browser.
Autogen traverses the directory tree, generating full path's and URL's for each path for directories containing mp3 files below where it's run.
The output is saved as auto.xsfp.dir in the current directory. Rename and optionally edit auto.xspf.dir to xspf,dir in your xspf installation directory (the one you created in step 1). Now DELETE or rename xspf.autogen.php when you are finished to prevent hackers abusing your bandwidth

You can also add the following to your xspf/php installation .htaccess to prevent unauthorized access.

<FilesMatch "settings\.php$|autogen\.php$">
Deny from All
allow from 127.0.0.1
</FilesMatch>

Manual xspf.dir creation:
Create a new text file with one line for each server directory you want to scan for music or video files. Each line should contain both the local server path to the directory and the URL used to access that directory separated by a comma. Save it as xspf.dir in the same directory.

4.Open original.xspf.settings.php in your favorite word processor.
Optionally edit values below and save it as xspf.settings.php

Edit red items below to fit your needs then save it as xspf.settings.php
I recomment you enable caching or the playlist generation is slow and uses excessive server resources.

---

xspf.settings.php options.

Set $link to true to include info element
Set $info to false if you want users to be able to download your files using the player link
Optionally set $linkuri to a uri, activated when user clicks player in some players, does nothing in JW player
Add info link in xspf.dir file if you enabled $link above

To enable database cacheing, create a new MySql database.
You can use an existing database provided you have permissions to create_tables.
Set $cached = true
Edit the $db values to reflect your database host, name user and pass.
Tables will be created in database if they don't exist.

$dbhost = 'localhost';
$dbname = 'xspf';
$dbuser = 'dbuser';
$dbpass = 'dbpass';

Complete list of settings, some of these are new as of 0.14.
$version = 0.14 //This is svn version 0.14
$cached = false; // cacheing is OFF by default
$comments = false; // Display comments in playlist. This adds a <!-- comment block --> in the heading and around each track.
$id3path = 'id3/getid3/'; // the path must point to the server directory where the id3 directory exists. It must end in a "/"
$encoding = 'UTF-8'; // Generally you can ignore this. It's here for testing and debugging of special languages.
$link = false; // include an info and link element to the location reference. =
$info = true //true = info link from xspf.dir, false info link is file url
$linkuri = 'http://xspfphp.sourceforge.net/' // Default value for <link rel="..." /> element
$html = true; // Attach html stylesheet for viewing the playlist in a browser.
$htmlref = 'html.xsl'; // URL or path to html.xsl. Defaults to current directory. Can also be used for external xsl sheet. See: http://gonze.com/xspf/ for more stylesheets.
$annotate = true; // Add <annotation> element with comments, default ON.
$debug = false //Debug mode, displays current settings as comment
$sort = 'true'; // Hack sorts each directory by file name prior to playlist generation

// $DirFile contains the path to a text file of valid directory names to search
$DirFile = "./xspf.dir"; // Normally you won't need to change this.

Uncomment one of the options, or create your own. Make sure you end the value with a "$" and use a "|" if you use multiple regex values.
$ft = "mp3$"; // scan for mp3 files, this is the default
//$ft = "flv$"; // scan for flv files
//$ft = "wma$|mp3$"; // scan for wma and mp3 files
//$ft = "mp3$|wma$"; // JW player won't play WMA files but this works for desktop media players.
This program uses POSIX style regex matching
see: http://us3.php.net/regex

5. If this is a new installation copy or upload the contents of the entire archive to your web accessible xspf installation directory.
If this is an update, just copy or upload xspf.php and xspf.settings.php
The sample player should work if you've followed these instructions.
Please provide feedback to siggma@trbailey.net

Player.php

Included with this package is a short embed script named "player.php". When executed it will generate simple embed code that can be copied and pasted to a web page, included as an iframe or embedded directly using an object block. I've created a sample page you can use to see the basic script in operation here. This is a whimsical feature that may or may not be kept up to date, depending on feedback. So if you have an opinion, send feedback.

The script reads player.ini to generate the embed code. Player.ini contains nearly all of the settings available for the standard freeware JW player, included in the archive. See PLAYER.PHP SAMPLE

Installation is not necessary provided player.php is in the xspf directory.
You can create multiple copies of player.php to for embedding different players in different sites.
Example:

$cp player.php nodoubt.php
$cp player.ini nodoubt.ini

The script will look for an ini file with the same name as the script. Now you can reference nodoubt.php from any web page like below.

<object id="nodoubt.php" type="text/html" data="http://yourdomain/yourxspf/nodoubt.php" width="610" height="300">
<p>Oops! That didn't work...</p>
</object>

Now you can edit nodoubt.ini to change the settings or easily customize the player as it appears on a remote web page.

Known issues:

Filename replaces tags in playlist :
I see the filename, the words "no album" etc. in the playlist instead of the tag contents even though I know it's a usable tag. In some situations the tags are not correctly cached for id3 v2.x tags. This issue seems to be prevalent in some newer mp3 files. The issue seems to be the tag itself and how it's written. The easiest way to correct the issue is to use the get_id3() tag editor to read and write the tags on offending files. The current distribution does not contain the tag editor so you'll have to download it and install it separately. To install it follow these instructions.

1. Download the getid3 archive from here or update to svn 33 or later.
   $svn update or $svn co https://xspfphp.svn.sourceforge.net/svnroot/xspfphp
2. Unpack it locally or edit directly via ssh.
3. Edit id3/demo/demo.browse.php and id3/demo/demo.write.php, commening out line 16 in both.
4. *Upload the entire "demo" directory, to your xspfphp/id3 directory
   *not necessary with svn update
5. In a browser, navigate to http://yourdoman/xspfinstall/id3/demo/demo.browse.php
6. Change the path at the top of the demo editor to the location of your mp3 files.
7. Use the "edit tags" link to read the files that don't cache correctly, then press SAVE at the bottom. This correctly writes the mp3 tag so that get_id3() can read and cache it.

You might also try using EasyTag. It comes in a flavors for Linux, Windows and OSX.

Adding custom album or track images:

The default "no image" image is rather droll. You can upload an album image named "-noimage.jpg" to each music directory and it will appear on all tracks. Default image for entire playist is -noimage.jpg in the installation directory.

To add a custom image for individual tracks, upload the custom image naming it exactly the same as the .mp3 file for that track with a .jpg extension. Regerate the player and that image will appear with that track. Many players are now able to extract the album art from the file so this project probably won't ever include the overhead of extracting and caching images.

Additional Links & Info:

XSPF/PHP is FREE software. Currently it is not covered by a GPL license. It is gifted to the people of the world for any use and may be modified and distributed in any way whatsoever for any purpose. This means it can be copied and used indiscriminately for commercial ventures. Just don't mention me if it's unscrupulous.

HOWEVER:
The JW Player distributed with this package may require a license if you use it to display ads or for any commercial use. Please read JW Player FAQ and Licensing and the Creative Commons License to determine if you need to purchase a license.

The id3 php class is distributed under GPL. See "id3/license.txt for licensing information for the id3 php class.

Links:
XSPF.PHP Embedding Examples
JW Player Embedding Wizard
File Thingie Great for uploading music from your browser
PHPDL Great for listing and viewing files on server using your browser