diff --git a/README.md b/README.md index a4e28a82..e0905666 100644 --- a/README.md +++ b/README.md @@ -3,7 +3,7 @@
-

A single file library for audio playback and capture.

+

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

discord @@ -20,6 +20,27 @@ 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 ======== @@ -128,6 +149,7 @@ int main(int argc, char** argv) 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/ @@ -139,14 +161,18 @@ documentation is generated from this in-code documentation. Supported Platforms =================== -- Windows, UWP +- Windows - macOS, iOS - Linux -- BSD +- 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 ======== @@ -169,39 +195,65 @@ Backends Major Features ============== -- Your choice of either public domain or [MIT No Attribution](https://github.com/aws/mit-0). -- Entirely contained within a single file for easy integration into your source tree. -- No external dependencies except for the C standard library and backend libraries. -- Written in C and compilable as C++, enabling miniaudio to work on almost all compilers. -- Supports all major desktop and mobile platforms, with multiple backends for maximum compatibility. -- A low level API with direct access to the raw audio data. -- A high level API with sound management and effects, including 3D spatialization. -- Supports playback, capture, full-duplex and loopback (WASAPI only). -- Device enumeration for connecting to specific devices, not just defaults. -- Connect to multiple devices at once. -- Shared and exclusive mode on supported backends. -- Resource management for loading and streaming sounds. -- A node graph system for advanced mixing and effect processing. -- Data conversion (sample format conversion, channel conversion and resampling). -- Filters. - - Biquads - - Low-pass (first, second and high order) - - High-pass (first, second and high order) - - Band-pass (second and high order) -- Effects. - - Delay/Echo - - Spatializer - - Stereo Pan -- Waveform generation (sine, square, triangle, sawtooth). -- Noise generation (white, pink, Brownian). -- Decoding - - WAV - - FLAC - - MP3 - - Vorbis via stb_vorbis (not built in - must be included separately). - - Custom -- Encoding - - WAV + +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. @@ -218,6 +270,9 @@ Then just compile. There's no need to install any dependencies. On Windows and m 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 @@ -228,19 +283,7 @@ single translation unit (AKA unity builds), you can just #include the .c file in 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. -Vorbis Decoding ---------------- -Vorbis decoding is enabled via stb_vorbis. To use it, you need to include the header section of stb_vorbis -before the implementation of miniaudio. You can enable Vorbis by doing the following: -```c -#define STB_VORBIS_HEADER_ONLY -#include "extras/stb_vorbis.c" /* Enables Vorbis decoding. */ - -#define MINIAUDIO_IMPLEMENTATION -#include "miniaudio.h" - -/* stb_vorbis implementation must come after the implementation of miniaudio. */ -#undef STB_VORBIS_HEADER_ONLY -#include "extras/stb_vorbis.c" -``` +License +======= +Your choice of either public domain or [MIT No Attribution](https://github.com/aws/mit-0).