4z4le4
commented
1 year ago * Audio playback and capture library. Choice of public domain or MIT-0. See license statements at the end of this file. miniaudio - v0.11.11 - 2022-11-04
David Reid - mackron@gmail.com */
/*
-
Introduction
miniaudio is a single file library for audio playback and capture. To use it, do the following in one .c file:
#define MINIAUDIO_IMPLEMENTATION #include "miniaudio.h"
You can do #include "miniaudio.h" in other parts of the program just like any other header.
miniaudio includes both low level and high level APIs. The low level API is good for those who want to do all of their mixing themselves and only require a light weight interface to the underlying audio device. The high level API is good for those who have complex mixing and effect requirements.
In miniaudio, objects are transparent structures. Unlike many other libraries, there are no handles to opaque objects which means you need to allocate memory for objects yourself. In the examples presented in this documentation you will often see objects declared on the stack. You need to be careful when translating these examples to your own code so that you don't accidentally declare your objects on the stack and then cause them to become invalid once the function returns. In addition, you must ensure the memory address of your objects remain the same throughout their lifetime. You therefore cannot be making copies of your objects.
A config/init pattern is used throughout the entire library. The idea is that you set up a config object and pass that into the initialization routine. The advantage to this system is that the config object can be initialized with logical defaults and new properties added to it without breaking the API. The config object can be allocated on the stack and does not need to be maintained after initialization of the corresponding object.
1.1. Low Level API
The low level API gives you access to the raw audio data of an audio device. It supports playback, capture, full-duplex and loopback (WASAPI only). You can enumerate over devices to determine which physical device(s) you want to connect to.
The low level API uses the concept of a "device" as the abstraction for physical devices. The idea is that you choose a physical device to emit or capture audio from, and then move data to/from the device when miniaudio tells you to. Data is delivered to and from devices asynchronously via a callback which you specify when initializing the device.
When initializing the device you first need to configure it. The device configuration allows you to specify things like the format of the data delivered via the callback, the size of the internal buffer and the ID of the device you want to emit or capture audio from.
Once you have the device configuration set up you can initialize the device. When initializing a device you need to allocate memory for the device object beforehand. This gives the application complete control over how the memory is allocated. In the example below we initialize a playback device on the stack, but you could allocate it on the heap if that suits your situation better.
```c
void data_callback(ma_device* pDevice, void* pOutput, const void* pInput, ma_uint32 frameCount)
{
// In playback mode copy data to pOutput. In capture mode read data from pInput. In full-duplex mode, both
// pOutput and pInput will be valid and you can move data from pInput into pOutput. Never process more than
// frameCount frames.
}
int main()
{
ma_device_config config = ma_device_config_init(ma_device_type_playback);
config.playback.format = ma_format_f32; // Set to ma_format_unknown to use the device's native format.
config.playback.channels = 2; // Set to 0 to use the device's native channel count.
config.sampleRate = 48000; // Set to 0 to use the device's native sample rate.
config.dataCallback = data_callback; // This function will be called when miniaudio needs more data.
config.pUserData = pMyCustomData; // Can be accessed from the device object (device.pUserData).
ma_device device;
if (ma_device_init(NULL, &config, &device) != MA_SUCCESS) {
return -1; // Failed to initialize the device.
}
ma_device_start(&device); // The device is sleeping by default so you'll need to start it manually.
// Do something here. Probably your program's main loop.
ma_device_uninit(&device); // This will stop the device so no need to do that manually.
return 0;
}
```In the example above, data_callback() is where audio data is written and read from the device.
The idea is in playback mode you cause sound to be emitted from the speakers by writing audio data
to the output buffer (pOutput in the example). In capture mode you read data from the input
buffer (pInput) to extract sound captured by the microphone. The frameCount parameter tells you
how many frames can be written to the output buffer and read from the input buffer. A "frame" is
one sample for each channel. For example, in a stereo stream (2 channels), one frame is 2
samples: one for the left, one for the right. The channel count is defined by the device config.
The size in bytes of an individual sample is defined by the sample format which is also specified
in the device config. Multi-channel audio data is always interleaved, which means the samples for
each frame are stored next to each other in memory. For example, in a stereo stream the first pair
of samples will be the left and right samples for the first frame, the second pair of samples will
be the left and right samples for the second frame, etc.
The configuration of the device is defined by the ma_device_config structure. The config object
is always initialized with ma_device_config_init(). It's important to always initialize the
config with this function as it initializes it with logical defaults and ensures your program
doesn't break when new members are added to the ma_device_config structure. The example above
uses a fairly simple and standard device configuration. The call to ma_device_config_init() takes
a single parameter, which is whether or not the device is a playback, capture, duplex or loopback
device (loopback devices are not supported on all backends). The config.playback.format member
sets the sample format which can be one of the following (all formats are native-endian):
+---------------+----------------------------------------+---------------------------+
| Symbol | Description | Range |
+---------------+----------------------------------------+---------------------------+
| ma_format_f32 | 32-bit floating point | [-1, 1] |
| ma_format_s16 | 16-bit signed integer | [-32768, 32767] |
| ma_format_s24 | 24-bit signed integer (tightly packed) | [-8388608, 8388607] |
| ma_format_s32 | 32-bit signed integer | [-2147483648, 2147483647] |
| ma_format_u8 | 8-bit unsigned integer | [0, 255] |
+---------------+----------------------------------------+---------------------------+The config.playback.channels member sets the number of channels to use with the device. The
channel count cannot exceed MA_MAX_CHANNELS. The config.sampleRate member sets the sample rate
(which must be the same for both playback and capture in full-duplex configurations). This is
usually set to 44100 or 48000, but can be set to anything. It's recommended to keep this between
8000 and 384000, however.
Note that leaving the format, channel count and/or sample rate at their default values will result in the internal device's native configuration being used which is useful if you want to avoid the overhead of miniaudio's automatic data conversion.
In addition to the sample format, channel count and sample rate, the data callback and user data
pointer are also set via the config. The user data pointer is not passed into the callback as a
parameter, but is instead set to the pUserData member of ma_device which you can access
directly since all miniaudio structures are transparent.
Initializing the device is done with ma_device_init(). This will return a result code telling you
what went wrong, if anything. On success it will return MA_SUCCESS. After initialization is
complete the device will be in a stopped state. To start it, use ma_device_start().
Uninitializing the device will stop it, which is what the example above does, but you can also stop
the device with ma_device_stop(). To resume the device simply call ma_device_start() again.
Note that it's important to never stop or start the device from inside the callback. This will
result in a deadlock. Instead you set a variable or signal an event indicating that the device
needs to stop and handle it in a different thread. The following APIs must never be called inside
the callback:
```c
ma_device_init()
ma_device_init_ex()
ma_device_uninit()
ma_device_start()
ma_device_stop()
```You must never try uninitializing and reinitializing a device inside the callback. You must also never try to stop and start it from inside the callback. There are a few other things you shouldn't do in the callback depending on your requirements, however this isn't so much a thread-safety thing, but rather a real-time processing thing which is beyond the scope of this introduction.
The example above demonstrates the initialization of a playback device, but it works exactly the
same for capture. All you need to do is change the device type from ma_device_type_playback to
ma_device_type_capture when setting up the config, like so:
```c
ma_device_config config = ma_device_config_init(ma_device_type_capture);
config.capture.format = MY_FORMAT;
config.capture.channels = MY_CHANNEL_COUNT;
```In the data callback you just read from the input buffer (pInput in the example above) and leave
the output buffer alone (it will be set to NULL when the device type is set to
ma_device_type_capture).
These are the available device types and how you should handle the buffers in the callback:
+-------------------------+--------------------------------------------------------+
| Device Type | Callback Behavior |
+-------------------------+--------------------------------------------------------+
| ma_device_type_playback | Write to output buffer, leave input buffer untouched. |
| ma_device_type_capture | Read from input buffer, leave output buffer untouched. |
| ma_device_type_duplex | Read from input buffer, write to output buffer. |
| ma_device_type_loopback | Read from input buffer, leave output buffer untouched. |
+-------------------------+--------------------------------------------------------+You will notice in the example above that the sample format and channel count is specified separately for playback and capture. This is to support different data formats between the playback and capture devices in a full-duplex system. An example may be that you want to capture audio data as a monaural stream (one channel), but output sound to a stereo speaker system. Note that if you use different formats between playback and capture in a full-duplex configuration you will need to convert the data yourself. There are functions available to help you do this which will be explained later.
The example above did not specify a physical device to connect to which means it will use the operating system's default device. If you have multiple physical devices connected and you want to use a specific one you will need to specify the device ID in the configuration, like so:
```c
config.playback.pDeviceID = pMyPlaybackDeviceID; // Only if requesting a playback or duplex device.
config.capture.pDeviceID = pMyCaptureDeviceID; // Only if requesting a capture, duplex or loopback device.
```To retrieve the device ID you will need to perform device enumeration, however this requires the use of a new concept called the "context". Conceptually speaking the context sits above the device. There is one context to many devices. The purpose of the context is to represent the backend at a more global level and to perform operations outside the scope of an individual device. Mainly it is used for performing run-time linking against backend libraries, initializing backends and enumerating devices. The example below shows how to enumerate devices.
```c
ma_context context;
if (ma_context_init(NULL, 0, NULL, &context) != MA_SUCCESS) {
// Error.
}
ma_device_info* pPlaybackInfos;
ma_uint32 playbackCount;
ma_device_info* pCaptureInfos;
ma_uint32 captureCount;
if (ma_context_get_devices(&context, &pPlaybackInfos, &playbackCount, &pCaptureInfos, &captureCount) != MA_SUCCESS) {
// Error.
}
// Loop over each device info and do something with it. Here we just print the name with their index. You may want
// to give the user the opportunity to choose which device they'd prefer.
for (ma_uint32 iDevice = 0; iDevice < playbackCount; iDevice += 1) {
printf("%d - %s\n", iDevice, pPlaybackInfos[iDevice].name);
}
ma_device_config config = ma_device_config_init(ma_device_type_playback);
config.playback.pDeviceID = &pPlaybackInfos[chosenPlaybackDeviceIndex].id;
config.playback.format = MY_FORMAT;
config.playback.channels = MY_CHANNEL_COUNT;
config.sampleRate = MY_SAMPLE_RATE;
config.dataCallback = data_callback;
config.pUserData = pMyCustomData;
ma_device device;
if (ma_device_init(&context, &config, &device) != MA_SUCCESS) {
// Error
}
...
ma_device_uninit(&device);
ma_context_uninit(&context);
```The first thing we do in this example is initialize a ma_context object with ma_context_init().
The first parameter is a pointer to a list of ma_backend values which are used to override the
default backend priorities. When this is NULL, as in this example, miniaudio's default priorities
are used. The second parameter is the number of backends listed in the array pointed to by the
first parameter. The third parameter is a pointer to a ma_context_config object which can be
NULL, in which case defaults are used. The context configuration is used for setting the logging
callback, custom memory allocation callbacks, user-defined data and some backend-specific
configurations.
Once the context has been initialized you can enumerate devices. In the example above we use the
simpler ma_context_get_devices(), however you can also use a callback for handling devices by
using ma_context_enumerate_devices(). When using ma_context_get_devices() you provide a pointer
to a pointer that will, upon output, be set to a pointer to a buffer containing a list of
ma_device_info structures. You also provide a pointer to an unsigned integer that will receive
the number of items in the returned buffer. Do not free the returned buffers as their memory is
managed internally by miniaudio.
The ma_device_info structure contains an id member which is the ID you pass to the device
config. It also contains the name of the device which is useful for presenting a list of devices
to the user via the UI.
When creating your own context you will want to pass it to ma_device_init() when initializing the
device. Passing in NULL, like we do in the first example, will result in miniaudio creating the
context for you, which you don't want to do since you've already created a context. Note that
internally the context is only tracked by it's pointer which means you must not change the location
of the ma_context object. If this is an issue, consider using malloc() to allocate memory for
the context.
1.2. High Level API
The high level API consists of three main parts:
- Resource management for loading and streaming sounds.
- A node graph for advanced mixing and effect processing.
- A high level "engine" that wraps around the resource manager and node graph.
The resource manager (ma_resource_manager) is used for loading sounds. It supports loading sounds
fully into memory and also streaming. It will also deal with reference counting for you which
avoids the same sound being loaded multiple times.
The node graph is used for mixing and effect processing. The idea is that you connect a number of nodes into the graph by connecting each node's outputs to another node's inputs. Each node can implement it's own effect. By chaining nodes together, advanced mixing and effect processing can be achieved.
The engine encapsulates both the resource manager and the node graph to create a simple, easy to use high level API. The resource manager and node graph APIs are covered in more later sections of this manual.
The code below shows how you can initialize an engine using it's default configuration.
```c
ma_result result;
ma_engine engine;
result = ma_engine_init(NULL, &engine);
if (result != MA_SUCCESS) {
return result; // Failed to initialize the engine.
}
```This creates an engine instance which will initialize a device internally which you can access with
ma_engine_get_device(). It will also initialize a resource manager for you which can be accessed
with ma_engine_get_resource_manager(). The engine itself is a node graph (ma_node_graph) which
means you can pass a pointer to the engine object into any of the ma_node_graph APIs (with a
cast). Alternatively, you can use ma_engine_get_node_graph() instead of a cast.
Note that all objects in miniaudio, including the ma_engine object in the example above, are
transparent structures. There are no handles to opaque structures in miniaudio which means you need
to be mindful of how you declare them. In the example above we are declaring it on the stack, but
this will result in the struct being invalidated once the function encapsulating it returns. If
allocating the engine on the heap is more appropriate, you can easily do so with a standard call
to malloc() or whatever heap allocation routine you like:
```c
ma_engine* pEngine = malloc(sizeof(*pEngine));
```The ma_engine API uses the same config/init pattern used all throughout miniaudio. To configure
an engine, you can fill out a ma_engine_config object and pass it into the first parameter of
ma_engine_init():
```c
ma_result result;
ma_engine engine;
ma_engine_config engineConfig;
engineConfig = ma_engine_config_init();
engineConfig.pResourceManager = &myCustomResourceManager; // <-- Initialized as some earlier stage.
result = ma_engine_init(&engineConfig, &engine);
if (result != MA_SUCCESS) {
return result;
}
```This creates an engine instance using a custom config. In this particular example it's showing how you can specify a custom resource manager rather than having the engine initialize one internally. This is particularly useful if you want to have multiple engine's share the same resource manager.
The engine must be uninitialized with ma_engine_uninit() when it's no longer needed.
By default the engine will be started, but nothing will be playing because no sounds have been initialized. The easiest but least flexible way of playing a sound is like so:
```c
ma_engine_play_sound(&engine, "my_sound.wav", NULL);
```This plays what miniaudio calls an "inline" sound. It plays the sound once, and then puts the internal sound up for recycling. The last parameter is used to specify which sound group the sound should be associated with which will be explained later. This particular way of playing a sound is simple, but lacks flexibility and features. A more flexible way of playing a sound is to first initialize a sound:
```c
ma_result result;
ma_sound sound;
result = ma_sound_init_from_file(&engine, "my_sound.wav", 0, NULL, NULL, &sound);
if (result != MA_SUCCESS) {
return result;
}
ma_sound_start(&sound);
```This returns a ma_sound object which represents a single instance of the specified sound file. If
you want to play the same file multiple times simultaneously, you need to create one sound for each
instance.
Sounds should be uninitialized with ma_sound_uninit().
Sounds are not started by default. Start a sound with ma_sound_start() and stop it with
ma_sound_stop(). When a sound is stopped, it is not rewound to the start. Use
ma_sound_seek_to_pcm_frame(&sound, 0) to seek back to the start of a sound. By default, starting
and stopping sounds happens immediately, but sometimes it might be convenient to schedule the sound
the be started and/or stopped at a specific time. This can be done with the following functions:
```c
ma_sound_set_start_time_in_pcm_frames()
ma_sound_set_start_time_in_milliseconds()
ma_sound_set_stop_time_in_pcm_frames()
ma_sound_set_stop_time_in_milliseconds()
```The start/stop time needs to be specified based on the absolute timer which is controlled by the
engine. The current global time time in PCM frames can be retrieved with ma_engine_get_time().
The engine's global time can be changed with ma_engine_set_time() for synchronization purposes if
required. Note that scheduling a start time still requires an explicit call to ma_sound_start()
before anything will play:
```c
ma_sound_set_start_time_in_pcm_frames(&sound, ma_engine_get_time(&engine) + (ma_engine_get_sample_rate(&engine) * 2);
ma_sound_start(&sound);
```The third parameter of ma_sound_init_from_file() is a set of flags that control how the sound be
loaded and a few options on which features should be enabled for that sound. By default, the sound
is synchronously loaded fully into memory straight from the file system without any kind of
decoding. If you want to decode the sound before storing it in memory, you need to specify the
MA_SOUND_FLAG_DECODE flag. This is useful if you want to incur the cost of decoding at an earlier
stage, such as a loading stage. Without this option, decoding will happen dynamically at mixing
time which might be too expensive on the audio thread.
If you want to load the sound asynchronously, you can specify the MA_SOUND_FLAG_ASYNC flag. This
will result in ma_sound_init_from_file() returning quickly, but the sound will not start playing
until the sound has had some audio decoded.
The fourth parameter is a pointer to sound group. A sound group is used as a mechanism to organise
sounds into groups which have their own effect processing and volume control. An example is a game
which might have separate groups for sfx, voice and music. Each of these groups have their own
independent volume control. Use ma_sound_group_init() or ma_sound_group_init_ex() to initialize
a sound group.
Sounds and sound groups are nodes in the engine's node graph and can be plugged into any ma_node
API. This makes it possible to connect sounds and sound groups to effect nodes to produce complex
effect chains.
A sound can have it's volume changed with ma_sound_set_volume(). If you prefer decibel volume
control you can use ma_volume_db_to_linear() to convert from decibel representation to linear.
Panning and pitching is supported with ma_sound_set_pan() and ma_sound_set_pitch(). If you know
a sound will never have it's pitch changed with ma_sound_set_pitch() or via the doppler effect,
you can specify the MA_SOUND_FLAG_NO_PITCH flag when initializing the sound for an optimization.
By default, sounds and sound groups have spatialization enabled. If you don't ever want to
spatialize your sounds, initialize the sound with the MA_SOUND_FLAG_NO_SPATIALIZATION flag. The
spatialization model is fairly simple and is roughly on feature parity with OpenAL. HRTF and
environmental occlusion are not currently supported, but planned for the future. The supported
features include:
- Sound and listener positioning and orientation with cones
- Attenuation models: none, inverse, linear and exponential
- Doppler effect
Sounds can be faded in and out with ma_sound_set_fade_in_pcm_frames().
To check if a sound is currently playing, you can use ma_sound_is_playing(). To check if a sound
is at the end, use ma_sound_at_end(). Looping of a sound can be controlled with
ma_sound_set_looping(). Use ma_sound_is_looping() to check whether or not the sound is looping.
-
Building
miniaudio should work cleanly out of the box without the need to download or install any dependencies. See below for platform-specific details.
2.1. Windows
The Windows build should compile cleanly on all popular compilers without the need to configure any include paths nor link to any libraries.
The UWP build may require linking to mmdevapi.lib if you get errors about an unresolved external
symbol for ActivateAudioInterfaceAsync().
2.2. macOS and iOS
The macOS build should compile cleanly without the need to download any dependencies nor link to
any libraries or frameworks. The iOS build needs to be compiled as Objective-C and will need to
link the relevant frameworks but should compile cleanly out of the box with Xcode. Compiling
through the command line requires linking to -lpthread and -lm.
Due to the way miniaudio links to frameworks at runtime, your application may not pass Apple's
notarization process. To fix this there are two options. The first is to use the
MA_NO_RUNTIME_LINKING option, like so:
```c
#ifdef __APPLE__
#define MA_NO_RUNTIME_LINKING
#endif
#define MINIAUDIO_IMPLEMENTATION
#include "miniaudio.h"
```This will require linking with -framework CoreFoundation -framework CoreAudio -framework AudioUnit.
Alternatively, if you would rather keep using runtime linking you can add the following to your
entitlements.xcent file:
```
<key>com.apple.security.cs.allow-dyld-environment-variables</key>
<true/>
<key>com.apple.security.cs.allow-unsigned-executable-memory</key>
<true/>
```See this discussion for more info: https://github.com/mackron/miniaudio/issues/203.
2.3. Linux
The Linux build only requires linking to -ldl, -lpthread and -lm. You do not need any
development packages. You may need to link with -latomic if you're compiling for 32-bit ARM.
2.4. BSD
The BSD build only requires linking to -lpthread and -lm. NetBSD uses audio(4), OpenBSD uses
sndio and FreeBSD uses OSS. You may need to link with -latomic if you're compiling for 32-bit
ARM.
2.5. Android
AAudio is the highest priority backend on Android. This should work out of the box without needing any kind of compiler configuration. Support for AAudio starts with Android 8 which means older versions will fall back to OpenSL|ES which requires API level 16+.
There have been reports that the OpenSL|ES backend fails to initialize on some Android based
devices due to dlopen() failing to open "libOpenSLES.so". If this happens on your platform
you'll need to disable run-time linking with MA_NO_RUNTIME_LINKING and link with -lOpenSLES.
2.6. Emscripten
The Emscripten build emits Web Audio JavaScript directly and should compile cleanly out of the box.
You cannot use -std=c* compiler flags, nor -ansi.
2.7. Build Options
test sound