This chapter 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 ricochet and echo 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 ring, 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 entries.

  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. 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 are available on the command's manual page.

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