audiomotion-analyzer 4.5.2 → 5.0.0-alpha.0

package/dist/index.js

@@ -16,17 +16,17 @@
   Object.defineProperty(_exports, "__esModule", {
     value: true
   });
-  _exports.default = _exports.AudioMotionAnalyzer = void 0;
+  _exports.default = _exports.SCALE_MEL = _exports.SCALE_LOG = _exports.SCALE_LINEAR = _exports.SCALE_BARK = _exports.REASON_USER = _exports.REASON_RESIZE = _exports.REASON_LORES = _exports.REASON_FULLSCREENCHANGE = _exports.REASON_CREATE = _exports.RADIAL_OUTER = _exports.RADIAL_OFF = _exports.RADIAL_INNER = _exports.PEAKS_OFF = _exports.PEAKS_FADE = _exports.PEAKS_DROP = _exports.MODE_GRAPH = _exports.MODE_BARS = _exports.LEDS_VINTAGE = _exports.LEDS_OFF = _exports.LEDS_MODERN = _exports.LAYOUT_VERTICAL = _exports.LAYOUT_SINGLE = _exports.LAYOUT_HORIZONTAL = _exports.LAYOUT_COMBINED = _exports.FILTER_NONE = _exports.FILTER_D = _exports.FILTER_C = _exports.FILTER_B = _exports.FILTER_A = _exports.FILTER_468 = _exports.ERR_INVALID_AUDIO_SOURCE = _exports.ERR_INVALID_AUDIO_CONTEXT = _exports.ERR_AUDIO_CONTEXT_FAIL = _exports.ENERGY_TREBLE = _exports.ENERGY_PEAK = _exports.ENERGY_MIDRANGE = _exports.ENERGY_LOWMID = _exports.ENERGY_HIGHMID = _exports.ENERGY_BASS = _exports.COLORMODE_LEVEL = _exports.COLORMODE_INDEX = _exports.COLORMODE_GRADIENT = _exports.BANDS_OCTAVE_HALF = _exports.BANDS_OCTAVE_FULL = _exports.BANDS_OCTAVE_8TH = _exports.BANDS_OCTAVE_6TH = _exports.BANDS_OCTAVE_4TH = _exports.BANDS_OCTAVE_3RD = _exports.BANDS_OCTAVE_24TH = _exports.BANDS_OCTAVE_12TH = _exports.BANDS_FFT = _exports.AudioMotionAnalyzer = _exports.ALPHABARS_ON = _exports.ALPHABARS_OFF = _exports.ALPHABARS_FULL = void 0;
   /**!
    * audioMotion-analyzer
    * High-resolution real-time graphic audio spectrum analyzer JS module
    *
-   * @version 4.5.2
+   * @version 5.0.0-alpha.0
    * @author  Henrique Avila Vianna <hvianna@gmail.com> <https://henriquevianna.com>
    * @license AGPL-3.0-or-later
    */
 
-  const VERSION = '4.5.2';
+  const VERSION = '5.0.0-alpha.0';
 
   // internal constants
   const PI = Math.PI,
@@ -34,161 +34,242 @@
     HALF_PI = PI / 2,
     C_1 = 8.17579892; // frequency for C -1
 
-  const CANVAS_BACKGROUND_COLOR = '#000',
-    CHANNEL_COMBINED = 'dual-combined',
-    CHANNEL_HORIZONTAL = 'dual-horizontal',
-    CHANNEL_SINGLE = 'single',
-    CHANNEL_VERTICAL = 'dual-vertical',
-    COLOR_BAR_INDEX = 'bar-index',
-    COLOR_BAR_LEVEL = 'bar-level',
-    COLOR_GRADIENT = 'gradient',
-    DEBOUNCE_TIMEOUT = 60,
+  const DEBOUNCE_TIMEOUT = 60,
     EVENT_CLICK = 'click',
     EVENT_FULLSCREENCHANGE = 'fullscreenchange',
     EVENT_RESIZE = 'resize',
-    GRADIENT_DEFAULT_BGCOLOR = '#111',
-    FILTER_NONE = '',
-    FILTER_A = 'A',
-    FILTER_B = 'B',
-    FILTER_C = 'C',
-    FILTER_D = 'D',
-    FILTER_468 = '468',
     FONT_FAMILY = 'sans-serif',
     FPS_COLOR = '#0f0',
-    LEDS_UNLIT_COLOR = '#7f7f7f22',
-    MODE_GRAPH = 10,
-    REASON_CREATE = 'create',
-    REASON_FSCHANGE = 'fschange',
-    REASON_LORES = 'lores',
-    REASON_RESIZE = EVENT_RESIZE,
-    REASON_USER = 'user',
-    SCALEX_BACKGROUND_COLOR = '#000c',
-    SCALEX_LABEL_COLOR = '#fff',
-    SCALEX_HIGHLIGHT_COLOR = '#4f4',
-    SCALEY_LABEL_COLOR = '#888',
-    SCALEY_MIDLINE_COLOR = '#555',
-    SCALE_BARK = 'bark',
-    SCALE_LINEAR = 'linear',
-    SCALE_LOG = 'log',
-    SCALE_MEL = 'mel';
-
-  // built-in gradients
+    MIN_AXIS_DIMENSION = 20,
+    OPTION_EMPTY = '',
+    OPTION_OFF = 'off',
+    OPTION_ON = 'on';
+
+  // exported constants
+  const ALPHABARS_FULL = _exports.ALPHABARS_FULL = 'full',
+    ALPHABARS_OFF = _exports.ALPHABARS_OFF = OPTION_OFF,
+    ALPHABARS_ON = _exports.ALPHABARS_ON = OPTION_ON,
+    BANDS_FFT = _exports.BANDS_FFT = 0,
+    BANDS_OCTAVE_FULL = _exports.BANDS_OCTAVE_FULL = 1,
+    BANDS_OCTAVE_HALF = _exports.BANDS_OCTAVE_HALF = 2,
+    BANDS_OCTAVE_3RD = _exports.BANDS_OCTAVE_3RD = 3,
+    BANDS_OCTAVE_4TH = _exports.BANDS_OCTAVE_4TH = 4,
+    BANDS_OCTAVE_6TH = _exports.BANDS_OCTAVE_6TH = 5,
+    BANDS_OCTAVE_8TH = _exports.BANDS_OCTAVE_8TH = 6,
+    BANDS_OCTAVE_12TH = _exports.BANDS_OCTAVE_12TH = 7,
+    BANDS_OCTAVE_24TH = _exports.BANDS_OCTAVE_24TH = 8,
+    COLORMODE_GRADIENT = _exports.COLORMODE_GRADIENT = 'gradient',
+    COLORMODE_INDEX = _exports.COLORMODE_INDEX = 'bar-index',
+    COLORMODE_LEVEL = _exports.COLORMODE_LEVEL = 'bar-level',
+    ENERGY_BASS = _exports.ENERGY_BASS = 'bass',
+    ENERGY_HIGHMID = _exports.ENERGY_HIGHMID = 'highMid',
+    ENERGY_LOWMID = _exports.ENERGY_LOWMID = 'lowMid',
+    ENERGY_MIDRANGE = _exports.ENERGY_MIDRANGE = 'mid',
+    ENERGY_PEAK = _exports.ENERGY_PEAK = 'peak',
+    ENERGY_TREBLE = _exports.ENERGY_TREBLE = 'treble',
+    ERR_AUDIO_CONTEXT_FAIL = _exports.ERR_AUDIO_CONTEXT_FAIL = 1,
+    ERR_INVALID_AUDIO_CONTEXT = _exports.ERR_INVALID_AUDIO_CONTEXT = 2,
+    ERR_INVALID_AUDIO_SOURCE = _exports.ERR_INVALID_AUDIO_SOURCE = 3,
+    FILTER_NONE = _exports.FILTER_NONE = OPTION_EMPTY,
+    FILTER_A = _exports.FILTER_A = 'A',
+    FILTER_B = _exports.FILTER_B = 'B',
+    FILTER_C = _exports.FILTER_C = 'C',
+    FILTER_D = _exports.FILTER_D = 'D',
+    FILTER_468 = _exports.FILTER_468 = '468',
+    LAYOUT_COMBINED = _exports.LAYOUT_COMBINED = 'dual-combined',
+    LAYOUT_HORIZONTAL = _exports.LAYOUT_HORIZONTAL = 'dual-horizontal',
+    LAYOUT_SINGLE = _exports.LAYOUT_SINGLE = 'single',
+    LAYOUT_VERTICAL = _exports.LAYOUT_VERTICAL = 'dual-vertical',
+    LEDS_MODERN = _exports.LEDS_MODERN = 'modern',
+    LEDS_OFF = _exports.LEDS_OFF = OPTION_OFF,
+    LEDS_VINTAGE = _exports.LEDS_VINTAGE = 'vintage',
+    MODE_BARS = _exports.MODE_BARS = 'bars',
+    MODE_GRAPH = _exports.MODE_GRAPH = 'graph',
+    PEAKS_DROP = _exports.PEAKS_DROP = 'drop',
+    PEAKS_FADE = _exports.PEAKS_FADE = 'fade',
+    PEAKS_OFF = _exports.PEAKS_OFF = OPTION_OFF,
+    RADIAL_INNER = _exports.RADIAL_INNER = -1,
+    RADIAL_OFF = _exports.RADIAL_OFF = 0,
+    RADIAL_OUTER = _exports.RADIAL_OUTER = 1,
+    REASON_CREATE = _exports.REASON_CREATE = 'create',
+    REASON_FULLSCREENCHANGE = _exports.REASON_FULLSCREENCHANGE = EVENT_FULLSCREENCHANGE,
+    REASON_LORES = _exports.REASON_LORES = 'lores',
+    REASON_RESIZE = _exports.REASON_RESIZE = EVENT_RESIZE,
+    REASON_USER = _exports.REASON_USER = 'user',
+    SCALE_BARK = _exports.SCALE_BARK = 'bark',
+    SCALE_LINEAR = _exports.SCALE_LINEAR = 'linear',
+    SCALE_LOG = _exports.SCALE_LOG = 'log',
+    SCALE_MEL = _exports.SCALE_MEL = 'mel';
+
+  // built-in color themes
   const PRISM = ['#a35', '#c66', '#e94', '#ed0', '#9d5', '#4d8', '#2cb', '#0bc', '#09c', '#36b'],
