npm - audiomotion-analyzer - Versions diffs - 5.0.0-alpha.1 → 5.0.0-beta.0 - Mend

audiomotion-analyzer 5.0.0-alpha.1 → 5.0.0-beta.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (5) hide show

package/README.md +431 -258
package/dist/index.js +938 -850
package/package.json +4 -4
package/src/audioMotion-analyzer.js +922 -865
package/src/index.d.ts +78 -32

package/README.md CHANGED Viewed

@@ -1,6 +1,6 @@
 ## About
-> **WARNING:** code in **alpha** stage is subject to major, drastic changes! **DO NOT USE THIS IN PRODUCTION!**
+> **VERSION 5 IS IN BETA PHASE!** Features can still change or be removed without warning. **DO NOT USE THIS VERSION IN PRODUCTION!**<br>
 **audioMotion-analyzer** is a high-resolution real-time audio spectrum analyzer built upon **Web Audio** and **Canvas** JavaScript APIs.
@@ -32,17 +32,19 @@ What users are saying:
 + Logarithmic, linear and perceptual (Bark and Mel) frequency scales, with customizable range
 + Visualization of discrete FFT frequencies or up to 240 frequency bands (supports ANSI and equal-tempered octave bands)
 + Decibel and linear amplitude scales, with customizable sensitivity
-+ Optional A, B, C, D and ITU-R 468 weighting filters
++ Optional weighting filters (A, B, C and D-weighting, ITU-R 468, 3dB and 4.5dB per octave tilt)
 + Additional effects: LED bars, radial spectrum, variable opacity bars, mirroring and reflection
 + Choose from 5 built-in color themes or easily add your own!
 + Fullscreen support, ready for retina / HiDPI displays
 + Zero-dependency native ES6+ module (ESM), \~30kB minified
+?> Minimum browser requirements: Chrome 84, Firefox 75, Opera 70 or Safari 13.1.
 ## Online demos
