The first command you send to the audio device should always be
adcmd_allocate.  you can do this when you open the device, or at a later
time.  You specify the channels you want in the ioa_Data field of the
ioaudio block. if the allocation succeeds, the audio device will return
the channels that you now own in the lower four bits of the
ioa_Request.io_Unit field of your ioaudio block. for instance, if the
io_Unit field equals 5 (binary 0101) then you own channels 2 and 0.  If
the io_Unit field equals 15 (binary 1111) then you own all the channels.

When you send the adcmd_allocate command, the audio device will also
return a unique allocation key in the ioa_AllocKey of the ioaudio block.
You must use this allocation key for all subsequent commands that you send
to the audio device.  The audio device uses this unique key to identify
which task issued the command.  If you do not use the correct allocation
key assigned to you by the audio device when you send a command, your
command will be ignored.

When you request a channel with adcmd_allocate, you specify a precedence
number from -128 to 127 in the ioa_Request.io_Message.mn_Node.ln_Pri field
of the IOAudio block. If a channel you want is being used and you have
specified a higher precedence than the current user, ADCMD_ALLOCATE will
"steal" the channel from the other user. Later on, if your precedence is
lower than that of another user who is performing an allocation, the
channel may be stolen from you.

If you set the precedence to 127 when you open the device or raise the
precedence to 127 with the adcmd_setprec command, no other tasks can steal
a channel from you. When you have finished with a channel, you must
relinquish it with the adcmd_free command to make it available for other
users.

The following table shows suggested precedence values.

                SUGGESTED PRECEDENCES FOR CHANNEL ALLOCATION

   Predecence                   Type of Sound
   ----------                   -------------
     127          Unstoppable. Sounds first allocated at lower precedence,
                  then set to this to the highest level.

     90 - 100     Emergencies.  Alert, urgent situation
                  that requires immediate action.

     80 - 90      Annunciators.  Attention, bell (CTRL-G).

     75           Speech. Synthesized or recorded speech (narrator.device).

     50 - 70      Sonic cues.  Sounds thatprovide information that is not
                  provided by graphics. Only the beginning of each sound
                  (enough to recognize it) should be at this level;the rest
                  should be set to sound effects level.

    -50 - 50      Music program.  Musical notes in music-oriented program.
                  The higher levels should be used for the attack portions
                  of each note.

    -70 - -50     Sound effects.  Sounds used in conjunction with graphics.
                  More important sounds should use higher levels.

    -100 - -80    Background. Theme music and restartable background
                  sounds.

    -128          Silence. Lowest level (freeing the channel completely
                  is preferred).

If you attempt to perform a command on a channel that has been stolen from
you by a higher priority task, an AUDIO_NOALLOCATION error is returned and
the bit in the ioa_Request.io_Unit field corresponding to the stolen
channel is cleared so you know which channel was stolen.

If you want to be warned before a channel is stolen so that you have a
chance to stop your sound gracefully, then you should use the adcmd_lock
command after you open the device.  This command is also useful for
programs which write directly to the audio hardware.  For more on
adcmd_lock, see the section below.