BBC BASIC Programmers' Reference

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
=====Outputting real-time audio=====

=====BBC BASIC for SDL 2.0=====

//by Richard Russell, April 2024//

//BBC BASIC for SDL 2.0// provides a number of methods for outputting sounds and music, for example the [[http://www.bbcbasic.co.uk/bbcwin/manual/bbcwin7.html#sound|SOUND]] statement and the [[https://www.bbcbasic.co.uk/bbcsdl/manual/bbcsdlg.html#audiolib|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 [[https://www.bbcbasic.co.uk/bbcsdl/manual/bbcsdlg.html#audiolib|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.

==== Preliminaries ====

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:

<code bb4w>
        ON ERROR PROCcleanup : MODE 7 : PRINT REPORT$ : QUIT
        ON CLOSE PROCcleanup : QUIT
</code>

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

==== Selecting the audio format ====

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 [[http://en.wikipedia.org/wiki/Nyquist_rate|Nyquist criterion]]).\\ \\  You set up the required audio format and open the wave output device as follows:

==== Selecting the audio format ====

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 [[http://en.wikipedia.org/wiki/Nyquist_rate|Nyquist criterion]]).

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

<code bb4w>
      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"
</code>

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

==== Creating and initialising the buffer ====

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:

<code bb4w>
        SamplesPerBuffer% = 1024
        BytesPerBuffer% = SamplesPerBuffer% * audiospec.channels& * 2
        WordsPerBuffer% = BytesPerBuffer% DIV 4

        DIM Buffer%(WordsPerBuffer%)
</code>

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.

==== Outputting in real-time ====

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:

<code bb4w>
        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
</code>

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.

==== Generating the audio data ====

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**:

<code bb4w>
        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
</code>

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.

==== Cleaning up ====

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

<code bb4w>
      DEF PROCcleanup
      IF @hwo% THEN
        SYS "SDL_PauseAudioDevice", @hwo%, 1, @memhdc%
        SYS "SDL_CloseAudioDevice", @hwo%, @memhdc%
      ENDIF
      ENDPROC
</code>

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

=====BBC BASIC for Windows=====

//by Richard Russell, November 2006//\\ \\  BBC BASIC for Windows provides a number of methods for outputting sounds and music, for example the [[http://www.bbcbasic.co.uk/bbcwin/manual/bbcwin7.html#sound|SOUND]] statement and the [[http://www.bbcbasic.co.uk/bbcwin/manual/bbcwin8.html#play|*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 [[http://www.bbcbasic.co.uk//bbcwin/manual/bbcwine.html#playsound|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.

==== Preliminaries ====

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:

<code bb4w>
        ON ERROR PROCcleanup : SYS "MessageBox", @hwnd%, REPORT$, 0, 48 : QUIT
        ON CLOSE PROCcleanup : QUIT
</code>

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

==== Selecting the audio format ====

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 [[http://en.wikipedia.org/wiki/Nyquist_rate|Nyquist criterion]]).\\ \\  You set up the required audio format and open the wave output device as follows:

<code bb4w>
        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%
</code>

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

==== Creating and initialising the buffers ====

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:

<code bb4w>
        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
</code>

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.

==== Outputting in real-time ====

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:

<code bb4w>
        _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
</code>

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.

==== Generating the audio data ====

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**:

<code bb4w>
        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
</code>

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.

==== Cleaning up ====

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

<code bb4w>
        DEF PROCcleanup
        WaveOut% += 0 : IF WaveOut% THEN
          SYS "waveOutReset", WaveOut%
          SYS "waveOutClose", WaveOut%
          WaveOut% = 0
        ENDIF
        ENDPROC
</code>

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