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   \example io/test-source.c
  54   \example io/test-source_multi.c
  55
  56 */
  57
  58 #ifdef __cplusplus
  59 extern "C" {
  60 #endif
  61
  62 /** media source object */
  63 typedef struct _aubio_source_t aubio_source_t;
  64
  65 /**
  66
  67   create new ::aubio_source_t
  68
  69   \param uri the file path or uri to read from
  70   \param samplerate sampling rate to view the fie at
  71   \param hop_size the size of the blocks to read from
  72
  73   Creates a new source object. If `0` is passed as `samplerate`, the sample
  74   rate of the original file is used.
  75
  76   The samplerate of newly created source can be obtained using
  77   ::aubio_source_get_samplerate.
  78
  79 */
  80 aubio_source_t * new_aubio_source(char_t * uri, uint_t samplerate, uint_t hop_size);
  81
  82 /**
  83
  84   read monophonic vector of length hop_size from source object
  85
  86   \param s source object, created with ::new_aubio_source
  87   \param read_to ::fvec_t of data to read to
  88   \param read upon returns, equals to number of frames actually read
  89
  90   Upon returns, `read` contains the number of frames actually read from the
  91   source. `hop_size` if enough frames could be read, less otherwise.
  92
  93 */
  94 void aubio_source_do(aubio_source_t * s, fvec_t * read_to, uint_t * read);
  95
  96 /**
  97
  98   read polyphonic vector of length hop_size from source object
  99
 100   \param s source object, created with ::new_aubio_source
 101   \param read_to ::fmat_t of data to read to
 102   \param[out] read upon returns, equals to number of frames actually read
 103
 104   Upon returns, `read` contains the number of frames actually read from the
 105   source. `hop_size` if enough frames could be read, less otherwise.
 106
 107 */
 108 void aubio_source_do_multi(aubio_source_t * s, fmat_t * read_to, uint_t * read);
 109
 110 /**
 111
 112   get samplerate of source object
 113
 114   \param s source object, created with ::new_aubio_source
 115   \return samplerate, in Hz
 116
 117 */
 118 uint_t aubio_source_get_samplerate(aubio_source_t * s);
 119
 120 /**
 121
 122   get channels of source object
 123
 124   \param s source object, created with ::new_aubio_source
 125   \return channels
 126
 127 */
 128 uint_t aubio_source_get_channels (aubio_source_t * s);
 129
 130 /**
 131
 132   seek source object
 133
 134   \param s source object, created with ::new_aubio_source
 135   \param pos position to seek to, in frames
 136
 137   \return 0 if sucessful, non-zero on failure
 138
 139 */
 140 uint_t aubio_source_seek (aubio_source_t * s, uint_t pos);
 141
 142 /**
 143
 144   close source and cleanup memory
 145
 146   \param s source object, created with ::new_aubio_source
 147
 148 */
 149 void del_aubio_source(aubio_source_t * s);
 150
 151 #ifdef __cplusplus
 152 }
 153 #endif
 154
 155 #endif /* _AUBIO_SOURCE_H */