==================
WISL SoundPalettes
==================

WISL (What the Internet Sounds Like) is an application that measures
network performance and plays sounds in real time. The sounds are
intended to be an aural representation of the current state of the
network. The original intent of WISL was to provide a platform for
creating musical compositions, but WISL can also be used to
monitor network elements and play out alarms indicating that the
network needs attention.

WISL is extensible at the lowest level where the measurements take
place, as well as at the highest level where the sounds are chosen
for playout.

This document describes how to generate and contribute a SoundPalette
in WISL. A SoundPalette is set of files that, when installed in the
WISL package and selected in the user interface, completely determines
the representation in sound that will be played. It should be read by
anyone who wishes to create a set of sounds that represent their
interpretation of how the current state of the network should sound.
In this document we give an overview of how to create a SoundPalette.
More details can be found in the html documentation for SoundPalette
Description files in the docs/SPDF directory, starting with the file
index.html.

-------------------------------
Preliminaries: NetModules (NMs)
-------------------------------

The measurements in WISL are performed by NetModules, or NMs. Each NM
performs its measurements independently --- sending, or "firing", events
from time to time to the SoundPalette level. Each event describes some
aspect of the network state and usually has a value associated with
the event.  For example, an NM may fire an event called "lossrate" with
a value of 0.1, indicating that the NM has detected that the current rate
of data loss on the network (the proportion of data that have fallen into
the proverbial bit bucket) is at 10%.

Associated with each NM is a file called "NM.desc" (replace NM with the
name of the NetModule, e.g., BinaryModule.desc) which describes,
among other things, the events fired by the NetModule and the values
associated with each event. The SoundPalette creator, or SoundModule
composer, may browse existing NM.desc files, choosing the events and
values that he or she wants to convert into sounds. The SoundPalette
composer then creates the set of sounds that will be played out upon
detection of the events. 

--------------------------------------
SoundPalette Description Files (SPDFs)
--------------------------------------

To set up the sounds to be played out, the SoundPalette composer must
provide a SoundPalette Description File, or SPDF. The SoundPalette's
SPDF must be named XXXXXXXX.xml, where XXXXXXXX is replaced with a
word describing the SoundPalette. The SPDF defines how WISL will map
events to sounds.

-----------
SPDF Format
-----------

The SPDF has a very strict format. (It is an XML document described by
the file config/soundpalette.dtd. This tells WISL what the SPDF has to
look like.)

WISL is shipped with a set of default SoundPalettes found in
subdirectories of palettes directory. Each SoundPalette has an SPDF
that can be examined as an example of how to write an SPDF.

The first line in the SPDF must look like this:
<!DOCTYPE soundpalette SYSTEM "soundpalette.dtd">
The rest of the file is characterized by having a lot of start-tags
and end-tags with things in between, like
      <hello>
      "Look at me"
      </hello>

A section of the SPDF enclosed in a start-tag and end-tag is called
an element, so the piece above is called a hello element. Elements
can contain other elements. The overall structure of an SPDF (very
stripped down) looks something like this:

<!DOCTYPE soundpalette SYSTEM "soundpalette.dtd">
<soundpalette>
    <netmoduleinit>
    </netmoduleinit>
    <soundmodule>
        <sound>
        </sound>
        <netmodule>
            <event>
                <listener>
                </listener>
            </event>
        </netmodule>
    </soundmodule>
</soundpalette>

After the special first line comes the start-tag <soundpalette>, and
at the bottom of the file is the end-tag </soundpalette>. This indicates
that it is a single element describing the SoundPalette. Start-tags may
also include attributes. In the case of the soundpalette start-tag,
two attributes are required: "initialtempo" and "initialenv". This
makes the soundpalette start-tag look like this:

  <soundpalette initialtempo="60" initialenv="A">

The soundpalette attributes describe the initial values of global sound
environment values that may change over time. See "Global Sound
Environment" below for more details. The other elements in the SPDF are
described in separate sections below.

-----------------------
Initializing NetModules
-----------------------

