Playing around with a restructure to the readme.

README.md

@@ -3,7 +3,7 @@
     <br>
 </h1>
 
-<h4 align="center">A single file library for audio playback and capture.</h4>
+<h4 align="center">An audio playback and capture library in a single source file.</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>
@@ -20,6 +20,27 @@
     <a href="#building">Building</a>
 </p>
 
+miniaudio is a C library (compilable as C++) with a simple API and build system. It has no dependencies and
+should compile cleanly on all major compilers. You can add the source file directly to your source tree
+without needing to install any additional development packages. See the <a href="#building">Building</a>
+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
+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.
+
+Included in miniaudio is a suite of functionality not directly related to playback and capture, but highly
+useful for a creating a complete audio solution. Such functionality includes a node graph for advanced mixing
+and effect processing, resource management, decoding, resampling, format conversion, and more. You can piece
+these together to help you develop your audio solution.
+
+Refer to the [Programming Manual](https://miniaud.io/docs/manual/) for a more complete description of
+available features in miniaudio.
+
+
 Examples
 ========
 
@@ -128,6 +149,7 @@ int main(int argc, char** argv)
 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/
@@ -139,14 +161,18 @@ documentation is generated from this in-code documentation.
 
 Supported Platforms
 ===================
-- Windows, UWP
+- Windows
 - macOS, iOS
 - Linux
-- BSD
+- FreeBSD / OpenBSD / NetBSD
 - Android
 - Raspberry Pi
 - Emscripten / HTML5
 
+miniaudio should compile clean on other platforms, but it will not include any support for playback or capture
+by default. To support that, you would need to implement a custom backend. You can do this without needing to
+modify the miniaudio source code. See the [custom_backend](examples/custom_backend.c) example.
+
 
 Backends
 ========
@@ -169,39 +195,65 @@ Backends
 
 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
+
+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.
@@ -218,6 +270,9 @@ Then just compile. There's no need to install any dependencies. On Windows and m
 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
@@ -228,19 +283,7 @@ single translation unit (AKA unity builds), you can just #include the .c file in
 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"
-```
+License
+=======
+Your choice of either public domain or [MIT No Attribution](https://github.com/aws/mit-0).