summaryrefslogtreecommitdiff
path: root/README.md
diff options
context:
space:
mode:
Diffstat (limited to 'README.md')
-rw-r--r--README.md44
1 files changed, 30 insertions, 14 deletions
diff --git a/README.md b/README.md
index 0165733..de38d9e 100644
--- a/README.md
+++ b/README.md
@@ -11,9 +11,11 @@ api
### `mossrose_sound_t` ###
-This structure encompasses loaded sounds in mossrose. It has the following attributes:
+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 *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.
@@ -23,9 +25,11 @@ This structure encompasses loaded sounds in mossrose. It has the following attri
Initialize mossrose.
- * `sample_rate` - samples per second to open the audio device with. Make sure your audio files use the same sample rate!
+ * `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.
+ * `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.
@@ -35,20 +39,31 @@ Returns 0 on success and an error code otherwise.
Terminate mossrose.
-### `int mossrose_play(struct mossrose_sound_t *sound, int channel)` ###
+### `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.
+ * `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.
+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.
+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.
+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.
+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)` ###
@@ -56,7 +71,8 @@ Returns the index of the channel used to play the sound on success, or a negativ
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].
+ * `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)` ###
@@ -67,7 +83,8 @@ Set the panning of a 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.
+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.
@@ -93,6 +110,5 @@ This function has no effect if the channel is already playing.
todo
----
- * loop audio
* playback finished callback
* audio loading