The netmoduleinit section initializes all of the NetModules that will
be used by this SoundPalette. Each NetModule
requires at least one netmoduleinit element. Each NetModule is
assigned a different identification number. Using this number as
the "id" attribute of the netmoduleinit start-tag identifies which
NetModule is being initialized. WISL also allows multiple instances
of a particular NetModule to be running simultaneously, each with
different attributes. The "instance" attribute is used to distinguish
between these instances. Any number can be chosen for the instance
attributes as long as they are different. For example, the following
two elements initialize different instances of the same NetModule:

<netmoduleinit id="14" instance="1">
</netmoduleinit>
<netmoduleinit id="14" instance="2">
</netmoduleinit>

Contained in each netmoduleinit element is a set of parameters. The
parameters are specific to each NetModule. The NM.desc file
describes the possible parameters for each NetModule. An example of
a full-blown netmoduleinit element is:

<netmoduleinit id="14" instance="2">
    <param name="period">5000</param>
    <param name="url">nimi.cc.gt.atl.ga.us</param>
    <param name="filename">pipe.jpg</param>
</netmoduleinit>

Since HTTPGetModule has been assigned an id of 14, this netmoduleinit
element initializes a single instance of HTTPGetModule. HTTPGetModule's
NM.desc file states that there are three parameters that must be
specified here: period, url and filename. The NM.desc file also
describes the form these parameters must take.

--------------------
SoundModule Elements
--------------------

Soundmodule elements are used to bind sounds to NetModule events.
The soundmodule start-tag requires two attributes: id and type.
The id attribute allows WISL to distinguish between different
SoundModules. The type attribute specifies the behavior of the
SoundModule in choosing Sounds based on global parameters. Currently
the only defined type is "default".

There are three elements that can appear in a soundmodule element:
netmodule, operator and sound. At least one sound must appear.
At least one of either netmodule or operator must appear.

--------------
Sound Elements
--------------

We're now getting to the actual sounds! The sound element defines
which sounds are bound to the parent SoundModule. There are no attributes,
so the tags are simply <sound></sound>, but there are many elements
that can be contained in between:

filename:   the filename of the sound. E.g.,
               <filename>
               ten_percent_data_loss.ogg
               </filename>
envlist:    the global sound environments for which it should be played
temporange: the range of tempos for which it should be played

The above three elements are required. The following elements are
optional:

volume       : relative volume at which the sound should be played
               as a percentage of the sound's maximum volume
repetitions  : number of times to repeat the sound
noqueue      : play this sound immediately, rather than being
               queued to play at the end of the current sound
flushqueue   : removes sounds currently being played and plays
               this sound immediately
mute         : mutes other queues while this sound is being played
stickymodulo : starts this sound regularly on a particular beats
               until it is stopped

Details on how all the elements in an SPDF fit together are specified
in the html documentation for SoundPalettes, docs/SPDF/index.html.

------------------
NetModule Elements
------------------

The netmodule element is contained in a soundmodule element and describes
the netmodule events that are being mapped to a sound. It requires two
attributes: id and instance. These must match how they were
specified in the associated netmoduleinit element at the top of the
SPDF.

The netmodule element contains at least one event element, which
describes the event this SoundModule is interested in.

--------------
Event Elements
--------------

An event element describes the event that is being mapped to the sound.
There is one attribute required for each event element: name. Valid
names are listed in the NetModule's NM.desc file.

Each event may also contain a set of param elements (parameters that
affect the behavior of the event) and listener elements (listeners
that perform some filtering on the events). Param elements contained
in events are NetModule-specific, so the NM.desc file describes the
set of parameters that can be set for an event. Listener elements
are a bit more involved and are described next.

-----------------
Listener Elements
-----------------

Listener elements can contain a set of standard parameters. These
parameters are highvaluestart, highvaluestop, lowvaluestart and
lowvaluestop. These parameters perform the following filtering
functions:

  highvaluestart: Begin allowing receipt of events when
                  the event values go above this value.
  highvaluestop:  Begin ignoring events when the event
                  values go below this value.
  lowvaluestart:  Begin allowing receipt of events when
                  the event values go below this value.
  lowvaluestop:   Begin ignoring events when the event
                  values go above this value.

The reason for this filtering is to reduce computation. If, for example,
an event is fired every few milliseconds but the SoundModule is not
interested in hearing about it when it's below a certain value, setting
the highvaluestop parameter keeps the event from propagating up to the
SoundModule. The highvaluestart parameter allows the event to begin
propagate up again.

