# Introduction

SoLoud is an easy to use, free, portable c/c++ audio engine for games.

#### How Easy?

The engine has been designed to make simple things easy, while not
making harder things impossible. Here's a code snippet that initializes
the library, loads a sample and plays it:

    // Declare some variables
    SoLoud::Soloud soloud; // Engine core
    SoLoud::Wav sample;    // One sample

    // Initialize SoLoud (automatic back-end selection)
    soloud.init();

    sample.load("pew_pew.wav"); // Load a wave file
    soloud.play(sample);        // Play it

The primary form of use the interface is designed for is "fire and
forget" audio. In many games, most of the time you don't need to modify
a sound's parameters on the fly - you just find an event, like an
explosion, and trigger a sound effect. SoLoud handles the rest.

If you need to alter some aspect of the sound after the fact, the "play"
function returns a handle you can use. For example:

    int handle = soloud.play(sample);         // Play the sound
    soloud.setVolume(handle, 0.5f);           // Set volume; 1.0f is "normal"
    soloud.setPan(handle, -0.2f);             // Set pan; -1 is left, 1 is right
    soloud.setRelativePlaySpeed(handle, 0.9f);// Play a bit slower; 1.0f is normal

If the sound doesn't exist anymore (either it's ended or you've played
so many sounds at once it's channel has been taken over by some other
sound), the handle is still safe to use - it just doesn't do anything.

There's also a pure "C" version of the whole API which can even be used 
from non-c languages by using SoLoud as an DLL, such as Python.

#### How Free?

SoLoud is released under the ZLib/LibPNG license. That means, among 
other things, that:

- You can use it in free or commercial applications as much as you want. 
- You can modify it. (But you don't need to).
- You don't need to give the changes back. (But you can).
- You don't need to release the source code. (But you can).
- You don't need to add a splash screen. (But you can).
- You don't need to mention it in your printed manual. (But you can).

Basically the only things the license forbids are suing the authors, or 
claiming that you made SoLoud. If you redistribute the source code, the 
license needs to be there. But not with the binaries.

Parts of the SoLoud package were not made by me, and those either have a
similar license, or more permissive (such as Unlicense, CC0, WTFPL or
Public Domain).



#### How Powerful?

While SoLoud's usage has been designed to be very easy, it's still packed
with powerful functionality. Some of the features include:

\pagebreak

- Multiple voices, playing different or even the same sound multiple times on top of each other.
- Adjustable play speed, volume and pan.
- Faders for all of the attributes (fade out for 2 seconds, then stop, for instance).
- Filter interface and ready filters for low/high pass, echo, etc for real-time modification of audio.
- Mixing busses for grouping of audio into different uses and adjusting their attributes in one go.
- Gapless looping.
- Queued sounds.
- Playing several ogg streams at once.
- Atomic operations for several sounds.
- "Clocked" playing for rapid sound effects.
- Sound effects synthesizer.
- Speech synthesizer.
- Support for various common formats like 8, 16, 32 bit wavs, floating point wavs, ogg, mp3.
- Up to 8 surround speaker support, easily extendable.
- 3d positional audio.
- Foreign interface support for python, ruby (and RPG maker), blitzmax, c# and more.
- Exotic formats like MONOTONE, SID and TED songs.
- Works with Emscripten.
- Virtual voices.
- Easy cleanup.

#### There's a Catch, Right?

SoLoud quite probably doesn't have all the features you'd find in a
commercial library like FMOD or WWISE. There's no artist tools, and
only limited engine integration. 

It quite probably isn't as fast. As of this writing, it has limited
specialized SSE optimizations. It contains no hand-written assembly.

It definitely doesn't come with the support you get from a commercial
library.

While software using SoLoud has already shipped on all current-gen
consoles (as of 2018), the backends needed for those are not included
with SoLoud due to SDK license issues. New backends are easy to write,
however. 

If you're planning to make a multi-million budgeted console game, this
library is (probably) not for you. Feel free to try it though :-)

Apparently it did ship as part of SNES Mini..
