src/io/source.h

   1 /*
   2   Copyright (C) 2012-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_SOURCE_H
  22 #define _AUBIO_SOURCE_H
  23
  24 /** \file
  25
  26   Media source to read blocks of consecutive audio samples from file
  27
  28   Depending on how aubio was compiled, the following file formats will be
  29   available.
  30
  31   To write to file, use ::aubio_sink_t.
  32
  33   \b \p source_avcodec : libav
  34
  35   aubio can be optionally compiled with [libav](http://libav.org), which can
  36   read from a very large number of audio and video formats, including over
  37   different network protocols such as HTTP.
  38
  39   \b \p source_apple_audio : ExtAudioFileRef
  40
  41   On Mac and iOS platforms, aubio should be compiled with CoreAudio [Extended
  42   Audio File Services]
  43   (https://developer.apple.com/library/mac/documentation/MusicAudio/Reference/ExtendedAudioFileServicesReference/Reference/reference.html).
  44   This provides access to most common audio file formats, including compressed
  45   ones.
  46
  47   \b \p source_sndfile : libsndfile
  48
  49   Also optional, aubio can be built against
  50   [libsndfile](http://www.mega-nerd.com/libsndfile/), which can read [most
  51   uncompressed formats](http://www.mega-nerd.com/libsndfile/#Features).
  52
  53   \b \p source_wavread : native WAV reader
  54
  55   A simple source to read from 16-bits PCM RIFF encoded WAV files.
  56
  57   \example io/test-source.c
  58   \example io/test-source_multi.c
  59
  60 */
  61
  62 #ifdef __cplusplus
  63 extern "C" {
  64 #endif
  65
  66 /** media source object */
  67 typedef struct _aubio_source_t aubio_source_t;
  68
  69 /**
  70
  71   create new ::aubio_source_t
  72
  73   \param uri the file path or uri to read from
  74   \param samplerate sampling rate to view the fie at
  75   \param hop_size the size of the blocks to read from
  76
  77   Creates a new source object. If `0` is passed as `samplerate`, the sample
  78   rate of the original file is used.
  79
  80   The samplerate of newly created source can be obtained using
  81   ::aubio_source_get_samplerate.
  82
  83 */
  84 aubio_source_t * new_aubio_source(char_t * uri, uint_t samplerate, uint_t hop_size);
  85
  86 /**
  87
  88   read monophonic vector of length hop_size from source object
  89
  90   \param s source object, created with ::new_aubio_source
  91   \param read_to ::fvec_t of data to read to
  92   \param read upon returns, equals to number of frames actually read
  93
  94   Upon returns, `read` contains the number of frames actually read from the
  95   source. `hop_size` if enough frames could be read, less otherwise.
  96
  97 */
  98 void aubio_source_do(aubio_source_t * s, fvec_t * read_to, uint_t * read);
  99
 100 /**
 101
 102   read polyphonic vector of length hop_size from source object
 103
 104   \param s source object, created with ::new_aubio_source
 105   \param read_to ::fmat_t of data to read to
 106   \param[out] read upon returns, equals to number of frames actually read
 107
 108   Upon returns, `read` contains the number of frames actually read from the
 109   source. `hop_size` if enough frames could be read, less otherwise.
 110
 111 */
 112 void aubio_source_do_multi(aubio_source_t * s, fmat_t * read_to, uint_t * read);
 113
 114 /**
 115
 116   get samplerate of source object
 117
 118   \param s source object, created with ::new_aubio_source
 119   \return samplerate, in Hz
 120
 121 */
 122 uint_t aubio_source_get_samplerate(aubio_source_t * s);
 123
 124 /**
 125
 126   get channels of source object
 127
 128   \param s source object, created with ::new_aubio_source
 129   \return channels
 130
 131 */
 132 uint_t aubio_source_get_channels (aubio_source_t * s);
 133
 134 /**
 135
 136   seek source object
 137
 138   \param s source object, created with ::new_aubio_source
 139   \param pos position to seek to, in frames
 140
 141   \return 0 if sucessful, non-zero on failure
 142
 143 */
 144 uint_t aubio_source_seek (aubio_source_t * s, uint_t pos);
 145
 146 /**
 147
 148   close source object
 149
 150   \param s source object, created with ::new_aubio_source
 151
 152   \return 0 if sucessful, non-zero on failure
 153
 154  */
 155 uint_t aubio_source_close (aubio_source_t *s);
 156
 157 /**
 158
 159   close source and cleanup memory
 160
 161   \param s source object, created with ::new_aubio_source
 162
 163 */
 164 void del_aubio_source(aubio_source_t * s);
 165
 166 #ifdef __cplusplus
 167 }
 168 #endif
 169
 170 #endif /* _AUBIO_SOURCE_H */