-----------------
Operator Elements
-----------------

Operator elements are used to combine the events specified by netmodule
elements in sophisticated ways. They can be combined so that a sound
is played when two events occur within a particular period of time,
or when either one or the other occurs in a period of time. The 
possible attributes for an operator element are "type", which can be set
to "AND" or "OR", and "within" which can be set to an amount of time in
milliseconds. The following is an example of using the operator element
to combine events:

<operator type="and" within=10000>
  <netmodule id="88" instance="1">
    <event name="manyparticipants">
      <param name="frequency">0</param>
      <listener></listener>
    </event>
  </netmodule>
  <netmodule id="23" instance="1">
    <event name="fast">
      <param name="frequency">0</param>
      <listener></listener>
    </event>
  </netmodule>
</operator>

This operator combines two NetModules, one with a "manyparticipants"
event and the other with a "fast" event. If these two events are
received within 10 seconds, the event is sent up to the parent module.
The parent may be either a GlobalModule or a SoundModule.

------------------------
Global Sound Environment
------------------------

A SoundModule composer may have different sets of sounds that work
together. For example, sounds 1, 2 and 3 belong together, as do sounds
A, B and C, but sounds 1 and B do not work together. WISL provides the
SoundPalette composer with the ability to do this using the global
sound environment (GSE). The GSE is comprised of two variables:
env and tempo. These two variables are initialized in the attributes of
the soundpalette element (see SPDF Format above). They are used by the
SoundModule when deciding which sounds to play upon receipt of an
event; the SoundModule checks the current GSE before choosing the
sounds. Changing env and tempo are akin to changing the key and tempo
in a conventional piece of music; env is more generic so as to not
impose constraints on the composer. The values can only be changed by
GlobalModules.

GlobalModules are very similar to SoundModules, except that they don't
contain sound elements. The "envchange" and "tempochange" attributes
indicate how the env and tempo should be set.

------------
Example SPDF
------------

We'll end this README with an example SPDF with comments interspersed,
preceded by ";;;". The comments would not appear in the actual SPDF.
This SoundPalette assumes that files named doh.ogg, tada.ogg,
woohoo.ogg, gong8.ogg, triangle.ogg, and the SPDF itself (HTTPTimeDemo.xml)
are in the wisl-rel/palettes/HTTPTimeDemo directory.

;;; The first line is required:
<!DOCTYPE soundpalette SYSTEM "soundpalette.dtd">

;;; The soundpalette initializes the Global Sound Environment
;;; variables, tempo and env:
<soundpalette initialtempo="60" initialenv="A">

;;; There are two NetModules being used by this SoundPalette:
;;; HTTPGetModule and PeriodicModule. HTTPGetModule was assigned
;;; an ID of 14, so this initializes the period, url and filename
;;; parameters of one instance of the HTTPGetModule:
  <netmoduleinit id="14" instance="1">
      <param name="period">2000</param>
      <param name="url">nimi.cc.gt.atl.ga.us</param>
      <param name="filename">pipe.jpg</param>
  </netmoduleinit>

;;; PeriodicModule was assigned an ID of 2222, so this initializes
;;; the period parameter of one instance of the PeriodicModule.
  <netmoduleinit id="222" instance="1">
      <param name="period">1000</param>
  </netmoduleinit>

;;; There are two GlobalModules. The first one listens to httptime
;;; events whose values are below 200. When this happens, the global
;;; env value is changed to "A".
  <globalmodule tempochange="" envchange="A">
    
    <netmodule id="14" instance="1">
      <event name="httptime">
		<param name="frequency">0</param>
		<listener>
		  <param name="lowvaluestart">200</param>
		  <param name="lowvaluestop">200</param>
		</listener>
   	   </event>
    </netmodule>
    
  </globalmodule>

;;; This is the second GlobalModule. When the httptime values
;;; are between 200 and 500 the global env value is changed to "B".
  <globalmodule tempochange="" envchange="B">
    
    <netmodule id="14" instance="1">
      <event name="httptime">
		<param name="frequency">0</param>
		<listener>
	 	  <param name="highvaluestart">200</param>
		  <param name="highvaluestop">200</param>
	 	  <param name="lowvaluestart">500</param>
		  <param name="lowvaluestop">500</param>
		</listener>
      </event>
    </netmodule>
    
  </globalmodule>

