audiomotion-analyzer 4.0.0-beta.0 → 4.0.0-beta.2

package/README.md

@@ -28,17 +28,18 @@ What users are saying:
 ## Features
 
 + High-resolution real-time dual channel audio spectrum analyzer
-+ Logarithmic frequency scale with customizable range
-+ 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
++ Logarithmic, linear and perceptual (Bark/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!
 + Fullscreen support, ready for retina / HiDPI displays
 + Zero-dependency native ES6+ module (ESM), \~20kB minified
 
 ## Online demos
 
-[![demo-animation](demo/media/demo.gif)](https://audiomotion.dev/demo/)
+[![demo-animation](img/demo.gif)](https://audiomotion.dev/demo/)
 
 ?> https://audiomotion.dev/demo/
 
@@ -121,11 +122,13 @@ options = {<br>
 &emsp;&emsp;[connectSpeakers](#connectspeakers-boolean): **true**, // constructor only<br>
 &emsp;&emsp;[fftSize](#fftsize-number): **8192**,<br>
 &emsp;&emsp;[fillAlpha](#fillalpha-number): **1**,<br>
+&emsp;&emsp;[frequencyScale](#frequencyscale-string): **'log'**,<br>
 &emsp;&emsp;[fsElement](#fselement-htmlelement-object): *undefined*, // constructor only<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;[linearBoost](#linearboost-number): **1**,<br>
 &emsp;&emsp;[lineWidth](#linewidth-number): **0**,<br>
 &emsp;&emsp;[loRes](#lores-boolean): **false**,<br>
 &emsp;&emsp;[lumiBars](#lumibars-boolean): **false**,<br>
@@ -158,6 +161,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>
 }
 
@@ -280,7 +284,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 **octave bands** [modes](#mode-number).
+Customize the spacing between bars in [bands modes](#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.
 
@@ -340,13 +344,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 **octave bands** modes when [`outlineBars`](#outlinebars-boolean) is *true*.
+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*.
 
 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 octave bands modes, [`alphaBars`](#alphabars-boolean) set to *true* takes precedence over `fillAlpha`.
+Also, for [bands modes](#mode-number), [`alphaBars`](#alphabars-boolean) set to *true* takes precedence over `fillAlpha`.
 
 Defaults to **1**.
 
@@ -356,6 +360,25 @@ Defaults to **1**.
 
 Current frame rate.
 
+### `frequencyScale` *string*
+
+*Available since v4.0.0*
+
+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)
+
+Logarithmic scale is required to visualize proper [octave bands](#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).
+
+Defaults to **'log'**.
+
 ### `fsElement` *HTMLElement object* *(Read only)*
 
 *Available since v3.4.0*
@@ -371,9 +394,9 @@ Canvas dimensions used during fullscreen mode. These take the current pixel rati
 
 ### `gradient` *string*
 
-Currently selected color gradient used for analyzer graphs.
+Name of the color gradient used for analyzer graphs.
 
-It must be the name of a built-in or [registered](#registergradient-name-options-) gradient. Built-in gradients are *'classic'*, *'prism'* and *'rainbow'*.
+It must be a built-in or [registered](#registergradient-name-options-) gradient name. Built-in gradients are *'classic'*, *'prism'* and *'rainbow'*.
 
 Defaults to **'classic'**.
 
@@ -384,7 +407,7 @@ Nominal dimensions of the analyzer.
 
 If one or both of these are `undefined`, the analyzer will try to adjust to the container's width and/or height.
 If the container's width and/or height are 0 (inline elements), a reference size of **640 x 270 pixels** will be used to replace the missing dimension(s).
-This should be considered the minimum dimensions for proper visualization of all available modes with the [LED effect](#ledbars-boolean) on.
+This should be considered the minimum dimensions for proper visualization of all available modes and effects.
 
 You can set both values at once using the [`setCanvasSize()`](#setcanvassize-width-height-) method.
 
@@ -395,7 +418,15 @@ 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 octave 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 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)*
+
+*Available since v4.0.0*
+
+***true*** when [`mode`](#mode-number) is set to one of the bands mode (modes 1 to 8).
+
+See also [`isOctaveBands`](#isoctavebands-boolean-read-only).
 
 ### `isFullscreen` *boolean* *(Read only)*
 
@@ -407,19 +438,19 @@ See [`toggleFullscreen()`](#togglefullscreen).
 
 *Available since v3.6.0* (formerly `isLedDisplay`)
 
-***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*.
+***true*** when LED bars are effectively being displayed, i.e., [`isBandsMode`](#isbandsmode-boolean-read-only) is *true*, [`ledBars`](#ledBars-boolean) is set to *true* and [`radial`](#radial-boolean) is set to *false*.
 
 ### `isLumiBars` *boolean* *(Read only)*
 
 *Available since v3.0.0*
 
-***true*** when luminance bars are effectively being displayed, i.e., [`lumiBars`](#lumibars-boolean) is set to *true* and [`mode`](#mode-number) is set to an octave bands mode and [`radial`](#radial-boolean) is *false*.
+***true*** when luminance bars are effectively being displayed, i.e., [`isBandsMode`](#isbandsmode-boolean-read-only) is *true*, [`lumiBars`](#lumibars-boolean) is set to *true* and [`radial`](#radial-boolean) is set to *false*.
 
 ### `isOctaveBands` *boolean* *(Read only)*
 
 *Available since v3.0.0*
 
-***true*** when [`mode`](#mode-number) is set to one of the octave bands modes.
+***true*** when [`isBandsMode`](#isbandsmode-boolean-read-only) is *true* and [`frequencyScale`](#frequencyscale-string) is set to *'log'*.
 
 ### `isOn` *boolean* *(Read only)*
 
@@ -431,14 +462,14 @@ See [`toggleAnalyzer()`](#toggleanalyzer-boolean-).
 
 *Available since v3.6.0*
 
-***true*** when outlined bars are effectively being displayed, i.e., [`outlineBars`](#outlinebars-boolean) is set to *true*, [`mode`](#mode-number) is set to
-one of the octave bands modes and both [`ledBars`](#ledbars-boolean) and [`lumiBars`](#lumibars-boolean) are set to *false*, or [`radial`](#radial-boolean) is set to *true*.
+***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*.
 
 ### `ledBars` *boolean*
 
 *Available since v3.6.0* (formerly `showLeds`)
 
-*true* to activate a vintage LEDs display effect. Only effective for **octave bands** [modes](#mode-number).
+*true* to activate the vintage LED bars effect for [bands modes](#mode-number).
 
 This effect can be customized via [`setLedParams()`](#setledparams-params-) method.
 
@@ -450,16 +481,29 @@ Defaults to **false**.
 
 *Available since v4.0.0*
 
-When set to *true* uses linear values, instead of decibels, for displaying bars' amplitudes.
+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*
 
-Line width for **Graph** [mode](#mode-number), or outline stroke in **octave bands** modes when [`outlineBars`](#outlinebars-boolean) is *true*.
+Line width for [Graph mode](#mode-number), or outline stroke in [bands modes](#mode-number) when [`outlineBars`](#outlinebars-boolean) is *true*.
 
 For the line to be distinguishable, set also [`fillAlpha`](#fillalpha-number) < 1.
 
@@ -486,7 +530,7 @@ This will prevent the canvas size from changing, when switching the low resoluti
 
 *Available since v1.1.0*
 
-This is only effective for **octave bands** [modes](#mode-number).
+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.
 
@@ -514,7 +558,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.
 
@@ -538,26 +583,26 @@ Defaults to **0**.
 
 ### `mode` *number*
 
-Current visualization mode.
-
-+ **Discrete** mode provides the highest resolution, allowing you to visualize individual frequencies amplitudes as provided by the [FFT](https://en.wikipedia.org/wiki/Fast_Fourier_transform) computation;
-+ **Octave bands** modes display wider vertical bars, each one representing the *n*th part of an octave, based on a [24-tone equal tempered scale](https://en.wikipedia.org/wiki/Quarter_tone);
-+ **Graph** mode uses the discrete data points to draw a continuous line and/or filled area graph (see [`fillAlpha`](#fillalpha-number) and [`lineWidth`](#linewidth-number) properties).
+Visualization mode.
 
 mode | description | notes
-------:|:-------------:|------
+----:|:-----------:|------
 0 | Discrete frequencies |
-1 | 1/24th octave bands |
-2 | 1/12th octave bands |
-3 | 1/8th octave bands |
-4 | 1/6th octave bands |
-5 | 1/4th octave bands |
-6 | 1/3rd octave bands |
-7 | Half octave bands |
-8 | Full octave bands |
+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 |
 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;
++ **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).
+
 Defaults to **0**.
 
 ### `noteLabels` *boolean*
@@ -566,7 +611,7 @@ 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, make sure [`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 all bands will be perfectly aligned with notes frequencies.
 
 Defaults to **false**.
 
@@ -574,7 +619,7 @@ Defaults to **false**.
 
 *Available since v3.6.0*
 
-When *true* and [`mode`](#mode-number) is set to one of the **octave bands** modes, draws outlined bars with customizable [`fillAlpha`](#fillalpha-number) and [`lineWidth`](#linewidth-number).
+When *true* and [`mode`](#mode-number) is set to one of the **bands** modes, analyzer bars are rendered outlined, with customizable [`fillAlpha`](#fillalpha-number) and [`lineWidth`](#linewidth-number).
 
 For effect priority when combined with other settings, see [`isOutlineBars`](#isoutlinebars-boolean-read-only).
 
@@ -735,9 +780,9 @@ When *true*, the gradient will be split between both channels, so each channel w
 
 | splitGradient: *true* | splitGradient: *false* |
 |:--:|:--:|
-| ![split-on](demo/media/splitGradient_on.png) | ![split-off](demo/media/splitGradient_off.png) |
+| ![split-on](img/splitGradient_on.png) | ![split-off](img/splitGradient_off.png) |
 
-This option has no effect in horizontal gradients, or when [`stereo`](#stereo-boolean) is set to *false*.
+This option has no effect on horizontal gradients, or when [`stereo`](#stereo-boolean) is set to *false*.
 
 Defaults to **false**.
 
@@ -783,6 +828,33 @@ Please note that changing the audio element volume directly will affect the ampl
 
 Defaults to **1**.
 
+### `weightingFilter` *string*
+
+*Available since v4.0.0*
+
+[Weighting filter](https://en.wikipedia.org/wiki/Weighting_filter) applied to frequency data for spectrum visualization.
+
+?> Selecting a weighting filter **does NOT** affect the audio output.
+
+Each filter applies a different curve of gain/attenuation to specific frequency ranges, but the general idea is to adjust the
+visualization of frequencies to which the human ear is more or less sensitive.
+
+Refer to the [weighting filters viewer tool](/tools/weighting-filters.html) for response tables and an interactive version of the curves graph seen below.
+
+<img src="img/weigthing-filters-curves.png" class="align-right">
+
+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)*
@@ -925,8 +997,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
@@ -970,7 +1043,8 @@ 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 when setting the [`gradient`](#gradient-string) property. `options` must be an object as shown below:
+`name` must be a non-empty *string* that will be used to select this gradient, via the [`gradient`](#gradient-string) property.
+`options` must be an object as shown below:
 
 ```js
 const options = {
@@ -978,12 +1052,21 @@ const options = {
     dir: 'h',           // add this property to create a horizontal gradient (optional)
     colorStops: [       // list your gradient colors in this array (at least 2 entries are required)
         'red',                      // colors may be defined in any valid CSS format
-        { pos: .6, color: '#ff0' }, // use an object to adjust the position (0 to 1) of a color
+        { pos: .6, color: '#ff0' }, // use an object to adjust the offset (0 to 1) of a colorStop
         'hsl( 120, 100%, 50% )'     // colors may be defined in any valid CSS format
     ]
 }
 
-audioMotion.registerGradient( 'my-grad', options );
+audioMotion.registerGradient( 'myGradient', options );
+```
+
+!> In TypeScript projects make sure to import the `GradientOptions` definition and use it as the type of your object, like so:
+
+```js
+import AudioMotionAnalyzer, { GradientOptions } from 'audiomotion-analyzer'
+
+const options: GradientOptions = {
+	⋮
 ```
 
 Additional information about [gradient color-stops](https://developer.mozilla.org/en-US/docs/Web/API/CanvasGradient/addColorStop).
@@ -996,11 +1079,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:
 
@@ -1014,16 +1099,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, clears custom parameters previously set.**
+?> If called with no arguments or any invalid property, clears custom parameters previously set.
 
 ### `setOptions( [options] )`
 
@@ -1134,15 +1219,16 @@ 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.
+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.
 
-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.
+**audioMotion-analyzer** tries to automatically start its audio context 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,
 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:
+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! -->

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