Changelog.md

Changelog

version 4.5.4 (2026-01-09)

Minor bugfix release

• Fixes peaks not fading out in radial graph mode when fadePeaks enabled;
• Updated dev npm packages to address vulnerability reports;
• Updated the suggested CDN in the Usage section to jsDelivr, which can provide minified versions of both the ESM and UMD modules.

NOTE: If you're using this package from a CDN, make sure to pin the version to v4 (by adding @4 after the package name) to prevent breaking changes when stable v5 is released!

version 4.5.3 (2026-01-05)

Minor bugfix release

• Fixes peaks not being displayed in radial graph mode with radialInvert enabled.

version 4.5.2 (2025-11-21)

Minor bugfix release

• Fixes visual glitches in radial mode, when radialInvert and showPeaks are enabled.

version 4.5.1 (2025-06-02)

Minor bugfix release

• Fixes audio context not being properly started in some cases, e.g., when a click event is programmatically triggered before an actual user click;
• Fixes optional bgColor property in the GradientOptions type definition - thanks jgabriel98 for reporting it (#82);
• Adds a demo file for the UMD module.

version 4.5.0 (2024-05-12)

Added:

• fadePeaks - peaks fade out instead of falling down - thanks @TF3RDL for this idea;
• gravity - customize peak drop acceleration;
• peakFadeTime - customize peak fade-out time;
• peakHoldTime - customize peak hold time;
• UMD module export - allows using the module via require() and provides a global variable for easier usage in the browser - thanks @shahkashani for the suggestion (#71 and #72); see the Usage section for more details.

The new gravity equation restores the original peak drop behavior and decay curve (using the default value) of versions 1.0.0 through 3.4.0. Check out the peak drop analysis tool for more information on the evolution of the equation and to compare different values of gravity.

As usual, you can interact with all the new properties in the fluid demo.

version 4.4.0 (2024-01-26)

Added:

• canvas property in the constructor options to use your own canvas - thanks @orangecoding for the suggestion;
• getOptions() - retrieve all analyzer settings as an options object. Also added a getOptions() button to fluid and multi demos to copy the current settings to the clipboard - thanks @biigpongsatorn for the suggestion;
• radialInvert - render radial spectrum bars towards the center of the screen;
• radius - customize the size of the radial spectrum - thanks @orangecoding for the suggestion.

Changed & improved:

• The constructor can now take the options object as the first argument if you don't need to define the container;
• start has been explicitly marked as a constructor-specific property in the Options object description and will no longer work with setOptions() as of the next major release.

Fixed:

• Bug preventing radial mode from working when set in the constructor options - thanks @lexterror and @ianrothmann for reporting it;
• Reverted an unintended property name change in the object passed to the onCanvasDraw callback, introduced in v4.2.0.

version 4.3.0 (2023-09-29)

Added:

• 'dual-horizontal' option for channelLayout;

Fixed:

• Fixed opacity for reflex effect on dual-combined channel layout.

Improved:

• Improved maxFPS frame rate throttling.

version 4.2.0 (2023-09-07)

Added:

• new stopTracks argument to disconnectInput() - thanks @hookedupjoe (#52);
• destroy() - thanks @lucienimmink for the suggestion;
• maxFPS - set the maximum desired animation frame rate;
• peakLine - show peaks as a continuous line for Graph mode;
• start() and stop() methods.

Fixed:

• Corrected ESM exports in package.json - thanks @cprussin (#54).

Improved:

• Peak hold and decay times and radial spin speed should now remain consistent on any frame rate;
• showPeaks now works for Graph mode in radial view;
• Code quality and documentation improvements - also thanks @Staijn1 for #55.

version 4.1.1 (2023-08-14)

• Fix a rendering bug when roundBars is combined with mirror and radial;
• Add a polyfill for Array.findLastIndex() to restore compatibility with not-so-recent browsers.

version 4.1.0 (2023-07-30)

Added:

• colorMode - additional options for coloring analyzer bars: by bar amplitude (level) or bar position (index);
• roundBars - rounded corner analyzer bars;
• isRoundBars read-only property;
• trueLeds - your LED bars now more vintage than ever!
• New level property for registered gradients

Fixed:

• Avoid drawing the Y-axis scale and unlit LEDs twice, in 'dual-combined' channel layout.

Improved:

• Improved frequency scales labeling (especially for noteLabels) - label sizes were slightly reduced in fullscreen;
• Code cleanup and optimizations.

version 4.0.0 (2023-03-26)

🚨 BREAKING CHANGES:

• Removed deprecated properties:

  • energy - use getEnergy() instead
  • isLedDisplay - use isLedBars instead
  • peakEnergy - use getEnergy('peak') instead
  • showLeds - use ledBars instead

• getBars() now includes an additional freq property for each element, representing the center frequency of the band. In addition, the range of each band has been adjusted so that frequencies that were previously at the lower edge (freqLo) are now located at the center of the band.

• stereo has been DEPRECATED and will be removed in version 5 - use channelLayout instead.

Added:

• ansiBands - use ANSI/IEC preferred frequencies for the octave bands;
• channelLayout - adds option for dual channel combined spectrum, with both channel graphs overlaid;
• frequencyScale - adds linear and perceptual (Bark/Mel) frequency scales;
• gradientLeft and gradientRight - allow to select different gradients for each channel;
• isBandsMode read-only property;
• linearAmplitude - use linear values instead of dB for spectrum amplitudes;
• linearBoost - amplify low energy values when using linear amplitude;
• noteLabels - display musical note labels instead of frequency values on the X-axis;
• weightingFilter - select from five different weighting filters for improved spectrum visualization;
• Two new built-in gradients: orangered and steelblue.

Thank you @jonathan-annett (#28) and @TF3RDL (#30 and #38) for the suggestions that led to the implementation of several of these new features.

Fixed:

• LED peaks showing below zero level when reflexRatio > 0.

Changed and improved:

• Optimized generation of octave bands, with more accurate ranges and center frequencies;
• Frequency labels on the X-axis now show different values depending on the value of ansiBands, to properly match the bands' center frequencies;
• The onCanvasDraw callback is now passed an additional object with timestamp and gradients information;
• The prism and rainbow gradients were recreated using the beautiful 12-bit rainbow palette by Kate Morley - If you need the old colors check this post;
• Custom gradients can now register a single color;
• splitGradient now works for horizontal gradients in radial visualization;
• maxFreq is now capped to half the AudioContext's sample rate (Nyquist frequency);
• Export additional types and interfaces in the TypeScript definition file;
• Code optimizations, minor fixes and clean-up;
• Revised and improved demos and documentation.

version 3.6.1 (2022-12-09)

• Minor update to fix wrong property names in the LedParameters interface in the TS definition file;
• Improved documentation of registerGradient() usage in TypeScript projects (#37).

version 3.6.0 (2021-10-10)

Added:

• alphaBars effect, which is similar to lumiBars but preserves bars' amplitudes and also works on discrete frequencies mode and radial visualization;
• outlineBars effect, which extends the usage of lineWidth and fillAlpha to octave bands modes;
• isAlphaBars and isOutlineBars read-only properties.

Changed:

• showLeds and isLedDisplay have been deprecated in favor of ledBars and isLedBars, for consistent naming of effects.

Fixed:

• getEnergy() would not accept a fractionary initial frequency.

Improved:

• Regenerate the current gradient if/when it is re-registered (#21);
• The fluid demo now shows the status of read-only flags, for better visualization of interactions between different properties.

version 3.5.1 (2021-09-10)

• Removed named tuples from the TS type definitions file, for improved compatibility (#20).

version 3.5.0 (2021-07-15)

Added:

• getBars() method, which provides real-time analyzer data;
• useCanvas property to disable rendering to the canvas - thanks @davay42 for suggesting this feature;
• A tool to view/debug the generated octave bands - see the /tools folder.

Improved:

• Fine-tuned generation of octave bands;
• Improved FFT data interpolation;
• Improved peak rendering when changing visualization modes;
• Added a simple piano keyboard to the test tones section of the "fluid" demo;
• Added search funcionality to the documentation website.

version 3.4.0 (2021-05-29)

Added:

• fsElement constructor option, for easily handling fullscreen on any element.

Fixed and improved:

• Fixed radial analyzer too wide in vertical containers;
• Fixed out of bounds bar in mode 0 (discrete frequencies) with mirror set to -1;
• Improved fullscreen rendering in portrait orientation displays;
• Improved font size adjustment for scale labels and FPS display on vertical containers.

version 3.3.0 (2021-05-03)

Added:

• New horizontal mirroring effect; see mirror property - thanks @lexterror for suggesting this feature.

Improvements:

• colorStops type definition updated for improved compatibility (see #17) - props to @Staijn1.

version 3.2.1 (2021-04-03)

• Fixes an undefined property error.

version 3.2.0 (2021-04-03)

Added:

• getEnergy() method - see it in action on this pen - thanks @Staijn1 for suggesting this feature;
• setLedParams() method, which allows you to customize the look of the LEDs - you can try it in the fluid demo;
• connectSpeakers constructor option - thanks @evoyy for the suggestion;
• connectedTo read only property.

Improvements:

• When passing an AudioNode in the source property of constructor, it's no longer necessary to explicitly provide the audioCtx, as it will be inferred from the source node - thanks @evoyy for this idea;
• Disconnecting the output from the speakers no longer prevents the analyzer from working on Chromium-based browsers;
• Expose the GradientOptions TypeScript interface for user scripts (props to @Staijn1);
• Improved the look of the LEDs effect in very small containers (like in the multi-instance demo), especially when loRes is active;
• Refactored some code for improved legibility, performance and file size (still below 20kB minified! 😎);
• Added compatibility with standardized-audio-context library - thanks @richclingman for reporting this issue.

Changed:

• energy and peakEnergy properties have been deprecated and will be removed in the next major release - use getEnergy() and getEnergy('peak') instead;
• FPS display font size is now scaled relatively to the canvas height;
• pixelRatio is now correctly reported for HiDPI devices with screen height <= 1080px.

version 3.1.0 (2021-02-27)

Added:

• TypeScript definition file (props to @alex-greff).

Improvements:

• Generate only the currently selected gradient on mode/gradient changes.

version 3.0.0 (2020-11-28)

BREAKING CHANGES:

• The analyzer object is no longer exposed - use the new connectInput() method to connect all audio sources and connectOutput() to connect the analyzer output to other nodes;
• audioSource property has been renamed to connectedSources, which now returns an array of all connected audio sources;
• binToFreq() and freqToBin() methods have been removed;
• connectAudio() method has been replaced by connectInput(), which now accepts either an HTML media element or any instance of AudioNode;
• dataArray property is no longer exposed;
• showScale property has been renamed to showScaleX;
• version is now a static property and should always be accessed as AudioMotionAnalyzer.version.

New features:

• Dual channel (stereo) analyzer option;
• Built-in volume control;
• New methods for easy connection/disconnection of input and output nodes:
  • connectInput()
  • disconnectInput()
  • connectOutput()
  • disconnectOutput()
• New properties:
  • isOctaveBands (read only)
  • isLedDisplay (read only)
  • isLumiBars (read only)
  • stereo
  • splitGradient
  • volume

Improvements:

• Automatically unlock/resume the AudioContext on first user click, so you don't need to handle this in your code anymore;
• Improved FFT data interpolation on low frequencies (especially noticeable in 1/12th and 1/24th octave bands);
• Corrected initial amplitude of line / area graph.

Fixed:

• A compatibility issue that could cause reflexRatio not to work in some environments.

version 2.5.0 (2020-10-07)

Improvements:

• Behavior of the onCanvasResize callback is now consistent across different browsers. Changes worth of note:
  1. on fullscreen changes, only a 'fschange' reason will be reported to the callback function - no more redundant 'resize' calls;
  2. the callback function is now executed only when canvas dimensions effectively change from the previous state - for example, setting loRes or width to the same value they already have won't trigger a callback;
• Canvas dimensions are now properly updated whenever the container element is resized, not only on window resize;
• audioSource now returns the first audio source connected via connectAudio() method, if no source was provided during instantiation;
• Size of scale labels on both axes is now scaled relatively to the canvas height;
• Added a new demo with only the minimal code required to use audioMotion-analyzer;
• Demo scripts are now loaded as native ES6 modules and no longer require bundling. See the README file for instructions on running the demos locally.

version 2.4.0 (2020-07-18)

Added:

• New Radial visualization - see radial and spinSpeed properties and try them in the demos! - thanks @inglesuniversal for suggesting this feature;
• showScaleY property for displaying the level (dB) scale on the analyzer's vertical axis;
• energy and peakEnergy read-only properties;
• Known issues section added to the documentation.

Changed:

• setOptions() called with no argument now resets all configuration options to their default values (it used to raise an error);
• The LED effect code has been refactored to improve appearance and compatibility with other (future) effects;
• "Unlit" LEDs are no longer displayed in overlay mode - see the notice in showBgColor documentation;
• Canvas fillStyle and strokeStyle properties are now set with the current gradient before calling the onCanvasDraw callback function;
• Updated all demos with more straightforward access to configuration options.

version 2.3.0 (2020-06-08)

Added:

• binToFreq() and freqToBin() methods;
• reflexBright property, which allows to adjust the brightness of the reflected image.

Changed:

• Reverted the change to reflexAlpha introduced in v2.2.1
• Removed the forced black layer off the reflection background.

version 2.2.1 (2020-05-31)

Changed:

• Improved the Reflex effect in overlay mode - the reflexAlpha property is now used to adjust the opacity of a dark layer applied over the reflection area, which prevents undesired transparency of the reflection itself and creates a consistent effect, whether overlay mode is on or off (reverted in v2.3.0);

• The package source code has been moved from the dist to the src folder.

Fixed:

• Prevent showing leds below the 0 level, when both reflex and overlay are active.

version 2.2.0 (2020-05-19)

Added:

• New overlay and bgAlpha properties allow displaying the analyzer over other contents. Check out the new demo!

Changed:

• Corrected the documentation for the registerGradient() method, which stated the bgColor property was required (it has always been optional).

version 2.1.0 (2020-04-06)

Added:

• Customizable Reflex effect - see reflexRatio and try it in the demo.

version 2.0.0 (2020-03-24)

Added:

• New lineWidth and fillAlpha properties for mode 10 customization, so it can now work as an area graph (default), a line graph or a combination of both;
• New barSpace property for customizable bar spacing in octave bands modes;
• You can now provide an external AudioContext via audioCtx property in the constructor's options, allowing you to share the same context among different instances;
• Custom error codes;
• New version property;

Changed:

• Increased default spacing between bars in octave bands modes - to get the previous look, set barSpace to 1;
• Improved accuracy when positioning the X-axis scale labels in octave bands modes;
• Slightly improved vertical usage of canvas when the LED effect is active (removed the black line at the bottom of the screen);
• Canvas context is now saved before calling the user callback function and restored afterwards, to avoid undesirable changes;
• Several functions were refactored for improved legibility, memory usage and performance;
• Improved documentation and demos;

Fixed:

• The multi-instance demo should now work on browsers other than Firefox (it now uses a shared audio context);
• isFullscreen property now correctly reads false (instead of undefined) when the analyzer is not in fullscreen (potentially breaking change);
• Setting one of the callback functions to undefined with setOptions() now properly unregisters the callback (potentially breaking change);

API breaking changes:

• audioCtx, analyzer, canvas and canvasCtx objects are now read-only (canvasCtx properties may be safely modified while inside the callback for onCanvasDraw);
• frame and time properties are not exposed anymore, as they are intended for internal use only;
• registerGradient() method now enforces the name argument being a non-empty string (throws an error otherwise);
• Errors now return a custom object and some error messages have changed - use the new code property to identify errors in a reliable way.

version 1.2.0 (2019-12-19)

• Improves the look of bars at lower frequencies in octave bands modes (especially 1/12th and 1/24th);
• Minor tweak to the "Rainbow" gradient to make cyan and blue shades a little more balanced.

version 1.1.0 (2019-12-08)

• New Area fill visualization mode (mode: 10), which uses the same full-frequency data of the discrete frequencies mode, but generates a brighter filled shape;
• New Luminance Bars option (lumiBars: <boolean>) for octave bands modes, which displays analyzer bars always at full-height, with varying luminance instead.

version 1.0.1 (2019-10-22)

• Minor cleanup to optimize npm package size.

version 1.0.0 (2019-10-07)

• First stable release.