;;; This is the third GlobalModule. When the httptime values
;;; are between 1000 and 2000 the global env value is changed to "C".
  <globalmodule tempochange="" envchange="C">
    
    <netmodule id="14" instance="1">
      <event name="httptime">
		<param name="frequency">0</param>
		<listener>
	  		<param name="highvaluestart">1000</param>
	  		<param name="highvaluestop">1000</param>
	  		<param name="lowvaluestart">2000</param>
	  		<param name="lowvaluestop">2000</param>
		</listener>
      </event>
    </netmodule>
    
  </globalmodule>
  
;;; This is the fourth GlobalModule. When the httptime values
;;; are above 2000 the global env value is changed to "D".
  <globalmodule tempochange="" envchange="D">
    
    <netmodule id="14" instance="1">
      <event name="httptime">
		<param name="frequency">0</param>
		<listener>
	  		<param name="highvaluestart">2000</param>
	  		<param name="highvaluestop">2000</param>
		</listener>
      </event>
    </netmodule>
    
  </globalmodule>

;;; This is the first SoundModule. When it receives an event called
;;; periodic from PeriodicModule and the global environment is either
;;; A,B,C or D it plays the sound contained in the filename "triangle.ogg".
  <soundmodule id="1" type="default">
    <sound>
      <filename>triangle.ogg</filename>
      <envlist>A,B,C,D</envlist>
      <temporange>1-3000</temporange>
    </sound>
    <netmodule id="222" instance="1">
      <event name="periodic">
		<param name="frequency">3000</param>
		<listener>
		</listener>
      </event>
    </netmodule>
  </soundmodule>

;;; This is the second SoundModule. When it receives an event called
;;; periodic from PeriodicModule and the global environment is A
;;; it plays the sound contained in the filename "gong8.ogg".
  <soundmodule id="2" type="default">
    <sound>
      <filename>gong8.ogg</filename>
      <envlist>A</envlist>
      <temporange>1-3000</temporange>
    </sound>
    <netmodule id="222" instance="1">
      <event name="periodic">
		<param name="frequency">5000</param>
		<listener>
		</listener>
      </event>
    </netmodule>
  </soundmodule>

;;; This is the third SoundModule. When it receives an event called
;;; periodic from PeriodicModule and the global environment is B
;;; it plays the sound contained in the filename "woohoo.ogg".
  <soundmodule id="3" type="default">
    <sound>
      <filename>woohoo.ogg</filename>
      <envlist>B</envlist>
      <temporange>1-3000</temporange>
    </sound>
    <netmodule id="222" instance="1">
      <event name="periodic">
		<param name="frequency">5000</param>
		<listener>
		</listener>
      </event>
    </netmodule>
  </soundmodule>

;;; This is the fourth SoundModule. When it receives an event called
;;; periodic from PeriodicModule and the global environment is C
;;; it plays the sound contained in the filename "tada.ogg".
  <soundmodule id="3" type="default">
    <sound>
      <filename>tada.ogg</filename>
      <envlist>C</envlist>
      <temporange>1-3000</temporange>
    </sound>
    <netmodule id="222" instance="1">
      <event name="periodic">
		<param name="frequency">5000</param>
		<listener>
		</listener>
      </event>
    </netmodule>
  </soundmodule>
  
;;; This is the fifth SoundModule. When it receives an event called
;;; periodic from PeriodicModule and the global environment is D
;;; it plays the sound contained in the filename "doh.ogg".
  <soundmodule id="4" type="default">
    <sound>
      <filename>doh.ogg</filename>
      <envlist>D</envlist>
      <temporange>1-3000</temporange>
    </sound>
    <netmodule id="222" instance="1">
      <event name="periodic">
		<param name="frequency">5000</param>
		<listener>
		</listener>
      </event>
    </netmodule>
  </soundmodule>

</soundpalette>

----------------------------------------------------------------------
Richard Liston
Sun Apr 18 15:15:29 EDT 2004