A feature-light HTML5 audio tag based player for the Nectarine, CVGM, and SceneSat
internet radio websites.

The list of streams and data source URLs are in their own JavaScript files. The
handling of streams is allows for site-specific behavior, see below on how to
configure it for sites with behavior not already included.

The player defaults to showing Nothing in the lower part of the front panel, so if
no suitable compatible data feeds are available, just target the panel options with
CSS and hide them. (Removing them would cause the code not to function properly.)

A future goal is to make the handling of data sources easier to replace so sources
with different data formats and panel options can be accomodated.

Code contributions and bug reports are appreciated.


Configuration notes:

To change the radio station this player points to, just edit the main HTML file so
the ".urls" script uses one of the included such files with the name of the radio
station wanted in its name. If no such file exists, one following the same format
as the existing ones can be created and used instead. This is preferable to editing
an existing URLs script as this may produce a large conflicting diff when pulling
from the repository to grab changes.

To replace the data handling code, just change the script to a ".data" file to
point to one for the platform the radio the player now targets is running. If one
doesn't exist, it will have to be written though some code from existing ones may
be useable as a base.

When deploying multiple copies of this player on the same domain, it is recommended
to configure the tools script so players which point to different stations do not
overwrite each other's saved preferences. This can be done by appending a question-
mark and a unique identifier to the end of the script's URL: "...tools.js?appkey"


Cross-domain configuration issues:

If the player is deployed on a different domain than the URLs it uses to get data,
the player may not work. If the data source does not provide suitable cross-domain
allowance headers then browsers will block the player's requests by default. It
would be impossible and unwise to advise all users to set their browsers to allow
such requests.

To resolve this issue, one of two things can be done: a proxy to the data sources
can be set up on the server the player is deployed so requests are no longer
between two different domains, or two cross-domain allowance headers can be added
to the responses returned by the data source.

The former can cause issues if the data source limits the number of requests, as
too many users will easily exceed the request cap as all requests will appear to
come from one location. Thus this option is best suited only when the person
deploying the player cannot change the data source configuration and owner of the
data source is unwilling.

Therefore it is preferable to go the header route when possible. The data sources
should send the following two headers with responses:

  Access-Control-Expose-Headers: Date
  Access-Control-Allow-Origin: *

Access to the date header is required for the player, but the origin header can be
more restrictive as long as the domain the player is deployed at is included. It is
not necessary to send those headers with all responses from the data source domain.
It is only necessary, and perhaps more desireable, to send them only with responses
to the URLs the player requests.


Minification notes:

My own simplistic combining minification tool, which uses Crockford's JS minifier,
can get the code and styles down to a single file around 21k. The combined minified
file can then be deployed by itself. The player will look and function fine without
the favicon or incuded font.

In theory this player is embeddable inside of an existing page without using
iframes, though it would require its element IDs not be in used anywhere else.

Lastly, it should also be noted that the URL query-configuration of the tools
script, noted above, is incompatible with minification which packs files directly
into the main HTML file. In such cases, however, the short bit of code at the top
of the block which used to be the tools script can be easily patched to set the
prefix directly instead of trying to look it up.

-----------------------------------------------------------------------------------
License: BEERWARE

You can do whatever you want with this stuff. If you meet me at a demoparty, and
you think this stuff is worth it, you can buy me a beer in return.

(based on the original "The Beer-ware License" by Poul-Henning Kamp)