mirror/miniaudio
1
0
Fork 0
mirror of https://github.com/mackron/miniaudio.git synced 2026-04-22 00:06:59 +02:00
Code Issues Packages Projects Releases Wiki Activity
Files
189beb67faecc813393a44b349de00fc532785a6
miniaudio/README.md
T
David Reid 189beb67fa Experiment with a change to the readme.
2023-04-30 08:53:14 +10:00

371 lines
11 KiB
Markdown
Raw Blame History

<h1 align="center">
<a href="https://miniaud.io"><img src="https://miniaud.io/img/miniaudio_wide.png" alt="miniaudio" width="1280"></a>
<br>
</h1>
<h4 align="center">A single file library for audio playback and capture.</h4>
<p align="center">
<a href="https://discord.gg/9vpqbjU"><img src="https://img.shields.io/discord/712952679415939085?label=discord&logo=discord&style=flat-square" alt="discord"></a>
<a href="https://fosstodon.org/@mackron"><img src="https://img.shields.io/mastodon/follow/109293691403797709?color=blue&domain=https%3A%2F%2Ffosstodon.org&label=mastodon&logo=mastodon&style=flat-square" alt="mastodon"></a>
<a href="https://www.reddit.com/r/miniaudio"><img src="https://img.shields.io/reddit/subreddit-subscribers/miniaudio?label=r%2Fminiaudio&logo=reddit&style=flat-square" alt="reddit"></a>
</p>
<p align="center">
<a href="#examples">Examples</a> -
<a href="#documentation">Documentation</a> -
<a href="#supported-platforms">Supported Platforms</a> -
<a href="#backends">Backends</a> -
<a href="#major-features">Major Features</a> -
<a href="#building">Building</a>
</p>
Examples
========
This example shows one way to play a sound using the high level API.
```c
#define MINIAUDIO_IMPLEMENTATION
#include "../miniaudio.h"
#include <stdio.h>
int main(int argc, char** argv)
{
ma_result result;
ma_engine engine;
if (argc < 2) {
printf("No input file.");
return -1;
}
result = ma_engine_init(NULL, &engine);
if (result != MA_SUCCESS) {
printf("Failed to initialize audio engine.");
return -1;
}
ma_engine_play_sound(&engine, argv[1], 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
#define MINIAUDIO_IMPLEMENTATION
#include "../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/
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 authoritive source of information on how to use miniaudio. All other
documentation is generated from this in-code documentation.
Platforms and Backends
======================
<table style="margin:0 auto; text-align:center; width:75%; margin-top:2em; font-size:12pt;">
<tr>
<td style="width:20%; vertical-align:center; padding:1em;">
<img src="https://miniaud.io/img/platforms/windows/windows-10.svg" style="height:128px;">
</td>
<td style="width:20%; vertical-align:center; padding:1em;">
<img src="https://miniaud.io/img/platforms/apple/apple-black.svg" style="height:128px;">
</td>
<td style="width:20%; vertical-align:center; padding:1em;">
<img src="https://miniaud.io/img/platforms/linux/linux.svg" style="height:128px;">
</td>
<td style="width:20%; vertical-align:center; padding:1em;">
<img src="https://miniaud.io/img/platforms/bsd/freebsd.svg" style="height:128px;">
</td>
<td style="width:20%; vertical-align:center; padding:1em;">
<img src="https://miniaud.io/img/platforms/android/android.svg" style="height:100px;">
</td>
</tr>
<tr style="font-weight:bold;">
<td style="vertical-align:top; padding:0em; font-weight:bold;">
Windows
</td>
<td style="vertical-align:top; padding:0em;">
macOS / iOS
</td>
<td style=vertical-align:top; padding:0em;">
Linux
</td>
<td style="vertical-align:top; padding:0em;">
FreeBSD /
OpenBSD /
NetBSD
</td>
<td style="vertical-align:top; padding:0em;">
Android
</td>
</tr>
<tr>
<td style="vertical-align:top; padding-top:1em;">
WASAPI<br/>
DirectSound<br/>
WinMM
</td>
<td style="vertical-align:top; padding-top:1em;">
Core Audio
</td>
<td style="vertical-align:top; padding-top:1em;">
ALSA<br/>
PulseAudio<br/>
JACK
</td>
<td style="vertical-align:top; padding-top:1em;">
OSS<br/>
sndio<br/>
audio(4)
</td>
<td style="vertical-align:top; padding-top:1em;">
AAudio<br/>
OpenSL | ES
</td>
</tr>
<!-- PLATFORM ROW 2 -->
<tr>
<td style="width:20%; vertical-align:center; padding:1em; padding-top:2em;">
</td>
<td style="width:20%; vertical-align:center; padding:1em; padding-top:2em;">
</td>
<td style="width:20%; vertical-align:center; padding:1em; padding-top:4em;">
<img src="https://miniaud.io/img/platforms/web/html5.svg" style="height:128px;">
</td>
<td style="width:20%; vertical-align:center; padding:1em; padding-top:2em;">
</td>
<td style="width:20%; vertical-align:center; padding:1em; padding-top:2em;">
</td>
</tr>
<tr style="font-weight:bold;">
<td style="vertical-align:top; padding:0em; font-weight:bold;">
</td>
<td style="vertical-align:top; padding:0em;">
</td>
<td style=vertical-align:top; padding:0em;">
Web
</td>
<td style="vertical-align:top; padding:0em;">
</td>
<td style="vertical-align:top; padding:0em;">
</td>
</tr>
<tr>
<td style="vertical-align:top; padding-top:1em;">
</td>
<td style="vertical-align:top; padding-top:1em;">
</td>
<td style="vertical-align:top; padding-top:1em;">
Emscripten / WebAudio
</td>
<td style="vertical-align:top; padding-top:1em;">
</td>
<td style="vertical-align:top; padding-top:1em;">
</td>
</tr>
</table>
Supported Platforms
===================
- Windows, UWP
- macOS, iOS
- Linux
- BSD
- Android
- Raspberry Pi
- Emscripten / HTML5
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
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
Refer to the [Programming Manual](https://miniaud.io/docs/manual/) for a more complete description of
available features in miniaudio.
Building
========
Do the following in one source file:
```c
#define MINIAUDIO_IMPLEMENTATION
#include "miniaudio.h"
```
Then just compile. There's no need to install any dependencies. On Windows and macOS there's no need to link
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 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
single translation unit (AKA unity builds), you can just #include the .c file in your main source file:
```c
#include "miniaudio.c"
```
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"
```
Reference in New Issue View Git Blame Copy Permalink