1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
|
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.
### `void mossrose_channel_stop(int channel)` ###
Stop a channel.
* `channel` - the index of the channel.
Stopped channels cannot be resumed and are made available for new samples to
be loaded into them.
### `void mossrose_channel_set_callback(int channel, mossrose_channel_callback_t callback, void *userdata)` ###
Set a callback to run each time playback of audio on a channel completes.
* `channel` - the channel to attach to
* `callback` - pointer to the callback function.
* `userdata` - pointer to data to pass to the callback function.
The callback function should return `void` and have signature `(int channel,
void *userdata)`, where
* `channel` is the index of the channel triggering the callback
* `userdata` is the user data bound to the callback via the `userdata`
argument to the setter function.
Callbacks will not be triggered on their own! You must periodically call
`mossrose_poll_callbacks` to trigger them.
### `void mossrose_poll_callbacks()` ###
Check all channels for playback-finished callbacks and run them if necessary.
todo
----
* audio loading
|
