[the torrez winamp plugin thing]

What is it?

[the torrez winamp plugin thing] is a plugin for media players (Winamp, Itunes coming soon) which logs the content and posts results to a webpage, through a database. This means you can list the tracks you and your friends have most recently played, and later sort them by user, popularity, or anything else you can think up.

The software has 3 components for you to adjust-- the plugin, the database, and the output scripts.

The plugin

You will need to create a file in your winamp plugins directory (probably C:\Program Files\Winamp\Plugins) called "plugin.ini"

Paste the following into it:

[submit]
pingURL=http://yourhost.com/songplayed.php?artist=%%ARTIST%%&song=%%SONG%%&username=yourname&userid=yournumber

Replace yourhost.com/songplayed.php with the host and display script you will be using. Replace yourname and yournumber with your username and usernumber, if desired.

for Filepile users, this would look like:

[submit]
pingURL=http://www.filepile.org/songplayed.php?artist=%%ARTIST%%&song=%%SONG%%&username=JanDevries&userid=000

given that your username is JanDevries and your usernumber is 000.

The database

This is a mysql database which the plugin will contact and store the track info. It has to be set up manually but don't worry, its not so bad given you have shell access and mysql installed.

The display scripts

These are the web pages which pull the info out of the database and tell it how to be displayed. If you do not know php, an example of a simple display is provided below.

Examples

The left sidebar on this page is an example of this plugin in use. You can see the last few songs played.
A rough collaborative list is at http://www.filepile.org/songs.php
See statistics in action at http://torrez.org/songs_played.php

Installing

Requirements

You will need slight familiarity with mysql, PHP, HTML, and Cascading StyleSheets (or advanced ability to RTFM). This is not automatic software, but it is also not very complex. A bright person with no PHP or SQL experience could still set this up, but it might be nice to have help available. If you have used a unix command line before, but have no mysql or php experience, you are probably good to go.

You will of course need a host on which to run this. The host will need to support PHP and creation of mysql databases. You will also need either shell access, or an extremely helpful/ friendly sysadmin.

1. Download and install the latest version of [the torrez winamp plugin thing] from:
 
torrez.net

There is nothing to configure for the plugin, just let it do its thing.

2. Set up the database

You can name the database anything you want.

Create it like this:

From your shell, start up mysql. Contact your sysadmin if you are unsure how to do this.
mysql> create database theplaylistdb;

Set "theplaylistdb" to whatever you want to call it.

Next, consider this data schema for a moment:

+-----------+-----------------------+------+-----+---------+----------------+

| Field     | Type                  | Null | Key | Default | Extra          |

+-----------+-----------------------+------+-----+---------+----------------+

| id        | mediumint(8)          |      | PRI | NULL    | auto_increment |

| artist    | varchar(50)           | YES  |     | NULL    |                |

| song      | varchar(50)           | YES  |     | NULL    |                |

| play_date | timestamp(14)         | YES  |     | NULL    |                |

| username  | varchar(25)           | YES  |     | NULL    |                |

| userid    | mediumint(8) unsigned |      |     | 0       |                |

+-----------+-----------------------+------+-----+---------+----------------+

If it makes no sense to you, fret not. Do try to understand the following, however.

Field	Description
id	This is just for the db to keep track of itself. Note that this is the primary key, but if that means nothing to you, don't worry.
artist	The artist from the id3 tag (or filename, winamp will try to guess)
song	Same as above for song title
play_date	When the track was played, or more accurately, when the record is created. Filled in automatically.
username	Optional for multiuser systems (collaborative playlist).
userid	Optional for multiuser systems, provides a simple way to link to someone's profile page, etc.

You are free of course to add any other info you want, but your php script and plugin.ini file will need to be adjusted.

Next you need to create a table called "songs_played". You can change this name, but you will then need to adjust the sample scripts.

mysql>\g CREATE TABLE songs_played ( id mediumint(8) DEFAULT '0' NOT NULL AUTO_INCREMENT PRIMARY KEY, artist varchar(50), song varchar(50), play_date timestamp(14), username varchar(25), userid mediumint(8) unsigned NOT NULL)
 
Thats all there is to setting up the DB!
 
Now to make sure its set up correctly, run this command:
 
mysql>describe songs_played;
 
and it should pull up an illustration like the schema above.
 
To preemptively help troubleshooting, you can add a line of data to it:
 
mysql> insert into songs_played set [hit enter]
->artist = 'Andre Torrez',
->song = 'Stairway to Heaven',
->username = 'janDevries',
->userid = '000';

 
Then, to make sure its there,
 
mysql> SELECT * from songs_played;
 
You should see the data you entered above.
 
This way if the webpage doesn't work, you will know its the output script and not the database.
 

Setting up the PHP scripts

 
You will need at least 2 web pages. One will take the info from winamp and write it to the database, the other(s) will display the results.

You are going to need to know your mysql username and password and how to add this to a file, so if that doesn't make sense, it is a good time to talk to your friendly sysadmin. Promising some beer for helping out smooths these transactions considerably.

