doc/py_io.rst

   1 .. currentmodule:: aubio
   2 .. default-domain:: py
   3
   4 Input/Output
   5 ------------
   6
   7 This section contains the documentation for two classes:
   8 :class:`source`, to read audio samples from files, and :class:`sink`,
   9 to write audio samples to disk.
  10
  11 .. defined in `python/ext`
  12
  13 ..
  14    Note: __call__ docstrings of objects defined in C must be written
  15    specifically in RST, since there is no known way to add them to
  16    their C implementation.
  17
  18 ..
  19    TODO: remove special-members documentation
  20
  21 .. defined in py-source.c
  22
  23 .. autoclass:: source
  24   :members:
  25   :special-members: __enter__
  26   :no-special-members:
  27
  28   .. function:: __call__()
  29
  30     Read at most `hop_size` new samples from self, return them in
  31     a tuple with the number of samples actually read.
  32
  33     The returned tuple contains:
  34
  35     - a vector of shape `(hop_size,)`, filled with the `read` next
  36       samples available, zero-padded if `read < hop_size`
  37     - `read`, an integer indicating the number of samples read
  38
  39     If opened with more than one channel, the frames will be
  40     down-mixed to produce the new samples.
  41
  42     :returns: A tuple of one array of samples and one integer.
  43     :rtype: (array, int)
  44
  45     .. seealso:: :meth:`__next__`
  46
  47     .. rubric:: Example
  48
  49     >>> src = aubio.source('stereo.wav')
  50     >>> while True:
  51     ...     samples, read = src()
  52     ...     if read < src.hop_size:
  53     ...         break
  54
  55   .. function:: __next__()
  56
  57     Read at most `hop_size` new frames from self, return them in
  58     an array.
  59
  60     If source was opened with one channel, next(self) returns
  61     an array of shape `(read,)`, where `read` is the actual
  62     number of frames read (`0 <= read <= hop_size`).
  63
  64     If `source` was opened with more then one channel, the
  65     returned arrays will be of shape `(channels, read)`, where
  66     `read` is the actual number of frames read (`0 <= read <=
  67     hop_size`).
  68
  69     :return: A tuple of one array of frames and one integer.
  70     :rtype: (array, int)
  71
  72     .. seealso:: :meth:`__call__`
  73
  74     .. rubric:: Example
  75
  76     >>> for frames in aubio.source('song.flac')
  77     ...     print(samples.shape)
  78
  79   .. function:: __iter__()
  80
  81     Implement iter(self).
  82
  83     .. seealso:: :meth:`__next__`
  84
  85   .. function:: __enter__()
  86
  87     Implement context manager interface. The file will be opened
  88     upon entering the context. See `with` statement.
  89
  90     .. rubric:: Example
  91
  92     >>> with aubio.source('loop.ogg') as src:
  93     ...     src.uri, src.samplerate, src.channels
  94
  95   .. function:: __exit__()
  96
  97     Implement context manager interface. The file will be closed
  98     before exiting the context. See `with` statement.
  99
 100     .. seealso:: :meth:`__enter__`
 101
 102 .. py-sink.c
 103    TODO: remove special-members documentation
 104
 105 .. autoclass:: aubio.sink
 106   :members:
 107
 108   .. function:: __call__(vec, length)
 109
 110     Write `length` samples from `vec`.
 111
 112     :param array vec: input vector to write from
 113     :param int length: number of samples to write
 114     :example:
 115
 116     >>> with aubio.sink('foo.wav') as snk:
 117     ...     snk(aubio.fvec(1025), 1025)
 118