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

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

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 +323 -202
package/dist/index.js +311 -244
package/package.json +4 -4
package/src/audioMotion-analyzer.js +307 -240
package/src/index.d.ts +35 -23

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!**
+> **WARNING:** code in **alpha** stage is subject to major, drastic changes! **DO NOT USE THIS VERSION IN PRODUCTION!**
 **audioMotion-analyzer** is a high-resolution real-time audio spectrum analyzer built upon **Web Audio** and **Canvas** JavaScript APIs.
@@ -32,7 +32,7 @@ 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
@@ -80,11 +80,11 @@ const { AudioMotionAnalyzer } = require('audioMotion-analyzer');
 ### In the browser using native ES6 module (ESM) <!-- {docsify-ignore} -->
-Load from Skypack CDN:
+Load from jsDelivr CDN:
 ```html
 <script type="module">
-  import AudioMotionAnalyzer from 'https://cdn.skypack.dev/audiomotion-analyzer@alpha?min';
+  import AudioMotionAnalyzer from 'https://cdn.jsdelivr.net/npm/audiomotion-analyzer@alpha/+esm';
   // your code here
 </script>
 ```
@@ -93,10 +93,10 @@ Or download the [latest version](https://github.com/hvianna/audioMotion-analyzer
 ### In the browser using global variable <!-- {docsify-ignore} -->
-Load from Unpkg CDN:
+Load from jsDelivr CDN:
 ```html
-<script src="https://unpkg.com/audiomotion-analyzer@alpha/dist"></script>
+<script src="https://cdn.jsdelivr.net/npm/audiomotion-analyzer@alpha"></script>
 <script>
   // available as AudioMotionAnalyzer global
 </script>
@@ -141,37 +141,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 +179,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 +224,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 +254,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 +305,14 @@ import {
 	FILTER_C,
 	FILTER_D,
 	FILTER_468,
+	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,
@@ -318,9 +325,9 @@ import {
 	PEAKS_DROP,
 	PEAKS_FADE,
 	PEAKS_OFF,
-	RADIAL_INNER,
+	RADIAL_INWARD,
 	RADIAL_OFF,
-	RADIAL_OUTER,
+	RADIAL_OUTWARD,
 	REASON_CREATE,
 	REASON_FULLSCREENCHANGE,
 	REASON_LORES,
@@ -371,8 +378,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.
@@ -550,7 +555,7 @@ value      | [Constant](#constants) | Description | Scale preview (10Hz - 24kHz
 `"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.
@@ -715,7 +720,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.
@@ -749,7 +754,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.
@@ -804,17 +809,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 +918,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 +934,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 +946,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)*
@@ -991,9 +969,9 @@ Whether to render the spectrum analyzer as a circle with radial bars.
 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 +1070,63 @@ 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)
