Skip to content

M
miniaudio
Commit 65955dfa authored by David Reid's avatar David Reid
Browse files
Options

Update to documentation in preparation for some doc generation.

parent 0e354931
Hide whitespace changes
Inline Side-by-side
Showing with 182 additions and 198 deletions
miniaudio.h
View file @ 65955dfa
...@@ -18,7 +18,7 @@ miniaudio is a single file library for audio playback and capture. To use it, do ...@@ -18,7 +18,7 @@ miniaudio is a single file library for audio playback and capture. To use it, do
#include "miniaudio.h" #include "miniaudio.h"
``` ```
You can #include miniaudio.h in other parts of the program just like any other header. You can do `#include miniaudio.h` in other parts of the program just like any other header.
miniaudio uses the concept of a "device" as the abstraction for physical devices. The idea is that you choose a physical device to emit or capture audio from, miniaudio uses the concept of a "device" as the abstraction for physical devices. The idea is that you choose a physical device to emit or capture audio from,
and then move data to/from the device when miniaudio tells you to. Data is delivered to and from devices asynchronously via a callback which you specify when and then move data to/from the device when miniaudio tells you to. Data is delivered to and from devices asynchronously via a callback which you specify when
...@@ -101,11 +101,13 @@ it, which is what the example above does, but you can also stop the device with ...@@ -101,11 +101,13 @@ it, which is what the example above does, but you can also stop the device with
Note that it's important to never stop or start the device from inside the callback. This will result in a deadlock. Instead you set a variable or signal an Note that it's important to never stop or start the device from inside the callback. This will result in a deadlock. Instead you set a variable or signal an
event indicating that the device needs to stop and handle it in a different thread. The following APIs must never be called inside the callback: event indicating that the device needs to stop and handle it in a different thread. The following APIs must never be called inside the callback:
```c
ma_device_init() ma_device_init()
ma_device_init_ex() ma_device_init_ex()
ma_device_uninit() ma_device_uninit()
ma_device_start() ma_device_start()
ma_device_stop() ma_device_stop()
```
You must never try uninitializing and reinitializing a device inside the callback. You must also never try to stop and start it from inside the callback. There You must never try uninitializing and reinitializing a device inside the callback. You must also never try to stop and start it from inside the callback. There
are a few other things you shouldn't do in the callback depending on your requirements, however this isn't so much a thread-safety thing, but rather a real- are a few other things you shouldn't do in the callback depending on your requirements, however this isn't so much a thread-safety thing, but rather a real-
...@@ -217,140 +219,119 @@ allocate memory for the context. ...@@ -217,140 +219,119 @@ allocate memory for the context.
miniaudio should work cleanly out of the box without the need to download or install any dependencies. See below for platform-specific details. miniaudio should work cleanly out of the box without the need to download or install any dependencies. See below for platform-specific details.
Windows 2.1. Windows
------- ------------
The Windows build should compile cleanly on all popular compilers without the need to configure any include paths nor link to any libraries. The Windows build should compile cleanly on all popular compilers without the need to configure any include paths nor link to any libraries.
macOS and iOS 2.2. macOS and iOS
------------- ------------------
The macOS build should compile cleanly without the need to download any dependencies nor link to any libraries or frameworks. The iOS build needs to be The macOS build should compile cleanly without the need to download any dependencies nor link to any libraries or frameworks. The iOS build needs to be
compiled as Objective-C (sorry) and will need to link the relevant frameworks but should Just Work with Xcode. Compiling through the command line requires compiled as Objective-C (sorry) and will need to link the relevant frameworks but should Just Work with Xcode. Compiling through the command line requires
linking to -lpthread and -lm. linking to `-lpthread` and `-lm`.
Linux 2.3. Linux
----- ----------
The Linux build only requires linking to -ldl, -lpthread and -lm. You do not need any development packages. The Linux build only requires linking to `-ldl`, `-lpthread` and `-lm`. You do not need any development packages.
BSD 2.4. BSD
--- --------
The BSD build only requires linking to -lpthread and -lm. NetBSD uses audio(4), OpenBSD uses sndio and FreeBSD uses OSS. The BSD build only requires linking to `-lpthread` and `-lm`. NetBSD uses audio(4), OpenBSD uses sndio and FreeBSD uses OSS.
Android 2.5. Android
------- ------------
AAudio is the highest priority backend on Android. This should work out of the box without needing any kind of compiler configuration. Support for AAudio AAudio is the highest priority backend on Android. This should work out of the box without needing any kind of compiler configuration. Support for AAudio
starts with Android 8 which means older versions will fall back to OpenSL|ES which requires API level 16+. starts with Android 8 which means older versions will fall back to OpenSL|ES which requires API level 16+.
Emscripten 2.6. Emscripten
---------- ---------------
The Emscripten build emits Web Audio JavaScript directly and should Just Work without any configuration. You cannot use -std=c* compiler flags, nor -ansi. The Emscripten build emits Web Audio JavaScript directly and should Just Work without any configuration. You cannot use -std=c* compiler flags, nor -ansi.
Build Options 2.7. Build Options
------------- ------------------
#define these options before including miniaudio.h. `#define` these options before including miniaudio.h.
#define MA_NO_WASAPI +----------------------+----------------------------------------------------------------------------------------------------------------------------------+
Disables the WASAPI backend. | Option | Description |
+----------------------+----------------------------------------------------------------------------------------------------------------------------------+
#define MA_NO_DSOUND | MA_NO_WASAPI | Disables the WASAPI backend. |
Disables the DirectSound backend. +----------------------+----------------------------------------------------------------------------------------------------------------------------------+
| MA_NO_DSOUND | Disables the DirectSound backend. |
#define MA_NO_WINMM +----------------------+----------------------------------------------------------------------------------------------------------------------------------+
Disables the WinMM backend. | MA_NO_WINMM | Disables the WinMM backend. |
+----------------------+----------------------------------------------------------------------------------------------------------------------------------+
#define MA_NO_ALSA | MA_NO_ALSA | Disables the ALSA backend. |
Disables the ALSA backend. +----------------------+----------------------------------------------------------------------------------------------------------------------------------+
| MA_NO_PULSEAUDIO | Disables the PulseAudio backend. |
#define MA_NO_PULSEAUDIO +----------------------+----------------------------------------------------------------------------------------------------------------------------------+
Disables the PulseAudio backend. | MA_NO_JACK | Disables the JACK backend. |
+----------------------+----------------------------------------------------------------------------------------------------------------------------------+
#define MA_NO_JACK | MA_NO_COREAUDIO | Disables the Core Audio backend. |
Disables the JACK backend. +----------------------+----------------------------------------------------------------------------------------------------------------------------------+
| MA_NO_SNDIO | Disables the sndio backend. |
#define MA_NO_COREAUDIO +----------------------+----------------------------------------------------------------------------------------------------------------------------------+
Disables the Core Audio backend. | MA_NO_AUDIO4 | Disables the audio(4) backend. |
+----------------------+----------------------------------------------------------------------------------------------------------------------------------+
#define MA_NO_SNDIO | MA_NO_OSS | Disables the OSS backend. |
Disables the sndio backend. +----------------------+----------------------------------------------------------------------------------------------------------------------------------+
| MA_NO_AAUDIO | Disables the AAudio backend. |
#define MA_NO_AUDIO4 +----------------------+----------------------------------------------------------------------------------------------------------------------------------+
Disables the audio(4) backend. | MA_NO_OPENSL | Disables the OpenSL|ES backend. |
+----------------------+----------------------------------------------------------------------------------------------------------------------------------+
#define MA_NO_OSS | MA_NO_WEBAUDIO | Disables the Web Audio backend. |
Disables the OSS backend. +----------------------+----------------------------------------------------------------------------------------------------------------------------------+
| MA_NO_NULL | Disables the null backend. |
#define MA_NO_AAUDIO +----------------------+----------------------------------------------------------------------------------------------------------------------------------+
Disables the AAudio backend. | MA_NO_DECODING | Disables decoding APIs. |
+----------------------+----------------------------------------------------------------------------------------------------------------------------------+
#define MA_NO_OPENSL | MA_NO_ENCODING | Disables encoding APIs. |
Disables the OpenSL|ES backend. +----------------------+----------------------------------------------------------------------------------------------------------------------------------+
| MA_NO_WAV | Disables the built-in WAV decoder and encoder. |
#define MA_NO_WEBAUDIO +----------------------+----------------------------------------------------------------------------------------------------------------------------------+
Disables the Web Audio backend. | MA_NO_FLAC | Disables the built-in FLAC decoder. |
+----------------------+----------------------------------------------------------------------------------------------------------------------------------+
#define MA_NO_NULL | MA_NO_MP3 | Disables the built-in MP3 decoder. |
Disables the null backend. +----------------------+----------------------------------------------------------------------------------------------------------------------------------+
| MA_NO_DEVICE_IO | Disables playback and recording. This will disable ma_context and ma_device APIs. This is useful if you only want to use |
#define MA_NO_DECODING | | miniaudio's data conversion and/or decoding APIs. |
Disables decoding APIs. +----------------------+----------------------------------------------------------------------------------------------------------------------------------+
| MA_NO_THREADING | Disables the ma_thread, ma_mutex, ma_semaphore and ma_event APIs. This option is useful if you only need to use miniaudio for |
#define MA_NO_ENCODING | | data conversion, decoding and/or encoding. Some families of APIs require threading which means the following options must also |
Disables encoding APIs. | | be set: |
| | |
#define MA_NO_WAV | | ``` |
Disables the built-in WAV decoder and encoder. | | MA_NO_DEVICE_IO |
| | ``` |
#define MA_NO_FLAC +----------------------+----------------------------------------------------------------------------------------------------------------------------------+
Disables the built-in FLAC decoder. | MA_NO_GENERATION | Disables generation APIs such a ma_waveform and ma_noise. |
+----------------------+----------------------------------------------------------------------------------------------------------------------------------+
#define MA_NO_MP3 | MA_NO_SSE2 | Disables SSE2 optimizations. |
Disables the built-in MP3 decoder. +----------------------+----------------------------------------------------------------------------------------------------------------------------------+
| MA_NO_AVX2 | Disables AVX2 optimizations. |
#define MA_NO_DEVICE_IO +----------------------+----------------------------------------------------------------------------------------------------------------------------------+
Disables playback and recording. This will disable ma_context and ma_device APIs. This is useful if you only want to use miniaudio's data conversion and/or | MA_NO_AVX512 | Disables AVX-512 optimizations. |
decoding APIs. +----------------------+----------------------------------------------------------------------------------------------------------------------------------+
| MA_NO_NEON | Disables NEON optimizations. |
#define MA_NO_THREADING +----------------------+----------------------------------------------------------------------------------------------------------------------------------+
Disables the ma_thread, ma_mutex, ma_semaphore and ma_event APIs. This option is useful if you only need to use miniaudio for data conversion, decoding | MA_LOG_LEVEL [level] | Sets the logging level. Set level to one of the following: |
and/or encoding. Some families of APIs require threading which means the following options must also be set: | | |
MA_NO_DEVICE_IO | | ``` |
| | MA_LOG_LEVEL_VERBOSE |
#define MA_NO_GENERATION | | MA_LOG_LEVEL_INFO |
Disables generation APIs such a ma_waveform and ma_noise. | | MA_LOG_LEVEL_WARNING |
| | MA_LOG_LEVEL_ERROR |
#define MA_NO_SSE2 | | ``` |
Disables SSE2 optimizations. +----------------------+----------------------------------------------------------------------------------------------------------------------------------+
| MA_DEBUG_OUTPUT | Enable printf() debug output. |
#define MA_NO_AVX2 +----------------------+----------------------------------------------------------------------------------------------------------------------------------+
Disables AVX2 optimizations. | MA_COINIT_VALUE | Windows only. The value to pass to internal calls to `CoInitializeEx()`. Defaults to `COINIT_MULTITHREADED`. |
+----------------------+----------------------------------------------------------------------------------------------------------------------------------+
#define MA_NO_AVX512 | MA_API | Controls how public APIs should be decorated. Defaults to `extern`. |
Disables AVX-512 optimizations. +----------------------+----------------------------------------------------------------------------------------------------------------------------------+
| MA_DLL | If set, configures MA_API to either import or export APIs depending on whether or not the implementation is being defined. If |
#define MA_NO_NEON | | defining the implementation, MA_API will be configured to export. Otherwise it will be configured to import. This has no effect |
Disables NEON optimizations. | | if MA_API is defined externally. |
+----------------------+----------------------------------------------------------------------------------------------------------------------------------+
#define MA_LOG_LEVEL <Level>
Sets the logging level. Set level to one of the following:
MA_LOG_LEVEL_VERBOSE
MA_LOG_LEVEL_INFO
MA_LOG_LEVEL_WARNING
MA_LOG_LEVEL_ERROR
#define MA_DEBUG_OUTPUT
Enable printf() debug output.
#define MA_COINIT_VALUE
Windows only. The value to pass to internal calls to CoInitializeEx(). Defaults to COINIT_MULTITHREADED.
#define MA_API
Controls how public APIs should be decorated. Defaults to `extern`.
#define MA_DLL
If set, configures MA_API to either import or export APIs depending on whether or not the implementation is being defined. If defining the implementation,
MA_API will be configured to export. Otherwise it will be configured to import. This has no effect if MA_API is defined externally.
3. Definitions 3. Definitions
...@@ -567,6 +548,7 @@ The different dithering modes include the following, in order of efficiency: ...@@ -567,6 +548,7 @@ The different dithering modes include the following, in order of efficiency:
Note that even if the dither mode is set to something other than `ma_dither_mode_none`, it will be ignored for conversions where dithering is not needed. Note that even if the dither mode is set to something other than `ma_dither_mode_none`, it will be ignored for conversions where dithering is not needed.
Dithering is available for the following conversions: Dithering is available for the following conversions:
```
s16 -> u8 s16 -> u8
s24 -> u8 s24 -> u8
s32 -> u8 s32 -> u8
...@@ -574,6 +556,7 @@ Dithering is available for the following conversions: ...@@ -574,6 +556,7 @@ Dithering is available for the following conversions:
s24 -> s16 s24 -> s16
s32 -> s16 s32 -> s16
f32 -> s16 f32 -> s16
```
Note that it is not an error to pass something other than ma_dither_mode_none for conversions where dither is not used. It will just be ignored. Note that it is not an error to pass something other than ma_dither_mode_none for conversions where dither is not used. It will just be ignored.
...@@ -643,63 +626,63 @@ be one of the following: ...@@ -643,63 +626,63 @@ be one of the following:
| ma_standard_channel_map_flac | FLAC channel map. | | ma_standard_channel_map_flac | FLAC channel map. |
| ma_standard_channel_map_vorbis | Vorbis channel map. | | ma_standard_channel_map_vorbis | Vorbis channel map. |
| ma_standard_channel_map_sound4 | FreeBSD's sound(4). | | ma_standard_channel_map_sound4 | FreeBSD's sound(4). |
| ma_standard_channel_map_sndio | sndio channel map. www.sndio.org/tips.html | | ma_standard_channel_map_sndio | sndio channel map. http://www.sndio.org/tips.html |
| ma_standard_channel_map_webaudio | https://webaudio.github.io/web-audio-api/#ChannelOrdering | | ma_standard_channel_map_webaudio | https://webaudio.github.io/web-audio-api/#ChannelOrdering |
+-----------------------------------+-----------------------------------------------------------+ +-----------------------------------+-----------------------------------------------------------+
Below are the channel maps used by default in miniaudio (ma_standard_channel_map_default): Below are the channel maps used by default in miniaudio (ma_standard_channel_map_default):
+---------------+------------------------------+ +---------------+---------------------------------+
| Channel Count | Mapping | | Channel Count | Mapping |
+---------------+------------------------------+ +---------------+---------------------------------+
| 1 (Mono) | 0: MA_CHANNEL_MONO | | 1 (Mono) | 0: MA_CHANNEL_MONO |
+---------------+------------------------------+ +---------------+---------------------------------+
| 2 (Stereo) | 0: MA_CHANNEL_FRONT_LEFT | | 2 (Stereo) | 0: MA_CHANNEL_FRONT_LEFT <br> |
| | 1: MA_CHANNEL_FRONT_RIGHT | | | 1: MA_CHANNEL_FRONT_RIGHT |
+---------------+------------------------------+ +---------------+---------------------------------+
| 3 | 0: MA_CHANNEL_FRONT_LEFT | | 3 | 0: MA_CHANNEL_FRONT_LEFT <br> |
| | 1: MA_CHANNEL_FRONT_RIGHT | | | 1: MA_CHANNEL_FRONT_RIGHT <br> |
| | 2: MA_CHANNEL_FRONT_CENTER | | | 2: MA_CHANNEL_FRONT_CENTER |
+---------------+------------------------------+ +---------------+---------------------------------+
| 4 (Surround) | 0: MA_CHANNEL_FRONT_LEFT | | 4 (Surround) | 0: MA_CHANNEL_FRONT_LEFT <br> |
| | 1: MA_CHANNEL_FRONT_RIGHT | | | 1: MA_CHANNEL_FRONT_RIGHT <br> |
| | 2: MA_CHANNEL_FRONT_CENTER | | | 2: MA_CHANNEL_FRONT_CENTER <br> |
| | 3: MA_CHANNEL_BACK_CENTER | | | 3: MA_CHANNEL_BACK_CENTER |
+---------------+------------------------------+ +---------------+---------------------------------+
| 5 | 0: MA_CHANNEL_FRONT_LEFT | | 5 | 0: MA_CHANNEL_FRONT_LEFT <br> |
| | 1: MA_CHANNEL_FRONT_RIGHT | | | 1: MA_CHANNEL_FRONT_RIGHT <br> |
| | 2: MA_CHANNEL_FRONT_CENTER | | | 2: MA_CHANNEL_FRONT_CENTER <br> |
| | 3: MA_CHANNEL_BACK_LEFT | | | 3: MA_CHANNEL_BACK_LEFT <br> |
| | 4: MA_CHANNEL_BACK_RIGHT | | | 4: MA_CHANNEL_BACK_RIGHT |
+---------------+------------------------------+ +---------------+---------------------------------+
| 6 (5.1) | 0: MA_CHANNEL_FRONT_LEFT | | 6 (5.1) | 0: MA_CHANNEL_FRONT_LEFT <br> |
| | 1: MA_CHANNEL_FRONT_RIGHT | | | 1: MA_CHANNEL_FRONT_RIGHT <br> |
| | 2: MA_CHANNEL_FRONT_CENTER | | | 2: MA_CHANNEL_FRONT_CENTER <br> |
| | 3: MA_CHANNEL_LFE | | | 3: MA_CHANNEL_LFE <br> |
| | 4: MA_CHANNEL_SIDE_LEFT | | | 4: MA_CHANNEL_SIDE_LEFT <br> |
| | 5: MA_CHANNEL_SIDE_RIGHT | | | 5: MA_CHANNEL_SIDE_RIGHT |
+---------------+------------------------------+ +---------------+---------------------------------+
| 7 | 0: MA_CHANNEL_FRONT_LEFT | | 7 | 0: MA_CHANNEL_FRONT_LEFT <br> |
| | 1: MA_CHANNEL_FRONT_RIGHT | | | 1: MA_CHANNEL_FRONT_RIGHT <br> |
| | 2: MA_CHANNEL_FRONT_CENTER | | | 2: MA_CHANNEL_FRONT_CENTER <br> |
| | 3: MA_CHANNEL_LFE | | | 3: MA_CHANNEL_LFE <br> |
| | 4: MA_CHANNEL_BACK_CENTER | | | 4: MA_CHANNEL_BACK_CENTER <br> |
| | 4: MA_CHANNEL_SIDE_LEFT | | | 4: MA_CHANNEL_SIDE_LEFT <br> |
| | 5: MA_CHANNEL_SIDE_RIGHT | | | 5: MA_CHANNEL_SIDE_RIGHT |
+---------------+------------------------------+ +---------------+---------------------------------+
| 8 (7.1) | 0: MA_CHANNEL_FRONT_LEFT | | 8 (7.1) | 0: MA_CHANNEL_FRONT_LEFT <br> |
| | 1: MA_CHANNEL_FRONT_RIGHT | | | 1: MA_CHANNEL_FRONT_RIGHT <br> |
| | 2: MA_CHANNEL_FRONT_CENTER | | | 2: MA_CHANNEL_FRONT_CENTER <br> |
| | 3: MA_CHANNEL_LFE | | | 3: MA_CHANNEL_LFE <br> |
| | 4: MA_CHANNEL_BACK_LEFT | | | 4: MA_CHANNEL_BACK_LEFT <br> |
| | 5: MA_CHANNEL_BACK_RIGHT | | | 5: MA_CHANNEL_BACK_RIGHT <br> |
| | 6: MA_CHANNEL_SIDE_LEFT | | | 6: MA_CHANNEL_SIDE_LEFT <br> |
| | 7: MA_CHANNEL_SIDE_RIGHT | | | 7: MA_CHANNEL_SIDE_RIGHT |
+---------------+------------------------------+ +---------------+---------------------------------+
| Other | All channels set to 0. This | | Other | All channels set to 0. This |
| | is equivalent to the same | | | is equivalent to the same |
| | mapping as the device. | | | mapping as the device. |
+---------------+------------------------------+ +---------------+---------------------------------+
...@@ -1248,7 +1231,7 @@ something like the following: ...@@ -1248,7 +1231,7 @@ something like the following:
The `ma_pcm_rb_init()` function takes the sample format and channel count as parameters because it's the PCM varient of the ring buffer API. For the regular The `ma_pcm_rb_init()` function takes the sample format and channel count as parameters because it's the PCM varient of the ring buffer API. For the regular
ring buffer that operates on bytes you would call `ma_rb_init()` which leaves these out and just takes the size of the buffer in bytes instead of frames. The ring buffer that operates on bytes you would call `ma_rb_init()` which leaves these out and just takes the size of the buffer in bytes instead of frames. The
fourth parameter is an optional pre-allocated buffer and the fifth parameter is a pointer to a `ma_allocation_callbacks` structure for custom memory allocation fourth parameter is an optional pre-allocated buffer and the fifth parameter is a pointer to a `ma_allocation_callbacks` structure for custom memory allocation
routines. Passing in NULL for this results in MA_MALLOC() and MA_FREE() being used. routines. Passing in `NULL` for this results in `MA_MALLOC()` and `MA_FREE()` being used.
Use `ma_pcm_rb_init_ex()` if you need a deinterleaved buffer. The data for each sub-buffer is offset from each other based on the stride. To manage your sub- Use `ma_pcm_rb_init_ex()` if you need a deinterleaved buffer. The data for each sub-buffer is offset from each other based on the stride. To manage your sub-
buffers you can use `ma_pcm_rb_get_subbuffer_stride()`, `ma_pcm_rb_get_subbuffer_offset()` and `ma_pcm_rb_get_subbuffer_ptr()`. buffers you can use `ma_pcm_rb_get_subbuffer_stride()`, `ma_pcm_rb_get_subbuffer_offset()` and `ma_pcm_rb_get_subbuffer_ptr()`.
...@@ -1268,9 +1251,9 @@ the consumer thread, and the write pointer forward by the producer thread. If th ...@@ -1268,9 +1251,9 @@ the consumer thread, and the write pointer forward by the producer thread. If th
there is too little space between the pointers, move the write pointer forward. there is too little space between the pointers, move the write pointer forward.
You can use a ring buffer at the byte level instead of the PCM frame level by using the `ma_rb` API. This is exactly the same, only you will use the `ma_rb` You can use a ring buffer at the byte level instead of the PCM frame level by using the `ma_rb` API. This is exactly the same, only you will use the `ma_rb`
functions instead of `ma_pcm_rb` and instead of frame counts you'll pass around byte counts. functions instead of `ma_pcm_rb` and instead of frame counts pass around byte counts.
The maximum size of the buffer in bytes is 0x7FFFFFFF-(MA_SIMD_ALIGNMENT-1) due to the most significant bit being used to encode a loop flag and the internally The maximum size of the buffer in bytes is `0x7FFFFFFF-(MA_SIMD_ALIGNMENT-1)` due to the most significant bit being used to encode a loop flag and the internally
managed buffers always being aligned to MA_SIMD_ALIGNMENT. managed buffers always being aligned to MA_SIMD_ALIGNMENT.
Note that the ring buffer is only thread safe when used by a single consumer thread and single producer thread. Note that the ring buffer is only thread safe when used by a single consumer thread and single producer thread.
...@@ -1295,7 +1278,7 @@ The following backends are supported by miniaudio. ...@@ -1295,7 +1278,7 @@ The following backends are supported by miniaudio.
| audio(4) | ma_backend_audio4 | NetBSD, OpenBSD | | audio(4) | ma_backend_audio4 | NetBSD, OpenBSD |
| OSS | ma_backend_oss | FreeBSD | | OSS | ma_backend_oss | FreeBSD |
| AAudio | ma_backend_aaudio | Android 8+ | | AAudio | ma_backend_aaudio | Android 8+ |
| OpenSL|ES | ma_backend_opensl | Android (API level 16+) | | OpenSL ES | ma_backend_opensl | Android (API level 16+) |
| Web Audio | ma_backend_webaudio | Web (via Emscripten) | | Web Audio | ma_backend_webaudio | Web (via Emscripten) |
| Null | ma_backend_null | Cross Platform (not used on Web) | | Null | ma_backend_null | Cross Platform (not used on Web) |
+-------------+-----------------------+--------------------------------------------------------+ +-------------+-----------------------+--------------------------------------------------------+
...@@ -1305,20 +1288,18 @@ Some backends have some nuance details you may want to be aware of. ...@@ -1305,20 +1288,18 @@ Some backends have some nuance details you may want to be aware of.
11.1. WASAPI 11.1. WASAPI
------------ ------------
- Low-latency shared mode will be disabled when using an application-defined sample rate which is different to the device's native sample rate. To work around - Low-latency shared mode will be disabled when using an application-defined sample rate which is different to the device's native sample rate. To work around
this, set wasapi.noAutoConvertSRC to true in the device config. This is due to IAudioClient3_InitializeSharedAudioStream() failing when the this, set `wasapi.noAutoConvertSRC` to true in the device config. This is due to IAudioClient3_InitializeSharedAudioStream() failing when the
AUDCLNT_STREAMFLAGS_AUTOCONVERTPCM flag is specified. Setting wasapi.noAutoConvertSRC will result in miniaudio's internal resampler being used instead which `AUDCLNT_STREAMFLAGS_AUTOCONVERTPCM` flag is specified. Setting wasapi.noAutoConvertSRC will result in miniaudio's internal resampler being used instead
will in turn enable the use of low-latency shared mode. which will in turn enable the use of low-latency shared mode.
11.2. PulseAudio 11.2. PulseAudio
---------------- ----------------
- If you experience bad glitching/noise on Arch Linux, consider this fix from the Arch wiki: - If you experience bad glitching/noise on Arch Linux, consider this fix from the Arch wiki:
https://wiki.archlinux.org/index.php/PulseAudio/Troubleshooting#Glitches,_skips_or_crackling https://wiki.archlinux.org/index.php/PulseAudio/Troubleshooting#Glitches,_skips_or_crackling. Alternatively, consider using a different backend such as ALSA.
Alternatively, consider using a different backend such as ALSA.
11.3. Android 11.3. Android
------------- -------------
- To capture audio on Android, remember to add the RECORD_AUDIO permission to your manifest: - To capture audio on Android, remember to add the RECORD_AUDIO permission to your manifest: `<uses-permission android:name="android.permission.RECORD_AUDIO" />`
<uses-permission android:name="android.permission.RECORD_AUDIO" />
- With OpenSL|ES, only a single ma_context can be active at any given time. This is due to a limitation with OpenSL|ES. - With OpenSL|ES, only a single ma_context can be active at any given time. This is due to a limitation with OpenSL|ES.
- With AAudio, only default devices are enumerated. This is due to AAudio not having an enumeration API (devices are enumerated through Java). You can however - With AAudio, only default devices are enumerated. This is due to AAudio not having an enumeration API (devices are enumerated through Java). You can however
perform your own device enumeration through Java and then set the ID in the ma_device_id structure (ma_device_id.aaudio) and pass it to ma_device_init(). perform your own device enumeration through Java and then set the ID in the ma_device_id structure (ma_device_id.aaudio) and pass it to ma_device_init().
...@@ -1329,16 +1310,19 @@ Some backends have some nuance details you may want to be aware of. ...@@ -1329,16 +1310,19 @@ Some backends have some nuance details you may want to be aware of.
--------- ---------
- UWP only supports default playback and capture devices. - UWP only supports default playback and capture devices.
- UWP requires the Microphone capability to be enabled in the application's manifest (Package.appxmanifest): - UWP requires the Microphone capability to be enabled in the application's manifest (Package.appxmanifest):
<Package ...>
... ```
<Capabilities> <Package ...>
<DeviceCapability Name="microphone" /> ...
</Capabilities> <Capabilities>
</Package> <DeviceCapability Name="microphone" />
</Capabilities>
</Package>
```
11.5. Web Audio / Emscripten 11.5. Web Audio / Emscripten
---------------------- ----------------------------
- You cannot use -std=c* compiler flags, nor -ansi. This only applies to the Emscripten build. - You cannot use `-std=c*` compiler flags, nor `-ansi`. This only applies to the Emscripten build.
- The first time a context is initialized it will create a global object called "miniaudio" whose primary purpose is to act as a factory for device objects. - The first time a context is initialized it will create a global object called "miniaudio" whose primary purpose is to act as a factory for device objects.
- Currently the Web Audio backend uses ScriptProcessorNode's, but this may need to change later as they've been deprecated. - Currently the Web Audio backend uses ScriptProcessorNode's, but this may need to change later as they've been deprecated.
- Google has implemented a policy in their browsers that prevent automatic media output without first receiving some kind of user input. The following web page - Google has implemented a policy in their browsers that prevent automatic media output without first receiving some kind of user input. The following web page
...@@ -1351,13 +1335,13 @@ Some backends have some nuance details you may want to be aware of. ...@@ -1351,13 +1335,13 @@ Some backends have some nuance details you may want to be aware of.
======================= =======================
- Automatic stream routing is enabled on a per-backend basis. Support is explicitly enabled for WASAPI and Core Audio, however other backends such as - Automatic stream routing is enabled on a per-backend basis. Support is explicitly enabled for WASAPI and Core Audio, however other backends such as
PulseAudio may naturally support it, though not all have been tested. PulseAudio may naturally support it, though not all have been tested.
- The contents of the output buffer passed into the data callback will always be pre-initialized to zero unless the noPreZeroedOutputBuffer config variable in - The contents of the output buffer passed into the data callback will always be pre-initialized to zero unless the `noPreZeroedOutputBuffer` config variable
ma_device_config is set to true, in which case it'll be undefined which will require you to write something to the entire buffer. in `ma_device_config` is set to true, in which case it'll be undefined which will require you to write something to the entire buffer.
- By default miniaudio will automatically clip samples. This only applies when the playback sample format is configured as ma_format_f32. If you are doing - By default miniaudio will automatically clip samples. This only applies when the playback sample format is configured as `ma_format_f32`. If you are doing
clipping yourself, you can disable this overhead by setting noClip to true in the device config. clipping yourself, you can disable this overhead by setting `noClip` to true in the device config.
- The sndio backend is currently only enabled on OpenBSD builds. - The sndio backend is currently only enabled on OpenBSD builds.
- The audio(4) backend is supported on OpenBSD, but you may need to disable sndiod before you can use it. - The audio(4) backend is supported on OpenBSD, but you may need to disable sndiod before you can use it.
- Note that GCC and Clang requires "-msse2", "-mavx2", etc. for SIMD optimizations. - Note that GCC and Clang requires `-msse2`, `-mavx2`, etc. for SIMD optimizations.
*/ */
#ifndef miniaudio_h #ifndef miniaudio_h
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment