Do Something Winamp Plugin Version 2.11

oddsock@oddsock.org

• Do Something Binary Distribution (PiMP Installer)
• Do Something Source Distribution (A VC++ 6.0 Project)

Release 1.1 Notes

Release 1.2 Notes

Release 1.21 Notes

Release 1.22 Notes

Release 1.23 Notes

Release 1.30 Notes (5/26/2000)

Release 2.0 Notes (6/12/2000)

Release 2.1 Notes (7/7/2000)

Release 2.2 Notes (7/13/2000)

Release 2.3 Notes (7/27/2000)

Release 2.4 Notes (8/16/2000)

Release 2.5 Notes (10/10/2000)

Release 2.6 Notes (10/16/2000)

Release 2.7 Notes (11/07/2000)

Release 2.8 Notes (2/07/2001)

Release 2.10 Notes (5/15/2001)

Release 2.11 Notes (1/7/2002)

What it is :

A Winamp General Purpose Plugin which is geared toward Shoutcasters. Whenever a song changes (or predetermined time interval) this plugin is responsible for doing "something". The somethings that are supported are as follows :

1. Submit A URL
2. FTP A file
3. Generate an HTML Playlist (Just like MusicTicker)
4. Run a command
5. Gather XML Statistics (this uses the Shoutcast XML admin interface to gather statistics about your broadcast, you can then use tags to substitute this information into any of the above actions)

Long Description:

I have been a pretty loyal user of Shoutcast for the last year or so and found that this product is most excellent for the type of broadcasting that I do. And there are alot of helper apps out there (well, maybe not *alot*) that you can use to help you in your broadcasting stuff that you do...Well, I started out with wanting to just submit a URL on song changes in Winamp. I wanted to call a CGI script and pass it in the song info so that I could publish a "What\'s Playing" type webpage as well as have the script keep track of songs played, etc... Well, things kinda ballooned from there and pretty soon I was wanting to generate HTML templates on song changes (since MusicTicker has seem to gone the way of the Mastadon), and then wanting to FTP the generate file somewhere, then I wanted to put a listener count (I use Live365 to relay my broadcast) in the Generated HTML file too, well...a week or so later, DoSomething was born. My first attempt at a Winamp Plugin and my first voyage into the incredible world of straight MFC programming (ugh). Since it\'s "birth" DoSomething has been updated and updated, with more and more tags supported. There is now an appendix which shows all the possible tags that you can use for your actions. The XML shoutcast admin interface has been integrated in as well, so now you have those tags at your disposal as well.

As an added feature I have added the ability to perform playlist monitoring. This allows you to set certain bounds on your playlist and have DoSomething monitor and enforce these bounds.

Using this plugin you build a list of actions that are done when the song changes in Winamp. Actions can be repeated any number of times in any order, but keep in mind that you probably don\'t want to do *too* much, since if it takes 10 minutes to do all your defined actions and your songs are only 5 minutes long, it won\'t take long for things to get behind. You are warned. :)

More importantly, information retrieved from one Action is carried over into the next action..So if your first action is to get a listener count from Live365, you can use this information in the next action (or any after that)..Any information gathering action (Get Listener Count, XML Statistics) stores it\'s information in persistent memory.

DoSomething allows you to therefore set up the execution of a potentially infitine series of "stuff" whenever the song changes in Winamp (or at predetermined time intervals - see Release 2.2 for the details). The following is a list of the things that you can do, and also a bit about how you can use it to do some really funky stuff..

1. Run A URL

This is a very powerful thing. This allows you to execute a URL when a song change occurs in Winamp. Right now you can specify 2 tags on the URL that DoSomething will substitute with values. They are as follows :

%%SONG%% - Substitutes with the current song (substituting reserved HTTP characters such as " " with "%20", etc.)

%%LISTENERS%% - Substitutes with the listener count from the previous running of "Listener Count From Live365".

