R-21: SOUND MUSIC & SPEECH COMMANDS 

Sound objects are used to store audio information. This information can be taken
from an 8SVX IFF file using LoadSound, or defined by hand through a BASIC routine
using InitSound and SoundData. Once a sound is created, it may be played through the
Amiga's audio hardware.

Blitz supports loading and playing of both soundtracker and medmodule music files.

The Amiga speech synthesiser is also accessible from Blitz. The narrator.device has
been upgraded in 2.0 increasing the quality of the speech. With a bit of messing
around you can have a lot of fun with the Amiga's 'voice'.


LoadSound Sound#,Filename$ 

LoadSound creates a sound object for later playback. The sound is taken from an 8SVX
IFF file. An error will be generated if the specified file is not in the correct IFF
format.


Sound Sound#,Channelmask[,Vol1[,Vol2...]] 

Sound causes a previously created sound object to be played through the Amiga's
audio hardware. Channelmask specifies which of the Amiga's four audio channels the
sound should be played through, and should be in the range one through fifteen.


The following is a list of Channelmask values and their effect:

Mask   Channel0    Channel1    Channel2    Channel3 
1      on          off         off         off
2      off         on          off         off
3      on          on          off         off
4      off         off         on          off
5      on          off         on          off
6      off         on          on          off
7      on          on          on          off
8      off         off         off         on
9      on          off         off         on
10     off         on          off         on
11     on          on          off         on
12     off         off         on          on
13     on          off         on          on
14     off         on          on          on
15     on          on          on          on

In the above table, any audio channels specified as 'off' are not altered by Sound,
and any sounds they may have previously been playing will not be affected.

The Volx parameters allow individual volume settings for different audio channels.
Volume settings must be in the range zero through 64, zero being silence, and 64
being loudest.

The first Vol parameter specifies the volume for the lowest numbered 'on' audio
channel, the second Vol for the next lowest and so on.

For example, assume you are using the following Sound command:

Sound 0,10,32,16

The Channelmask of ten means the sound will play through audio channels one and
three. The first volume of 32 will be applied to channel one, and the second volume
of 16 will be applied to channel three.

Any Vol parameters omitted will be cause a volume setting of 64.


LoopSound Sound#,Channelmask[,Vol1[,Vol2]] 

LoopSound behaves identically to Sound, only the sound will be played repeatedly.
Looping a sound allows for the facility to play the entire sound just once, and
begin repeating at a point in the sound other than the beginning. This information
is picked up from the 8SVX IFF file, when LoadSound is used to create the sound, or
from the offset parameter of InitSound.


Volume Channelmask, Vol1[,Vol2...] 

Volume allows you to dynamically alter the volume of an audio channel. This enables
effects such as volume fades. For an explanation of Channelmask and Vol parameters,
please refer to the Sound command.


InitSound Sound#,Length[,Period[,Repeat]] 

InitSound initializes a sound object in preparation for the creation of custom sound
data. This allows simple sound waves such as sine or square waves to be
algorithmically created. SoundData should be used to create the actual wave data.

Length refers to the length, in bytes, the sound object is required to be. Length
MUST be less than 128K, and MUST be even.

Period allows you to specify a default pitch for the sound. A period of 428 will
cause the sound to be played at approximately middle 'C'.

Offset is used in conjunction with LoopSound, and specifies a position in the sound
at which repeating should begin. Please refer to LoopSound for more information on
repeating sounds.


SoundData Sound#,Offset,Data 

SoundData allows you to manually specify the waveform of a sound object. The sound
object should normally have been created using InitSound, although altering IFF
sounds is perfectly legal.

SoundData alters one byte of sound data at the specified Offset. Data refers to the
actual byte to place into the sound, and should be in the range -128 to +127.


