Index: src/io/source.h
===================================================================
--- src/io/source.h	(revision eaaba627e15400faa1b83b05a184ea885710d5c3)
+++ src/io/source.h	(revision bd1fa89b806943e5e99d6bef368af2c163ca8589)
@@ -26,5 +26,8 @@
   Media source to read blocks of consecutive audio samples from file
 
+  To write to file, use ::aubio_sink_t.
+
   \example io/test-source.c
+  \example io/test-source_multi.c
 
 */
Index: src/io/source_apple_audio.c
===================================================================
--- src/io/source_apple_audio.c	(revision eaaba627e15400faa1b83b05a184ea885710d5c3)
+++ src/io/source_apple_audio.c	(revision bd1fa89b806943e5e99d6bef368af2c163ca8589)
@@ -52,13 +52,28 @@
 extern CFURLRef getURLFromPath(const char * path);
 
+uint_t aubio_source_apple_audio_open (aubio_source_apple_audio_t *s, char_t * path);
+
 aubio_source_apple_audio_t * new_aubio_source_apple_audio(char_t * path, uint_t samplerate, uint_t block_size)
 {
   aubio_source_apple_audio_t * s = AUBIO_NEW(aubio_source_apple_audio_t);
 
-  s->path = path;
   s->block_size = block_size;
-
+  s->samplerate = samplerate;
+
+  if ( aubio_source_apple_audio_open ( s, path ) ) {
+    goto beach;
+  }
+  return s;
+
+beach:
+  AUBIO_FREE(s);
+  return NULL;
+}
+
+uint_t aubio_source_apple_audio_open (aubio_source_apple_audio_t *s, char_t * path)
+{
   OSStatus err = noErr;
   UInt32 propSize;
+  s->path = path;
 
   // open the resource url
@@ -77,9 +92,9 @@
   if (err) { AUBIO_ERROR("error in ExtAudioFileGetProperty, %d\n", (int)err); goto beach;}
 
-  if (samplerate == 0) {
-    samplerate = fileFormat.mSampleRate;
+  if (s->samplerate == 0) {
+    s->samplerate = fileFormat.mSampleRate;
     //AUBIO_DBG("sampling rate set to 0, automagically adjusting to %d\n", samplerate);
   }
-  s->samplerate = samplerate;
+
   s->source_samplerate = fileFormat.mSampleRate;
   s->channels = fileFormat.mChannelsPerFrame;
@@ -124,11 +139,11 @@
 
   // compute the size of the segments needed to read the input file
-  UInt32 samples = s->block_size * clientFormat.mChannelsPerFrame;
-  Float64 rateRatio = clientFormat.mSampleRate / fileFormat.mSampleRate;
+  UInt32 samples = s->block_size * s->channels;
+  Float64 rateRatio = s->samplerate / s->source_samplerate;
   uint_t segmentSize= (uint_t)(samples * rateRatio + .5);
   if (rateRatio < 1.) {
     segmentSize = (uint_t)(samples / rateRatio + .5);
   } else if (rateRatio > 1.) {
-    AUBIO_WRN("up-sampling %s from %0.2fHz to %0.2fHz\n", s->path, fileFormat.mSampleRate, clientFormat.mSampleRate);
+    AUBIO_WRN("up-sampling %s from %0dHz to %0dHz\n", s->path, s->source_samplerate, s->samplerate);
   } else {
     assert ( segmentSize == samples );
@@ -137,11 +152,11 @@
 
   // allocate the AudioBufferList
-  if (createAubioBufferList(&s->bufferList, s->channels, segmentSize)) err = -1;
-
-  return s;
- 
-beach:
-  AUBIO_FREE(s);
-  return NULL;
+  if (createAubioBufferList(&s->bufferList, s->channels, segmentSize)) {
+    AUBIO_ERR("source_apple_audio: failed creating bufferList\n");
+    goto beach;
+  }
+
+beach:
+  return err;
 }
 
@@ -205,10 +220,16 @@
 }
 
-void del_aubio_source_apple_audio(aubio_source_apple_audio_t * s){
+uint_t aubio_source_apple_audio_close (aubio_source_apple_audio_t *s)
+{
   OSStatus err = noErr;
-  if (!s || !s->audioFile) { return; }
+  if (!s || !s->audioFile) { return 1; }
   err = ExtAudioFileDispose(s->audioFile);
   if (err) AUBIO_ERROR("error in ExtAudioFileDispose, %d\n", (int)err);
   s->audioFile = NULL;
+  return err;
+}
+
+void del_aubio_source_apple_audio(aubio_source_apple_audio_t * s){
+  aubio_source_apple_audio_close (s);
   freeAudioBufferList(&s->bufferList);
   AUBIO_FREE(s);
@@ -217,4 +238,11 @@
 
 uint_t aubio_source_apple_audio_seek (aubio_source_apple_audio_t * s, uint_t pos) {
+  if (1) {
+    AudioBufferList *bufferList = &s->bufferList;
+    UInt32 samples = s->block_size * s->channels;
+    Float64 rateRatio = s->samplerate / s->source_samplerate;
+    uint_t segmentSize= (uint_t)(samples * rateRatio + .5);
+    bufferList->mBuffers[0].mDataByteSize = segmentSize * sizeof(short);
+  }
   SInt64 resampled_pos = (SInt64)ROUND( pos * s->source_samplerate * 1. / s->samplerate );
   OSStatus err = ExtAudioFileSeek(s->audioFile, resampled_pos);
Index: src/io/utils_apple_audio.c
===================================================================
--- src/io/utils_apple_audio.c	(revision eaaba627e15400faa1b83b05a184ea885710d5c3)
+++ src/io/utils_apple_audio.c	(revision bd1fa89b806943e5e99d6bef368af2c163ca8589)
@@ -5,4 +5,5 @@
 // ExtAudioFileRef, AudioStreamBasicDescription, AudioBufferList, ...
 #include <AudioToolbox/AudioToolbox.h>
+#include "aubio_priv.h"
 
 int createAubioBufferList(AudioBufferList *bufferList, int channels, int segmentSize);
@@ -13,5 +14,5 @@
   bufferList->mNumberBuffers = 1;
   bufferList->mBuffers[0].mNumberChannels = channels;
-  bufferList->mBuffers[0].mData = (short *)malloc(segmentSize * sizeof(short));
+  bufferList->mBuffers[0].mData = AUBIO_ARRAY(short, segmentSize);
   bufferList->mBuffers[0].mDataByteSize = segmentSize * sizeof(short);
   return 0;
@@ -23,5 +24,5 @@
   for (i = 0; i < bufferList->mNumberBuffers; i++) {
     if (bufferList->mBuffers[i].mData) {
-      free (bufferList->mBuffers[i].mData);
+      AUBIO_FREE(bufferList->mBuffers[i].mData);
       bufferList->mBuffers[i].mData = NULL;
     }
Index: src/pitch/pitchyinfft.h
===================================================================
--- src/pitch/pitchyinfft.h	(revision eaaba627e15400faa1b83b05a184ea885710d5c3)
+++ src/pitch/pitchyinfft.h	(revision bd1fa89b806943e5e99d6bef368af2c163ca8589)
@@ -28,7 +28,7 @@
   function is tapered, the selection of the period is simplified.
  
-  Paul Brossier, ``Automatic annotation of musical audio for interactive
-  systems'', Chapter 3, Pitch Analysis, PhD thesis, Centre for Digital music,
-  Queen Mary University of London, London, UK, 2006.
+  Paul Brossier, [Automatic annotation of musical audio for interactive
+  systems](http://aubio.org/phd/), Chapter 3, Pitch Analysis, PhD thesis,
+  Centre for Digital music, Queen Mary University of London, London, UK, 2006.
 
   \example pitch/test-pitchyinfft.c
Index: src/tempo/tempo.h
===================================================================
--- src/tempo/tempo.h	(revision eaaba627e15400faa1b83b05a184ea885710d5c3)
+++ src/tempo/tempo.h	(revision bd1fa89b806943e5e99d6bef368af2c163ca8589)
@@ -19,6 +19,6 @@
 */
 
-/** \file 
-  
+/** \file
+
   Tempo detection object
 
@@ -40,37 +40,69 @@
 typedef struct _aubio_tempo_t aubio_tempo_t;
 
-/** create tempo detection object */
-aubio_tempo_t * new_aubio_tempo (char_t * method, 
+/** create tempo detection object
+
+  \param buf_size length of FFT
+  \param hop_size number of frames between two consecutive runs
+  \param samplerate sampling rate of the signal to analyze
+
+  \return newly created ::aubio_tempo_t if successful, `NULL` otherwise
+
+*/
+aubio_tempo_t * new_aubio_tempo (char_t * method,
     uint_t buf_size, uint_t hop_size, uint_t samplerate);
 
-/** execute tempo detection */
+/** execute tempo detection
+
+  \param o beat tracking object
+  \param input new samples
+  \param tempo output beats
+
+*/
 void aubio_tempo_do (aubio_tempo_t *o, fvec_t * input, fvec_t * tempo);
 
-/** set tempo detection silence threshold  */
+/** set tempo detection silence threshold
+
+  \param o beat tracking object
+  \param threshold new silence threshold, in dB
+
+  \return `0` if successful, non-zero otherwise
+
+*/
 uint_t aubio_tempo_set_silence(aubio_tempo_t * o, smpl_t silence);
 
-/** set tempo detection peak picking threshold  */
+/** set tempo detection peak picking threshold
+
+  \param o beat tracking object
+  \param threshold new threshold
+
+  \return `0` if successful, non-zero otherwise
+
+*/
 uint_t aubio_tempo_set_threshold(aubio_tempo_t * o, smpl_t threshold);
 
 /** get current tempo
 
-  \param bt beat tracking object
+  \param o beat tracking object
 
-  Returns the currently observed tempo, or 0 if no consistent value is found
+  \return the currently observed tempo, or `0` if no consistent value is found
 
 */
-smpl_t aubio_tempo_get_bpm(aubio_tempo_t * bt);
+smpl_t aubio_tempo_get_bpm(aubio_tempo_t * o);
 
 /** get current tempo confidence
 
-  \param bt beat tracking object
+  \param o beat tracking object
 
-  Returns the confidence with which the tempo has been observed, 0 if no
+  \return confidence with which the tempo has been observed, `0` if no
   consistent value is found.
 
 */
-smpl_t aubio_tempo_get_confidence(aubio_tempo_t * bt);
+smpl_t aubio_tempo_get_confidence(aubio_tempo_t * o);
 
-/** delete tempo detection object */
+/** delete tempo detection object
+
+  \param o beat tracking object
+
+*/
 void del_aubio_tempo(aubio_tempo_t * o);
 