%%NEXTSONG%% - Substitutes with the next song in the playlist(substituting reserved HTTP characters such as " " with "%20", etc.) Note this will *only* work if you are not using shuffle or random play, otherwise this info will be incorrect.

There are *more* tags now supported in version 1.2. See the release notes for the info.

And even *more* tags now supported with the XML statistics...See the appendix for all the tags you can use with SubmitURL.

Some uses of this feature :

• Execute a CGI script and pass in song info to it to track song plays.
• If you are a member of Shoutclub.com, then you can use this feature to update their directory with "currently playing song info" See (here) for more info on this.

2. Generate An HTML playlist.

This will generate an "most recently played" playlist based off a supplied template.

The idea here is you create a HTML file any way you want and put in the following tags (in the table below) and DoSomething will replace the tags with the appropriate values. Note that in order to support the tags %%LISTENERS%% and %%TOTALLISTENERS%% you must first have executed the "Get Listener Count From Live365" *before* you run this action. This also applies to the XML tags (you must execute a Gather XML statistics before you can use the XML tags).

Also, the %%LASTURLRESPONSE%% tag is unique as it is another way to pass data between actions, this tag will get replaced with the response from the previous SubmitURL command. Think of this kinda like a SSI (Server side include).

Table of supported tags :

The tag index as been moved to an appendix.

I will be including a sample template.html file that can be used as a guide.

3. FTP a File

This is pretty much self explanatory. Normally I guess you would run this action right after the "Generate a HTML Playlist" action so that you could upload the file you just generated. Note that you can chain any number of these actions together, so you could put 2 FTP a File actions back-to-back in order to ftp the same file to 2 locations. (kinda neat huh ?)

4. Run A Command

Again, pretty self explanatory, and to be honest I really haven\'t found a good use for this one yet...But I\'m sure someone would want to do it...And it was real easy for me to do...Keep in mind that this will run the program using system(), and will generate a MS-DOS type window when it\'s running...This is just like the same facility in MusicTicker.

6. Gather XML Statistics

This action provides you access to the information contained within the XML interface of Shoutcast. If you perform this action, DoSomething builds an internal array of tags derived from the output of this interface. This facility is built such that as new information is presented (i.e. Nullsoft adds new XML elements) DoSomething will automatically support the new tags.

To describe how the tags are referenced, let us look at the Shoutcast XML interface as seen through IE

This is just a subset of the information available through this interface. Once you perform the Gather XML statistics action, you can put any of the following tags in your HTML template file :

%%XML_SHOUTCASTSERVER_IRC%% - DoSomething will replace with N/A (in the above example.

%%XML_SHOUTCASTSERVER_WEBDATA_LISTEN%% - DoSomething will replace with 0 (in the above example).

So you can see how the tags are built..they are derived off the XML element names as such and are all prepended with an %%XML_

The template.html file included with DoSomething will contain example tags for this facility.

Note the only field you need to specify is the following :

XML URL : http://shoutserver:port/admin.cgi?pass=PASSWORD&mode=viewxml

You must replace shoutserver with the IP of the shoutcast server, port with the port, and PASSWORD with your admin password (of the shoutcast server).

See the appendix for the current list of XML tags that you can use.

Playlist Monitoring

Playlist monitoring is no more (as of 2.11)

Other Configuration Buttons/Stuff

Buttons

Everything else on the configuration screen is pretty self explanatory. The "Add" button is used to add defined actions to your "Action List"...If you double-click on an action in the Action List, the parameters for that action appear and you can modify them and click the "Update" button to update that information. Note you *cannot* just change the values and click OK...You *must* click the Update button.

Use the Delete Button to remove a defined action from the Action List.

Use the Insert Button to insert a new Action at a specific point in the Action List. Otherwise, if you use the Add button, the new action will be put at the bottom of the List.

The Clear Playlist Song Cache is to delete all previous songs that DoSomething knows about. DoSomething will keep a list of the last 50 songs played for use in the generation of the HTML playlist. This button will clear all these entries.

Checkboxes

The "Show Status Window" checkbox will turn on/off the displaying of a status window which describes which actions are being executed. In general, it\'s good to turn this on to make sure that everything is running okay, and then turn it off while your are broadcasting.

The "Disable Plugin" checkbox will turn on/off the plugin (duh. :))

