updated cavacore documentation

Author: karlstav

CAVACORE.md

@@ -11,38 +11,35 @@ the raw output data from fftw will not look very nice when used directly in a vi
 to improve the look of the visualization:
 
 
-* limit bandwith
+## adjustable bandwith
 
-theoretically the human ear can hear frequencies up to 20kHz, but the information above 10k is hard to separate from eachother
-and does not give much feedback by itself when visualizing audio. Similarly audio below 50Hz can be heard but does not directly provide 
-anything to the visualizing of the audio.
+Theoretically the human ear can hear frequencies up to 20kHz, but the information above 10k is hard to separate from eachother
+and does not give much feedback by itself when visualizing audio. Similarly audio down to 20Hz can be heard, but the frequencies
+below 50Hz does not directly provide anything to the visualizing of the audio.
 
 
-* spread the output logarithmically
+## spread the output logarithmically
 
-the human ear hears different frequencies logarithmically, so notes that are 2x and 4x higher than eachother, will be preceived
-as beeing a fixed amount higher than eachother.
+The human ear hears different frequencies logarithmically, so notes that are 2x and 4x higher than eachother, will be preceived
+as beeing a fixed amount higher than eachother. Therefore cavacore outputs the frequencies logarithmically. Cavacore will also
+group the output in the desired number of samples.
 
 
-* limit number of buckets
+## noise reduction
 
-fftw gives out (input samples / 2) + 1 number of ouput samples. cavacore can limit this to the desired needed "bars" in your application.
+the raw output of fftw is very noisy, cavacore processes the output signal in two ways to provide a smooth output:
 
+  * an integral filter calculates a weighted average of the last values
+  * fall off filter, when values is lower than last value it uses a  fall down effect instead of the new value
 
-* noise reduction
+This feature can be adjusted.
 
-the raw output of fftw is very jittery, cavacore processes the output signal in two ways to provide a smooth output:
 
-a. an integral filter calculates a weighted average of the last values
+## real-time sensitivity adjustment
 
-b. fall off filter, when values is lower than last value it uses a  fall down effect instead of the new value
-
-
-* real-time sensitivity adjustment
-
-the range of an input signal can vary a lot. cavacore will keep the output signal within the desired range in real-time.
+The range of an input signal can vary a lot. cavacore can keep the output signal within range in real-time. This feature can be disabled.
 
 
 # Usage
 
-look in cavacore.h for documentation and the cavacore_test.c application for how to use.
+See cavacore.h for documentation and the cavacore_test.c application for how to use.

README.md

@@ -458,7 +458,7 @@ $ pkill -USR2 cava
 Using cava in other applications
 --------------------------------
 
-The core processing engine in cava has been split into a separate library `cavacore`. Look in CAVACORE.md for usage.
+The core processing engine in cava has been split into a separate library `cavacore`. See CAVACORE.md for details.
 
 
 Contribution

cavacore.h

@@ -3,6 +3,9 @@
 
 #include <fftw3.h>
 
