audiomotion-analyzer 4.1.0 → 4.2.0

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 only 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 my full-featured music player called [**audioMotion**](https://audiomotion.me), but I later decided
+to make the spectrum analyzer available as a self-contained module, so other developers could use it in their own JS 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.
 
@@ -137,6 +137,7 @@ options = {<br>
 &emsp;&emsp;[loRes](#lores-boolean): **false**,<br>
 &emsp;&emsp;[lumiBars](#lumibars-boolean): **false**,<br>
 &emsp;&emsp;[maxDecibels](#maxdecibels-number): **-25**,<br>
+&emsp;&emsp;[maxFPS](#maxfps-number): **0**,<br>
 &emsp;&emsp;[maxFreq](#maxfreq-number): **22000**,<br>
 &emsp;&emsp;[minDecibels](#mindecibels-number): **-85**,<br>
 &emsp;&emsp;[minFreq](#minfreq-number): **20**,<br>
@@ -147,6 +148,7 @@ options = {<br>
 &emsp;&emsp;[onCanvasResize](#oncanvasresize-function): *undefined*,<br>
 &emsp;&emsp;[outlineBars](#outlinebars-boolean): **false**,<br>
 &emsp;&emsp;[overlay](#overlay-boolean): **false**,<br>
+&emsp;&emsp;[peakLine](#peakline-boolean): **false**,<br>
 &emsp;&emsp;[radial](#radial-boolean): **false**,<br>
 &emsp;&emsp;[reflexAlpha](#reflexalpha-number): **0.15**,<br>
 &emsp;&emsp;[reflexBright](#reflexbright-number): **1**,<br>
@@ -219,14 +221,14 @@ After instantiation, [`fsElement`](#fselement-htmlelement-object-read-only) is a
 
 #### `source` *HTMLMediaElement or AudioNode object*
 
-If `source` is specified, connects an [*HTMLMediaElement*](https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement) object (an `<audio>` or `<video>` HTML tag)
-or any instance of [*AudioNode*](https://developer.mozilla.org/en-US/docs/Web/API/AudioNode) to the analyzer.
+If `source` is specified, connects an [*HTMLMediaElement*](https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement) (`<audio>` or `<video>` HTML element)
+or [*AudioNode*](https://developer.mozilla.org/en-US/docs/Web/API/AudioNode) object to the analyzer.
 
 At least one audio source is required for the analyzer to work. You can also connect audio sources after instantiation, using the [`connectInput()`](#connectinput-source-) method.
 
 #### `start` *boolean*
 
-If `start: false` is specified, the analyzer will be created stopped. You can then start it with the [`toggleAnalyzer()`](#toggleanalyzer-boolean-) method.
+If `start: false` is specified, the analyzer will be created stopped. You can then start it with the [`start()`](#start) or [`toggleAnalyzer()`](#toggleanalyzer-boolean-) methods.
 
 Defaults to **true**, so the analyzer will start running right after initialization.
 
@@ -500,6 +502,12 @@ or one of the frequency bands modes, in which case [`lumiBars`](#lumibars-boolea
 
 See also [`isOctaveBands`](#isoctavebands-boolean-read-only).
 
+### `isDestroyed` *boolean* *(Read only)*
+
+*Available since v4.2.0*
+
+***true*** when the object has been destroyed with [`destroy()`](#destroy).
+
 ### `isFullscreen` *boolean* *(Read only)*
 
 ***true*** when the analyzer is being displayed in fullscreen, or ***false*** otherwise.
@@ -508,7 +516,7 @@ See [`toggleFullscreen()`](#togglefullscreen).
 
 ### `isLedBars` *boolean* *(Read only)*
 
-*Available since v3.6.0* (formerly `isLedDisplay`)
+*Available since v3.6.0; formerly `isLedDisplay` (since v3.0.0)*
 
 ***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*.
 
@@ -528,7 +536,7 @@ See [`toggleFullscreen()`](#togglefullscreen).
 
 ***true*** if the analyzer process is running, or *false* if it's stopped.
 
-See [`toggleAnalyzer()`](#toggleanalyzer-boolean-).
+See [`start()`](#start), [`stop()`](#stop) and [`toggleAnalyzer()`](#toggleanalyzer-boolean-).
 
 ### `isOutlineBars` *boolean* *(Read only)*
 
@@ -546,14 +554,16 @@ and [`ledBars`](#ledbars-boolean) and [`lumiBars`](#lumibars-boolean) are both s
 
 ### `ledBars` *boolean*
 
-*Available since v3.6.0* (formerly `showLeds`)
+*Available since v3.6.0; formerly `showLeds` (since v1.0.0)*
 
-*true* to activate the vintage LED bars effect for frequency bands modes (see [`mode`](#mode-number)).
+*true* to activate the LED bars effect for frequency bands modes (see [`mode`](#mode-number)).
 
 This effect can be customized via [`setLedParams()`](#setledparams-params-) method.
 
 For effect priority when combined with other settings, see [`isLedBars`](#isledbars-boolean-read-only).
 
+See also [`trueLeds`](#trueleds-boolean).
+
 Defaults to **false**.
 
 ### `linearAmplitude` *boolean*
@@ -630,6 +640,16 @@ For more info, see [AnalyserNode.minDecibels](https://developer.mozilla.org/en-U
 
 *minDecibels* defaults to **-85** and *maxDecibels* defaults to **-25**.
 
+### `maxFPS` *number*
+
+*Available since v4.2.0*
+
+Sets the maximum desired animation frame rate. This can help reducing CPU usage, especially on high refresh rate monitors.
+
+It must be a number, indicating frames per second. A value of **0** means the animation will run at the highest frame rate possible.
+
+Defaults to **0**.
+
 ### `maxFreq` *number*
 ### `minFreq` *number*
 
@@ -676,7 +696,7 @@ mode | description | notes
 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*
+10 | Graph | *since 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** [`frequencyScale`](#frequencyscale-string), each band represents the *n*th part of an octave; otherwise, a fixed number of bands is used for each mode;
@@ -719,6 +739,14 @@ 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.
 
+### `peakLine` *boolean*
+
+*Available since v4.2.0*
+
+When *true* and [`mode`](#mode-number) is *10* (**Graph**) and [`showPeaks`](#showpeaks-boolean) is *true*, peaks are connected into a continuous line. It has no effect in other modes.
+
+Defaults to **false**.
+
 ### `pixelRatio` *number* *(Read only)*
 
 Current [devicePixelRatio](https://developer.mozilla.org/en-US/docs/Web/API/Window/devicePixelRatio).
@@ -734,9 +762,9 @@ 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 view, [`ledBars`](#ledbars-boolean) and [`lumiBars`](#lumibars-boolean) effects are disabled, and [`showPeaks`](#showpeaks-boolean) has no effect when in **Graph** [`mode`](#mode-number).
+In radial view, [`ledBars`](#ledbars-boolean) and [`lumiBars`](#lumibars-boolean) effects are disabled.
 
-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.
+When [`channelLayout`](#channellayout-string) is set to *'dual-vertical'*, graphs for the right channel are rendered towards the center of the screen.
 
 See also [`spinSpeed`](#spinspeed-number).
 
@@ -825,11 +853,13 @@ and setting `showBgColor` to ***true*** will make the "unlit" LEDs visible inste
 
 ### `showPeaks` *boolean*
 
-*true* to show amplitude peaks for each frequency. Defaults to **true**.
+*true* to show amplitude peaks. Defaults to **true**.
+
+See also [`peakLine`](#peakline-boolean).
 
 ### `showScaleX` *boolean*
 
-*Available since v3.0.0 - this property was named `showScale` in earlier versions*
+*Available since v3.0.0; formerly `showScale` (since v1.0.0)*
 
 *true* to display scale labels on the X axis.
 
@@ -918,7 +948,7 @@ Setting it to *false* in the [**constructor**](#constructor) options also preven
 Please note that the analyzer processing runs regardless of the value of `useCanvas` and any callback defined for [`onCanvasDraw`](#oncanvasdraw-function)
 will still be triggered on every animation frame, so you can use the [`getBars()`](#getbars) method to create your own visualizations.
 
-If you want to completely stop the audio data processing, see [`toggleAnalyzer()`](#toggleanalyzer-boolean-).
+If you want to completely stop the analyzer's data processing, see [`stop()`](#stop).
 
 Defaults to **true**.
 
@@ -1066,7 +1096,7 @@ Connects an [HTMLMediaElement](https://developer.mozilla.org/en-US/docs/Web/API/
 If `source` is an *HTMLMediaElement*, the method returns a [MediaElementAudioSourceNode](https://developer.mozilla.org/en-US/docs/Web/API/MediaElementAudioSourceNode) created
 for that element; if `source` is an *AudioNode* instance, it returns the `source` object itself; if it's neither an [ERR_INVALID_AUDIO_SOURCE](#custom-errors) error is thrown.
 
-See also [`disconnectInput()`](#disconnectinput-node-) and [`connectedSources`](#connectedsources-array-read-only).
+See also [`disconnectInput()`](#disconnectinput-node-stoptracks-) and [`connectedSources`](#connectedsources-array-read-only).
 
 ### `connectOutput( [node] )`
 
@@ -1082,20 +1112,39 @@ See also [`disconnectOutput()`](#disconnectoutput-node-) and [`connectedTo`](#co
 
 ?> If called with no argument, analyzer output is connected to the speakers (the *AudioContext* `destination` node).
 
-### `disconnectInput( [node] )`
+### `destroy()`
 
-*Available since v3.0.0*
+*Available since v4.2.0*
 
-Disconnects audio source nodes previously connected to the analyzer.
+Destroys the **audioMotion-analyzer** instance and release resources. A destroyed analyzer cannot be started again.
+
+This method:
+
++ Stops the analyzer data processing and animation;
++ Disconnects all input and output nodes;
++ Clears event listeners and callback functions;
++ Stops the *AudioContext* created by this instance (won't affect context provided to the [constructor](#constructor) via [`audioCtx`](#audioctx-audiocontext-object) property or an *AudioNode* [`source`](#source-htmlmediaelement-or-audionode-object));
++ Removes the [`canvas`](#canvas-htmlcanvaselement-object-read-only) from the DOM.
+
+See usage example in the [minimal demo](/demo/minimal.html).
 
-`node` may be an *AudioNode* instance or an **array** of such objects.
+See also [`isDestroyed`](#isdestroyed-boolean-read-only).
 
-Please note that if you have connected an `<audio>` or `<video>` element, you should disconnect the respective [MediaElementAudioSourceNode](https://developer.mozilla.org/en-US/docs/Web/API/MediaElementAudioSourceNode)
-created for it.
+### `disconnectInput( [node], [stopTracks] )`
 
-See also [`connectInput()`](#connectinput-source-).
+*Available since v3.0.0; `stopTracks` parameter since v4.2.0*
 
-?> If called with no argument, all connected sources are disconnected.
+Disconnects audio source nodes previously connected to the analyzer.
+
+`node` may be an *AudioNode* instance or an **array** of such objects. If it's **undefined** (or any [*falsy*](https://developer.mozilla.org/en-US/docs/Glossary/Falsy) value),
+**all connected sources are disconnected.**
+
+`stopTracks` is a boolean value; if **true**, permanently stops all audio tracks from any [*MediaStream*](https://developer.mozilla.org/en-US/docs/Web/API/MediaStream)s being
+disconnected, e.g. a microphone. Use it to effectively release the stream if it's no longer needed.
+
+Please note that when you have connected an `<audio>` or `<video>` element, you need to disconnect the respective [MediaElementAudioSourceNode](https://developer.mozilla.org/en-US/docs/Web/API/MediaElementAudioSourceNode)
+created for it. The node reference is returned by [`connectInput()`](#connectinput-source-), or can be obtained from [`connectedSources`](#connectedsources-array-read-only)
+if the element was connected via [`source`](#source-htmlmediaelement-or-audionode-object) constructor option.
 
 ### `disconnectOutput( [node] )`
 
@@ -1244,16 +1293,35 @@ See **[Options object](#options-object)** for object structure and default value
 
 Adjust the analyzer's sensitivity. See [`minDecibels`](#mindecibels-number) and [`maxDecibels`](#maxdecibels-number) properties.
 
-### `toggleAnalyzer( [boolean] )`
+### `start()`
 
-Starts (*true*) or stops (*false*) the analyzer process. If no argument provided, inverts the current status.
+*Available since v4.2.0*
 
-Returns the resulting status.
+Starts the analyzer data processing and animation.
 
 The analyzer is started by default after initialization, unless you specify [`start: false`](#start-boolean) in the [constructor](#constructor) options.
+
+See also [`stop()`](#stop), [`toggleAnalyzer()`](#toggleanalyzer-boolean-) and [`isOn`](#ison-boolean-read-only).
+
+### `stop()`
+
+*Available since v4.2.0*
+
+Stops the analyzer process.
+
 When the analyzer is off, no audio data is processed and no callbacks to [`onCanvasDraw`](#oncanvasdraw-function) will be triggered.
 
-See also [`isOn`](#ison-boolean-read-only) property.
+The analyzer can be resumed with [`start()`](#start) or [`toggleAnalyzer()`](#toggleanalyzer-boolean-).
+
+See also [`destroy()`](#destroy) and [`isOn`](#ison-boolean-read-only).
+
+### `toggleAnalyzer( [boolean] )`
+
+Toggles the analyzer data processing and animation. The boolean argument can be used to force the desired state: *true* to start or *false* to stop the analyzer.
+
+Returns the resulting state.
+
+See also [`start()`](#start), [`stop()`](#stop) and [`isOn`](#ison-boolean-read-only).
 
 ### `toggleFullscreen()`
 
@@ -1341,33 +1409,23 @@ myAudio.crossOrigin = 'anonymous';
 
 ### Sound only plays after the user clicks somewhere on the page. <!-- {docsify-ignore} -->
 
-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.
+Browser autoplay policy dictates that audio output can only be initiated by a user gesture, and this policy is enforced by Web Audio API
+by putting [*AudioContext*](#audioctx-audiocontext-object-read-only) objects into *suspended* mode if they're not created on user action.
 
-**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.
+**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 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:
+Possible solutions are:
 
-```html
-<audio id="myAudio" src="track.mp3" crossorigin="anonymous"></audio> <!-- do not add the 'controls' property! -->
+1. Ensure your users have to click somewhere else before using the native media controls, like a "power on" button;
 
-<button id="play"> Play </button>
-<button id="stop"> Stop </button>
-```
+1. Don't use the native controls at all, and create your own custom play and stop buttons;
 
-```js
-const myAudio = document.getElementById('audio');
-
-document.getElementById('play').addEventListener( 'click', () => myAudio.play() );
-document.getElementById('stop').addEventListener( 'click', () => myAudio.pause() );
-```
+1. Even better, instantiate your **audioMotion-analyzer** object within a function triggered by a user click. This will allow the *AudioContext* to
+be started right away and will also prevent the *"The AudioContext was not allowed to start"* warning message from appearing in the browser console.
 
-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.
+See the [minimal demo](/demo/minimal.html) code for an example.
 
 
 ## References and acknowledgments

package/package.json

@@ -1,12 +1,16 @@
 {
   "name": "audiomotion-analyzer",
   "description": "High-resolution real-time graphic audio spectrum analyzer JavaScript module with no dependencies.",
-  "version": "4.1.0",
+  "version": "4.2.0",
   "main": "./src/audioMotion-analyzer.js",
   "module": "./src/audioMotion-analyzer.js",
   "types": "./src/index.d.ts",
+  "type": "module",
   "exports": {
-    ".": "./src/audioMotion-analyzer.js"
+    ".": {
+      "import": "./src/audioMotion-analyzer.js",
+      "types": "./src/index.d.ts"
+    }
   },
   "files": [
     "src/**/*.js",