You can either create the following locally in a text editor (notepad, homesite, interdev, etc) and upload them, or you can work directly on the server (you do have shell access, right?).

In your web folder, create a file called "songplayed.php"

Using whatever text editor you have (vi, pico, emacs, etc) add the following:

<?php
$lnk = mysql_connect("localhost", "SQLUSER", "SQLPASSWORD")
or die("Could not connect: " . mysql_error());
mysql_select_db('DBNAME', $lnk) or die ('Can\'t use foo : ' . mysql_error());
$sql = "insert into songs_played (artist, song) values ('".$_GET['artist'] . "', '" . $_GET['song'] . "')";
mysql_query($sql);
?>

Thats it for the datawriter. You will need to of course replace SQLUSER, DBNAME and SQLPASSWORD as appropriate. You might probably want to set this as an external file and load it as an include, if you don't know what that means and your friendly sysadmin didn't tell you to, don't worry about it.

Now you need to add the file to display the results from the db.

Make another new file called "songs.php".

Here's what it should contain:

<html>
<body>
<font face="arial">
<?php
$lnk = mysql_connect("localhost", "SQLUSER", "SQLPASSWORD")
or die("Could not connect: " . mysql_error());
mysql_select_db('DBNAME', $lnk) or die ('Can\'t use foo : ' . mysql_error());
$sql = "select artist, song, play_date from songs_played order by
play_date desc limit 100";
$res = mysql_query($sql);
print "Songs played:\n<br />";
print "\n<br />";
while(list($artist, $song, $play_date) = mysql_fetch_array($res)){$theTime = strftime("%A %b %d at %r", mktime(substr($play_date, 8, 2),substr($play_date, 10, 2),substr($play_date, 12, 2),substr($play_date,4,2),substr($play_date,6,2),substr($play_date,0,4)));
print "$artist - $song [$theTime]\n
";
}
print "\n";
?>
</font>
</body>
</html>


Of course the SQLUSER, DBNAME and SQLPASSWORD need to be updated again, unless of course you are using the handy include technique. Anyway.
 
Now make sure you have your plugin.ini file set up, play a song in winamp (you have to let it go to 72% through the playback (no cheating!), point your browser to the page "songs.php" (http://yoursite.com/songs.php) and you should see your listings come up.
 
The above example script does nothing with the username or userids. It also does nothing with the formatting other than set the font to arial and add a break to the end of each line.

Now, that is a fairly simple page, and you probably want to do something a little more complex. You will need to get somewhat comfortable with php scripting (or perl, or whatever you prefer). However, this sample should be fairly clear, and is easily customizable without touching the php code:

<html>
<head>
<title>Songs Played</title>
<link rel="stylesheet" href="songs.css" />
</head>
<body bgcolor="#cccccc">
<h2>The Playlist</h2>
<?php
$lnk = mysql_connect("localhost", "SQLUSER", "SQLPASSWORD")
or die("Could not connect: " . mysql_error());
mysql_select_db('DBNAME', $lnk) or die ('Can\'t use foo : ' . mysql_error());
$sql = "select artist, song, play_date from songs_played order by play_date desc limit 100";
$res = mysql_query($sql);
print "\n<br /><table class=\"playlist\">";
while(list($artist, $song, $play_date) = mysql_fetch_array($res)){$theTime = strftime("%A %b %d at %r", mktime(substr($play_date, 8, 2),substr($play$ print "<tr><td class=\"artist\">$artist</td><td class=\"song\">$song</td><td class=\"timestamp\">[$theTime]</td>\n</tr>";
}
print "</table>\n";
?>
</body>
</html>


You should be pretty familiar with changing DBNAME etc. by now. You also know about the wrapping lines (it either doesn't matter for you or you have learned to fix it already). So what has changed here? Two important things. A link to a stylesheet, and a table structure.

The php starts a table, then a new row for each playlist entry. Each element (artist, song, time) is given its own style, set on the <td> level.

The style sheet will need to look like this, and be called "songs.css". It should be in the same folder as the above php file, or you will need to adjust the line containing hte link to it.
 
h2 {
font-family:arial;
font-size:14px;
text-align:left;
color:#333333;
margin-top: 10px;
}
 
table.playlist tr td{
background-color: #eeeeee;
padding: 5px;
}
 
.artist {
font-family:arial;
font-size:12px;
text-align:left;
color:#669966;
}
 
.song {
font-family:arial;
font-size:12px;
text-align:left;
color:#88bb88;
}
 
.timestamp {
font-family:arial;
font-size:12px;
text-align:left;
color:#bbbbbb;
}
 
.user {
font-family:arial;
font-size:12px;
text-align:left;
color:#ccff00;
}
 
.userid {
font-family:arial;
font-size:12px;
text-align:left;
color:#ccff00;
}
 


This yields a very plain page, but now it is easily customizable without touching the php. The colors listed above are pretty bad, they are just in there to show how each column is adjustable. Also notice that styles are there for user and userid, this is just to make it easier later if you do decide to use them.

Soon there will be examples of a sortable playlist, top 20 feature, etc.