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

package/README.md

@@ -1,6 +1,6 @@
 ## About
 
-> **WARNING:** code in **alpha** stage is subject to major, drastic changes! **DO NOT USE THIS VERSION 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.
 
@@ -38,11 +38,13 @@ What users are saying:
 + 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>
@@ -305,6 +307,8 @@ import {
 	FILTER_C,
 	FILTER_D,
 	FILTER_468,
+	FILTER_TILT3,
+	FILTER_TILT45,
 	LABELS_X_CUSTOM,
 	LABELS_X_FREQS,
 	LABELS_X_FREQS_CUSTOM,
@@ -320,6 +324,9 @@ import {
 	LEDS_MODERN,
 	LEDS_OFF,
 	LEDS_VINTAGE,
+	MIRROR_LEFT,
+	MIRROR_OFF,
+	MIRROR_RIGHT,
 	MODE_BARS,
 	MODE_GRAPH,
 	PEAKS_DROP,
@@ -351,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
@@ -369,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)
@@ -416,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
@@ -466,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).
@@ -486,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)
@@ -548,7 +555,7 @@ 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)
@@ -655,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).
 
@@ -737,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`
 
@@ -780,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.
 
@@ -794,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
@@ -967,7 +974,7 @@ 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_OUTWARD` | Bars grow towards the edges of the screen
@@ -1070,13 +1077,15 @@ 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
+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
@@ -1095,12 +1104,12 @@ Whether to display scale labels on the X-axis.
 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 [`setScaleX()`](#setscalex).
+`"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.
+`"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 [`setScaleX()`](#setscalex) method.
+Several display properties of the scale can be customized via [`setScaleProps()`](#setscaleprops) method.
 
 ?> 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.
 
@@ -1120,7 +1129,7 @@ Value       | [Constant](#constants) | Description
 
 This option has no effect when [`radial`](#radial) is active or [`alphaBars`](#alphabars) is set to `"full"`.
 
-Several display properties of the scale can be customized via [`setScaleY()`](#setscaley) method.
+Several display properties of the scale can be customized via [`setScaleProps()`](#setscaleprops) method.
 
 See also [`minDecibels`](#mindecibels) and [`maxDecibels`](#maxdecibels).
 
@@ -1418,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*
@@ -1441,56 +1458,46 @@ Callbacks and [constructor-specific properties](#constructor-specific-options) a
 
 See also [`setOptions()`](#setoptions).
 
-### `getScaleX()`
+### `getScaleProps()`
 
 *Available since v5.0.0*
 
-Returns the display properties of the X-axis scale.
+Retrieves the current scale display properties on both axes.
 
 **Syntax:**
 
 ```js
-getScaleX()
+getScaleProps()
 ```
 
-**Return value:** an *object* - see [`setScaleX()`](#setscalex) for object structure.
-
-### `getScaleY()`
-
-*Available since v5.0.0*
-
-Returns the display properties of the Y-axis scale.
-
-**Syntax:**
-
-```js
-getScaleY()
-```
-
-**Return value:** an *object* - see [`setScaleY()`](#setscaley) for object structure.
+**Return value:** an *object* - see [`setScaleProps()`](#setscaleprops) for object structure.
 
 ### `getTheme()`
 
 *Available since v5.0.0*
 
-Returns the name of the active theme, and optionally the state of theme modifiers, 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()`
 
@@ -1508,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)
@@ -1549,23 +1556,15 @@ Returns the state of theme modifiers for the given channel.
 ```js
 getThemeModifiers()
 getThemeModifiers(channel)
-getThemeModifiers(modifier, channel)
 ```
 
 Parameter  | type     | description
 -----------|----------|-----------------
-`modifier` | *string* | *(optional)* desired modifier - if undefined, returns an object with all modifiers
-`channel`  | *number* | *(optional)* channel to set (`0` = left, `1` = right) - if not specified, considers channel 0
-
-**Return value:** a *boolean* representing the state of the selected modifier, when `modifier` is specified;
-otherwise, an *object* with the structure below:
+`channel`  | *number* | Channel index (`0` = left, `1` = right) - **if omitted, considers channel 0**
 
-property     | type      | description
--------------|-----------|---------------
-`horizontal` | *boolean* | If `true`, the color gradient is rendered horizontally, instead of vertically
-`revert`     | *boolean* | If `true`, reverses the order in which theme colors are applied
+**Return value:** an *object* - see [`setThemeModifiers()`](#setthememodifiers) for object structure.
 
-See also [`getTheme()`](#gettheme) and [`setThemeModifiers()`](#setthememodifiers).
+See also [`getTheme()`](#gettheme).
 
 ### `registerTheme()`
 
@@ -1579,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` 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).
@@ -1644,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.
@@ -1672,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()`
@@ -1724,73 +1749,48 @@ setSensitivity(minDecibels, maxDecibels)
 
 **Return value:** none (`undefined`).
 
-### `setScaleX()`
+### `setScaleProps()`
 
 *Available since v5.0.0*
 
-Customize the appearance of the X-axis scale and labels.
+Customize the scale appearance on one or both axes.
 
 **Syntax:**
 
 ```js
-setScaleX()
-setScaleX(options)
+setScaleProps()
+setScaleProps(props)
 ```
 
-**If called with no argument, all properties will be reset to their default values.**
+**If `props` is omitted, ALL properties will be reset to their default values.**
+
+`props` object:
 
-If `options` is defined, it should be an object with the structure below (all properties are optional).
+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.
 
-property           | type      | description | default
+`xAxis` object (all properties are optional):
+
+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. Values between `0.0` and `1.0` (recommended for responsivity) represent a fraction of one tenth of the smallest canvas dimension (width or height). A minimum of 10px is enforced for the computed size. Values greater than `1` are interpreted as fixed pixel sizes. | `0.15`
+`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
+`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`
 
-**Return value:** none (`undefined`).
+`yAxis` object (all properties are optional):
 
-**Example usage:**
-
-```js
-audioMotion.setScaleX({
-    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
-    ],
-});
-```
-
-See also [`showScaleX`](#showscalex).
-
-### `setScaleY()`
-
-*Available since v5.0.0*
-
-Customize the appearance of the Y-axis scale and labels.
-
-**Syntax:**
-
-```js
-setScaleY()
-setScaleY(options)
-```
-
- **If called with no argument, all properties will be reset to their default values.**
-
-If `options` is defined, it should be an object with the structure below (all properties are optional).
-
-property           | type      | description | default
+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. Values between `0.0` and `1.0` (recommended for responsivity) represent a fraction of one tenth of the smallest canvas dimension (width or height). A minimum of 10px is enforced for the computed size. Values greater than `1` are interpreted as fixed pixel sizes. | `0.15`
+`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]`
-`operation`        | *string*  | Compositing operation used to draw labels and lines. See [Reference](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/globalCompositeOperation). **Note: some operations may hinder or prevent the proper visualization of analyzer graphs.** | `"destination-over"`
 `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`
@@ -1802,14 +1802,24 @@ property           | type      | description | default
 **Example usage:**
 
 ```js
-audioMotion.setScaleY({
-  percentInterval: 10,
-  operation: 'screen',
-  showSubdivisions: false,
+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,
+    }
 });
 ```
 
-See also [`showScaleY`](#showscaley).
+See also [`getScaleProps()`](#getscaleprops), [`showScaleX`](#showscalex) and [`showScaleY`](#showscaley).
 
 ### `setTheme()`
 
@@ -1820,52 +1830,71 @@ Sets the color theme for one or both analyzer channels.
 **Syntax:**
 
 ```js
-setTheme(name, channel)
-setTheme(name, modifiers, channel)
-setTheme(themeObject, channel)
+// 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)
 ```
 
-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)
+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`
 
 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.
+When using a single `name` or `themeObject`, if `channel` is not specified, the same settings will be applied to both channels.
 
-!> 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).
+**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`).
 
-See also [`channelLayout`](#channellayout), [`registerTheme()`](#registertheme) and [`spreadGradient`](#spreadgradient).
+See also [`channelLayout`](#channellayout), [`registerTheme()`](#registertheme), [`setThemeModifiers()`](#setthememodifiers) and [`spreadGradient`](#spreadgradient).
 
 ### `setThemeModifiers()`
 
+*Available since v5.0.0*
+
+Sets theme modifiers for one or both analyzer channels.
+
 **Syntax:**
 
 ```js
-setThemeModifiers()
-setThemeModifiers(modifier, state, channel)
-setThemeModifiers(modifiersObject, channel)
+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
 ```
 
-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)
+Parameter   | type     | description
+------------|----------|------------------
+`channel`   | *number* | Channel index to set (`0` = left, `1` = right)
+`modifiers` | *object* | Modifiers object (see below)
 
-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
+**When called without arguments, resets modifiers to defaults on both channels. If only a channel is specified, resets on given channel only.**
+
+`modifiers` object structure:
+
+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
 
 **Return value:** none (`undefined`).
 
-See also [`toggleThemeModifier()`](#togglethememodifier) and [`setTheme()`](#settheme).
+See also [`getThemeModifiers()`](#getthememodifiers) and [`setTheme()`](#settheme).
 
 ### `start()`
 
@@ -1904,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
 
@@ -1923,26 +1952,49 @@ 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.
 
-### `toggleThemeModifier()`
+### `unregisterTheme()`
 
 *Available since v5.0.0*
 
-Toggles the state of a theme modifier for the given channel.
+Unregisters a color theme.
 
 **Syntax:**
 
 ```js
-toggleThemeModifier(modifier, channel)
+unregisterTheme(name)
 ```
 
-Parameter  | type     | description
------------|----------|-----------------
-`modifier` | *string* | desired modifier
-`channel`  | *number* | *(optional)* desired channel (`0` = left, `1` = right) - **if not specified, toggles modifier on both channels**
+Parameter | type     | description
+----------|----------|---------------
+`name`    | *string* | Valid theme name. May include built-in themes. See [`getThemeList()`](#getthemelist).
 
-**Return value:** none (`undefined`).
+**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)
 
-See also [`setThemeModifiers()`](#setthememodifiers) and [`setTheme()`](#settheme).
+**Return value:** a *number*, representing the gain or attenuation (in dB) to be applied to the original amplitude value.
 
 
 ## Custom Errors
@@ -1953,11 +2005,11 @@ See also [`setThemeModifiers()`](#setthememodifiers) and [`setTheme()`](#setthem
 
 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
@@ -1986,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>