From: Paul Brossier Date: Mon, 18 Mar 2013 15:32:08 +0000 (-0500) Subject: src/io/*.h: add documentation to source and sink X-Git-Url: http://git.tremily.us/?a=commitdiff_plain;h=ac20c856d41f89c5c9c4e2f197ff79d4fc4e0c2d;p=aubio.git src/io/*.h: add documentation to source and sink --- diff --git a/src/io/audio_unit.h b/src/io/audio_unit.h new file mode 100644 index 00000000..4fb0a5dd --- /dev/null +++ b/src/io/audio_unit.h @@ -0,0 +1,45 @@ +/* + Copyright (C) 2013 Paul Brossier + + This file is part of aubio. + + aubio is free software: you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation, either version 3 of the License, or + (at your option) any later version. + + aubio is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with aubio. If not, see . + +*/ + +#ifndef _AUBIO_IO_AUDIO_UNIT_H +#define _AUBIO_IO_AUDIO_UNIT_H + +/** \file + +*/ + +#ifdef __cplusplus +extern "C" { +#endif + +typedef struct _aubio_audio_unit_t aubio_audio_unit_t; + +typedef uint_t (*aubio_audio_unit_callback_t) (void * closure, float *ibuf, float *obuf, uint_t size); + + +aubio_audio_unit_t * new_aubio_audio_unit(uint_t samplerate, uint_t inchannels, + uint_t outchannels, uint_t blocksize); +uint_t del_aubio_audio_unit(aubio_audio_unit_t *o); + +#ifdef __cplusplus +} +#endif + +#endif /* _AUBIO_IO_AUDIO_UNIT_H */ diff --git a/src/io/sink.h b/src/io/sink.h index 846b1acf..ef8cd905 100644 --- a/src/io/sink.h +++ b/src/io/sink.h @@ -1,5 +1,5 @@ /* - Copyright (C) 2012 Paul Brossier + Copyright (C) 2012-2013 Paul Brossier This file is part of aubio. @@ -23,7 +23,7 @@ /** \file - Media sink + Media sink to write blocks of consecutive audio samples to file. \example io/test-sink.c @@ -33,9 +33,41 @@ extern "C" { #endif +/** media sink object */ typedef struct _aubio_sink_t aubio_sink_t; + +/** + + create new ::aubio_sink_t + + \param uri the file path or uri to write to + \param samplerate sample rate to write the file at + + \return newly created ::aubio_sink_t + + Creates a new sink object. + +*/ aubio_sink_t * new_aubio_sink(char_t * uri, uint_t samplerate); -void aubio_sink_do(aubio_sink_t * s, fvec_t * write_data, uint_t written); + +/** + + write monophonic vector of length hop_size to sink + + \param s sink, created with ::new_aubio_sink + \param write_data ::fvec_t samples to write to sink + \param write number of frames to write + +*/ +void aubio_sink_do(aubio_sink_t * s, fvec_t * write_data, uint_t write); + +/** + + close sink and cleanup memory + + \param s source object, created with ::new_aubio_source + +*/ void del_aubio_sink(aubio_sink_t * s); #ifdef __cplusplus diff --git a/src/io/sink_apple_audio.h b/src/io/sink_apple_audio.h index 13dae942..b26fefec 100644 --- a/src/io/sink_apple_audio.h +++ b/src/io/sink_apple_audio.h @@ -1,5 +1,5 @@ /* - Copyright (C) 2012 Paul Brossier + Copyright (C) 2012-2013 Paul Brossier This file is part of aubio. @@ -23,7 +23,13 @@ /** \file - Apple Audio Media + Write to file using Apple AudioToolbox's + [ExtAudioFileRef](https://developer.apple.com/library/ios/#documentation/MusicAudio/Reference/ExtendedAudioFileServicesReference/Reference/reference.html) + + Avoid including this file directly! Prefer using ::aubio_sink_t instead to + make your code portable. + + To read from file, use ::aubio_source_t. \example io/test-sink_apple_audio.c @@ -34,8 +40,39 @@ extern "C" { #endif typedef struct _aubio_sink_apple_audio_t aubio_sink_apple_audio_t; -aubio_sink_apple_audio_t * new_aubio_sink_apple_audio(char_t * method, uint_t samplerate); + +/** + + create new ::aubio_sink_apple_audio_t + + \param uri the file path or uri to write to + \param samplerate sample rate to write the file at + + \return newly created ::aubio_sink_apple_audio_t + + Creates a new sink object. + +*/ +aubio_sink_apple_audio_t * new_aubio_sink_apple_audio(char_t * uri, uint_t samplerate); + +/** + + write monophonic vector of length hop_size to sink + + \param s sink, created with ::new_aubio_sink_apple_audio + \param write_data ::fvec_t samples to write to sink + \param write number of frames to write + +*/ void aubio_sink_apple_audio_do(aubio_sink_apple_audio_t * s, fvec_t * write_data, uint_t write); + +/** + + close sink and cleanup memory + + \param s sink, created with ::new_aubio_sink_apple_audio + +*/ void del_aubio_sink_apple_audio(aubio_sink_apple_audio_t * s); #ifdef __cplusplus diff --git a/src/io/sink_sndfile.h b/src/io/sink_sndfile.h index 330ed39f..c767e1db 100644 --- a/src/io/sink_sndfile.h +++ b/src/io/sink_sndfile.h @@ -1,5 +1,5 @@ /* - Copyright (C) 2012 Paul Brossier + Copyright (C) 2012-2013 Paul Brossier This file is part of aubio. @@ -23,7 +23,12 @@ /** \file - sndfile sink + Write to file using [libsndfile](http://www.mega-nerd.com/libsndfile/) + + Avoid including this file directly! Prefer using ::aubio_sink_t instead to + make your code portable. + + To read from file, use ::aubio_source_t. \example io/test-sink_sndfile.c @@ -34,8 +39,39 @@ extern "C" { #endif typedef struct _aubio_sink_sndfile_t aubio_sink_sndfile_t; -aubio_sink_sndfile_t * new_aubio_sink_sndfile(char_t * method, uint_t samplerate); + +/** + + create new ::aubio_sink_sndfile_t + + \param uri the file path or uri to write to + \param samplerate sample rate to write the file at + + \return newly created ::aubio_sink_sndfile_t + + Creates a new sink object. + +*/ +aubio_sink_sndfile_t * new_aubio_sink_sndfile(char_t * uri, uint_t samplerate); + +/** + + write monophonic vector of length hop_size to sink + + \param s sink, created with ::new_aubio_sink_sndfile + \param write_data ::fvec_t samples to write to sink + \param write number of frames to write + +*/ void aubio_sink_sndfile_do(aubio_sink_sndfile_t * s, fvec_t * write_data, uint_t write); + +/** + + close sink and cleanup memory + + \param s sink, created with ::new_aubio_sink_sndfile + +*/ void del_aubio_sink_sndfile(aubio_sink_sndfile_t * s); #ifdef __cplusplus diff --git a/src/io/source.h b/src/io/source.h index d4517a3d..abfd7827 100644 --- a/src/io/source.h +++ b/src/io/source.h @@ -1,5 +1,5 @@ /* - Copyright (C) 2012 Paul Brossier + Copyright (C) 2012-2013 Paul Brossier This file is part of aubio. @@ -23,7 +23,7 @@ /** \file - Media source object + Media source to read blocks of consecutive audio samples from file \example io/test-source.c @@ -33,7 +33,7 @@ extern "C" { #endif -/** source object structure */ +/** media source object */ typedef struct _aubio_source_t aubio_source_t; /** @@ -41,31 +41,31 @@ typedef struct _aubio_source_t aubio_source_t; create new ::aubio_source_t \param uri the file path or uri to read from - \param samplerate the sample rate to read the file at - \param hop_size the size of the blocks to read from + \param samplerate sampling rate to view the fie at + \param block_size the size of the blocks to read from Creates a new source object. If `0` is passed as `samplerate`, the sample rate of the original file is used. - The samplerate of the current source can be obtained with + The samplerate of newly created source can be obtained using ::aubio_source_get_samplerate. */ -aubio_source_t * new_aubio_source(char_t * uri, uint_t samplerate, uint_t hop_size); +aubio_source_t * new_aubio_source(char_t * uri, uint_t samplerate, uint_t block_size); /** - read monophonic vector of length hop_size from source object + read monophonic vector of length block_size from source object \param s source object, created with ::new_aubio_source - \param read_data ::fvec_t of data to read to - \param read number of frames actually read + \param read_to ::fvec_t of data to read to + \param read upon returns, equals to number of frames actually read Upon returns, `read` contains the number of frames actually read from the - source. `hop_size` if enough frames could be read, less otherwise. + source. `block_size` if enough frames could be read, less otherwise. */ -void aubio_source_do(aubio_source_t * s, fvec_t * read_data, uint_t * read); +void aubio_source_do(aubio_source_t * s, fvec_t * read_to, uint_t * read); /** @@ -79,7 +79,7 @@ uint_t aubio_source_get_samplerate(aubio_source_t * s); /** - destroy source object + close source and cleanup memory \param s source object, created with ::new_aubio_source diff --git a/src/io/source_apple_audio.h b/src/io/source_apple_audio.h index d6744120..5f9e70bf 100644 --- a/src/io/source_apple_audio.h +++ b/src/io/source_apple_audio.h @@ -1,5 +1,5 @@ /* - Copyright (C) 2012 Paul Brossier + Copyright (C) 2012-2013 Paul Brossier This file is part of aubio. @@ -23,7 +23,13 @@ /** \file - aubio source using ExtAudioFileRef + Read from file using Apple AudioToolbox's + [ExtAudioFileRef](https://developer.apple.com/library/ios/#documentation/MusicAudio/Reference/ExtendedAudioFileServicesReference/Reference/reference.html) + + Avoid including this file directly! Prefer using ::aubio_source_t instead to + make your code portable. + + To write to file, use ::aubio_sink_t. \example io/test-source_apple_audio.c @@ -33,10 +39,58 @@ extern "C" { #endif +/** apple audio media source object */ typedef struct _aubio_source_apple_audio_t aubio_source_apple_audio_t; -aubio_source_apple_audio_t * new_aubio_source_apple_audio(char_t * path, uint_t samplerate, uint_t block_size); + +/** + + create new ::aubio_source_apple_audio_t + + \param uri the file path or uri to read from + \param samplerate sampling rate to view the fie at + \param block_size the size of the blocks to read from + + Creates a new source object. If `0` is passed as `samplerate`, the sample + rate of the original file is used. + + The samplerate of newly created source can be obtained using + ::aubio_source_apple_audio_get_samplerate. + +*/ +aubio_source_apple_audio_t * new_aubio_source_apple_audio(char_t * uri, uint_t samplerate, uint_t block_size); + +/** + + read monophonic vector of length block_size from source object + + \param s source object, created with ::new_aubio_source_apple_audio + \param read_to ::fvec_t of data to read to + \param read upon returns, equals to number of frames actually read + + Upon returns, `read` contains the number of frames actually read from the + source. `block_size` if enough frames could be read, less otherwise. + +*/ void aubio_source_apple_audio_do(aubio_source_apple_audio_t * s, fvec_t * read_to, uint_t * read); +void aubio_source_apple_audio_do_multi(aubio_source_apple_audio_t * s, fmat_t * read_to, uint_t * read); + +/** + + get samplerate of source object + + \param s source object, created with ::new_aubio_source_apple_audio + \return samplerate, in Hz + +*/ uint_t aubio_source_apple_audio_get_samplerate(aubio_source_apple_audio_t * s); + +/** + + close source and cleanup memory + + \param s source object, created with ::new_aubio_source_apple_audio + +*/ void del_aubio_source_apple_audio(aubio_source_apple_audio_t * s); #ifdef __cplusplus diff --git a/src/io/source_sndfile.h b/src/io/source_sndfile.h index 1dff6d8e..8bac20cd 100644 --- a/src/io/source_sndfile.h +++ b/src/io/source_sndfile.h @@ -1,5 +1,5 @@ /* - Copyright (C) 2012 Paul Brossier + Copyright (C) 2012-2013 Paul Brossier This file is part of aubio. @@ -23,6 +23,13 @@ /** \file + Read from file using [libsndfile](http://www.mega-nerd.com/libsndfile/) + + Avoid including this file directly! Prefer using ::aubio_source_t instead to + make your code portable. + + To write to file, use ::aubio_sink_t. + \example io/test-source_sndfile.c */ @@ -31,10 +38,57 @@ extern "C" { #endif +/** sndfile media source object */ typedef struct _aubio_source_sndfile_t aubio_source_sndfile_t; -aubio_source_sndfile_t * new_aubio_source_sndfile(char_t * path, uint_t samplerate, uint_t block_size); + +/** + + create new ::aubio_source_sndfile_t + + \param uri the file path or uri to read from + \param samplerate sampling rate to view the fie at + \param block_size the size of the blocks to read from + + Creates a new source object. If `0` is passed as `samplerate`, the sample + rate of the original file is used. + + The samplerate of newly created source can be obtained using + ::aubio_source_sndfile_get_samplerate. + +*/ +aubio_source_sndfile_t * new_aubio_source_sndfile(char_t * uri, uint_t samplerate, uint_t block_size); + +/** + + read monophonic vector of length block_size from source object + + \param s source object, created with ::new_aubio_source_sndfile + \param read_to ::fvec_t of data to read to + \param read upon returns, equals to number of frames actually read + + Upon returns, `read` contains the number of frames actually read from the + source. `block_size` if enough frames could be read, less otherwise. + +*/ void aubio_source_sndfile_do(aubio_source_sndfile_t * s, fvec_t * read_to, uint_t * read); + +/** + + get samplerate of source object + + \param s source object, created with ::new_aubio_source_sndfile + \return samplerate, in Hz + +*/ uint_t aubio_source_sndfile_get_samplerate(aubio_source_sndfile_t * s); + +/** + + close source and cleanup memory + + \param s source object, created with ::new_aubio_source_sndfile + +*/ void del_aubio_source_sndfile(aubio_source_sndfile_t * s); #ifdef __cplusplus