An audio playback and capture library in a single source file.

Examples - Documentation - Supported Platforms - Backends - Major Features - Building

miniaudio is a C library (compilable as C++) with a simple API and build system. It has no dependencies and should compile cleanly on all major compilers. You can add the source file directly to your source tree without needing to install any additional development packages. See the Building section for more details. All major platforms are supported, and where applicable, each platform has support for multiple backends so that the best backend can be used when available. miniaudio is primarily concerned with audio playback and capture. The low-level API is a simple connection to a physical device with a callback used for delivery of raw audio data. Built on top of the low-level API is an optional high-level API which is highly flexible and usable for most scenarios. Included in miniaudio is a suite of functionality not directly related to playback and capture, but highly useful for a creating a complete audio solution. Such functionality includes a node graph for advanced mixing and effect processing, resource management, decoding, resampling, format conversion, and more. You can piece these together to help you develop your audio solution. Refer to the [Programming Manual](https://miniaud.io/docs/manual/) for a more complete description of available features in miniaudio. Examples ======== This example shows one way to play a sound using the high level API. ```c #define MINIAUDIO_IMPLEMENTATION #include "../miniaudio.h" #include int main(int argc, char** argv) { ma_result result; ma_engine engine; if (argc < 2) { printf("No input file."); return -1; } result = ma_engine_init(NULL, &engine); if (result != MA_SUCCESS) { printf("Failed to initialize audio engine."); return -1; } ma_engine_play_sound(&engine, argv[1], NULL); printf("Press Enter to quit..."); getchar(); ma_engine_uninit(&engine); return 0; } ``` This example shows how to decode and play a sound using the low level API. ```c #define MINIAUDIO_IMPLEMENTATION #include "../miniaudio.h" #include void data_callback(ma_device* pDevice, void* pOutput, const void* pInput, ma_uint32 frameCount) { ma_decoder* pDecoder = (ma_decoder*)pDevice->pUserData; if (pDecoder == NULL) { return; } ma_decoder_read_pcm_frames(pDecoder, pOutput, frameCount, NULL); (void)pInput; } int main(int argc, char** argv) { ma_result result; ma_decoder decoder; ma_device_config deviceConfig; ma_device device; if (argc < 2) { printf("No input file.\n"); return -1; } result = ma_decoder_init_file(argv[1], NULL, &decoder); if (result != MA_SUCCESS) { return -2; } deviceConfig = ma_device_config_init(ma_device_type_playback); deviceConfig.playback.format = decoder.outputFormat; deviceConfig.playback.channels = decoder.outputChannels; deviceConfig.sampleRate = decoder.outputSampleRate; deviceConfig.dataCallback = data_callback; deviceConfig.pUserData = &decoder; if (ma_device_init(NULL, &deviceConfig, &device) != MA_SUCCESS) { printf("Failed to open playback device.\n"); ma_decoder_uninit(&decoder); return -3; } if (ma_device_start(&device) != MA_SUCCESS) { printf("Failed to start playback device.\n"); ma_device_uninit(&device); ma_decoder_uninit(&decoder); return -4; } printf("Press Enter to quit..."); getchar(); ma_device_uninit(&device); ma_decoder_uninit(&decoder); return 0; } ``` More examples can be found in the [examples](examples) folder or online here: https://miniaud.io/docs/examples/ Documentation ============= Online documentation can be found here: https://miniaud.io/docs/ Documentation can also be found at the top of [miniaudio.h](https://raw.githubusercontent.com/mackron/miniaudio/master/miniaudio.h) which is always the most up-to-date and authoritive source of information on how to use miniaudio. All other documentation is generated from this in-code documentation. Supported Platforms =================== - Windows - macOS, iOS - Linux - FreeBSD / OpenBSD / NetBSD - Android - Raspberry Pi - Emscripten / HTML5 miniaudio should compile clean on other platforms, but it will not include any support for playback or capture by default. To support that, you would need to implement a custom backend. You can do this without needing to modify the miniaudio source code. See the [custom_backend](examples/custom_backend.c) example. Backends ======== - WASAPI - DirectSound - WinMM - Core Audio (Apple) - ALSA - PulseAudio - JACK - sndio (OpenBSD) - audio(4) (NetBSD and OpenBSD) - OSS (FreeBSD) - AAudio (Android 8.0+) - OpenSL|ES (Android only) - Web Audio (Emscripten) - Null (Silence) - Custom Major Features ============== Low-Level API ------------- The low-level API is a lightweight API for doing processing of raw audio data straight to/from the underlying device. You can connect to multiple devices at once, and can choose specific devices to connect to rather than being forced to use system defaults. You can do playback, capture and full-duplex. The WASAPI backend can also do loopback. miniaudio also exposes backend-specific configuration options for when you need finer control over platform- specific settings. High-Level API -------------- The high-level audio engine in miniaudio encapsulates the resource manager and node graph to give you an easy to use API to manage sounds. The engine is a node graph, and each sound is a node within that graph which means you can take advantage of miniaudio's graph based effect processing and routing infrastructure. Sounds support 3D spatialization and can be pluged into effect nodes if you need to apply an effect. You can also group sounds for when you need to apply volume control or an effect on a group of sounds. Advanced Mixing and Effect Processing ------------------------------------- miniaudio includes a node graph system for doing mixing and effect processing. The output of each node is connected to an input of another node. When the outputs of multiple nodes are connected to the same input node, they will be mixed before being processed by the input node. You can implement custom nodes for doing your own effect processing. miniaudio has some basic nodes built-in, but there are some additional nodes in the extras folder in the miniaudio repository. Resource Management ------------------- The resource manager is used for simplifying the hassle of dealing with the loading and management of your audio resources. It will reference count files so they're only loaded once and handles streaming of large audio sources to save on memory. It can even load files asynchronously and exposes it's job system so you can handle resource management jobs from your existing job infrastructure. Flexible and Modular API ------------------------ miniaudio have a very flexible and highly decoupled API. The high-level API is built on top of the low-level API but can even be used without it. For example, if you want to use a different library for handling playback, such as SDL, you can configure miniaudio to bypass it's low-level API completely so you can plug it into SDL instead. This modularity extends to all parts of miniaudio, such as the resource manager, node graph, decoders and more. You can use these as completely independant units for constructing your audio solution. And More -------- - Decoding, with built-in support for WAV, FLAC and MP3, in addition to being able to plug in custom decoders. - Encoding (WAV only). - Data conversion. - Resampling, including custom resamplers. - Basic generation of waveforms and noise. - Basic effects and filters. Refer to the [Programming Manual](https://miniaud.io/docs/manual/) for a more complete description of available features in miniaudio. Building ======== Do the following in one source file: ```c #define MINIAUDIO_IMPLEMENTATION #include "miniaudio.h" ``` Then just compile. There's no need to install any dependencies. On Windows and macOS there's no need to link to anything. On Linux just link to -lpthread, -lm and -ldl. On BSD just link to -lpthread and -lm. On iOS you need to compile as Objective-C. If you get errors about undefined references to `__sync_val_compare_and_swap_8`, `__atomic_load_8`, etc. you need to link with `-latomic`. If you prefer separate .h and .c files, you can find a split version of miniaudio in the extras/miniaudio_split folder. From here you can use miniaudio as a traditional .c and .h library - just add miniaudio.c to your source tree like any other source file and include miniaudio.h like a normal header. If you prefer compiling as a single translation unit (AKA unity builds), you can just #include the .c file in your main source file: ```c #include "miniaudio.c" ``` Note that the split version is auto-generated using a tool and is based on the main file in the root directory. If you want to contribute, please make the change in the main file. License ======= Your choice of either public domain or [MIT No Attribution](https://github.com/aws/mit-0).