mossrose
========

> *Portulaca grandiflora*

A minimal-dependency PortAudio-based audio mixer library.


api
---

### `mossrose_sound_t` ###

This structure encompasses loaded sounds in mossrose. It has the following 
attributes:

  * `float *left` - pointer to the left audio channel, or the mono channel for 
     mono sounds.
  * `float *right` - pointer to the right audio channel, or NULL for mono sounds.
  * `bool mono` - `true` if the sound is mono, `false` if it is stereo.
  * `size_t len` - the number of samples in each channel.


### `int mossrose_init(double sample_rate, int n_channels, bool init_plibsys)` ###

Initialize mossrose. 

  * `sample_rate` - samples per second to open the audio device with. Make 
     sure your audio files use the same sample rate!
  * `n_channels` - the maximum number of sounds that can be played simultaneously.
  * `init_plibsys` - `true` if mossrose should initialize plibsys. Set to
    `false` only if you are using plibsys elsewhere and initializing it separately.

Returns 0 on success and an error code otherwise.


### `int mossrose_terminate()` ###

Terminate mossrose.


### `int mossrose_play(struct mossrose_sound_t *sound, int channel, int loops)` ###

Play a sound.

  * `sound` - pointer to a `struct mossrose_sound_t` struct containing the 
     audio data.
  * `channel` - optionally request a specific channel to play the sound on. If 
     `channel` is negative, the first available channel will be used; otherwise,
     the specified channel will be used.
  * `loops` - the number of times to play the audio. 1 will play once, 2 will 
     play twice, et cetera. 0 loops forever.

On a successful call, the audio data will be copied into the channel and so 
any user-allocated buffers can be freed.

When no specific channel is selected, default volume (1.0) and panning (left:
-1.0, right: 1.0) are used to play the sound. If a specific channel is 
requested, that channel's pre-set volume and panning are used instead. Pause, 
however, is always false.

If no channel was specified and no channels are currently available to play, 
the call will fail.

Returns the index of the channel used to play the sound on success, or a 
negative value on failure.


### `void mossrose_channel_set_volume(int channel, float volume)` ###

Set the volume of a channel.

  * `channel` - the index of the channel, usually as returned by `mossrose_play`.
  * `volume` - a value between 0 and 1. Values outside this range are clamped 
     to [0,1].


### `void mossrose_channel_set_pan(int channel, float left, float right)` ###

Set the panning of a channel.

  * `channel` - the index of the channel.
  * `left` - panning for the left channel, or, for mono channels, the pan.
  * `right` - panning for the right channel. Ignored for mono channels.

Pan values must be in the range [-1,1] and values outside this range are 
clamped to it. -1 represents full left, 0 is center, and 1 is full right.

mossrose uses trigonometric constant-power panning.


### `void mossrose_channel_pause(int channel)` ###

Pause a channel.

  * `channel` - the index of the channel.

This function has no effect if the channel is already paused.


### `void mossrose_channel_resume(int channel)` ###

Resume a channel.

  * `channel` - the index of the channel.

This function has no effect if the channel is already playing.


todo
----

  * playback finished callback
  * audio loading