This page explains how to use the sound capabilities of the retrocomputers. It will deal with simple audio effects and, more over, the use of music in ugBASIC.
Generally, the sound capabilities of a retrocomputer are a bit limited,
but ugBASIC sound commands operate independently from
other routines, so that they can never interfere with your programming.
On the contrary, they should enhance your work in any way that you chose,
acting as markers, adding realism, soothing, shocking or providing
comic relief.
Audio, notes and sound effects can be used in an ugBASIC program.
There are three common sound effects that can be called up by their
own commands, and used for testing and punctuating your routines.
By making use of the internal chipset to simulate “white noise”,
the BOOM
command plays a realistic explosive sound effect.
This does not delay the program at all, so it may be necessary to use
WAIT
between successive explosions, or to create specific
audio effects. For example:
CENTRE "Thunderbolt and Lightning"
BOOM : WAIT 1000 MS: BOOM: CLS
CENTRE "Very Very Frightening"
WAIT 500 MS: BOOM
On the other hand, the SHOOT
command generates a simple
sound effect in exactly the same way as BOOM
.
For example:
SHOOT: WAIT 1000 MS: SHOOT: PRINT "Ouch!"
Unlike the built-in explosive sound effects, BELL
produces a simple pure tone. The "pitch" of this sound can be
changed by adding a "pitch value" after the BELL
command, ranging from 0
for a very deep sound, up to
107
for an ultra high pitched sound. You can hear
the range of frequencies with this example:
FOR f=0 TO 107
BELL f
WAIT (f/10+1)*1000 MS
NEXT
Another way to produce sound in ugBASIC is with the use of the
SOUND
command. This command can accept various
parameters, depending on the use you want to make of it.
The simplest form is to reproduce a certain frequency for
a certain duration:
SOUND 440, 1000 MS :'(reproduce a 440 Hz sound for 1 second)
Sometimes it can be useful to be able to reproduce a sound
while doing other processing. In this case, you can omit the duration
and the sound will continue until the next command or until it is
stopped with the SOUND OFF
command.
SOUND 440
FOR i=0 TO 10 : PRINT "OK!": WAIT 500 MS : NEXT
SOUND OFF
Sometimes it can be useful to reproduce frequencies on multiple
channels, or "voices". The SOUND
command also accepts
a third parameter prefixed by the keyword ON
, which is
a bitmask with the mapping of the voices.
SOUND 440, 1000 MS ON %0010 (reproduce a 440 Hz sound for 1 second on voice 1)
This additional parameter with the voice is clearly available even
if you do not indicate a duration, and this allows you to produce polyphony.
SOUND 440 ON %0001: SOUND 480 ON %0010
FOR i=0 TO 10 : PRINT "OK!": WAIT 500 MS : NEXT
SOUND OFF
The values from 0
to 107
that are used
to control the pitch of the BELL
sound correspond to
the notes on the keyboard of a piano. The white key at the extreme
left-hand side of the keyboard is known as "Bottom C", and corresponds
to pitch value 0
. Value 1
is the equivalent
to the black note next to it, which is a C#, and so on up to “Middle C”
at pitch value 6
, then all the way up to 107.
In reality, grand piano keyboards run out of notes after 88
,
and most synthesizer keyboards have a lot less than that.
In Western music, notes are given their own code letter so that
musicians can all refer to the same pitch when they try and play
together. These letters repeat themselves after twelve notes, and
each group of twelve is known as an “octave”.
To indicate a specific note (of middle octave) you can use the NOTE
command, like NOTE C#
or NOTE D
. In order to
indicate the octave, you can use the NOTE C4
annotation.
So you can use the following command to sound a bell with A
note:
BELL NOTE A4
The retrocomputer produces sound like a river, and ugBASIC
allows you to split this river into various separate channels, all pouring
out at the same time, but each capable of individual control. These channels
can be heard individually, or mixed together, or directed to the left and
right creating stereo sound. They can also be individually increased and
decreased in volume, or dammed up altogether. Obviously, it depends on
the specific chipset capabilities if these channels can be given a different
"voice", and each voice can be controlled in terms of volume and direction.
The VOLUME
command controls the level of sound flowing through
one or more channels, ranging from MIN VOLUME
(complete silence)
up to MAX VOLUME
(ear-splitting), like this:
FOR level=VOLUME MIN TO VOLUME MAX
VOLUME level
BELL NOTE C4
WAIT 500 MS
NEXT
Once the VOLUME
level has been set, all future sound effects
and music will be delivered at that level, across all four channels.
In order to create "stereo" effects and perfect sound mixes, each of
the voices needs to be adjusted independently from one another.
The volume of each voice can now be controlled by specifying voices
and volumes, like this:
VOLUME 63 ON %0001
BOOM : WAIT 100 MS
VOLUME 5 ON %1110
BOOM : WAIT 50 MS
BELL 40 : WAIT 50
VOLUME 60: BELL 40
Patterns of individual notes can be played, allocated to any voice,
given a pitch and delayed for pause, using just one PLAY
command:
PLAY voice, note, delay
The voice parameter is optional, allowing notes to be played through any
combination of the retrocomputer voices, and is set by the usual bitmap
format. The note parameter uses the values from 0
to 107
,
or by using the NOTE
annotation. The parameter delay
sets the length of any pause between this PLAY
command and the
next instruction in the program, with a value of zero starting the note
and immediately going on to the next command.
The next example demonstrates this technique, including stereo harmonies:
PLAY 40, 0 ON 1: PLAY 50, 0 ON 2
WAIT KEY
PLAY 50, 15 ON 1: PLAY 50, 15 ON 2
DO
v = RND(5)
p = RND(108)
PLAY p, 3 ON v
LOOP
PLAY
is not restricted to pure notes. It is possible to assign
complex wave forms to voices, using the WAVE
and NOISE
commands, which are explained next. To stop the playing process, simply
turn it off like this:
PLAY OFF
Some audio chipsets have the ability to define the waveform of the sound
that will be output, to make it look like an instrument. Others have the
ability to use actual "samples", which will then be reproduced at certain
frequencies. The ugBASIC language provides a set of
primitives that allow you to take advantage of this feature.
The most useful (and easy) command is INSTRUMENT
. This command
allows you to modify the waveform of one of the voices, so that subsequent
commands such as SOUND
or PLAY
modify the sound.
The syntax is quite easy:
INSTRUMENT $42 ON %0001
: ' Use the saxophone on voice 1
The instrument can also be indicated symbolically. Accepted values follows:
The ugBASIC music system allows backing tracks to
be added to any program. Music can be created from a variety of
sources, including MIDI files. These tracks are converted into IMF
format, and can be used as well. Music tracks are loaded with the
MUSIC
command, volume is controlled by MUSIC VOLUME
,
and speed by MUSIC TEMPO
. Individual music passages can be
halted using the MUSIC STOP
instruction, and all music is
halted by MUSIC OFF
.
For a taster of these techniques in action, load this ready-made example:
music := LOAD("examples/music.imf")
MUSIC music: MUSIC VOLUME MAX VOLUME: MUSIC TEMPO 35
If you have found a problem, if you think there is a bug or, more
simply, you would like something to be improved, write a topic on the official forum, or open an issue on GitHub.
Thank you!