The IotaSound module

The IotaSound module (download: 5K) provides an easy way of playing sound samples on Acorn RiscOS computers. Using The Complete Animator, you can create a SoundLib file containing several samples, and play them using a dead simple interface. You'll also need to know about the IotaSound module if you're writing code that plays back Film files made with The Complete Animator.

When your application starts, call SWI IotaSound_RegisterApp.

To load a SoundLib file, call SWI IotaSound_LoadFile. This will return a wave-table handle, which you then use to identify which pool of sounds you want to make noises from.

(If you don't have a SoundLib file, but instead have an Iota Film file, then call SWI IotaSound_LoadTable, which also returns a wave-table handle.)

The simplest way to make a noise is then to make a call to SWI IotaSound_TrySound. If you want more control over the sound (its pitch, for instance), or if you want to play the sounds from a film file, you'll need SWI IotaSound_Play instead.

You can test whether any noises are still playing by calling IotaSound_Playing. Note that other programs might be using the IotaSound module too, so if there is a sound playing, it's not necessarily yours!

You must call IotaSound_ReleaseTable when you've finished with a wave-table. This call releases memory which IotaSound uses to keep the sounds in. (In fact, they're kept in the system sprite area.) If you're programming in C, you should consider doing this in your atexit handler; if in BASIC, it ought to be in your ON ERROR code.

At the very end of your application (just before you call SWI Wimp_CloseDown), you should call IotaSound_DeregisterApp.

This is a complete BBC BASIC program which plays a random sound from a given file, and then exits as soon as the sound has finished. For clarity, no error handling is shown, but there should of course be some, e.g. in case of 'file not found'.

      10 : SYS "Wimp_Initialise",200,&4B534154,"A noise"
      20 : SYS "IotaSound_RegisterApp"
      30 : DIM event% 256
      40 : SYS "IotaSound_LoadFile","SoundsFile"
           TO handle%, num%
      50 : SYS "IotaSound_TrySound",handle%,RND(num%)-1
      60 : REPEAT
      70 :     SYS "IotaSound_Playing" TO A%
      80 :     SYS "Wimp_Poll",0,event%
      90 : UNTIL A%=0
     100 : SYS "IotaSound_ReleaseTable",handle%
     110 : SYS "IotaSound_DeregisterApp"
     120 : SYS "Wimp_CloseDown"
 

The ADPCM support in IotaSound was adapted (read, hand-compiled) from C code supplied with the following copyright notice:

Copyright 1992 by Stichting Mathematisch Centrum, Amsterdam, The
Netherlands.

                        All Rights Reserved

Permission to use, copy, modify, and distribute this software and its 
documentation for any purpose and without fee is hereby granted, 
provided that the above copyright notice appear in all copies and that
both that copyright notice and this permission notice appear in 
supporting documentation, and that the names of Stichting Mathematisch
Centrum or CWI not be used in advertising or publicity pertaining to
distribution of the software without specific, written prior permission.

STICHTING MATHEMATISCH CENTRUM DISCLAIMS ALL WARRANTIES WITH REGARD TO
THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
FITNESS, IN NO EVENT SHALL STICHTING MATHEMATISCH CENTRUM BE LIABLE
FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT
OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.