BBC BASIC Programmers' Reference

by Richard Russell, April 2024

BBC BASIC for SDL 2.0 provides a number of methods for outputting sounds and music, for example the SOUND statement and the audiolib library. However there may be circumstances when you want more control over the audio output, such as generating continuous tones of a particular waveform and/or frequency.

One way you can go about that is to create a .WAV or .MP3 file containing the required audio content, and play that using the audiolib library, but that isn't suitable when you need continuous output or real-time control. In those cases you can use the method described in this article, which allows you to create and output audio data directly under the control of your program.

As is usual for programs accessing the SDL 2.0 API, it is important to trap errors, and closing the window, so that the necessary 'cleanup' operations can take place:

        ON ERROR PROCcleanup : MODE 7 : PRINT REPORT$ : QUIT
        ON CLOSE PROCcleanup : QUIT

The PROCcleanup routine is listed later. You may want to change the error reporting to a different method.

The first step is to decide the audio format you will use: the principal choices being of sampling rate (the main ones being 11025 Hz, 22050 Hz and 44100 Hz) and number of channels (mono, 1 channel, or stereo, 2 channels). The higher the sampling rate the higher the audio frequency that can be generated, but the more work your software needs to do. Normally you should choose the lowest sampling rate suitable for your application, remembering that it needs to be at least double the highest audio frequency to be generated (according to the Nyquist criterion).

You set up the required audio format and open the wave output device as follows:

The next step is to decide the audio format you will use: the principal choices being of sampling rate (the main ones being 11025 Hz, 22050 Hz and 44100 Hz) and number of channels (mono, 1 channel, or stereo, 2 channels). The higher the sampling rate the higher the audio frequency that can be received, but the more work your software needs to do. Normally you should choose the lowest sampling rate suitable for your application, remembering that it needs to be at least double the highest audio frequency in which you are interested (according to the Nyquist criterion).

You set up the required audio format and open the audio device as follows:

      DIM audiospec{freq%, format{l&,h&}, channels&, silence&, samples%, size%, callback%%, userdata%%}
      audiospec.freq% = 44100
      audiospec.format.h& = &80 : REM AUDIO_S16LSB
      audiospec.format.l& = &10 : REM AUDIO_S16LSB
      audiospec.channels& = 1
 
      SYS "SDL_OpenAudioDevice", FALSE, FALSE, audiospec{}, 0, 0, @memhdc% TO @hwo%
      IF @hwo% = 0 ERROR 100, "Couldn't open audio device"

In this example a sampling rate of 44100 Hz and monaural (single channel) output has been selected.

The next step is to decide how large the audio buffer needs to be. To some extent this is an arbitrary decision, but it will depend on things like latency (how much time elapses between your program generating the audio data and the actual sound output) and the amount of work needed to create the audio data.

It is vitally important that your program can create the audio data quickly enough, otherwise there will be interruptions (clicks and stutters) to the sound output. If there is any variability in the rate at which you can generate the data (for example it depends on disk or network accesses) then you may need to use a larger buffer to 'iron out' the fluctuation, but this will necessarily result in greater latency.

In the example below the buffer size is 1024 samples; at 44100 Hz that implies a total latency of about 24 milliseconds. The code for creating and initialising the buffer is as follows:

        SamplesPerBuffer% = 1024
        BytesPerBuffer% = SamplesPerBuffer% * audiospec.channels& * 2
        WordsPerBuffer% = BytesPerBuffer% DIV 4
 
        DIM Buffer%(WordsPerBuffer%)

Note that in this case the audio buffer is allocated from BASIC's heap; you could alternatively use the SDL 2.0 API to allocate the memory.

Once the above code has been executed you need to refill the audio buffer fast enough to keep up with the requested sampling rate. The following code cycles, calling the PROCfillbuffer routine then outputting the data:

        REPEAT
          lpData%% = ^Buffer%(0)
          PROCfillbuffer(lpData%%, SamplesPerBuffer%)
          SYS "SDL_QueueAudio", @hwo%, lpData%%, BytesPerBuffer%, @memhdc%
          SYS "SDL_PauseAudioDevice", @hwo%, 0, @memhdc%
          REPEAT
            WAIT 1
            SYS "SDL_GetQueuedAudioSize", @hwo%, @memhdc% TO S%            
          UNTIL S% < 2 * BytesPerBuffer%
        UNTIL FALSE
        END

