loudness-worklet 1.4.3 → 1.5.1

package/README.md

@@ -1,13 +1,13 @@
 # Loudness Audio Worklet Processor
 
 [![npm version](https://img.shields.io/npm/v/loudness-worklet.svg)](https://www.npmjs.com/package/loudness-worklet)
-[![license](https://img.shields.io/github/license/lcweden/loudness-audio-worklet-processor.svg)](LICENSE)
+[![license](https://img.shields.io/github/license/lcweden/loudness-worklet.svg)](LICENSE)
 
 A loudness meter for the `Web Audio API`, based on the [ITU-R BS.1770-5](https://www.itu.int/rec/R-REC-BS.1770) standard and implemented as an AudioWorkletProcessor.
 
-[![screenshot](https://github.com/lcweden/loudness-audio-worklet-processor/blob/main/public/screenshots/meter.png)](https://lcweden.github.io/loudness-audio-worklet-processor/)
+[![screenshot](https://github.com/lcweden/loudness-worklet/blob/main/public/screenshots/meter.png)](https://lcweden.github.io/loudness-worklet/)
 
-<p align="center"><a href="https://lcweden.github.io/loudness-audio-worklet-processor/">Demo</a></p>
+<p align="center"><a href="https://lcweden.github.io/loudness-worklet/">Demo</a></p>
 
 ## Features
 
@@ -23,17 +23,19 @@ A loudness meter for the `Web Audio API`, based on the [ITU-R BS.1770-5](https:/
 Import directly in your code:
 
 ```javascript
-const module = new URL("https://lcweden.github.io/loudness-audio-worklet-processor/loudness.worklet.js");
-audioContext.audioWorklet.addModule(module);
+const module = "https://lcweden.github.io/loudness-worklet/loudness.worklet.js";
+await audioContext.audioWorklet.addModule(module);
+const worklet = new AudioWorkletNode(audioContext, "loudness-processor");
 ```
 
 ### Download
 
-1. Download the pre-built file: [loudness.worklet.js](https://lcweden.github.io/loudness-audio-worklet-processor/loudness.worklet.js).
+1. Download the pre-built file: [loudness.worklet.js](https://lcweden.github.io/loudness-worklet/loudness.worklet.js).
 2. Place `loudness.worklet.js` in your project directory (e.g., `/public/`).
 
 ```javascript
-audioContext.audioWorklet.addModule("loudness.worklet.js");
+await audioContext.audioWorklet.addModule("loudness.worklet.js");
+const worklet = new AudioWorkletNode(audioContext, "loudness-processor");
 ```
 
 ### NPM
@@ -49,23 +51,61 @@ Use helper functions to create and load the worklet:
 ```javascript
 import { createLoudnessWorklet, LoudnessWorkletNode } from "loudness-worklet";
 
-const worklet = await createLoudnessWorklet(audioContext, {
-  processorOptions: {
-    interval: 0.1,
-    capacity: 600
-  }
-});
+const worklet = await createLoudnessWorklet(audioContext);
 
 // or
 
 await LoudnessWorkletNode.loadModule(audioContext);
+const worklet = new LoudnessWorkletNode(audioContext);
+```
 
-const worklet = new LoudnessWorkletNode(audioContext, {
-  processorOptions: {
-    interval: 0.1,
-    capacity: 600
-  }
-});
+## Concepts
+
+### Contexts
+
+Provide the execution environment for audio processing.
+
+#### AudioContext
+
+`AudioContext` is used for real-time audio processing, such as live audio input from a microphone or media stream.
+
+#### OfflineAudioContext
+
+`OfflineAudioContext` is used for processing audio data offline, allowing for rendering and analysis without requiring real-time playback.
+
+### Nodes
+
+Nodes are the building blocks of an audio graph, representing audio sources, processing modules, and destinations. The following nodes are commonly used as a source input:
+
+#### AudioBufferSourceNode
+
+`AudioBufferSourceNode` is used to play audio data stored in an `AudioBuffer`, typically for pre-recorded audio files.
+
+```javascript
+const audioContext = new AudioContext();
+const arrayBuffer = await file.arrayBuffer();
+const audioBuffer = await audioContext.decodeAudioData(arrayBuffer);
+const bufferSource = new AudioBufferSourceNode(audioContext, { buffer: audioBuffer });
+```
+
+#### MediaStreamAudioSourceNode
+
+`MediaStreamAudioSourceNode` is used to play audio from a `MediaStream`, such as a live microphone input or a video element.
+
+```javascript
+const audioContext = new AudioContext();
+const mediaStream = await navigator.mediaDevices.getUserMedia({ audio: true });
+const mediaStreamSource = new MediaStreamAudioSourceNode(audioContext, { mediaStream });
+```
+
+#### MediaElementAudioSourceNode
+
+`MediaElementAudioSourceNode` is used to play audio from an HTML `<audio>` or `<video>` element.
+
+```javascript
+const audioContext = new AudioContext();
+const mediaElement = document.querySelector("audio");
+const elementSource = new MediaElementAudioSourceNode(audioContext, { mediaElement });
 ```
 
 ## Quick Start
@@ -75,13 +115,13 @@ const worklet = new LoudnessWorkletNode(audioContext, {
 This example shows the easiest way to get started with the Loudness Audio Worklet Processor.
 
 ```html
-<!doctype html>
+<!DOCTYPE html>
 <html>
   <body>
     <button>Share Screen</button>
     <pre></pre>
     <script>
-      const script = "https://lcweden.github.io/loudness-audio-worklet-processor/loudness.worklet.js";
+      const module = "https://lcweden.github.io/loudness-worklet/loudness.worklet.js";
       const button = document.querySelector("button");
       const pre = document.querySelector("pre");
 
@@ -91,15 +131,15 @@ This example shows the easiest way to get started with the Loudness Audio Workle
         const context = new AudioContext();
 
         // Load the loudness worklet processor
-        await context.audioWorklet.addModule(script);
+        await context.audioWorklet.addModule(module);
 
         // Create the audio node from the stream
         const source = new MediaStreamAudioSourceNode(context, { mediaStream });
         // Create the loudness worklet node
         const worklet = new AudioWorkletNode(context, "loudness-processor", {
           processorOptions: {
-            interval: 0.1,
-            capacity: 600 // it means 1 minute of history can be stored
+            interval: 0.1, // every 0.1s a message will be sent
+            capacity: 600 // 1 minute of history can be stored
           }
         });
 
@@ -117,65 +157,53 @@ This example shows the easiest way to get started with the Loudness Audio Workle
 
 ### File-based measurement
 
-Suppose you already have an audio file (e.g., from an input[type="file"]):
+You can measure the loudness of audio files using `OfflineAudioContext`.
 
 ```javascript
-const arrayBuffer = await file.arrayBuffer();
-const audioBuffer = await new AudioContext().decodeAudioData(arrayBuffer);
+import { LoudnessWorkletNode } from "loudness-worklet";
 
-const { numberOfChannels, length, sampleRate } = audioBuffer;
-const context = new OfflineAudioContext(numberOfChannels, length, sampleRate);
-
-await context.audioWorklet.addModule("loudness.worklet.js");
-
-const source = new AudioBufferSourceNode(context, { buffer: audioBuffer });
-const worklet = new AudioWorkletNode(context, "loudness-processor");
-
-// Or using the helper function
-//
-// import { createLoudnessWorklet } from "loudness-worklet";
-//
-// const worklet = await createLoudnessWorklet(audioContext, {
-//   processorOptions: {
-//     interval: 0.1,
-//     capacity: 600
-//    }
-//  });
-
-worklet.port.onmessage = (event) => {
-  console.log("Loudness Data:", event.data);
-};
+const input = document.querySelector("input");
+
+input.addEventListener("change", async (event) => {
+  const file = event.target.files[0];
+  const arrayBuffer = await file.arrayBuffer();
+  const audioBuffer = await new AudioContext().decodeAudioData(arrayBuffer);
+  const { numberOfChannels, length, sampleRate } = audioBuffer;
+  const context = new OfflineAudioContext(numberOfChannels, length, sampleRate);
+
+  await LoudnessWorkletNode.loadModule(context);
+
+  const source = new AudioBufferSourceNode(context, { buffer: audioBuffer });
+  const worklet = new LoudnessWorkletNode(context);
 
-source.connect(worklet).connect(context.destination);
-source.start();
+  worklet.port.onmessage = (event) => console.log("Loudness Data:", event.data);
 
-context.startRendering();
+  source.connect(worklet).connect(context.destination);
+  source.start();
+
+  await context.startRendering();
+});
 ```
 
 ### Live-based measurement
 
-Supports `MediaStream` or `MediaElement` sources:
+Supports all kinds of audio input.
 
 ```javascript
-const context = new AudioContext({ sampleRate: 48000 });
+import { createLoudnessWorklet } from "loudness-worklet";
 
-await context.audioWorklet.addModule("loudness.worklet.js");
-
-const audioTrack = mediaStream.getAudioTracks()[0];
-const { channelCount } = audioTrack.getSettings();
-
-const source = new MediaStreamAudioSourceNode(context, { mediaStream });
-const worklet = new AudioWorkletNode(context, "loudness-processor", {
-  processorOptions: {
-    capacity: 600 // Seconds of history to keep, prevent memory overflow
-  }
+const mediaStream = await navigator.mediaDevices.getUserMedia({ audio: true });
+const context = new AudioContext({ sampleRate: 48000 });
+const source = context.createMediaStreamSource(mediaStream);
+const worklet = await createLoudnessWorklet(context, {
+  processorOptions: { interval: 1, capacity: 600 }
 });
 
-worklet.port.onmessage = (event) => {
-  console.log("Loudness Data:", event.data);
-};
+worklet.port.onmessage = (event) => console.log("Loudness Data:", event.data);
+source.connect(worklet);
 
-source.connect(worklet).connect(context.destination);
+// worklet.connect(context.destination);
+// Optionally connect to destination for monitoring (echo)
 ```
 
 ## API
@@ -196,6 +224,8 @@ The `AudioWorkletNode` constructor accepts the following options:
 
 #### Example
 
+Most of the time, you only need to set `processorOptions`.
+
 ```javascript
 const { numberOfChannels, length, sampleRate } = audioBuffer;
 const worklet = new AudioWorkletNode(context, "loudness-processor", {

package/dist/index.js

@@ -2,11 +2,11 @@ const i = `/**
  * A lightweight and efficient AudioWorklet for real-time loudness measurement in the browser, compliant with the ITU-R BS.1770-5 standard.
  *
  * @file loudness.worklet.js
- * @version 1.4.3
+ * @version 1.5.1
  * @author lcweden
  * @license MIT
- * @see git+https://github.com/lcweden/loudness-audio-worklet-processor.git
- * @date 2025-09-25T18:58:20.105Z
+ * @see https://github.com/lcweden/loudness-worklet.git
+ * @date 2025-11-18T12:38:50.840Z
  */\r
 \r
 class O {
@@ -35,12 +35,14 @@ class O {
    * Sets new filter coefficients.
    * @param { number[] } a - Feedback coefficients [a1, a2]
    * @param { number[] } b - Feedforward coefficients [b0, b1, b2]
+   * @returns { void }
    */
   set(e, r) {
     this.#t.set((e.length = 2, e)), this.#e.set((r.length = 3, r));
   }
   /**
    * Resets the filter state.
+   * @returns { void }
    */
   reset() {
     this.#s.fill(0), this.#r.fill(0);
@@ -52,22 +54,45 @@ class d {
   #s = 0;
   #r = 0;
   #n = 0;
+  /**
+   * Creates a new CircularBuffer with given capacity.
+   * @param { number } capacity - The maximum number of items the buffer can hold.
+   */
   constructor(e) {
     this.#e = e || 0, this.#t = new Array(e);
   }
+  /**
+   * Adds an item to the buffer.
+   * @param item - The item to add to the buffer.
+   * @returns { void }
+   */
   push(e) {
     this.#t[this.#r] = e, this.isFull() ? this.#s = (this.#s + 1) % this.#e : this.#n++, this.#r = (this.#r + 1) % this.#e;
   }
+  /**
+   * Removes and returns the oldest item from the buffer.
+   * @returns { T | undefined }
+   */
   pop() {
     if (this.isEmpty())
       return;
     const e = this.#t[this.#s];
     return this.#s = (this.#s + 1) % this.#e, this.#n--, e;
   }
+  /**
+   * Returns the oldest item from the buffer without removing it.
+   * @returns { T | undefined }
+   */
   peek() {
     if (!this.isEmpty())
       return this.#t[this.#s];
   }
+  /**
+   * Returns a slice of the buffer contents.
+   * @param { number } start - The starting index of the slice (inclusive).
+   * @param { number } end - The ending index of the slice (exclusive).
+   * @returns { T[] }
+   */
   slice(e = 0, r = this.#n) {
     if (e < 0 && (e = 0), r > this.#n && (r = this.#n), e >= r)
       return [];
@@ -78,18 +103,29 @@ class d {
     }
     return n;
   }
+  /**
+   * Checks if the buffer is empty.
+   * @returns { boolean }
+   */
   isEmpty() {
     return this.#n === 0;
   }
+  /**
+   * Checks if the buffer is full.
+   * @returns { boolean }
+   */
   isFull() {
     return this.#n === this.#e;
   }
+  /** @type { number } */
   get length() {
     return this.#n;
   }
+  /** @type { number } */
   get capacity() {
     return this.#e;
   }
+  /** @type { IterableIterator<T> } */
   *[Symbol.iterator]() {
     for (let e = 0; e < this.#n; e++) {
       const r = (this.#s + e) % this.#e;
@@ -209,6 +245,10 @@ const L = {
 class F {
   #t;
   #e;
+  /**
+   * Creates an instance of the filter.
+   * @param coefficients - The filter coefficients.
+   */
   constructor(e) {
     this.#t = e, this.#e = Array(e.length).fill(0);
   }
@@ -224,6 +264,10 @@ class F {
       return n;
     }
   }
+  /**
+   * Resets the filter state.
+   * @returns { void }
+   */
   reset() {
     this.#e.fill(0);
   }
@@ -374,22 +418,22 @@ class X extends AudioWorkletProcessor {
 registerProcessor("loudness-processor", X);
 `, t = "loudness-processor";
 class h extends AudioWorkletNode {
-  constructor(n, e) {
-    super(n, t, e);
+  constructor(n, s) {
+    super(n, t, s);
   }
   static async loadModule(n) {
     return r(n);
   }
 }
-async function o(s, n) {
-  return await r(s), new AudioWorkletNode(s, t, n);
+async function o(e, n) {
+  return await r(e), new AudioWorkletNode(e, t, n);
 }
-async function r(s) {
-  const n = new Blob([i], { type: "application/javascript" }), e = URL.createObjectURL(n);
+async function r(e) {
+  const n = new Blob([i], { type: "application/javascript" }), s = URL.createObjectURL(n);
   try {
-    await s.audioWorklet.addModule(e);
+    await e.audioWorklet.addModule(s);
   } finally {
-    URL.revokeObjectURL(e);
+    URL.revokeObjectURL(s);
   }
 }
 export {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "loudness-worklet",
-  "version": "1.4.3",
+  "version": "1.5.1",
   "description": "A lightweight and efficient AudioWorklet for real-time loudness measurement in the browser, compliant with the ITU-R BS.1770-5 standard.",
   "keywords": [
     "web-audio",
@@ -35,12 +35,13 @@
   ],
   "license": "MIT",
   "author": "lcweden",
-  "homepage": "https://lcweden.github.io/loudness-audio-worklet-processor/",
+  "homepage": "https://lcweden.github.io/loudness-worklet/",
   "repository": {
-    "url": "git+https://github.com/lcweden/loudness-audio-worklet-processor.git"
+    "type": "git",
+    "url": "https://github.com/lcweden/loudness-worklet.git"
   },
   "bugs": {
-    "url": "https://github.com/lcweden/loudness-audio-worklet-processor/issues"
+    "url": "https://github.com/lcweden/loudness-worklet/issues"
   },
   "scripts": {
     "dev": "vite --mode dev",