|
| 1 | +<h1 align="center"> |
| 2 | + <a href="https://miniaud.io"><img src="https://miniaud.io/img/miniaudio_wide.png" alt="miniaudio" width="1280"></a> |
| 3 | + <br> |
| 4 | +</h1> |
| 5 | + |
| 6 | +<h4 align="center">A single file library for audio playback and capture.</h4> |
| 7 | + |
| 8 | +<p align="center"> |
| 9 | + <a href="https://discord.gg/9vpqbjU"><img src="https://img.shields.io/discord/712952679415939085?label=discord&logo=discord" alt="discord"></a> |
| 10 | + <a href="https://twitter.com/mackron"><img src="https://img.shields.io/twitter/follow/mackron?style=flat&label=twitter&color=1da1f2&logo=twitter" alt="twitter"></a> |
| 11 | + <a href="https://www.reddit.com/r/miniaudio"><img src="https://img.shields.io/reddit/subreddit-subscribers/miniaudio?label=r%2Fminiaudio&logo=reddit" alt="reddit"></a> |
| 12 | +</p> |
| 13 | + |
| 14 | +<p align="center"> |
| 15 | + <a href="#examples">Examples</a> - |
| 16 | + <a href="#documentation">Documentation</a> - |
| 17 | + <a href="#supported-platforms">Supported Platforms</a> - |
| 18 | + <a href="#backends">Backends</a> - |
| 19 | + <a href="#major-features">Major Features</a> - |
| 20 | + <a href="#building">Building</a> - |
| 21 | + <a href="#unofficial-bindings">Unofficial Bindings</a> |
| 22 | +</p> |
| 23 | + |
| 24 | +Examples |
| 25 | +======== |
| 26 | + |
| 27 | +This example shows one way to play a sound using the high level API. |
| 28 | + |
| 29 | +```c |
| 30 | +#define MINIAUDIO_IMPLEMENTATION |
| 31 | +#include "../miniaudio.h" |
| 32 | + |
| 33 | +#include <stdio.h> |
| 34 | + |
| 35 | +int main(int argc, char** argv) |
| 36 | +{ |
| 37 | + ma_result result; |
| 38 | + ma_engine engine; |
| 39 | + |
| 40 | + if (argc < 2) { |
| 41 | + printf("No input file."); |
| 42 | + return -1; |
| 43 | + } |
| 44 | + |
| 45 | + result = ma_engine_init(NULL, &engine); |
| 46 | + if (result != MA_SUCCESS) { |
| 47 | + printf("Failed to initialize audio engine."); |
| 48 | + return -1; |
| 49 | + } |
| 50 | + |
| 51 | + ma_engine_play_sound(&engine, argv[1], NULL); |
| 52 | + |
| 53 | + printf("Press Enter to quit..."); |
| 54 | + getchar(); |
| 55 | + |
| 56 | + ma_engine_uninit(&engine); |
| 57 | + |
| 58 | + return 0; |
| 59 | +} |
| 60 | +``` |
| 61 | +
|
| 62 | +This example shows how to decode and play a sound using the low level API. |
| 63 | +
|
| 64 | +```c |
| 65 | +#define MINIAUDIO_IMPLEMENTATION |
| 66 | +#include "../miniaudio.h" |
| 67 | +
|
| 68 | +#include <stdio.h> |
| 69 | +
|
| 70 | +void data_callback(ma_device* pDevice, void* pOutput, const void* pInput, ma_uint32 frameCount) |
| 71 | +{ |
| 72 | + ma_decoder* pDecoder = (ma_decoder*)pDevice->pUserData; |
| 73 | + if (pDecoder == NULL) { |
| 74 | + return; |
| 75 | + } |
| 76 | +
|
| 77 | + ma_decoder_read_pcm_frames(pDecoder, pOutput, frameCount); |
| 78 | +
|
| 79 | + (void)pInput; |
| 80 | +} |
| 81 | +
|
| 82 | +int main(int argc, char** argv) |
| 83 | +{ |
| 84 | + ma_result result; |
| 85 | + ma_decoder decoder; |
| 86 | + ma_device_config deviceConfig; |
| 87 | + ma_device device; |
| 88 | +
|
| 89 | + if (argc < 2) { |
| 90 | + printf("No input file.\n"); |
| 91 | + return -1; |
| 92 | + } |
| 93 | +
|
| 94 | + result = ma_decoder_init_file(argv[1], NULL, &decoder); |
| 95 | + if (result != MA_SUCCESS) { |
| 96 | + return -2; |
| 97 | + } |
| 98 | +
|
| 99 | + deviceConfig = ma_device_config_init(ma_device_type_playback); |
| 100 | + deviceConfig.playback.format = decoder.outputFormat; |
| 101 | + deviceConfig.playback.channels = decoder.outputChannels; |
| 102 | + deviceConfig.sampleRate = decoder.outputSampleRate; |
| 103 | + deviceConfig.dataCallback = data_callback; |
| 104 | + deviceConfig.pUserData = &decoder; |
| 105 | +
|
| 106 | + if (ma_device_init(NULL, &deviceConfig, &device) != MA_SUCCESS) { |
| 107 | + printf("Failed to open playback device.\n"); |
| 108 | + ma_decoder_uninit(&decoder); |
| 109 | + return -3; |
| 110 | + } |
| 111 | +
|
| 112 | + if (ma_device_start(&device) != MA_SUCCESS) { |
| 113 | + printf("Failed to start playback device.\n"); |
| 114 | + ma_device_uninit(&device); |
| 115 | + ma_decoder_uninit(&decoder); |
| 116 | + return -4; |
| 117 | + } |
| 118 | +
|
| 119 | + printf("Press Enter to quit..."); |
| 120 | + getchar(); |
| 121 | +
|
| 122 | + ma_device_uninit(&device); |
| 123 | + ma_decoder_uninit(&decoder); |
| 124 | +
|
| 125 | + return 0; |
| 126 | +} |
| 127 | +``` |
| 128 | + |
| 129 | +More examples can be found in the [examples](examples) folder or online here: https://miniaud.io/docs/examples/ |
| 130 | + |
| 131 | + |
| 132 | +Documentation |
| 133 | +============= |
| 134 | +Online documentation can be found here: https://miniaud.io/docs/ |
| 135 | + |
| 136 | +Documentation can also be found at the top of [miniaudio.h](https://raw.githubusercontent.com/mackron/miniaudio/master/miniaudio.h) |
| 137 | +which is always the most up-to-date and authoritive source of information on how to use miniaudio. All other |
| 138 | +documentation is generated from this in-code documentation. |
| 139 | + |
| 140 | + |
| 141 | +Supported Platforms |
| 142 | +=================== |
| 143 | +- Windows (XP+), UWP |
| 144 | +- macOS, iOS |
| 145 | +- Linux |
| 146 | +- BSD |
| 147 | +- Android |
| 148 | +- Raspberry Pi |
| 149 | +- Emscripten / HTML5 |
| 150 | + |
| 151 | + |
| 152 | +Backends |
| 153 | +======== |
| 154 | +- WASAPI |
| 155 | +- DirectSound |
| 156 | +- WinMM |
| 157 | +- Core Audio (Apple) |
| 158 | +- ALSA |
| 159 | +- PulseAudio |
| 160 | +- JACK |
| 161 | +- sndio (OpenBSD) |
| 162 | +- audio(4) (NetBSD and OpenBSD) |
| 163 | +- OSS (FreeBSD) |
| 164 | +- AAudio (Android 8.0+) |
| 165 | +- OpenSL|ES (Android only) |
| 166 | +- Web Audio (Emscripten) |
| 167 | +- Null (Silence) |
| 168 | +- Custom |
| 169 | + |
| 170 | + |
| 171 | +Major Features |
| 172 | +============== |
| 173 | +- Your choice of either public domain or [MIT No Attribution](https://github.com/aws/mit-0). |
| 174 | +- Entirely contained within a single file for easy integration into your source tree. |
| 175 | +- No external dependencies except for the C standard library and backend libraries. |
| 176 | +- Written in C and compilable as C++, enabling miniaudio to work on almost all compilers. |
| 177 | +- Supports all major desktop and mobile platforms, with multiple backends for maximum compatibility. |
| 178 | +- A low level API with direct access to the raw audio data. |
| 179 | +- A high level API with sound management and effects, including 3D spatialization. |
| 180 | +- Supports playback, capture, full-duplex and loopback (WASAPI only). |
| 181 | +- Device enumeration for connecting to specific devices, not just defaults. |
| 182 | +- Connect to multiple devices at once. |
| 183 | +- Shared and exclusive mode on supported backends. |
| 184 | +- Resource management for loading and streaming sounds. |
| 185 | +- A node graph system for advanced mixing and effect processing. |
| 186 | +- Data conversion (sample format conversion, channel conversion and resampling). |
| 187 | +- Filters. |
| 188 | + - Biquads |
| 189 | + - Low-pass (first, second and high order) |
| 190 | + - High-pass (first, second and high order) |
| 191 | + - Band-pass (second and high order) |
| 192 | +- Effects. |
| 193 | + - Delay/Echo |
| 194 | + - Spatializer |
| 195 | + - Stereo Pan |
| 196 | +- Waveform generation (sine, square, triangle, sawtooth). |
| 197 | +- Noise generation (white, pink, Brownian). |
| 198 | +- Decoding |
| 199 | + - WAV |
| 200 | + - FLAC |
| 201 | + - MP3 |
| 202 | + - Vorbis via stb_vorbis (not built in - must be included separately). |
| 203 | + - Custom |
| 204 | +- Encoding |
| 205 | + - WAV |
| 206 | + |
| 207 | +Refer to the [Programming Manual](https://miniaud.io/docs/manual/) for a more complete description of |
| 208 | +available features in miniaudio. |
| 209 | + |
| 210 | + |
| 211 | +Building |
| 212 | +======== |
| 213 | +Do the following in one source file: |
| 214 | +```c |
| 215 | +#define MINIAUDIO_IMPLEMENTATION |
| 216 | +#include "miniaudio.h" |
| 217 | +``` |
| 218 | +Then just compile. There's no need to install any dependencies. On Windows and macOS there's no need to link |
| 219 | +to anything. On Linux just link to -lpthread, -lm and -ldl. On BSD just link to -lpthread and -lm. On iOS you |
| 220 | +need to compile as Objective-C. |
| 221 | + |
| 222 | +If you prefer separate .h and .c files, you can find a split version of miniaudio in the extras/miniaudio_split |
| 223 | +folder. From here you can use miniaudio as a traditional .c and .h library - just add miniaudio.c to your source |
| 224 | +tree like any other source file and include miniaudio.h like a normal header. If you prefer compiling as a |
| 225 | +single translation unit (AKA unity builds), you can just #include the .c file in your main source file: |
| 226 | +```c |
| 227 | +#include "miniaudio.c" |
| 228 | +``` |
| 229 | +Note that the split version is auto-generated using a tool and is based on the main file in the root directory. |
| 230 | +If you want to contribute, please make the change in the main file. |
| 231 | + |
| 232 | +Vorbis Decoding |
| 233 | +--------------- |
| 234 | +Vorbis decoding is enabled via stb_vorbis. To use it, you need to include the header section of stb_vorbis |
| 235 | +before the implementation of miniaudio. You can enable Vorbis by doing the following: |
| 236 | + |
| 237 | +```c |
| 238 | +#define STB_VORBIS_HEADER_ONLY |
| 239 | +#include "extras/stb_vorbis.c" /* Enables Vorbis decoding. */ |
| 240 | + |
| 241 | +#define MINIAUDIO_IMPLEMENTATION |
| 242 | +#include "miniaudio.h" |
| 243 | + |
| 244 | +/* stb_vorbis implementation must come after the implementation of miniaudio. */ |
| 245 | +#undef STB_VORBIS_HEADER_ONLY |
| 246 | +#include "extras/stb_vorbis.c" |
| 247 | +``` |
0 commit comments