pianod Viewer
=============
The viewer JavaScript can be used to display current pianod state on a website.  


Invokation
----------
The viewer requires these JavaScript inclusions:
	<script src="http://deviousfish.com/pianod/client/jquery.min.js"></script>
	<script src="http://deviousfish.com/pianod/client/communication.js"></script>
	<script src="http://deviousfish.com/pianod/client/viewer.js"></script>

Most version of JQuery will do, and you can alternately access the minified code:
  <script src="http://deviousfish.com/pianod/client/viewer-engine.js"></script>


The viewer is invoked by:

	<script>
	my_viewer = new PianodViewer (url, instancename)
	</script>

The required `url` is the URL of the pianod websocket gateway, such as `ws://house.perette.barella.org:4446/pianod?encoding=text`.  `instancename` is an optional name of an HTML ID tag within which pianod data will be substituted; if omitted, the ID tag is assumed to be `pianod`.  It may be `style="display:none"`, in which case the viewer is made visible when instantiated.  

PianodViewer opens the connection and handles reconnection attempts when necessary.  Multiple viewers may appear on a single page with different instancenames, either using separate static blocks of HTML for each instance or by dynamically adding each instance to the page.

To destroy a viewer, call its .destroy() method:

	<script>
	my_viewer.destroy();
	</script>

The destroy method hides the instance with which it is associated.

DOM Objects
-----------
Within the `#pianod` ID tag, manipulable items are tagged with classes.  All items are optional; if not provided then the corresponding data isn't displayed.

There are two main classes, providing an alternative display when pianod is stopped.

* `.offline`: This element is visible when pianod is offline or otherwise unreachable (network problems, machine down, WebSockets not available).
* `.idle`: This element is visible when pianod is idle.
* `.playing`: This element is visible when pianod is playing.

If two classes are assigned to an element, the visible takes preference.  So:

	<DIV CLASS="offline idle">
		This displays when either stopped or unable to connect to pianod.
	</DIV>

Two more classes provide status information:

* `.playbackstatus.paused`: The element is visible while paused in the middle of a track.
* `.playbackstatus.stalled`: The element is visible during playback stalls (typically a network buffer underrun).

The remaining classes will be children of .playing, and indicate the location where data will be inserted into the page.

* `.albumart`: An `<img>` element, whose `src=` attribute is set to the URL of the album art.  If art is not available, `src=` is set to "`no-art.jpeg`".
* `.trackname .value`: The current track name.
* `.artistname .value`: The current artist name.
* `.songplaylist .value`: The station the current song originates from.  Note: The original pianod viewer uses `.songstation`, whereas pianod2 viewer uses `.songplaylist`.
* `.selectedname .value`: The selected playlist/station.  If pianod is stopped, the value is replaced will an empty string.
* `.timepoint.time`: The current point in the track in minutes:seconds.
* `.duration.time`: The duration of the track.
* `.progressbar`: The `width` of this element is set to the percent of the track played.

For the pianod2 viewer, `.trackname`, `.artistname`, `.songplaylist`, and .selectedname` are hidden/shown depending on whether a value is available.

Examples
--------

### http://deviousfish.com/Pianod/Client/viewer.html
Displays a white-on-black layout with the album art and track details, using a suitable font size for public display.  Add ?server=host:port query parameter to specify your own instance.  Original pianod.

### http://deviousfish.com/Pianod/Client2/viewer.html
Displays a white-on-black layout with the album art and track details, using a suitable font size for public display.  Add ?server=host:port query parameter to specify your own instance.  For pianod2.

### Another example at:
http://perette.barella.org
The right column ("Get a freakin' life" image) displays when idle or unreachable, otherwise it announces what I'm listening to.