audiomotion-analyzer 3.6.1 → 4.0.0-beta.1

package/README.md

@@ -3,8 +3,8 @@
 
 **audioMotion-analyzer** is a high-resolution real-time audio spectrum analyzer built upon **Web Audio** and **Canvas** JavaScript APIs.
 
-It was originally conceived as part of a full-featured music player called [**audioMotion**](https://audiomotion.me), but I later decided to make just
-the spectrum analyzer available as a self-contained module, so other developers could use it in their own projects.
+It was originally conceived as part of a full-featured music player called [**audioMotion**](https://audiomotion.me),
+but I later decided to make only the spectrum analyzer available as a self-contained module, so other developers could use it in their own projects.
 
 My goal is to make this the best looking, most accurate and customizable spectrum analyzer around, in a small-footprint and high-performance package.
 
@@ -29,7 +29,7 @@ What users are saying:
 
 + High-resolution real-time dual channel audio spectrum analyzer
 + Logarithmic frequency scale with customizable range
-+ Visualize discrete frequencies or octave bands based on the equal tempered scale
++ Visualize discrete FFT frequencies or octave bands
 + Optional effects: vintage LEDs, luminance bars, mirroring and reflection, radial visualization
 + Customizable sensitivity, FFT size and time-smoothing constant
 + Comes with 3 predefined color gradients - easily add your own!
@@ -48,7 +48,10 @@ What users are saying:
 - [Using microphone input](https://codepen.io/hvianna/pen/VwKZgEE)
 - [Creating additional effects with `getEnergy()`](https://codepen.io/hvianna/pen/poNmVYo)
 - [No canvas example](https://codepen.io/hvianna/pen/ZEKWWJb) (create your own visualization using analyzer data)
-- [Integration with Pizzicato library](https://codesandbox.io/s/9y6qb) - see [this discussion](https://github.com/hvianna/audioMotion-analyzer/issues/10) for more info
+- Example integrations with other audio libraries:
+  - [Icecast Metadata Player](https://codepen.io/hvianna/pen/YzrgWVe)
+  - [Pizzicato](https://codesandbox.io/s/9y6qb)
+  - [jPlayer](https://codepen.io/hvianna/pen/dyVrMJX)
 - [See more code examples on CodePen](https://codepen.io/collection/ABbbKr)
 
 ## Usage
@@ -71,7 +74,7 @@ Or download the [latest version](https://github.com/hvianna/audioMotion-analyzer
 Install as a dependency:
 
 ```console
-$ npm i --save audiomotion-analyzer
+$ npm i audiomotion-analyzer
 ```
 
 Use ES6 import syntax:
@@ -111,6 +114,7 @@ Properties marked as *constructor only* can only be set by the constructor call,
 
 options = {<br>
 &emsp;&emsp;[alphaBars](#alphabars-boolean): **false**,<br>
+&emsp;&emsp;[ansiBands](#ansibands-boolean): **false**,<br>
 &emsp;&emsp;[audioCtx](#audioctx-audiocontext-object): *undefined*, // constructor only<br>
 &emsp;&emsp;[barSpace](#barspace-number): **0.1**,<br>
 &emsp;&emsp;[bgAlpha](#bgalpha-number): **0.7**,<br>
@@ -121,6 +125,7 @@ options = {<br>
 &emsp;&emsp;[gradient](#gradient-string): **'classic'**,<br>
 &emsp;&emsp;[height](#height-number): *undefined*,<br>
 &emsp;&emsp;[ledBars](#ledbars-boolean): **false**,<br>
+&emsp;&emsp;[linearAmplitude](#linearamplitude-boolean): **false**,<br>
 &emsp;&emsp;[lineWidth](#linewidth-number): **0**,<br>
 &emsp;&emsp;[loRes](#lores-boolean): **false**,<br>
 &emsp;&emsp;[lumiBars](#lumibars-boolean): **false**,<br>
@@ -130,6 +135,7 @@ options = {<br>
 &emsp;&emsp;[minFreq](#minfreq-number): **20**,<br>
 &emsp;&emsp;[mirror](#mirror-number): **0**,<br>
 &emsp;&emsp;[mode](#mode-number): **0**,<br>
+&emsp;&emsp;[noteLabels](#notelabels-boolean): **false**,<br>
 &emsp;&emsp;[onCanvasDraw](#oncanvasdraw-function): *undefined*,<br>
 &emsp;&emsp;[onCanvasResize](#oncanvasresize-function): *undefined*,<br>
 &emsp;&emsp;[outlineBars](#outlinebars-boolean): **false**,<br>
@@ -141,7 +147,6 @@ options = {<br>
 &emsp;&emsp;[reflexRatio](#reflexratio-number): **0**,<br>
 &emsp;&emsp;[showBgColor](#showbgcolor-boolean): **true**,<br>
 &emsp;&emsp;[showFPS](#showfps-boolean): **false**,<br>
-&emsp;&emsp;[showLeds](#showleds-deprecated): **false**, // DEPRECATED - use ledBars instead<br>
 &emsp;&emsp;[showPeaks](#showpeaks-boolean): **true**,<br>
 &emsp;&emsp;[showScaleX](#showscalex-boolean): **true**,<br>
 &emsp;&emsp;[showScaleY](#showscaley-boolean): **false**,<br>
@@ -153,6 +158,7 @@ options = {<br>
 &emsp;&emsp;[stereo](#stereo-boolean): **false**,<br>
 &emsp;&emsp;[useCanvas](#usecanvas-boolean): **true**,<br>
 &emsp;&emsp;[volume](#volume-number): **1**,<br>
+&emsp;&emsp;[weightingFilter](#weightingFilter-string): **''**<br>
 &emsp;&emsp;[width](#width-number): *undefined*<br>
 }
 
@@ -186,10 +192,10 @@ only one of them needs to be connected to the speakers, otherwise the volume wil
 
 After instantiation, use [`connectOutput()`](#connectoutput-node-) and [`disconnectOutput()`](#disconnectoutput-node-) to connect or disconnect the output from the speakers (or other nodes).
 
-Defaults to **true**.
-
 See also [`connectedTo`](#connectedto-array-read-only).
 
+Defaults to **true**.
+
 #### `fsElement` *HTMLElement object*
 
 *Available since v3.4.0*
@@ -232,6 +238,18 @@ Defaults to **false**.
 
 !> [See related known issue](#alphabars-and-fillalpha-wont-work-with-radial-on-firefox)
 
+### `ansiBands` *boolean*
+
+*Available since v4.0.0*
+
+When set to *true* uses ANSI/IEC preferred frequencies to generate the bands for [octave bands modes](#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
+the center of each band is perfectly tuned to a musical note.
+
+Defaults to **false**.
+
 ### `audioCtx` *AudioContext object* *(Read only)*
 
 [*AudioContext*](https://developer.mozilla.org/en-US/docs/Web/API/AudioContext) used by **audioMotion-analyzer**.
@@ -310,10 +328,6 @@ By default, **audioMotion-analyzer** is connected to the *AudioContext* `destina
 
 See also [`connectOutput()`](#connectoutput-node-).
 
-### `energy` **(DEPRECATED)**
-
-**This property will be removed in version 4.0.0** - Use [`getEnergy()`](#getenergy-preset-startfreq-endfreq-) instead.
-
 ### `fftSize` *number*
 
 Number of samples used for the FFT performed by the [*AnalyzerNode*](https://developer.mozilla.org/en-US/docs/Web/API/AnalyserNode).
@@ -396,10 +410,6 @@ See [`toggleFullscreen()`](#togglefullscreen).
 
 ***true*** when LED bars are effectively being displayed, i.e., [`ledBars`](#ledBars-boolean) is set to *true* and [`mode`](#mode-number) is set to an octave bands mode and [`radial`](#radial-boolean) is *false*.
 
-### `isLedDisplay` **(DEPRECATED)**
-
-**This property will be removed in version 4.0.0** - Use [`isLedBars`](#isledbars-boolean-read-only) instead.
-
 ### `isLumiBars` *boolean* *(Read only)*
 
 *Available since v3.0.0*
@@ -437,6 +447,28 @@ For effect priority when combined with other settings, see [`isLedBars`](#isledb
 
 Defaults to **false**.
 
+### `linearAmplitude` *boolean*
+
+*Available since v4.0.0*
+
+When set to *true*, spectrum amplitudes are represented in linear scale instead of decibels (logarithmic).
+
+This may improve the visualization of predominant tones, especially at higher frequencies, but it will make the entire spectrum look much quieter.
+
+See also [`linearBoost`](#linearboost-number).
+
+Defaults to **false**.
+
+### `linearBoost` *number*
+
+*Available since v4.0.0*
+
+Performs an *n*th-root to amplify low energy values when using linear scale for the amplitude.
+
+It should be a number >= 1, while 1 means no boosting. Only effective when [`linearAmplitude`](#linearamplitude-boolean) is set to *true*.
+
+Defaults to **1**.
+
 ### `lineWidth` *number*
 
 *Available since v2.0.0*
@@ -496,7 +528,8 @@ Highest and lowest frequencies represented in the X-axis of the analyzer. Values
 
 The minimum allowed value is **1**. Trying to set a lower value will throw an `ERR_FREQUENCY_TOO_LOW` [error](#custom-errors).
 
-The maximum practical value is half the sampling rate ([`audioCtx.sampleRate`](#audioctx-audiocontext-object-read-only)), although this is not enforced by **audioMotion-analyzer**.
+The maximum allowed value is half the sampling rate ([`audioCtx.sampleRate`](#audioctx-audiocontext-object-read-only)), known as the [Nyquist frequency](https://en.wikipedia.org/wiki/Nyquist_frequency).
+Values higher than that will be capped.
 
 It is preferable to use the [`setFreqRange()`](#setfreqrange-minfreq-maxfreq-) method and set both values at once, to prevent `minFreq` being higher than the current `maxFreq` or vice-versa at a given moment.
 
@@ -542,6 +575,16 @@ mode | description | notes
 
 Defaults to **0**.
 
+### `noteLabels` *boolean*
+
+*Available since v4.0.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, make sure [`ansiBands`](#ansibands-boolean) is set to *false*, so all bands will be perfectly aligned with notes frequencies.
+
+Defaults to **false**.
+
 ### `outlineBars` *boolean*
 
 *Available since v3.6.0*
@@ -564,27 +607,25 @@ Defaults to **false**.
 
 ?> In order to keep elements other than the canvas visible in fullscreen, you'll need to set the [`fsElement`](#fselement-htmlelement-object) property in the [constructor](#constructor) options.
 
-### `peakEnergy` **(DEPRECATED)**
-
-**This property will be removed in version 4.0.0** - Use [`getEnergy('peak')`](#getenergy-preset-startfreq-endfreq-) instead.
-
 ### `pixelRatio` *number* *(Read only)*
 
 Current [devicePixelRatio](https://developer.mozilla.org/en-US/docs/Web/API/Window/devicePixelRatio).
 This is usually **1** for standard displays and **2** for retina / Hi-DPI screens.
 
-You can refer to this value to adjust any additional drawings done in the canvas (via [callback function](#oncanvasdraw-function)).
+When [`loRes`](#lores-boolean) is *true*, the value of `pixelRatio` is halved, i.e. **0.5** for standard displays and **1** for retina / Hi-DPI.
 
-When [`loRes`](#lores-boolean) is *true* `pixelRatio` is halved, i.e. **0.5** for standard displays and **1** for retina / Hi-DPI.
+You can refer to this value to adjust any additional drawings done in the canvas (via [callback function](#oncanvasdraw-function)).
 
 ### `radial` *boolean*
 
 *Available since v2.4.0*
 
-When *true*, the spectrum analyzer is rendered as a circle, with radial frequency bars spreading from the center of the canvas.
+When *true*, the spectrum analyzer is rendered in a circular shape, with radial frequency bars spreading from its center.
 
-When radial mode is active, [`ledBars`](#ledbars-boolean) and [`lumiBars`](#lumibars-boolean) have no effect, and
-also [`showPeaks`](#showpeaks-boolean) has no effect in radial **Graph** mode.
+In radial visualization, [`ledBars`](#ledbars-boolean) and [`lumiBars`](#lumibars-boolean) effects are disabled, and
+[`showPeaks`](#showpeaks-boolean) has no effect for [**Graph** mode](#mode-number).
+
+When [`stereo`](#stereo-boolean) is *true*, a larger diameter is used and the right channel bars are rendered towards the center of the analyzer.
 
 See also [`spinSpeed`](#spinspeed-number).
 
@@ -654,30 +695,35 @@ and setting `showBgColor` to ***true*** will make the "unlit" LEDs visible inste
 
 *true* to display the current frame rate. Defaults to **false**.
 
-### `showLeds` **(DEPRECATED)**
-
-**This property will be removed in version 4.0.0** - Use [`ledBars`](#ledbars-boolean) instead.
-
 ### `showPeaks` *boolean*
 
 *true* to show amplitude peaks for each frequency. Defaults to **true**.
 
 ### `showScaleX` *boolean*
 
-*Available since v3.0.0*
+*Available since v3.0.0 - this property was named `showScale` in earlier versions*
+
+*true* to display scale labels on the X axis.
 
-*true* to display the frequency (Hz) scale on the X axis. Defaults to **true**.
+See also [`noteLabels`](#notelabels-boolean).
 
-*NOTE: this property was named `showScale` in versions prior to v3.0.0*
+Defaults to **true**.
 
 ### `showScaleY` *boolean*
 
 *Available since v2.4.0*
 
-*true* to display the level (dB) scale on the Y axis. Defaults to **false**.
+*true* to display the level/amplitude scale on the Y axis.
 
 This option has no effect when [`radial`](#radial-boolean) or [`lumiBars`](#lumibars-boolean) are set to *true*.
 
+When [`linearAmplitude`](#linearamplitude-boolean) is set to *false* (default), labels are shown in decibels (dB);
+otherwise, values represent a percentage (0-100%) of the maximum amplitude.
+
+See also [`minDecibels`](#mindecibels-number) and [`maxDecibels`](#maxdecibels-number).
+
+Defaults to **false**.
+
 ### `smoothing` *number*
 
 Sets the analyzer's [smoothingTimeConstant](https://developer.mozilla.org/en-US/docs/Web/API/AnalyserNode/smoothingTimeConstant).
@@ -752,6 +798,30 @@ Please note that changing the audio element volume directly will affect the ampl
 
 Defaults to **1**.
 
+### `weightingFilter` *string*
+
+*Available since v4.0.0*
+
+Select a [weighting filter](https://en.wikipedia.org/wiki/Weighting_filter) for spectrum visualization.
+
+Each filter applies a different curve of gain/attenuation to specific frequency ranges, but the general idea is to adjust the
+visualization of frequencies to which the human ear is more or less sensitive.
+Refer to the [weighting filters viewer tool](/tools/weighting-filters.html) for curves and response tables.
+
+?> Selecting a weighting filter **does NOT** affect the audio output, only the visualization.
+
+weightingFilter | description
+------|------------------------------
+'' (empty string) | No weighting applied (default)
+'A'   | A-weighting
+'B'   | B-weighting
+'C'   | C-weighting
+'D'   | D-weighting
+'468' | ITU-R 468 weighting
+
+Defaults to **''**.
+
+
 ## Static properties
 
 ### `AudioMotionAnalyzer.version` *string* *(Read only)*
@@ -894,8 +964,9 @@ Returns an array with current data for each analyzer bar. Each array element is
 ```js
 {
 	posX: <number>,   // horizontal position of this bar on the canvas
-	freqLo: <number>, // starting frequency for this bar
-	freqHi: <number>, // ending frequency for this bar
+	freq: <number>,   // center frequency for this bar (added in v4.0.0)
+	freqLo: <number>, // lower edge frequency
+	freqHi: <number>, // upper edge frequency
 	peak: <array>,    // peak values for left and right channels
 	hold: <array>,    // peak hold frames for left and right channels - values < 0 mean the peak is falling down
 	value: <array>    // current amplitude on left and right channels
@@ -910,7 +981,7 @@ Please note that `hold` and `value` will have only one element when [`stereo`](#
 
 You can use this method to create your own visualizations using the analyzer data. See [this pen](https://codepen.io/hvianna/pen/ZEKWWJb) for usage example.
 
-### `getEnergy( [preset | startFreq], [endFreq] )`
+### `getEnergy( [preset | startFreq [, endFreq] ] )`
 
 *Available since v3.2.0*
 
@@ -975,11 +1046,13 @@ Sets the analyzer nominal dimensions in pixels. See [`height`](#height-number) a
 
 Sets the desired frequency range. Values are expressed in Hz (Hertz).
 
+See [`minFreq` and `maxFreq`](#minfreq-number) for lower and upper limit values.
+
 ### `setLedParams( [params] )`
 
 *Available since v3.2.0*
 
-Customize parameters used to create the [LEDs display effect](#ledbars-boolean).
+Customize parameters used to create the [`ledBars`](#ledbars-boolean) effect.
 
 `params` should be an object with the following structure:
 
@@ -993,16 +1066,16 @@ const params = {
 
 property  | description
 ----------|-------------
-`maxLeds` | maximum desired number of LED elements per analyzer bar
+`maxLeds` | **maximum** desired number of LED elements per analyzer bar
 `spaceV`  | vertical spacing ratio, relative to the LED height (**1** means spacing is the same as the LED height)
-`spaceH`  | **minimum** horizontal spacing ratio, relative to the available width (**0.5** means half of the width is used for spacing and half for the LED); behaves exactly like [barSpace](#barspace-number) (values >= 1 are considered as literal pixel values) and will override it if larger
+`spaceH`  | **minimum** horizontal spacing ratio, relative to the available width for each band, or a literal pixel value if **>= 1**;<br>this behaves exactly like [`barSpace`](#barspace-number) and the largest spacing (resulting from either `barSpace` or `spaceH`) will prevail.
 
 The available canvas height is initially divided by `maxLeds` and vertical spacing is calculated observing the `spaceV` ratio;
 if necessary, the led count is decreased until both the led segment and the vertical spacing are at least 2px tall.
 
 You can try different values in the [fluid demo](https://audiomotion.dev/demo/fluid.html).
 
-**If called with no arguments or any invalid property, disables previously set parameters.**
+**If called with no arguments or any invalid property, clears custom parameters previously set.**
 
 ### `setOptions( [options] )`
 
@@ -1061,12 +1134,12 @@ ERR_UNKNOWN_GRADIENT       | User tried to [select a gradient](#gradient-string)
 
 ## Known Issues
 
-### reflexBright won't work on some browsers {docsify-ignore}
+### reflexBright won't work on some browsers <!-- {docsify-ignore} -->
 
 [`reflexBright`](#reflexbright-number) feature relies on the [`filter`](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/filter) property of the Canvas API,
 which is [currently not supported in some browsers](https://caniuse.com/#feat=mdn-api_canvasrenderingcontext2d_filter) (notably, Opera and Safari).
 
-### alphaBars and fillAlpha won't work with Radial on Firefox {docsify-ignore}
+### 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).
 
@@ -1075,10 +1148,75 @@ On Firefox, [`alphaBars`](#alphaBars-boolean) and [`fillAlpha`](#fillalpha-numbe
 Safari's implementation of Web Audio won't return analyzer data for live streams, as documented in [this bug report](https://bugs.webkit.org/show_bug.cgi?id=195043).
 
 
+## Troubleshooting
+
+Common problems and solutions. Remember to check the browser console for error messages.
+
+### Error message: `Cannot use import statement outside a module` <!-- {docsify-ignore} -->
+
+The `import` statement must be inside a `script` which has the `type="module"` property (and no `type="text/javascript"`), like so:
+
+```html
+  <script type="module">
+    import AudioMotionAnalyzer from 'https://cdn.skypack.dev/audiomotion-analyzer?min';
+
+    // your code here
+  </script>
+```
+
+Or
+
+```html
+  <script src="main.js" type="module"></script>
+```
+
+### Error message: `MediaElementAudioSource outputs zeroes due to CORS access restrictions` <!-- {docsify-ignore} -->
+
+Make sure the media element (`audio` or `video` tag) connected to **audioMotion-analyzer** has the `crossorigin = "anonymous"` property, like so:
+
+```html
+<audio id="myAudio" src="https://example.com/stream" controls crossorigin="anonymous"></audio>
+```
+
+You can also set the `crossOrigin` (mind the uppercase "O") property via JavaScript, like so:
+
+```js
+myAudio.crossOrigin = 'anonymous';
+```
+
+### Sound only plays after the user clicks somewhere on the page. <!-- {docsify-ignore} -->
+
+**audioMotion-analyzer** automatically unlocks the audio context on the first click on the page,
+since browsers' autoplay policy requires audio output to be initiated on user gesture only.
+
+However, if you're using an `audio` or `video` element with the `controls` property, clicks on those native media
+controls can't be detected, 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,
+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:
+
+```html
+<audio id="myAudio" src="track.mp3" crossorigin="anonymous"></audio> <!-- do not add the 'controls' property! -->
+
+<button id="play"> Play </button>
+<button id="stop"> Stop </button>
+```
+
+```js
+const myAudio = document.getElementById('audio');
+
+document.getElementById('play').addEventListener( 'click', () => myAudio.play() );
+document.getElementById('stop').addEventListener( 'click', () => myAudio.pause() );
+```
+
+
 ## References and acknowledgments
 
+* Thanks to my wife, Virginia, for her never-ending love and support! 💞
 * Thanks to [Yuji Koike](http://www.ykcircus.com) for his awesome [Soniq Viewer for iOS](https://itunes.apple.com/us/app/soniq-viewer/id448343005), which inspired me to create **audioMotion**
 * [HTML Canvas Reference @W3Schools](https://www.w3schools.com/tags/ref_canvas.asp)
+* [Web Audio API specification](https://webaudio.github.io/web-audio-api/)
 * [Web Audio API documentation @MDN](https://developer.mozilla.org/en-US/docs/Web/API/Web_Audio_API)
 * [What does the FFT data in the Web Audio API correspond to?](https://stackoverflow.com/a/14789992/2370385)
 * [Equations for equal-tempered scale frequencies](http://pages.mtu.edu/~suits/NoteFreqCalcs.html)
@@ -1107,5 +1245,5 @@ And if you're feeling generous, maybe:
 
 ## License
 
-audioMotion-analyzer copyright (c) 2018-2021 [Henrique Avila Vianna](https://henriquevianna.com)<br>
+audioMotion-analyzer copyright (c) 2018-2022 [Henrique Avila Vianna](https://henriquevianna.com)<br>
 Licensed under the [GNU Affero General Public License, version 3 or later](https://www.gnu.org/licenses/agpl.html).

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": "3.6.1",
+  "version": "4.0.0-beta.1",
   "main": "./src/audioMotion-analyzer.js",
   "module": "./src/audioMotion-analyzer.js",
   "types": "./src/index.d.ts",