git.mutantstargoat.com Git - liquidmodel/blob - libs/miniaudio/README.md

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