+// cava_plan, parameters used internally by cavacore, do not modify these directly
+// only the cut off frequencies is of any potential interest to read out,
+// the rest should most likley be hidden somehow
 struct cava_plan {
     int FFTbassbufferSize;
     int FFTmidbufferSize;
@@ -53,48 +56,52 @@ struct cava_plan {
     int *cava_fall;
 };
 
-// cava_init initialize cava, takes the following parameters:
+// cava_init, initialize visualization, takes the following parameters:
 
-// number_of_bars is number of wanted bars per channel
+// number_of_bars, number of wanted bars per channel
 
-// rate is sample rate of input signal
+// rate, sample rate of input signal
 
-// channels is number of interleaved channels in input
+// channels, number of interleaved channels in input
 
-// autosens toggle automatic sensitivity adjustment 1 = on, 2 = off
-// on gives a dynamically adjusted output signal from 0 to 1
+// autosens, toggle automatic sensitivity adjustment 1 = on, 0 = off
+// on, gives a dynamically adjusted output signal from 0 to 1
 // the output is continously adjusted to use the entire range
-// off will pass the raw values from cava directly to the output
-// the max values will depend on the input
+// off, will pass the raw values from cava directly to the output
+// the max values will then be dependent on the input
 
-// noise_reduction 0 - 1, recomended 0.77
+// noise_reduction, adjust noise reduciton filters. 0 - 1, recomended 0.77
 // the raw visualization is very noisy, this factor adjusts the integral
 // and gravity filters inside cavacore to keep the signal smooth
 // 1 will be very slow and smooth, 0 will be fast but noisy.
 
 // low_cut_off, high_cut_off cut off frequencies for visualization in Hz
+// recomended: 50, 10000
 
 // returns a cava_plan to be used by cava_execute
 extern struct cava_plan *cava_init(int number_of_bars, unsigned int rate, int channels,
                                    int autosens, double noise_reduction, int low_cut_off,
                                    int high_cut_off);
 
-// cava_execute executes cava
+// cava_execute, executes visualization
 
-// cava_in size can be up to  4096 * number of channels, but it is recomended to only fill up some
+// cava_in, input buffer can be any size. internal buffers in cavacore is
+// 4096 * number of channels at 44100 samples rate, but it is recomended to use less
 // new samples per execution as this determines your framerate.
 // 512 samples at 44100 sample rate mono, gives about 86 frames per second.
 
-// new_samples is the number of samples in cava_in
+// new_samples, the number of samples in cava_in to be processed
 // if you have async reading of data this number can vary from execution to execution
 
-// cava_out size must be number of bars * number of channels, left + right
+// cava_out, output buffer. Size must be number of bars * number of channels. Bars will
+// be sorted from lowest to highest frequency. Feft channel first then right channel.
 
-// plan is the struct returned from cava_init
+// plan, the cava_plan struct returned from cava_init
 
 // cava_execute assumes cava_in samples to be interleaved if more than one channel
+// only up to two channels are supported.
 extern void cava_execute(double *cava_in, int new_samples, double *cava_out,
                          struct cava_plan *plan);
 
-// destroys the plan, frees up memory
+// cava_destroy, destroys the plan, frees up memory
 extern void cava_destroy(struct cava_plan *plan);

cavacore_test.c

@@ -11,7 +11,7 @@
 
 void main() {
 
-    printf("welcome to cavalib standalone test app\n");
+    printf("welcome to cavacore standalone test app\n");
 
     int bars_per_channel = 10;
     int channels = 2;
@@ -21,7 +21,7 @@ void main() {
     double blueprint_200MHz[10] = {0, 0.002, 0.980, 0.049, 0.001, 0, 0, 0, 0, 0};
 
     printf("planning visualization with 10 bars per channel, 44100 rate, 2 cahnnels, autosens, "
-           "0.77 noise reduction, 50 - 10000 MHz.\n");
+           "0.77 noise reduction, 50 - 10000 MHz bandwith.\n");
 
     struct cava_plan *plan = cava_init(bars_per_channel, rate, channels, 1, 0.77, 50, 10000);
     printf("got lower cut off frequencies:\n");
@@ -46,11 +46,15 @@ void main() {
 
     printf("running cava execute 300 times (simulating about 3.5 seconds run time)\n\n");
     for (int k = 0; k < 300; k++) {
+
         // filling up 512*2 samples at a time, making sure the sinus wave is unbroken
+        // 200MHz in right channel, 2000MHz in left
+        // if we where using a proper audio source this would be replaced by a simple read function
         for (int n = 0; n < buffer_size / 2; n++) {
             cava_in[n * 2] = sin(2 * PI * 200 / rate * (n + (k * buffer_size / 2))) * 10000;
             cava_in[n * 2 + 1] = sin(2 * PI * 2000 / rate * (n + (k * buffer_size / 2))) * 10000;
         }
+
         cava_execute(cava_in, buffer_size, cava_out, plan);
     }