mirror/miniaudio
1
0
Fork 0
mirror of https://github.com/mackron/miniaudio.git synced 2026-04-21 15:56:58 +02:00
Code Issues Packages Projects Releases Wiki Activity

Another update to the readme to make it less wordy.

Browse Source
This commit is contained in:
David Reid
2023-04-30 12:03:26 +10:00
parent d1f3715a08
commit 937cd9c16c
1 changed files with 49 additions and 115 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+49 -115
View File
@@ -20,22 +20,26 @@
<a href="#building">Building</a> <a href="#building">Building</a>
</p> </p>
miniaudio is a C library (compilable as C++) with a simple API and build system. It has no dependencies and miniaudio is written in C with no dependencies except the standard library and should compile clean on all major
should compile cleanly on all major compilers. You can add the source file directly to your source tree compilers without the need to install any additional development packages. All major desktop and mobile platforms
without needing to install any additional development packages. See the <a href="#building">Building</a> are supported.
section for more details.
All major platforms are supported, and where applicable, each platform has support for multiple backends so
that the best backend can be used when available.
miniaudio is primarily concerned with audio playback and capture. The low-level API is a simple connection Features
to a physical device with a callback used for delivery of raw audio data. Built on top of the low-level API ========
is an optional high-level API which is highly flexible and usable for most scenarios. - Simple build system with no external dependencies.
- Simple and flexible API.
Included in miniaudio is a suite of functionality not directly related to playback and capture, but highly - Low-level API for direct access to raw audio data.
useful for a creating a complete audio solution. Such functionality includes a node graph for advanced mixing - High-level API for sound management, mixing, effects and optional 3D spatialization.
and effect processing, resource management, decoding, resampling, format conversion, and more. You can piece - Flexible node graph system for advanced mixing and effect processing.
these together to help you develop your audio solution. - 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 Refer to the [Programming Manual](https://miniaud.io/docs/manual/) for a more complete description of
available features in miniaudio. available features in miniaudio.
@@ -48,27 +52,21 @@ This example shows one way to play a sound using the high level API.
```c ```c
#define MINIAUDIO_IMPLEMENTATION #define MINIAUDIO_IMPLEMENTATION
#include "../miniaudio.h" #include "miniaudio.h"
#include <stdio.h> #include <stdio.h>
int main(int argc, char** argv) int main()
{ {
ma_result result; ma_result result;
ma_engine engine; ma_engine engine;
if (argc < 2) {
printf("No input file.");
return -1;
}
result = ma_engine_init(NULL, &engine); result = ma_engine_init(NULL, &engine);
if (result != MA_SUCCESS) { if (result != MA_SUCCESS) {
printf("Failed to initialize audio engine.");
return -1; return -1;
} }
ma_engine_play_sound(&engine, argv[1], NULL); ma_engine_play_sound(&engine, "sound.wav", NULL);
printf("Press Enter to quit..."); printf("Press Enter to quit...");
getchar(); getchar();
@@ -83,7 +81,7 @@ This example shows how to decode and play a sound using the low level API.
```c ```c
#define MINIAUDIO_IMPLEMENTATION #define MINIAUDIO_IMPLEMENTATION
#include "../miniaudio.h" #include "miniaudio.h"
#include <stdio.h> #include <stdio.h>
@@ -149,6 +147,33 @@ int main(int argc, char** argv)
More examples can be found in the [examples](examples) folder or online here: https://miniaud.io/docs/examples/ More examples can be found in the [examples](examples) folder or online here: https://miniaud.io/docs/examples/
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 get errors about undefined references to `__sync_val_compare_and_swap_8`, `__atomic_load_8`, etc. you
need to link with `-latomic`.
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.
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.
Documentation Documentation
============= =============
@@ -193,97 +218,6 @@ Backends
- Custom - Custom
Major Features
==============
Low-Level API
-------------
The low-level API is a lightweight API for doing processing of raw audio data straight to/from the underlying
device. You can connect to multiple devices at once, and can choose specific devices to connect to rather than
being forced to use system defaults. You can do playback, capture and full-duplex. The WASAPI backend can also
do loopback.
miniaudio also exposes backend-specific configuration options for when you need finer control over platform-
specific settings.
High-Level API
--------------
The high-level audio engine in miniaudio encapsulates the resource manager and node graph to give you an easy to
use API to manage sounds. The engine is a node graph, and each sound is a node within that graph which means you
can take advantage of miniaudio's graph based effect processing and routing infrastructure.
Sounds support 3D spatialization and can be pluged into effect nodes if you need to apply an effect. You can
also group sounds for when you need to apply volume control or an effect on a group of sounds.
Advanced Mixing and Effect Processing
-------------------------------------
miniaudio includes a node graph system for doing mixing and effect processing. The output of each node is
connected to an input of another node. When the outputs of multiple nodes are connected to the same input node,
they will be mixed before being processed by the input node.
You can implement custom nodes for doing your own effect processing. miniaudio has some basic nodes built-in, but
there are some additional nodes in the extras folder in the miniaudio repository.
Resource Management
-------------------
The resource manager is used for simplifying the hassle of dealing with the loading and management of your audio
resources. It will reference count files so they're only loaded once and handles streaming of large audio sources
to save on memory. It can even load files asynchronously and exposes it's job system so you can handle resource
management jobs from your existing job infrastructure.
Flexible and Modular API
------------------------
miniaudio have a very flexible and highly decoupled API. The high-level API is built on top of the low-level
API but can even be used without it. For example, if you want to use a different library for handling playback,
such as SDL, you can configure miniaudio to bypass it's low-level API completely so you can plug it into SDL
instead.
This modularity extends to all parts of miniaudio, such as the resource manager, node graph, decoders and more.
You can use these as completely independant units for constructing your audio solution.
And More
--------
- 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.
- 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.
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 get errors about undefined references to `__sync_val_compare_and_swap_8`, `__atomic_load_8`, etc. you
need to link with `-latomic`.
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.
License License
======= =======
Your choice of either public domain or [MIT No Attribution](https://github.com/aws/mit-0). Your choice of either public domain or [MIT No Attribution](https://github.com/aws/mit-0).