In this example the sound generation continues indefinitely, but you can terminate the process prematurely if you wish. If you do, don't forget to execute PROCcleanup before exiting the program.

Obviously it's only possible to describe this aspect in general terms, because precisely what audio data you need to generate will depend on what the program is designed to do. One of the simplest applications is to generate a single pure (sine wave) tone of a specified frequency. The code below does that, where the frequency (in Hz) is assumed to be in the global variable Frequency:

        DEF PROCfillbuffer(B%%, N%)
        LOCAL I%, D
        PRIVATE P
        D = Frequency / audiospec.freq% * 2*PI : REM Phase change per sample
        FOR I% = 0 TO 2*N%-2 STEP 2
          B%%!I% = 32767*SIN(P)
          P += D
        NEXT
        ENDPROC

This code is appropriate for monaural output (one channel) where each audio sample consists of a signed 16-bit value in the range -32767 to +32767. Note that, since BBC BASIC has no 16-bit operations, 32-bit indirection (“B%%!I%”) is used to write to the audio buffer. As a result it is inevitable that two bytes after the end of the buffer are corrupted; therefore it is essential that when the buffers are created two extra bytes of memory at the end are allocated.

When you stop the sound generation, or exit the program, you need to shut down the audio output in a controlled fashion:

      DEF PROCcleanup
      IF @hwo% THEN
        SYS "SDL_PauseAudioDevice", @hwo%, 1, @memhdc%
        SYS "SDL_CloseAudioDevice", @hwo%, @memhdc%
      ENDIF
      ENDPROC

This code might form part of a larger routine, if there are other things that need to be shut down.

by Richard Russell, November 2006

BBC BASIC for Windows provides a number of methods for outputting sounds and music, for example the SOUND statement and the *PLAY command. However there may be circumstances when you want more control over the audio output, such as generating continuous tones of a particular waveform and/or frequency.

One way you can go about that is to create a .WAV file containing the required audio content, and play that using SYS "PlaySound", but that isn't suitable when you need continuous output or real-time control. In those cases you can use the method described in this article, which allows you to create and output audio data directly under the control of your program.

As is usual for programs accessing the Windows API, it is important to trap errors, and closing the window, so that the necessary 'cleanup' operations can take place:

        ON ERROR PROCcleanup : SYS "MessageBox", @hwnd%, REPORT$, 0, 48 : QUIT
        ON CLOSE PROCcleanup : QUIT

The PROCcleanup routine is listed later. You may want to change the error reporting to a different method.

The first step is to decide the audio format you will use: the principal choices being of sampling rate (the main ones being 11025 Hz, 22050 Hz and 44100 Hz) and number of channels (mono, 1 channel, or stereo, 2 channels). The higher the sampling rate the higher the audio frequency that can be generated, but the more work your software needs to do. Normally you should choose the lowest sampling rate suitable for your application, remembering that it needs to be at least double the highest audio frequency to be generated (according to the Nyquist criterion).

You set up the required audio format and open the wave output device as follows:

        DIM Format{wFormatTag{l&,h&}, nChannels{l&,h&}, nSamplesPerSec%, \
        \          nAvgBytesPerSec%, nBlockAlign{l&,h&}, wBitsPerSample{l&,h&}, \
        \          cbSize{l&,h&}}
 
        Format.wFormatTag.l& = 1 : REM WAVE_FORMAT_PCM
        Format.nChannels.l& = 1  : REM Monaural
        Format.nSamplesPerSec% = 44100
        Format.wBitsPerSample.l& = 16
        Format.nBlockAlign.l& = Format.nChannels.l& * Format.wBitsPerSample.l& / 8
        Format.nAvgBytesPerSec% = Format.nSamplesPerSec% * Format.nBlockAlign.l&
 
        _WAVE_MAPPER = -1
        SYS "waveOutOpen", ^WaveOut%, _WAVE_MAPPER, Format{}, 0, 0, 0 TO ret%
        IF ret% ERROR 100, "waveOutOpen failed: "+STR$~ret%

In this example a sampling rate of 44100 Hz has been selected.

The next step is to decide how many audio buffers you need and how large they should be. To some extent this is an arbitrary decision, but it will depend on things like latency (how much time elapses between your program generating the audio data and the actual sound output) and the amount of work needed to create the audio data.

