Differences

This shows you the differences between two versions of the page.

--- outputting_20real-time_20audio [2018/04/15 12:32] – Added syntax highlighting richardrussell
+++ outputting_20real-time_20audio [2024/04/19 17:40] (current) – tentative richardrussell
@@ Line 1: / Line 1: @@
 =====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.