source: src/synth/sampler.h @ f651625

sampler
Last change on this file since f651625 was f651625, checked in by Paul Brossier <piem@piem.org>, 2 years ago

src/synth/sampler.h: improve documentation

  • Property mode set to 100644
File size: 7.6 KB
Line 
1/*
2  Copyright (C) 2003-2013 Paul Brossier <piem@aubio.org>
3
4  This file is part of aubio.
5
6  aubio is free software: you can redistribute it and/or modify
7  it under the terms of the GNU General Public License as published by
8  the Free Software Foundation, either version 3 of the License, or
9  (at your option) any later version.
10
11  aubio is distributed in the hope that it will be useful,
12  but WITHOUT ANY WARRANTY; without even the implied warranty of
13  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
14  GNU General Public License for more details.
15
16  You should have received a copy of the GNU General Public License
17  along with aubio.  If not, see <http://www.gnu.org/licenses/>.
18
19*/
20
21#ifndef AUBIO_SAMPLER_H
22#define AUBIO_SAMPLER_H
23
24/** \file
25
26  Load and play a sound file.
27
28  This file loads a sample and gets ready to play it.
29
30  The `_do` function adds the new samples to the input, and write the result as
31  the output.
32
33TODO:
34  - add _preset_threaded(level)
35  - rename _set_loop/_get_loop to _set_looping/_get_looping
36  - add option to pass a callback to signal eof
37
38  \example synth/test-sampler.c
39
40*/
41
42#ifdef __cplusplus
43extern "C" {
44#endif
45
46/** sampler object */
47typedef struct _aubio_sampler_t aubio_sampler_t;
48
49/** create new sampler object
50
51  \param samplerate the sampling rate of the new sampler
52  \param hop_size the block size of the new sampler
53
54  \return the newly created ::aubio_sampler_t
55
56*/
57aubio_sampler_t * new_aubio_sampler(uint_t hop_size, uint_t samplerate);
58
59/** load source in sampler
60
61  \param o sampler, created by new_aubio_sampler()
62  \param uri the uri of the source to load
63
64  \return 0 if successful, non-zero otherwise
65
66  This function attempts to load a new source, swaps the current one with the
67  newly loaded one (or NULL if loading failed), then delete the old one.
68
69*/
70uint_t aubio_sampler_load( aubio_sampler_t * o, const char_t * uri );
71
72/** queue source in sampler
73
74  \param o sampler, created by new_aubio_sampler()
75  \param uri the uri of the source to load
76
77  \return 0 if successfully queued, non-zero otherwise
78
79  This function is identical to aubio_sampler_load(), except it will be called
80  in its own thread to avoid blocking calls to aubio_sampler_do().
81
82*/
83uint_t aubio_sampler_queue(aubio_sampler_t * o, const char_t * uri );
84
85/** set array to read from
86
87  \param o sampler, created by new_aubio_sampler()
88  \param samples the vector to set the table to
89
90  \return 0 if successfully set, non-zero otherwise
91
92*/
93uint_t aubio_sampler_set_table(aubio_sampler_t *o, fvec_t *samples);
94
95/** process sampler function
96
97  \param o sampler, created by new_aubio_sampler()
98  \param output output of the sampler
99  \param read will be set to then number of samples actually read
100
101  This function get new samples from the sampler and store them into output.
102
103  The output vector will be completed with 0 if too few samples are available.
104
105*/
106void aubio_sampler_do ( aubio_sampler_t * o, fvec_t * output, uint_t *read);
107
108/** process sampler function, multiple channels
109
110  \param o sampler, created by new_aubio_sampler()
111  \param output output of the sampler
112  \param read will be set to the number of samples actually read
113
114  This function is identical to aubio_sampler_do(), but for a multi-channel source.
115
116*/
117void aubio_sampler_do_multi ( aubio_sampler_t * o, fmat_t * output, uint_t *read);
118
119/** get current playing state
120
121  \param o sampler, created by new_aubio_sampler()
122
123  \return 0 if not playing, 1 if playing
124
125*/
126uint_t aubio_sampler_get_playing ( const aubio_sampler_t * o );
127
128/** set current playing state
129
130  \param o sampler, created by new_aubio_sampler()
131  \param playing 0 for not playing, 1 for playing
132
133  \return 0 if successful, 1 otherwise
134
135*/
136uint_t aubio_sampler_set_playing ( aubio_sampler_t * o, uint_t playing );
137
138/** get current looping state
139
140  \param o sampler, created by new_aubio_sampler()
141
142  \return 0 if not looping , 1 if looping
143
144*/
145uint_t aubio_sampler_get_loop(aubio_sampler_t * o);
146
147/** set current looping state
148
149  \param o sampler, created by new_aubio_sampler()
150  \param loop 0 for not looping, 1 for looping
151
152  \return 0 if successful, 1 otherwise
153
154*/
155uint_t aubio_sampler_set_loop(aubio_sampler_t * o, uint_t loop);
156
157/** play sample
158
159  \param o sampler, created by new_aubio_sampler()
160
161  \return 0 if successful, 1 otherwise
162
163*/
164uint_t aubio_sampler_play ( aubio_sampler_t * o );
165
166/** play sample from start, looping it
167
168  \param o sampler, created by new_aubio_sampler()
169
170  \return 0 if successful, 1 otherwise
171
172*/
173uint_t aubio_sampler_loop ( aubio_sampler_t * o );
174
175/** play sample from start, once
176
177  \param o sampler, created by new_aubio_sampler()
178
179  \return 0 if successful, 1 otherwise
180
181*/
182uint_t aubio_sampler_trigger ( aubio_sampler_t * o );
183
184/** stop sample
185
186  \param o sampler, created by new_aubio_sampler()
187
188  \return 0 if successful, 1 otherwise
189
190*/
191uint_t aubio_sampler_stop ( aubio_sampler_t * o );
192
193/** get end-of-file status
194
195  \param o sampler, created by new_aubio_sampler()
196
197  \return 1 when the eof is being reached, 0 otherwise
198
199*/
200uint_t aubio_sampler_get_eof(aubio_sampler_t * o);
201
202/** get end-of-file status
203
204  \param o sampler, created by new_aubio_sampler()
205
206  \return 1 when end of file has been reached, 0 otherwise
207
208*/
209uint_t aubio_sampler_get_finished (aubio_sampler_t * o);
210
211/** get samplerate
212
213  \param o sampler, created by new_aubio_sampler()
214
215  \return samplerate of the sampler
216
217*/
218uint_t aubio_sampler_get_samplerate(aubio_sampler_t * o);
219
220/** get the number of samples that were set to zero while opening a file
221
222  \param o sampler, created by new_aubio_sampler()
223  \param waited the number of frames processed during this block
224
225  \return the total delay in samples when the file was successfuly opened, 0
226  otherwise
227
228*/
229uint_t aubio_sampler_get_waited_opening(aubio_sampler_t * o, uint_t waited);
230
231/** get current time stretching factor
232
233  \param o sampler, created by new_aubio_sampler()
234
235  \return the current time stretch factor
236
237 */
238smpl_t aubio_sampler_get_stretch (aubio_sampler_t *o);
239
240/** set current time stretching factor
241
242  \param o sampler, created by new_aubio_sampler()
243  \param stretch new time stretching factor
244
245  \return AUBIO_OK on success, AUBIO_FAIL otherwise
246
247 */
248uint_t aubio_sampler_set_stretch (aubio_sampler_t *o, smpl_t stretch);
249
250/** get current pitch shifting factor
251
252  \param o sampler, created by new_aubio_sampler()
253
254  \return the current pitch transposition factor
255
256 */
257smpl_t aubio_sampler_get_transpose (aubio_sampler_t *o);
258
259/** set current pitch shifting factor
260
261  \param o sampler, created by new_aubio_sampler()
262  \param transpose new pitch shifting (transposition) factor
263
264  \return AUBIO_OK on success, AUBIO_FAIL otherwise
265
266 */
267uint_t aubio_sampler_set_transpose (aubio_sampler_t *o, smpl_t transpose);
268
269/** get the current perfect loop mode
270
271  \param o sampler, created by new_aubio_sampler()
272
273  \return the total delay in samples when the file was successfuly opened, 0
274  otherwise
275
276*/
277uint_t aubio_sampler_get_perfectloop (aubio_sampler_t *o);
278
279/** set the perfect loop mode
280
281  \param o sampler, created by new_aubio_sampler()
282  \param perfectloop 1 to set perfect loop mode, 0 to turn it of
283
284  \return AUBIO_OK on success, AUBIO_FAIL otherwise
285
286 */
287uint_t aubio_sampler_set_perfectloop (aubio_sampler_t *o, uint_t perfectloop);
288
289/** seek to position
290
291  \param o sampler, created by new_aubio_sampler()
292  \param pos position to seek to, in samples
293
294  \return 0 if successful, 1 otherwise
295
296*/
297uint_t aubio_sampler_seek(aubio_sampler_t * o, uint_t pos);
298
299/** destroy ::aubio_sampler_t object
300
301  \param o sampler, created by new_aubio_sampler()
302
303*/
304void del_aubio_sampler( aubio_sampler_t * o );
305
306#ifdef __cplusplus
307}
308#endif
309
310#endif /* AUBIO_SAMPLER_H */
Note: See TracBrowser for help on using the repository browser.