The "Enable Error Messages" checkbox is used to turn on/off any error messages trapped during the Action calls. It is defaulted to "Disabled" since most people will run this on a machine they don\'t check often and any error messages will pop up a message box and halt the execution of the plugin. Since many errors generated (i.e. can\'t FTP file, error Submitting URL) will eventually go away, I put this option in here so that if you do get a few errors, it will not stop the execution of the plugin. Be warned though, when this is "Disabled" there won\'t be any error messages (duh). So it\'s best to run through your Action List with this "Enabled" until you are sure there are no errors, then "Disable" it.

Requirements:

• You need Winamp.

Other/Misc:

Using DoSomething you can totally replace MusicTicker, which is a good thing since I think it has been discontinued.

Since I am providing the source code, feel free to make your own "Actions" and send me the code and I will encorporate it if it is useful.

Since this is my first winamp plugin your patience and understanding is welcomed. :)

Release 1.1 Notes :

I have added a few new features, and fixed a couple of bugs (well, kindof...). There was a problem with the plugin keeping the status window open, and I have added a "Dismiss" button that should remove the window if this happens...It should normally happen, but there are some specific cases when it was, and I couldn\'t figure it out...You can aviod this whole thing by turning off the status window.

New Feature :

When you hit stop on Winamp, it will trigger the calling of the defined actions. This is so that you can publish this info in your generated HTML page. When you hit stop, the current song will show up as "Winamp Stopped!". Also, when you close Winamp, I also trigger the calling of the defined actions, and this time the current song will show up as "Broadcast Stopped!"...This is all stuff that MusicTicker did, so I thought it would be good to include it.

Also, I have added some new fields for the soon to be developed "Playlist Monitoring". This will be just like the MusicTicker stuff, but it isn\'t done yet, so they don\'t really do anything....

I am also working on a new plugin, which will function as a simple web server with the added functionality of providing a nice straightforward song request mechanism. It will be entirely contained within the plugin (no extras :)), and if you are interested, send me an email an I will include you on my beta list...

Release 1.2 Notes :

MORE TAGS! At the request of a few people, I have added more flexible tags to the HTML generation. Before you could only specify the current song as a combined entity...Now I am using ID3Lib so I can get much more info about what is currently playing..I now read the ID3 tag in the Mp3 file and allow you to specify the following new tags :

See the appendix for the list of tags.

Additional tags have also been added to the SubmitURL action, they are as follows :

See the appendix for the list of tags.

So now you can Submit URLs like :

http://www.myhost.com/cgi-bin/playedSong.pl?artist=%%ARTIST%%&album=%%ALBUM%%&songtitle=%%SONGTITLE%%

when each song is played.

Note that all the new tags that are supported *require* that proper ID3 tags are on your Mp3s...The plugin will still function as normal if you don\'t.

I have also redone how the song caching is done, so if you are upgrading from an earlier version of DoSomething, you *must* clear your song cache before you use any of the HTML generation stuff...Otherwise unpredictable results will occur.. :)

The song cache needs to store a temporary file for song history, and it was previously hard coded to C:\songs.txt...Now you can specify where you want it to store the song history info...I put this here in case anyone wanted to run two versions of the plugin on the same machine.

Also fixed a few minor bugs.

The "playlist monitoring" features are also still not implemented. If someone wants to have this upped on my priority list, please let me know...Right now it\'s pretty low...

Release 1.21 Notes :

