ref: ac20c856d41f89c5c9c4e2f197ff79d4fc4e0c2d
parent: de5d3f123debc4c03dad0ad15f2af5b7a444e0c0
author: Paul Brossier <piem@piem.org>
date: Mon Mar 18 06:32:08 EDT 2013
src/io/*.h: add documentation to source and sink
--- /dev/null
+++ b/src/io/audio_unit.h
@@ -1,0 +1,45 @@
+/*
+ Copyright (C) 2013 Paul Brossier <piem@aubio.org>
+
+ 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 <http://www.gnu.org/licenses/>.
+
+*/
+
+#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 */
--- a/src/io/sink.h
+++ b/src/io/sink.h
@@ -1,5 +1,5 @@
/*
- Copyright (C) 2012 Paul Brossier <piem@aubio.org>
+ Copyright (C) 2012-2013 Paul Brossier <piem@aubio.org>
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
--- a/src/io/sink_apple_audio.h
+++ b/src/io/sink_apple_audio.h
@@ -1,5 +1,5 @@
/*
- Copyright (C) 2012 Paul Brossier <piem@aubio.org>
+ Copyright (C) 2012-2013 Paul Brossier <piem@aubio.org>
This file is part of aubio.
@@ -23,8 +23,14 @@
/** \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 @@
#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
--- a/src/io/sink_sndfile.h
+++ b/src/io/sink_sndfile.h
@@ -1,5 +1,5 @@
/*
- Copyright (C) 2012 Paul Brossier <piem@aubio.org>
+ Copyright (C) 2012-2013 Paul Brossier <piem@aubio.org>
This file is part of aubio.
@@ -23,8 +23,13 @@
/** \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 @@
#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
--- a/src/io/source.h
+++ b/src/io/source.h
@@ -1,5 +1,5 @@
/*
- Copyright (C) 2012 Paul Brossier <piem@aubio.org>
+ Copyright (C) 2012-2013 Paul Brossier <piem@aubio.org>
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 @@
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 @@
/**
- destroy source object
+ close source and cleanup memory
\param s source object, created with ::new_aubio_source
--- a/src/io/source_apple_audio.h
+++ b/src/io/source_apple_audio.h
@@ -1,5 +1,5 @@
/*
- Copyright (C) 2012 Paul Brossier <piem@aubio.org>
+ Copyright (C) 2012-2013 Paul Brossier <piem@aubio.org>
This file is part of aubio.
@@ -23,8 +23,14 @@
/** \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
--- a/src/io/source_sndfile.h
+++ b/src/io/source_sndfile.h
@@ -1,5 +1,5 @@
/*
- Copyright (C) 2012 Paul Brossier <piem@aubio.org>
+ Copyright (C) 2012-2013 Paul Brossier <piem@aubio.org>
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