blip_buf $vers -------------- Author : Shay Green Website : http://www.slack.net/~ant/ License : GNU Lesser General Public License (LGPL) Contents -------- * Overview * Buffer creation * Waveform generation * Time frames * Complex waveforms * Sample buffering * Thanks Overview -------- This library resamples audio waveforms from input clock rate to output sample rate. Usage follows this general pattern: * Create buffer with blip_new(). * Set clock rate and sample rate with blip_set_rates(). * Waveform generation loop: - Generate several clocks of waveform with blip_add_delta(). - End time frame with blip_end_frame(). - Read samples from buffer with blip_read_samples(). * Free buffer with blip_delete(). Buffer creation --------------- Before synthesis, a buffer must be created with blip_new(). Its size is the maximum number of unread samples it can hold. For most uses, this can be 1/10 the sample rate or less, since samples will usually be read out immediately after being generated. After the buffer is created, the input clock rate and output sample rate must be set with blip_set_rates(). This determines how many input clocks there are per second, and how many output samples are generated per second. If the compiler supports a 64-bit integer type, then the input-output ratio is stored very accurately. If the compiler only supports a 32-bit integer type, then the ratio is stored with only 20 fraction bits, so some ratios cannot be represented exactly (for example, sample rate=48000 and clock rate=48001). The ratio is internally rounded up, so there will never be fewer than 'sample rate' samples per second. Having too many per second is generally better than having too few. Waveform generation ------------------- Waveforms are generated at the input clock rate. Consider a simple square wave with 8 clocks per cycle (4 clocks high, 4 clocks low): |<-- 8 clocks ->| +5| ._._._._ ._._._._ ._._._._ ._._ | | | | | | | | Amp 0|._._._._ | | | | | | | | | | | | | -5| ._._._._ ._._._._ ._._._._ * . . . * . . . * . . . * . . . * . . . * . . . * . . . * . Time 0 4 8 12 16 20 24 28 The wave changes amplitude at time points 0, 4, 8, 12, 16, etc. The following generates the amplitude at every clock of above waveform at the input clock rate: int wave [30]; for ( int i = 4; i < 30; ++i ) { if ( i % 8 < 4 ) wave [i] = -5; else wave [i] = +5; } Without this library, the wave array would then need to be resampled from the input clock rate to the output sample rate. This library does this resampling internally, so it won't be discussed further; waveform generation code can focus entirely on the input clocks. Rather than specify the amplitude at every clock, this library merely needs to know the points where the amplitude CHANGES, referred to as a delta. The time of a delta is specified with a clock count. The deltas for this square wave are shown below the time points they occur at: +5| ._._._._ ._._._._ ._._._._ ._._ | | | | | | | | Amp 0|._._._._ | | | | | | | | | | | | | -5| ._._._._ ._._._._ ._._._._ * . . . * . . . * . . . * . . . * . . . * . . . * . . . * . Time 0 4 8 12 16 20 24 28 Delta +5 -10 +10 -10 +10 -10 +10 The following calls generate the above waveform: blip_add_delta( blip, 4, +5 ); blip_add_delta( blip, 8, -10 ); blip_add_delta( blip, 12, +10 ); blip_add_delta( blip, 16, -10 ); blip_add_delta( blip, 20, +10 ); blip_add_delta( blip, 24, -10 ); blip_add_delta( blip, 28, +10 ); In the examples above, the amplitudes are small for clarity. The 16-bit sample range is -32768 to +32767, so actual waveform amplitudes would need to be in the thousands to be audible (for example, -5000 to +5000). This library allows waveform generation code to pay NO attention to the output sample rate. It can focus ENTIRELY on the essence of the waveform: the points where its amplitude changes. Since these points can be efficiently generated in a loop, synthesis is efficient. Sound chip emulation code can be structured to allow full accuracy down to a single clock, with the emulated CPU being able to simply tell the sound chip to "emulate from wherever you left off, up to clock time T within the current time frame". Time frames ----------- Since time keeps increasing, if left unchecked, at some point it would overflow the range of an integer. This library's solution to the problem is to break waveform generation into time frames of moderate length. Clock counts within a time frame are thus relative to the beginning of the frame, where 0 is the beginning of the frame. When a time frame of length T is ended, what was at time T in the old time frame is now at time 0 in the new time frame. Breaking the above waveform into time frames of 10 clocks each looks like this: +5| ._._._._ ._._._._ ._._._._ ._._ | | | | | | | | Amp 0|._._._._ | | | | | | | | | | | | | -5| ._._._._ ._._._._ ._._._._ * . . . * . . . * . . . * . . . * . . . * . . . * . . . * . Time |0 4 8 | 2 6 |0 4 8 | | first time frame | second time frame | third time frame | |<--- 10 clocks --->|<--- 10 clocks --->|<--- 10 clocks --->| The following calls generate the above waveform. After they execute, the first 30 clocks of the waveform will have been resampled and be available as output samples for reading with blip_read_samples(). blip_add_delta( blip, 4, +5 ); blip_add_delta( blip, 8, -10 ); blip_end_frame( blip, 10 ); blip_add_delta( blip, 2, +10 ); blip_add_delta( blip, 6, -10 ); blip_end_frame( blip, 10 ); blip_add_delta( blip, 0, +10 ); blip_add_delta( blip, 4, -10 ); blip_add_delta( blip, 8, +10 ); blip_end_frame( blip, 10 ); ... Time frames can be a convenient length, and the length can vary from one frame to the next. Once a time frame is ended, the resulting output samples become available for reading immediately, and no more deltas can be added to it. There is a limit of about 4000 output samples per time frame. The number of clocks depends on the clock rate. At common sample rates, this allows time frames of at least 1/15 second, plenty for most uses. This limit allows increased resampling ratio accuracy. In an emulator, it is usually convenient to have audio time frames correspond to video frames, where the CPU's clock counter is reset at the beginning of each video frame and thus can be used directly as the relative clock counts for audio time frames. Complex waveforms ----------------- Any sort of waveform can be generated, not just a square wave. For example, a saw-like wave: +5| ._._._._ ._._._._ ._._ | | | | | | Amp 0|._._._._ | ._._._._ | ._._._._ | | | | | -5| ._._._._ ._._._._ * . . . * . . . * . . . * . . . * . . . * . . . * . . . * . Time 0 4 8 12 16 20 24 28 Delta +5 -10 +5 +5 -10 +5 +5 Code to generate above waveform: blip_add_delta( blip, 4, +5 ); blip_add_delta( blip, 8, -10 ); blip_add_delta( blip, 12, +5 ); blip_add_delta( blip, 16, +5 ); blip_add_delta( blip, 20, +10 ); blip_add_delta( blip, 24, +5 ); blip_add_delta( blip, 28, +5 ); Similarly, multiple waveforms can be added within a time frame without problem. It doesn't matter what order they're added, because all the library needs are the deltas. The synthesis code doesn't need to know all the waveforms at once either; it can calculate and add the deltas for each waveform individually. Deltas don't need to be added in chronological order either. Sample buffering ---------------- Sample buffering is very flexible. Once a time frame is ended, the resampled waveforms become output samples that are immediately made available for reading with blip_read_samples(). They don't have to be read immediately; they can be allowed to accumulate in the buffer, with each time frame appending more samples to the buffer. When reading, some or all of the samples in can be read out, with the remaining unread samples staying in the buffer for later. Usually a program will immediately read all available samples after ending a time frame and play them immediately. In some systems, a program needs samples in fixed-length blocks; in that case, it would keep generating time frames until some number of samples are available, then read only that many, even if slightly more were available in the buffer. In some systems, one wants to run waveform generation for exactly the number of clocks necessary to generate some desired number of output samples, and no more. In that case, use blip_clocks_needed( blip, N ) to find out how many clocks are needed to generate N additional samples. Ending a time frame with this value will result in exactly N more samples becoming available for reading. Thanks ------ Thanks to Jsr (FamiTracker author), the Mednafen team (multi-system emulator), ShizZie (Nhes GMB author), Marcel van Tongeren, Luke Molnar (UberNES author), Fredrick Meunier (Fuse contributor) for using and giving feedback for another similar library. Thanks to Disch for his interest and discussions about the synthesis algorithm itself, and for writing his own implementation of it (Schpune) rather than just using mine. Thanks to Xodnizel for Festalon, whose sound quality got me interested in video game sound emulation in the first place, and where I first came up with the algorithm while optimizing its brute-force filter. -- Shay Green