audiomotion-analyzer 4.0.0-beta.4 → 4.0.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/
 
@@ -161,7 +161,6 @@ 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;[stereo](#stereo-deprecated-boolean): **false**, // DEPRECATED - use channelLayout instead<br>
 &emsp;&emsp;[useCanvas](#usecanvas-boolean): **true**,<br>
 &emsp;&emsp;[volume](#volume-number): **1**,<br>
 &emsp;&emsp;[weightingFilter](#weightingFilter-string): **''**<br>
@@ -236,7 +235,7 @@ Defaults to **true**, so the analyzer will start running right after initializat
 
 When set to *true* each bar's amplitude affects its opacity, i.e., higher bars are rendered more opaque while shorter bars are more transparent.
 
-This is similar to the [`lumiBars`](#lumibars-boolean) effect, but bars' amplitudes are preserved and it also works on **Discrete** [mode](#mode-number) and [radial](#radial-boolean) visualization.
+This is similar to the [`lumiBars`](#lumibars-boolean) effect, but bars' amplitudes are preserved and it also works on **Discrete** [mode](#mode-number) and [radial](#radial-boolean) spectrum.
 
 For effect priority when combined with other settings, see [`isAlphaBars`](#isalphabars-boolean-read-only).
 
@@ -248,12 +247,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)*
@@ -324,11 +328,11 @@ Defaults to **0.7**.
 
 Defines the number and layout of analyzer channels.
 
-channelLayout  | description
--------------- |------------
-'single'       | Single channel analyzer, representing the combined output of both left and right channels.
-'dualVertical' | Dual channel analyzer, with left channel shown at the top and right channel at the bottom.
-'dualCombined' | Left and right channel graphs are shown overlaid. Works best with semi-transparent **Graph** [`mode`](#mode-number) or [`outlineBars`](#outlinebars-boolean).
+channelLayout   | description
+----------------|------------
+'single'        | Single channel analyzer, representing the combined output of both left and right channels.
+'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.
@@ -386,16 +390,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 (20Hz - 22kHz range)
+---------------|-------------|-----------------------------------
+'bark' | [Bark scale](https://en.wikipedia.org/wiki/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](https://en.wikipedia.org/wiki/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* and *Mel* are perceptual pitch scales, which provide better visualization of mid-range to high frequencies.
 
 Defaults to **'log'**.
 
@@ -416,9 +420,23 @@ Canvas dimensions used during fullscreen mode. These take the current pixel rati
 
 Name of the color gradient used for analyzer graphs.
 
-It must be a built-in or [registered](#registergradient-name-options-) gradient name. Built-in gradients are *'classic'*, *'prism'* and *'rainbow'*.
+It must be a built-in or registered gradient name (see [`registerGradient()`](#registergradient-name-options-)).
+
+`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) to set/read the gradient on each channel individually.
+
+Built-in gradients are shown below:
 
-See also [`gradientLeft`](#gradientleft-string) and [`gradientRight`](#gradientright-string).
+gradient    | preview
+------------|---------
+'classic'   | ![classic](img/gradient-classic.png)
+'orangered' | ![orangered](img/gradient-orangered.png)
+'prism'     | ![prism](img/gradient-prism.png)
+'rainbow'   | ![rainbow](img/gradient-rainbow.png)
+'steelblue' | ![steelblue](img/gradient-steelblue.png)
+
+See also [`splitGradient`](#splitgradient-boolean).
 
 Defaults to **'classic'**.
 
@@ -427,11 +445,13 @@ Defaults to **'classic'**.
 
 *Available since v4.0.0*
 
-When using a dual [`channelLayout`](#channellayout-string), different gradients can be selected for the left and right channels.
+Select gradients for the left and right analyzer channels independently, for use with a dual [`channelLayout`](#channellayout-string).
+
+**_Single_** channel layout will use the gradient selected by `gradientLeft`.
 
-When [`channelLayout`](#channellayout-string) is set to *'single'*, the gradient selected by `gradientLeft` is used.
+For **_dual-combined_** channel layout or [`radial`](#radial-boolean) spectrum, only the background color defined by `gradientLeft` will be applied when [`showBgColor`](#showbgcolor-boolean) is *true*.
 
-The [`gradient`](#gradient-string) property can be used as a shorthand to set the same gradient for both channels. Its read value returns only the left (or single) channel gradient though.
+See also [`gradient`](#gradient-string) and [`splitGradient`](#splitgradient-boolean).
 
 ### `height` *number*
 ### `width` *number*
@@ -567,7 +587,7 @@ This is only effective for [bands modes](#mode-number).
 
 When set to *true* all analyzer bars will be displayed at full height with varying luminance (opacity, actually) instead.
 
-`lumiBars` takes precedence over [`alphaBars`](#alphabars-boolean) and [`outlineBars`](#outlinebars-boolean), except in [`radial`](#radial-boolean) visualization.
+`lumiBars` takes precedence over [`alphaBars`](#alphabars-boolean) and [`outlineBars`](#outlinebars-boolean), except on [`radial`](#radial-boolean) spectrum.
 
 For effect priority when combined with other settings, see [`isLumiBars`](#islumibars-boolean-read-only).
 
@@ -620,22 +640,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*
@@ -685,10 +707,10 @@ 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.
 
-In radial visualization, [`ledBars`](#ledbars-boolean) and [`lumiBars`](#lumibars-boolean) effects are disabled, and
+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).
 
-When [`channelLayout`](#channellayout-string) is set to *'dualVertical'*, a larger diameter is used and the right channel bars are rendered towards the center of the analyzer.
+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.
 
 See also [`spinSpeed`](#spinspeed-number).
 
@@ -749,6 +771,8 @@ Opacity can be adjusted via [`bgAlpha`](#bgalpha-number) property, when [`overla
 If ***false***, the canvas background will be painted black when [`overlay`](#overlay-boolean) is ***false***,
 or transparent when [`overlay`](#overlay-boolean) is ***true***.
 
+See also [`registerGradient()`](#registergradient-name-options-).
+
 Defaults to **true**.
 
 ?> Please note that when [`overlay`](#overlay-boolean) is ***false*** and [`ledBars`](#ledbars-boolean) is ***true***, the background color will always be black,
@@ -809,13 +833,15 @@ Defaults to **0**.
 
 *Available since v3.0.0*
 
-When *true*, the gradient will be split between both channels, so each channel will have different colors. If *false*, both channels will use the full gradient.
+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.
 
-| splitGradient: *true* | splitGradient: *false* |
+| gradient: *'classic'* - splitGradient: *false* | gradient: *'classic'* - splitGradient: *true* |
 |:--:|:--:|
-| ![split-on](img/splitGradient_on.png) | ![split-off](img/splitGradient_off.png) |
+| ![split-off](img/splitGradient_off.png) | ![split-on](img/splitGradient_on.png) |
 
-This option has no effect on horizontal gradients (except in [`radial`](#radial-boolean) visualization - see note in [`registerGradient()`](#registergradient-name-options-)), or when [`channelLayout`](#channellayout-string) is set to *'single'* or *'dualCombined'*.
+This option has no effect on horizontal gradients, except on [`radial`](#radial-boolean) spectrum - see note in [`registerGradient()`](#registergradient-name-options-).
 
 Defaults to **false**.
 
@@ -892,11 +918,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:
 
@@ -909,16 +939,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 ) );
 }
 ```
 
@@ -928,7 +968,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
 -------|------------
@@ -1083,9 +1123,11 @@ const options = {
 audioMotion.registerGradient( 'myGradient', options );
 ```
 
-?> During [`radial`](#radial-boolean) visualization all gradients are rendered in radial direction, so the horizontal flag (`dir: 'h'`) has no effect.
+Check the [built-in **_'rainbow'_** gradient](#gradient-string) for an example of horizontal gradient.
+
+**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.
 
-Additional information about [gradient color-stops](https://developer.mozilla.org/en-US/docs/Web/API/CanvasGradient/addColorStop).
+?> Any gradient, including the built-in ones, may be modified by (re-)registering the same gradient name (names are case sensitive).
 
 ### `setCanvasSize( width, height )`
 
@@ -1190,7 +1232,7 @@ which is [currently not supported in some browsers](https://caniuse.com/#feat=md
 
 ### alphaBars and fillAlpha won't work with Radial on Firefox <!-- {docsify-ignore} -->
 
-On Firefox, [`alphaBars`](#alphaBars-boolean) and [`fillAlpha`](#fillalpha-number) won't work with [`radial`](#radial-boolean) visualization when using hardware acceleration, due to [this bug](https://bugzilla.mozilla.org/show_bug.cgi?id=1164912).
+On Firefox, [`alphaBars`](#alphaBars-boolean) and [`fillAlpha`](#fillalpha-number) won't work with [`radial`](#radial-boolean) spectrum when using hardware acceleration, due to [this bug](https://bugzilla.mozilla.org/show_bug.cgi?id=1164912).
 
 ### Visualization of live streams won't work on Safari {docsify-ignore}
 
@@ -1238,11 +1280,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:
 
@@ -1260,6 +1302,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
 
@@ -1272,7 +1317,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
@@ -1282,18 +1329,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.4",
+  "version": "4.0.0",
   "main": "./src/audioMotion-analyzer.js",
   "module": "./src/audioMotion-analyzer.js",
   "types": "./src/index.d.ts",

package/src/audioMotion-analyzer.js

@@ -2,12 +2,12 @@
  * audioMotion-analyzer
  * High-resolution real-time graphic audio spectrum analyzer JS module
  *
- * @version 4.0.0-beta.4
+ * @version 4.0.0
  * @author  Henrique Avila Vianna <hvianna@gmail.com> <https://henriquevianna.com>
  * @license AGPL-3.0-or-later
  */
 
-const VERSION = '4.0.0-beta.4';
+const VERSION = '4.0.0';
 
 // internal constants
 const TAU     = 2 * Math.PI,
@@ -16,9 +16,9 @@ const TAU     = 2 * Math.PI,
 	  C_1     = 8.17579892;  // frequency for C -1
 
 const CANVAS_BACKGROUND_COLOR  = '#000',
-	  CHANNEL_COMBINED         = 'dualCombined',
+	  CHANNEL_COMBINED         = 'dual-combined',
 	  CHANNEL_SINGLE           = 'single',
-	  CHANNEL_VERTICAL         = 'dualVertical',
+	  CHANNEL_VERTICAL         = 'dual-vertical',
  	  GRADIENT_DEFAULT_BGCOLOR = '#111',
  	  FILTER_NONE              = '',
  	  FILTER_A                 = 'A',
@@ -28,9 +28,6 @@ const CANVAS_BACKGROUND_COLOR  = '#000',
  	  FILTER_468               = '468',
 	  FONT_FAMILY              = 'sans-serif',
 	  FPS_COLOR                = '#0f0',
-	  GRADIENT_CLASSIC         = 'classic',
-	  GRADIENT_PRISM           = 'prism',
-	  GRADIENT_RAINBOW         = 'rainbow',
 	  LEDS_UNLIT_COLOR         = '#7f7f7f22',
 	  REASON_CREATE            = 'create',
 	  REASON_FSCHANGE          = 'fschange',
@@ -47,6 +44,33 @@ const CANVAS_BACKGROUND_COLOR  = '#000',
 	  SCALE_LOG                = 'log',
 	  SCALE_MEL                = 'mel';
 
+// built-in gradients
+const PRISM = [ '#a35', '#c66', '#e94', '#ed0', '#9d5', '#4d8', '#2cb', '#0bc', '#09c', '#36b' ],
+	  GRADIENTS = [
+	  [ 'classic', {
+			colorStops: [
+				'hsl( 0, 100%, 50% )',
+				{ pos: .6, color: 'hsl( 60, 100%, 50% )' },
+				'hsl( 120, 100%, 50% )'
+			]
+	  }],
+	  [ 'prism', {
+			colorStops: PRISM
+	  }],
+	  [ 'rainbow', {
+			dir: 'h',
+			colorStops: [ '#817', ...PRISM, '#639' ]
+	  }],
+	  [ 'orangered', {
+	  		bgColor: '#3e2f29',
+	  		colorStops: [ 'OrangeRed' ]
+	  }],
+	  [ 'steelblue', {
+	  		bgColor: '#222c35',
+	  		colorStops: [ 'SteelBlue' ]
+	  }]
+];
+
 // custom error messages
 const ERR_AUDIO_CONTEXT_FAIL     = [ 'ERR_AUDIO_CONTEXT_FAIL', 'Could not create audio context. Web Audio API not supported?' ],
 	  ERR_INVALID_AUDIO_CONTEXT  = [ 'ERR_INVALID_AUDIO_CONTEXT', 'Provided audio context is not valid' ],
@@ -88,38 +112,12 @@ export default class AudioMotionAnalyzer {
 
 		// Initialize internal gradient objects
 		this._gradients = {};       // registered gradients
-		this._gradientNames = [];   // names of the currently selected gradients for channels 0 and 1
+		this._selectedGrads = [];   // names of the currently selected gradients for channels 0 and 1
 		this._canvasGradients = []; // actual CanvasGradient objects for channels 0 and 1
 
 		// Register built-in gradients
-		this.registerGradient( GRADIENT_CLASSIC, {
-			colorStops: [
-				'hsl( 0, 100%, 50% )',
-				{ pos: .6, color: 'hsl( 60, 100%, 50% )' },
-				'hsl( 120, 100%, 50% )'
-			]
-		});
-		this.registerGradient( GRADIENT_PRISM, {
-			colorStops: [
-				'hsl( 0, 100%, 50% )',
-				'hsl( 60, 100%, 50% )',
-				'hsl( 120, 100%, 50% )',
-				'hsl( 180, 100%, 50% )',
-				'hsl( 240, 100%, 50% )'
-			]
-		});
-		this.registerGradient( GRADIENT_RAINBOW, {
-			dir: 'h',
-			colorStops: [
-				'hsl( 0, 100%, 50% )',
-				'hsl( 60, 100%, 50% )',
-				'hsl( 120, 100%, 50% )',
-				'hsl( 180, 100%, 47% )',
-				'hsl( 240, 100%, 58% )',
-				'hsl( 300, 100%, 50% )',
-				'hsl( 360, 100%, 50% )'
-			]
-		});
+		for ( const [ name, options ] of GRADIENTS )
+			this.registerGradient( name, options );
 
 		// Set container
 		this._container = container || document.body;
@@ -315,8 +313,8 @@ export default class AudioMotionAnalyzer {
 		return this._chLayout;
 	}
 	set channelLayout( value ) {
-		const MODES = [ CHANNEL_SINGLE, CHANNEL_VERTICAL, CHANNEL_COMBINED ];
-		this._chLayout = MODES[ Math.max( 0, MODES.findIndex( el => el.toLowerCase() == ( '' + value ).toLowerCase() ) ) ];
+		const LAYOUTS = [ CHANNEL_SINGLE, CHANNEL_VERTICAL, CHANNEL_COMBINED ];
+		this._chLayout = LAYOUTS[ Math.max( 0, LAYOUTS.indexOf( ( '' + value ).toLowerCase() ) ) ];
 
 		// update node connections
 		this._input.disconnect();
@@ -354,21 +352,21 @@ export default class AudioMotionAnalyzer {
 	}
 
 	get gradient() {
-		return this._gradientNames[0];
+		return this._selectedGrads[0];
 	}
 	set gradient( value ) {
 		this._setGradient( value );
 	}
 
 	get gradientLeft() {
-		return this._gradientNames[0];
+		return this._selectedGrads[0];
 	}
 	set gradientLeft( value ) {
 		this._setGradient( value, 0 );
 	}
 
 	get gradientRight() {
-		return this._gradientNames[1];
+		return this._selectedGrads[1];
 	}
 	set gradientRight( value ) {
 		this._setGradient( value, 1 );
@@ -808,7 +806,7 @@ export default class AudioMotionAnalyzer {
 		};
 
 		// if the registered gradient is one of the currently selected gradients, regenerate them
-		if ( this._gradientNames.includes( name ) )
+		if ( this._selectedGrads.includes( name ) )
 			this._makeGrad();
 	}
 
@@ -1126,7 +1124,7 @@ export default class AudioMotionAnalyzer {
 					  [ binLo, ratioLo ] = calcRatio( freqLo ),
 					  [ binHi, ratioHi ] = calcRatio( freqHi );
 
-				barsPush( { posX, freq, freqLo, freqHi, binLo, binHi, ratioLo, ratioHi } );
+				barsPush( { posX: initialX + posX, freq, freqLo, freqHi, binLo, binHi, ratioLo, ratioHi } );
 			}
 
 		}
@@ -1353,11 +1351,15 @@ export default class AudioMotionAnalyzer {
 	 * this is called 60 times per second by requestAnimationFrame()
 	 */
 	_draw( timestamp ) {
-		const ctx            = this._canvasCtx,
+		const barSpace       = this._barSpace,
+			  barSpacePx     = this._barSpacePx,
+			  ctx            = this._canvasCtx,
 			  canvas         = ctx.canvas,
 			  canvasX        = this._scaleX.canvas,
 			  canvasR        = this._scaleR.canvas,
+			  canvasGradients= this._canvasGradients,
 			  energy         = this._energy,
+			  fillAlpha      = this.fillAlpha,
 			  mode           = this._mode,
 			  isAlphaBars    = this._isAlphaBars,
 			  isLedDisplay   = this._isLedDisplay,
@@ -1365,6 +1367,7 @@ export default class AudioMotionAnalyzer {
 			  isLumiBars     = this._isLumiBars,
 			  isBandsMode    = this._isBandsMode,
 			  isOutline      = this._isOutline,
+			  isOverlay      = this.overlay,
 			  isRadial       = this._radial,
 			  channelLayout  = this._chLayout,
 			  lineWidth      = +this.lineWidth, // make sure the damn thing is a number!
@@ -1378,6 +1381,7 @@ export default class AudioMotionAnalyzer {
 			  centerX        = canvas.width >> 1,
 			  centerY        = canvas.height >> 1,
 			  radius         = this._radius,
+			  showBgColor    = this.showBgColor,
 			  maxBarHeight   = isRadial ? Math.min( centerX, centerY ) - radius : analyzerHeight,
 			  maxdB			 = this.maxDecibels,
 			  mindB			 = this.minDecibels,
@@ -1461,15 +1465,12 @@ export default class AudioMotionAnalyzer {
 		const [ ledCount, ledSpaceH, ledSpaceV, ledHeight ] = this._leds || [];
 		const ledPosY = height => Math.max( 0, ( height * ledCount | 0 ) * ( ledHeight + ledSpaceV ) - ledSpaceV );
 
-		// select background color
-		const bgColor = ( ! this.showBgColor || isLedDisplay && ! this.overlay ) ? '#000' : this._gradients[ this._gradientNames[0] ].bgColor;
-
 		// compute the effective bar width, considering the selected bar spacing
 		// if led effect is active, ensure at least the spacing from led definitions
-		let width = this._barWidth - ( ! isBandsMode ? 0 : Math.max( isLedDisplay ? ledSpaceH : 0, this._barSpacePx ) );
+		let width = this._barWidth - ( ! isBandsMode ? 0 : Math.max( isLedDisplay ? ledSpaceH : 0, barSpacePx ) );
 
 		// make sure width is integer for pixel accurate calculation, when no bar spacing is required
-		if ( this._barSpace == 0 && ! isLedDisplay )
+		if ( barSpace == 0 && ! isLedDisplay )
 			width |= 0;
 
 		let currentEnergy = 0;
@@ -1481,24 +1482,26 @@ export default class AudioMotionAnalyzer {
 
 			const channelTop     = channelLayout == CHANNEL_VERTICAL ? channelHeight * channel + channelGap * channel : 0,
 				  channelBottom  = channelTop + channelHeight,
-				  analyzerBottom = channelTop + analyzerHeight - ( isLedDisplay && ! this._maximizeLeds ? ledSpaceV : 0 );
+				  analyzerBottom = channelTop + analyzerHeight - ( isLedDisplay && ! this._maximizeLeds ? ledSpaceV : 0 ),
+				  bgColor        = ( ! showBgColor || isLedDisplay && ! isOverlay ) ? '#000' : this._gradients[ this._selectedGrads[ channel ] ].bgColor,
+				  mustClear      = channel == 0 || ! isRadial && channelLayout != CHANNEL_COMBINED;
 
 			if ( useCanvas ) {
 				// clear the channel area, if in overlay mode
 				// this is done per channel to clear any residue below 0 off the top channel (especially in line graph mode with lineWidth > 1)
-				if ( this.overlay && ( ! isRadial || channel == 0 ) )
+				if ( isOverlay && mustClear )
 					ctx.clearRect( 0, channelTop - channelGap, canvas.width, channelHeight + channelGap );
 
 				// fill the analyzer background if needed (not overlay or overlay + showBgColor)
-				if ( ! this.overlay || this.showBgColor ) {
-					if ( this.overlay )
+				if ( ! isOverlay || showBgColor ) {
+					if ( isOverlay )
 						ctx.globalAlpha = this.bgAlpha;
 
 					ctx.fillStyle = bgColor;
 
 					// exclude the reflection area when overlay is true and reflexAlpha == 1 (avoids alpha over alpha difference, in case bgAlpha < 1)
-					if ( ! isRadial && channelLayout != CHANNEL_COMBINED || channel == 0 )
-						ctx.fillRect( initialX, channelTop - channelGap, analyzerWidth, ( this.overlay && this.reflexAlpha == 1 ? analyzerHeight : channelHeight ) + channelGap );
+					if ( mustClear )
+						ctx.fillRect( initialX, channelTop - channelGap, analyzerWidth, ( isOverlay && this.reflexAlpha == 1 ? analyzerHeight : channelHeight ) + channelGap );
 
 					ctx.globalAlpha = 1;
 				}
@@ -1556,7 +1559,7 @@ export default class AudioMotionAnalyzer {
 					ctx.lineWidth = isOutline ? Math.min( lineWidth, width / 2 ) : lineWidth;
 
 				// set selected gradient for fill and stroke
-				ctx.fillStyle = ctx.strokeStyle = this._canvasGradients[ channel ];
+				ctx.fillStyle = ctx.strokeStyle = canvasGradients[ channel ];
 			} // if ( useCanvas )
 
 			// get a new array of data from the FFT
@@ -1622,7 +1625,7 @@ export default class AudioMotionAnalyzer {
 				if ( isLumiBars || isAlphaBars )
 					ctx.globalAlpha = barHeight;
 				else if ( isOutline )
-					ctx.globalAlpha = this.fillAlpha;
+					ctx.globalAlpha = fillAlpha;
 
 				// compute actual bar height on screen
 				barHeight = isLedDisplay ? ledPosY( barHeight ) : barHeight * maxBarHeight | 0;
@@ -1671,9 +1674,9 @@ export default class AudioMotionAnalyzer {
 				else {
 					if ( mode > 0 ) {
 						if ( isLedDisplay )
-							posX += Math.max( ledSpaceH / 2, this._barSpacePx / 2 );
+							posX += Math.max( ledSpaceH / 2, barSpacePx / 2 );
 						else {
-							if ( this._barSpace == 0 ) {
+							if ( barSpace == 0 ) {
 								posX |= 0;
 								if ( i > 0 && posX > this._bars[ i - 1 ].posX + width ) {
 									posX--;
@@ -1681,14 +1684,14 @@ export default class AudioMotionAnalyzer {
 								}
 							}
 							else
-								posX += this._barSpacePx / 2;
+								posX += barSpacePx / 2;
 						}
 					}
 
 					if ( isLedDisplay ) {
 						const x = posX + width / 2;
 						// draw "unlit" leds
-						if ( this.showBgColor && ! this.overlay ) {
+						if ( showBgColor && ! isOverlay ) {
 							const alpha = ctx.globalAlpha;
 							ctx.beginPath();
 							ctx.moveTo( x, channelTop );
@@ -1770,7 +1773,7 @@ export default class AudioMotionAnalyzer {
 				if ( lineWidth > 0 )
 					ctx.stroke();
 
-				if ( this.fillAlpha > 0 ) {
+				if ( fillAlpha > 0 ) {
 					if ( isRadial ) {
 						// exclude the center circle from the fill area
 						ctx.moveTo( centerX + radius, centerY );
@@ -1781,7 +1784,7 @@ export default class AudioMotionAnalyzer {
 						ctx.lineTo( initialX, analyzerBottom );
 					}
 
-					ctx.globalAlpha = this.fillAlpha;
+					ctx.globalAlpha = fillAlpha;
 					ctx.fill();
 					ctx.globalAlpha = 1;
 				}
@@ -1876,8 +1879,8 @@ export default class AudioMotionAnalyzer {
 		// call callback function, if defined
 		if ( this.onCanvasDraw ) {
 			ctx.save();
-			ctx.fillStyle = ctx.strokeStyle = this._canvasGradients[0];
-			this.onCanvasDraw( this );
+			ctx.fillStyle = ctx.strokeStyle = canvasGradients[0];
+			this.onCanvasDraw( this, { timestamp, canvasGradients } );
 			ctx.restore();
 		}
 
@@ -1921,9 +1924,10 @@ export default class AudioMotionAnalyzer {
 
 		const ctx            = this._canvasCtx,
 			  canvas         = ctx.canvas,
+			  channelLayout  = this._chLayout,
 			  isLumiBars     = this._isLumiBars,
 			  isRadial       = this._radial,
-			  gradientHeight = isLumiBars ? canvas.height : canvas.height * ( 1 - this._reflexRatio * ( this._chLayout != CHANNEL_VERTICAL ) ) | 0,
+			  gradientHeight = isLumiBars ? canvas.height : canvas.height * ( 1 - this._reflexRatio * ( channelLayout != CHANNEL_VERTICAL ) ) | 0,
 			  				   // for vertical stereo we keep the full canvas height and handle the reflex areas while generating the color stops
 			  analyzerRatio  = 1 - this._reflexRatio,
 			  initialX       = this._initialX;
@@ -1934,29 +1938,28 @@ export default class AudioMotionAnalyzer {
 			  maxRadius = Math.min( centerX, centerY ),
 			  radius    = this._radius;
 
-		for ( let chn = 0; chn < 2; chn++ ) {
-			const currGradient = this._gradients[ this._gradientNames[ chn ] ],
+		for ( const channel of [0,1] ) {
+			const currGradient = this._gradients[ this._selectedGrads[ channel ] ],
 				  colorStops   = currGradient.colorStops,
 				  isHorizontal = currGradient.dir == 'h';
 
 			let grad;
 
 			if ( isRadial )
-				grad = ctx.createRadialGradient( centerX, centerY, maxRadius, centerX, centerY, radius - ( maxRadius - radius ) * ( this._chLayout == CHANNEL_VERTICAL ) );
+				grad = ctx.createRadialGradient( centerX, centerY, maxRadius, centerX, centerY, radius - ( maxRadius - radius ) * ( channelLayout == CHANNEL_VERTICAL ) );
 			else
 				grad = ctx.createLinearGradient( ...( isHorizontal ? [ initialX, 0, initialX + this._analyzerWidth, 0 ] : [ 0, 0, 0, gradientHeight ] ) );
 
 			if ( colorStops ) {
-				const dual = this._chLayout == CHANNEL_VERTICAL && ! this._splitGradient && ( ! isHorizontal || isRadial );
+				const dual = channelLayout == CHANNEL_VERTICAL && ! this._splitGradient && ( ! isHorizontal || isRadial );
 
 				// helper function
 				const addColorStop = ( offset, colorInfo ) => grad.addColorStop( offset, colorInfo.color || colorInfo );
 
-				for ( let channel = 0; channel < 1 + dual; channel++ ) {
-					colorStops.forEach( ( colorInfo, index ) => {
+				for ( let channelArea = 0; channelArea < 1 + dual; channelArea++ ) {
 
+					colorStops.forEach( ( colorInfo, index ) => {
 						const maxIndex = colorStops.length - 1;
-
 						let offset = colorInfo.pos !== undefined ? colorInfo.pos : index / Math.max( 1, maxIndex );
 
 						// in dual mode (not split), use half the original offset for each channel
@@ -1964,15 +1967,15 @@ export default class AudioMotionAnalyzer {
 							offset /= 2;
 
 						// constrain the offset within the useful analyzer areas (avoid reflex areas)
-						if ( this._chLayout == CHANNEL_VERTICAL && ! isLumiBars && ! isRadial && ! isHorizontal ) {
+						if ( channelLayout == CHANNEL_VERTICAL && ! isLumiBars && ! isRadial && ! isHorizontal ) {
 							offset *= analyzerRatio;
 							// skip the first reflex area in split mode
 							if ( ! dual && offset > .5 * analyzerRatio )
 								offset += .5 * this._reflexRatio;
 						}
 
-						// only for non-split gradient
-						if ( channel == 1 ) {
+						// only for dual-vertical non-split gradient (creates full gradient on both halves of the canvas)
+						if ( channelArea == 1 ) {
 							// add colors in reverse order if radial or lumi are active
 							if ( isRadial || isLumiBars ) {
 								const revIndex = maxIndex - index;
@@ -1992,14 +1995,14 @@ export default class AudioMotionAnalyzer {
 						addColorStop( offset, colorInfo );
 
 						// create additional color stop at the end of first channel to prevent bleeding
-						if ( this._chLayout == CHANNEL_VERTICAL && index == maxIndex && offset < .5 )
+						if ( channelLayout == CHANNEL_VERTICAL && index == maxIndex && offset < .5 )
 							addColorStop( .5, colorInfo );
 					});
-				}
+				} // for ( let channelArea = 0; channelArea < 1 + dual; channelArea++ )
 			}
 
-			this._canvasGradients[ chn ] = grad;
-		} // for (chn)
+			this._canvasGradients[ channel ] = grad;
+		} // for ( const channel of [0,1] )
 	}
 
 	/**
@@ -2104,11 +2107,11 @@ export default class AudioMotionAnalyzer {
 			throw new AudioMotionError( ERR_UNKNOWN_GRADIENT, name );
 
 		if ( ! [0,1].includes( channel ) ) {
-			this._gradientNames[1] = name;
+			this._selectedGrads[1] = name;
 			channel = 0;
 		}
 
-		this._gradientNames[ channel ] = name;
+		this._selectedGrads[ channel ] = name;
 		this._makeGrad();
 	}
 
@@ -2127,7 +2130,7 @@ export default class AudioMotionAnalyzer {
 			fftSize        : 8192,
 			fillAlpha      : 1,
 			frequencyScale : SCALE_LOG,
-			gradient       : GRADIENT_CLASSIC,
+			gradient       : GRADIENTS[0][0],
 			ledBars        : false,
 			linearAmplitude: false,
 			linearBoost    : 1,

package/src/index.d.ts

@@ -1,5 +1,14 @@
-type OnCanvasDrawFunction = (instance: AudioMotionAnalyzer) => unknown;
-type OnCanvasResizeFunction = (
+export type OnCanvasDrawFunction = (
+  instance: AudioMotionAnalyzer,
+  info: CanvasDrawInfo
+) => unknown;
+
+export type CanvasDrawInfo = {
+  timestamp: DOMHighResTimeStamp,
+  canvasGradients: CanvasGradient[]
+}
+
+export type OnCanvasResizeFunction = (
   reason: CanvasResizeReason,
   instance: AudioMotionAnalyzer
 ) => unknown;
@@ -74,7 +83,7 @@ export interface ConstructorOptions extends Options {
   source?: HTMLMediaElement | AudioNode;
 }
 
-export type ChannelLayout = "single" | "dualVertical" | "dualCombined";
+export type ChannelLayout = "single" | "dual-vertical" | "dual-combined";
 
 export type EnergyPreset = "peak" | "bass" | "lowMid" | "mid" | "highMid" | "treble";