Ok, quick bug fix....Apparently for those of you using the Live365 Listener counter action, the data was not updating correctly...If you have a problem with the listener count data not seeming to be correct, get this release and see how it goes....

Another bug fix that had the same songs being displayed twice if you had 2 Generate HTML actions defined. This has been fixed....

Thanks to yurst for identifing both of these...

Release 1.22 Notes :

Well, it seems that yet another bug has creeped into the plugin...This time it was in the ID3 libraries that I use to get the more detailed Song tag information. I thought I could count on this library to be fairly stable, but alas....Anyway, luckily I had the code for the library and have since fixed the problem...Apparently certain Mp3 would cause a GPF and it has something to do with the ID3Frame not being done correctly....So please make sure that your ID3 tags are correct and if you run into a GPF from the plugin, write down the song that it did it on and make sure that ID3 tag is correct. Since I know not everyone keeps their ID3 tags up to snuff, I have added a flag so that you can disable this ID3tag info gathering altogether. If you are getting a GPF b/c of a crappy ID3tag, then try turning this option off (it\'s in the configuration screen).

And Thanks again to yurst for this one.

Release 1.23 Notes :

Fixed a small bug if you happen to be using SAM....It still doesn\'t quite work right with SAM since they interpose themselves within the winamp playlist....But it works pretty well...The one problem that I know of is the fact that when you use SAM, in the playlist is only one entry and it is the *next* song, and normally it would be the *current* song...so your Currently playing song might be off by one...Ah well....

Release 1.30 Notes :

Playlist Monitoring!!! Now you can be DMCA compliant with your broadcast playlist...Read more about it here.

Added the ability to turn off the "Winamp Stopped!" message that appears in your HTML template when you stop winamp from playing.

Release 2.0 Notes :

XML has finally come to DoSomething. You can now use the information from the Shoutcast XML interface in your Generated HTML file or SubmitURL actions. This can be very powerful since there is alot of info contained in this interface.

A new HTML template is also provided showing off the new tags that you can use. It is copied into your Winamp directory as template.html....Check it out.

See the appendix for a complete list of XML tags that you can use.

Release 2.1 Notes :

I have added an exclusion feature in which you can enter specific MP3s that you do not want to be included in the Playlist monitoring that DoSomething does....So for instance, if you have promos named "Promo1.mp3" and "Promo2.mp3" then you can enter "Promo" in the exclusion field and these promos that match this entry (it matches on only the first part of the word, so "Promo" matches Promo_Bleh.mp3, but not Bleh_Promo.mp3) will not be measured against the Playlist monitoring that is being done. You can enter multiple substrings if they are separated by a comma. So "promo,Promo,Monkey" will exclude all MP3s that begin with promo or Promo or Monkey (case sensitive) from the playlist monitoring rules.

I have also made this version compatable with another plugin written by me, SongRequester. There were some conflicts if you used both of these plugins together. This version should clear this up. If you use SongRequester, then you must check the "SongRequester Compatability" checkbox on the DoSomething config screen. Also, since both DoSomething and SongRequester both do PlaylistMonitoring, make sure that only one of the two is configured to perform this monitoring, otherwise wacky things can begin happening... :)

Release 2.2 Notes

For those of you who thought that DoSomething just doesn't have enough "stuff", I bring you Release 2.2 with 2 new things...First, for those major Shoutcast stations with multiple relays (Ari) I have encorporated the ability to call the XML parsing "Action" multiple times and have each execution's tags available to you....The first time you call an XML "Action", the results will be located in the tags that begin with "%%XML_", such as %%XML_SHOUTCASTSERVER_CURRENTLISTENERS%%. If you add another "XML" action then all the values from that server can be represented by using tags that begin with "%%XML1_", such as %%XML1_SHOUTCASTSERVER_CURRENTLISTENERS%%. Add as many XML "Actions" as you want...I changed the web template to show examples of how to display stats from 2 Shoutcast servers...Note that you can also use the new %%XML# tags for SubmitURL, so finally you can submit something like :

