audiomotion-analyzer 4.0.0-beta.5 → 4.1.0

package/README.md

@@ -27,19 +27,19 @@ What users are saying:
 
 ## Features
 
-+ High-resolution real-time dual channel audio spectrum analyzer
-+ Logarithmic, linear and perceptual (Bark/Mel) frequency scales, with customizable range
++ Dual-channel high-resolution real-time audio spectrum analyzer
++ 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
-+ A, B, C, D and ITU-R 468 weighting filters
-+ Optional effects: LED bars, luminance bars, mirroring and reflection, radial spectrum
-+ Comes with 3 predefined color gradients - easily add your own!
++ Optional A, B, C, D and ITU-R 468 weighting filters
++ Additional effects: LED bars, luminance bars, mirroring and reflection, radial spectrum
++ Choose from 5 built-in color gradients or easily add your own!
 + Fullscreen support, ready for retina / HiDPI displays
 + Zero-dependency native ES6+ module (ESM), \~25kB minified
 
 ## Online demos
 
-[![demo-animation](img/demo.gif)](https://audiomotion.dev/demo/)
+[![demo-animation](img/demo.webp)](https://audiomotion.dev/demo/)
 
 ?> https://audiomotion.dev/demo/
 
@@ -120,6 +120,7 @@ options = {<br>
 &emsp;&emsp;[barSpace](#barspace-number): **0.1**,<br>
 &emsp;&emsp;[bgAlpha](#bgalpha-number): **0.7**,<br>
 &emsp;&emsp;[channelLayout](#channellayout-string): **'single'**,<br>
+&emsp;&emsp;[colorMode](#colormode-string): **'gradient'**,<br>
 &emsp;&emsp;[connectSpeakers](#connectspeakers-boolean): **true**, // constructor only<br>
 &emsp;&emsp;[fftSize](#fftsize-number): **8192**,<br>
 &emsp;&emsp;[fillAlpha](#fillalpha-number): **1**,<br>
@@ -151,6 +152,7 @@ options = {<br>
 &emsp;&emsp;[reflexBright](#reflexbright-number): **1**,<br>
 &emsp;&emsp;[reflexFit](#reflexfit-boolean): **true**,<br>
 &emsp;&emsp;[reflexRatio](#reflexratio-number): **0**,<br>
+&emsp;&emsp;[roundBars](#roundbars-boolean): **false**,<br>
 &emsp;&emsp;[showBgColor](#showbgcolor-boolean): **true**,<br>
 &emsp;&emsp;[showFPS](#showfps-boolean): **false**,<br>
 &emsp;&emsp;[showPeaks](#showpeaks-boolean): **true**,<br>
@@ -161,6 +163,7 @@ options = {<br>
 &emsp;&emsp;[spinSpeed](#spinspeed-number): **0**,<br>
 &emsp;&emsp;[splitGradient](#splitgradient-boolean): **false**,<br>
 &emsp;&emsp;[start](#start-boolean): **true**,<br>
+&emsp;&emsp;[trueLeds](#trueleds-boolean): **false**,<br>
 &emsp;&emsp;[useCanvas](#usecanvas-boolean): **true**,<br>
 &emsp;&emsp;[volume](#volume-number): **1**,<br>
 &emsp;&emsp;[weightingFilter](#weightingFilter-string): **''**<br>
@@ -247,12 +250,17 @@ Defaults to **false**.
 
 *Available since v4.0.0*
 
-When set to *true* uses ANSI/IEC preferred frequencies to generate the bands for [octave bands modes](#mode-number).
+When set to *true*, ANSI/IEC preferred frequencies are used to generate the bands for **octave bands** modes (see [`mode`](#mode-number)).
 The preferred base-10 scale is used to compute the center and bandedge frequencies, as specified in the [ANSI S1.11-2004 standard](https://archive.org/details/gov.law.ansi.s1.11.2004).
 
-The default is to use the [equal temperament scale](http://hyperphysics.phy-astr.gsu.edu/hbase/Music/et.html), so that in 1/12 octave bands
+When *false*, bands are based on the [equal-tempered scale](http://hyperphysics.phy-astr.gsu.edu/hbase/Music/et.html), so that in 1/12 octave bands
 the center of each band is perfectly tuned to a musical note.
 
+ansiBands | bands standard | octaves' center frequencies
+----------|----------------|----------------------------
+false     | Equal temperament (A-440 Hz) | ![scale-log-equal-temperament](img/scale-log-equal-temperament.png)
+true      | ANSI S1.11-2004 | ![scale-log-ansi](img/scale-log-ansi.png)
+
 Defaults to **false**.
 
 ### `audioCtx` *AudioContext object* *(Read only)*
@@ -286,7 +294,7 @@ See also the [fluid demo](/demo/fluid.html) and the [multi-instance demo](/demo/
 
 *Available since v2.0.0*
 
-Customize the spacing between bars in [bands modes](#mode-number).
+Customize the spacing between bars in frequency bands modes (see [`mode`](#mode-number)).
 
 Use a value between 0 and 1 for spacing proportional to the band width. Values >= 1 will be considered as a literal number of pixels.
 
@@ -323,17 +331,33 @@ Defaults to **0.7**.
 
 Defines the number and layout of analyzer channels.
 
-channelLayout   | description
+channelLayout   | Description
 ----------------|------------
 'single'        | Single channel analyzer, representing the combined output of both left and right channels.
-'dual-vertical' | Dual channel analyzer, with left channel shown at the top and right channel at the bottom.
-'dual-combined' | Left and right channel graphs are shown overlaid. Works best with semi-transparent **Graph** [`mode`](#mode-number) or [`outlineBars`](#outlinebars-boolean).
+'dual-combined' | Dual channel analyzer, with both channel graphs overlaid. Works best with semi-transparent **Graph** [`mode`](#mode-number) or [`outlineBars`](#outlinebars-boolean).
+'dual-vertical' | Left channel shown at the top half of the canvas and right channel at the bottom.
 
 !> When a *dual* layout is selected, any mono (single channel) audio source connected to the analyzer will output sound only from the left speaker,
 unless a stereo source is simultaneously connected to the analyzer, which will force the mono input to be upmixed to stereo.
 
 See also [`gradientLeft`](#gradientleft-string), [`gradientRight`](#gradientright-string) and [`splitGradient`](#splitgradient-boolean).
 
+### `colorMode` *string*
+
+*Available since v4.1.0*
+
+Selects the desired mode for coloring the analyzer bars. This property has no effect in **Graph** [`mode`](#mode-number).
+
+colorMode   | Description | Preview ('prism' gradient)
+------------|-------------|----------------------------
+'gradient'  | Analyzer bars are painted with the currently selected [`gradient`](#gradient-string). This is the default behavior. | ![prism](img/gradient-prism.png)
+'bar-index' | Each analyzer bar is painted with a **single color** from the selected gradient's *colorStops*, starting with the first color applied to the first bar, and so on, cycling through the available colorStops. | ![prism-bar-index](img/gradient-prism-bar-index.png)
+'bar-level' | Colors from the selected gradient are used to paint each bar, according to its current level (amplitude). | ![prism-bar-level](img/gradient-prism-bar-level.png)
+
+See also [`registerGradient()`](#registergradient-name-options-).
+
+Defaults to **'gradient'**.
+
 ### `connectedSources` *array* *(Read only)*
 
 *Available since v3.0.0*
@@ -363,13 +387,13 @@ Defaults to **8192**.
 
 *Available since v2.0.0*
 
-Opacity of the area fill in [Graph mode](#mode-number), or inner fill of bars in [bands modes](#mode-number) when [`outlineBars`](#outlinebars-boolean) is *true*.
+Opacity of the area fill in [Graph mode](#mode-number), or inner fill of bars in [frequency bands modes](#mode-number) when [`outlineBars`](#outlinebars-boolean) is *true*.
 
 It must be a number between 0 (completely transparent) and 1 (completely opaque).
 
 Please note that the line stroke (when [`lineWidth`](#linewidth-number) > 0) is always drawn at full opacity, regardless of the `fillAlpha` value.
 
-Also, for [bands modes](#mode-number), [`alphaBars`](#alphabars-boolean) set to *true* takes precedence over `fillAlpha`.
+Also, for [frequency bands modes](#mode-number), [`alphaBars`](#alphabars-boolean) set to *true* takes precedence over `fillAlpha`.
 
 Defaults to **1**.
 
@@ -385,16 +409,16 @@ Current frame rate.
 
 Scale used to represent frequencies in the horizontal axis.
 
-frequencyScale | description
----------------|------------
-'bark' | [Bark scale](https://en.wikipedia.org/wiki/Bark_scale)
-'linear' | Linear scale
-'log' | Logarithmic scale
-'mel' | [Mel scale](https://en.wikipedia.org/wiki/Mel_scale)
+frequencyScale | description | scale preview (10Hz - 24kHz range)
+---------------|-------------|-----------------------------------
+'bark' | Bark scale | ![scale-bark](img/scale-bark.png)
+'linear' | Linear scale | ![scale-linear](img/scale-linear.png)
+'log' | Logarithmic scale | ![scale-log-ansi](img/scale-log-ansi.png)
+'mel' | Mel scale | ![scale-mel](img/scale-mel.png)
 
-Logarithmic scale is required to visualize proper [octave bands](#mode-number) and it's also recommended when using [`noteLabels`](#notelabels-boolean).
+Logarithmic scale allows visualization of proper **octave bands** (see [`mode`](#mode-number)) and it's also recommended when using [`noteLabels`](#notelabels-boolean).
 
-*Bark* and *Mel* are perceptual pitch scales which provide better visualization of midrange and high frequencies, especially in the [discrete frequencies mode](#mode-number).
+[*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.
 
 Defaults to **'log'**.
 
@@ -419,7 +443,7 @@ It must be a built-in or registered gradient name (see [`registerGradient()`](#r
 
 `gradient` sets the gradient for both analyzer channels, but its read value represents only the gradient on the left (or single) channel.
 
-When using a dual [`channelLayout`](#channellayout-string), use [`gradientLeft`](#gradientleft-string) and [`gradientRight`](#gradientright-string) if you want to individually set/read the gradient for each channel.
+When using a dual [`channelLayout`](#channellayout-string), use [`gradientLeft`](#gradientleft-string) and [`gradientRight`](#gradientright-string) to set/read the gradient on each channel individually.
 
 Built-in gradients are shown below:
 
@@ -466,7 +490,7 @@ You can set both values at once using the [`setCanvasSize()`](#setcanvassize-wid
 *Available since v3.6.0*
 
 ***true*** when alpha bars are effectively being displayed, i.e., [`alphaBars`](#alphabars-boolean) is set to *true* and [`mode`](#mode-number) is set to discrete frequencies
-or one of the bands modes, in which case [`lumiBars`](#lumibars-boolean) must be set to *false* or [`radial`](#radial-boolean) must be set to *true*.
+or one of the frequency bands modes, in which case [`lumiBars`](#lumibars-boolean) must be set to *false* or [`radial`](#radial-boolean) must be set to *true*.
 
 ### `isBandsMode` *boolean* *(Read only)*
 
@@ -513,11 +537,18 @@ See [`toggleAnalyzer()`](#toggleanalyzer-boolean-).
 ***true*** when outlined bars are effectively being displayed, i.e., [`isBandsMode`](#isbandsmode-boolean-read-only) is *true*, [`outlineBars`](#outlinebars-boolean) is set to *true*
 and both [`ledBars`](#ledbars-boolean) and [`lumiBars`](#lumibars-boolean) are set to *false*, or [`radial`](#radial-boolean) is set to *true*.
 
+### `isRoundBars` *boolean* *(Read only)*
+
+*Available since v4.1.0*
+
+***true*** when round bars are effectively being displayed, i.e., [`isBandsMode`](#isbandsmode-boolean-read-only) is *true*, [`roundBars`](#roundbars-boolean) is set to *true*
+and [`ledBars`](#ledbars-boolean) and [`lumiBars`](#lumibars-boolean) are both set to *false*.
+
 ### `ledBars` *boolean*
 
 *Available since v3.6.0* (formerly `showLeds`)
 
-*true* to activate the vintage LED bars effect for [bands modes](#mode-number).
+*true* to activate the vintage LED bars effect for frequency bands modes (see [`mode`](#mode-number)).
 
 This effect can be customized via [`setLedParams()`](#setledparams-params-) method.
 
@@ -551,7 +582,7 @@ Defaults to **1**.
 
 *Available since v2.0.0*
 
-Line width for [Graph mode](#mode-number), or outline stroke in [bands modes](#mode-number) when [`outlineBars`](#outlinebars-boolean) is *true*.
+Line width for [Graph mode](#mode-number), or outline stroke in [frequency bands modes](#mode-number) when [`outlineBars`](#outlinebars-boolean) is *true*.
 
 For the line to be distinguishable, set also [`fillAlpha`](#fillalpha-number) < 1.
 
@@ -578,7 +609,7 @@ This will prevent the canvas size from changing, when switching the low resoluti
 
 *Available since v1.1.0*
 
-This is only effective for [bands modes](#mode-number).
+This is only effective for frequency bands modes (see [`mode`](#mode-number)).
 
 When set to *true* all analyzer bars will be displayed at full height with varying luminance (opacity, actually) instead.
 
@@ -635,22 +666,24 @@ Visualization mode.
 
 mode | description | notes
 ----:|:-----------:|------
-0 | Discrete frequencies |
-1 | 1/24th octave bands or 240 bands |
-2 | 1/12th octave bands or 120 bands |
-3 | 1/8th octave bands or 80 bands |
-4 | 1/6th octave bands or 60 bands |
-5 | 1/4th octave bands or 40 bands |
-6 | 1/3rd octave bands or 30 bands |
-7 | Half octave bands or 20 bands |
-8 | Full octave bands or 10 bands |
+0 | Discrete frequencies | *default*
+1 | 1/24th octave bands or 240 bands | *use 'log' `frequencyScale` for octave bands*
+2 | 1/12th octave bands or 120 bands | *use 'log' `frequencyScale` for octave bands*
+3 | 1/8th octave bands or 80 bands | *use 'log' `frequencyScale` for octave bands*
+4 | 1/6th octave bands or 60 bands | *use 'log' `frequencyScale` for octave bands*
+5 | 1/4th octave bands or 40 bands | *use 'log' `frequencyScale` for octave bands*
+6 | 1/3rd octave bands or 30 bands | *use 'log' `frequencyScale` for octave bands*
+7 | Half octave bands or 20 bands | *use 'log' `frequencyScale` for octave bands*
+8 | Full octave bands or 10 bands | *use 'log' `frequencyScale` for octave bands*
 9 | *(not valid)* | *reserved*
 10 | Graph | *added in v1.1.0*
 
 + **Mode 0** provides the highest resolution, allowing you to visualize individual frequencies as provided by the [FFT](https://en.wikipedia.org/wiki/Fast_Fourier_transform) computation;
-+ **Modes 1 - 8** divide the frequency spectrum in bands; when using the default **logarithmic** [frequency scale](#frequencyscale-string), each band represents the *n*th part of an octave (see also [`ansiBands`](#ansibands-boolean)); otherwise, a fixed number of bands is used for each mode;
++ **Modes 1 - 8** divide the frequency spectrum in bands; when using the default **logarithmic** [`frequencyScale`](#frequencyscale-string), each band represents the *n*th part of an octave; otherwise, a fixed number of bands is used for each mode;
 + **Mode 10** uses the discrete FFT data points to draw a continuous line and/or a filled area graph (see [`fillAlpha`](#fillalpha-number) and [`lineWidth`](#linewidth-number) properties).
 
+See also [`ansiBands`](#ansibands-boolean).
+
 Defaults to **0**.
 
 ### `noteLabels` *boolean*
@@ -659,7 +692,8 @@ Defaults to **0**.
 
 When set to *true* displays musical note labels instead of frequency values, in the X axis (when [`showScaleX`](#showscalex-boolean) is also set to *true*).
 
-For best visualization in [octave bands modes](#mode-number), make sure [`frequencyScale`](#frequencyscale-string) is set to *'log'* and [`ansiBands`](#ansibands-boolean) is set to *false*, so all bands will be perfectly aligned with notes frequencies.
+For best visualization in [octave bands modes](#mode-number), make sure [`frequencyScale`](#frequencyscale-string) is set to *'log'*
+and [`ansiBands`](#ansibands-boolean) is set to *false*, so bands are tuned to the equal temperament musical scale.
 
 Defaults to **false**.
 
@@ -700,8 +734,7 @@ You can refer to this value to adjust any additional drawings done in the canvas
 
 When *true*, the spectrum analyzer is rendered in a circular shape, with radial frequency bars spreading from its center.
 
-On radial spectrum, [`ledBars`](#ledbars-boolean) and [`lumiBars`](#lumibars-boolean) effects are disabled, and
-[`showPeaks`](#showpeaks-boolean) has no effect for [**Graph** mode](#mode-number).
+In radial view, [`ledBars`](#ledbars-boolean) and [`lumiBars`](#lumibars-boolean) effects are disabled, and [`showPeaks`](#showpeaks-boolean) has no effect when in **Graph** [`mode`](#mode-number).
 
 When [`channelLayout`](#channellayout-string) is set to *'dual-vertical'*, a larger diameter is used and the right channel bars are rendered towards the center of the analyzer.
 
@@ -754,6 +787,21 @@ This has no effect when [`lumiBars`](#lumibars-boolean) is *true*.
 
 Defaults to **0** (no reflection).
 
+### `roundBars` *boolean*
+
+*Available since v4.1.0*
+
+When *true* and [`mode`](#mode-number) is set to one of the **bands** modes, analyzer bars are rendered with rounded corners at the top.
+
+In [`radial`](#radial-boolean) view this makes the top and bottom of bars to follow the curvatures of the outer and inner circles, respectivelly, although the effect
+can be barely noticeable with a band count greater than 20 (half-octave bands).
+
+This has no effect when [`ledBars`](#ledbars-boolean) or [`lumiBars`](#lumibars-boolean) are set to *true*.
+
+See also [`isRoundBars`](#isroundbars-boolean-read-only).
+
+Defaults to **false**.
+
 ### `showBgColor` *boolean*
 
 Determines whether the canvas background should be painted.
@@ -828,9 +876,9 @@ Defaults to **0**.
 
 When set to *true* and [`channelLayout`](#channellayout-string) is **_dual-vertical_**, the gradient will be split between channels.
 
-When *false*, both channels will use the full gradient.
+When *false*, both channels will use the full gradient. The effect is illustrated below, using the *'classic'* gradient.
 
-| gradient: *'classic'* - splitGradient: *false* | gradient: *'classic'* - splitGradient: *true* |
+| splitGradient: *false* | splitGradient: *true* |
 |:--:|:--:|
 | ![split-off](img/splitGradient_off.png) | ![split-on](img/splitGradient_on.png) |
 
@@ -842,6 +890,24 @@ Defaults to **false**.
 
 **This property will be removed in version 5** - Use [`channelLayout`](#channellayout-string) instead.
 
+### `trueLeds` *boolean*
+
+*Available since v4.1.0*
+
+When set to *true*, LEDs are painted with individual colors from the current gradient, instead of using the gradient itself.
+
+The effect is illustrated below, using the *'classic'* gradient.
+
+| trueLeds: *false* | trueLeds: *true* |
+|:--:|:--:|
+| ![split-off](img/trueleds_off.png) | ![split-on](img/trueleds_on.png) |
+
+The threshold for each color can be adjusted via the `level` property when registering a gradient. See [`registerGradient()`](#registergradient-name-options-).
+
+This option is only effective for frequency bands [modes](#mode-number), when [`ledBars`](#ledbars-boolean) is *true* and [`colorMode`](#colormode-string) is set to *'gradient'*.
+
+Defaults to **false**.
+
 ### `useCanvas` *boolean*
 
 *Available since v3.5.0*
@@ -911,11 +977,15 @@ Since this is a static property, you should always access it as `AudioMotionAnal
 
 ### `onCanvasDraw` *function*
 
-If defined, this function will be called after rendering each frame.
+If defined, this function will be called after **audioMotion-analyzer** finishes rendering each animation frame.
 
-The audioMotion object will be passed as an argument to the callback function.
+The callback function is passed two arguments: an *AudioMotionAnalyzer* object, and an object with the following properties:
+- `timestamp`, a [*DOMHighResTimeStamp*](https://developer.mozilla.org/en-US/docs/Web/API/DOMHighResTimeStamp)
+which indicates the elapsed time in milliseconds since the analyzer started running;
+- `canvasGradients`, an array of [*CanvasGradient*](https://developer.mozilla.org/en-US/docs/Web/API/CanvasGradient])
+objects currently in use on the left (or single) and right analyzer channels.
 
-Canvas properties `fillStyle` and `strokeStyle` will be set to the current gradient when the function is called.
+The canvas properties `fillStyle` and `strokeStyle` will be set to the left/single channel gradient before the function is called.
 
 Usage example:
 
@@ -928,16 +998,26 @@ const audioMotion = new AudioMotionAnalyzer(
     }
 );
 
-function drawCallback( instance ) {
-	const ctx      = instance.canvasCtx,
-    	  baseSize = ( instance.isFullscreen ? 40 : 20 ) * instance.pixelRatio;
-
-    // use the 'energy' value to increase the font size and make the logo pulse to the beat
+function drawCallback( instance, info ) {
+    const baseSize  = ( instance.isFullscreen ? 40 : 20 ) * instance.pixelRatio,
+          canvas    = instance.canvas,
+          centerX   = canvas.width / 2,
+          centerY   = canvas.height / 2,
+          ctx       = instance.canvasCtx,
+          maxHeight = centerY / 2,
+          maxWidth  = centerX - baseSize * 5,
+          time      = info.timestamp / 1e4;
+
+    // the energy value is used here to increase the font size and make the logo pulsate to the beat
     ctx.font = `${ baseSize + instance.getEnergy() * 25 * instance.pixelRatio }px Orbitron, sans-serif`;
 
-    ctx.fillStyle = '#fff8';
+    // use the right-channel gradient to fill text
+    ctx.fillStyle = info.canvasGradients[1];
     ctx.textAlign = 'center';
-    ctx.fillText( 'audioMotion', instance.canvas.width - baseSize * 8, baseSize * 2 );
+    ctx.globalCompositeOperation = 'lighter';
+
+    // the timestamp can be used to create effects and animations based on the elapsed time
+    ctx.fillText( 'audioMotion', centerX + maxWidth * Math.cos( time % Math.PI * 2 ), centerY + maxHeight * Math.sin( time % Math.PI * 16 ) );
 }
 ```
 
@@ -947,7 +1027,7 @@ For more examples, see the fluid demo [source code](https://github.com/hvianna/a
 
 If defined, this function will be called whenever the canvas is resized.
 
-Two arguments are passed: a string with the reason why the function was called (see below) and the audioMotion object.
+The callback function is passed two arguments: a string which indicates the reason that triggered the call (see below) and the *AudioMotionAnalyzer* object.
 
 Reason | Description
 -------|------------
@@ -1084,29 +1164,34 @@ Use this method inside your callback function to create additional visual effect
 
 Registers a custom color gradient.
 
-`name` must be a non-empty string that will be used to select this gradient, via the [`gradient`](#gradient-string) property.
+`name` must be a non-empty string that will be used to select this gradient, via the [`gradient`](#gradient-string) property. Names are case sensitive.
 
 `options` must be an object as shown below:
 
 ```js
-const options = {
+audioMotion.registerGradient( 'myGradient', {
     bgColor: '#011a35', // background color (optional) - defaults to '#111'
     dir: 'h',           // add this property to create a horizontal gradient (optional)
     colorStops: [       // list your gradient colors in this array (at least one color is required)
-        'red',                      // colors may be defined in any valid CSS format
-        { pos: .6, color: '#ff0' }, // use an object to adjust the offset (0 to 1) of a colorStop
-        'hsl( 120, 100%, 50% )'
+        'hsl( 0, 100%, 50% )',        // colors can be defined in any valid CSS format
+        { color: 'yellow', pos: .6 }, // in an object, use `pos` to adjust the offset (0 to 1) of a colorStop
+        { color: '#0f0', level: .5 }  // use `level` to set the max bar amplitude (0 to 1) to use this color
     ]
-}
-
-audioMotion.registerGradient( 'myGradient', options );
+});
 ```
 
-Check the [built-in **_'rainbow'_** gradient](#gradient-string) for an example of horizontal gradient.
+The `dir` property has no effect on [`radial`](#radial-boolean) spectrum or when [`trueLeds`](#trueleds-boolean) is in effect.
 
-**Note:** the horizontal flag (`dir: 'h'`) has no effect on [`radial`](#radial-boolean) spectrum, because in that mode all gradients are rendered in radial direction.
+Each element of `colorStops` may be either a string (color only), or an object with at least a `color` property and optional `pos` and `level` properties.
+- `pos` defines the relative position of a color in the gradient, when [`colorMode`](#colormode-string) is set to **'gradient'**. It must be a number between `0` and `1`, where `0` represents the top of the screen and `1` the bottom
+(or left and right sides, for horizontal gradients);
+- `level` defines the level threshold of a color, when [`colorMode`](#colormode-string) is set to **'bar-level'** or [`trueLeds`](#trueleds-boolean) is active.
+The color will be applied to bars (or LED elements) with amplitude **less than or equal to** `level`. It must be a number between `0` and `1`, where `1` is the maximum
+amplitude (top of screen);
+- If `pos` or `level` are not explicitly defined, colors will be evenly distributed across the gradient or amplitude range;
+- Defining `level: 0` for a colorStop will effectively prevent that color from being used for *'bar-level'* colorMode and *trueLeds* effect.
 
-?> Any gradient, including the built-in ones, may be modified by (re-)registering the same gradient name (names are case sensitive).
+?> Any gradient, including the built-in ones, may be modified at any time by (re-)registering the same gradient name.
 
 ### `setCanvasSize( width, height )`
 
@@ -1259,11 +1344,11 @@ myAudio.crossOrigin = 'anonymous';
 Browser autoplay policy dictates that audio output can only be initiated by a user gesture, and this is enforced by WebAudio API
 by creating [*AudioContext*](#audioctx-audiocontext-object-read-only) objects in *suspended* mode.
 
-**audioMotion-analyzer** tries to automatically start its audio context on the first click on the page.
+**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 only be enabled if/when the user clicks somewhere else.
 
-Two possible solutions: **1)** make **sure** your users have to click somewhere else before using the media controls,
+Two possible solutions are: **1)** ensure your users have to click somewhere else before using the media controls,
 like a "power on" button, or simply clicking to select a song from a list will do; or **2)** don't use the native
 controls at all, and create your own custom play and stop buttons. A very simple example:
 
@@ -1281,6 +1366,9 @@ document.getElementById('play').addEventListener( 'click', () => myAudio.play()
 document.getElementById('stop').addEventListener( 'click', () => myAudio.pause() );
 ```
 
+You can also prevent the _"The AudioContext was not allowed to start"_ warning message from appearing in the browser console, by instantiating
+your **audioMotion-analyzer** object within a function triggered by a user click. See the [minimal demo](/demo/minimal.html) code for an example.
+
 
 ## References and acknowledgments
 
@@ -1293,7 +1381,9 @@ document.getElementById('stop').addEventListener( 'click', () => myAudio.pause()
 * [Equations for equal-tempered scale frequencies](http://pages.mtu.edu/~suits/NoteFreqCalcs.html)
 * [Making Audio Reactive Visuals](https://www.airtightinteractive.com/2013/10/making-audio-reactive-visuals/)
 * The font used in audioMotion's logo is [Orbitron](https://fonts.google.com/specimen/Orbitron) by Matt McInerney
-* This documentation website is powered by [GitHub Pages](https://pages.github.com/), [docsify](https://docsify.js.org/) and [docsify-themeable](https://jhildenbiddle.github.io/docsify-themeable).
+* The _prism_ and _rainbow_ gradients use the [12-bit rainbow palette](https://iamkate.com/data/12-bit-rainbow/) by Kate Morley
+* The cover page animation was recorded with [ScreenToGif](https://github.com/NickeManarin/ScreenToGif) by Nicke Manarin
+* This documentation website is powered by [GitHub Pages](https://pages.github.com/), [docsify](https://docsify.js.org/) and [docsify-themeable](https://jhildenbiddle.github.io/docsify-themeable)
 
 
 ## Changelog
@@ -1303,18 +1393,20 @@ See [Changelog.md](Changelog.md)
 
 ## Contributing
 
-If you want to send feedback, ask a question, or need help with something, please use the [**Discussions**](https://github.com/hvianna/audioMotion-analyzer/discussions) area on GitHub.
+I kindly request that you only [open an issue](https://github.com/hvianna/audioMotion-analyzer/issues) for submitting a **bug report**.
 
-I would love to see your cool projects using **audioMotion-analyzer** -- post them in the *Show and tell* section of [Discussions](https://github.com/hvianna/audioMotion-analyzer/discussions)!
+If you need help integrating *audioMotion-analyzer* with your project, have ideas for **new features** or any other questions or feedback,
+please use the [**Discussions**](https://github.com/hvianna/audioMotion-analyzer/discussions) section on GitHub.
 
-For **bug reports** and **feature requests**, feel free to [open an issue](https://github.com/hvianna/audioMotion-analyzer/issues).
+Additionally, I would love it if you could showcase your project using *audioMotion-analyzer* in [**Show and Tell**](https://github.com/hvianna/audioMotion-analyzer/discussions/categories/show-and-tell),
+and share your custom gradients with the community in [**Gradients**](https://github.com/hvianna/audioMotion-analyzer/discussions/categories/gradients)!
 
-If you want to submit a **Pull Request**, please branch it off the project's `develop` branch.
+When submitting a **Pull Request**, please branch it off the project's `develop` branch.
 
 And if you're feeling generous, maybe:
 
 * [Buy me a coffee](https://ko-fi.com/Q5Q6157GZ) on Ko-fi ☕😁
-* Gift me something from my [Bandcamp wishlist](https://bandcamp.com/henriquevianna/wishlist) 🎁🥰
+* Gift me something from my [Bandcamp wishlist](https://bandcamp.com/henriquevianna/wishlist) 🎁🎶🥰
 * Tip me via [Brave Rewards](https://brave.com/brave-rewards/) using Brave browser 🤓
 
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "audiomotion-analyzer",
   "description": "High-resolution real-time graphic audio spectrum analyzer JavaScript module with no dependencies.",
-  "version": "4.0.0-beta.5",
+  "version": "4.1.0",
   "main": "./src/audioMotion-analyzer.js",
   "module": "./src/audioMotion-analyzer.js",
   "types": "./src/index.d.ts",