#include <dvmbasic.h>
The Audio abstraction stores generic 8-bit and 16-bit audio samples in a 1D array. The Audio buffer can be either physical or virtual. The buffer may contains contiguous samples from a single channel, or interleaved samples from both left and right channel. In cases where we store both channels, we can select an individual channel for processing by passing in a (offset, stride) pair.
typedef struct Audio {
int start;
int length;
unsigned char *firstSample;
unsigned char *buffer;
char isVirtual;
} Audio;
- start
- number of samples skipped from the physical buffer
- length
- number of samples in the current buffer
- firstSample
- pointer to the first audio sample
- buffer
- pointer to the beginning of the physical buffer
- isVirtual
- 1 if the audio buffer is a virtual buffer, 0 otherwise.
The return codes indicate if an audio operation is successful. DVM_AUDIO_OK is returned if an operation is completed successfully. Otherwise DVM_AUDIO_ERROR is returned.
#define DVM_AUDIO_OK 0
#define DVM_AUDIO_ERROR 1
Audio *Audio8New (int numSamples)
Audio *Audio16New (int numSamples)
Allocate a new physical Audio buffer of size numSamples samples. The amount of memory allocated is:
numSamples bytes -- 8-bit audio buffer numSamples*sizeof(short) bytes -- 16-bit audio buffer.Returns a handle to the newly created Audio buffer.void AudioFree (Audio *audio)
Free the memory allocated for the Audio buffer. If the audio buffer is physical, all memory allocated for the buffer will be freed. If the buffer is virtual, only the "header" information is freed, the memory it borrows from its parent is not freed.
Audio *Audio8Clip (Audio *audio, int x, int numSamples)
Audio *Audio16Clip (Audio *audio, int x, int numSamples);
Creates a virtual Audio buffer from the Audio buffer audio. The virtual buffer consists of samples starting from the x-th sample of audio, and contains numSamples samples. A handle to the virtual buffer is returned.
void Audio8Reclip (Audio *audio, int x, int numSamples, Audio *clipped)
void Audio16Reclip (Audio *audio, int x, int numSamples, Audio *clipped);
This function is identical to AudioClip, except that it destructively modifies the virtual Audio buffer clipped (instead of allocating a new virtual Audio buffer). Warning : memory leaks will occurs if clipped is a physical Audio buffer.
void Audio8Set (Audio *audio, unsigned char v)
Set each sample in the Audio buffer audio to value v. The implementation uses memset(). For setting values in a 16 bit audio buffer, use Audio16SetSome()
void Audio8SetSome (Audio *audio, unsigned char v, int offset, int stride)
void Audio16SetSome (Audio *audio, short value, int offset, int stride)
Set each sample in the Audio buffer audio as selected by (offset, stride) to value v.
void Audio8Copy (Audio *src, Audio *dest)
void Audio16Copy (Audio *src, Audio *dest)
Copy all the samples from src to dest.
void Audio8CopySome (Audio *src, Audio *dest, int srcOffset, int srcStride, int destOffset, int destStride)
void Audio16CopySome (Audio *src, Audio *dest, int srcOffset, int srcStride, int destOffset, int destStride)
Copy the specified amount of samples from src to dest. This function can be used to copy one channel of audio data by specifying the right values for offset and stride. To copy mono data or both channels of stereo data, use offset=0 and stride=1. To copy one channel of stereo data, use stride=2 and specify the channel by setting offset to 0 for the left channel or offset to 1 for the right channel.
void Audio8Split (Audio *src, Audio *left, Audio *right)
void Audio16Split (Audio *src, Audio *left, Audio *right)
Demultiplex audio data from the stereo Audio buffer src into two mono Audio buffers (one for each channel). Samples from left channel of src are stored in left; samples from right channel of src are stored in right.
void Audio8Merge (Audio *left, Audio *right, Audio *dest)
void Audio16Merge (Audio *left, Audio *right, Audio *dest)
Multiplex the two mono Audio buffers left and right into the stereo Audio buffer dest.
void Audio8ResampleHalf(Audio *in, Audio *out)
void Audio8ResampleQuarter(Audio *in, Audio *out)
void Audio16ResampleHalf(Audio *in, Audio *out)
void Audio16ResampleQuarter(Audio *in, Audio *out)
Reduce the sampling rate of in by one-half (or one-quarter), and write the resulting signal in out. The audio data is resampled by averaging pairs or quadruples of values, so it must be in PCM format. To obtain a lower quality resampling of μ-law or A-law data without resampling use one of the decimate commands (see below).
For example, if in contains 16-bit audio sampled at 44100 Hertz, Audio16ResampleQuarter() will write the equivalent data sampled at 11025 Hertz.
void Audio8ResampleLinear(Audio *src, int srcSamples, int destSamples, Audio *dest)
void Audio8ResampleDecimate(Audio *src, int srcSamples, int destSamples, Audio *dest)
void Audio16ResampleLinear(Audio *src, int srcSamples, int destSamples, Audio *dest)
void Audio16ResampleDecimate(Audio *src, int srcSamples, int destSamples, Audio *dest)
Resample the audio data in src and write the resulting signal in dest. srcSamples samples of data in src are mapped to destSamples samples to data in dest. The sampling method uses either linear interpolation or decimation, depending on the function called. Decimation is typically significantly faster than interpolation, but introduces more artifacts. The audio data must be in PCM format for linear interpolation to function correctly. These functions may be used to either increase or decrease the sampling rate in an Audio Buffer.
For example, if in contains one second of 8-bit PCM audio sampled at 11025 Hertz, Audio8ResampleLinear (in, out, 11025, 8000) will convert it to 8000 Hz.
Audio *BitstreamCastToAudio8(BitStream *bs, int offset, int length)
Audio *BitstreamCastToAudio16(BitStream *bs, int offset, int length)
Cast data from bs into a virtual Audio buffer and return the newly created buffer. The data cast starts offset bytes from the start of bs. The resulting audio buffer contains length samples of mono data.
For example, suppose bs is bitstream containing data from a wave audio file. The bitstream is determined to have a a 44 byte header followed by 16-bit stereo data at 8 kHz. To get an audio buffer containing the first second of audio data, you would use
audio = BitstreamCastToAudio8(bs, 44, 16000);since the audio data is 44 bytes into bs, and we want to cast 16000 samples (8000 for the left channel, 8000 for the right channel).
It is the responsibility of the caller to maintain the integrity of the data in bs and to free the virtual audio buffer returned by this call when it is no longer needed.
BitStream *Audio8CastToBitstream(Audio *audio);
BitStream *Audio16CastToBitstream(Audio *audio);
Cast the Audio buffer audio as a virtual BitStream and return a handle to the BitStream.
AudioGetStartOffset(Audio *audio)
AudioGetNumOfSamples(Audio *audio)
Returns the start offset or number of samples in audio. The start offset is 0 if audio is a physical buffer, or the offset into the parent physical buffer if audio is a virtual buffer. Implementation note: these are currently implemented as macros that access the slots start and length in the Audio structure.
int Audio8ChunkAbsSum(Audio *audio, int chunkSize, int **pSums)
int Audio16ChunkAbsSum(Audio *audio, int chunkSize, int **pSums)
Compute the sum of the absolute values of each group of chunkSize samples in audio. For example, if chunkSize is 10, then this function computes the sum of the absolute values of each chunk of 10 samples. This function is useful for locating silent sections of an Audio buffer. The values computed are returned in the array pSums. This array is allocated by this function. The size of the allocated array is returned. It is the responsibility of the caller to free pSums when it is no longer needed.
int Audio8MaxAbs(Audio *audio)
int Audio16MaxAbs(Audio *audio)
Returns the maximum absolute value of any sample in the audio buffer audio. This function is useful in combination with AudioMap8to8InitVolume (or AudioMap16to16InitVolume) to normalize the samples in an audio buffer.
Last updated : Saturday, November 14, 1998, 07:50 PM