audiomotion-analyzer 4.5.0-beta.1 → 4.5.1

package/README.md

@@ -3,7 +3,7 @@
 
 **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 my full-featured music player called [**audioMotion**](https://audiomotion.me), but I later decided
+It was originally conceived as part of my full-featured media player called [**audioMotion**](https://audiomotion.app), 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.
@@ -35,7 +35,7 @@ What users are saying:
 + 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
++ Zero-dependency native ES6+ module (ESM), \~30kB minified
 
 ## Online demos
 
@@ -57,7 +57,27 @@ What users are saying:
 
 ## Usage
 
-### Native ES6 module (ESM)
+### Node.js project
+
+Install via npm:
+
+```console
+npm i audiomotion-analyzer
+```
+
+Use ES6 import:
+
+```js
+import AudioMotionAnalyzer from 'audiomotion-analyzer';
+```
+
+Or CommonJS require:
+
+```js
+const { AudioMotionAnalyzer } = require('audioMotion-analyzer');
+```
+
+### In the browser using native ES6 module (ESM)
 
 Load from Skypack CDN:
 
@@ -70,19 +90,17 @@ Load from Skypack CDN:
 
 Or download the [latest version](https://github.com/hvianna/audioMotion-analyzer/releases) and copy the `audioMotion-analyzer.js` file from the `src/` folder into your project folder.
 
-### npm project
+### In the browser using global variable
 
-Install as a dependency:
+Load from Unpkg CDN:
 
-```console
-$ npm i audiomotion-analyzer
+```html
+<script src="https://unpkg.com/audiomotion-analyzer/dist"></script>
+<script>
+  // available as AudioMotionAnalyzer global
+</script>
 ```
 
-Use ES6 import syntax:
-
-```js
-import AudioMotionAnalyzer from 'audiomotion-analyzer';
-```
 
 ## Constructor
 
@@ -133,6 +151,7 @@ options = {<br>
 &emsp;&emsp;[channelLayout](#channellayout-string): **'single'**,<br>
 &emsp;&emsp;[colorMode](#colormode-string): **'gradient'**,<br>
 &emsp;&emsp;[connectSpeakers](#connectspeakers-boolean): **true**, // constructor only<br>
+&emsp;&emsp;[fadePeaks](#fadepeaks-boolean): **false**,<br>
 &emsp;&emsp;[fftSize](#fftsize-number): **8192**,<br>
 &emsp;&emsp;[fillAlpha](#fillalpha-number): **1**,<br>
 &emsp;&emsp;[frequencyScale](#frequencyscale-string): **'log'**,<br>
@@ -140,7 +159,7 @@ options = {<br>
 &emsp;&emsp;[gradient](#gradient-string): **'classic'**,<br>
 &emsp;&emsp;[gradientLeft](#gradientleft-string): *undefined*,<br>
 &emsp;&emsp;[gradientRight](#gradientright-string): *undefined*,<br>
-&emsp;&emsp;[gravity](#gravity-number): **1**,<br>
+&emsp;&emsp;[gravity](#gravity-number): **3.8**,<br>
 &emsp;&emsp;[height](#height-number): *undefined*,<br>
 &emsp;&emsp;[ledBars](#ledbars-boolean): **false**,<br>
 &emsp;&emsp;[linearAmplitude](#linearamplitude-boolean): **false**,<br>
@@ -160,6 +179,8 @@ 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;[peakFadeTime](#peakfadetime-number): **750**,<br>
+&emsp;&emsp;[peakHoldTime](#peakholdtime-number): **500**,<br>
 &emsp;&emsp;[peakLine](#peakline-boolean): **false**,<br>
 &emsp;&emsp;[radial](#radial-boolean): **false**,<br>
 &emsp;&emsp;[radialInvert](#radialinvert-boolean): **false**,<br>
@@ -401,6 +422,18 @@ By default, **audioMotion-analyzer** is connected to the *AudioContext* `destina
 
 See also [`connectOutput()`](#connectoutput-node-).
 
+### `fadePeaks` *boolean*
+
+*Available since v4.5.0*
+
+When *true*, peaks fade out instead of falling down. It has no effect when [`peakLine`](#peakline-boolean) is active.
+
+Fade time can be customized via [`peakFadeTime`](#peakfadetime-number).
+
+See also [`peakHoldTime`](#peakholdtime-number) and [`showPeaks`](#showpeaks-boolean).
+
+Defaults to **false**.
+
 ### `fftSize` *number*
 
 Number of samples used for the FFT performed by the [*AnalyzerNode*](https://developer.mozilla.org/en-US/docs/Web/API/AnalyserNode).
@@ -503,11 +536,17 @@ See also [`gradient`](#gradient-string) and [`splitGradient`](#splitgradient-boo
 
 *Available since v4.5.0*
 
-Controls the acceleration of [peaks](#showpeaks-boolean) falling down.
+Customize the acceleration of falling peaks.
 
-It must be a number greater than zero. Invalid values are ignored and no error is thrown.
+It must be a number **greater than zero,** representing _thousands of pixels per second squared_. Invalid values are ignored and no error is thrown.
 
-Defaults to **1**.
+With the default value and analyzer height of 1080px, a peak at maximum amplitude takes approximately 750ms to fall to zero.
+
+You can use the [peak drop analysis tool](/tools/peak-drop.html) to see the decay curve for different values of gravity.
+
+See also [`peakHoldTime`](#peakholdtime-number) and [`showPeaks`](#showpeaks-boolean).
+
+Defaults to **3.8**.
 
 ### `height` *number*
 ### `width` *number*
@@ -779,6 +818,30 @@ 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.
 
+### `peakFadeTime` *number*
+
+*Available since v4.5.0*
+
+Time in milliseconds for peaks to completely fade out, when [`fadePeaks`](#fadepeaks-boolean) is active.
+
+It must be a number greater than or equal to zero. Invalid values are ignored and no error is thrown.
+
+See also [`peakHoldTime`](#peakholdtime-number) and [`showPeaks`](#showpeaks-boolean).
+
+Defaults to **750**.
+
+### `peakHoldTime` *number*
+
+*Available since v4.5.0*
+
+Time in milliseconds for peaks to hold their value before they begin to fall or fade.
+
+It must be a number greater than or equal to zero. Invalid values are ignored and no error is thrown.
+
+See also [`fadePeaks`](#fadepeaks-boolean), [`gravity`](#gravity-number), [`peakFadeTime`](#peakfadetime-number) and [`showPeaks`](#showpeaks-boolean).
+
+Defaults to **500**.
+
 ### `peakLine` *boolean*
 
 *Available since v4.2.0*
@@ -919,7 +982,7 @@ and setting `showBgColor` to ***true*** will make the "unlit" LEDs visible inste
 
 *true* to show amplitude peaks.
 
-See also [`gravity`](#gravity-number) and [`peakLine`](#peakline-boolean).
+See also [`gravity`](#gravity-number), [`peakFadeTime`](#peakfadetime-number), [`peakHoldTime`](#peakholdtime-number) and [`peakLine`](#peakline-boolean).
 
 Defaults to **true**.
 
@@ -1551,5 +1614,5 @@ And if you're feeling generous, maybe:
 
 ## License
 
-audioMotion-analyzer copyright (c) 2018-2024 [Henrique Avila Vianna](https://henriquevianna.com)<br>
+audioMotion-analyzer copyright (c) 2018-2025 [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/dist/index.js

@@ -21,12 +21,12 @@
    * audioMotion-analyzer
    * High-resolution real-time graphic audio spectrum analyzer JS module
    *
-   * @version 4.5.0-beta.1
+   * @version 4.5.1
    * @author  Henrique Avila Vianna <hvianna@gmail.com> <https://henriquevianna.com>
    * @license AGPL-3.0-or-later
    */
 
-  const VERSION = '4.5.0-beta.1';
+  const VERSION = '4.5.1';
 
   // internal constants
   const PI = Math.PI,
@@ -104,11 +104,12 @@
     bgAlpha: 0.7,
     channelLayout: CHANNEL_SINGLE,
     colorMode: COLOR_GRADIENT,
+    fadePeaks: false,
     fftSize: 8192,
     fillAlpha: 1,
     frequencyScale: SCALE_LOG,
     gradient: GRADIENTS[0][0],
-    gravity: 1,
+    gravity: 3.8,
     height: undefined,
     ledBars: false,
     linearAmplitude: false,
@@ -126,6 +127,8 @@
     noteLabels: false,
     outlineBars: false,
     overlay: false,
+    peakFadeTime: 750,
+    peakHoldTime: 500,
     peakLine: false,
     radial: false,
     radialInvert: false,
@@ -366,8 +369,7 @@
 
       // Resume audio context if in suspended state (browsers' autoplay policy)
       const unlockContext = () => {
-        if (audioCtx.state == 'suspended') audioCtx.resume();
-        window.removeEventListener(EVENT_CLICK, unlockContext);
+        if (audioCtx.state == 'suspended') audioCtx.resume().then(() => window.removeEventListener(EVENT_CLICK, unlockContext));
       };
       window.addEventListener(EVENT_CLICK, unlockContext);
 
@@ -443,6 +445,12 @@
     set colorMode(value) {
       this._colorMode = validateFromList(value, [COLOR_GRADIENT, COLOR_BAR_INDEX, COLOR_BAR_LEVEL]);
     }
+    get fadePeaks() {
+      return this._fadePeaks;
+    }
+    set fadePeaks(value) {
+      this._fadePeaks = !!value;
+    }
     get fftSize() {
       return this._analyzer[0].fftSize;
     }
@@ -599,6 +607,18 @@
       this._outlineBars = !!value;
       this._calcBars();
     }
+    get peakFadeTime() {
+      return this._peakFadeTime;
+    }
+    set peakFadeTime(value) {
+      this._peakFadeTime = value >= 0 ? +value : this._peakFadeTime || DEFAULT_SETTINGS.peakFadeTime;
+    }
+    get peakHoldTime() {
+      return this._peakHoldTime;
+    }
+    set peakHoldTime(value) {
+      this._peakHoldTime = +value || 0;
+    }
     get peakLine() {
       return this._peakLine;
     }
@@ -1223,12 +1243,27 @@
        *		unitWidth
        */
 
-      // helper function
-      // bar object: { posX, freq, freqLo, freqHi, binLo, binHi, ratioLo, ratioHi, peak, hold, value }
+      // helper function to add a bar to the bars array
+      // bar object format:
+      // {
+      //	 posX,
+      //   freq,
+      //   freqLo,
+      //   freqHi,
+      //   binLo,
+      //   binHi,
+      //   ratioLo,
+      //   ratioHi,
+      //   peak,    // peak value
+      //   hold,    // peak hold frames (negative value indicates peak falling / fading)
+      //   alpha,   // peak alpha (used by fadePeaks)
+      //   value    // current bar value
+      // }
       const barsPush = args => bars.push({
         ...args,
         peak: [0, 0],
         hold: [0],
+        alpha: [0],
         value: [0]
       });
 
@@ -1720,9 +1755,9 @@
           _colorMode,
           _ctx,
           _energy,
+          _fadePeaks,
           fillAlpha,
           _fps,
-          _gravity,
           _linearAmplitude,
           _lineWidth,
           maxDecibels,
@@ -1738,8 +1773,10 @@
         } = this,
         canvasX = this._scaleX.canvas,
         canvasR = this._scaleR.canvas,
-        holdFrames = _fps >> 1,
-        // number of frames in half a second
+        fadeFrames = _fps * this._peakFadeTime / 1e3,
+        fpsSquared = _fps ** 2,
+        gravity = this._gravity * 1e3,
+        holdFrames = _fps * this._peakHoldTime / 1e3,
         isDualCombined = _chLayout == CHANNEL_COMBINED,
         isDualHorizontal = _chLayout == CHANNEL_HORIZONTAL,
         isDualVertical = _chLayout == CHANNEL_VERTICAL,
@@ -1749,6 +1786,8 @@
         finalX = initialX + analyzerWidth,
         showPeakLine = showPeaks && this._peakLine && _mode == MODE_GRAPH,
         maxBarHeight = _radial ? outerRadius - innerRadius : analyzerHeight,
+        nominalMaxHeight = maxBarHeight / this._pixelRatio,
+        // for consistent gravity on lo-res or hi-dpi
         dbRange = maxDecibels - minDecibels,
         [ledCount, ledSpaceH, ledSpaceV, ledHeight] = this._leds || [];
       if (_energy.val > 0 && _fps > 0) this._spinAngle += this._spinSpeed * TAU / 60 / _fps; // spinSpeed * angle increment per frame for 1 RPM
@@ -1853,7 +1892,8 @@
         _energy.val = newVal;
         if (_energy.peak > 0) {
           _energy.hold--;
-          if (_energy.hold < 0) _energy.peak += _energy.hold / (holdFrames * holdFrames / _gravity);
+          if (_energy.hold < 0) _energy.peak += _energy.hold * gravity / fpsSquared / canvas.height * this._pixelRatio;
+          // TO-DO: replace `canvas.height * this._pixelRatio` with `maxNominalHeight` when implementing dual-channel energy
         }
         if (newVal >= _energy.peak) {
           _energy.peak = newVal;
@@ -2067,23 +2107,32 @@
           currentEnergy += barValue;
 
           // update bar peak
-          if (bar.peak[channel] > 0) {
+          if (bar.peak[channel] > 0 && bar.alpha[channel] > 0) {
             bar.hold[channel]--;
-            // if hold is negative, it becomes the "acceleration" for peak drop
-            if (bar.hold[channel] < 0) bar.peak[channel] += bar.hold[channel] / (holdFrames * holdFrames / _gravity);
+            // if hold is negative, start peak drop or fade out
+            if (bar.hold[channel] < 0) {
+              if (_fadePeaks && !showPeakLine) {
+                const initialAlpha = !isAlpha || isOutline && _lineWidth > 0 ? 1 : isAlpha ? bar.peak[channel] : fillAlpha;
+                bar.alpha[channel] = initialAlpha * (1 + bar.hold[channel] / fadeFrames); // hold is negative, so this is <= 1
+              } else bar.peak[channel] += bar.hold[channel] * gravity / fpsSquared / nominalMaxHeight;
+              // make sure the peak value is reset when using fadePeaks
+              if (bar.alpha[channel] <= 0) bar.peak[channel] = 0;
+            }
           }
 
           // check if it's a new peak for this bar
           if (barValue >= bar.peak[channel]) {
             bar.peak[channel] = barValue;
             bar.hold[channel] = holdFrames;
+            // check whether isAlpha or isOutline are active to start the peak alpha with the proper value
+            bar.alpha[channel] = !isAlpha || isOutline && _lineWidth > 0 ? 1 : isAlpha ? barValue : fillAlpha;
           }
 
           // if not using the canvas, move earlier to the next bar
           if (!useCanvas) continue;
 
           // set opacity for bar effects
-          if (isLumi || isAlpha) _ctx.globalAlpha = barValue;else if (isOutline) _ctx.globalAlpha = fillAlpha;
+          _ctx.globalAlpha = isLumi || isAlpha ? barValue : isOutline ? fillAlpha : 1;
 
           // set fillStyle and strokeStyle for the current bar
           setBarColor(barValue, barIndex);
@@ -2167,23 +2216,28 @@
           }
 
           // Draw peak
-          const peak = bar.peak[channel];
-          if (peak > 0 && showPeaks && !showPeakLine && !isLumi && posX >= initialX && posX < finalX) {
-            // set opacity
-            if (isOutline && _lineWidth > 0) _ctx.globalAlpha = 1;else if (isAlpha) _ctx.globalAlpha = peak;
+          const peakValue = bar.peak[channel],
+            peakAlpha = bar.alpha[channel];
+          if (peakValue > 0 && peakAlpha > 0 && showPeaks && !showPeakLine && !isLumi && posX >= initialX && posX < finalX) {
+            // set opacity for peak
+            if (_fadePeaks) _ctx.globalAlpha = peakAlpha;else if (isOutline && _lineWidth > 0)
+              // when lineWidth == 0 ctx.globalAlpha remains set to `fillAlpha`
+              _ctx.globalAlpha = 1;else if (isAlpha)
+              // isAlpha (alpha based on peak value) supersedes fillAlpha if lineWidth == 0
+              _ctx.globalAlpha = peakValue;
 
             // select the peak color for 'bar-level' colorMode or 'trueLeds'
-            if (_colorMode == COLOR_BAR_LEVEL || isTrueLeds) setBarColor(peak);
+            if (_colorMode == COLOR_BAR_LEVEL || isTrueLeds) setBarColor(peakValue);
 
             // render peak according to current mode / effect
             if (isLeds) {
-              const ledPeak = ledPosY(peak);
+              const ledPeak = ledPosY(peakValue);
               if (ledPeak >= ledSpaceV)
                 // avoid peak below first led
                 _ctx.fillRect(posX, analyzerBottom - ledPeak, width, ledHeight);
-            } else if (!_radial) _ctx.fillRect(posX, analyzerBottom - peak * maxBarHeight, width, 2);else if (_mode != MODE_GRAPH) {
+            } else if (!_radial) _ctx.fillRect(posX, analyzerBottom - peakValue * maxBarHeight, width, 2);else if (_mode != MODE_GRAPH) {
               // radial (peaks for graph mode are done by the peakLine code)
-              const y = peak * maxBarHeight;
+              const y = peakValue * maxBarHeight;
               radialPoly(posX, y, width, !this._radialInvert || isDualVertical || y + innerRadius >= 2 ? -2 : 2);
             }
           }

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.5.0-beta.1",
+  "version": "4.5.1",
   "main": "./dist/index.js",
   "module": "./src/audioMotion-analyzer.js",
   "types": "./src/index.d.ts",
@@ -27,7 +27,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/hvianna/audioMotion-analyzer"
+    "url": "git+https://github.com/hvianna/audioMotion-analyzer.git"
   },
   "keywords": [
     "spectrum analyzer",
@@ -43,9 +43,8 @@
   },
   "homepage": "https://audiomotion.dev",
   "devDependencies": {
-    "@babel/cli": "^7.24.1",
-    "@babel/core": "^7.24.3",
-    "@babel/plugin-transform-modules-umd": "^7.24.1",
-    "@babel/preset-env": "^7.24.3"
+    "@babel/cli": "^7.27.2",
+    "@babel/core": "^7.27.4",
+    "@babel/plugin-transform-modules-umd": "^7.27.1"
   }
 }

package/src/audioMotion-analyzer.js

@@ -2,12 +2,12 @@
  * audioMotion-analyzer
  * High-resolution real-time graphic audio spectrum analyzer JS module
  *
- * @version 4.5.0-beta.1
+ * @version 4.5.1
  * @author  Henrique Avila Vianna <hvianna@gmail.com> <https://henriquevianna.com>
  * @license AGPL-3.0-or-later
  */
 
-const VERSION = '4.5.0-beta.1';
+const VERSION = '4.5.1';
 
 // internal constants
 const PI      = Math.PI,
@@ -88,11 +88,12 @@ const DEFAULT_SETTINGS = {
 	bgAlpha        : 0.7,
 	channelLayout  : CHANNEL_SINGLE,
 	colorMode      : COLOR_GRADIENT,
+	fadePeaks      : false,
 	fftSize        : 8192,
 	fillAlpha      : 1,
 	frequencyScale : SCALE_LOG,
 	gradient       : GRADIENTS[0][0],
-	gravity        : 1,
+	gravity        : 3.8,
 	height         : undefined,
 	ledBars        : false,
 	linearAmplitude: false,
@@ -110,6 +111,8 @@ const DEFAULT_SETTINGS = {
 	noteLabels     : false,
 	outlineBars    : false,
 	overlay        : false,
+	peakFadeTime   : 750,
+	peakHoldTime   : 500,
 	peakLine       : false,
 	radial		   : false,
 	radialInvert   : false,
@@ -365,8 +368,7 @@ class AudioMotionAnalyzer {
 		// Resume audio context if in suspended state (browsers' autoplay policy)
 		const unlockContext = () => {
 			if ( audioCtx.state == 'suspended' )
-				audioCtx.resume();
-			window.removeEventListener( EVENT_CLICK, unlockContext );
+				audioCtx.resume().then( () => window.removeEventListener( EVENT_CLICK, unlockContext ) );
 		}
 		window.addEventListener( EVENT_CLICK, unlockContext );
 
@@ -446,6 +448,13 @@ class AudioMotionAnalyzer {
 		this._colorMode = validateFromList( value, [ COLOR_GRADIENT, COLOR_BAR_INDEX, COLOR_BAR_LEVEL ] );
 	}
 
+	get fadePeaks() {
+		return this._fadePeaks;
+	}
+	set fadePeaks( value ) {
+		this._fadePeaks = !! value;
+	}
+
 	get fftSize() {
 		return this._analyzer[0].fftSize;
 	}
@@ -633,6 +642,20 @@ class AudioMotionAnalyzer {
 		this._calcBars();
 	}
 
+	get peakFadeTime() {
+		return this._peakFadeTime;
+	}
+	set peakFadeTime( value ) {
+		this._peakFadeTime = value >= 0 ? +value : this._peakFadeTime || DEFAULT_SETTINGS.peakFadeTime;
+	}
+
+	get peakHoldTime() {
+		return this._peakHoldTime;
+	}
+	set peakHoldTime( value ) {
+		this._peakHoldTime = +value || 0;
+	}
+
 	get peakLine() {
 		return this._peakLine;
 	}
@@ -1289,9 +1312,23 @@ class AudioMotionAnalyzer {
 		 *		unitWidth
 		 */
 
-		// helper function
-		// bar object: { posX, freq, freqLo, freqHi, binLo, binHi, ratioLo, ratioHi, peak, hold, value }
-		const barsPush = args => bars.push( { ...args, peak: [0,0], hold: [0], value: [0] } );
+		// helper function to add a bar to the bars array
+		// bar object format:
+		// {
+		//	 posX,
+		//   freq,
+		//   freqLo,
+		//   freqHi,
+		//   binLo,
+		//   binHi,
+		//   ratioLo,
+		//   ratioHi,
+		//   peak,    // peak value
+		//   hold,    // peak hold frames (negative value indicates peak falling / fading)
+		//   alpha,   // peak alpha (used by fadePeaks)
+		//   value    // current bar value
+		// }
+		const barsPush = args => bars.push( { ...args, peak: [0,0], hold: [0], alpha: [0], value: [0] } );
 
 		/*
 			A simple interpolation is used to obtain an approximate amplitude value for any given frequency,
@@ -1773,9 +1810,9 @@ class AudioMotionAnalyzer {
 			    _colorMode,
 			    _ctx,
 			    _energy,
+			    _fadePeaks,
 			    fillAlpha,
 			    _fps,
-			    _gravity,
 			    _linearAmplitude,
 			    _lineWidth,
 			    maxDecibels,
@@ -1791,7 +1828,10 @@ class AudioMotionAnalyzer {
 
 			  canvasX          = this._scaleX.canvas,
 			  canvasR          = this._scaleR.canvas,
-			  holdFrames       = _fps >> 1, // number of frames in half a second
+			  fadeFrames       = _fps * this._peakFadeTime / 1e3,
+			  fpsSquared       = _fps ** 2,
+			  gravity          = this._gravity * 1e3,
+			  holdFrames       = _fps * this._peakHoldTime / 1e3,
 			  isDualCombined   = _chLayout == CHANNEL_COMBINED,
 			  isDualHorizontal = _chLayout == CHANNEL_HORIZONTAL,
 			  isDualVertical   = _chLayout == CHANNEL_VERTICAL,
@@ -1801,6 +1841,7 @@ class AudioMotionAnalyzer {
 			  finalX           = initialX + analyzerWidth,
 			  showPeakLine     = showPeaks && this._peakLine && _mode == MODE_GRAPH,
 			  maxBarHeight     = _radial ? outerRadius - innerRadius : analyzerHeight,
+			  nominalMaxHeight = maxBarHeight / this._pixelRatio, // for consistent gravity on lo-res or hi-dpi
 			  dbRange 		   = maxDecibels - minDecibels,
 			  [ ledCount, ledSpaceH, ledSpaceV, ledHeight ] = this._leds || [];
 
@@ -1918,7 +1959,8 @@ class AudioMotionAnalyzer {
 			if ( _energy.peak > 0 ) {
 				_energy.hold--;
 				if ( _energy.hold < 0 )
-					_energy.peak += _energy.hold / ( holdFrames * holdFrames / _gravity );
+					_energy.peak += _energy.hold * gravity / fpsSquared / canvas.height * this._pixelRatio;
+					// TO-DO: replace `canvas.height * this._pixelRatio` with `maxNominalHeight` when implementing dual-channel energy
 			}
 			if ( newVal >= _energy.peak ) {
 				_energy.peak = newVal;
@@ -2146,17 +2188,28 @@ class AudioMotionAnalyzer {
 				currentEnergy += barValue;
 
 				// update bar peak
-				if ( bar.peak[ channel ] > 0 ) {
+				if ( bar.peak[ channel ] > 0 && bar.alpha[ channel ] > 0 ) {
 					bar.hold[ channel ]--;
-					// if hold is negative, it becomes the "acceleration" for peak drop
-					if ( bar.hold[ channel ] < 0 )
-						bar.peak[ channel ] += bar.hold[ channel ] / ( holdFrames * holdFrames / _gravity );
+					// if hold is negative, start peak drop or fade out
+					if ( bar.hold[ channel ] < 0 ) {
+						if ( _fadePeaks && ! showPeakLine ) {
+							const initialAlpha = ! isAlpha || ( isOutline && _lineWidth > 0 ) ? 1 : isAlpha ? bar.peak[ channel ] : fillAlpha;
+							bar.alpha[ channel ] = initialAlpha * ( 1 + bar.hold[ channel ] / fadeFrames ); // hold is negative, so this is <= 1
+						}
+						else
+							bar.peak[ channel ] += bar.hold[ channel ] * gravity / fpsSquared / nominalMaxHeight;
+						// make sure the peak value is reset when using fadePeaks
+						if ( bar.alpha[ channel ] <= 0 )
+							bar.peak[ channel ] = 0;
+					}
 				}
 
 				// check if it's a new peak for this bar
 				if ( barValue >= bar.peak[ channel ] ) {
 					bar.peak[ channel ] = barValue;
 					bar.hold[ channel ] = holdFrames;
+					// check whether isAlpha or isOutline are active to start the peak alpha with the proper value
+					bar.alpha[ channel ] = ! isAlpha || ( isOutline && _lineWidth > 0 ) ? 1 : isAlpha ? barValue : fillAlpha;
 				}
 
 				// if not using the canvas, move earlier to the next bar
@@ -2164,10 +2217,7 @@ class AudioMotionAnalyzer {
 					continue;
 
 				// set opacity for bar effects
-				if ( isLumi || isAlpha )
-					_ctx.globalAlpha = barValue;
-				else if ( isOutline )
-					_ctx.globalAlpha = fillAlpha;
+				_ctx.globalAlpha = ( isLumi || isAlpha ) ? barValue : ( isOutline ) ? fillAlpha : 1;
 
 				// set fillStyle and strokeStyle for the current bar
 				setBarColor( barValue, barIndex );
@@ -2263,28 +2313,32 @@ class AudioMotionAnalyzer {
 				}
 
 				// Draw peak
-				const peak = bar.peak[ channel ];
-				if ( peak > 0 && showPeaks && ! showPeakLine && ! isLumi && posX >= initialX && posX < finalX ) {
-					// set opacity
-					if ( isOutline && _lineWidth > 0 )
+				const peakValue = bar.peak[ channel ],
+					  peakAlpha = bar.alpha[ channel ];
+
+				if ( peakValue > 0 && peakAlpha > 0 && showPeaks && ! showPeakLine && ! isLumi && posX >= initialX && posX < finalX ) {
+					// set opacity for peak
+					if ( _fadePeaks )
+						_ctx.globalAlpha = peakAlpha;
+					else if ( isOutline && _lineWidth > 0 ) // when lineWidth == 0 ctx.globalAlpha remains set to `fillAlpha`
 						_ctx.globalAlpha = 1;
-					else if ( isAlpha )
-						_ctx.globalAlpha = peak;
+					else if ( isAlpha )						// isAlpha (alpha based on peak value) supersedes fillAlpha if lineWidth == 0
+						_ctx.globalAlpha = peakValue;
 
 					// select the peak color for 'bar-level' colorMode or 'trueLeds'
 					if ( _colorMode == COLOR_BAR_LEVEL || isTrueLeds )
-						setBarColor( peak );
+						setBarColor( peakValue );
 
 					// render peak according to current mode / effect
 					if ( isLeds ) {
-						const ledPeak = ledPosY( peak );
+						const ledPeak = ledPosY( peakValue );
 						if ( ledPeak >= ledSpaceV ) // avoid peak below first led
 							_ctx.fillRect( posX, analyzerBottom - ledPeak, width, ledHeight );
 					}
 					else if ( ! _radial )
-						_ctx.fillRect( posX, analyzerBottom - peak * maxBarHeight, width, 2 );
+						_ctx.fillRect( posX, analyzerBottom - peakValue * maxBarHeight, width, 2 );
 					else if ( _mode != MODE_GRAPH ) { // radial (peaks for graph mode are done by the peakLine code)
-						const y = peak * maxBarHeight;
+						const y = peakValue * maxBarHeight;
 						radialPoly( posX, y, width, ! this._radialInvert || isDualVertical || y + innerRadius >= 2 ? -2 : 2 );
 					}
 				}

package/src/index.d.ts

@@ -22,6 +22,7 @@ export interface Options {
   bgAlpha?: number;
   channelLayout?: ChannelLayout;
   colorMode?: ColorMode;
+  fadePeaks?: boolean;
   fftSize?: number;
   fillAlpha?: number;
   frequencyScale?: FrequencyScale;
@@ -48,6 +49,8 @@ export interface Options {
   onCanvasResize?: OnCanvasResizeFunction;
   outlineBars?: boolean;
   overlay?: boolean;
+  peakFadeTime?: number;
+  peakHoldTime?: number;
   peakLine?: boolean;
   radial?: boolean;
   radialInvert?: boolean;
@@ -105,7 +108,7 @@ export type GradientColorStop = string | { pos?: number; color: string; level?:
 export type WeightingFilter = "" | "A" | "B" | "C" | "D" | "468";
 
 export interface GradientOptions {
-  bgColor: string;
+  bgColor?: string;
   dir?: "h";
   colorStops: GradientColorStop[];
 }
@@ -144,6 +147,9 @@ declare class AudioMotionAnalyzer {
   get connectedSources(): AudioNode[];
   get connectedTo(): AudioNode[];
 
+  get fadePeaks(): boolean;
+  set fadePeaks(value: boolean);
+
   get fftSize(): number;
   set fftSize(value: number);
 
@@ -234,6 +240,12 @@ declare class AudioMotionAnalyzer {
 
   public overlay: boolean;
 
+  get peakFadeTime(): number;
+  set peakFadeTime(value: number);
+
+  get peakHoldTime(): number;
+  set peakHoldTime(value: number);
+
   get peakLine(): boolean;
   set peakLine(value: boolean);