Normally you should have at least three buffers: one outputting the sound, one being filled with audio data by your program, and one spare (the buffers are reused cyclically). It is vitally important that your program can create the audio data quickly enough, otherwise there will be interruptions (clicks and stutters) to the sound output. If there is any variability in the rate at which you can generate the data (for example it depends on disk or network accesses) then you may need to use more and/or larger buffers to 'iron out' the fluctuation, but this will necessarily result in greater latency.

In the example below the number of buffers is three and the length of each buffer is 1024 samples; at 44100 Hz that implies a total latency of about 70 milliseconds. The code for creating and initialising the buffers is as follows:

        nBuffers% = 3
        SamplesPerBuffer% = 1024
        BytesPerBuffer% = SamplesPerBuffer% * Format.nBlockAlign.l&
 
        DIM _WAVEHDR{lpData%, dwBufferLength%, dwBytesRecorded%, dwUser%, \
        \            dwFlags%, dwLoops%, lpNext%, Reserved%}
 
        DIM Headers{(nBuffers%-1)} = _WAVEHDR{}
 
        FOR buff% = 0 TO nBuffers%-1
          DIM buffer% BytesPerBuffer% + 1 : REM. 2 spare bytes at end
 
          Headers{(buff%)}.lpData% = buffer%
          Headers{(buff%)}.dwBufferLength% = BytesPerBuffer%
 
          SYS "waveOutPrepareHeader", WaveOut%, Headers{(buff%)}, DIM(_WAVEHDR{}) TO ret%
          IF ret% ERROR 100, "waveOutPrepareHeader failed: "+STR$~ret%
 
          SYS "waveOutWrite", WaveOut%, Headers{(buff%)}, DIM(_WAVEHDR{}) TO ret%
          IF ret% ERROR 100, "waveOutWrite failed: "+STR$~ret%
        NEXT

Note that in this case the audio buffers are allocated from BASIC's heap; you could alternatively use the Windows API to allocate the memory.

Once the above code has been executed you need to refill the audio buffers fast enough to keep up with the requested sampling rate. The following code constantly checks whether any of the buffers needs refilling and if so calls the PROCfillbuffer routine:

        _WHDR_DONE = 1
        REPEAT
          FOR buff% = 0 TO nBuffers%-1
            IF Headers{(buff%)}.dwFlags% AND _WHDR_DONE THEN
              PROCfillbuffer(Headers{(buff%)}.lpData%, SamplesPerBuffer%)
              Headers{(buff%)}.dwFlags% AND= NOT _WHDR_DONE
              SYS "waveOutWrite", WaveOut%, Headers{(buff%)}, DIM(_WAVEHDR{})
            ENDIF
          NEXT
          SYS "Sleep", 1
        UNTIL FALSE

In this example the sound generation continues indefinitely, but you can terminate the process prematurely if you wish. If you do, don't forget to execute PROCcleanup before exiting the program.

Obviously it's only possible to describe this aspect in general terms, because precisely what audio data you need to generate will depend on what the program is designed to do. One of the simplest applications is to generate a single pure (sine wave) tone of a specified frequency. The code below does that, where the frequency (in Hz) is assumed to be in the global variable Frequency:

        DEF PROCfillbuffer(B%, N%)
        LOCAL I%, D
        PRIVATE P
        D = Frequency / Format.nSamplesPerSec% * 2*PI : REM Phase change per sample
        FOR I% = 0 TO 2*N%-2 STEP 2
          B%!I% = 32767*SIN(P)
          P += D
        NEXT
        ENDPROC

This code is appropriate for monaural output (one channel) where each audio sample consists of a signed 16-bit value in the range -32767 to +32767. Note that, since BBC BASIC has no 16-bit operations, 32-bit indirection (“B%!I%”) is used to write to the audio buffer. As a result it is inevitable that two bytes after the end of the buffer are corrupted; therefore it is essential that when the buffers are created two extra bytes of memory at the end are allocated.

When you stop the sound generation, or exit the program, you need to shut down the audio output in a controlled fashion:

        DEF PROCcleanup
        WaveOut% += 0 : IF WaveOut% THEN
          SYS "waveOutReset", WaveOut%
          SYS "waveOutClose", WaveOut%
          WaveOut% = 0
        ENDIF
        ENDPROC

This code might form part of a larger routine, if there are other things that need to be shut down.