| |
|
|
| |
Song
Requester
Winamp
Plugin
Version 2.5
|
|
| |
|
|
oddsock@oddsock.org
Release 1.1 Notes :
Release 1.2 Notes :
Release 1.3 Notes :
Release 2.0 Notes :
Release 2.1 Notes :
Release 2.2 Notes :
Release 2.3 Notes :
Release 2.5 Notes :
What it is :
There really aren't too many
tools available for MP3 broadcasting, let alone ones that are
free...And the implementations that I saw that did Song
Requesting were pretty much tied to a web server of sorts
(running either CGI, PHP, ASP,etc)...None of which provided any
source code (except for some *real* basic ones) so extending them
was tough...So I thought, hell, I'll do my own. I wanted it to
allow people to be able to use it without requiring any
additional software (like a webserver) and yet still be very
functional. Plus, I've always wanted to write a web server, and
the SongRequester plugin is the result of all this.
How it works :
The plugin is (in itself) a very
simple web server with some additional features. You can use it
as a simple web server if you'd like, but the real power is in
something else. There are specially defined URLs which trigger
special things within the plugin. For instance, if you call
playlist.cgi (i.e. http://yourserver:yourport/playlist.cgi) then the plugin detects it and runs
some special code. Note that in the case of all the
"special" URLs there does not exist any physical cgi
script (i.e. playlist.cgi does not exist) it is merely a tag used
by the plugin to trigger special action. There are currently 2
separate special action URLs (playlist.cgi and request.cgi).
Playlist.cgi will serve up an HTML page containing your Winamp
playlist and Request.cgi will add a playlist entry into the
Request Queue.
An example playlist template is distributed
with the program. This is contained in the file playlist.html. Feel
free to modify it however you see fit, but be aware of the special %% tags which
are used for internal processing type stuff..
Configuration Parameters for the
plugin
There are 3 sections that are responsible for
the configuration of the plugin, they are
Configuration Options
These options define general parameters for the
plugin. The fields are as follows :
WebRoot Directory
| This parameter defines the root
directory for all your URL requests. So if a user goes to
http://yourserver:yourport/bleh/bigBroadcast.html the plugin will look for the file in
WEBROOT/bleh/bigBroadcast.html. So if you set this to C:\Webroot,it will then look for the file
C:\Webroot\bleh\bigBroadcast.html. |
Port
| This defines the port that the plugin
will listen on. You *must* (repeat *must*) pick a port
that is not currently in use. Do *not* pick the port your
shoutcast server is listening on....If you are having
problems getting the plugin to work, try changing this
value first. |
File for playlist.cgi
| This parameter defines the template
file which the plugin uses to serve up your playlist. It
is assumed that the file that is specified here contains
special tags which the plugin will replace with values
from the playlist. Unless you know alot about HTML, I
would suggest starting with the template that is provided (playlist.html) with the plugin and extend from there.
Keep in mind that this field is *relative* to your
Webroot, so if you specify playlist.html in this field
(and you set Webroot to C:\Webroot) then the
plugin will look for the template at C:\Webroot\playlist.html. |
The pic below shows you the fields I'm
referring to...
Restrictions
These options define certain restrictions that
are placed on users that are submitting requests. They are as
follows :
Number Of Max Queued Requests Per IP
Address
| This one is kinda self explanatory... |
Max Playlist Entries to Display
| This field defined the maximum number
of playlist entries that the plugin will display to the
user per request. So if you set this to 50, and your
playlist is 1000 entries long, then the plugin will only
display the entries 50 at a time. Keep in mind, the
bigger this value, the bigger the HTML page sent to the
user (duh). Note that this also applies to search
results. So if you do a search for "Metallica"
and you have their entire collection in your playlist,
then you will only get 50 songs at a time (assuming you
set the value to 50).... |
Max Queue Size
| This parameter limits the number of
total requests that are allowed on your request queue. |
The pic below shows you the fields I'm
referring to...
Plugin "Special Actions"
admin.cgi
This special action will is used to perform
some very basic admin functions. Currently you can only do a few things if
you are logged in as administrator. This special action requires and
additional parameter (pass) in order for the plugin to actually recognize you as
an admin. You *must* pass this password through to all the calls to
admin.cgi in order access admin features. If you hit the URL http://yourserver:port/admin.cgi
then you will be prompted to enter the admin password. The rest of
admin.cgi is very similar to playlist.cgi.
If you are logged in as an admin, then you are
not subject to the playlist Restrictions defined in the plugin...Additionally
you will be able to delete queued up requests however you see fit...
playlist.cgi
This special action will serve
you an HTML page containing the playlist that is currently
playing within winamp. The page that actually is served to you is
based off a template which you provide (a sample template is
included with the plugin - template.html). Within this template
you can build your HTML pretty much any way you want, and use
special TAGs to represent data that the plugin will fill in for
you.
The following tags can be used
in this template file :
| %%ERROR%% |
Used internally to
display error messages to the browser, error messages
like "You cannot request any more songs" or
even success messages like "Request Added" are
these type of things. |
| %%CURRENTSONG%% |
The name of the
currently playing song (as it appears in the winamp
playlist) |
| %%QUEUELISTPOS%% |
This tag and the next
one *must* appear on the same line. The line that they
appear on will appear once for *each* entry in the
Request Queue. In each line these 2 tags will be replaced
by their value. |
| %%QUEUELISTENTRY%% |
see above |
| %%PLAYLISTENTRY%% |
These two tags are
similar to the Request Queue ones, except they represent
playlist entries, not Request Queue entries. They *must*
appear on the same line as well. There is a max number of
these that is displayed (you don't want someone to see
2000 of the songs in your playlist)..and the number
display is configurable. |
| %%PLAYLISTPOS%% |
see above |
| %%NAV_PREV%% |
This tag builds a link
used in navagating though a playlist. ** |
| %%NAV_NEXT%% |
ditto ** |
| %%CONTENT_REFRESH%% |
This value represents
the number of seconds left in the currently playing song.
In the template.html file it is used to initialize a
counter that "counts down" the time as well as
triggering an automatic update of the page when the song
is changed. |
| %%HTTP_REFERRER%% |
This tag represents the
page that brought you to the current page..It is used in
the template for navagation |
| %%ARTISTSELECT%% |
A special drop-down
select box which represents a self contained component
which contains all the Artists in your playlist (it
infers the artist name from the item displayed in the
playlist - It looks for Artist - Title). |
| %%ADMINPASSWORD%% |
If you are logged in as admin, then
this will be replaced by "&pass=adminpassword". You can
use this tag to integrate admin functionality with your site as
needed... |
| %%ADMINHIDDENFIELD%% |
This tag will be replaced with a
hidden form field "<input type=hidden name=pass value=adminpassword>".
This will only occur if you are logged in as an admin
(obviously). This is used in the provided template to propagate
the admin password for searches and artist lookups. |
| %%ADMINWINAMPCONTROL%% |
This tag will be replaced with
controls that can be used for basic winamp control...currently
supported actions are "Prev, Play, Pause, Stop, Next" |
** Note that these
tags must occur after the %%PLAYLISTPOS%% and %%PLAYLISTENTRY%%
tags in order to work properly. This is because their generation
is based on data that the %%PLAYLIST tags represent.
Other parameters to playlist.cgi
psearch
| This parameter to
playlist.cgi can be used perform a substring search on
the elements of your playlist. So if you execute http://yourserver:yourport/playlist.cgi?psearch=Mother then only those playlist entries
that contain the string "Mother" will be
displayed in the resultant HTML page. |
startswith
| This parameter is very
similar to psearch except that it matches on the
beginning of the playlist entry. It's primary use is so
that you can provide a link such as "Here is a list
of all entries that start with A" ( http://yourserver:yourport/playlist.cgi?startswith=A ). Somewhat useful I guess. |
current
| This parameter can be
used to tell the plugin where in the playlist to begin
displaying entries. For instance if you call http://yourserver:yourport/playlist.cgi?current=50 then the plugin will return an
HTML page with entries that begin at position 50 in the
playlist. This is mainly used by the Navagation tags so
that you can provide the ability to page through your
playlist. |
Configuring playlist.cgi
There is really only a few
configuration elements for this "Special Action" and it
is that of the template file, port, and webroot. On the plugin
configuration screen you specify the location of the template
HTML file which the plugin will use to generate your playlist to
people submitting the playlist.cgi URL. This is the HTML file
which contains all the tags defined above. A sample template HTML
file is included in the distribution. Note that the location
specified on the config screen is *relative* to your webroot
field. So if your webroot is D:\Webroot, and you put in
mytemplate.html in the "File for playlist.cgi" field,
then you need to copy your template into D:\Webroot\mytemplate.html.
request.cgi
This special action will request
a particular song on the playlist to be placed on the request
queue. The interface is very simple and takes only one parameter,
listpos, which refers to the playlist entry position on the
winamp playlist.
Parameters to request.cgi
listpos
Serving up other kinds of data (HTML, PLS)
Since the SongRequester plugin
is essentially a webserver, it can serve up normal web server
type stuff...
It supports the following MIME
types :
image/jpeg
image/gif
image/png
text/css
audio/wav
video/x-msvideo
video/quicktime
video/mpeg
model/vrml
audio/mpeg
audio/x-scpls
text/html
So go ahead and put your HTML files, your MP3
files, etc in your webroot and reference them as such....
So I hope you all enjoy it....
Release 2.5 Notes :
Fixed some more bugs causing crashes in certain circumstances...Hopefully this clears up alot of problems people have been happening that I have (until now) been unable
to reproduce. The bugs that I just fixed were related to adding songs to the playlist after you start the plugin, and then trying to request them, as well as
trying to requests songs that are beyond the playlist (such as request.cgi?listpos=666666 when do you don't have 666666 entries in the playlist..Also,
what happened to 2.4 ? I dunno, either it didn't get released or got lost somehow, anyway, my versioning says 2.5, so I'm
sticking to it.. :)
Release 2.3 Notes :
Got a little bit carried away on the buffer overflow problem and prevented some searching
from being proceeed correctly...specifically, it would match only on the first 4 bytes of a search string..
It's been fixed.. :)
Release 2.2 Notes :
Fixed a bad buffer overflow problem (doh) as well as fixed (hopefully) the
problem some people have had with it crashing when getting a request from a
machine that is *not* the source stream....
Release 2.1 Notes :
I've fixed the much reported "Next" link issue...my bad...The Next/Prev
links should now all work again..Also, I've taken the opportunity (now that we
have admin controls) to add basic controls of Winamp (Prev, Play, Pause, Stop,
Next)...just insert a %%ADMINWINAMPCONTROL%% tag in your SR template and if you
are logged in as administrator, you should see new controls which you can use to
control winamp (just basic control is implemented now)... This modification is
included in the supplied playlist.html template file. I've also still
recieved some complaints about some crashes, but nothing that I can
reproduce...I've fixed a few places that *might* be causing it, but nothing
major...I've also tested SR with Sqrsoft's Crossfader, and it seems to work
properly....
Release 2.0 Notes :
A whole mess of changes here....I've ripped out all the DMCA and playlist
monitoring stuff..it was crap anyway..hopefully, this will make the plugin a
whole lot more stable. Also, I've fixed a memory leak which would cause
alot of trouble for people running this alot...and also added a rudimentary
admin interface. You
can now hit http://yourserver:ip/admin.cgi
and enter an admin password (specified in the configuration screen of the
plugin) which will allow you to delete queued entries and also allow you to make
as many requests as you'd like (admins are excluded from all the Validation
rules)..Overall, things should be much better and thus I've bumped the version
to 2.0.
Release 1.3 Notes :
Ok, so I am continuing my "purging" of id3lib....So
now Songrequester no longer uses this library to gather ID3 tag
information....I now have my own parsing routine to do
it....which means that Songrequester only supports ID3V1 tags.
What does it use ID3 tags for you ask ? Well, it is used
primarily for the DMCA rules so that if you say, "Don't play
more than 3 songs by the same aritist in an hour", the way
it knows which artist is being played is via the ID3 tags. (It
will fall back to the <artist> - <title> format if
the ID3 tags aren't there....)
I have also modified SR so that if you hit http://yourserver:yourport/
it will trigger the playlist.cgi logic....just a little bit more
convienient for some people...
Also, I believe the "song change" logic has been
dramatically improved....you should no longer get the 1-2 second
blip of a skipped song before switching....
Release 1.2 Notes :
I have *finally* gotten the time to update the version of
id3Lib that was being used by SongRequester...This (I believe)
has been causing all the crashes that people have been having. I,
personally, have been able to make it crash with certain mp3
files in my playlist...I don't know what about them made it crash
id3lib, but hey, I didn't write the damn thing...anyway, this
version should be much more stable...
nothing else was really added here....
Release 1.1 Notes :
I originally intended this release to be more a cleanup and
release of the code, but in some testing that I was doing I
realized that there were some pretty serious conflicts when using
DoSomething (http://www.oddsock.org/tools/dosomething) at the
same time. This was due to the playlist monitoring that they were
both doing....To fix these conflicts I rewote alot of how
SongRequester was internally storing the playlist
entries...Consequently I not only fixed the conflicts, but made
it way more efficient. So this is a good thing.. :) If you use
DoSomething and SongRequester together, then you will have to get
at least version 2.1 of DoSomething and be sure to check the
"Song Requester Compatability" checkbox on the
DoSomething config screen.
The ramifications of this compatability are that DoSomething
will now wait for 5 seconds after it detects a song change before
running the defined actions...This is to get rid of a race
condition that was occuring. If you don't check the "Song
Requester Compatability" checkbox, then it will operate as
normal. (Note that the mentioned checkbox is on the DoSomething
config screen (not SongRequester)).
I have also modified the "Artist Select"
(%%ARTISTSELECT%%) drop down so that the Artists are displayed in
sorted order rather than in playlist order.
Also, if you experienced occasional pausing of the playlist,
that should also be fixed as well (that whole logic was
redone...)
Source Code!
|
