loudness-worklet 1.5.0 → 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.5.0
+ * @version 1.5.1
  * @author lcweden
  * @license MIT
- * @see https://github.com/lcweden/loudness-audio-worklet-processor.git
- * @date 2025-10-07T13:01:56.024Z
+ * @see https://github.com/lcweden/loudness-worklet.git
+ * @date 2025-11-18T12:38:50.840Z
  */\r
 \r
 class O {
@@ -417,7 +417,7 @@ class X extends AudioWorkletProcessor {
 }
 registerProcessor("loudness-processor", X);
 `, t = "loudness-processor";
-class o extends AudioWorkletNode {
+class h extends AudioWorkletNode {
   constructor(n, s) {
     super(n, t, s);
   }
@@ -425,7 +425,7 @@ class o extends AudioWorkletNode {
     return r(n);
   }
 }
-async function h(e, n) {
+async function o(e, n) {
   return await r(e), new AudioWorkletNode(e, t, n);
 }
 async function r(e) {
@@ -437,6 +437,6 @@ async function r(e) {
   }
 }
 export {
-  o as LoudnessWorkletNode,
-  h as createLoudnessWorklet
+  h as LoudnessWorkletNode,
+  o as createLoudnessWorklet
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "loudness-worklet",
-  "version": "1.5.0",
+  "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,13 +35,13 @@
   ],
   "license": "MIT",
   "author": "lcweden",
-  "homepage": "https://lcweden.github.io/loudness-audio-worklet-processor/",
+  "homepage": "https://lcweden.github.io/loudness-worklet/",
   "repository": {
     "type": "git",
-    "url": "https://github.com/lcweden/loudness-audio-worklet-processor.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",