http://www.mysite.org/cgi-bin/calcTotals?L1=%%XML_SHOUTCASTSERVER_CURRENTLISTENERS%%&L2=%%XML1_SHOUTCASTSERVER_CURRENTLISTENERS%%&

To call a CGI script which can add up the two values and put it on a webpage somewhere...nifty eh ?

And if this wasn't enough, I have added the ability to execute your DoSomething Actions on a timed basis...This is for those stations who play tracks that are very long in length and since DoSomething only "did something" when song changes occurred, listener counts and such on these sites were pretty stale (especially for some trance stuff which as far as I can tell, can go on for days...)..Anyway, you can now tell DoSomething to cycle through the Actions on a timed basis...I strongly recommend against anything less than a minute...Generating HTML can take some major time, so you don't want to be stepping on yourself...you are warned.

Well, that's about it for this version.....

Release 2.3 Notes

Well, there was apparently a bug in the method I was using to get the XML statistics...the "connect-to-server/download XML" part was very unreliable...So I scrapped the method I was using and am now using CInternetSession.....It should be much more stable now....Thanks to webboy for allowing me to test with his server...

Note: I know there are still some problems with the new "Timed trigger" thingy...That is a bit of a beast, so it will take a bit to figure out what's going on there....

Release 2.4 Notes

I have finally recompiled DoSomething with the new id3lib...Sorry Greg for taking so long.. :) This should provide more stability for those having ID3 tag problems.

There isn't anything else in this version

Release 2.5 Notes

Ok, so I've gotten rid of ID3Lib now....it was causing way too many problems for some of my users....so it's gone...replaced by my own ID3 tag parsing....so now it only supports ID3V1 tags, but hey, it's not like people are really using the Id3V2 tags...This should be very stable now...

I also fixed the listener count for Live365...which was broken when Live changed their site recently...

Release 2.6 Notes

I think I have finally gotten the 1 second-blip on song changes fixed...The reason why this was occurring was a rather complicated matter, and the fix was not without problems....The result is as a consequence, if you ever have 28 consecutive "violations" of your DMCA rules, the 29th song will be played (regardless of the rules you have defined)...In my opinion it is reasonable that this will never be achieved for anyone who has a decent playlist...If you have 28 consecutive "DMCA" violations, I'm thinking you should rethink your playlist rotation...Anyway, hopefully I haven't introduced a whole slew of new problems by fixing this one....Keep in mind that DoSomething was one of the 1st plugins that I did, and I have never gone back and fixed alot of the code that I found better (or more efficient) ways of doing...

Release 2.7 Notes

Whoops...looks like a bug found it's way in which would prevent you from using the %%LISTENERS%% tag if you didn't do a "Generate HTML" action...Sorry about that...it's fixed now....Thanks to Aaron Bell for finding this one...

Release 2.8 Notes

Looks like Nullsoft changed their XML interface in Shoutcast 1.8...this proceeded to break the hacks that I had previously put in there because of Nullsoft's bad XML document from before...evidently, they fixed their XML stuff, and broke mine...either way...it's fixed.... 

Release 2.10 Notes

Hey, what happened to 2.9 ??? I have no idea...either way, this version is 2.10...with just a few bug fixes, and all "actions" can now be run simultaneous..Which means if you have a very short song, you could be executing actions in parallel...just something to keep in mind...Ari wanted this, so I thought I would do it....

Release 2.11 Notes

Changed FTP mode to PASSIVE

Rewrote alot of the code, took out alot of unused junk, changed method of detecting song changes....removed all the playlist monitoring crap that noone used.

Live365 crap also removed

Appendix

This section lists all the tags that you have at your disposal for various uses. These are really only referenced in either the Generate HTML or Submit URL actions.

** URL encoded means coverting special characters to their URL-safe counterparts..For instance, " " (space) is converted to "%20".