diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 44 |
1 files changed, 30 insertions, 14 deletions
@@ -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 |