weq8 Parametric Equaliser

To display the visual equaliser interface, follow these steps:

1. Import the UI module to register the <weq8-ui /> web component.
2. Add the <weq8-ui /> element to your HTML.
3. Assign your WEQ8Runtime instance to the runtime property of the web component element.

// 1. Import the UI module
import "weq8/ui"; // or "https://cdn.skypack.dev/weq8/ui"

// 2. (In HTML) <weq8-ui />

// 3. Connect the runtime to the UI
document.querySelector("weq8-ui").runtime = weq8;

The library does not automatically save state between sessions. To persist settings, subscribe to the filtersChanged event to capture the state object, which can be serialized to JSON. To restore state, pass the saved state object into the WEQ8Runtime constructor.

// Subscribe to changes to save state
weq8.on("filtersChanged", (state) => {
  // 'state' can be serialized to JSON and stored
});

// Restore state on initialization
let weq8 = new WEQ8Runtime(yourAudioCtx, savedState);

You can install the weq8 package using either npm or yarn to add the parametric equaliser to your project.

yarn add weq8
# or
npm install weq8

The WEQ8Runtime class handles all audio processing. To use it, instantiate it with an existing AudioContext, then connect your audio source to the weq8.input and connect weq8.output (or the runtime instance itself) to your destination node.

import { WEQ8Runtime } from "weq8"; // or from "https://cdn.skypack.dev/weq8"

let weq8 = new WEQ8Runtime(yourAudioCtx);
yourAudioSourceNode.connect(weq8.input);
weq8.connect(yourAudioDestinationNode);

You can control the eight filters (indexed 0-7) headlessly using the WEQ8Runtime API. This is useful for custom UIs or non-visual applications. If using only programmatic control, you do not need to import weq8/ui.

// All control methods take the filter number (0-7) as the first argument
weq8.setFilterType(filterNumber, "lowpass12"); 
weq8.toggleBypass(filterNumber, true); // true to bypass, false to (re-)connect
weq8.setFilterFrequency(filterNumber, 1000); // frequency in Hz
weq8.setFilterQ(filterNumber, 1.0); // filter Q
weq8.setFilterGain(filterNumber, 0.0); // gain in dB

When calling setFilterType(filterNumber, type), use the following strings. Types suffixed with 12 use a single BiquadFilterNode, while types suffixed with 24 use two nodes in series for a steeper roll-off.

"lowpass12", "lowpass24",
"highpass12", "highpass24",
"bandpass",
"lowshelf12", "lowshelf24",
"highshelf12", "highshelf24",
"peaking12", "peaking24",
"notch12", "notch24"

The <weq8-ui-filter-hud> is a Lit-based web component that provides a Heads-Up Display (HUD) for controlling individual filter parameters (Type, Frequency, Gain, and Q) within a WEQ8Runtime. It supports both direct numeric input and touch/pointer dragging to adjust values.

To use it, you must provide a runtime instance and the index of the filter you wish to control. You can also specify its initial x and y coordinates.

<!-- Example usage in HTML -->
<weq8-ui-filter-hud 
  runtime="${myRuntimeInstance}" 
  index="0" 
  x="100" 
  y="100">
</weq8-ui-filter-hud

The WEQ8Runtime provides an input and an output AudioNode (specifically GainNodes) to integrate into your Web Audio graph.

• Use runtime.input as the entry point for your audio source.
• Use runtime.connect(node) to connect the runtime's output to another AudioNode.
• Use runtime.disconnect(node) to disconnect the runtime's output from a specific AudioNode.

// Connect source to runtime input
sourceNode.connect(runtime.input);

// Connect runtime output to destination
runtime.connect(audioCtx.destination);

The WEQ8Analyser class provides a utility for visualizing the frequency response of an audio stream using an HTML5 Canvas. It connects to a WEQ8Runtime instance, creates an internal AnalyserNode with an FFT size of 8192, and renders a frequency spectrum visualization that automatically scales to the canvas dimensions.

To use it, instantiate the class with an existing WEQ8Runtime and a target HTMLCanvasElement, then call .analyse() to start the animation loop.

import { WEQ8Runtime } from "../runtime";
import { WEQ8Analyser } from "./ui/WEQ8Analyser";

// Assuming runtime and canvas are already initialized
const analyser = new WEQ8Analyser(runtime, canvasElement);

// Start the visualization loop
analyser.analyse();

// When finished, clean up resources
// analyser.dispose();

The view property of the <weq8-ui> element controls the layout of the interface:

• 'allBands': Displays a table of filter rows (showing Frequency, Gain, and Q) next to the frequency response visualization.
• 'hud': Hides the table and shows a Head-Up Display (HUD) for the currently selected filter directly on the visualization.

Set this property to switch between the detailed parameter view and the streamlined HUD view.

// Setting the view via JavaScript
const ui = document.querySelector('weq8-ui');
ui.view = 'hud';

// Or via HTML attribute
// <weq8-ui view="hud"></weq8-ui>

The WEQ8Runtime class is the main headless audio processing engine. It manages a chain of Biquad filters based on a provided WEQ8Spec. To use it, instantiate it with an existing BaseAudioContext.

Constructor Parameters:

• audioCtx: The BaseAudioContext used for creating audio nodes.
• spec (optional): A WEQ8Spec object defining the filter chain. Defaults to DEFAULT_SPEC.
• supportedFilterTypes (optional): An array of FilterType[] that the runtime should support. Defaults to FILTER_TYPES.

import { WEQ8Runtime } from './weq8/runtime';

const audioCtx = new AudioContext();
const runtime = new WEQ8Runtime(audioCtx);