From e3a810db094ea4c71869fb2b9e4945e98c4c3fc2 Mon Sep 17 00:00:00 2001
From: Scott Lawson <scottlawsonbc@gmail.com>
Date: Mon, 21 Nov 2016 20:08:35 -0800
Subject: [PATCH] Updated documentation for configuration settings

---
 python/config.py | 49 +++++++++++++++++++++++++++++-------------------
 1 file changed, 30 insertions(+), 19 deletions(-)

diff --git a/python/config.py b/python/config.py
index 14b6987..9b57374 100644
--- a/python/config.py
+++ b/python/config.py
@@ -9,42 +9,53 @@ N_PIXELS = 60
 GAMMA_TABLE_PATH = os.path.join(os.path.dirname(__file__), 'gamma_table.npy')
 """Location of the gamma correction table"""
 
-UDP_IP = '192.168.0.150'
+UDP_IP = '192.168.137.150'
 """IP address of the ESP8266"""
 
 UDP_PORT = 7777
 """Port number used for socket communication between Python and ESP8266"""
 
-#MIC_RATE = 44100
 MIC_RATE = 48000
 """Sampling frequency of the microphone in Hz"""
 
-FPS = 100
-"""Desired LED strip update rate in frames (updates) per second
+FPS = 60
+"""Desired refresh rate of the visualization (frames per second)
 
-This is the desired update rate of the LED strip. The actual refresh rate of
-the LED strip may be lower if the time needed for signal processing exceeds
-the per-frame recording time.
+FPS indicates the desired refresh rate, or frames-per-second, of the audio
+visualization. The actual refresh rate may be lower if the computer cannot keep
+up with desired FPS value.
 
-A high FPS results in low latency and smooth animations, but it also reduces
-the duration of the short-time Fourier transform. This can negatively affect
-low frequency (bass) response.
+Higher framerates improve "responsiveness" and reduce the latency of the
+visualization but are more computationally expensive.
+
+Low framerates are less computationally expensive, but the visualization may
+appear "sluggish" or out of sync with the audio being played if it is too low.
+
+The FPS should not exceed the maximum refresh rate of the LED strip, which
+depends on how long the LED strip is.
 """
+_max_led_FPS = int(((N_PIXELS * 30e-6) + 50e-6)**-1.0)
+assert FPS <= _max_led_FPS, 'FPS must be <= {}'.format(_max_led_FPS)
 
 MIN_FREQUENCY = 200
-"""Frequencies below this value will be removed during onset detection"""
+"""Frequencies below this value will be removed during audio processing"""
 
-MAX_FREQUENCY = 14000
-"""Frequencies above this value will be removed during onset detection"""
+MAX_FREQUENCY = 12000
+"""Frequencies above this value will be removed during audio processing"""
 
-N_SUBBANDS = 30  # 240 #48
-"""Number of frequency bins to use for beat detection
+N_FFT_BINS = 30
+"""Number of frequency bins to use when transforming audio to frequency domain
 
-More subbands improve beat detection sensitivity but it may become more
-challenging for the visualization to work for a wide range of music.
+Fast Fourier transforms are used to transform time-domain audio data to the
+frequency domain. The frequencies present in the audio signal are assigned
+to their respective frequency bins. This value indicates the number of
+frequency bins to use.
 
-Fewer subbands reduces signal processing time at the expense of beat detection
-sensitivity.
+A small number of bins reduces the frequency resolution of the visualization
+but improves amplitude resolution. The opposite is true when using a large
+number of bins.
+
+There is no point using more bins than there are pixels on the LED strip.
 """
 
 GAMMA_CORRECTION = True