RateTracker
===========

RateTracker is a simple module designed to be used in conjunction with the
SharedSound module from ESP.

SharedSound provides a mechanism for several different claimants to use the
sound system at the same time, possibly at different frequencies. At no point
however does SharedSound ever set the global sound system frequency.

The original idea of this is that a user could set the global system frequency
once at startup (typically to whatever it is configured to be). Nothing should
ever change this and everything should run happily from that point onwards. A
user can therefore select the sound frequency that is right for the processing
power of their machine and not ever have to worry again.

Sadly, as not everything uses SharedSound this falls down a bit; often 'badly
behaved', pre-SharedSound apps come along and set the frequency to whatever
they need. SharedSound does its best to cope by telling its registered sound
handlers (the applications/modules actually producing sound) to resample their
output to a different frequency.

This can lead to SharedSound putting up with a less than ideal sound rate;
either samples are needlessly resampled to a higher rate, or they are played
at less than their full resolution.

RateTracker is an attempt to cure this problem. Once a second it scans the
registered handlers using SharedSound at the moment; if nothing is registered
it does nothing. Otherwise it sets the global sound frequency to be the
highest frequency currently requested.

This means that:

 * A handler should never be asked to resample its output up unnecessarily (*).
 
 * In the most common situation of just one sound source operating at a time
   the global sound system will be set to the rate that that source has
   requested (thus eliinating any aliasing effects) (*).
 
 * When several sources are playing together the lower quality sources will
   not cause the higher quality one to be 'dragged down' to their level.
   
[ * Subject to the underlying sound system supporting the requested rate.]

Basically, stick this in your !Boot.Choices.Boot.PreDesk directory and
forget about it.


Possible future extensions
--------------------------

 * Have configurable minimum/maximum sample rates. Minimum rate will allow
   forced oversampling at low rates and maximum one will limit CPU usage.

 * Anything else worthwhile that people suggest.


Copyright
---------

The RateTracker module and associated files are Copyright (C) 2001 Robin
Watts for Warm Silence Software Ltd, all rights reserved.

They may be freely copied and distributed for non-commercial use provided
no charge (other than possibly a nominal media charge) is made, and that
the associated ReadMe files are included.

Inclusion with a commercial product or on a magazine disc/CD is not
permitted without the authors permission, though this permission will
not generally be withheld (basically I want to keep track of where it
goes!). The author reserves the right to charge a license fee for the
use of this software in any commercial system.


Warranty
--------

This is an unwarrantied product. I'll say that again; no warranty is given.
If it eats your data, scares your children or impregnates your cat, its your
problem.

This is an unsupported product. Warm Silence Software Ltd cannot *promise* to
offer any advice, help or other support for this module, but we may be able
to help out with simple problems; feel free to contact us - at worst we'll
ignore you.


Contact Addresses
-----------------

Warm Silence Software can be reached at the following addresses:

  Snail Mail: Warm Silence Software Ltd
              PO Box 28
              Woodstock
              Oxfordshire
              OX20 1XX
       Email: info@wss.co.uk
         WWW: http://www.wss.co.uk/
     Tel/Fax: 01608 737172
      Mobile: 07558 467642


Version history
---------------

20/2/01: 0.01

  Initial version.

20/2/01: 0.02

  Reissued so that the 26bit version no longer says 32bit.

24/2/01: 0.03

  Workaround for SharedSound bug in enumerating handlers.

??/??/01: 0.04/0.05

  Not a clue. Probably really important.

??/??/02: 0.06-0.08
  
  Similar lack of clue. Undoubtedly important.
  Developed by RISC OS.
