## File: README.md

<h1 align="center">
    [](https://miniaud.io)
    
</h1>

<h4 align="center">An audio playback and capture library in a single source file.</h4>





miniaudio is written in C with no dependencies except the standard library and should compile clean on all major
compilers without the need to install any additional development packages. All major desktop and mobile platforms
are supported.


Features
========
- Simple build system with no external dependencies.
- Simple and flexible API.
- Low-level API for direct access to raw audio data.
- High-level API for sound management, mixing, effects and optional 3D spatialization.
- Flexible node graph system for advanced mixing and effect processing.
- Resource management for loading sound files.
- 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.
- Channel mapping.
- 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.


Examples
========

This example shows one way to play a sound using the high level API.

```c
#include "miniaudio/miniaudio.h"

#include <stdio.h>

int main()
{
    ma_result result;
    ma_engine engine;

    result = ma_engine_init(NULL, &engine);
    if (result != MA_SUCCESS) {
        return -1;
    }

    ma_engine_play_sound(&engine, "sound.wav", 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
#include "miniaudio/miniaudio.h"

#include <stdio.h>

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/


Building
========
Just compile miniaudio.c like any other source file and include miniaudio.h like a normal header. There's no need
to install any dependencies. On Windows and macOS there's no need to link to anything. On Linux and BSD just link
to `-lpthread` and `-lm`. On iOS you need to compile as Objective-C. Link to `-ldl` if you get errors about
`dlopen()`, etc.

If you get errors about undefined references to `__sync_val_compare_and_swap_8`, `__atomic_load_8`, etc. you
need to link with `-latomic`.

ABI compatibility is not guaranteed between versions so take care if compiling as a DLL/SO. The suggested way
to integrate miniaudio is by adding it directly to your source tree.

You can also use CMake if that's your preference.


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 authoritative 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


Security
========
See the miniaudio [security policy](.github/SECURITY.md).


License
=======
Your choice of either public domain or [MIT No Attribution](https://github.com/aws/mit-0).

---

## File: examples/build/README.md

Examples
--------
    gcc ../simple_playback.c -o bin/simple_playback -ldl -lm -lpthread
    gcc ../simple_playback.c -o bin/simple_playback -ldl -lm -lpthread -Wall -Wextra -Wpedantic -std=c89
    
Emscripten
----------
On Windows, you need to move into the build and run emsdk_env.bat from a command prompt using an absolute
path like "C:\emsdk\emsdk_env.bat". Note that PowerShell doesn't work for me for some reason. Examples:

    emcc ../simple_playback_sine.c -o bin/simple_playback_sine.html
    emcc ../simple_playback_sine.c -o bin/simple_playback_sine.html -s WASM=0 -Wall -Wextra
    
To compile with support for Audio Worklets:

    emcc ../simple_playback_sine.c -o bin/simple_playback_sine.html -DMA_ENABLE_AUDIO_WORKLETS -sAUDIO_WORKLET=1 -sWASM_WORKERS=1 -sASYNCIFY

If you output WASM it may not work when running the web page locally. To test you can run with something
like this:

    emrun ./bin/simple_playback_sine.html

If you want to see stdout on the command line when running from emrun, add `--emrun` to your emcc command.

---

## File: extras/miniaudio_split/README.md

These files split the main library into separate .h and .c files. This is intended for those who prefer separate files
or whose build environment better suits this configuration. The files here are generated from a tool based on the
content in the main miniaudio.h file. Do not edit these files directly. If you want to contribute, please make the
contribution in the main file.

This is not always up to date with the most recent commit in the dev branch, but will usually be up to date with the
master branch.

---

## File: extras/osaudio/README.md

This is just a little experiment to explore some ideas for the kind of API that I would build if I
was building my own operation system. The name "osaudio" means Operating System Audio. Or maybe you
can think of it as Open Source Audio. It's whatever you want it to be.

The idea behind this project came about after considering the absurd complexity of audio APIs on
various platforms after years of working on miniaudio. This project aims to disprove the idea that
complete and flexible audio solutions and simple APIs are mutually exclusive and that it's possible
to have both. I challenge anybody to prove me wrong.

In addition to the above, I also wanted to explore some ideas for a different API design to
miniaudio. miniaudio uses a callback model for data transfer, whereas osaudio uses a blocking
read/write model.

This project is essentially just a header file with a reference implementation that uses miniaudio
under the hood. You can compile this very easily - just compile osaudio_miniaudio.c, and use
osaudio.h just like any other header. There are no dependencies for the header, and the miniaudio
implementation obviously requires miniaudio. Adjust the include path in osaudio_miniaudio.c if need
be.

See osaudio.h for full documentation. Below is an example to get you started:

```c
#include "osaudio.h"

...

osaudio_t audio;
osaudio_config_t config;

osaudio_config_init(&config, OSAUDIO_OUTPUT);
config.format   = OSAUDIO_FORMAT_F32;
config.channels = 2;
config.rate     = 48000;

osaudio_open(&audio, &config);

osaudio_write(audio, myAudioData, frameCount);  // <-- This will block until all of the data has been sent to the device.

osaudio_close(audio);
```

Compare the code above with the likes of other APIs like Core Audio and PipeWire. I challenge
anybody to argue their APIs are cleaner and easier to use than this when it comes to simple audio
playback.

If you have any feedback on this I'd be interested to hear it. In particular, I'd really like to
hear from people who believe the likes of Core Audio (Apple), PipeWire, PulseAudio or any other
audio API actually have good APIs (they don't!) and what makes their's better and/or worse than
this project.