1 #include "aubio-types.h"
18 static char Py_source_doc[] = ""
19 "source(path, samplerate=0, hop_size=512, channels=0)\n"
21 "Read audio samples from a media file.\n"
23 "`source` open the file specified in `path` and creates a callable\n"
24 "returning `hop_size` new audio samples at each invocation.\n"
26 "If `samplerate=0` (default), the original sampling rate of `path`\n"
27 "will be used. Otherwise, the output audio samples will be\n"
28 "resampled at the desired sampling-rate.\n"
30 "If `channels=0` (default), the original number of channels\n"
31 "in `path` will be used. Otherwise, the output audio samples\n"
32 "will be down-mixed or up-mixed to the desired number of\n"
35 "If `path` is a URL, a remote connection will be attempted to\n"
36 "open the resource and stream data from it.\n"
38 "The parameter `hop_size` determines how many samples should be\n"
39 "read at each consecutive calls.\n"
44 " pathname (or URL) of the file to be opened for reading\n"
45 "samplerate : int, optional\n"
46 " sampling rate of the file\n"
47 "hop_size : int, optional\n"
48 " number of samples to be read per iteration\n"
49 "channels : int, optional\n"
50 " number of channels of the file\n"
54 "By default, when only `path` is given, the file will be opened\n"
55 "with its original sampling rate and channel:\n"
57 ">>> src = aubio.source('stereo.wav')\n"
58 ">>> src.uri, src.samplerate, src.channels, src.duration\n"
59 "('stereo.wav', 48000, 2, 86833)\n"
61 "A typical loop to read all samples from a local file could\n"
64 ">>> src = aubio.source('stereo.wav')\n"
65 ">>> total_read = 0\n"
67 "... samples, read = src()\n"
68 "... # do something with samples\n"
69 "... total_read += read\n"
70 "... if read < src.hop_size:\n"
74 "In a more Pythonic way, it can also look like this:\n"
76 ">>> total_read = 0\n"
77 ">>> with aubio.source('stereo.wav') as src:\n"
78 "... for frames in src:\n"
79 "... total_read += samples.shape[-1]\n"
82 ".. rubric:: Basic interface\n"
84 "`source` is a **callable**; its :meth:`__call__` method\n"
85 "returns a tuple containing:\n"
87 "- a vector of shape `(hop_size,)`, filled with the `read` next\n"
88 " samples available, zero-padded if `read < hop_size`\n"
89 "- `read`, an integer indicating the number of samples read\n"
91 "To read the first `hop_size` samples from the source, simply call\n"
92 "the instance itself, with no argument:\n"
94 ">>> src = aubio.source('song.ogg')\n"
95 ">>> samples, read = src()\n"
96 ">>> samples.shape, read, src.hop_size\n"
97 "((512,), 512, 512)\n"
99 "The first call returned the slice of samples `[0 : hop_size]`.\n"
100 "The next call will return samples `[hop_size: 2*hop_size]`.\n"
102 "After several invocations of :meth:`__call__`, when reaching the end\n"
103 "of the opened stream, `read` might become less than `hop_size`:\n"
105 ">>> samples, read = src()\n"
106 ">>> samples.shape, read\n"
109 "The end of the vector `samples` is filled with zeros.\n"
111 "After the end of the stream, `read` will be `0` since no more\n"
112 "samples are available:\n"
114 ">>> samples, read = src()\n"
115 ">>> samples.shape, read\n"
118 "**Note**: when the source has more than one channels, they\n"
119 "are be down-mixed to mono when invoking :meth:`__call__`.\n"
120 "To read from each individual channel, see :meth:`__next__`.\n"
122 ".. rubric:: ``for`` statements\n"
124 "The `source` objects are **iterables**. This allows using them\n"
125 "directly in a ``for`` loop, which calls :meth:`__next__` until\n"
126 "the end of the stream is reached:\n"
128 ">>> src = aubio.source('stereo.wav')\n"
129 ">>> for frames in src:\n"
130 ">>> print (frames.shape)\n"
136 "**Note**: When `next(self)` is called on a source with multiple\n"
137 "channels, an array of shape `(channels, read)` is returned,\n"
138 "unlike with :meth:`__call__` which always returns the down-mixed\n"
141 "If the file is opened with a single channel, `next(self)` returns\n"
142 "an array of shape `(read,)`:\n"
144 ">>> src = aubio.source('stereo.wav', channels=1)\n"
145 ">>> next(src).shape\n"
148 ".. rubric:: ``with`` statements\n"
150 "The `source` objects are **context managers**, which allows using\n"
151 "them in ``with`` statements:\n"
153 ">>> with aubio.source('audiotrack.wav') as source:\n"
155 "... for samples in source:\n"
156 "... n_frames += len(samples)\n"
157 "... print('read', n_frames, 'samples in', samples.shape[0], 'channels',\n"
158 "... 'from file \"%%s\"' %% source.uri)\n"
160 "read 239334 samples in 2 channels from file \"audiotrack.wav\"\n"
162 "The file will be closed before exiting the statement.\n"
164 "See also the methods implementing the context manager,\n"
165 ":meth:`__enter__` and :meth:`__exit__`.\n"
167 ".. rubric:: Seeking and closing\n"
169 "At any time, :meth:`seek` can be used to move to any position in\n"
170 "the file. For instance, to rewind to the start of the stream:\n"
174 "The opened file will be automatically closed when the object falls\n"
175 "out of scope and is scheduled for garbage collection.\n"
177 "In some cases, it is useful to manually :meth:`close` a given source,\n"
178 "for instance to limit the number of simultaneously opened files:\n"
182 ".. rubric:: Input formats\n"
184 "Depending on how aubio was compiled, :class:`source` may or may not\n"
185 "open certain **files format**. Below are some examples that assume\n"
186 "support for compressed files and remote urls was compiled in:\n"
188 "- open a local file using its original sampling rate and channels,\n"
189 " and with the default hop size:\n"
191 ">>> s = aubio.source('sample.wav')\n"
192 ">>> s.uri, s.samplerate, s.channels, s.hop_size\n"
193 "('sample.wav', 44100, 2, 512)\n"
195 "- open a local compressed audio file, resampling to 32000Hz if needed:\n"
197 ">>> s = aubio.source('song.mp3', samplerate=32000)\n"
198 ">>> s.uri, s.samplerate, s.channels, s.hop_size\n"
199 "('song.mp3', 32000, 2, 512)\n"
201 "- open a local video file, down-mixing and resampling it to 16kHz:\n"
203 ">>> s = aubio.source('movie.mp4', samplerate=16000, channels=1)\n"
204 ">>> s.uri, s.samplerate, s.channels, s.hop_size\n"
205 "('movie.mp4', 16000, 1, 512)\n"
207 "- open a remote resource, with hop_size = 1024:\n"
209 ">>> s = aubio.source('https://aubio.org/drum.ogg', hop_size=1024)\n"
210 ">>> s.uri, s.samplerate, s.channels, s.hop_size\n"
211 "('https://aubio.org/drum.ogg', 48000, 2, 1024)\n"
215 "sink: write audio samples to a file.\n"
218 static char Py_source_get_samplerate_doc[] = ""
221 "Get sampling rate of source.\n"
226 " Sampling rate, in Hz.\n"
229 static char Py_source_get_channels_doc[] = ""
232 "Get number of channels in source.\n"
237 " Number of channels.\n"
240 static char Py_source_do_doc[] = ""
243 "Read vector of audio samples.\n"
245 "If the audio stream in the source has more than one channel,\n"
246 "the channels will be down-mixed.\n"
250 "samples : numpy.ndarray\n"
251 " `fvec` of size `hop_size` containing the new samples.\n"
253 " Number of samples read from the source, equals to `hop_size`\n"
254 " before the end-of-file is reached, less when it is reached,\n"
263 ">>> src = aubio.source('sample.wav', hop_size=1024)\n"
265 "(array([-0.00123001, -0.00036685, 0.00097106, ..., -0.2031033 ,\n"
266 " -0.2025854 , -0.20221856], dtype=" AUBIO_NPY_SMPL_STR "), 1024)\n"
269 static char Py_source_do_multi_doc[] = ""
272 "Read multiple channels of audio samples.\n"
274 "If the source was opened with the same number of channels\n"
275 "found in the stream, each channel will be read individually.\n"
277 "If the source was opened with less channels than the number\n"
278 "of channels in the stream, only the first channels will be read.\n"
280 "If the source was opened with more channels than the number\n"
281 "of channel in the original stream, the first channels will\n"
282 "be duplicated on the additional output channel.\n"
286 "samples : numpy.ndarray\n"
287 " NumPy array of shape `(hop_size, channels)` containing the new\n"
290 " Number of samples read from the source, equals to `hop_size`\n"
291 " before the end-of-file is reached, less when it is reached,\n"
300 ">>> src = aubio.source('sample.wav')\n"
301 ">>> src.do_multi()\n"
302 "(array([[ 0.00668335, 0.0067749 , 0.00714111, ..., -0.05737305,\n"
303 " -0.05856323, -0.06018066],\n"
304 " [-0.00842285, -0.0072937 , -0.00576782, ..., -0.09405518,\n"
305 " -0.09558105, -0.09725952]], dtype=" AUBIO_NPY_SMPL_STR "), 512)\n"
308 static char Py_source_close_doc[] = ""
311 "Close this source now.\n"
313 ".. note:: Closing twice a source will **not** raise any exception.\n"
316 static char Py_source_seek_doc[] = ""
319 "Seek to position in file.\n"
321 "If the source was not opened with its original sampling-rate,\n"
322 "`position` corresponds to the position in the re-sampled file.\n"
327 " position to seek to, in samples\n"
331 Py_source_new (PyTypeObject * pytype, PyObject * args, PyObject * kwds)
335 uint_t samplerate = 0;
338 static char *kwlist[] = { "uri", "samplerate", "hop_size", "channels", NULL };
340 if (!PyArg_ParseTupleAndKeywords (args, kwds, "|sIII", kwlist,
341 &uri, &samplerate, &hop_size, &channels)) {
345 self = (Py_source *) pytype->tp_alloc (pytype, 0);
353 self->uri = (char_t *)malloc(sizeof(char_t) * (strnlen(uri, PATH_MAX) + 1));
354 strncpy(self->uri, uri, strnlen(uri, PATH_MAX) + 1);
357 self->samplerate = 0;
358 if ((sint_t)samplerate > 0) {
359 self->samplerate = samplerate;
360 } else if ((sint_t)samplerate < 0) {
361 PyErr_SetString (PyExc_ValueError,
362 "can not use negative value for samplerate");
366 self->hop_size = Py_default_vector_length / 2;
367 if ((sint_t)hop_size > 0) {
368 self->hop_size = hop_size;
369 } else if ((sint_t)hop_size < 0) {
370 PyErr_SetString (PyExc_ValueError,
371 "can not use negative value for hop_size");
376 if ((sint_t)channels >= 0) {
377 self->channels = channels;
378 } else if ((sint_t)channels < 0) {
379 PyErr_SetString (PyExc_ValueError,
380 "can not use negative value for channels");
384 return (PyObject *) self;
388 Py_source_init (Py_source * self, PyObject * args, PyObject * kwds)
390 self->o = new_aubio_source ( self->uri, self->samplerate, self->hop_size );
391 if (self->o == NULL) {
392 // PyErr_Format(PyExc_RuntimeError, ...) was set above by new_ which called
393 // AUBIO_ERR when failing
396 self->samplerate = aubio_source_get_samplerate ( self->o );
397 if (self->channels == 0) {
398 self->channels = aubio_source_get_channels ( self->o );
400 self->duration = aubio_source_get_duration ( self->o );
402 self->read_to = new_py_fvec(self->hop_size);
403 self->mread_to = new_py_fmat(self->channels, self->hop_size);
409 Py_source_del (Py_source *self, PyObject *unused)
412 del_aubio_source(self->o);
413 free(self->c_mread_to.data);
418 Py_XDECREF(self->read_to);
419 Py_XDECREF(self->mread_to);
420 Py_TYPE(self)->tp_free((PyObject *) self);
424 /* function Py_source_do */
426 Py_source_do(Py_source * self, PyObject * args)
432 Py_INCREF(self->read_to);
433 if (!PyAubio_ArrayToCFvec(self->read_to, &(self->c_read_to))) {
436 /* compute _do function */
437 aubio_source_do (self->o, &(self->c_read_to), &read);
439 outputs = PyTuple_New(2);
440 PyTuple_SetItem( outputs, 0, self->read_to );
441 PyTuple_SetItem( outputs, 1, (PyObject *)PyLong_FromLong(read));
445 /* function Py_source_do_multi */
447 Py_source_do_multi(Py_source * self, PyObject * args)
453 Py_INCREF(self->mread_to);
454 if (!PyAubio_ArrayToCFmat(self->mread_to, &(self->c_mread_to))) {
457 /* compute _do function */
458 aubio_source_do_multi (self->o, &(self->c_mread_to), &read);
460 outputs = PyTuple_New(2);
461 PyTuple_SetItem( outputs, 0, self->mread_to);
462 PyTuple_SetItem( outputs, 1, (PyObject *)PyLong_FromLong(read));
466 static PyMemberDef Py_source_members[] = {
467 {"uri", T_STRING, offsetof (Py_source, uri), READONLY,
468 "str (read-only): pathname or URL"},
469 {"samplerate", T_INT, offsetof (Py_source, samplerate), READONLY,
470 "int (read-only): sampling rate"},
471 {"channels", T_INT, offsetof (Py_source, channels), READONLY,
472 "int (read-only): number of channels"},
473 {"hop_size", T_INT, offsetof (Py_source, hop_size), READONLY,
474 "int (read-only): number of samples read per iteration"},
475 {"duration", T_INT, offsetof (Py_source, duration), READONLY,
476 "int (read-only): total number of frames in the source\n"
478 "Can be estimated, for instance if the opened stream is\n"
479 "a compressed media or a remote resource.\n"
484 ">>> src = aubio.source('track1.mp3')\n"
485 ">>> for samples in src:\n"
486 "... n += samples.shape[-1]\n"
488 ">>> n, src.duration\n"
489 "(9638784, 9616561)\n"
495 Pyaubio_source_get_samplerate (Py_source *self, PyObject *unused)
497 uint_t tmp = aubio_source_get_samplerate (self->o);
498 return (PyObject *)PyLong_FromLong (tmp);
502 Pyaubio_source_get_channels (Py_source *self, PyObject *unused)
504 uint_t tmp = aubio_source_get_channels (self->o);
505 return (PyObject *)PyLong_FromLong (tmp);
509 Pyaubio_source_close (Py_source *self, PyObject *unused)
511 if (aubio_source_close(self->o) != 0) return NULL;
516 Pyaubio_source_seek (Py_source *self, PyObject *args)
521 if (!PyArg_ParseTuple (args, "I", &position)) {
526 PyErr_Format(PyExc_ValueError,
527 "error when seeking in source: can not seek to negative value %d",
532 err = aubio_source_seek(self->o, position);
534 PyErr_SetString (PyExc_ValueError,
535 "error when seeking in source");
541 static char Pyaubio_source_enter_doc[] = "";
542 static PyObject* Pyaubio_source_enter(Py_source *self, PyObject *unused) {
544 return (PyObject*)self;
547 static char Pyaubio_source_exit_doc[] = "";
548 static PyObject* Pyaubio_source_exit(Py_source *self, PyObject *unused) {
549 return Pyaubio_source_close(self, unused);
552 static PyObject* Pyaubio_source_iter(PyObject *self) {
554 return (PyObject*)self;
557 static PyObject* Pyaubio_source_iter_next(Py_source *self) {
558 PyObject *done, *size;
559 if (self->channels == 1) {
560 done = Py_source_do(self, NULL);
562 done = Py_source_do_multi(self, NULL);
564 if (!PyTuple_Check(done)) {
565 PyErr_Format(PyExc_ValueError,
566 "error when reading source: not opened?");
569 size = PyTuple_GetItem(done, 1);
570 if (size != NULL && PyLong_Check(size)) {
571 if (PyLong_AsLong(size) == (long)self->hop_size) {
572 PyObject *vec = PyTuple_GetItem(done, 0);
574 } else if (PyLong_AsLong(size) > 0) {
575 // short read, return a shorter array
576 PyArrayObject *shortread = (PyArrayObject*)
577 PyArray_FROM_OTF(PyTuple_GetItem(done, 0), NPY_NOTYPE,
578 NPY_ARRAY_ENSURECOPY);
579 PyArray_Dims newdims;
581 newdims.len = PyArray_NDIM(shortread);
582 newdims.ptr = PyArray_DIMS(shortread);
583 // mono or multiple channels?
584 if (newdims.len == 1) {
585 newdims.ptr[0] = PyLong_AsLong(size);
587 newdims.ptr[1] = PyLong_AsLong(size);
589 reshaped = PyArray_Newshape(shortread, &newdims, NPY_CORDER);
590 Py_DECREF(shortread);
593 PyErr_SetNone(PyExc_StopIteration);
597 PyErr_SetNone(PyExc_StopIteration);
602 static PyMethodDef Py_source_methods[] = {
603 {"get_samplerate", (PyCFunction) Pyaubio_source_get_samplerate,
604 METH_NOARGS, Py_source_get_samplerate_doc},
605 {"get_channels", (PyCFunction) Pyaubio_source_get_channels,
606 METH_NOARGS, Py_source_get_channels_doc},
607 {"do", (PyCFunction) Py_source_do,
608 METH_NOARGS, Py_source_do_doc},
609 {"do_multi", (PyCFunction) Py_source_do_multi,
610 METH_NOARGS, Py_source_do_multi_doc},
611 {"close", (PyCFunction) Pyaubio_source_close,
612 METH_NOARGS, Py_source_close_doc},
613 {"seek", (PyCFunction) Pyaubio_source_seek,
614 METH_VARARGS, Py_source_seek_doc},
615 {"__enter__", (PyCFunction)Pyaubio_source_enter, METH_NOARGS,
616 Pyaubio_source_enter_doc},
617 {"__exit__", (PyCFunction)Pyaubio_source_exit, METH_VARARGS,
618 Pyaubio_source_exit_doc},
619 {NULL} /* sentinel */
622 PyTypeObject Py_sourceType = {
623 PyVarObject_HEAD_INIT (NULL, 0)
627 (destructor) Py_source_del,
637 (ternaryfunc)Py_source_do,
649 (unaryfunc)Pyaubio_source_iter_next,
658 (initproc) Py_source_init,