+### `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 [`setScaleX()`](#setscalex).
+`"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.
-See also [`noteLabels`](#notelabels).
+Several display properties of the scale can be customized via [`setScaleX()`](#setscalex) 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.
 ### `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 [`setScaleY()`](#setscaley) 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 +1191,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.
+[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 `"none"`.
 <img src="img/weigthing-filters-curves.png" class="align-right">
-**Value:** a *string*. The default value is `""`.
+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
-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
+?> Refer to the [**weighting filters viewer tool**](/tools/weighting-filters.html) for filter response tables and an interactive version of the graph seen above.
-?> Weighting filters only affect the visualization, **NOT** the audio output.
-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 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 +1236,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 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.
+If `source` is not a valid object, an [`ERR_INVALID_AUDIO_SOURCE`](#custom-errors) error is thrown.
-See also [`disconnectInput()`](#disconnectinput-node-stoptracks-) and [`connectedSources`](#connectedsources-array-read-only).
+**Return value:** an *AudioNode* object, representing the actual audio node connected.
-### `connectOutput( [node] )`
+See also [`disconnectInput()`](#disconnectinput) and [`connectedSources`](#connectedsources-read-only).
+### `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:**
+```js
+connectOutput()
+connectOutput(node)
+```
+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).
-By default, the analyzer is connected to the speakers upon instantiation, unless you set [`connectSpeakers: false`](#connectspeakers) in the constructor options.
+By default, the analyzer is already connected to the speakers upon instantiation, unless you set [`connectSpeakers: false`](#connectspeakers) in the constructor options.
-See also [`disconnectOutput()`](#disconnectoutput-node-) and [`connectedTo`](#connectedto-array-read-only).
+**Return value:** none (`undefined`).
-?> If called with no argument, analyzer output is connected to the speakers (the *AudioContext* `destination` node).
+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 +1373,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.
@@ -1393,11 +1441,39 @@ Callbacks and [constructor-specific properties](#constructor-specific-options) a
 See also [`setOptions()`](#setoptions).
+### `getScaleX()`
+*Available since v5.0.0*
+Returns the display properties of the X-axis scale.
+**Syntax:**
+```js
+getScaleX()
+```
+**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.
 ### `getTheme()`
 *Available since v5.0.0*
-Returns the name of the theme set for the given channel.
+Returns the name of the active theme, and optionally the state of theme modifiers, for the given channel.
 **Syntax:**
@@ -1462,6 +1538,35 @@ 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)
+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:
+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
+See also [`getTheme()`](#gettheme) and [`setThemeModifiers()`](#setthememodifiers).
 ### `registerTheme()`
 *Available since v5.0.0; formerly `registerGradient()` (since v1.0.0)*
@@ -1486,7 +1591,7 @@ 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
 ---------|--------|-------------
@@ -1619,153 +1724,148 @@ setSensitivity(minDecibels, maxDecibels)
 **Return value:** none (`undefined`).
-### `setTheme()`
+### `setScaleX()`
 *Available since v5.0.0*
-Sets the color theme for one or both analyzer channels.
+Customize the appearance of the X-axis scale and labels.
 **Syntax:**
 ```js
-setTheme(name, channel)
-setTheme(name, modifiers, channel)
-setTheme(themeObject, channel)
+setScaleX()
+setScaleX(options)
 ```
-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 called with no argument, 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.
+If `options` is defined, it should be an object with the structure below (all properties are optional).
-!> 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 | 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`
+`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`
 **Return value:** none (`undefined`).
-See also [`channelLayout`](#channellayout), [`registerTheme()`](#registertheme) and [`spreadGradient`](#spreadgradient).
-### `setThemeModifiers()`
-**Syntax:**
+**Example usage:**
 ```js
-setThemeModifiers()
-setThemeModifiers(modifier, state, channel)
-setThemeModifiers(modifiersObject, channel)
+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
+    ],
+});
 ```
-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)
+See also [`showScaleX`](#showscalex).
-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
-**Return value:** none (`undefined`).
-### `setXAxis()`
+### `setScaleY()`
 *Available since v5.0.0*
-Customize the appearance of the X-axis labels.
+Customize the appearance of the Y-axis scale and labels.
 **Syntax:**
 ```js
-setXAxis()
-setXAxis(options)
+setScaleY()
+setScaleY(options)
 ```
-**If called with no argument, all properties will be reset to their default values.**
+ **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
 -------------------|-----------|-------------|---------
-`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`
+`color`            | *string*  | Color of labels and lines | `"#888"`
+`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`
+`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`
+`subLineColor`     | *string*  | Line color used for subdivisions | `"#555"`
+`subLineDash`      | *array*   | Line style for subdivisions (see `lineDash` above) | `[2,8]`
 **Return value:** none (`undefined`).
 **Example usage:**
 ```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
-    ],
+audioMotion.setScaleY({
+  percentInterval: 10,
+  operation: 'screen',
+  showSubdivisions: false,
 });
 ```
-> **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*.
+See also [`showScaleY`](#showscaley).
-### `setYAxis()`
+### `setTheme()`
 *Available since v5.0.0*
-Customize the appearance of the Y-axis labels.
+Sets the color theme for one or both analyzer channels.
 **Syntax:**
 ```js
-setYAxis()
-setYAxis(options)
+setTheme(name, channel)
+setTheme(name, modifiers, channel)
+setTheme(themeObject, channel)
 ```
- **If called with no argument, all properties will be reset to their default values.**
+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 `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 theme will be applied to both channels.
-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`
+!> 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).
 **Return value:** none (`undefined`).
-**Example usage:**
+See also [`channelLayout`](#channellayout), [`registerTheme()`](#registertheme) and [`spreadGradient`](#spreadgradient).
+### `setThemeModifiers()`
+**Syntax:**
 ```js
-audioMotion.setYAxis({
-  linearInterval: 10,
-  operation: 'screen',
-  showSubdivisions: false,
-});
+setThemeModifiers()
+setThemeModifiers(modifier, state, channel)
+setThemeModifiers(modifiersObject, channel)
 ```
-> **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.
+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)
+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
+**Return value:** none (`undefined`).
+See also [`toggleThemeModifier()`](#togglethememodifier) and [`setTheme()`](#settheme).
 ### `start()`
@@ -1823,6 +1923,27 @@ 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()`
+*Available since v5.0.0*
+Toggles the state of a theme modifier for the given channel.
+**Syntax:**
+```js
+toggleThemeModifier(modifier, channel)
+```
+Parameter  | type     | description
+-----------|----------|-----------------
+`modifier` | *string* | desired modifier
+`channel`  | *number* | *(optional)* desired channel (`0` = left, `1` = right) - **if not specified, toggles modifier on both channels**
+**Return value:** none (`undefined`).
+See also [`setThemeModifiers()`](#setthememodifiers) and [`setTheme()`](#settheme).
 ## Custom Errors
@@ -1865,7 +1986,7 @@ The `import` statement must be inside a `script` which has the `type="module"` p
 ```html
   <script type="module">
-    import AudioMotionAnalyzer from 'https://cdn.skypack.dev/audiomotion-analyzer@alpha?min';
+    import AudioMotionAnalyzer from 'https://cdn.jsdelivr.net/npm/audiomotion-analyzer@alpha/+esm';
     // your code here
   </script>
@@ -1894,7 +2015,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