-[![demo-animation](img/demo.webp)](https://audiomotion.dev/demo/alpha/)
+[![demo-animation](img/demo.webp)](https://audiomotion.dev/demo/beta/)
-?> https://audiomotion.dev/demo/alpha/
+?> https://audiomotion.dev/demo/beta/
 ## Live code examples
@@ -63,7 +65,7 @@ What users are saying:
 Install via npm:
 ```console
-npm i audiomotion-analyzer@alpha
+npm i audiomotion-analyzer@beta
 ```
 Use ES6 import:
@@ -84,7 +86,7 @@ Load from jsDelivr CDN:
 ```html
 <script type="module">
-  import AudioMotionAnalyzer from 'https://cdn.jsdelivr.net/npm/audiomotion-analyzer@alpha/+esm';
+  import AudioMotionAnalyzer from 'https://cdn.jsdelivr.net/npm/audiomotion-analyzer@beta/+esm';
   // your code here
 </script>
 ```
@@ -96,7 +98,7 @@ Or download the [latest version](https://github.com/hvianna/audioMotion-analyzer
 Load from jsDelivr CDN:
 ```html
-<script src="https://cdn.jsdelivr.net/npm/audiomotion-analyzer@alpha"></script>
+<script src="https://cdn.jsdelivr.net/npm/audiomotion-analyzer@beta"></script>
 <script>
   // available as AudioMotionAnalyzer global
 </script>
@@ -141,37 +143,35 @@ property                              | type      | default | notes
 --------------------------------------|-----------|---------|-------------------------------
 [`alphaBars`](#alphabars)             | *string*  | `"off"` |
 [`ansiBands`](#ansibands)             | *boolean* | `false` |
-[`audioCtx`](#audioctx)               | *AudioContext object* | *creates new object* | constructor only
+[`audioCtx`](#audioctx)               | *AudioContext* | *creates new object* | constructor only
 [`barSpace`](#barspace)               | *number*  | `0.1` |
-[`canvas`](#canvas)                   | *HTMLCanvasElement object* | *creates new object* | constructor only
+[`canvas`](#canvas)                   | *HTMLCanvasElement* | *creates new object* | constructor only
 [`channelLayout`](#channellayout)     | *string*  | `"single"` |
 [`colorMode`](#colormode)             | *string*  | `"gradient"` |
 [`connectSpeakers`](#connectspeakers) | *boolean* | `true` | constructor only
 [`fftSize`](#fftsize)                 | *number*  | `8192` |
 [`fillAlpha`](#fillalpha)             | *number*  | `0.5` |
 [`frequencyScale`](#frequencyscale)   | *string*  | `"log"` |
-[`fsElement`](#fselement)             | *HTMLElement object* | [`canvas`](#canvas) | constructor only
+[`fsElement`](#fselement)             | *HTMLElement* | [`canvas`](#canvas) | constructor only
 [`height`](#height)                   | *number* or *undefined* | `undefined` |
 [`ledBars`](#ledbars)                 | *string*  | `"off"` |
 [`linearAmplitude`](#linearamplitude) | *boolean* | `false` |
 [`linearBoost`](#linearboost)         | *number*  | `1` |
 [`lineWidth`](#linewidth)             | *number*  | `1` |
 [`loRes`](#lores)                     | *boolean* | `false` |
-[`maxDecibels`](#maxdecibels)         | *number*  | `-25` |
+[`maxDecibels`](#maxdecibels)         | *number*  | `-30` |
 [`maxFPS`](#maxfps)                   | *number*  | `0` |
 [`maxFreq`](#maxfreq)                 | *number*  | `22000` |
-[`minDecibels`](#mindecibels)         | *number*  | `-85` |
+[`minDecibels`](#mindecibels)         | *number*  | `-90` |
 [`minFreq`](#minfreq)                 | *number*  | `20` |
 [`mirror`](#mirror)                   | *number*  | `0` |
 [`mode`](#mode)                       | *string*  | `"bars"` |
-[`noteLabels`](#notelabels)           | *boolean* | `false` |
 [`onCanvasDraw`](#oncanvasdraw)       | *function* or *undefined* | `undefined` |
 [`onCanvasResize`](#oncanvasresize)   | *function* or *undefined* | `undefined` |
 [`outlineBars`](#outlinebars)         | *boolean* | `false` |
 [`peakDecayTime`](#peakdecaytime)     | *number*  | `750` |
 [`peakHoldTime`](#peakholdtime)       | *number*  | `500` |
 [`peakLine`](#peakline)               | *boolean* | `false` |
-[`peaks`](#peaks)                     | *string*  | `"drop"` |
 [`radial`](#radial)                   | *number*  | `0` |
 [`radius`](#radius)                   | *number*  | `0.5` |
 [`reflexAlpha`](#reflexalpha)         | *number*  | `0.15` |
@@ -181,16 +181,17 @@ property                              | type      | default | notes
 [`roundBars`](#roundbars)             | *boolean* | `false` |
 [`showFPS`](#showfps)                 | *boolean* | `false` |
 [`showLedMask`](#showledmask)         | *boolean* | `true` |
-[`showScaleX`](#showscalex)           | *boolean* | `true` |
-[`showScaleY`](#showscaley)           | *boolean* | `false` |
-[`smoothing`](#smoothing)             | *number*  | `0.5` |
-[`source`](#source)                   | *AudioNode* or *HTMLMediaElement object* | *none* | constructor only
+[`showPeaks`](#showpeaks)             | *string*  | `"drop"` |
+[`showScaleX`](#showscalex)           | *string*  | `"freqs"` |
+[`showScaleY`](#showscaley)           | *string*  | `"off"` |
+[`smoothing`](#smoothing)             | *number*  | `0.7` |
+[`source`](#source)                   | *AudioNode*, *HTMLMediaElement* or *MediaStream* | *none* | constructor only
 [`spinSpeed`](#spinspeed)             | *number*  | `0` |
 [`spreadGradient`](#spreadgradient)   | *boolean* | `false` |
 [`start`](#start)                     | *boolean* | `true` | constructor only
 [`useCanvas`](#usecanvas)             | *boolean* | `true` |
 [`volume`](#volume)                   | *number*  | `1` |
-[`weightingFilter`](#weightingFilter) | *string*  | `""` |
+[`weightingFilter`](#weightingFilter) | *string*  | `"none"` |
 [`width`](#width)                     | *number* or *undefined* | `undefined` |
 ### Constructor-specific options
@@ -225,7 +226,7 @@ If not defined, a new Canvas will be created. After instantiation, you can obtai
 **Value:** a *boolean* value. The default value is `true`.
-Whether or not to connect the analyzer output to the speakers (technically, the *AudioContext* `destination` node).
+Whether or not to connect the analyzer output to the speakers (technically, the *AudioContext* [`destination`](https://developer.mozilla.org/en-US/docs/Web/API/BaseAudioContext/destination) node).
 Some scenarios where you may want to set this to `false`:
@@ -255,9 +256,9 @@ After instantiation, [`fsElement`](#fselement-read-only) is available as a read-
 #### `source`
-**Value:** an [*AudioNode*](https://developer.mozilla.org/en-US/docs/Web/API/AudioNode) or [*HTMLMediaElement*](https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement) object.
+**Value:** an [*AudioNode*](https://developer.mozilla.org/en-US/docs/Web/API/AudioNode), [*HTMLMediaElement*](https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement) or [MediaStream](https://developer.mozilla.org/en-US/docs/Web/API/MediaStream) object.
-If `source` is specified, connects an AudioNode or an `<audio>` or `<video>` HTML element to the analyzer.
+If `source` is specified, connects the provided *AudioNode*, HTML media element (`<audio>` or `<video>` elements) or *MediaStream* object to the analyzer.
 At least one audio source is required for the analyzer to work. You can also connect audio sources after instantiation, using the [`connectInput()`](#connectinput) method.
@@ -306,6 +307,16 @@ import {
 	FILTER_C,
 	FILTER_D,
 	FILTER_468,
+	FILTER_TILT3,
+	FILTER_TILT45,
+	LABELS_X_CUSTOM,
+	LABELS_X_FREQS,
+	LABELS_X_FREQS_CUSTOM,
+	LABELS_X_NOTES,
+	LABELS_X_OFF,
+	LABELS_Y_DB,
+	LABELS_Y_PERCENT,
+	LABELS_Y_OFF,
 	LAYOUT_COMBINED,
 	LAYOUT_HORIZONTAL,
 	LAYOUT_SINGLE,
@@ -313,14 +324,17 @@ import {
 	LEDS_MODERN,
 	LEDS_OFF,
 	LEDS_VINTAGE,
+	MIRROR_LEFT,
+	MIRROR_OFF,
+	MIRROR_RIGHT,
 	MODE_BARS,
 	MODE_GRAPH,
 	PEAKS_DROP,
 	PEAKS_FADE,
 	PEAKS_OFF,
-	RADIAL_INNER,
+	RADIAL_INWARD,
 	RADIAL_OFF,
-	RADIAL_OUTER,
+	RADIAL_OUTWARD,
 	REASON_CREATE,
 	REASON_FULLSCREENCHANGE,
 	REASON_LORES,
@@ -344,7 +358,7 @@ import {
 Determines whether each bar's opacity is affected by its amplitude. Only effective in **Bars** [`mode`](#mode).
-value    | [Constant](#constants) | Description
+Value    | [Constant](#constants) | Description
 ---------|------------------------|--------------
 `"off"`  | `ALPHABARS_OFF`  | Disables effect
 `"on"`   | `ALPHABARS_ON`   | Bars with higher amplitude are rendered more opaque while those with lower amplitude are mode transparent
@@ -362,7 +376,7 @@ For effect priority when combined with other settings, see [`isAlphaBars`](#isal
 Whether to use the ANSI/IEC preferred frequencies, instead of the musical scale, to compute the center and edge frequencies of [octave bands](#bandresolution).
-value   | Reference | Octaves' center frequencies
+Value   | Reference | Octaves' center frequencies
 --------|-----------------|----------------------------
 `false` | [A 440 pitch standard](http://hyperphysics.phy-astr.gsu.edu/hbase/Music/et.html) (equal temperament scale) | ![scale-log-equal-temperament](img/scale-log-equal-temperament.png)
 `true`  | [ANSI S1.11-2004 standard](https://archive.org/details/gov.law.ansi.s1.11.2004) (base-10 scale) | ![scale-log-ansi](img/scale-log-ansi.png)
@@ -371,8 +385,6 @@ Only effective when [`frequencyScale`](#frequencyScale) is set to `"log"` and [`
 When using the equal-tempered scale, the center frequency of each band is tuned to a standard musical note.
-See also [`noteLabels`](#notelabels).
 ### `audioCtx` *(read only)*
 The [*AudioContext*](https://developer.mozilla.org/en-US/docs/Web/API/AudioContext) used by **audioMotion-analyzer** for audio processing.
@@ -411,7 +423,7 @@ How much of an octave should each analyzer band represent, or how many bands sho
 When [`frequencyScale`](#frequencyscale-string) is set to `"log"`, this setting defines which fraction of an octave is included in each bar.
 Otherwise, the frequency spectrum is divided into a fixed amount of bars, with the bandwidth of each bar varying according to the selected frequency scale.
-value | [Constant](#constants) | Description
+Value | [Constant](#constants) | Description
 :----:|------------------------|-----------------
 `0`   | `BANDS_FFT`         | Discrete frequencies provided by the [FFT](https://en.wikipedia.org/wiki/Fast_Fourier_transform) computation
 `1`   | `BANDS_OCTAVE_FULL` | Full octave bands or 10 bands
@@ -461,7 +473,7 @@ See also the [`canvas`](#canvas) constructor option.
 Defines the number and layout of analyzer channels.
-value               | [Constant](#constants) | Description
+Value               | [Constant](#constants) | Description
 --------------------|------------------------|-----------------
 `"single"`          | `LAYOUT_SINGLE`     | Single channel analyzer, representing the combined output of both left and right channels.
 `"dual-combined"`   | `LAYOUT_COMBINED`   | Dual channel analyzer, both channels overlaid. Works best with semi-transparent **Graph** [`mode`](#mode) or [`outlineBars`](#outlinebars).
@@ -481,7 +493,7 @@ See also [`setTheme()`](#settheme) and [`spreadGradient`](#spreadgradient).
 Selects the desired mode for coloring the analyzer bars. This property has no effect in **Graph** [`mode`](#mode).
-value         | [Constant](#constants) | Description | Preview ('prism' theme)
+Value         | [Constant](#constants) | Description | Preview ('prism' theme)
 --------------|------------------------|-------------|-------------------------
 `"gradient"`  | `COLORMODE_GRADIENT` | Analyzer bars are painted with a gradient of the selected [`theme`](#theme-string)'s colors. This is the default behavior. | ![prism](img/gradient-prism.png)
 `"bar-index"` | `COLORMODE_INDEX`    | Each analyzer bar is painted with a **single color** from the selected theme's colors, starting with the first color applied to the first bar, and so on, cycling through the available colors. | ![prism-bar-index](img/gradient-prism-bar-index.png)
@@ -543,14 +555,14 @@ Current frame rate.
 Scale used to represent frequencies in the horizontal axis.
-value      | [Constant](#constants) | Description | Scale preview (10Hz - 24kHz range)
+Value      | [Constant](#constants) | Description | Scale preview (10Hz - 24kHz range)
 -----------|------------------------|-------------|-------------------------------------
 `"bark"`   | `SCALE_BARK`   | Bark scale | ![scale-bark](img/scale-bark.png)
 `"linear"` | `SCALE_LINEAR` | Linear scale | ![scale-linear](img/scale-linear.png)
 `"log"`    | `SCALE_LOG`    | Logarithmic scale | ![scale-log-ansi](img/scale-log-ansi.png)
 `"mel"`    | `SCALE_MEL`    | Mel scale | ![scale-mel](img/scale-mel.png)
-Logarithmic scale allows visualization of proper **octave bands** (see [`bandResolution`](#bandresolution)) and it's also recommended when using [`noteLabels`](#notelabels).
+Logarithmic scale allows visualization of proper **octave bands** (see [`bandResolution`](#bandresolution)) and it's also recommended when using [`showScaleX`](#showscalex) set to `"notes"`.
 [*Bark*](https://en.wikipedia.org/wiki/Bark_scale) and [*Mel*](https://en.wikipedia.org/wiki/Mel_scale) are perceptual pitch scales, which may provide better visualization of mid-range frequencies, when compared to log or linear scales.
@@ -650,15 +662,15 @@ Returns `true` when round bars are effectively being displayed, i.e., [`roundBar
 Determines the appearance of the LED bars. Only effective in **Bars** [`mode`](#mode), when [`bandResolution`](#bandresolution) > `0` and [`radial`](#radial) set to `0`.
-value       | [Constant](#constants) | Description | Preview
+Value       | [Constant](#constants) | Description | Preview
 ------------|------------------------|-------------|----------
 `"off"`     | `LEDS_OFF`     | Disables effect | ![leds-off](img/leds_off.png)
 `"modern"`  | `LEDS_MODERN`  | Gradient-colored LEDs when [`colorMode`](#colormode) is set to `"gradient"` | ![leds-modern](img/leds_modern.png)
 `"vintage"` | `LEDS_VINTAGE` | Single color LEDs, determined by the `level` property of each color - see [registerTheme()](#registertheme) | ![leds-vintage](img/leds_vintage.png)
-Please note that `"modern"` and `"vintage"` will have the same look when [`colorMode`](#colormode) is set to `"bar-level"` or `"bar-index"`, as each bar will be a single color anyway.
+Please note that `"modern"` and `"vintage"` will have the same look when [`colorMode`](#colormode) is set to `"bar-level"` or `"bar-index"`, as each bar will be assigned a single color in both cases.
-?> The height and spacing of LED elements can be customized via [`setLeds()`](#setleds) method.
+?> The appearance of the LED bars can be customized via [`setLedProps()`](#setledprops) method.
 For effect priority when combined with other settings, see [`isLedBars`](#isledbars-read-only).
@@ -715,7 +727,7 @@ This will prevent the canvas size from changing, when switching the low resoluti
 ### `maxDecibels`
-**Value:** a *number*. The default value is `-25`.
+**Value:** a *number*. The default value is `-30`.
 Maximum amplitude value, in decibels, represented in the Y-axis of the analyzer.
@@ -732,9 +744,9 @@ See also [`minDecibels`](#mindecibels) and [`setSensitivity()`](#setsensitivity)
 Determines the maximum desired frame rate for the analyzer animation, in frames per second.
 A value of `0` means the animation will run at the highest frame rate possible, limited by the refresh rate of your display.
-For example, if you have a 144Hz monitor, the frame rate may reach up to 144 fps.
+For example, if you have a 144Hz monitor, the frame rate may reach up to 144 FPS.
-Usually, 60 fps is enough for a smooth animation, so setting `maxFPS` to `60` may help reducing CPU usage on high refresh rate monitors.
+Usually, 60 FPS is enough for a smooth animation, so setting `maxFPS` to `60` may help reducing CPU usage on monitors with higher refresh rates.
 ### `maxFreq`
@@ -749,7 +761,7 @@ See also [`minFreq`](#minfreq) and [`setFreqRange()`](#setfreqrange).
 ### `minDecibels`
-**Value:** a *number*. The default value is `-85`.
+**Value:** a *number*. The default value is `-90`.
 Minimum amplitude value, in decibels, represented in the Y-axis of the analyzer.
@@ -775,11 +787,11 @@ When [`channelLayout`](#channellayout-string) is **dual-horizontal**, this prope
 For other layouts, it horizontally mirrors the spectrum image to the left or right side.
-value  | Description
-:-----:|-------------
-`-1`   | Low frequencies meet at the center of the screen (mirror left)
-`0`    | No mirror effect or change to axis orientation (default)
-`1`    | High frequencies meet at the center of the screen (mirror right)
+Value  | [Constant](#constants) | Description
+:-----:|------------------------|---------------
+`-1`   | `MIRROR_LEFT`  | Low frequencies meet at the center of the screen
+`0`    | `MIRROR_OFF`   | No mirror effect or change to axis orientation (default)
+`1`    | `MIRROR_RIGHT` | High frequencies meet at the center of the screen
 **Note:** On [`radial`](#radial) spectrum with channel layouts other than *dual-horizontal*, both `1` and `-1` have the same effect.
@@ -789,7 +801,7 @@ value  | Description
 Determines the visualization mode.
-value     | [Constant](#constants) | Description
+Value     | [Constant](#constants) | Description
 ----------|------------------------|-----------------
 `"bars"`  | `MODE_BARS`  | displays bars for each frequency or frequency band
 `"graph"` | `MODE_GRAPH` | connects frequency/bands data points into continuous line with optional filled area graph
@@ -804,17 +816,6 @@ See also [`bandResolution`](#bandresolution).
 > 1 through 8   | "bars"  | 9 *minus* legacy mode
 > 10            | "graph" | 0
-### `noteLabels`
-*Available since v4.0.0*
-**Value:** a *boolean* value. The default value is `false`.
-Whether to displays musical note labels instead of frequency values, in the X-axis (when [`showScaleX`](#showscalex) is `true`).
-For best visualization in [octave bands modes](#mode), make sure [`frequencyScale`](#frequencyscale) is set to `"log"`
-and [`ansiBands`](#ansibands) is set to `false`, so bands are tuned to the equal temperament musical scale.
 ### `onCanvasDraw`
 **Value:** a *function* or *undefined*. The default value is `undefined`.
@@ -924,7 +925,7 @@ For effect priority when combined with other settings, see [`isOutlineBars`](#is
 **Value:** a *number*. The default value is `750`.
-Time in milliseconds for peaks to fall down from maximum amplitude to zero, or to completely fade out (when [`fadePeaks`](#fadepeaks) is `true`).
+Time in milliseconds for peaks to fall down from maximum amplitude to zero, or to completely fade out (when [`showPeaks`](#showpeaks) is set to `"fade"`).
 It must be a number greater than or equal to zero. Invalid values are ignored.
@@ -940,7 +941,7 @@ Time in milliseconds for peaks to hold their value before they begin to fall or
 It must be a number greater than or equal to zero. Invalid values are ignored.
-See also [`fadePeaks`](#fadepeaks), [`peakDecayTime`](#peakdecaytime) and [`showPeaks`](#showpeaks).
+See also [`peakDecayTime`](#peakdecaytime) and [`showPeaks`](#showpeaks).
 ### `peakLine`
@@ -952,23 +953,7 @@ Determines the line width used to connect the amplitude peaks, when [`mode`](#mo
 A value of `0` means no line.
-Please note that [`peaks`](#peaks) must be set to either `"drop"` or `"fade"`, although peak lines will always display the *"drop"* behavior.
-### `peaks`
-*Available since v5.0.0; formerly `showPeaks` (since v1.0.0)*
-**Value:** a *string*. The default value is `"drop"`.
-Determines the display and behavior of amplitude peaks.
-value    | [Constant](#constants) | Description
----------|------------------------|--------------
-`"off"`  | `PEAKS_OFF`  | Disable display of amplitude peaks (including [`peakLine`](#peakline))
-`"drop"` | `PEAKS_DROP` | Display peaks that fall down over time
-`"fade"` | `PEAKS_FADE` | Display peaks that fade out over time
-See also [`peakDecayTime`](#peakdecaytime) and [`peakHoldTime`](#peakholdtime).
+Please note that [`showPeaks`](#showpeaks) must be set to either `"drop"` or `"fade"`, although peak lines will always display the *"drop"* behavior.
 ### `pixelRatio` *(read only)*
@@ -989,11 +974,11 @@ You can refer to this value to adjust any additional drawings done in the canvas
 Whether to render the spectrum analyzer as a circle with radial bars.
-value | [Constant](#constants) | Description
+Value | [Constant](#constants) | Description
 ------|------------------------|----------------
-`0`   | `RADIAL_OFF`   | Disables radial
-`1`   | `RADIAL_OUTER` | Bars grow towards the edges of the screen
-`-1`  | `RADIAL_INNER` | Bars grow towards the center of the screen
+`0`   | `RADIAL_OFF`     | Disables radial
+`1`   | `RADIAL_OUTWARD` | Bars grow towards the edges of the screen
+`-1`  | `RADIAL_INWARD`  | Bars grow towards the center of the screen
 When [`channelLayout`](#channellayout) is set to `"dual-vertical"`, left channel bars grow outwards and right channel bars grow inwards, so both `1` and `-1` values have the same effect.
@@ -1092,38 +1077,65 @@ Whether to display the "unlit" LED elements. Has no effect when [`ledBars`](#led
 :----------------------:|:-----------------------:
 ![ledmask-off](img/ledmask_off.png) | ![ledmask-on](img/ledmask_on.png)
+?> The appearance of the LED mask can be customized via [`setLedProps()`](#setledprops).
+### `showPeaks`
+**Value:** a *string*. The default value is `"drop"`.
+Determines the display and behavior of amplitude peaks.
+Value    | [Constant](#constants) | Description
+---------|------------------------|--------------
+`"off"`  | `PEAKS_OFF`  | Disable display of amplitude peaks and [`peakLine`](#peakline)
+`"drop"` | `PEAKS_DROP` | Display peaks that fall down over time
+`"fade"` | `PEAKS_FADE` | Display peaks that fade out over time
+See also [`peakDecayTime`](#peakdecaytime) and [`peakHoldTime`](#peakholdtime).
 ### `showScaleX`
 *Available since v3.0.0; formerly `showScale` (since v1.0.0)*
-**Value:** a *boolean* value. The default value is `true`.
+**Value:** a *string*. The default value is `"freqs"`.
 Whether to display scale labels on the X-axis.
-Several properties of the scale can be customized via [`setXAxis()`](#setxaxis) method.
+Value            | [Constant](#constants)  | Description
+-----------------|-------------------------|---------------
+`"off"`          | `LABELS_X_OFF`          | Do not display scale labels on the X-axis.
+`"custom"`       | `LABELS_X_CUSTOM`       | Display custom `labels` defined via [`setScaleProps()`](#setscaleprops).
+`"freqs"`        | `LABELS_X_FREQS`        | Display octaves center frequencies - see also [`ansiBands`](#ansibands).
+`"freqs+custom"` | `LABELS_X_FREQS_CUSTOM` | Display center frequencies and any additional custom labels.
+`"notes"`        | `LABELS_X_NOTES`        | Display musical note labels.
+Several display properties of the scale can be customized via [`setScaleProps()`](#setscaleprops) method.
-See also [`noteLabels`](#notelabels).
+?> For best results of `"notes"` setting in [octave bands modes](#bandresolution), make sure [`frequencyScale`](#frequencyscale) is set to `"log"` and [`ansiBands`](#ansibands) is set to `false`, so bands are tuned to the equal temperament musical scale.
 ### `showScaleY`
 *Available since v2.4.0*
-**Value:** a *boolean* value. The default value is `false`.
+**Value:** a *string*. The default value is `"off"`.
 Whether to display the level/amplitude scale on the Y-axis.
-This option has no effect when [`radial`](#radial) is active or [`alphaBars`](#alphabars) is set to `"full"`.
+Value       | [Constant](#constants) | Description
+------------|------------------------|---------------
+`"off"`     | `LABELS_Y_OFF`         | Do not display scale labels on the Y-axis.
+`"db"`      | `LABELS_Y_DB`          | Display labels in decibels.
+`"percent"` | `LABELS_Y_PERCENT`     | Display labels in percent values.
-When [`linearAmplitude`](#linearamplitude) is set to *false* (default), labels are shown in decibels (dB);
-otherwise, values represent a percentage (0-100%) of the maximum amplitude.
+This option has no effect when [`radial`](#radial) is active or [`alphaBars`](#alphabars) is set to `"full"`.
-Several properties of the scale can be customized via [`setYAxis()`](#setyaxis) method.
+Several display properties of the scale can be customized via [`setScaleProps()`](#setscaleprops) method.
 See also [`minDecibels`](#mindecibels) and [`maxDecibels`](#maxdecibels).
 ### `smoothing`
-**Value:** a *number*. The default value is `0.5`.
+**Value:** a *number*. The default value is `0.7`.
 Determines the analyzer's [smoothingTimeConstant](https://developer.mozilla.org/en-US/docs/Web/API/AnalyserNode/smoothingTimeConstant).
@@ -1188,27 +1200,28 @@ Please note that changing the volume on the audio element will affect the amplit
 *Available since v4.0.0*
-[Weighting filter](https://en.wikipedia.org/wiki/Weighting_filter) applied to analyzer data, for spectrum visualization only.
-<img src="img/weigthing-filters-curves.png" class="align-right">
+[Weighting filter](https://en.wikipedia.org/wiki/Weighting_filter) applied to analyzer data, for spectrum visualization.
+Each filter applies a different curve of gain/attenuation to specific frequency ranges, but the general idea is to adjust the
+visualization of frequencies to the sensitivity of the human ear.
-**Value:** a *string*. The default value is `""`.
+**Value:** a *string*. The default value is `"none"`.
-Value   | [Constant](#constants) | Description
---------|------------------------|---------------
-`""`    | `FILTER_NONE` | No weighting applied (default)
-`"A"`   | `FILTER_A`    | A-weighting
-`"B"`   | `FILTER_B`    | B-weighting
-`"C"`   | `FILTER_C`    | C-weighting
-`"D"`   | `FILTER_D`    | D-weighting
-`"468"` | `FILTER_468`  | ITU-R 468 weighting
+<img src="img/weigthing-filters-curves.png" class="align-right">
-?> Weighting filters only affect the visualization, **NOT** the audio output.
+Value       | [Constant](#constants) | Description
+------------|------------------------|---------------
+`"none"`    | `FILTER_NONE`   | No weighting applied (default)
+`"a"`       | `FILTER_A`      | A-weighting
+`"b"`       | `FILTER_B`      | B-weighting
+`"c"`       | `FILTER_C`      | C-weighting
+`"d"`       | `FILTER_D`      | D-weighting
+`"468"`     | `FILTER_468`    | ITU-R 468 weighting
+`"tilt3"`   | `FILTER_TILT3`  | 3dB per octave tilt
+`"tilt4.5"` | `FILTER_TILT45` | 4.5dB per octave tilt
-Each filter applies a different curve of gain/attenuation to specific frequency ranges, but the general idea is to adjust the
-visualization of frequencies to the sensitivity of the human ear.
+?> Refer to the [**weighting filters viewer tool**](/tools/weighting-filters.html) for filter response tables and an interactive version of the graph seen above.
-Refer to the [weighting filters viewer tool](/tools/weighting-filters.html) for response tables and an interactive version of the curves graph seen below.
+!> Weighting filters only affect the spectrum visualization, **NOT** the audio output.
 ### `width`
@@ -1232,77 +1245,121 @@ Since this is a static property, you should always access it as `AudioMotionAnal
 ## Methods
-### `connectInput( source )`
+### `connectInput()`
 *Available since v3.0.0*
-Connects an [HTMLMediaElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement) or an [AudioNode](https://developer.mozilla.org/en-US/docs/Web/API/AudioNode)
-(or any of its descendants) to the analyzer.
+Connects an audio source to the analyzer.
+**Syntax:**
+```js
+connectInput(source)
+```
+Parameter | type | description
+----------|------|---------------
+`source`  | *object* | an [AudioNode](https://developer.mozilla.org/en-US/docs/Web/API/AudioNode) (or any of its descendants), [HTMLMediaElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement) or [MediaStream](https://developer.mozilla.org/en-US/docs/Web/API/MediaStream) object
+When `source` is an *HTMLMediaElement* or *MediaStream*, a [MediaElementAudioSourceNode](https://developer.mozilla.org/en-US/docs/Web/API/MediaElementAudioSourceNode)
+or [MediaStreamAudioSourceNode](https://developer.mozilla.org/en-US/docs/Web/API/MediaStreamAudioSourceNode) object will be created, respectivelly.
+If `source` is not a valid object, an [`ERR_INVALID_AUDIO_SOURCE`](#custom-errors) error is thrown.
-If `source` is an *HTMLMediaElement*, the method returns a [MediaElementAudioSourceNode](https://developer.mozilla.org/en-US/docs/Web/API/MediaElementAudioSourceNode) created
-for that element; if `source` is an *AudioNode* instance, it returns the `source` object itself; if it's neither an [ERR_INVALID_AUDIO_SOURCE](#custom-errors) error is thrown.
+**Return value:** an *AudioNode* object, representing the actual audio node connected.
-See also [`disconnectInput()`](#disconnectinput-node-stoptracks-) and [`connectedSources`](#connectedsources-array-read-only).
+See also [`disconnectInput()`](#disconnectinput) and [`connectedSources`](#connectedsources-read-only).
-### `connectOutput( [node] )`
+### `connectOutput()`
 *Available since v3.0.0*
 This method allows connecting the analyzer **output** to other audio processing modules that use the Web Audio API.
-`node` must be an [*AudioNode*](https://developer.mozilla.org/en-US/docs/Web/API/AudioNode) instance.
+**Syntax:**
-By default, the analyzer is connected to the speakers upon instantiation, unless you set [`connectSpeakers: false`](#connectspeakers) in the constructor options.
+```js
+connectOutput()
+connectOutput(node)
+```
-See also [`disconnectOutput()`](#disconnectoutput-node-) and [`connectedTo`](#connectedto-array-read-only).
+Parameter | type | description
+----------|------|---------------
+`node`    | [*AudioNode*](https://developer.mozilla.org/en-US/docs/Web/API/AudioNode) | If not specified, output is connected to the speakers (the *AudioContext* `destination` node).
-?> If called with no argument, analyzer output is connected to the speakers (the *AudioContext* `destination` node).
+By default, the analyzer is already connected to the speakers upon instantiation, unless you set [`connectSpeakers: false`](#connectspeakers) in the constructor options.
+**Return value:** none (`undefined`).
+See also [`disconnectOutput()`](#disconnectoutput) and [`connectedTo`](#connectedto-read-only).
 ### `destroy()`
 *Available since v4.2.0*
-Destroys the **audioMotion-analyzer** instance and release resources. A destroyed analyzer cannot be started again.
+Destroys the **audioMotion-analyzer** instance and releases resources. A destroyed analyzer cannot be started again.
+**Syntax:**
+```js
+destroy()
+```
 This method:
 + Stops the analyzer data processing and animation;
 + Disconnects all input and output nodes;
 + Clears event listeners and callback functions;
-+ Stops the *AudioContext* created by this instance (won't affect context provided to the [constructor](#constructor) via [`audioCtx`](#audioctx-audiocontext-object) property or an *AudioNode* [`source`](#source-htmlmediaelement-or-audionode-object));
++ Stops the *AudioContext* created by this instance (won't affect context provided to the [constructor](#constructor) via [`audioCtx`](#audioctx) property or an *AudioNode* [`source`](#source));
 + Removes the [`canvas`](#canvas-htmlcanvaselement-object-read-only) from the DOM.
 See usage example in the [minimal demo](/demo/minimal.html).
+**Return value:** none (`undefined`).
 See also [`isDestroyed`](#isdestroyed-read-only).
-### `disconnectInput( [node], [stopTracks] )`
+### `disconnectInput()`
 *Available since v3.0.0; `stopTracks` parameter since v4.2.0*
 Disconnects audio source nodes previously connected to the analyzer.
-`node` may be an *AudioNode* instance or an **array** of such objects. If it's **undefined** (or any [*falsy*](https://developer.mozilla.org/en-US/docs/Glossary/Falsy) value),
-**all connected sources are disconnected.**
+**Syntax:**
+```js
+disconnectInput()
+disconnectInput(sources)
+disconnectInput(sources, stopTracks)
+```
-`stopTracks` is a boolean value; if **true**, permanently stops all audio tracks from any [*MediaStream*](https://developer.mozilla.org/en-US/docs/Web/API/MediaStream)s being
-disconnected, e.g. a microphone. Use it to effectively release the stream if it's no longer needed.
+Parameter    | type | description
+-------------|------|---------------
+`sources`    | *object* or *array* | a previously connected [AudioNode](https://developer.mozilla.org/en-US/docs/Web/API/AudioNode), [HTMLMediaElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement) or [MediaStream](https://developer.mozilla.org/en-US/docs/Web/API/MediaStream), or an array of such objects. **When [*falsy*](https://developer.mozilla.org/en-US/docs/Glossary/Falsy), all connected sources are disconnected.**
+`stopTracks` | *boolean* | if `true`, permanently stops all audio tracks from any [*MediaStream*](https://developer.mozilla.org/en-US/docs/Web/API/MediaStream)s being disconnected.
-Please note that when you have connected an `<audio>` or `<video>` element, you need to disconnect the respective [MediaElementAudioSourceNode](https://developer.mozilla.org/en-US/docs/Web/API/MediaElementAudioSourceNode)
-created for it. The node reference is returned by [`connectInput()`](#connectinput-source-), or can be obtained from [`connectedSources`](#connectedsources-array-read-only)
-if the element was connected via [`source`](#source-htmlmediaelement-or-audionode-object) constructor option.
+**Return value:** none (`undefined`).
-### `disconnectOutput( [node] )`
+### `disconnectOutput()`
 *Available since v3.0.0*
 Disconnects the analyzer output from previously connected audio nodes.
-`node` must be a connected *AudioNode*.
+**Syntax:**
-See also [`connectOutput()`](#connectoutput-node-).
+```js
+disconnectOutput()
+disconnectOutput(node)
+```
-?> If called with no argument, analyzer output is disconnected from all nodes, **including the speakers!**
+Parameter | type | description
+----------|------|---------------
+`node`    | *AudioNode* | must be a connected *AudioNode*. If not specified, analyzer output is disconnected from all nodes, **including the speakers!**
+**Return value:** none (`undefined`).
+See also [`connectOutput()`](#connectoutput).
 ### `getBars()`
@@ -1325,7 +1382,7 @@ Returns an array with current data for each analyzer bar. Each array element is
 `peak` and `value` elements are floats between 0 and 1, relative to the lowest and highest volume levels defined by [`minDecibels`](#mindecibels) and [`maxDecibels`](#maxdecibels).
 `hold` values are integers and indicate the hold time (in frames) for the current peak.
-Negative values mean the peak is currently fading or falling down, depending on the value of [`fadePeaks`](#fadepeaks).
+Negative values mean the peak is currently falling down or fading out.
 Please note that `hold` and `value` will have only one element when [`channelLayout`](#channellayout-string) is set to *'single'*, but `peak` is always a two-element array.
@@ -1370,6 +1427,14 @@ Use this method inside your callback function to create additional visual effect
 **Return value:** a *number* between `0.0` and `1.0`, or `null` if preset name is invalid.
+### `getLedProps()`
+*Available since v5.0.0*
+Retrieves the current properties used to create the [`ledBars`](#ledbars) effect.
+**Return value:** an *object*. Refer to [`setLedProps()`](#setledprops) for available properties.
 ### `getOptions()`
 *Available since v4.4.0*
@@ -1393,28 +1458,46 @@ Callbacks and [constructor-specific properties](#constructor-specific-options) a
 See also [`setOptions()`](#setoptions).
+### `getScaleProps()`
+*Available since v5.0.0*
+Retrieves the current scale display properties on both axes.
+**Syntax:**
+```js
+getScaleProps()
+```
+**Return value:** an *object* - see [`setScaleProps()`](#setscaleprops) for object structure.
 ### `getTheme()`
 *Available since v5.0.0*
-Returns the name of the theme set for the given channel.
+Retrieves the active theme name and, optionally, the state of theme modifiers for one or both analyzer channels.
 **Syntax:**
 ```js
-getTheme()
-getTheme(channel, includeModifiers)
-getTheme(includeModifiers)
+getTheme()                          // returns theme names for both channels (array of strings)
+getTheme(includeModifiers)          // returns theme and modifiers for both channels (array of objects)
+getTheme(channel)                   // returns theme name for given channel (string)
+getTheme(channel, includeModifiers) // returns theme and modifiers for given channel (object)
 ```
 Parameter | type | description
 ----------|------|-----------------
-`channel` | *number* | *(optional)* channel to set (`0` = left, `1` = right) - if not specified, considers channel 0
-`includeModifiers` | *boolean* | *(optional)* `true` to also return the state of theme modifiers
+`channel` | *number* | Channel index (`0` = left, `1` = right). If omitted or invalid, returns data for both channels in an array.
+`includeModifiers` | *boolean* | If `true`, includes the state of theme modifiers (returns an object).
-**Return value:** a *string* representing the theme name, or an *object* with `name` and `modifiers` properties.
+**Return value:**
+- *string* → theme name (single channel, no modifiers)
+- *object* → `{ name, modifiers }` (single channel with modifiers)
+- *array* → of strings or objects (both channels)
-See also [`setTheme()`](#settheme).
+See also [`getThemeModifiers()`](#getthememodifiers) and [`setTheme()`](#settheme).
 ### `getThemeData()`
@@ -1432,7 +1515,7 @@ getThemeData(name)
 **Return value:** an *object* (structure below) or `null` if theme name is invalid.
-property | type | description
+Property | type | description
 ---------|------|---------------
 `colorStops` | *array*  | all entries are normalized as objects with `color`, `level` and `pos` properties
 `peakColor`  | *string* | `undefined` if not originally defined in [theme registration](#registertheme)
@@ -1462,6 +1545,27 @@ Returns the names of available themes, including built-in and custom registered
 **Return value:** an *array* of *string*s.
+### `getThemeModifiers()`
+*Available since v5.0.0*
+Returns the state of theme modifiers for the given channel.
+**Syntax:**
+```js
+getThemeModifiers()
+getThemeModifiers(channel)
+```
+Parameter  | type     | description
+-----------|----------|-----------------
+`channel`  | *number* | Channel index (`0` = left, `1` = right) - **if omitted, considers channel 0**
+**Return value:** an *object* - see [`setThemeModifiers()`](#setthememodifiers) for object structure.
+See also [`getTheme()`](#gettheme).
 ### `registerTheme()`
 *Available since v5.0.0; formerly `registerGradient()` (since v1.0.0)*
@@ -1474,21 +1578,21 @@ Registers a custom color theme.
 registerTheme(name, options)
 ```
-parameter | type | description
+Parameter | type | description
 ----------|------|-------------
 `name`    | *string* | Names are **case sensitive** and will be used to select the theme via [`setTheme()`](#settheme) method.
 `options` | *object* | Contains the color information (see below).
 **`options` object structure:**
-property     | type   | description
+Property     | type   | description
 -------------|--------|-------------
 `colorStops` | *array*  | **At least one array element is required.** Each one must be either a *string* (color in CSS format), or an *object* (see below).
 `peakColor`  | *string* | Optional; if defined, **all peaks** will be painted this color, regardless of their levels.
-**`colorStops` color object structure:**
+**`colorStops` entry object structure:**
-property | type   | description
+Property | type   | description
 ---------|--------|-------------
 `color`  | *string* | Any valid CSS color format, e.g. 'red', '#f00', 'rgb(…)', 'hsl(…)', etc.
 `level`  | *number* | Optional; sets the **upper level** threshold for applying this color to a bar (when [`colorMode`](#colormode-string) is set to `"bar-level"`) or LED segment (when [`ledBars`](#ledbars) is set to `"vintage"`). It must be a number between `0` and `1`, where `1` is the maximum amplitude (top of screen).
@@ -1539,10 +1643,28 @@ Theme | [`ledBars`](#ledbars) = `"off"` | [`ledBars`](#ledbars) = `"vintage"` |
 **bluey-B**<br>(custom `pos` / custom `level`)   | ![bluey-b-gradient](img/levels-bluey-b-gradient.png) | ![bluey-b-trueleds](img/levels-bluey-b-trueleds.png) | ![bluey-b-barlevel](img/levels-bluey-b-barlevel.png)
-See also: [unregisterTheme()](#unregistertheme-name)
+See also: [unregisterTheme()](#unregistertheme)
 ?> Any color theme, including the built-in ones, may be modified at any time by simply re-registering the same theme name.
+### `renderFrame()`
+*Available since v5.0.0*
+Stops normal analyzer animation and renders a single frame, using custom data.
+**Syntax:**
+```js
+renderFrame(barData)
+```
+Parameter | type    | description
+----------|---------|-------------
+`barData` | *array* | An array of numbers between `0.0` and `1.0`, each corresponding to one analyzer bar. Each array element can also be an array of two numbers, for dual-channel layouts.
+**Return value:** none (`undefined`).
 ### `setCanvasSize()`
 Shortand hand method for setting both [`height`](#height) and [`width`](#width) properties at once.
@@ -1567,27 +1689,35 @@ setFreqRange(minFreq, maxFreq)
 **Return value:** none (`undefined`).
-### `setLeds()`
+### `setLedProps()`
 *Available since v5.0.0; formerly `setLedParams()` (since v3.2.0)*
-Customizes the appearance of LED elements used to create the [`ledBars`](#ledbars) effect.
+Customizes the appearance of the [`ledBars`](#ledbars) effect.
 **Syntax:**
 ```js
-setLeds(ledHeight, gapHeight)
+setLedProps()
+setLedProps(props)
 ```
-parameter   | type     | description     | default
+**If `props` is omitted or not an object, ALL properties are reset to their default values.**
+To reset a specific property to its default, set it to `null` in the passed object.
+Property    | type     | description     | default
 ------------|----------|-----------------|----------:
 `ledHeight` | *number* | Height, in pixels, of each LED element. **A value of `0` will match the bar width (generates square LEDs).** | `8`
-`gapHeight` | *number* | Vertical gap, in pixels, between two consecutive LED elements. **A value of `0` will match the current [bar spacing](#barSpace).** | `8`
-**If called with no argument, or if ANY of the values is invalid, BOTH parameters are reset to their default values.**
+`gapHeight` | *number* | Vertical gap, in pixels, between two consecutive LED elements. **A value of `0` will match the current [bar spacing](#barSpace).** | `5`
+`maskAlpha` | *number* | Transparency of the LED mask, between `0.0` (fully transparent) and `1.0` (fully opaque). | `0.2`
+`maskLightness`  | *number* | Color lightness for the LED mask, between `0` (pure black) and `100` (pure white), with `50` being the normal color intensity. **A value of `-1` will preserve the original lightness of theme colors.** | `-1`
+`maskSaturation` | *number* | Color saturation for the LED mask, between `0` (grayscale) and `100` (full saturation). **A value of `-1` will preserve the original saturation of theme colors.** | `20`
 **Return value:** none (`undefined`).
+See also [`getLedProps()`](#getledprops) and [`showLedMask`](#showledmask).
 ?> You can experiment with different values in the [fluid demo](https://audiomotion.dev/demo/fluid.html).
 ### `setOptions()`
@@ -1619,153 +1749,152 @@ setSensitivity(minDecibels, maxDecibels)
 **Return value:** none (`undefined`).
-### `setTheme()`
+### `setScaleProps()`
 *Available since v5.0.0*
-Sets the color theme for one or both analyzer channels.
+Customize the scale appearance on one or both axes.
 **Syntax:**
 ```js
-setTheme(name, channel)
-setTheme(name, modifiers, channel)
-setTheme(themeObject, channel)
+setScaleProps()
+setScaleProps(props)
 ```
-Parameter     | type   | description
---------------|--------|------------------
-`name`        | *string* or *array* | theme name, or an array of theme names - must be a name as returned by [`getThemeList()`](#getthemelist)
-`modifiers`   | *object* | *(optional)* a modifiers object, as returned by [`getThemeModifiers()`](#getthememodifiers)
-`themeObject` | *object* or *array* | a theme object, as returned by [`getTheme()`](#gettheme) or an array of such objects
-`channel`     | *number* | *(optional)* channel to set (`0` = left, `1` = right)
+**If `props` is omitted, ALL properties will be reset to their default values.**
-When passing arrays for `name` or `themeObject` you can assign different themes to each channel at once.
-When using a single `name` or `themeObject`, if `channel` is not specified, the same theme will be applied to both channels.
+`props` object:
-!> Note that when setting theme modifiers, properties not defined in the passed object will be reset to their default values. To selectively enable or disable modifiers while preserving others, use [`setThemeModifiers( name, state )`](#setthememodifiers).
+Property | type     | description
+---------|----------|-------------
+`xAxis`  | *object* | X-axis scale properties (see below). A value of `null` will reset only the X-axis properties to their defaults.
+`yAxis`  | *object* | Y-axis scale properties (see below). A value of `null` will reset only the Y-axis properties to their defaults.
-**Return value:** none (`undefined`).
+`xAxis` object (all properties are optional):
-See also [`channelLayout`](#channellayout), [`registerTheme()`](#registertheme) and [`spreadGradient`](#spreadgradient).
+Property           | type      | description | default
+-------------------|-----------|-------------|---------
+`backgroundColor`  | *string*  | Background color of the X-axis. Any valid CSS color format is acceptable. Use a blank string or `"transparent"` for fully transparent background | `"#0008"`
+`color`            | *string*  | Color of labels | `"#fff"`
+`fontSize`         | *number*  | Font size for labels. For responsive behavior, values between `0.0` and `1.0` represent a fraction of one tenth of the canvas width or height (whichever is smaller). A minimum of 10px is enforced for the computed value. Values greater than `1` are interpreted as fixed pixel sizes. | `0.15`
+`highlightColor`   | *string*  | Color used to highlight *C* notes when [`showScaleX`](#showscalex) is set to `"notes"`, and for labels highlighted via `labels` property (see below) | `"#4f4"`
+`labels`           | *array*   | Custom labels displayed when [`showScaleX`](#showscalex) is set to `"custom"` or `"freqs+custom"`. Each element of the array must be either a number, representing the frequency in Hz, or an array of **[ &lt;frequency&gt; *(number)*, &lt;label&gt; *(string)*, &lt;highlight&gt; *(boolean, optional)* ]** (see example below) | octaves center frequencies
+`overlay`          | *boolean* | Whether the X-axis should overlay the bottom of the analyzer area | `false`
-### `setThemeModifiers()`
+`yAxis` object (all properties are optional):
-**Syntax:**
+Property           | type      | description | default
+-------------------|-----------|-------------|---------
+`color`            | *string*  | Color of labels and lines | `"#888"`
+`compositing`      | *string*  | Compositing operation used to draw labels and lines. See [Reference](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/globalCompositeOperation). **Note: some compositing operations may hinder or prevent the proper visualization of analyzer graphs.** | `"destination-over"`
+`dbInterval`       | *number*  | Interval between labels, in decibels. Applied when [`showScaleY`](#showscaley) is set to `"db"`. | `6`
+`fontSize`         | *number*  | Font size for labels. For responsive behavior, values between `0.0` and `1.0` represent a fraction of one tenth of the canvas width or height (whichever is smaller). A minimum of 10px is enforced for the computed value. Values greater than `1` are interpreted as fixed pixel sizes. | `0.15`
+`lineDash`         | *array*   | Line style. See [format reference](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/setLineDash) | `[2,4]`
+`percentInterval`  | *number*  | Interval between labels, in percentage values. Applied when [`showScaleY`](#showscaley) is set to `"percent"` | `20`
+`showSubdivisions` | *boolean* | Whether to show subdivision lines between two labels | `true`
+`showUnit`         | *boolean* | Whether to display the scale unit ("dB" or "%") at the top of the axis | `true`
+`subLineColor`     | *string*  | Line color used for subdivisions | `"#555"`
+`subLineDash`      | *array*   | Line style for subdivisions (see `lineDash` above) | `[2,8]`
-```js
-setThemeModifiers()
-setThemeModifiers(modifier, state, channel)
-setThemeModifiers(modifiersObject, channel)
-```
+**Return value:** none (`undefined`).
-Parameter     | type   | description
---------------|--------|------------------
-`modifier`    | *string* | modifier to set (see below)
-`state`       | *boolean* | desired state for selected modifier
-`modifiersObject` | *object* | modifiers object, as returned by [`getThemeModifiers()`](#getthememodifiers)
-`channel`         | *number* | *(optional)* channel to set (`0` = left, `1` = right)
+**Example usage:**
-Modifier | description
----------|----------------
-`"horizontal"` | Renders the color gradient horizontally across the screen, instead of vertically - has no effect in [`radial`](#radial) spectrum or when [`ledBars`](#ledbars) is set to `"vintage"`
-`"revert"`     | Reverts the order of the theme colors
+```js
+audioMotion.setScaleProps({
+    xAxis: {
+        backgroundColor: '',   // transparent background on the axis bar
+        labels: [
+          [ 440, 'A4', true ], // highlight "A4" label at 440 Hz
+          800,                 // additional label at 800 Hz
+          [ 3000, '|' ],       // just a tick mark at 3 kHz
+        ],
+    },
+    yAxis: {
+        compositing: 'screen',
+        percentInterval: 10,
+        showSubdivisions: false,
+    }
+});
+```
-**Return value:** none (`undefined`).
+See also [`getScaleProps()`](#getscaleprops), [`showScaleX`](#showscalex) and [`showScaleY`](#showscaley).
-### `setXAxis()`
+### `setTheme()`
 *Available since v5.0.0*
-Customize the appearance of the X-axis labels.
+Sets the color theme for one or both analyzer channels.
 **Syntax:**
 ```js
-setXAxis()
-setXAxis(options)
+// set same theme (and modifiers) on both channels
+setTheme() // reset themes and modifiers to defaults
+setTheme(name)
+setTheme(name, modifiers)
+setTheme(themeObject)
+// set different theme (and modifiers) on each channel
+setTheme([name, name])
+setTheme([themeObject, themeObject])
+// set theme (and modifiers) per channel
+setTheme(channel) // reset to defaults only on given channel
+setTheme(channel, name)
+setTheme(channel, name, modifiers)
+setTheme(channel, themeObject)
 ```
-**If called with no argument, all properties will be reset to their default values.**
+Parameter     | type     | description
+--------------|----------|------------------
+`channel`     | *number* | Channel index to set (`0` = left, `1` = right)
+`name`        | *string* | Valid theme name - see [`getThemeList()`](#getthemelist)
+`modifiers`   | *object* | Modifiers object - see [`setThemeModifiers()`](#setthememodifiers)
+`themeObject` | *object* | Theme object, as returned by [`getTheme()`](#gettheme) with the `includeModifiers` argument set to `true`
-If `options` is defined, it should be an object with the structure below (all properties are optional).
+When passing arrays for `name` or `themeObject` you can assign different themes to each channel at once.
+When using a single `name` or `themeObject`, if `channel` is not specified, the same settings will be applied to both channels.
-property           | type      | description | default
--------------------|-----------|-------------|---------
-`addLabels`        | *boolean* | Contents of `labels` will be *added* to the default labels, instead of replacing them | `false`
-`backgroundColor`  | *string*  | Background color of the X-axis; any valid CSS color format is acceptable; use a blank string or 'transparent' for fully transparent background | `"#0008"`
-`color`            | *string*  | Color of labels | `"#fff"`
-`height`           | *number*  | Height of the X-axis; a number between `0.0` and `1.0` (recommended for responsivity) represents a fraction of the canvas width or height, whichever is smaller; numbers greater than 1 represent a fixed value in pixels | `0.03`
-`highlightColor`   | *string*  | Color used to highlight *C* notes when [`noteLabels`](#notelabels) is *true*, or those highlighted via `labels` definition (see below) | `"#4f4"`
-`labels`           | *array*   | Custom labels; each element of the array must be either a number, representing the frequency, or an array of [frequency&lt;number&gt;, label&lt;string&gt;, highlight?&lt;boolean&gt;] | octaves center frequencies
-`overlay`          | *boolean* | Whether the X-axis should overlay the bottom of the analyzer area | `false`
+**When called without arguments, resets theme and modifiers to defaults on both channels. If only a channel is specified, resets on given channel only.**
 **Return value:** none (`undefined`).
-**Example usage:**
+See also [`channelLayout`](#channellayout), [`registerTheme()`](#registertheme), [`setThemeModifiers()`](#setthememodifiers) and [`spreadGradient`](#spreadgradient).
-```js
-audioMotion.setXAxis({
-    addLabels: true,       // add custom labels on top of default ones
-    backgroundColor: '',   // transparent background on the axis bar
-    labels: [
-      [ 440, 'A4', true ], // highlight A4 label at 440 Hz
-      800,                 // additional label at 800 Hz
-      [ 3000, '|' ],       // just a tick mark at 3 kHz
-    ],
-});
-```
-> **Notes:**
->
-> - The axis height also defines the labels font size (half its value). A minimum of 20 pixels is enforced for the computed `height` value;
-> - Custom labels are not displayed when [`noteLabels`](#notelabels) is *true*.
-### `setYAxis()`
+### `setThemeModifiers()`
 *Available since v5.0.0*
-Customize the appearance of the Y-axis labels.
+Sets theme modifiers for one or both analyzer channels.
 **Syntax:**
 ```js
-setYAxis()
-setYAxis(options)
+setThemeModifiers()                   // reset modifiers to defaults on both channels
+setThemeModifiers(channel)            // reset to defaults on given channel only
+setThemeModifiers(modifiers)          // set same modifiers on both channels
+setThemeModifiers(channel, modifiers) // set modifiers on given channel only
 ```
- **If called with no argument, all properties will be reset to their default values.**
+Parameter   | type     | description
+------------|----------|------------------
+`channel`   | *number* | Channel index to set (`0` = left, `1` = right)
+`modifiers` | *object* | Modifiers object (see below)
-If `options` is defined, it should be an object with the structure below (all properties are optional).
+**When called without arguments, resets modifiers to defaults on both channels. If only a channel is specified, resets on given channel only.**
-property         | type    | description | default
------------------|---------|-------------|---------
-color            | string  | Color of labels and lines | `"#888"`
-dbInterval       | number  | Interval between labels, in decibels - used when [`linearAmplitude`](#linearamplitude) is *false* | `10`
-linearInterval   | number  | Interval between labels, in percentage values - used when [`linearAmplitude`](#linearamplitude) is *true* | `20`
-lineDash         | array   | Line style - [format reference](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/setLineDash) | `[2,4]`
-operation        | array   | Compositing operation used to draw labels and lines - [Reference](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/globalCompositeOperation) | `"destination-over"`
-showSubdivisions | array   | Whether to show subdivision lines between two labels | `true`
-subLineColor     | string  | Line color used for subdivisions | `"#555"`
-subLineDash      | array   | Line style for subdivisions (see `lineDash` above) | `[2,8]``
-width            | number  | Width of the Y-axis; a number between `0.0` and `1.0` represents a fraction of the canvas width or height, whichever is smaller; numbers greater than `1` represent a fixed value in pixels | `0.03`
+`modifiers` object structure:
-**Return value:** none (`undefined`).
-**Example usage:**
+Property     | type      | description
+-------------|-----------|---------------
+`horizontal` | *boolean* | `true` to create a horizontal color gradient - has no effect in [`radial`](#radial) spectrum or when [`ledBars`](#ledbars) is set to `"vintage"`
+`reverse`    | *boolean* | `true` to reverse the order in which theme colors are applied
-```js
-audioMotion.setYAxis({
-  linearInterval: 10,
-  operation: 'screen',
-  showSubdivisions: false,
-});
-```
+**Return value:** none (`undefined`).
-> **Notes:**
->
-> - The axis width also affects the labels font size (half its value). A minimum of 20 pixels is enforced for the computed `width` value;
-> - Some values of `operation` may make the visualization of analyzer graphs impossible.
+See also [`getThemeModifiers()`](#getthememodifiers) and [`setTheme()`](#settheme).
 ### `start()`
@@ -1804,7 +1933,7 @@ toggleAnalyzer()
 toggleAnalyzer(force)
 ```
-parameter | type | description
+Parameter | type | description
 ----------|------|------------
 `force`   | *boolean* | forces the desired state - `true` to start or `false` to stop the analyzer
@@ -1823,6 +1952,50 @@ You can set the [`fsElement`](#fselement-htmlelement-object) constructor option
 ?> Fullscreen requests must be triggered by user action, like a key press or mouse click, so you must call this method from within a user-generated event handler.
+### `unregisterTheme()`
+*Available since v5.0.0*
+Unregisters a color theme.
+**Syntax:**
+```js
+unregisterTheme(name)
+```
+Parameter | type     | description
+----------|----------|---------------
+`name`    | *string* | Valid theme name. May include built-in themes. See [`getThemeList()`](#getthemelist).
+**Return value:** a *boolean* value. `true` on success, or `false` if theme is in use or not registered.
+See also [`registerTheme()`](#registertheme).
+## Static Methods
+### `weightingGain()`
+*Available since v5.0.0*
+Returns gain, in decibels, to correct the amplitude value at a given frequency, according to the specified weighting filter.
+**Syntax:**
+```js
+AudioMotionAnalyzer.weightingGain(frequency, filter)
+```
+*Since this is a static method, always call it as `AudioMotionAnalyzer.weightingGain()`, rather than as a method of an instantiated object.*
+Parameter   | type     | description
+------------|----------|-----------------
+`frequency` | *number* | Frequency value, in Hz
+`filter`    | *string* | A valid [weighting filter](#weightingfilter)
+**Return value:** a *number*, representing the gain or attenuation (in dB) to be applied to the original amplitude value.
 ## Custom Errors
@@ -1832,11 +2005,11 @@ You can set the [`fsElement`](#fselement-htmlelement-object) constructor option
 The `code` property is a *number*. [Constants](#constants) are available to simplify checking for error codes.
-code | Constant            | Error description
------|---------------------|--------------------
-`1`  | `ERR_AUDIO_CONTEXT_FAIL`    | Could not create audio context. The user agent may lack support for the Web Audio API.
-`2`  | `ERR_INVALID_AUDIO_CONTEXT` | [Audio context](#audioctx-read-only) provided by user is not valid.
-`3`  | `ERR_INVALID_AUDIO_SOURCE`  | Audio source provided in [`source`](#source) option or [`connectInput()`](#connectinput) method is not an instance of HTMLMediaElement or AudioNode.
+`code` | Constant            | Error description
+-------|---------------------|--------------------
+`1`    | `ERR_AUDIO_CONTEXT_FAIL`    | Could not create audio context. The user agent may lack support for the Web Audio API.
+`2`    | `ERR_INVALID_AUDIO_CONTEXT` | [Audio context](#audioctx-read-only) provided by user is not valid.
+`3`    | `ERR_INVALID_AUDIO_SOURCE`  | Audio source provided in [`source`](#source) option or [`connectInput()`](#connectinput) method is not an instance of *HTMLMediaElement*, *MediaStream* or *AudioNode*.
 ## Known Issues
@@ -1865,7 +2038,7 @@ The `import` statement must be inside a `script` which has the `type="module"` p
 ```html
   <script type="module">
-    import AudioMotionAnalyzer from 'https://cdn.jsdelivr.net/npm/audiomotion-analyzer@alpha/+esm';
+    import AudioMotionAnalyzer from 'https://cdn.jsdelivr.net/npm/audiomotion-analyzer@beta/+esm';
     // your code here
   </script>
@@ -1894,7 +2067,7 @@ myAudio.crossOrigin = 'anonymous';
 ### Sound only plays after the user clicks somewhere on the page. <!-- {docsify-ignore} -->
 Browser autoplay policy dictates that audio output can only be initiated by a user gesture, and this policy is enforced by Web Audio API
-by putting [*AudioContext*](#audioctx-audiocontext-object-read-only) objects into *suspended* mode if they're not created on user action.
+by putting [*AudioContext*](#audioctx-read-only) objects into *suspended* mode if they're not created on user action.
 **audioMotion-analyzer** tries to automatically start its *AudioContext* on the first click on the page. However, if you're using an `audio`
 or `video` element with the `controls` property, clicks on those native media controls cannot be detected by JavaScript, so the audio will