-    GRADIENTS = [['classic', {
+    THEMES = [['classic', {
       colorStops: ['red', {
         color: 'yellow',
-        level: .85,
-        pos: .6
+        level: .9
       }, {
         color: 'lime',
-        level: .475
+        level: .6
       }]
+    }], ['mono', {
+      colorStops: ['#eee'],
+      peakColor: 'red'
     }], ['prism', {
       colorStops: PRISM
     }], ['rainbow', {
-      dir: 'h',
       colorStops: ['#817', ...PRISM, '#639']
     }], ['orangered', {
-      bgColor: '#3e2f29',
       colorStops: ['OrangeRed']
     }], ['steelblue', {
-      bgColor: '#222c35',
       colorStops: ['SteelBlue']
     }]];
 
   // settings defaults
   const DEFAULT_SETTINGS = {
-    alphaBars: false,
+    alphaBars: ALPHABARS_OFF,
     ansiBands: false,
+    bandResolution: BANDS_FFT,
     barSpace: 0.1,
-    bgAlpha: 0.7,
-    channelLayout: CHANNEL_SINGLE,
-    colorMode: COLOR_GRADIENT,
-    fadePeaks: false,
+    channelLayout: LAYOUT_SINGLE,
+    colorMode: COLORMODE_GRADIENT,
     fftSize: 8192,
-    fillAlpha: 1,
+    fillAlpha: 0.5,
     frequencyScale: SCALE_LOG,
-    gradient: GRADIENTS[0][0],
-    gravity: 3.8,
     height: undefined,
-    ledBars: false,
+    ledBars: LEDS_OFF,
     linearAmplitude: false,
     linearBoost: 1,
-    lineWidth: 0,
+    lineWidth: 1,
     loRes: false,
-    lumiBars: false,
     maxDecibels: -25,
     maxFPS: 0,
     maxFreq: 22000,
     minDecibels: -85,
     minFreq: 20,
     mirror: 0,
-    mode: 0,
+    mode: MODE_BARS,
     noteLabels: false,
     outlineBars: false,
-    overlay: false,
-    peakFadeTime: 750,
+    peakDecayTime: 750,
     peakHoldTime: 500,
-    peakLine: false,
-    radial: false,
-    radialInvert: false,
-    radius: 0.3,
+    peaks: PEAKS_DROP,
+    peakLine: 0,
+    radial: RADIAL_OFF,
+    radius: 0.5,
     reflexAlpha: 0.15,
     reflexBright: 1,
     reflexFit: true,
     reflexRatio: 0,
     roundBars: false,
-    showBgColor: true,
     showFPS: false,
-    showPeaks: true,
+    showLedMask: true,
     showScaleX: true,
     showScaleY: false,
     smoothing: 0.5,
     spinSpeed: 0,
-    splitGradient: false,
-    start: true,
-    trueLeds: false,
+    spreadGradient: false,
     useCanvas: true,
     volume: 1,
     weightingFilter: FILTER_NONE,
     width: undefined
   };
+  const DEFAULT_LED_PARAMETERS = [8, 8],
+    // ledHeight, gapHeight
+    DEFAULT_LEDMASK_PARAMS = [.2, -1, 20]; // alpha, lightness, saturation
+
+  const DEFAULT_THEME_MODIFIERS = {
+    horizontal: false,
+    reverse: false
+  };
 
   // custom error messages
-  const ERR_AUDIO_CONTEXT_FAIL = ['ERR_AUDIO_CONTEXT_FAIL', 'Could not create audio context. Web Audio API not supported?'],
-    ERR_INVALID_AUDIO_CONTEXT = ['ERR_INVALID_AUDIO_CONTEXT', 'Provided audio context is not valid'],
-    ERR_UNKNOWN_GRADIENT = ['ERR_UNKNOWN_GRADIENT', 'Unknown gradient'],
-    ERR_FREQUENCY_TOO_LOW = ['ERR_FREQUENCY_TOO_LOW', 'Frequency values must be >= 1'],
-    ERR_INVALID_MODE = ['ERR_INVALID_MODE', 'Invalid mode'],
-    ERR_REFLEX_OUT_OF_RANGE = ['ERR_REFLEX_OUT_OF_RANGE', 'Reflex ratio must be >= 0 and < 1'],
-    ERR_INVALID_AUDIO_SOURCE = ['ERR_INVALID_AUDIO_SOURCE', 'Audio source must be an instance of HTMLMediaElement or AudioNode'],
-    ERR_GRADIENT_INVALID_NAME = ['ERR_GRADIENT_INVALID_NAME', 'Gradient name must be a non-empty string'],
-    ERR_GRADIENT_NOT_AN_OBJECT = ['ERR_GRADIENT_NOT_AN_OBJECT', 'Gradient options must be an object'],
-    ERR_GRADIENT_MISSING_COLOR = ['ERR_GRADIENT_MISSING_COLOR', 'Gradient colorStops must be a non-empty array'];
+  const ERROR_MESSAGE = {
+    [ERR_AUDIO_CONTEXT_FAIL]: 'Could not create audio context. Web Audio API not supported?',
+    [ERR_INVALID_AUDIO_CONTEXT]: 'Provided audio context is not valid',
+    [ERR_INVALID_AUDIO_SOURCE]: 'Audio source must be an instance of HTMLMediaElement or AudioNode'
+  };
   class AudioMotionError extends Error {
-    constructor(error, value) {
-      const [code, message] = error;
-      super(message + (value !== undefined ? `: ${value}` : ''));
+    constructor(code, value) {
+      super(ERROR_MESSAGE[code] + (value !== undefined ? `: ${value}` : ''));
       this.name = 'AudioMotionError';
       this.code = code;
     }
   }
 
-  // helper function - output deprecation warning message on console
+  /* helper functions */
+
+  // clamp a given value between `min` and `max`
+  const clamp = (val, min, max) => val <= min ? min : val >= max ? max : val; // TO-DO: handle +val == NaN
+
+  // convert any CSS color format to HSL format
+  const cssColorToHSL = color => {
+    const ctx = document.createElement('canvas').getContext('2d'); // use a canvas to convert any CSS color to RGB format
+    ctx.fillStyle = color;
+    const computedColor = ctx.fillStyle,
+      // hex string (#ffffff) - TO-DO: if original color has alpha channel this will be in rgba() format
+      [r, g, b] = computedColor.match(/[^#]{2}/g).map(n => parseInt(n, 16) / 255),
+      max = Math.max(r, g, b),
+      min = Math.min(r, g, b);
+    let h,
+      s,
+      l = (max + min) / 2;
+    if (max === min) h = s = 0; // achromatic
+    else {
+      const d = max - min;
+      s = l > 0.5 ? d / (2 - max - min) : d / (max + min);
+      switch (max) {
+        case r:
+          h = (g - b) / d + (g < b ? 6 : 0);
+          break;
+        case g:
+          h = (b - r) / d + 2;
+          break;
+        case b:
+          h = (r - g) / d + 4;
+      }
+      h *= 60;
+    }
+    return [h, Math.round(s * 100), Math.round(l * 100)];
+  };
+
+  // deep clone object
+  const deepCloneObject = obj => JSON.parse(JSON.stringify(obj));
+
+  // output deprecation warning message on console
   const deprecate = (name, alternative) => console.warn(`${name} is deprecated. Use ${alternative} instead.`);
 
-  // helper function - check if a given object is empty (also returns `true` on null, undefined or any non-object value)
+  // find the Y-coordinate of a point located between two other points, given its X-coordinate
+  const findY = (x1, y1, x2, y2, x) => y1 + (y2 - y1) * (x - x1) / (x2 - x1);
+
+  // shorthand for Array.isArray()
+  const {
+    isArray
+  } = Array;
+
+  // check if a given object is empty (also returns `true` on null, undefined or any non-object value)
   const isEmpty = obj => {
     for (const p in obj) return false;
     return true;
   };
 
-  // helper function - validate a given value with an array of strings (by default, all lowercase)
+  // check if given value is numeric
+  const isNumeric = val => !isArray(val) && val == +val; // note: +[] == []
+
+  // check if given value is an object (not null or array, which are also considered objects)
+  const isObject = val => typeof val == 'object' && !!val && !isArray(val);
+
+  // check if given value is a valid channel number
+  const isValidChannel = channel => isNumeric(channel) && [0, 1].includes(+channel);
+
+  // validate a given value with an array of strings (by default, all lowercase)
   // returns the validated value, or the first element of `list` if `value` is not found in the array
   const validateFromList = (value, list, modifier = 'toLowerCase') => list[Math.max(0, list.indexOf(('' + value)[modifier]()))];
 
-  // helper function - find the Y-coordinate of a point located between two other points, given its X-coordinate
-  const findY = (x1, y1, x2, y2, x) => y1 + (y2 - y1) * (x - x1) / (x2 - x1);
+  // returns an array with the given channel number if valid, or [0,1] otherwise
+  const validateChannelArray = channel => isValidChannel(channel) ? [+channel] : [0, 1];
+
+  // output invalid value warning message on console
+  const warnInvalid = (name, value) => console.warn(`${name}: ignoring invalid value (${value})`);
 
   // Polyfill for Array.findLastIndex()
   if (!Array.prototype.findLastIndex) {
@@ -201,7 +282,7 @@
     };
   }
 
-  // AudioMotionAnalyzer class
+  /* *********************************** class AudioMotionAnalyzer ************************************ */
 
   class AudioMotionAnalyzer {
     /**
@@ -216,7 +297,8 @@
 
       // Initialize internal objects
       this._aux = {}; // auxiliary variables
-      this._canvasGradients = []; // CanvasGradient objects for channels 0 and 1
+      this._activeThemes = []; // currently active themes for channels 0 and 1 (refer to _makeGrad() for object structure)
+      this._bars = [];
       this._destroyed = false;
       this._energy = {
         val: 0,
@@ -225,12 +307,14 @@
       };
       this._flg = {}; // flags
       this._fps = 0;
-      this._gradients = {}; // registered gradients
       this._last = 0; // timestamp of last rendered frame
+      this._leds = []; // currently effective led attributes (ledCount, ledHeight, ledGap)
       this._outNodes = []; // output nodes
       this._ownContext = false;
-      this._selectedGrads = []; // names of the currently selected gradients for channels 0 and 1
       this._sources = []; // input nodes
+      this._themes = {}; // registered color themes
+      this._xAxis = {}; // X-axis label parameters
+      this._yAxis = {}; // Y-axis label parameters
 
       // Check if options object passed as first argument
       if (!(container instanceof Element)) {
@@ -244,8 +328,8 @@
       canvas.style = 'max-width: 100%;';
       this._ctx = canvas.getContext('2d');
 
-      // Register built-in gradients
-      for (const [name, options] of GRADIENTS) this.registerGradient(name, options);
+      // Register built-in color themes
+      for (const [name, options] of THEMES) this.registerTheme(name, options);
 
       // Set container
       this._container = container || !this._ownCanvas && canvas.parentElement || document.body;
@@ -356,7 +440,7 @@
         if (this._fsTimeout) window.clearTimeout(this._fsTimeout);
 
         // update the canvas
-        this._setCanvas(REASON_FSCHANGE);
+        this._setCanvas(REASON_FULLSCREENCHANGE);
 
         // delay clearing the flag to prevent any shortly following resize event
         this._fsTimeout = window.setTimeout(() => {
@@ -383,9 +467,17 @@
         signal
       });
 
-      // Set configuration options and use defaults for any missing properties
+      // Initialize default properties
+      this.setTheme();
+      this.setXAxis();
+      this.setYAxis();
+
+      // Set configuration options passed to the constructor and use defaults for any missing properties
       this._setProps(options, true);
 
+      // Start the analyzer, unless `start` is explicitly set to false in the options
+      this.toggleAnalyzer(options.start !== false);
+
       // Add canvas to the container (only when canvas not provided by user)
       if (this.useCanvas && this._ownCanvas) this._container.appendChild(canvas);
 
@@ -406,8 +498,9 @@
       return this._alphaBars;
     }
     set alphaBars(value) {
-      this._alphaBars = !!value;
+      this._alphaBars = validateFromList(value, [ALPHABARS_OFF, ALPHABARS_ON, ALPHABARS_FULL]);
       this._calcBars();
+      this._makeGrad();
     }
     get ansiBands() {
       return this._ansiBands;
@@ -416,6 +509,13 @@
       this._ansiBands = !!value;
       this._calcBars();
     }
+    get bandResolution() {
+      return this._bandRes;
+    }
+    set bandResolution(value) {
+      this._bandRes = clamp(value | 0, 0, 8);
+      this._calcBars();
+    }
     get barSpace() {
       return this._barSpace;
     }
@@ -427,15 +527,15 @@
       return this._chLayout;
     }
     set channelLayout(value) {
-      this._chLayout = validateFromList(value, [CHANNEL_SINGLE, CHANNEL_HORIZONTAL, CHANNEL_VERTICAL, CHANNEL_COMBINED]);
+      this._chLayout = validateFromList(value, [LAYOUT_SINGLE, LAYOUT_HORIZONTAL, LAYOUT_VERTICAL, LAYOUT_COMBINED]);
 
       // update node connections
       this._input.disconnect();
-      this._input.connect(this._chLayout != CHANNEL_SINGLE ? this._splitter : this._analyzer[0]);
+      this._input.connect(this._chLayout != LAYOUT_SINGLE ? this._splitter : this._analyzer[0]);
       this._analyzer[0].disconnect();
       if (this._outNodes.length)
         // connect analyzer only if the output is connected to other nodes
-        this._analyzer[0].connect(this._chLayout != CHANNEL_SINGLE ? this._merger : this._output);
+        this._analyzer[0].connect(this._chLayout != LAYOUT_SINGLE ? this._merger : this._output);
       this._calcBars();
       this._makeGrad();
     }
@@ -443,13 +543,7 @@
       return this._colorMode;
     }
     set colorMode(value) {
-      this._colorMode = validateFromList(value, [COLOR_GRADIENT, COLOR_BAR_INDEX, COLOR_BAR_LEVEL]);
-    }
-    get fadePeaks() {
-      return this._fadePeaks;
-    }
-    set fadePeaks(value) {
-      this._fadePeaks = !!value;
+      this._colorMode = validateFromList(value, [COLORMODE_GRADIENT, COLORMODE_INDEX, COLORMODE_LEVEL]);
     }
     get fftSize() {
       return this._analyzer[0].fftSize;
@@ -467,30 +561,6 @@
       this._frequencyScale = validateFromList(value, [SCALE_LOG, SCALE_BARK, SCALE_MEL, SCALE_LINEAR]);
       this._calcBars();
     }
-    get gradient() {
-      return this._selectedGrads[0];
-    }
-    set gradient(value) {
-      this._setGradient(value);
-    }
-    get gradientLeft() {
-      return this._selectedGrads[0];
-    }
-    set gradientLeft(value) {
-      this._setGradient(value, 0);
-    }
-    get gradientRight() {
-      return this._selectedGrads[1];
-    }
-    set gradientRight(value) {
-      this._setGradient(value, 1);
-    }
-    get gravity() {
-      return this._gravity;
-    }
-    set gravity(value) {
-      this._gravity = value > 0 ? +value : this._gravity || DEFAULT_SETTINGS.gravity;
-    }
     get height() {
       return this._height;
     }
@@ -499,10 +569,10 @@
       this._setCanvas(REASON_USER);
     }
     get ledBars() {
-      return this._showLeds;
+      return this._ledBars;
     }
     set ledBars(value) {
-      this._showLeds = !!value;
+      this._ledBars = validateFromList(value, [LEDS_OFF, LEDS_MODERN, LEDS_VINTAGE]);
       this._calcBars();
     }
     get linearAmplitude() {
@@ -530,14 +600,6 @@
       this._loRes = !!value;
       this._setCanvas(REASON_LORES);
     }
-    get lumiBars() {
-      return this._lumiBars;
-    }
-    set lumiBars(value) {
-      this._lumiBars = !!value;
-      this._calcBars();
-      this._makeGrad();
-    }
     get maxDecibels() {
       return this._analyzer[0].maxDecibels;
     }
@@ -554,10 +616,13 @@
       return this._maxFreq;
     }
     set maxFreq(value) {
-      if (value < 1) throw new AudioMotionError(ERR_FREQUENCY_TOO_LOW);else {
-        this._maxFreq = Math.min(value, this.audioCtx.sampleRate / 2);
-        this._calcBars();
+      if (!(value > 0)) {
+        // should catch all 'falsy' and negative values (`value <= 0` would fail on NaN or undefined)
+        warnInvalid('maxFreq', value);
+        value = this._maxFreq || DEFAULT_SETTINGS.maxFreq; // keep previous value, if any
       }
+      this._maxFreq = Math.min(value, this.audioCtx.sampleRate / 2);
+      this._calcBars();
     }
     get minDecibels() {
       return this._analyzer[0].minDecibels;
@@ -569,10 +634,13 @@
       return this._minFreq;
     }
     set minFreq(value) {
-      if (value < 1) throw new AudioMotionError(ERR_FREQUENCY_TOO_LOW);else {
-        this._minFreq = +value;
-        this._calcBars();
+      if (!(value > 0)) {
+        // should catch all 'falsy' and negative values (`value <= 0` would fail on NaN or undefined)
+        warnInvalid('minFreq', value);
+        value = this._minFreq || DEFAULT_SETTINGS.minFreq;
       }
+      this._minFreq = +value;
+      this._calcBars();
     }
     get mirror() {
       return this._mirror;
@@ -586,12 +654,9 @@
       return this._mode;
     }
     set mode(value) {
-      const mode = value | 0;
-      if (mode >= 0 && mode <= 10 && mode != 9) {
-        this._mode = mode;
-        this._calcBars();
-        this._makeGrad();
-      } else throw new AudioMotionError(ERR_INVALID_MODE, value);
+      this._mode = validateFromList(value, [MODE_BARS, MODE_GRAPH]);
+      this._calcBars();
+      this._makeGrad();
     }
     get noteLabels() {
       return this._noteLabels;
@@ -607,37 +672,37 @@
       this._outlineBars = !!value;
       this._calcBars();
     }
-    get peakFadeTime() {
-      return this._peakFadeTime;
+    get peakDecayTime() {
+      return this._peakDecayTime * 1e3;
     }
-    set peakFadeTime(value) {
-      this._peakFadeTime = value >= 0 ? +value : this._peakFadeTime || DEFAULT_SETTINGS.peakFadeTime;
+    set peakDecayTime(value) {
+      // note: time is stored in seconds to reduce the number of operations during rendering
+      this._peakDecayTime = (value >= 0 ? +value : this._peakDecayTime ?? DEFAULT_SETTINGS.peakDecayTime) / 1e3;
     }
     get peakHoldTime() {
-      return this._peakHoldTime;
+      return this._peakHoldTime * 1e3;
     }
     set peakHoldTime(value) {
-      this._peakHoldTime = +value || 0;
+      // note: time is stored in seconds to reduce the number of operations during rendering
+      this._peakHoldTime = +value / 1e3 || 0;
     }
     get peakLine() {
       return this._peakLine;
     }
     set peakLine(value) {
-      this._peakLine = !!value;
+      this._peakLine = +value || 0;
+    }
+    get peaks() {
+      return this._peaks;
+    }
+    set peaks(value) {
+      this._peaks = validateFromList(value, [PEAKS_OFF, PEAKS_DROP, PEAKS_FADE]);
     }
     get radial() {
       return this._radial;
     }
     set radial(value) {
-      this._radial = !!value;
-      this._calcBars();
-      this._makeGrad();
-    }
-    get radialInvert() {
-      return this._radialInvert;
-    }
-    set radialInvert(value) {
-      this._radialInvert = !!value;
+      this._radial = [RADIAL_INNER, RADIAL_OFF, RADIAL_OUTER].includes(+value) ? +value : this._radial ?? DEFAULT_SETTINGS.radial;
       this._calcBars();
       this._makeGrad();
     }
@@ -653,12 +718,14 @@
       return this._reflexRatio;
     }
     set reflexRatio(value) {
-      value = +value || 0;
-      if (value < 0 || value >= 1) throw new AudioMotionError(ERR_REFLEX_OUT_OF_RANGE);else {
-        this._reflexRatio = value;
-        this._calcBars();
-        this._makeGrad();
+      if (!(value >= 0 && value < 1)) {
+        // also catches undefined and strings that evaluate to NaN
+        warnInvalid('reflexRatio', value);
+        value = this._reflexRatio ?? DEFAULT_SETTINGS.reflexRatio;
       }
+      this._reflexRatio = +value;
+      this._calcBars();
+      this._makeGrad();
     }
     get roundBars() {
       return this._roundBars;
@@ -667,6 +734,14 @@
       this._roundBars = !!value;
       this._calcBars();
     }
+    get showScaleX() {
+      return this._sxshow;
+    }
+    set showScaleX(value) {
+      this._sxshow = !!value;
+      this._calcBars();
+      this._makeGrad();
+    }
     get smoothing() {
       return this._analyzer[0].smoothingTimeConstant;
     }
@@ -681,27 +756,13 @@
       if (this._spinSpeed === undefined || value == 0) this._spinAngle = -HALF_PI; // initialize or reset the rotation angle
       this._spinSpeed = value;
     }
-    get splitGradient() {
-      return this._splitGradient;
+    get spreadGradient() {
+      return this._spread;
     }
-    set splitGradient(value) {
-      this._splitGradient = !!value;
+    set spreadGradient(value) {
+      this._spread = !!value;
       this._makeGrad();
     }
-    get stereo() {
-      deprecate('stereo', 'channelLayout');
-      return this._chLayout != CHANNEL_SINGLE;
-    }
-    set stereo(value) {
-      deprecate('stereo', 'channelLayout');
-      this.channelLayout = value ? CHANNEL_VERTICAL : CHANNEL_SINGLE;
-    }
-    get trueLeds() {
-      return this._trueLeds;
-    }
-    set trueLeds(value) {
-      this._trueLeds = !!value;
-    }
     get volume() {
       return this._output.gain.value;
     }
@@ -749,7 +810,7 @@
       return this._fsWidth;
     }
     get isAlphaBars() {
-      return this._flg.isAlpha;
+      return this._flg.isAlpha || this._flg.isLumi;
     }
     get isBandsMode() {
       return this._flg.isBands;
@@ -763,9 +824,6 @@
     get isLedBars() {
       return this._flg.isLeds;
     }
-    get isLumiBars() {
-      return this._flg.isLumi;
-    }
     get isOctaveBands() {
       return this._flg.isOctaves;
     }
@@ -824,7 +882,7 @@
 
       // when connecting the first node, also connect the analyzer nodes to the merger / output nodes
       if (this._outNodes.length == 1) {
-        for (const i of [0, 1]) this._analyzer[i].connect(this._chLayout == CHANNEL_SINGLE && !i ? this._output : this._merger, 0, i);
+        for (const i of [0, 1]) this._analyzer[i].connect(this._chLayout == LAYOUT_SINGLE && !i ? this._output : this._merger, 0, i);
       }
     }
 
@@ -881,7 +939,7 @@
      * @param [{boolean}] if true, stops/releases audio tracks from disconnected media streams (e.g. microphone)
      */
     disconnectInput(sources, stopTracks) {
-      if (!sources) sources = Array.from(this._sources);else if (!Array.isArray(sources)) sources = [sources];
+      if (!sources) sources = Array.from(this._sources);else if (!isArray(sources)) sources = [sources];
       for (const node of sources) {
         const idx = this._sources.indexOf(node);
         if (stopTracks && node.mediaStream) {
@@ -950,20 +1008,20 @@
 
       // if startFreq is a string, check for presets
       if (startFreq != +startFreq) {
-        if (startFreq == 'peak') return this._energy.peak;
+        if (startFreq == ENERGY_PEAK) return this._energy.peak;
         const presets = {
-          bass: [20, 250],
-          lowMid: [250, 500],
-          mid: [500, 2e3],
-          highMid: [2e3, 4e3],
-          treble: [4e3, 16e3]
+          [ENERGY_BASS]: [20, 250],
+          [ENERGY_LOWMID]: [250, 500],
+          [ENERGY_MIDRANGE]: [500, 2e3],
+          [ENERGY_HIGHMID]: [2e3, 4e3],
+          [ENERGY_TREBLE]: [4e3, 16e3]
         };
         if (!presets[startFreq]) return null;
         [startFreq, endFreq] = presets[startFreq];
       }
       const startBin = this._freqToBin(startFreq),
         endBin = endFreq ? this._freqToBin(endFreq) : startBin,
-        chnCount = this._chLayout == CHANNEL_SINGLE ? 1 : 2;
+        chnCount = this._chLayout == LAYOUT_SINGLE ? 1 : 2;
       let energy = 0;
       for (let channel = 0; channel < chnCount; channel++) {
         for (let i = startBin; i <= endBin; i++) energy += this._normalizedB(this._fftData[channel][i]);
@@ -978,59 +1036,135 @@
      * @returns {object} Options object
      */
     getOptions(ignore) {
-      if (!Array.isArray(ignore)) ignore = [ignore];
+      if (!isArray(ignore)) ignore = [ignore];
       let options = {};
       for (const prop of Object.keys(DEFAULT_SETTINGS)) {
-        if (!ignore.includes(prop)) {
-          if (prop == 'gradient' && this.gradientLeft != this.gradientRight) {
-            options.gradientLeft = this.gradientLeft;
-            options.gradientRight = this.gradientRight;
-          } else if (prop != 'start') options[prop] = this[prop];
-        }
+        if (!ignore.includes(prop)) options[prop] = this[prop];
       }
       return options;
     }
 
     /**
-     * Registers a custom gradient
+     * Returns the selected theme for the given channel
+     *
+     * @param [{number}] channel - if undefined or invalid, considers channel 0
+     * @param [{boolean}] `true` to include modifiers
+     * @returns {string|object} theme name, or object with `name` and `modifiers`
+     */
+    getTheme(channel, includeModifiers) {
+      if (channel === true) {
+        channel = 0;
+        includeModifiers = true;
+      } else if (!isValidChannel(channel)) channel = 0;
+      const {
+        name
+      } = this._activeThemes[channel];
+      return includeModifiers ? {
+        name,
+        modifiers: this.getThemeModifiers(channel)
+      } : name;
+    }
+
+    /**
+     * Returns data for the theme with the given name
+     *
+     * @param {string} theme name
+     * @returns {object|null} theme object or null if name is invalid
+     */
+    getThemeData(name) {
+      return this.getThemeList().includes(name) ? Object.fromEntries(Object.entries(this._themes[name]).filter(([key]) => key != 'mask')) : null;
+    }
+
+    /**
+     * Returns the names of available themes
+     *
+     * @returns {array}
+     */
+    getThemeList() {
+      return Object.keys(this._themes);
+    }
+
+    /**
+     * Returns the current state of theme modifiers for the given channel
+     *
+     * @param [{string}] desired modifier - if undefined, returns all modifiers
+     * @param [{number}] channel - if undefined or invalid, considers channel 0
+     * @returns {boolean|object} value of requested modifier, or object with all modifiers
+     */
+    getThemeModifiers(modifier, channel) {
+      if (isNumeric(modifier)) {
+        channel = modifier;
+        modifier = null;
+      }
+      if (!isValidChannel(channel)) channel = 0;
+      const {
+        modifiers
+      } = this._activeThemes[channel];
+      return modifier ? modifiers[modifier] : {
+        ...modifiers
+      };
+    }
+
+    /**
+     * Registers a custom color theme
      *
      * @param {string} name
      * @param {object} options
+     * @returns {boolean} true on success or false on error
      */
-    registerGradient(name, options) {
-      if (typeof name != 'string' || name.trim().length == 0) throw new AudioMotionError(ERR_GRADIENT_INVALID_NAME);
-      if (typeof options != 'object') throw new AudioMotionError(ERR_GRADIENT_NOT_AN_OBJECT);
+    registerTheme(name, options) {
+      const fail = msg => {
+        console.warn(`Cannot register theme "${name}": ${msg}`);
+        return false;
+      };
+      if (typeof name != 'string' || name.trim().length == 0) return fail('name must be a non-empty string');
+      if (!isObject(options)) return fail('options must be an object');
       const {
-        colorStops
-      } = options;
-      if (!Array.isArray(colorStops) || !colorStops.length) throw new AudioMotionError(ERR_GRADIENT_MISSING_COLOR);
+        colorStops,
+        peakColor
+      } = deepCloneObject(options); // avoid modifying user's original object (see discussion #58)
+
+      if (!isArray(colorStops) || !colorStops.length) return fail('colorStops must be a non-empty array');
       const count = colorStops.length,
-        isInvalid = val => +val != val || val < 0 || val > 1;
+        isInvalid = val => +val != clamp(val, 0, 1);
 
-      // normalize all colorStops as objects with `pos`, `color` and `level` properties
+      // normalize all colorStops as objects with `color`, `level` and `pos` properties
       colorStops.forEach((colorStop, index) => {
         const pos = index / Math.max(1, count - 1);
-        if (typeof colorStop != 'object')
+        if (!isObject(colorStop))
           // only color string was defined
           colorStops[index] = {
-            pos,
-            color: colorStop
+            color: colorStop,
+            pos
           };else if (isInvalid(colorStop.pos)) colorStop.pos = pos;
         if (isInvalid(colorStop.level)) colorStops[index].level = 1 - index / count;
       });
 
-      // make sure colorStops is in descending `level` order and that the first one has `level == 1`
-      // this is crucial for proper operation of 'bar-level' colorMode!
-      colorStops.sort((a, b) => a.level < b.level ? 1 : a.level > b.level ? -1 : 0);
+      // important: ensure colorStops is in descending `level` order and the first colorStop has `level: 1`
+      colorStops.sort((a, b) => b.level - a.level);
       colorStops[0].level = 1;
-      this._gradients[name] = {
-        bgColor: options.bgColor || GRADIENT_DEFAULT_BGCOLOR,
-        dir: options.dir,
-        colorStops: colorStops
+
+      // generate the colorstops for the led mask
+
+      const maskColorStops = deepCloneObject(colorStops),
+        [maskAlpha, maskLightness, maskSaturation] = DEFAULT_LEDMASK_PARAMS; // TO-DO: make these customizable
+
+      for (let i = 0; i < count; i++) {
+        const cs = maskColorStops[i],
+          [h, s, l] = cssColorToHSL(cs.color);
+        cs.color = `hsla( ${h}, ${maskSaturation == -1 ? s : maskSaturation}%, ${maskLightness == -1 ? l : maskSaturation}%, ${maskAlpha} )`;
+      }
+      this._themes[name] = {
+        colorStops,
+        mask: {
+          colorStops: maskColorStops
+        },
+        peakColor
       };
 
-      // if the registered gradient is one of the currently selected gradients, regenerate them
-      if (this._selectedGrads.includes(name)) this._makeGrad();
+      // if the registered theme is one of the currently selected ones, regenerate the gradients
+      if (this._activeThemes.some(theme => theme.name == name)) this._makeGrad();
+      return true;
     }
 
     /**
@@ -1052,28 +1186,26 @@
      * @param {number} max highest frequency represented in the x-axis
      */
     setFreqRange(min, max) {
-      if (min < 1 || max < 1) throw new AudioMotionError(ERR_FREQUENCY_TOO_LOW);else {
+      if (!(min > 0 && max > 0))
+        // also catches undefined and strings that evaluate to NaN
+        warnInvalid('setFreqRange', [min, max]);else {
         this._minFreq = Math.min(min, max);
         this.maxFreq = Math.max(min, max); // use the setter for maxFreq
       }
     }
 
     /**
-     * Set custom parameters for LED effect
-     * If called with no arguments or if any property is invalid, clears any previous custom parameters
+     * Set custom parameters for ledBars effect
+     * If called with no arguments or if any value is invalid, resets both parameters to the defaults
      *
-     * @param {object} [params]
+     * @param {number} height of each led element (in pixels)
+     * @param {number} vertical gap between led elements (in pixels)
      */
-    setLedParams(params) {
-      let maxLeds, spaceV, spaceH;
-
+    setLeds(ledHeight, gapHeight) {
       // coerce parameters to Number; `NaN` results are rejected in the condition below
-      if (params) {
-        maxLeds = params.maxLeds | 0,
-        // ensure integer
-        spaceV = +params.spaceV, spaceH = +params.spaceH;
-      }
-      this._ledParams = maxLeds > 0 && spaceV > 0 && spaceH >= 0 ? [maxLeds, spaceV, spaceH] : undefined;
+      ledHeight = +ledHeight;
+      gapHeight = +gapHeight;
+      this._ledParams = ledHeight >= 0 && gapHeight >= 0 ? [ledHeight, gapHeight] : undefined;
       this._calcBars();
     }
 
@@ -1099,6 +1231,136 @@
       }
     }
 
+    /**
+     * Set color theme
+     *
+     * @param {string|object|array} theme name, theme object as returned by getTheme(), or array of such types
+     * @param [{object}] theme modifiers, as returned by getThemeModifiers() (only when first argument is a string)
+     * @param [{number}] desired channel (0 or 1) - if empty or invalid, sets both channels (ignored when first argument is an array)
+     */
+    setTheme(...args) {
+      // if first argument is an array, make recursive calls for each channel
+      if (isArray(args[0])) {
+        for (let ch = 0; ch < Math.max(2, args[0].length); ch++) this.setTheme(args[0][ch], ch);
+        return;
+      }
+      const {
+          name,
+          modifiers
+        } = isObject(args[0]) ? args[0] : {
+          name: args[0],
+          modifiers: isObject(args[1]) ? args[1] : null
+        },
+        channel = args[2] ?? args[1],
+        themeNames = this.getThemeList(),
+        isNameValid = themeNames.includes(name);
+      for (const ch of validateChannelArray(channel)) {
+        if (!this._activeThemes[ch]) this._activeThemes[ch] = {
+          modifiers: {
+            ...DEFAULT_THEME_MODIFIERS
+          }
+        }; // creates new entry (during constructor initialization)
+
+        this._activeThemes[ch].name = isNameValid ? name : this._activeThemes[ch].name || themeNames[0];
+      }
+      if (modifiers) this.setThemeModifiers(modifiers, channel);else this._makeGrad();
+    }
+
+    /**
+     * Set theme modifiers
+     *
+     * @param [{string|object}] modifier name or modifiers object; if null or undefined resets to defaults
+     * @param [{boolean}] desired value when setting a single modifier
+     * @param [{number}] channel (0 or 1) - if empty or invalid, sets modifiers on both channels
+     */
+    setThemeModifiers(modifier, value, channel) {
+      const validKeys = Object.keys(DEFAULT_THEME_MODIFIERS);
+      if (modifier === null || modifier === undefined) {
+        modifier = {}; // will reset to defaults
+        channel = value; // optional
+      } else if (isNumeric(modifier)) {
+        channel = modifier; // only channel passed
+        modifier = {}; // will reset to defaults
+      } else if (isObject(modifier)) {
+        channel = value;
+        modifier = deepCloneObject(modifier); // make a copy, so we don't change user's original object
+
+        // remove invalid modifiers and ensure all values are boolean
+        for (const key of Object.keys(modifier)) {
+          if (validKeys.includes(key)) modifier[key] = !!modifier[key];else delete modifier[key];
+        }
+      } else if (!validKeys.includes(modifier))
+        // validates single modifier
+        return;
+      for (const ch of validateChannelArray(channel)) {
+        const activeThemeData = this._activeThemes[ch];
+        if (isObject(modifier)) {
+          // when passed an object, any modifier not present will be reset to its default value!
+          activeThemeData.modifiers = {
+            ...DEFAULT_THEME_MODIFIERS,
+            ...modifier
+          };
+        } else activeThemeData.modifiers[modifier] = !!value;
+      }
+      this._makeGrad();
+    }
+
+    /**
+     * Customize X-Axis display
+     *
+     * @param {object} options
+     */
+    setXAxis(options) {
+      const defaultOptions = {
+        addLabels: false,
+        backgroundColor: '#0008',
+        color: '#fff',
+        height: .03,
+        highlightColor: '#4f4',
+        labels: [],
+        overlay: false
+      };
+      this._xAxis = {
+        ...defaultOptions,
+        // if `options` is valid, add its properties on top of current settings; otherwise keep just the defaults
+        ...(isObject(options) ? {
+          ...this._xAxis,
+          ...options
+        } : [])
+      };
+      this._calcBars(); // note that changes to `height` and `overlay` affect usable canvas height
+      this._makeGrad();
+    }
+
+    /**
+     * Customize Y-axis display
+     *
+     * @param {object} options
+     */
+    setYAxis(options) {
+      const defaultOptions = {
+        color: '#888',
+        dbInterval: 10,
+        linearInterval: 20,
+        lineDash: [2, 4],
+        operation: 'destination-over',
+        showSubdivisions: true,
+        showUnit: true,
+        subLineColor: '#555',
+        subLineDash: [2, 8],
+        width: .03
+      };
+      this._yAxis = {
+        ...defaultOptions,
+        // if `options` is valid, add its properties on top of current settings; otherwise keep just the defaults
+        ...(isObject(options) ? {
+          ...this._yAxis,
+          ...options
+        } : [])
+      };
+      this._calcBars(); // only to compute yAxisWidth - TO-DO: improve this?
+    }
+
     /**
      * Start the analyzer
      */
@@ -1122,14 +1384,11 @@
     toggleAnalyzer(force) {
       const hasStarted = this.isOn;
       if (force === undefined) force = !hasStarted;
-
-      // Stop the analyzer if it was already running and must be disabled
       if (hasStarted && !force) {
-        cancelAnimationFrame(this._runId);
-        this._runId = 0;
-      }
-      // Start the analyzer if it was stopped and must be enabled
-      else if (!hasStarted && force && !this._destroyed) {
+        // Stop the analyzer if it was already running and must be disabled
+        this._runId = cancelAnimationFrame(this._runId);
+      } else if (!hasStarted && force && !this._destroyed) {
+        // Start the analyzer if it was stopped and must be enabled
         this._frames = 0;
         this._time = performance.now();
         this._runId = requestAnimationFrame(timestamp => this._draw(timestamp)); // arrow function preserves the scope of *this*
@@ -1150,6 +1409,27 @@
       }
     }
 
+    /**
+     * Toggle a theme modifier
+     *
+     * @param {string} modifier name
+     * @param [{number}] channel (0 or 1) - if empty or invalid, toggles modifier on both channels
+     */
+    toggleThemeModifier(modifier, channel) {
+      for (const ch of validateChannelArray(channel)) this.setThemeModifiers(modifier, !this.getThemeModifiers(modifier, channel), channel);
+    }
+
+    /**
+     * Unregisters a color theme
+     *
+     * @param {string} name
+     * @return {boolean} `true` on success or `false` if theme is not registered or in use
+     */
+    unregisterTheme(name) {
+      if (!this.getThemeList().includes(name) || this._activeThemes.some(theme => theme.name == name)) return false;
+      return delete this._themes[name];
+    }
+
     /**
      * ==========================================================================
      *
@@ -1169,23 +1449,11 @@
      * Compute all internal data required for the analyzer, based on its current settings
      */
     _calcBars() {
-      const bars = this._bars = []; // initialize object property
-
-      if (!this._ready) {
-        this._flg = {
-          isAlpha: false,
-          isBands: false,
-          isLeds: false,
-          isLumi: false,
-          isOctaves: false,
-          isOutline: false,
-          isRound: false,
-          noLedGap: false
-        };
-        return;
-      }
+      if (!this._ready) return;
       const {
+          _alphaBars,
           _ansiBands,
+          _bandRes,
           _barSpace,
           canvas,
           _chLayout,
@@ -1193,39 +1461,45 @@
           _minFreq,
           _mirror,
           _mode,
+          _pixelRatio,
           _radial,
-          _radialInvert,
-          _reflexRatio
+          _reflexRatio,
+          _xAxis,
+          _yAxis
         } = this,
+        bars = [],
         centerX = canvas.width >> 1,
         centerY = canvas.height >> 1,
-        isDualVertical = _chLayout == CHANNEL_VERTICAL && !_radial,
-        isDualHorizontal = _chLayout == CHANNEL_HORIZONTAL,
+        isDualVertical = _chLayout == LAYOUT_VERTICAL && !_radial,
+        isDualHorizontal = _chLayout == LAYOUT_HORIZONTAL,
+        minCanvasDimension = Math.min(canvas.width, canvas.height),
+        xAxisHeight = Math.max(MIN_AXIS_DIMENSION * _pixelRatio, _xAxis.height * (_xAxis.height > 1 ? _pixelRatio : minCanvasDimension) | 0),
+        yAxisWidth = Math.max(MIN_AXIS_DIMENSION * _pixelRatio, _yAxis.width * (_yAxis.width > 1 ? _pixelRatio : minCanvasDimension) | 0),
+        scaleGap = xAxisHeight * (!_xAxis.overlay && this._sxshow),
         // COMPUTE FLAGS
 
-        isBands = _mode % 10 != 0,
-        // true for modes 1 to 9
+        isAlpha = _alphaBars == ALPHABARS_ON && _mode == MODE_BARS,
+        isBands = _bandRes > 0,
         isOctaves = isBands && this._frequencyScale == SCALE_LOG,
-        isLeds = this._showLeds && isBands && !_radial,
-        isLumi = this._lumiBars && isBands && !_radial,
-        isAlpha = this._alphaBars && !isLumi && _mode != MODE_GRAPH,
-        isOutline = this._outlineBars && isBands && !isLumi && !isLeds,
-        isRound = this._roundBars && isBands && !isLumi && !isLeds,
-        noLedGap = _chLayout != CHANNEL_VERTICAL || _reflexRatio > 0 && !isLumi,
+        isLeds = this._ledBars != LEDS_OFF && isBands && !_radial && _mode == MODE_BARS,
+        isLumi = _alphaBars == ALPHABARS_FULL && _mode == MODE_BARS,
+        isOutline = this._outlineBars && _mode == MODE_BARS && isBands && !isLumi && !isLeds,
+        isRound = this._roundBars && _mode == MODE_BARS && isBands && !isLumi && !isLeds,
+        noLedGap = _chLayout != LAYOUT_VERTICAL || _reflexRatio > 0 && !isLumi || scaleGap > 0,
         // COMPUTE AUXILIARY VALUES
 
         // channelHeight is the total canvas height dedicated to each channel, including the reflex area, if any)
         channelHeight = canvas.height - (isDualVertical && !isLeds ? .5 : 0) >> isDualVertical,
         // analyzerHeight is the effective height used to render the analyzer, excluding the reflex area
-        analyzerHeight = channelHeight * (isLumi || _radial ? 1 : 1 - _reflexRatio) | 0,
+        analyzerHeight = (channelHeight - scaleGap) * (isLumi || _radial ? 1 : 1 - _reflexRatio) | 0,
         analyzerWidth = canvas.width - centerX * (isDualHorizontal || _mirror != 0),
         // channelGap is **0** if isLedDisplay == true (LEDs already have spacing); **1** if canvas height is odd (windowed); **2** if it's even
-        // TODO: improve this, make it configurable?
+        // TO-DO: improve this, make it configurable?
         channelGap = isDualVertical ? canvas.height - channelHeight * 2 : 0,
         initialX = centerX * (_mirror == -1 && !isDualHorizontal && !_radial);
-      let innerRadius = Math.min(canvas.width, canvas.height) * .375 * (_chLayout == CHANNEL_VERTICAL ? 1 : this._radius) | 0,
+      let innerRadius = minCanvasDimension * .375 * (_chLayout == LAYOUT_VERTICAL ? 1 : this._radius) | 0,
         outerRadius = Math.min(centerX, centerY);
-      if (_radialInvert && _chLayout != CHANNEL_VERTICAL) [innerRadius, outerRadius] = [outerRadius, innerRadius];
+      if (_radial == RADIAL_INNER && _chLayout != LAYOUT_VERTICAL) [innerRadius, outerRadius] = [outerRadius, innerRadius];
 
       /**
        *	CREATE ANALYZER BANDS
@@ -1256,7 +1530,7 @@
       //   ratioHi,
       //   peak,    // peak value
       //   hold,    // peak hold frames (negative value indicates peak falling / fading)
-      //   alpha,   // peak alpha (used by fadePeaks)
+      //   alpha,   // peak alpha (used to fade peaks)
       //   value    // current bar value
       // }
       const barsPush = args => bars.push({
@@ -1314,7 +1588,7 @@
 
         // ANSI standard octave bands use the base-10 frequency ratio, as preferred by [ANSI S1.11-2004, p.2]
         // The equal-tempered scale uses the base-2 ratio
-        const bands = [0, 24, 12, 8, 6, 4, 3, 2, 1][_mode],
+        const bands = [0, 1, 2, 3, 4, 6, 8, 12, 24][_bandRes],
           bandWidth = _ansiBands ? 10 ** (3 / (bands * 10)) : 2 ** (1 / bands),
           // 10^(3/10N) or 2^(1/N)
           halfBand = bandWidth ** .5;
@@ -1369,7 +1643,7 @@
       } else if (isBands) {
         // a bands mode is selected, but frequency scale is not logarithmic
 
-        const bands = [0, 24, 12, 8, 6, 4, 3, 2, 1][_mode] * 10;
+        const bands = [0, 1, 2, 3, 4, 6, 8, 12, 24][_bandRes] * 10;
         const invFreqScaling = x => {
           switch (this._frequencyScale) {
             case SCALE_BARK:
@@ -1435,6 +1709,8 @@
           }
         }
       }
+      const barSpacePx = Math.min(barWidth - 1, _barSpace * (_barSpace > 0 && _barSpace < 1 ? barWidth : 1));
+      if (isBands) barWidth -= Math.max(0, barSpacePx);
 
       /**
        *  COMPUTE ATTRIBUTES FOR THE LED BARS
@@ -1445,68 +1721,46 @@
        *		noLedGap
        *
        *	GENERATES:
-       * 		spaceH
-       * 		spaceV
        *		this._leds
        */
 
-      let spaceH = 0,
-        spaceV = 0;
       if (isLeds) {
-        // adjustment for high pixel-ratio values on low-resolution screens (Android TV)
-        const dPR = this._pixelRatio / (window.devicePixelRatio > 1 && window.screen.height <= 540 ? 2 : 1);
-        const params = [[], [128, 3, .45],
-        // mode 1
-        [128, 4, .225],
-        // mode 2
-        [96, 6, .225],
-        // mode 3
-        [80, 6, .225],
-        // mode 4
-        [80, 6, .125],
-        // mode 5
-        [64, 6, .125],
-        // mode 6
-        [48, 8, .125],
-        // mode 7
-        [24, 16, .125] // mode 8
-        ];
-
-        // use custom LED parameters if set, or the default parameters for the current mode
-        const customParams = this._ledParams,
-          [maxLeds, spaceVRatio, spaceHRatio] = customParams || params[_mode];
-        let ledCount,
-          maxHeight = analyzerHeight;
-        if (customParams) {
-          const minHeight = 2 * dPR;
-          let blockHeight;
-          ledCount = maxLeds + 1;
-          do {
-            ledCount--;
-            blockHeight = maxHeight / ledCount / (1 + spaceVRatio);
-            spaceV = blockHeight * spaceVRatio;
-          } while ((blockHeight < minHeight || spaceV < minHeight) && ledCount > 1);
-        } else {
-          // calculate vertical spacing - aim for the reference ratio, but make sure it's at least 2px
-          const refRatio = 540 / spaceVRatio;
-          spaceV = Math.min(spaceVRatio * dPR, Math.max(2, maxHeight / refRatio + .1 | 0));
+        // adjustment for high pixel-ratio values reported on low-resolution screens (Android TV)
+        const dPR = _pixelRatio / (window.devicePixelRatio > 1 && window.screen.height <= 540 ? 2 : 1);
+        let [ledHeight, ledGap] = (this._ledParams || DEFAULT_LED_PARAMETERS).map(v => v * dPR),
+          isSquareLeds = ledHeight == 0;
+        if (isSquareLeds) ledHeight = barWidth;
+        if (ledGap == 0) ledGap = barSpacePx; // matches gapHeight to bar spacing
+
+        let maxHeight = analyzerHeight + (noLedGap ? ledGap : 0),
+          // if noLedGap is true, add one extra gap height so the last gap is off-screen
+          elemHeight = ledHeight + ledGap,
+          // height of one LED element + gap (defined by user)
+          ledCount = maxHeight / elemHeight | 0,
+          // how many LED elements fit in the available canvas height
+          unitHeight = maxHeight / ledCount; // height of one LED element + gap (adjusted to fit canvas height)
+
+        if (isSquareLeds || ledGap > ledHeight) {
+          // for square LEDs, or when ledGap is higher than ledHeight
+          ledGap = unitHeight * (1 - ledHeight / unitHeight); // adjust ledGap, preserve user-defined ledHeight (only needs minor adjustment when noLedGap is true)
+          if (noLedGap) {
+            // when ledGap changes, more adjustments are necessary for noLedGap
+            const ledBarHeight = (ledHeight + ledGap) * ledCount,
+              // height of full LED bar
+              newMaxHeight = analyzerHeight + ledGap; // height it needs to be
+            ledGap += (newMaxHeight - ledBarHeight) / ledCount; // distribute the difference across all gaps
+            unitHeight = (analyzerHeight + ledGap) / ledCount; // update unitHeight with new ledGap, for ledHeight adjustment below
+          }
         }
 
-        // remove the extra spacing below the last line of LEDs
-        if (noLedGap) maxHeight += spaceV;
-
-        // recalculate the number of leds, considering the effective spaceV
-        if (!customParams) ledCount = Math.min(maxLeds, maxHeight / (spaceV * 2) | 0);
-        spaceH = spaceHRatio >= 1 ? spaceHRatio : barWidth * spaceHRatio;
-        this._leds = [ledCount, spaceH, spaceV, maxHeight / ledCount - spaceV // ledHeight
-        ];
+        // adjust ledHeight (user-defined ledGap is preserved when less than or equal to ledHeight)
+        ledHeight = unitHeight * (1 - ledGap / unitHeight);
+        this._leds = [ledCount, ledHeight, ledGap];
       }
 
       // COMPUTE ADDITIONAL BAR POSITIONING, ACCORDING TO THE CURRENT SETTINGS
-      // uses: _barSpace, barWidth, spaceH
+      // uses: _barSpace, barWidth
 
-      const barSpacePx = Math.min(barWidth - 1, _barSpace * (_barSpace > 0 && _barSpace < 1 ? barWidth : 1));
-      if (isBands) barWidth -= Math.max(isLeds ? spaceH : 0, barSpacePx);
       bars.forEach((bar, index) => {
         let posX = bar.posX,
           width = barWidth;
@@ -1522,20 +1776,21 @@
               posX--;
               width++;
             }
-          } else posX += Math.max(isLeds ? spaceH : 0, barSpacePx) / 2;
+          } else posX += Math.max(0, barSpacePx) / 2;
           bar.posX = posX; // update
         }
         bar.barCenter = posX + (barWidth == 1 ? 0 : width / 2);
         bar.width = width;
       });
 
-      // COMPUTE CHANNEL COORDINATES (uses spaceV)
+      // COMPUTE CHANNEL COORDINATES
 
-      const channelCoords = [];
+      const channelCoords = [],
+        [,, ledGap] = this._leds;
       for (const channel of [0, 1]) {
-        const channelTop = _chLayout == CHANNEL_VERTICAL ? (channelHeight + channelGap) * channel : 0,
+        const channelTop = _chLayout == LAYOUT_VERTICAL ? (channelHeight + channelGap) * channel : 0,
           channelBottom = channelTop + channelHeight,
-          analyzerBottom = channelTop + analyzerHeight - (!isLeds || noLedGap ? 0 : spaceV);
+          analyzerBottom = channelTop + analyzerHeight - (!isLeds || noLedGap ? 0 : ledGap);
         channelCoords.push({
           channelTop,
           channelBottom,
@@ -1544,7 +1799,7 @@
       }
 
       // SAVE INTERNAL PROPERTIES
-
+      this._bars = bars;
       this._aux = {
         analyzerHeight,
         analyzerWidth,
@@ -1557,7 +1812,9 @@
         innerRadius,
         outerRadius,
         scaleMin,
-        unitWidth
+        unitWidth,
+        xAxisHeight,
+        yAxisWidth
       };
       this._flg = {
         isAlpha,
@@ -1570,7 +1827,7 @@
         noLedGap
       };
 
-      // generate the X-axis and radial scales
+      // generate X-axis and radial scale labels
       this._createScales();
     }
 
@@ -1584,7 +1841,8 @@
           initialX,
           innerRadius,
           scaleMin,
-          unitWidth
+          unitWidth,
+          xAxisHeight
         } = this._aux,
         {
           canvas,
@@ -1593,44 +1851,58 @@
           _noteLabels,
           _radial,
           _scaleX,
-          _scaleR
+          _scaleR,
+          _xAxis
         } = this,
         canvasX = _scaleX.canvas,
         canvasR = _scaleR.canvas,
-        freqLabels = [],
-        isDualHorizontal = this._chLayout == CHANNEL_HORIZONTAL,
-        isDualVertical = this._chLayout == CHANNEL_VERTICAL,
-        minDimension = Math.min(canvas.width, canvas.height),
+        freqLabels = isArray(_xAxis.labels) && !_noteLabels ? [..._xAxis.labels] : [],
+        isDualHorizontal = this._chLayout == LAYOUT_HORIZONTAL,
+        isDualVertical = this._chLayout == LAYOUT_VERTICAL,
+        minCanvasDimension = Math.min(canvas.width, canvas.height),
         scale = ['C',, 'D',, 'E', 'F',, 'G',, 'A',, 'B'],
         // for note labels (no sharp notes)
-        scaleHeight = minDimension / 34 | 0,
+        radialScaleHeight = minCanvasDimension / 34 | 0,
         // circular scale height (radial mode)
-        fontSizeX = canvasX.height >> 1,
-        fontSizeR = scaleHeight >> 1,
-        labelWidthX = fontSizeX * (_noteLabels ? .7 : 1.5),
+        fontSizeR = radialScaleHeight >> 1,
+        fontSizeX = xAxisHeight >> 1,
         labelWidthR = fontSizeR * (_noteLabels ? 1 : 2),
+        labelWidthX = fontSizeX * (_noteLabels ? .7 : 1.5),
         root12 = 2 ** (1 / 12);
-      if (!_noteLabels && (this._ansiBands || _frequencyScale != SCALE_LOG)) {
-        freqLabels.push(16, 31.5, 63, 125, 250, 500, 1e3, 2e3, 4e3);
-        if (_frequencyScale == SCALE_LINEAR) freqLabels.push(6e3, 8e3, 10e3, 12e3, 14e3, 16e3, 18e3, 20e3, 22e3);else freqLabels.push(8e3, 16e3);
-      } else {
-        let freq = C_1;
-        for (let octave = -1; octave < 11; octave++) {
-          for (let note = 0; note < 12; note++) {
-            if (freq >= this._minFreq && freq <= this._maxFreq) {
-              const pitch = scale[note],
-                isC = pitch == 'C';
-              if (pitch && _noteLabels && !_mirror && !isDualHorizontal || isC) freqLabels.push(_noteLabels ? [freq, pitch + (isC ? octave : '')] : freq);
+
+      // helper function - format a value using compact engineering notation (e.g.: 1000 -> 1k, 16700 -> 16k7)
+      const formatLabel = f => f < 1e3 ? f | 0 : (f / 1e3).toFixed(1).replace(/([\.])([\d])$/, (m, p1, p2) => 'k' + (+p2 || ''));
+
+      // generate labels if not customized via setXAxis()
+      if (!freqLabels.length || _xAxis.addLabels) {
+        if (!_noteLabels && (this._ansiBands || _frequencyScale != SCALE_LOG)) {
+          freqLabels.push(16, 31.5, 63, 125, 250, 500, 1e3, 2e3, 4e3);
+          if (_frequencyScale == SCALE_LINEAR) freqLabels.push(6e3, 8e3, 10e3, 12e3, 14e3, 16e3, 18e3, 20e3, 22e3);else freqLabels.push(8e3, 16e3);
+        } else {
+          let freq = C_1;
+          for (let octave = -1; octave < 11; octave++) {
+            for (let note = 0; note < 12; note++) {
+              if (freq >= this._minFreq && freq <= this._maxFreq) {
+                const pitch = scale[note],
+                  isC = pitch == 'C';
+                if (pitch && _noteLabels && !_mirror && !isDualHorizontal || isC) {
+                  const highlight = isC && !_mirror && !isDualHorizontal;
+                  freqLabels.push(_noteLabels ? [freq, pitch + (isC ? octave : ''), highlight] : freq);
+                }
+              }
+              freq *= root12;
             }
-            freq *= root12;
           }
         }
       }
 
+      // make sure labels added via setXAxis() are in asceding order
+      freqLabels.sort((a, b) => (isArray(a) ? a[0] : a) - (isArray(b) ? b[0] : b));
+
       // in radial dual-vertical layout, the scale is positioned exactly between both channels, by making the canvas a bit larger than the inner diameter
-      canvasR.width = canvasR.height = Math.max(minDimension * .15, (innerRadius << 1) + isDualVertical * scaleHeight);
+      canvasR.width = canvasR.height = Math.max(minCanvasDimension * .15, (innerRadius << 1) + isDualVertical * radialScaleHeight);
       const centerR = canvasR.width >> 1,
-        radialY = centerR - scaleHeight * .7; // vertical position of text labels in the circular scale
+        radialY = centerR - radialScaleHeight * .7; // vertical position of text labels in the circular scale
 
       // helper function
       const radialLabel = (x, label) => {
@@ -1646,28 +1918,31 @@
         _scaleR.restore();
       };
 
-      // clear scale canvas
-      canvasX.width |= 0;
-      _scaleX.fillStyle = _scaleR.strokeStyle = SCALEX_BACKGROUND_COLOR;
-      _scaleX.fillRect(0, 0, canvasX.width, canvasX.height);
-      _scaleR.arc(centerR, centerR, centerR - scaleHeight / 2, 0, TAU);
-      _scaleR.lineWidth = scaleHeight;
-      _scaleR.stroke();
-      _scaleX.fillStyle = _scaleR.fillStyle = SCALEX_LABEL_COLOR;
+      // update scale canvas dimensions and clear it
+      canvasX.width = canvas.width;
+      canvasX.height = xAxisHeight;
+      if (_xAxis.backgroundColor) {
+        _scaleX.fillStyle = _scaleR.strokeStyle = _xAxis.backgroundColor;
+        _scaleX.fillRect(0, 0, canvasX.width, canvasX.height);
+        _scaleR.arc(centerR, centerR, centerR - radialScaleHeight / 2, 0, TAU);
+        _scaleR.lineWidth = radialScaleHeight;
+        _scaleR.stroke();
+      }
+      _scaleX.fillStyle = _scaleR.fillStyle = _xAxis.color;
       _scaleX.font = `${fontSizeX}px ${FONT_FAMILY}`;
       _scaleR.font = `${fontSizeR}px ${FONT_FAMILY}`;
       _scaleX.textAlign = _scaleR.textAlign = 'center';
       let prevX = -labelWidthX / 4,
         prevR = -labelWidthR;
       for (const item of freqLabels) {
-        const [freq, label] = Array.isArray(item) ? item : [item, item < 1e3 ? item | 0 : `${(item / 100 | 0) / 10}k`],
+        const [freq, label, highlight] = isArray(item) ? item : [item, formatLabel(item)],
           x = unitWidth * (this._freqScaling(freq) - scaleMin),
           y = canvasX.height * .75,
           isC = label[0] == 'C',
           maxW = fontSizeX * (_noteLabels && !_mirror && !isDualHorizontal ? isC ? 1.2 : .6 : 3);
 
         // set label color - no highlight when mirror effect is active (only Cs displayed)
-        _scaleX.fillStyle = _scaleR.fillStyle = isC && !_mirror && !isDualHorizontal ? SCALEX_HIGHLIGHT_COLOR : SCALEX_LABEL_COLOR;
+        _scaleX.fillStyle = _scaleR.fillStyle = highlight ? _xAxis.highlightColor : _xAxis.color;
 
         // prioritizes which note labels are displayed, due to the restricted space on some ranges/scales
         if (_noteLabels) {
@@ -1728,13 +2003,10 @@
 
       const {
           isAlpha,
-          isBands,
           isLeds,
           isLumi,
-          isOctaves,
           isOutline,
-          isRound,
-          noLedGap
+          isRound
         } = this._flg,
         {
           analyzerHeight,
@@ -1745,17 +2017,18 @@
           channelGap,
           initialX,
           innerRadius,
-          outerRadius
+          outerRadius,
+          xAxisHeight,
+          yAxisWidth
         } = this._aux,
         {
+          _activeThemes,
           _bars,
           canvas,
-          _canvasGradients,
           _chLayout,
           _colorMode,
           _ctx,
           _energy,
-          _fadePeaks,
           fillAlpha,
           _fps,
           _linearAmplitude,
@@ -1764,32 +2037,34 @@
           minDecibels,
           _mirror,
           _mode,
-          overlay,
+          _peakLine,
+          _peaks,
           _radial,
-          showBgColor,
-          showPeaks,
+          showLedMask,
+          _sxshow,
           useCanvas,
-          _weightingFilter
+          _weightingFilter,
+          _xAxis,
+          _yAxis
         } = this,
+        [ledCount, ledHeight, ledGap] = this._leds,
         canvasX = this._scaleX.canvas,
         canvasR = this._scaleR.canvas,
-        fadeFrames = _fps * this._peakFadeTime / 1e3,
-        fpsSquared = _fps ** 2,
-        gravity = this._gravity * 1e3,
-        holdFrames = _fps * this._peakHoldTime / 1e3,
-        isDualCombined = _chLayout == CHANNEL_COMBINED,
-        isDualHorizontal = _chLayout == CHANNEL_HORIZONTAL,
-        isDualVertical = _chLayout == CHANNEL_VERTICAL,
-        isSingle = _chLayout == CHANNEL_SINGLE,
-        isTrueLeds = isLeds && this._trueLeds && _colorMode == COLOR_GRADIENT,
+        holdFrames = _fps * this._peakHoldTime,
+        isDualCombined = _chLayout == LAYOUT_COMBINED,
+        isDualHorizontal = _chLayout == LAYOUT_HORIZONTAL,
+        isDualVertical = _chLayout == LAYOUT_VERTICAL,
+        isGraphMode = _mode == MODE_GRAPH,
+        isSingle = _chLayout == LAYOUT_SINGLE,
+        isVintageLeds = isLeds && this._ledBars == LEDS_VINTAGE && _colorMode == COLORMODE_GRADIENT,
         analyzerWidth = _radial ? canvas.width : this._aux.analyzerWidth,
         finalX = initialX + analyzerWidth,
-        showPeakLine = showPeaks && this._peakLine && _mode == MODE_GRAPH,
+        showPeaks = _peaks != PEAKS_OFF,
+        showPeakLine = showPeaks && _peakLine > 0 && isGraphMode,
         maxBarHeight = _radial ? outerRadius - innerRadius : analyzerHeight,
-        nominalMaxHeight = maxBarHeight / this._pixelRatio,
-        // for consistent gravity on lo-res or hi-dpi
         dbRange = maxDecibels - minDecibels,
-        [ledCount, ledSpaceH, ledSpaceV, ledHeight] = this._leds || [];
+        decayRate = 2 / this._peakDecayTime ** 2 / _fps ** 2,
+        ledUnitHeight = ledHeight + ledGap;
       if (_energy.val > 0 && _fps > 0) this._spinAngle += this._spinSpeed * TAU / 60 / _fps; // spinSpeed * angle increment per frame for 1 RPM
 
       /* HELPER FUNCTIONS */
@@ -1797,13 +2072,14 @@
       // create Reflex effect
       const doReflex = channel => {
         if (this._reflexRatio > 0 && !isLumi && !_radial) {
+          const scaleHeight = xAxisHeight * (!_xAxis.overlay && _sxshow);
           let posY, height;
           if (this.reflexFit || isDualVertical) {
-            // always fit reflex in vertical stereo mode
+            // always fit reflex in dual-vertical mode
             posY = isDualVertical && channel == 0 ? channelHeight + channelGap : 0;
-            height = channelHeight - analyzerHeight;
+            height = channelHeight - analyzerHeight - scaleHeight;
           } else {
-            posY = canvas.height - analyzerHeight * 2;
+            posY = canvas.height - analyzerHeight * 2 - scaleHeight;
             height = analyzerHeight;
           }
           _ctx.save();
@@ -1813,7 +2089,7 @@
           if (this.reflexBright != 1) _ctx.filter = `brightness(${this.reflexBright})`;
 
           // create the reflection
-          _ctx.setTransform(1, 0, 0, -1, 0, canvas.height);
+          _ctx.setTransform(1, 0, 0, -1, 0, canvas.height - scaleHeight);
           _ctx.drawImage(canvas, 0, channelCoords[channel].channelTop, canvas.width, analyzerHeight, 0, posY, canvas.width, height);
           _ctx.restore();
         }
@@ -1821,15 +2097,80 @@
 
       // draw scale on X-axis
       const drawScaleX = () => {
-        if (this.showScaleX) {
+        if (_sxshow) {
           if (_radial) {
             _ctx.save();
             _ctx.translate(centerX, centerY);
             if (this._spinSpeed) _ctx.rotate(this._spinAngle + HALF_PI);
             _ctx.drawImage(canvasR, -canvasR.width >> 1, -canvasR.width >> 1);
             _ctx.restore();
-          } else _ctx.drawImage(canvasX, 0, canvas.height - canvasX.height);
+          } else {
+            _ctx.drawImage(canvasX, 0, canvas.height - canvasX.height);
+            if (isDualVertical) _ctx.drawImage(canvasX, 0, (canvas.height >> 1) - canvasX.height);
+          }
+        }
+      };
+
+      // draw scale on Y-axis - TO-DO: handle reflex!
+      const drawScaleY = () => {
+        if (!this.showScaleY || isLumi || _radial) return;
+        const {
+            color,
+            dbInterval,
+            linearInterval,
+            lineDash,
+            operation,
+            showSubdivisions,
+            showUnit,
+            subLineColor,
+            subLineDash
+          } = _yAxis,
+          fontSize = yAxisWidth >> 1,
+          increment = (_linearAmplitude ? linearInterval : dbInterval) / (showSubdivisions ? 2 : 1),
+          left = yAxisWidth * .85,
+          max = _linearAmplitude ? 100 : maxDecibels,
+          min = _linearAmplitude ? 0 : minDecibels,
+          right = canvas.width - yAxisWidth * .1,
+          unit = _linearAmplitude ? '%' : 'dB',
+          unitHeight = analyzerHeight / (max - min);
+        _ctx.save();
+        _ctx.globalCompositeOperation = operation;
+        _ctx.fillStyle = color;
+        _ctx.font = `${fontSize}px ${FONT_FAMILY}`;
+        _ctx.textAlign = 'right';
+        _ctx.lineWidth = 1;
+        for (let channel = 0; channel < 1 + isDualVertical; channel++) {
+          const {
+            channelTop
+          } = channelCoords[channel];
+          for (let val = max, minor = false; val > min; val -= increment) {
+            const posY = channelTop + (max - val) * unitHeight;
+            if (minor && showSubdivisions) {
+              _ctx.strokeStyle = subLineColor;
+              _ctx.setLineDash(subLineDash);
+              _ctx.lineDashOffset = 1;
+            } else {
+              let labelY = posY + fontSize * (posY == channelTop ? .8 : .35);
+              _ctx.fillText(val, left, labelY);
+              _ctx.fillText(val, right, labelY);
+              if (showUnit && val - increment * (showSubdivisions ? 2 : 1) <= min) {
+                // display unit (dB or %) below the bottom label on both sides
+                labelY += fontSize * 1.5;
+                _ctx.fillText(unit, left, labelY);
+                _ctx.fillText(unit, right, labelY);
+              }
+              _ctx.strokeStyle = color;
+              _ctx.setLineDash(lineDash);
+              _ctx.lineDashOffset = 0;
+            }
+            _ctx.beginPath();
+            _ctx.moveTo(yAxisWidth * !minor, ~~posY + .5); // for sharp 1px line (https://stackoverflow.com/a/13879402/2370385)
+            _ctx.lineTo(canvas.width - yAxisWidth * !minor, ~~posY + .5);
+            _ctx.stroke();
+            if (showSubdivisions) minor = !minor;
+          }
         }
+        _ctx.restore();
       };
 
       // returns the gain (in dB) for a given frequency, considering the currently selected weighting filter
@@ -1884,16 +2225,18 @@
         }
       };
 
-      // converts a value in [0;1] range to a height in pixels that fits into the current LED elements
-      const ledPosY = value => Math.max(0, (value * ledCount | 0) * (ledHeight + ledSpaceV) - ledSpaceV);
+      // converts an amplitude value (0-1) to an integer number of LED elements
+      const ledUnits = value => Math.round(clamp(value, 0, 1) * ledCount);
+
+      // converts an amplitude value (0-1) to a height that, when subtracted from `analyzerBottom`, matches the top position of a LED element
+      const ledPosY = value => Math.max(0, ledUnits(value) * ledUnitHeight - ledGap);
 
       // update energy information
       const updateEnergy = newVal => {
         _energy.val = newVal;
         if (_energy.peak > 0) {
           _energy.hold--;
-          if (_energy.hold < 0) _energy.peak += _energy.hold * gravity / fpsSquared / canvas.height * this._pixelRatio;
-          // TO-DO: replace `canvas.height * this._pixelRatio` with `maxNominalHeight` when implementing dual-channel energy
+          if (_energy.hold < 0) _energy.peak += _energy.hold * decayRate;
         }
         if (newVal >= _energy.peak) {
           _energy.peak = newVal;
@@ -1903,20 +2246,24 @@
 
       /* MAIN FUNCTION */
 
-      if (overlay) _ctx.clearRect(0, 0, canvas.width, canvas.height);
+      // clear canvas
+      _ctx.clearRect(0, 0, canvas.width, canvas.height);
       let currentEnergy = 0;
       const nBars = _bars.length,
         nChannels = isSingle ? 1 : 2;
       for (let channel = 0; channel < nChannels; channel++) {
-        const {
+        const theme = _activeThemes[channel],
+          {
+            colorStops,
+            gradient,
+            mask
+          } = theme,
+          {
             channelTop,
             channelBottom,
             analyzerBottom
           } = channelCoords[channel],
-          channelGradient = this._gradients[this._selectedGrads[channel]],
-          colorStops = channelGradient.colorStops,
           colorCount = colorStops.length,
-          bgColor = !showBgColor || isLeds && !overlay ? '#000' : channelGradient.bgColor,
           radialDirection = isDualVertical && _radial && channel ? -1 : 1,
           // 1 = outwards, -1 = inwards
           invertedChannel = !channel && _mirror == -1 || channel && _mirror == 1,
@@ -1945,43 +2292,6 @@
         				}
         			}
         */
-        // draw scale on Y-axis (uses: channel, channelTop)
-        const drawScaleY = () => {
-          const scaleWidth = canvasX.height,
-            fontSize = scaleWidth >> 1,
-            max = _linearAmplitude ? 100 : maxDecibels,
-            min = _linearAmplitude ? 0 : minDecibels,
-            incr = _linearAmplitude ? 20 : 5,
-            interval = analyzerHeight / (max - min),
-            atStart = _mirror != -1 && (!isDualHorizontal || channel == 0 || _mirror == 1),
-            atEnd = _mirror != 1 && (!isDualHorizontal || channel != _mirror);
-          _ctx.save();
-          _ctx.fillStyle = SCALEY_LABEL_COLOR;
-          _ctx.font = `${fontSize}px ${FONT_FAMILY}`;
-          _ctx.textAlign = 'right';
-          _ctx.lineWidth = 1;
-          for (let val = max; val > min; val -= incr) {
-            const posY = channelTop + (max - val) * interval,
-              even = val % 2 == 0 | 0;
-            if (even) {
-              const labelY = posY + fontSize * (posY == channelTop ? .8 : .35);
-              if (atStart) _ctx.fillText(val, scaleWidth * .85, labelY);
-              if (atEnd) _ctx.fillText(val, (isDualHorizontal ? analyzerWidth : canvas.width) - scaleWidth * .1, labelY);
-              _ctx.strokeStyle = SCALEY_LABEL_COLOR;
-              _ctx.setLineDash([2, 4]);
-              _ctx.lineDashOffset = 0;
-            } else {
-              _ctx.strokeStyle = SCALEY_MIDLINE_COLOR;
-              _ctx.setLineDash([2, 8]);
-              _ctx.lineDashOffset = 1;
-            }
-            _ctx.beginPath();
-            _ctx.moveTo(initialX + scaleWidth * even * atStart, ~~posY + .5); // for sharp 1px line (https://stackoverflow.com/a/13879402/2370385)
-            _ctx.lineTo(finalX - scaleWidth * even * atEnd, ~~posY + .5);
-            _ctx.stroke();
-          }
-          _ctx.restore();
-        };
 
         // FFT bin data interpolation (uses fftData)
         const interpolate = (bin, ratio) => {
@@ -2016,12 +2326,26 @@
           _ctx.fill();
         };
 
-        // set fillStyle and strokeStyle according to current colorMode (uses: channel, colorStops, colorCount)
-        const setBarColor = (value = 0, barIndex = 0) => {
+        // render a bar of LEDs where each element has a single color (uses: analyzerBottom, isLumi)
+        const renderVintageLeds = (colorStops, barCenter, barHeight, barValue) => {
+          const colorIndex = isLumi ? 0 : colorStops.findLastIndex(item => ledUnits(barValue) <= ledUnits(item.level)),
+            savedStrokeStyle = _ctx.strokeStyle;
+          let last = analyzerBottom;
+          for (let i = colorCount - 1; i >= colorIndex; i--) {
+            _ctx.strokeStyle = colorStops[i].color;
+            let y = analyzerBottom - (i == colorIndex ? barHeight : ledPosY(colorStops[i].level));
+            strokeBar(barCenter, last, y);
+            last = y - ledGap;
+          }
+          _ctx.strokeStyle = savedStrokeStyle;
+        };
+
+        // set fillStyle and strokeStyle according to current colorMode (uses: colorStops, colorCount, gradient)
+        const setBarColor = (colorStops, value = 0, barIndex = 0) => {
           let color;
           // for graph mode, always use the channel gradient (ignore colorMode)
-          if (_colorMode == COLOR_GRADIENT && !isTrueLeds || _mode == MODE_GRAPH) color = _canvasGradients[channel];else {
-            const selectedIndex = _colorMode == COLOR_BAR_INDEX ? barIndex % colorCount : colorStops.findLastIndex(item => isLeds ? ledPosY(value) <= ledPosY(item.level) : value <= item.level);
+          if (_colorMode == COLORMODE_GRADIENT && !isVintageLeds || isGraphMode) color = gradient;else {
+            const selectedIndex = _colorMode == COLORMODE_INDEX ? barIndex % colorCount : colorStops.findLastIndex(item => isLeds ? ledUnits(value) <= ledUnits(item.level) : value <= item.level);
             color = colorStops[selectedIndex].color;
           }
           _ctx.fillStyle = _ctx.strokeStyle = color;
@@ -2037,22 +2361,9 @@
             _ctx.setTransform(flipX, 0, 0, 1, translateX, 0);
           }
 
-          // fill the analyzer background if needed (not overlay or overlay + showBgColor)
-          if (!overlay || showBgColor) {
-            if (overlay) _ctx.globalAlpha = this.bgAlpha;
-            _ctx.fillStyle = bgColor;
-
-            // exclude the reflection area when overlay is true and reflexAlpha == 1 (avoids alpha over alpha difference, in case bgAlpha < 1)
-            if (channel == 0 || !_radial && !isDualCombined) _ctx.fillRect(initialX, channelTop - channelGap, analyzerWidth, (overlay && this.reflexAlpha == 1 ? analyzerHeight : channelHeight) + channelGap);
-            _ctx.globalAlpha = 1;
-          }
-
-          // draw dB scale (Y-axis) - avoid drawing it twice on 'dual-combined' channel layout
-          if (this.showScaleY && !isLumi && !_radial && (channel == 0 || !isDualCombined)) drawScaleY();
-
           // set line width and dash for LEDs effect
           if (isLeds) {
-            _ctx.setLineDash([ledHeight, ledSpaceV]);
+            _ctx.setLineDash([ledHeight, ledGap]);
             _ctx.lineWidth = _bars[0].width;
           } else
             // for outline effect ensure linewidth is not greater than half the bar width
@@ -2111,11 +2422,9 @@
             bar.hold[channel]--;
             // if hold is negative, start peak drop or fade out
             if (bar.hold[channel] < 0) {
-              if (_fadePeaks && !showPeakLine) {
-                const initialAlpha = !isAlpha || isOutline && _lineWidth > 0 ? 1 : isAlpha ? bar.peak[channel] : fillAlpha;
-                bar.alpha[channel] = initialAlpha * (1 + bar.hold[channel] / fadeFrames); // hold is negative, so this is <= 1
-              } else bar.peak[channel] += bar.hold[channel] * gravity / fpsSquared / Math.abs(nominalMaxHeight);
-              // make sure the peak value is reset when using fadePeaks
+              const acceleration = bar.hold[channel] * decayRate;
+              if (_peaks == PEAKS_FADE && !showPeakLine) bar.alpha[channel] += acceleration;else bar.peak[channel] += acceleration;
+              // make sure the peak value is reset when peaks fade out
               if (bar.alpha[channel] <= 0) bar.peak[channel] = 0;
             }
           }
@@ -2135,14 +2444,14 @@
           _ctx.globalAlpha = isLumi || isAlpha ? barValue : isOutline ? fillAlpha : 1;
 
           // set fillStyle and strokeStyle for the current bar
-          setBarColor(barValue, barIndex);
+          setBarColor(colorStops, barValue, barIndex);
 
           // compute actual bar height on screen
           const barHeight = isLumi ? maxBarHeight : isLeds ? ledPosY(barValue) : barValue * maxBarHeight | 0;
 
           // Draw current bar or line segment
 
-          if (_mode == MODE_GRAPH) {
+          if (isGraphMode) {
             // compute the average between the initial bar (barIndex==0) and the next one
             // used to smooth the curve when the initial posX is off the screen, in mirror and radial modes
             const nextBarAvg = barIndex ? 0 : (this._normalizedB(fftData[_bars[1].binLo]) * maxBarHeight + barHeight) / 2;
@@ -2153,7 +2462,7 @@
               }
               // draw line to the current point, avoiding overlapping wrap-around frequencies
               if (posX >= 0) {
-                const point = [posX, barHeight];
+                const point = [barCenter, barHeight];
                 _ctx.lineTo(...radialXY(...point));
                 points.push(point);
               }
@@ -2168,31 +2477,23 @@
               }
               // draw line to the current point
               // avoid X values lower than the origin when mirroring left, otherwise draw them for best graph accuracy
-              if (isDualHorizontal || _mirror != -1 || posX >= initialX) _ctx.lineTo(posX, analyzerBottom - barHeight);
+              if (isDualHorizontal || _mirror != -1 || posX >= initialX) _ctx.lineTo(barCenter, analyzerBottom - barHeight);
             }
           } else {
             if (isLeds) {
-              // draw "unlit" leds - avoid drawing it twice on 'dual-combined' channel layout
-              if (showBgColor && !overlay && (channel == 0 || !isDualCombined)) {
-                const alpha = _ctx.globalAlpha;
-                _ctx.strokeStyle = LEDS_UNLIT_COLOR;
-                _ctx.globalAlpha = 1;
-                strokeBar(barCenter, channelTop, analyzerBottom);
-                // restore properties
-                _ctx.strokeStyle = _ctx.fillStyle;
-                _ctx.globalAlpha = alpha;
-              }
-              if (isTrueLeds) {
-                // ledPosY() is used below to fit one entire led height into the selected range
-                const colorIndex = isLumi ? 0 : colorStops.findLastIndex(item => ledPosY(barValue) <= ledPosY(item.level));
-                let last = analyzerBottom;
-                for (let i = colorCount - 1; i >= colorIndex; i--) {
-                  _ctx.strokeStyle = colorStops[i].color;
-                  let y = analyzerBottom - (i == colorIndex ? barHeight : ledPosY(colorStops[i].level));
-                  strokeBar(barCenter, last, y);
-                  last = y - ledSpaceV;
+              // draw led mask - avoid drawing it twice on 'dual-combined' channel layout
+              if (showLedMask && (!isDualCombined || channel == 0)) {
+                const savedAlpha = _ctx.globalAlpha;
+                _ctx.globalAlpha = 1; // TO-DO: maybe set the led mask alpha here, instead of doing it in each color?
+                if (isVintageLeds) renderVintageLeds(mask.colorStops, barCenter, maxBarHeight, 1);else {
+                  const savedColor = _ctx.fillStyle;
+                  if (_colorMode == COLORMODE_GRADIENT) _ctx.strokeStyle = mask.gradient;else setBarColor(mask.colorStops, 0, barIndex);
+                  strokeBar(barCenter, channelTop, analyzerBottom);
+                  _ctx.fillStyle = _ctx.strokeStyle = savedColor;
                 }
-              } else strokeBar(barCenter, analyzerBottom, analyzerBottom - barHeight);
+                _ctx.globalAlpha = savedAlpha;
+              }
+              if (isVintageLeds) renderVintageLeds(colorStops, barCenter, barHeight, barValue);else strokeBar(barCenter, analyzerBottom, analyzerBottom - barHeight);
             } else if (posX >= initialX) {
               if (_radial) radialPoly(posX, 0, width, barHeight, isOutline);else if (isRound) {
                 const halfWidth = width / 2,
@@ -2220,25 +2521,30 @@
             peakAlpha = bar.alpha[channel];
           if (peakValue > 0 && peakAlpha > 0 && showPeaks && !showPeakLine && !isLumi && posX >= initialX && posX < finalX) {
             // set opacity for peak
-            if (_fadePeaks) _ctx.globalAlpha = peakAlpha;else if (isOutline && _lineWidth > 0)
+            if (_peaks == PEAKS_FADE) _ctx.globalAlpha = peakAlpha;else if (isOutline && _lineWidth > 0)
               // when lineWidth == 0 ctx.globalAlpha remains set to `fillAlpha`
               _ctx.globalAlpha = 1;else if (isAlpha)
               // isAlpha (alpha based on peak value) supersedes fillAlpha if lineWidth == 0
               _ctx.globalAlpha = peakValue;
 
-            // select the peak color for 'bar-level' colorMode or 'trueLeds'
-            if (_colorMode == COLOR_BAR_LEVEL || isTrueLeds) setBarColor(peakValue);
+            // use peakColor when defined by the theme in use
+            if (theme.peakColor) {
+              _ctx.fillStyle = _ctx.strokeStyle = theme.peakColor;
+            } else if (_colorMode == COLORMODE_LEVEL || isVintageLeds) {
+              // select the proper peak color for 'bar-level' colorMode or 'vintage' ledBars
+              setBarColor(colorStops, peakValue);
+            }
 
             // render peak according to current mode / effect
             if (isLeds) {
               const ledPeak = ledPosY(peakValue);
-              if (ledPeak >= ledSpaceV)
+              if (ledPeak >= ledGap)
                 // avoid peak below first led
                 _ctx.fillRect(posX, analyzerBottom - ledPeak, width, ledHeight);
-            } else if (!_radial) _ctx.fillRect(posX, analyzerBottom - peakValue * maxBarHeight, width, 2);else if (_mode != MODE_GRAPH) {
+            } else if (!_radial) _ctx.fillRect(isGraphMode ? barCenter : posX, analyzerBottom - peakValue * maxBarHeight, isGraphMode ? 1 : width, 2);else if (!isGraphMode) {
               // radial (peaks for graph mode are done by the peakLine code)
               const y = peakValue * maxBarHeight;
-              radialPoly(posX, y, width, !this._radialInvert || isDualVertical || y + innerRadius >= 2 ? -2 : 2);
+              radialPoly(posX, y, width, _radial != RADIAL_INNER || isDualVertical || y + innerRadius >= 2 ? -2 : 2);
             }
           }
         } // for ( let barIndex = 0; barIndex < nBars; barIndex++ )
@@ -2250,7 +2556,7 @@
         _ctx.globalAlpha = 1;
 
         // Fill/stroke drawing path for graph mode
-        if (_mode == MODE_GRAPH) {
+        if (isGraphMode) {
           setBarColor(); // select channel gradient
 
           if (_radial && !isDualHorizontal) {
@@ -2281,26 +2587,29 @@
           // draw peak line (and standard peaks on radial)
           if (showPeakLine || _radial && showPeaks) {
             points = []; // for mirror line on radial
+            if (theme.peakColor) _ctx.fillStyle = _ctx.strokeStyle = theme.peakColor;
             _ctx.beginPath();
             _bars.forEach((b, i) => {
-              let x = b.posX,
+              let x = b.barCenter,
                 h = b.peak[channel],
                 m = i ? 'lineTo' : 'moveTo';
               if (_radial && x < 0) {
                 const nextBar = _bars[i + 1];
-                h = findY(x, h, nextBar.posX, nextBar.peak[channel], 0);
+                h = findY(x, h, nextBar.barCenter, nextBar.peak[channel], 0);
                 x = 0;
               }
               h *= maxBarHeight;
               if (showPeakLine) {
                 _ctx[m](...(_radial ? radialXY(x, h) : [x, analyzerBottom - h]));
                 if (_radial && _mirror && !isDualHorizontal) points.push([x, h]);
-              } else if (h > 0) radialPoly(x, h, 1, -2); // standard peaks (also does mirror)
+              } else if (b.peak[channel] > 0)
+                // note: `h` is negative in inner radial
+                radialPoly(x, h, 1, -2); // standard peaks (also does mirror)
             });
             if (showPeakLine) {
               let p;
               while (p = points.pop()) _ctx.lineTo(...radialXY(...p, -1)); // mirror line points
-              _ctx.lineWidth = 1;
+              _ctx.lineWidth = _peakLine;
               _ctx.stroke(); // stroke peak line
             }
           }
@@ -2325,7 +2634,8 @@
         // restore solid lines
         _ctx.setLineDash([]);
 
-        // draw frequency scale (X-axis)
+        // draw scales
+        drawScaleY();
         drawScaleX();
       }
 
@@ -2341,10 +2651,9 @@
       // call callback function, if defined
       if (this.onCanvasDraw) {
         _ctx.save();
-        _ctx.fillStyle = _ctx.strokeStyle = _canvasGradients[0];
         this.onCanvasDraw(this, {
           timestamp,
-          canvasGradients: _canvasGradients
+          themes: _activeThemes
         });
         _ctx.restore();
       }
@@ -2376,79 +2685,150 @@
     }
 
     /**
-     * Generate currently selected gradient
+     * Generates canvas gradients and updates _activeThemes properties
+     *
+     * 	_activeThemes = [
+     *		// one object per channel:
+     *		{
+     *			// theme name and modifiers are set by setTheme()
+     *			name: <string>,
+     * 			modifiers: {
+     *	 			horizontal: <boolean>,
+     * 				reverse: <boolean>
+     *			},
+     *
+     * 			// colorStops and peakColor come from the theme registration
+     *			colorStops: <array>,
+     *			peakColor: <string>,
+     *
+     *			// gradient and mask.gradient are generated here
+     *			gradient: <CanvasGradient>,
+     *			mask: {
+     *				colorStops: <array>,
+     *				gradient: <CanvasGradient>
+     *			}
+     *		}
+     *	]
+     *
      */
     _makeGrad() {
       if (!this._ready) return;
       const {
           canvas,
+          _chLayout,
           _ctx,
+          _horizGrad,
+          _mirror,
           _radial,
-          _reflexRatio
+          _reflexRatio,
+          _spread,
+          _xAxis
         } = this,
         {
+          analyzerHeight,
           analyzerWidth,
           centerX,
           centerY,
+          channelHeight,
           initialX,
           innerRadius,
-          outerRadius
+          outerRadius,
+          xAxisHeight
         } = this._aux,
         {
           isLumi
         } = this._flg,
-        isDualVertical = this._chLayout == CHANNEL_VERTICAL,
-        analyzerRatio = 1 - _reflexRatio,
-        gradientHeight = isLumi ? canvas.height : canvas.height * (1 - _reflexRatio * !isDualVertical) | 0;
-      // for vertical stereo we keep the full canvas height and handle the reflex areas while generating the color stops
-
+        isDualVertical = _chLayout == LAYOUT_VERTICAL,
+        isDualHorizontal = _chLayout == LAYOUT_HORIZONTAL;
       for (const channel of [0, 1]) {
-        const currGradient = this._gradients[this._selectedGrads[channel]],
-          colorStops = currGradient.colorStops,
-          isHorizontal = currGradient.dir == 'h';
-        let grad;
-        if (_radial) grad = _ctx.createRadialGradient(centerX, centerY, outerRadius, centerX, centerY, innerRadius - (outerRadius - innerRadius) * isDualVertical);else grad = _ctx.createLinearGradient(...(isHorizontal ? [initialX, 0, initialX + analyzerWidth, 0] : [0, 0, 0, gradientHeight]));
-        if (colorStops) {
-          const dual = isDualVertical && !this._splitGradient && (!isHorizontal || _radial);
-          for (let channelArea = 0; channelArea < 1 + dual; channelArea++) {
-            const maxIndex = colorStops.length - 1;
-            colorStops.forEach((colorStop, index) => {
-              let offset = colorStop.pos;
-
-              // in dual mode (not split), use half the original offset for each channel
-              if (dual) offset /= 2;
-
-              // constrain the offset within the useful analyzer areas (avoid reflex areas)
-              if (isDualVertical && !isLumi && !_radial && !isHorizontal) {
-                offset *= analyzerRatio;
-                // skip the first reflex area in split mode
-                if (!dual && offset > .5 * analyzerRatio) offset += .5 * _reflexRatio;
-              }
+        const {
+            name,
+            modifiers
+          } = this._activeThemes[channel],
+          analyzerRatio = _radial || modifiers.horizontal ? 1 : analyzerHeight / channelHeight,
+          sourceTheme = deepCloneObject(this._themes[name]),
+          {
+            colorStops,
+            mask
+          } = sourceTheme,
+          maskColorStops = mask.colorStops,
+          maxIndex = colorStops.length - 1;
+
+        // compute start and end coordinates for the gradient on each channel
+
+        let [startX, endX, startY, endY, outer, inner] = [0, 0, 0, 0, outerRadius, innerRadius];
+        if (_radial) {
+          // handle radial
+          if (isDualVertical) {
+            // on dual-vertical radial, innerRadius is actually the center radius between both channels
+            // so we need to compute the actual innermost gradient radius
+            if (_spread) inner -= outer - inner;else if (channel == 1) outer = inner - (outer - inner); // top of channel 1 (outer < inner, so inverts gradient)
+          }
+        } else if (_spread && (isDualHorizontal && modifiers.horizontal || isDualVertical && !modifiers.horizontal)) {
+          // handle spread gradient (both horizontal and vertical)
+          if (modifiers.horizontal) {
+            // on dual-horizontal layout, both channels only use the *first half* of the gradient, due to flip and translation
+            // for spread on channel 1 we need to start of the gradient halfway off-screen, so as to use the second half of it
+            startX = channel == 1 ? -analyzerWidth : 0;
+            endX = startX + analyzerWidth * 2;
+          } else endY = canvas.height;
+        } else {
+          if (modifiers.horizontal) {
+            startX = isDualHorizontal && channel == 1 || _mirror == -1 ? initialX : 0;
+            endX = startX + analyzerWidth;
+          } else {
+            startY = isDualVertical && channel == 1 ? channelHeight : 0;
+            endY = startY + analyzerHeight;
+          }
+        }
 
-              // only for dual-vertical non-split gradient (creates full gradient on both halves of the canvas)
-              if (channelArea == 1) {
-                // add colors in reverse order if radial or lumi are active
-                if (_radial || isLumi) {
-                  const revIndex = maxIndex - index;
-                  colorStop = colorStops[revIndex];
-                  offset = 1 - colorStop.pos / 2;
-                } else {
-                  // if the first offset is not 0, create an additional color stop to prevent bleeding from the first channel
-                  if (index == 0 && offset > 0) grad.addColorStop(.5, colorStop.color);
-                  // bump the offset to the second half of the gradient
-                  offset += .5;
-                }
-              }
+        // helper function
+        const createNewGradient = _ => _ctx.createLinearGradient(startX, startY, endX, endY);
+        if (modifiers.reverse) {
+          // reverse colors only (preserve offsets and level thresholds of each colorstop)
+          for (let i = 0; i <= maxIndex >> 1; i++) {
+            [colorStops[i].color, colorStops[maxIndex - i].color] = [colorStops[maxIndex - i].color, colorStops[i].color];
+            [maskColorStops[i].color, maskColorStops[maxIndex - i].color] = [maskColorStops[maxIndex - i].color, maskColorStops[i].color];
+          }
+        }
+        let gradient = _radial ? _ctx.createRadialGradient(centerX, centerY, outer, centerX, centerY, inner) : createNewGradient(),
+          maskGradient = _radial ? null : createNewGradient(); // no LEDs in radial
 
-              // add gradient color stop
-              grad.addColorStop(offset, colorStop.color);
+        colorStops.forEach((colorStop, index) => {
+          let offset = colorStop.pos;
 
-              // create additional color stop at the end of first channel to prevent bleeding
-              if (isDualVertical && index == maxIndex && offset < .5) grad.addColorStop(.5, colorStop.color);
-            });
-          } // for ( let channelArea = 0; channelArea < 1 + dual; channelArea++ )
-        }
-        this._canvasGradients[channel] = grad;
+          // additional offset processing to account for spread gradient combined with reflex and/or X-axis display on dual-vertical layout
+          // TO-DO: add support for no scale overlay on radial too? Requires changes to outerRadius and innerRadius computation in calcBars()
+          if (!_radial && _spread && isDualVertical && !modifiers.horizontal) {
+            // "shrink" each offset to fit into the usable analyzer area
+            offset *= analyzerRatio;
+
+            // skip top reflex + X-axis areas, on all offsets below it (>.5)
+            if (offset > .5 * analyzerRatio) offset += (1 - analyzerRatio) / 2;
+          }
+
+          // add computed color stop to the gradient
+          gradient.addColorStop(clamp(offset, 0, 1), colorStop.color);
+          if (maskGradient) maskGradient.addColorStop(clamp(offset, 0, 1), maskColorStops[index].color);
+        });
+        this._activeThemes[channel] = {
+          name,
+          // set by setTheme()
+          modifiers,
+          ...sourceTheme,
+          // preserves properties from the source theme, not changed here, like `peakColor`
+          colorStops,
+          // from the source theme, but modified by this method if `flipGrad` is on
+          gradient,
+          // generated by this method
+          mask: {
+            ...sourceTheme.mask,
+            // preserves any original properties (future-proof!)
+            colorStops: maskColorStops,
+            // from the source theme, but modified by this method if `flipGrad` is on
+            gradient: maskGradient // generated by this method
+          }
+        };
       } // for ( const channel of [0,1] )
     }
 
@@ -2458,7 +2838,6 @@
     _normalizedB(value) {
       const isLinear = this._linearAmplitude,
         boost = isLinear ? 1 / this._linearBoost : 1,
-        clamp = (val, min, max) => val <= min ? min : val >= max ? max : val,
         dBToLinear = val => 10 ** (val / 20);
       let maxValue = this.maxDecibels,
         minValue = this.minDecibels;
@@ -2479,7 +2858,6 @@
           canvas,
           _ctx
         } = this,
-        canvasX = this._scaleX.canvas,
         pixelRatio = window.devicePixelRatio / (this._loRes + 1);
       let screenWidth = window.screen.width * pixelRatio,
         screenHeight = window.screen.height * pixelRatio;
@@ -2503,49 +2881,23 @@
       canvas.width = newWidth;
       canvas.height = newHeight;
 
-      // if not in overlay mode, paint the canvas black
-      if (!this.overlay) {
-        _ctx.fillStyle = '#000';
-        _ctx.fillRect(0, 0, newWidth, newHeight);
-      }
-
       // set lineJoin property for area fill mode (this is reset whenever the canvas size changes)
       _ctx.lineJoin = 'bevel';
 
-      // update dimensions of the scale canvas
-      canvasX.width = newWidth;
-      canvasX.height = Math.max(20 * pixelRatio, Math.min(newWidth, newHeight) / 32 | 0);
-
       // calculate bar positions and led options
       this._calcBars();
 
-      // (re)generate gradient
+      // (re)generate gradients
       this._makeGrad();
 
       // detect fullscreen changes (for Safari)
-      if (this._fsStatus !== undefined && this._fsStatus !== isFullscreen) reason = REASON_FSCHANGE;
+      if (this._fsStatus !== undefined && this._fsStatus !== isFullscreen) reason = REASON_FULLSCREENCHANGE;
       this._fsStatus = isFullscreen;
 
       // call the callback function, if defined
       if (this.onCanvasResize) this.onCanvasResize(reason, this);
     }
 
-    /**
-     * Select a gradient for one or both channels
-     *
-     * @param {string} name gradient name
-     * @param [{number}] desired channel (0 or 1) - if empty or invalid, sets both channels
-     */
-    _setGradient(name, channel) {
-      if (!this._gradients.hasOwnProperty(name)) throw new AudioMotionError(ERR_UNKNOWN_GRADIENT, name);
-      if (![0, 1].includes(channel)) {
-        this._selectedGrads[1] = name;
-        channel = 0;
-      }
-      this._selectedGrads[channel] = name;
-      this._makeGrad();
-    }
-
     /**
      * Set object properties
      */
@@ -2553,11 +2905,11 @@
       // callback functions properties
       const callbacks = ['onCanvasDraw', 'onCanvasResize'];
 
-      // properties not in the defaults (`stereo` is deprecated)
-      const extraProps = ['gradientLeft', 'gradientRight', 'stereo'];
+      // allow other properties not in the defaults
+      const extraProps = ['themeLeft', 'themeRight'];
 
-      // build an array of valid properties; `start` is not an actual property and is handled after setting everything else
-      const validProps = Object.keys(DEFAULT_SETTINGS).filter(e => e != 'start').concat(callbacks, extraProps);
+      // build an array of valid properties
+      const validProps = Object.keys(DEFAULT_SETTINGS).concat(callbacks, extraProps);
       if (useDefaults || options === undefined) options = {
         ...DEFAULT_SETTINGS,
         ...options
@@ -2570,9 +2922,6 @@
           // set only valid properties
           this[prop] = options[prop];
       }
-
-      // deprecated - move this to the constructor in the next major release (`start` should be constructor-specific)
-      if (options.start !== undefined) this.toggleAnalyzer(options.start);
     }
   }
   _exports.AudioMotionAnalyzer = AudioMotionAnalyzer;