Index: tests/src/pitch/test-pitch.c
===================================================================
--- tests/src/pitch/test-pitch.c	(revision ed1deac8ca3b75cdccddf62388f1f4164ecc1578)
+++ tests/src/pitch/test-pitch.c	(revision c71aa4417bf3e9bd52acd75c51c7b43193ad285a)
@@ -1,25 +1,32 @@
 #include <aubio.h>
 
-int
-main ()
+int main ()
 {
-  /* allocate some memory */
-  uint_t win_s = 1024;          /* window size */
-  uint_t hop_s = win_s / 4;     /* hop size */
-  uint_t samplerate = 44100;    /* samplerate */
-  fvec_t *in = new_fvec (hop_s);      /* input buffer */
-  fvec_t *out = new_fvec (1); /* input buffer */
-  aubio_pitch_t *o =
-      new_aubio_pitch ("default", win_s, hop_s, samplerate);
-  uint_t i = 0;
+  // 1. allocate some memory
+  uint_t n = 0; // frame counter
+  uint_t win_s = 1024; // window size
+  uint_t hop_s = win_s / 4; // hop size
+  uint_t samplerate = 44100; // samplerate
+  // create some vectors
+  fvec_t *input = new_fvec (hop_s); // input buffer
+  fvec_t *out = new_fvec (1); // output candidates
+  // create pitch object
+  aubio_pitch_t *o = new_aubio_pitch ("default", win_s, hop_s, samplerate);
 
-  while (i < 100) {
-    aubio_pitch_do (o, in, out);
-    i++;
+  // 2. do something with it
+  while (n < 100) {
+    // get `hop_s` new samples into `input`
+    // ...
+    // exectute pitch
+    aubio_pitch_do (o, input, out);
+    // do something with output candidates
+    // ...
+    n++;
   };
 
+  // 3. clean up memory
   del_aubio_pitch (o);
   del_fvec (out);
-  del_fvec (in);
+  del_fvec (input);
   aubio_cleanup ();
 
Index: tests/src/pitch/test-pitchfcomb.c
===================================================================
--- tests/src/pitch/test-pitchfcomb.c	(revision ed1deac8ca3b75cdccddf62388f1f4164ecc1578)
+++ tests/src/pitch/test-pitchfcomb.c	(revision c71aa4417bf3e9bd52acd75c51c7b43193ad285a)
@@ -1,26 +1,29 @@
 #define AUBIO_UNSTABLE 1
+
+// this file uses the unstable aubio api, please use aubio_pitch instead
+// see src/pitch/pitch.h and tests/src/pitch/test-pitch.c
 
 #include <aubio.h>
 
-int main(){
-        /* allocate some memory */
-        uint_t win_s      = 1024;                       /* window size */
-        uint_t hop_s      = win_s/4;                    /* hop size */
-        fvec_t * in       = new_fvec (hop_s); /* input buffer */
-        fvec_t * out      = new_fvec (1);
-        aubio_pitchfcomb_t * o  = new_aubio_pitchfcomb (
-          win_s, hop_s);
-        uint_t i = 0;
+int main ()
+{
+  uint_t i = 0;
+  uint_t win_s = 1024; // window size
+  uint_t hop_s = win_s/4; // hop size
+  // create some vectors
+  fvec_t * in = new_fvec (hop_s); // input buffer
+  fvec_t * out = new_fvec (1); // output candidates
+  // create pitch object
+  aubio_pitchfcomb_t * o  = new_aubio_pitchfcomb ( win_s, hop_s);
 
-        while (i < 2) {
-          aubio_pitchfcomb_do (o,in, out);
-          i++;
-        };
+  while (i < 10) {
+    aubio_pitchfcomb_do (o,in, out);
+    i++;
+  };
 
-        del_aubio_pitchfcomb(o);
-        del_fvec(out);
-        del_fvec(in);
-        aubio_cleanup();
-
-        return 0;
+  del_aubio_pitchfcomb(o);
+  del_fvec(out);
+  del_fvec(in);
+  aubio_cleanup();
+  return 0;
 }
Index: tests/src/pitch/test-pitchmcomb.c
===================================================================
--- tests/src/pitch/test-pitchmcomb.c	(revision ed1deac8ca3b75cdccddf62388f1f4164ecc1578)
+++ tests/src/pitch/test-pitchmcomb.c	(revision c71aa4417bf3e9bd52acd75c51c7b43193ad285a)
@@ -1,26 +1,32 @@
 #define AUBIO_UNSTABLE 1
+
+// this file uses the unstable aubio api, please use aubio_pitch instead
+// see src/pitch/pitch.h and tests/src/pitch/test-pitch.c
 
 #include <aubio.h>
 
-int main(){
-        /* allocate some memory */
-        uint_t win_s      = 1024;                       /* window size */
-        uint_t hop_s      = win_s/4;                    /* hop size */
-        cvec_t * in       = new_cvec (win_s); /* input buffer */
-        fvec_t * out      = new_fvec (1); /* input buffer */
+int main ()
+{
+  uint_t n = 10; // compute n times
+  uint_t win_s = 1024; // window size
+  uint_t hop_s = win_s/4; // hop size
+  // create some vectors
+  cvec_t * in_cvec = new_cvec (win_s); // input fftgrain
+  fvec_t * out_cands = new_fvec (1); // pitch candidate
+  // create pitch object
+  aubio_pitchmcomb_t * mcomb = new_aubio_pitchmcomb(win_s, hop_s);
 
-        aubio_pitchmcomb_t * o  = new_aubio_pitchmcomb(win_s, hop_s);
-        uint_t i = 0;
+  while ( n-- ) {
+    aubio_pitchmcomb_do (mcomb, in_cvec, out_cands);
+    // fvec_print(out_cands);
+  };
 
-        while (i < 1000) {
-          aubio_pitchmcomb_do (o,in, out);
-          i++;
-        };
+  // clean up before exiting
+  del_aubio_pitchmcomb(mcomb);
+  del_cvec(in_cvec);
+  del_fvec(out_cands);
 
-        del_aubio_pitchmcomb(o);
-        del_cvec(in);
-        del_fvec(out);
-        aubio_cleanup();
+  aubio_cleanup();
 
-        return 0;
+  return 0;
 }
Index: tests/src/pitch/test-pitchschmitt.c
===================================================================
--- tests/src/pitch/test-pitchschmitt.c	(revision ed1deac8ca3b75cdccddf62388f1f4164ecc1578)
+++ tests/src/pitch/test-pitchschmitt.c	(revision c71aa4417bf3e9bd52acd75c51c7b43193ad285a)
@@ -1,25 +1,29 @@
 #define AUBIO_UNSTABLE 1
+
+// this file uses the unstable aubio api, please use aubio_pitch instead
+// see src/pitch/pitch.h and tests/src/pitch/test-pitch.c
 
 #include <aubio.h>
 
-int main(){
-        /* allocate some memory */
-        uint_t win_s      = 1024;                       /* window size */
-        fvec_t * in       = new_fvec (win_s); /* input buffer */
-        fvec_t * out = new_fvec (1); /* input buffer */
-        aubio_pitchschmitt_t * o  = new_aubio_pitchschmitt(win_s);
-        uint_t i = 0;
+int main ()
+{
+  uint_t n = 10; // compute n times
+  uint_t win_s = 1024; // window size
+  // create some vectors
+  fvec_t * in = new_fvec (win_s); // input buffer
+  fvec_t * out = new_fvec (1); // input buffer
+  // create pitch object
+  aubio_pitchschmitt_t * o = new_aubio_pitchschmitt(win_s);
 
-        while (i < 1000) {
-          aubio_pitchschmitt_do (o,in, out);
-          i++;
-        };
+  while ( n-- ) {
+    aubio_pitchschmitt_do (o,in, out);
+  };
 
-        del_aubio_pitchschmitt(o);
-        del_fvec(in);
-        del_fvec(out);
-        aubio_cleanup();
+  del_aubio_pitchschmitt(o);
+  del_fvec(in);
+  del_fvec(out);
+  aubio_cleanup();
 
-        return 0;
+  return 0;
 }
 
Index: tests/src/pitch/test-pitchyin.c
===================================================================
--- tests/src/pitch/test-pitchyin.c	(revision ed1deac8ca3b75cdccddf62388f1f4164ecc1578)
+++ tests/src/pitch/test-pitchyin.c	(revision c71aa4417bf3e9bd52acd75c51c7b43193ad285a)
@@ -1,24 +1,30 @@
 #define AUBIO_UNSTABLE 1
+
+// this file uses the unstable aubio api, please use aubio_pitch instead
+// see src/pitch/pitch.h and tests/src/pitch/test-pitch.c
 
 #include <aubio.h>
 
-int main(){
-        /* allocate some memory */
-        uint_t win_s      = 1024;                       /* window size */
-        fvec_t * in       = new_fvec (win_s); /* input buffer */
-        fvec_t * out      = new_fvec (win_s/2); /* input buffer */
-        aubio_pitchyin_t *p = new_aubio_pitchyin (win_s);
-        uint_t i = 0;
+int main ()
+{
+  uint_t n = 10; // compute n times
+  uint_t win_s = 1024; // window size
+  // create some vectors
+  fvec_t * input_signal = new_fvec (win_s); // input signal
+  fvec_t * output_cands = new_fvec (1); // output candidates
+  // create pitch object
+  aubio_pitchyin_t *p = new_aubio_pitchyin (win_s);
 
-        while (i < 10) {
-          aubio_pitchyin_do (p, in,out);
-          i++;
-        };
+  while ( n-- ) {
+    aubio_pitchyin_do (p, input_signal, output_cands);
+  };
 
-        del_fvec(in);
-        del_fvec(out);
-        del_aubio_pitchyin(p);
-        aubio_cleanup();
+  fvec_print(output_cands);
 
-        return 0;
+  del_fvec(input_signal);
+  del_fvec(output_cands);
+  del_aubio_pitchyin(p);
+  aubio_cleanup();
+
+  return 0;
 }
Index: tests/src/pitch/test-pitchyinfft.c
===================================================================
--- tests/src/pitch/test-pitchyinfft.c	(revision ed1deac8ca3b75cdccddf62388f1f4164ecc1578)
+++ tests/src/pitch/test-pitchyinfft.c	(revision c71aa4417bf3e9bd52acd75c51c7b43193ad285a)
@@ -1,26 +1,31 @@
 #define AUBIO_UNSTABLE 1
+
+// this file uses the unstable aubio api, please use aubio_pitch instead
+// see src/pitch/pitch.h and tests/src/pitch/test-pitch.c
 
 #include <aubio.h>
 
-int main(){
-        /* allocate some memory */
-        uint_t win_s      = 1024;                       /* window size */
-        fvec_t * in       = new_fvec (win_s); /* input buffer */
-        fvec_t * out      = new_fvec (1); /* output pitch periods */
-        aubio_pitchyinfft_t * o  = new_aubio_pitchyinfft(win_s);
-        aubio_pitchyinfft_set_tolerance (o, 0.2);
-        uint_t i = 0;
+int main ()
+{
+  uint_t n = 10; // compute n times
+  uint_t win_s = 1024; // window size
+  // create some vectors
+  fvec_t * in = new_fvec (win_s); // input buffer
+  fvec_t * out = new_fvec (1); // output candidates
+  // create pitch object
+  aubio_pitchyinfft_t *p  = new_aubio_pitchyinfft(win_s);
+  aubio_pitchyinfft_set_tolerance (p, 0.2);
 
-        while (i < 10) {
-          aubio_pitchyinfft_do (o,in,out);
-          i++;
-        };
+  while ( n-- ) {
+    aubio_pitchyinfft_do (p, in,out);
+  };
 
-        del_aubio_pitchyinfft(o);
-        del_fvec(in);
-        del_fvec(out);
-        aubio_cleanup();
+  fvec_print(out);
 
-        return 0;
+  del_fvec(in);
+  del_fvec(out);
+  del_aubio_pitchyinfft(p);
+  aubio_cleanup();
+
+  return 0;
 }
-
