aubio  0.4.1
io/source.h
Go to the documentation of this file.
00001 /*
00002   Copyright (C) 2012-2013 Paul Brossier <piem@aubio.org>
00003 
00004   This file is part of aubio.
00005 
00006   aubio is free software: you can redistribute it and/or modify
00007   it under the terms of the GNU General Public License as published by
00008   the Free Software Foundation, either version 3 of the License, or
00009   (at your option) any later version.
00010 
00011   aubio is distributed in the hope that it will be useful,
00012   but WITHOUT ANY WARRANTY; without even the implied warranty of
00013   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
00014   GNU General Public License for more details.
00015 
00016   You should have received a copy of the GNU General Public License
00017   along with aubio.  If not, see <http://www.gnu.org/licenses/>.
00018 
00019 */
00020 
00021 #ifndef _AUBIO_SOURCE_H
00022 #define _AUBIO_SOURCE_H
00023 
00024 /** \file
00025 
00026   Media source to read blocks of consecutive audio samples from file.
00027 
00028   To write to file, use ::aubio_sink_t.
00029 
00030   Depending on how aubio was compiled, the following sources will be available.
00031 
00032   When creating a new source using ::new_aubio_source, the new function of each
00033   of the compiled-in sources will be used, in the following order, until one of
00034   them gets successfully created. If all sources returned NULL,
00035   ::new_aubio_source will return NULL.
00036 
00037   \b \p source_avcodec : libav
00038 
00039   aubio can be optionally compiled with [libav](http://libav.org), which can
00040   read from a very large number of audio and video formats, including over
00041   different network protocols such as HTTP.
00042 
00043   \b \p source_apple_audio : ExtAudioFileRef
00044 
00045   On Mac and iOS platforms, aubio should be compiled with CoreAudio [Extended
00046   Audio File Services]
00047   (https://developer.apple.com/library/mac/documentation/MusicAudio/Reference/ExtendedAudioFileServicesReference/Reference/reference.html).
00048   This provides access to most common audio file formats, including compressed
00049   ones.
00050 
00051   \b \p source_sndfile : libsndfile
00052 
00053   Also optional, aubio can be built against
00054   [libsndfile](http://www.mega-nerd.com/libsndfile/), which can read [most
00055   uncompressed formats](http://www.mega-nerd.com/libsndfile/#Features).
00056 
00057   \b \p source_wavread : native WAV reader
00058 
00059   A simple source to read from 16-bits PCM RIFF encoded WAV files.
00060 
00061   \example io/test-source.c
00062   \example io/test-source_multi.c
00063 
00064 */
00065 
00066 #ifdef __cplusplus
00067 extern "C" {
00068 #endif
00069 
00070 /** media source object */
00071 typedef struct _aubio_source_t aubio_source_t;
00072 
00073 /**
00074 
00075   create new ::aubio_source_t
00076 
00077   \param uri the file path or uri to read from
00078   \param samplerate sampling rate to view the fie at
00079   \param hop_size the size of the blocks to read from
00080 
00081   Creates a new source object. If `0` is passed as `samplerate`, the sample
00082   rate of the original file is used.
00083 
00084   The samplerate of newly created source can be obtained using
00085   ::aubio_source_get_samplerate.
00086 
00087 */
00088 aubio_source_t * new_aubio_source(char_t * uri, uint_t samplerate, uint_t hop_size);
00089 
00090 /**
00091 
00092   read monophonic vector of length hop_size from source object
00093 
00094   \param s source object, created with ::new_aubio_source
00095   \param read_to ::fvec_t of data to read to
00096   \param read upon returns, equals to number of frames actually read
00097 
00098   Upon returns, `read` contains the number of frames actually read from the
00099   source. `hop_size` if enough frames could be read, less otherwise.
00100 
00101 */
00102 void aubio_source_do(aubio_source_t * s, fvec_t * read_to, uint_t * read);
00103 
00104 /**
00105 
00106   read polyphonic vector of length hop_size from source object
00107 
00108   \param s source object, created with ::new_aubio_source
00109   \param read_to ::fmat_t of data to read to
00110   \param[out] read upon returns, equals to number of frames actually read
00111 
00112   Upon returns, `read` contains the number of frames actually read from the
00113   source. `hop_size` if enough frames could be read, less otherwise.
00114 
00115 */
00116 void aubio_source_do_multi(aubio_source_t * s, fmat_t * read_to, uint_t * read);
00117 
00118 /**
00119 
00120   get samplerate of source object
00121 
00122   \param s source object, created with ::new_aubio_source
00123   \return samplerate, in Hz
00124 
00125 */
00126 uint_t aubio_source_get_samplerate(aubio_source_t * s);
00127 
00128 /**
00129 
00130   get channels of source object
00131 
00132   \param s source object, created with ::new_aubio_source
00133   \return channels
00134 
00135 */
00136 uint_t aubio_source_get_channels (aubio_source_t * s);
00137 
00138 /**
00139 
00140   seek source object
00141 
00142   \param s source object, created with ::new_aubio_source
00143   \param pos position to seek to, in frames
00144 
00145   \return 0 if sucessful, non-zero on failure
00146 
00147 */
00148 uint_t aubio_source_seek (aubio_source_t * s, uint_t pos);
00149 
00150 /**
00151 
00152   close source object
00153 
00154   \param s source object, created with ::new_aubio_source
00155 
00156   \return 0 if sucessful, non-zero on failure
00157 
00158  */
00159 uint_t aubio_source_close (aubio_source_t *s);
00160 
00161 /**
00162 
00163   close source and cleanup memory
00164 
00165   \param s source object, created with ::new_aubio_source
00166 
00167 */
00168 void del_aubio_source(aubio_source_t * s);
00169 
00170 #ifdef __cplusplus
00171 }
00172 #endif
00173 
00174 #endif /* _AUBIO_SOURCE_H */
 All Data Structures Files Functions Variables Typedefs Defines