summaryrefslogtreecommitdiff
path: root/README.md
diff options
context:
space:
mode:
authorsanine <sanine.not@pm.me>2022-09-03 11:09:37 -0500
committersanine <sanine.not@pm.me>2022-09-03 11:09:37 -0500
commit04d2f4e4d5a18be4473537e95bdf8c14c5c37886 (patch)
tree8afd7ea7af967b22e6a53de5fce133070f6e9a4c /README.md
parent10a652728f2bc8e5f01aedf97ccc849b8ac686ba (diff)
update README.md with better api documentation
Diffstat (limited to 'README.md')
-rw-r--r--README.md78
1 files changed, 71 insertions, 7 deletions
diff --git a/README.md b/README.md
index 38207f1..da41c49 100644
--- a/README.md
+++ b/README.md
@@ -9,18 +9,82 @@ A minimal-dependency PortAudio-based audio mixer library. It doesn't *load* audi
api
---
-### `int mr_init(double sample_rate, int n_channels)` ###
+### `mossrose_sound_t` ###
-Initialize mossrose with `n_channels` worth of audio, at `sample_rate` Hz. Returns 0 on success and 1 otherwise.
+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 mr_terminate()` ###
+
+### `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 mr_play(float *left, float *right, size_t n_samples, int channel)` ###
+### `int mossrose_play(struct mossrose_sound_t *sound, int channel)` ###
+
+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.
+
+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.
-Play a sound. Either `left` or `right` may be NULL, but not both. If `channel` is non-negative,
-it will use that channel; otherwise, it will use the first available free channel. Returns the
-channel used on success, or -1 on failure.
+This function has no effect if the channel is already playing.