PeekSound (Sound#,Offset) 

PeekSound returns the byte of a sample at the specified offset of the sound object
specified.


DecodeSound Sound#,MemoryLocation 

DecodeSound, similar to the other new Decode commands allows the programmer to
include sound files within their program's object code.


SetPeriod Sound#,Period 

This command allows the programmer to manually adjust the period of the sound object
to change it's effective pitch.


DiskPlay Filename$, Channelmask[,Vol1[,Vol2...]] 

DiskPlay will play an 8SVX IFF sound file straight from disk. This is ideal for
situations where you simply want to play a sample without the extra hassle of
loading a sound, playing it, and then freeing it. The DiskPlay command will also
halt program flow until the sample has finished playing.

DiskPlay usually requires much less memory to play a sample than the LoadSound,
Sound technique. Also, DiskPlay allows you to play samples of any length, whereas
LoadSound only allows samples up to 128K in length to be loaded.


DiskBuffer Bufferlen 

DiskBuffer allows you to set the size of the memory buffer used by the DiskPlay
command. This Buffer is by default set to 1024 bytes, and should not normally have
to be set to more than this.

Reducing the buffer size by too much may cause loss of sound quality of the DiskPlay
command.

If you are using DiskPlay to access a very slow device, the buffer size may have to
be increased.


Filter On|Off 

Filter may be used to turn on or off the Amiga's low pass audio filter.


LoadModule Module#,Filename$ 

LoadModule loads in from disk a soundtracker/noisetracker music module. This module
may be later played back using PlayModule.


Free Module Module# 

Free Module may be used to delete a module object. Any memory occupied by the module
will also be free'd.


PlayModule Module# 

PlayModule will cause a previously loaded soundtracker/noisetracker song module to
be played back.


StopModule 

StopModule will cause any soundtracker/noisetracker modules which may be currently
playing to stop.


LoadMedModule MedModule# FileName$ 

The LoadMedModule command loads any version 4 channel Octamed module. The following
routines support upto and including version 3 of the Amiganut's Med standard.

The number of MedModules loaded in memory at one time is only limited by the
MedModules maximum set in the Blitz Options requester. Like any Blitz commands that
access files LoadMedModule can only be used in AmigaMode.


StartMedModule MedModule# 

StartMedModule is responsible for initialising the module including LINKing after it
is loaded from disk using the LoadMedModule command. It can also be used to restart
a module from the beginning.


PlayMed

PlayMed is responsible for playing the current MedModule, it must be called every
50th of a second either on an interupt (#5) or after a VWait in a program loop.


StopMed

StopMed will cause any med module to stop playing. This not only means that PlayMed
will have no affect until the next StartMedModule but silences the audio channels so
they are not left ringing as is the effect when PlayMed is not called every vertical
blank.


JumpMed Pattern# 

JumpMed will change the pattern being played in the current module.


SetMedVolume Volume 

SetMedVolume changes the overall volume that the Med Library plays the module, all
the audio channels are affected. This is most useful for fading out music by slowly
decreasing the volume from 64 to 0.


GetMedVolume Channel# 

GetMedVolume returns the current volume setting of the specified audio channel. This
is useful for graphic effects that you may wish to sync to certain channels of the
music playing.


GetMedNote Channel# 

GetMedNote returns the current note playing from the specified channel. As with
GetMedVolume this is useful for producing graphics effects synced to the music the
Med Library is playing.


GetMedinstr Channel 

GetMedInstr returns the current instrument playing through the specified audio
channel.


SetMedMask Channel Mask 

SetMedMask allows the user to mask out audio channels needed by sound effects
stopping the Med Library using them.


DecodeMedModule MedModule#,MemoryLocation 

DecodeMedModule replaces the cludgemedmodule, as med modules are not packed but used
raw, DecodeMedModule simply checks to see the memory location passed is in ChipMem
(if not it copies the data to chip) and points the Blitz MedModule object to that
memory.


Speak string$ 

The Speak command will first convert the given string to phonetics and then pass it
to the Narrator.Device. Depending on the settings of the Narrator device (see
SetVoice) the Amiga will "speak" the string you have sent in the familiar Amiga
synthetic voice.


SetVoice rate,pitch,expression,sex,volume,frequency 

SetVoice alters the sound of the Amiga's speech synthsiser by changing the vocal
characteristics listed in the parameters above.


Translate$ (string$) 

Translate$() returns the phonetic equivalent of the string for use with the
PhoneticSpeak command.


PhoneticSpeak phonetic$ 

PhoneticSpeak is similar to the Speak command but should only be passed strings
containing legal phonemes such as that produced by the Translate$() function.


VoiceLoc 

VoiceLoc returns a pointer to the internal variables in the speech synthesiser that
enable the user to access new parameters added to the V37 Narrator Device.

Formants as referred to in the descriptions are the major vocal tracts and are
separated into the parts of speech that produce the bass, medium and trebly sounds.