audiomotion-analyzer 4.0.0-beta.5 → 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/
 
@@ -247,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)*
@@ -326,8 +331,8 @@ Defines the number and layout of analyzer channels.
 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.
@@ -385,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'**.
 
@@ -419,7 +424,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:
 
@@ -635,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*
@@ -911,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:
 
@@ -928,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 ) );
 }
 ```
 
@@ -947,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
 -------|------------
@@ -1259,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:
 
@@ -1281,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
 
@@ -1293,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
@@ -1303,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.5",
+  "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.5
+ * @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.5';
+const VERSION = '4.0.0';
 
 // internal constants
 const TAU     = 2 * Math.PI,
@@ -45,7 +45,8 @@ const CANVAS_BACKGROUND_COLOR  = '#000',
 	  SCALE_MEL                = 'mel';
 
 // built-in gradients
-const GRADIENTS = [
+const PRISM = [ '#a35', '#c66', '#e94', '#ed0', '#9d5', '#4d8', '#2cb', '#0bc', '#09c', '#36b' ],
+	  GRADIENTS = [
 	  [ 'classic', {
 			colorStops: [
 				'hsl( 0, 100%, 50% )',
@@ -54,25 +55,11 @@ const GRADIENTS = [
 			]
 	  }],
 	  [ 'prism', {
-			colorStops: [
-				'hsl( 0, 100%, 50% )',
-				'hsl( 60, 100%, 50% )',
-				'hsl( 120, 100%, 50% )',
-				'hsl( 180, 100%, 50% )',
-				'hsl( 240, 100%, 50% )'
-			]
+			colorStops: PRISM
 	  }],
 	  [ '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% )'
-			]
+			colorStops: [ '#817', ...PRISM, '#639' ]
 	  }],
 	  [ 'orangered', {
 	  		bgColor: '#3e2f29',
@@ -1137,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 } );
 			}
 
 		}
@@ -1370,6 +1357,7 @@ export default class AudioMotionAnalyzer {
 			  canvas         = ctx.canvas,
 			  canvasX        = this._scaleX.canvas,
 			  canvasR        = this._scaleR.canvas,
+			  canvasGradients= this._canvasGradients,
 			  energy         = this._energy,
 			  fillAlpha      = this.fillAlpha,
 			  mode           = this._mode,
@@ -1571,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
@@ -1891,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();
 		}
 

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;