ampsig data clients

In addition to your media player, you will need something to POST the song data to ampsig; a data client..

On Linux..

We've put together a Linux data client called signux. The whole thing runs in a shell script you can simply add to your cron and leave it. It utilises the services of the excellent info-pipe plugin for xmms media player (also Beep Media Player), and works really well.

The plugin creates a "named pipe", rather like a UNIX socket, and signux reads the info from the pipe. clever stuff.

signux is included in the ampsig distribution, along with the Windows stuff. (Oh! I hope they don't fight!)

On Mac OS X..

If you are a Mac OS X user, you can use the excellent macsig client for iTunes (pictured above), available here.. http://www.pcheese.net/software/macsig/

On Windows..

On the Windows platform we recommend the AMIP plugin, available here for Winamp, Apollo, QCD, Foobar2000 (fb2k) and iTunes for Windows.

If you are an IRC user, and haven't heard of AMIP yet, you're in for some fun! While you're there, grab the "AMIP jConfigurator" which makes setting up all this nonsense a breeze. (you need the Java Runtime environment installed to use the jConfigurator. If Azureus works on you system, then you already have this, if not, grab it from sun.. http://www.java.com/en/ )

At the time of writing, AMIP doesn't have an internal HTTP client, so it utilises the services of cURL, which is installed on most good computers, but if you don't have it (that's most windows users), go here, and grab a distro for your particular operating system. unzip, and drop it somewhere like.. c:\unix\bin\curl.exe

By the way, if you don't have curl installed on your machine, you're missing out. think of it as a web browser that doesn't need a user. you can script it do all sorts of www tasks that you otherwise wouldn't be bothered with.

If you can't get AMIP/cURL to work on windows, you could try the NowPlaying plugin for Winamp. The range of available variables is much more limited, but NowPlaying is very easy to setup. more information below.

POST variables..

Your data client (AMIP, macsig, signux, NowPlaying, etc) extracts all the song information from the media player, and sends this by HTTP POST request - just like a web browser sending a form - to ampsig (AMIP does this via a cURL)..

It's easy to edit this data to suit different needs. There are also custom fields you can use for any purpose. To function correctly, amp.php utilises and expects at least some of the following POST variables..

note: not every variable is sent for every type of event, see the examples below for guidance.

trick: you can send piece of information to your ampsig at any time. So long as it comes with your valid password, ampsig will update the appropriate field. This might be handy if you wanted to write a wee script that updates only one or two fields, perhaps the custom fields. This script might even be triggered by some other event on your system. This gives us a great deal of flexibility, and possibility.

data client preferences..

The following data clients work with ampsig, click the links to find out how..

AMIP prefs..

AMIP has a huge number of available variables to send.
There's lots of possibilities, apart from the basic "now playing" stuff..

important: because the callback command is being sent to cURL, any strings which contain problematic characters must be "HTML encoded" before sending. AMIP provides a way to do this with the $ue(string) function. Remember that if you add extra data types, etc.

To tell AMIP what variables to send, go into the AMIP jConfigurator, "Other Integrations" preferences, "Callbacks/Web". In the first tab ('Play') enter the following command (all on one line)..

play:

replacing the fictional URL at its end with the real valid URL of amp.php on your publicly accessible web server. Enter your own username/password (update code) too, and set these same in the global prefs inside amp.php (if you are hosting your own sig). if your copy of cURL isn't at c:\unix\bin\curl.exe, replace that part with its real location, obviously.

If you are hosting your own ampsig, instead of "http://my.ampsig.com/username" you would use "http://mydomain.com/path/to/amp.php", same with the other callbacks..

The other web callbacks will probably look something like this..

pause:

stop:

start:

which is a bit pointless, the data is about to be overwritten any second!
much better use for 'start': if you are using uTu, you could have a 'start' preset like this..

better start:


now you can make use of the 'uptime' variable and have your computer's uptime right there in your ampsig!

exit:

you can fine-tune these strings to suit your particular requirements, add more, whatever, but it's probably a good idea to start with these known working strings. note: you don't have to send position ('pos') data with stop/exit, but if you do, ampsig will remember the last position and keep the progress bar there even after you exit Winamp. nice, and optional.

AMIP tips:

• you can override the AMIP jConfigurator's default font and use a nice monospaced font like Lucida Console or ProFont; makes editing the callbacks a great deal easier.
  
• the "~" (tilde) characters in the callbacks are removed (by AMIP) before sending, which enables you to put text directly after values in your callback. eg. %br~Kb/s for "256kb/s"

"NowPlaying" prefs..

NowPlaying is similar to AMIP, but differs in three fundamental ways..

• It's very easy to setup. (this is Good)
• It does its own HTTP POST (no cURL required, this is also Good)
• It sends an extremely limited number of variables, and in "unusual" formats. (this is Bad.)

But if you can't get AMIP/cURL to work, NowPlaying might be for you. To setup..

In the general preferences, set the three inputs to "1" (no quotes), that is, song history, frequency, and 'update after'. Then go to the "HTTP Post" tab and enable HTTP Post. Enter your ampsig URL into the URL input (probably port 80) and in the "extra data" input, put something like this..


You can enable, disable, do other stuff via NowPlaying's cool taskbar icon. Sure, it can't send nearly as many variables as AMIP or macsig, but you can still have a nice ampsig with a cool progress bar.

note: NowPlaying doesn't send events for pause, so don't expect to have your progress bar do anything except follow a song playing all the way straight through. If you pause the track, the progress bar will keep on going! It resets when you play again, of course.

Also, with NowPlaying, you can only update one URL at a time (most folk won't be limited by this). Also, if you want to display uptime information, you will need to run uTu separately. A simple shortcut will do the job (one is included). Edit the shortcut's "Target" field to something like..


replacing "PASSWORD" with your own password (or update code if you host with us). If you host your own, it would be..


and drop into your Windows startup items, or wherever. You might want to customise the shortcut further, run minimised, etc. your call. It only needs to run once on every reboot, or whenever you feel your webserver's clock has drifted too far. It's simply a "sync".

So there you are, if for whatever reason you can't get AMIP/cURL to work, NowPlaying is there as an alternative. Future versions may even have more useful options, too, we hope. Alternatively, it would be good to get a copy of the source! *wink*

macsig prefs..

You lucky lucky Mac users!!!

Like most Mac applications, macsig is very easy to setup, but if you have any queries, the answer will most likely be here..

http://www.pcheese.net/software/macsig/documentation/

If you have any questions about macsig, its preferences, or even (*gasp!*) any bugs to report, head along to the forum, PCheese is usually hanging around somewhere.

signux prefs..

signux is the Linux ampsig data client.
This script will be fairly straightforward for most Linux users.

Briefly, you need to first alter the preferences inside the shell script (open in any text editor, set your password, URL, etc), and then make a cron job for it. Something like this would do the trick, executing signux every minute..


or, exactly the same timing (in a slightly different format), but this time with the output logged - crazy!


or something along those lines. Alternatively, you could put the signux code inside some perpetually looping shell script and drop into your startup sequence (I might put together one of these).

There is more documentation inside the signux package itself (in the main ampsig distribution), and if there's anything still confusing or whatever, feel free to ask questions, even daft ones, on the forum.

That's it!

If all goes to plan, ampsig will remain perpetually updated of all changes in your media player, and publish this information as a cute dynamic signature image to anyone who asks.