====== ugBASIC User Manual ======

===== AUDIO =====

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.

==== Available sound effects ====

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

==== Playing frequencies ====

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

==== Musical notes ====

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

==== Channels and voices ====

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

==== Playing notes ====

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

==== Using instruments ====

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.

==== Playing music ====

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