@sv443-network/userutils 1.2.0 → 2.0.1

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # @sv443-network/userutils
 
+## 2.0.1
+
+### Patch Changes
+
+- 63af1a7: Change default limiter options to be more balanced
+
+## 2.0.0
+
+### Major Changes
+
+- b53a946: Added compression to `amplifyMedia()` to prevent audio clipping and distortion and modified return type accordingly:
+  - Renamed: `amplify()` to `setGain()` and `getAmpLevel()` to `getGain()`
+  - Added properties: `enable()`, `disable()`, `setLimiterOptions()` and `limiterNode`
+  - Other changes: Amplification is no longer enabled automatically, `enable()` must now be called manually after initializing
+
 ## 1.2.0
 
 ### Minor Changes

package/README.md

@@ -478,47 +478,98 @@ interceptWindowEvent("beforeunload", (event) => {
 ### amplifyMedia()
 Usage:  
 ```ts
-amplifyMedia(mediaElement: HTMLMediaElement, multiplier?: number): AmplifyMediaResult
+amplifyMedia(mediaElement: HTMLMediaElement, initialMultiplier?: number): AmplifyMediaResult
 ```
   
 Amplifies the gain of a media element (like `<audio>` or `<video>`) by a given multiplier (defaults to 1.0).  
 This is how you can increase the volume of a media element beyond the default maximum volume of 1.0 or 100%.  
-Make sure to limit the multiplier to a reasonable value ([clamp()](#clamp) is good for this), as it may cause clipping or bleeding eardrums.  
+Make sure to limit the multiplier to a reasonable value ([clamp()](#clamp) is good for this), as it may cause bleeding eardrums.  
+  
+This is the processing workflow applied to the media element:  
+`MediaElement (source)` => `DynamicsCompressorNode (limiter)` => `GainNode` => `AudioDestination (output)`  
+  
+A limiter (compression) is applied to the audio to prevent clipping.  
+Its properties can be changed by calling the returned function `setLimiterOptions()`  
+The limiter options set by default are `{ threshold: -12, knee: 30, ratio: 12, attack: 0.003, release: 0.25 }`  
   
 ⚠️ This function has to be run in response to a user interaction event, else the browser will reject it because of the strict autoplay policy.  
+⚠️ Make sure to call the returned function `enable()` after calling this function to actually enable the amplification.  
   
-The returned AmplifyMediaResult object has the following properties:
+The returned object of the type `AmplifyMediaResult` has the following properties:
 | Property | Description |
 | :-- | :-- |
-| `mediaElement` | The passed media element |
-| `amplify()` | A function to change the amplification level |
-| `getAmpLevel()` | A function to return the current amplification level |
+| `setGain()` | Used to change the gain multiplier |
+| `getGain()` | Returns the current gain multiplier |
+| `enable()` | Call to enable the amplification for the first time or if it was disabled before |
+| `disable()` | Call to disable amplification |
+| `setLimiterOptions()` | Used for changing the [options of the DynamicsCompressorNode](https://developer.mozilla.org/en-US/docs/Web/API/DynamicsCompressorNode/DynamicsCompressorNode#options) - the default is `{ threshold: -12, knee: 30, ratio: 12, attack: 0.003, release: 0.25 }` |
 | `context` | The AudioContext instance |
 | `source` | The MediaElementSourceNode instance |
-| `gain` | The GainNode instance |
+| `gainNode` | The GainNode instance used for actually boosting the gain |
+| `limiterNode` | The DynamicsCompressorNode instance used for limiting clipping and distortion |
   
 <details><summary><b>Example - click to view</b></summary>
 
 ```ts
-import { amplifyMedia } from "@sv443-network/userutils";
+import { amplifyMedia, clamp } from "@sv443-network/userutils";
+import type { AmplifyMediaResult } from "@sv443-network/userutils";
+
+const audioElement = document.querySelector<HTMLAudioElement>("audio");
+
+let ampResult: AmplifyMediaResult | undefined;
+
+function setGain(newValue: number) {
+  if(!ampResult)
+    return;
+  // constrain the value to between 0 and 3 for safety
+  ampResult.setGain(clamp(newValue, 0, 3));
+  console.log("Gain set to", ampResult.getGain());
+}
+
+
+const amplifyButton = document.querySelector<HTMLButtonElement>("button#amplify");
 
-const audio = document.querySelector<HTMLAudioElement>("audio");
-const button = document.querySelector<HTMLButtonElement>("button");
+// amplifyMedia() needs to be called in response to a user interaction event:
+amplifyButton.addEventListener("click", () => {
+  // only needs to be initialized once, afterwards the returned object
+  // can be used to change settings and enable/disable the amplification
+  if(!ampResult) {
+    // initialize amplification and set gain to 2x
+    ampResult = amplifyMedia(audioElement, 2);
+    // enable the amplification
+    ampResult.enable();
+  }
+
+  setGain(2.5);  // set gain to 2.5x
+
+  console.log(ampResult.getGain()); // 2.5
+});
 
-// amplifyMedia needs to be called in response to a user interaction event:
-button.addEventListener("click", () => {
-  const { amplify, getAmpLevel } = amplifyMedia(audio);
 
-  const setGain = (value: number) => {
-    // constrain the value to between 0 and 5
-    amplify(clamp(value, 0, 5));
-    console.log("Gain set to", getAmpLevel());
+const disableButton = document.querySelector<HTMLButtonElement>("button#disable");
+
+disableButton.addEventListener("click", () => {
+  if(ampResult) {
+    // disable the amplification
+    ampResult.disable();
   }
+});
 
-  setGain(2);    // set gain to 2x
-  setGain(3.5);  // set gain to 3.5x
 
-  console.log(getAmpLevel()); // 3.5
+const limiterButton = document.querySelector<HTMLButtonElement>("button#limiter");
+
+limiterButton.addEventListener("click", () => {
+  if(ampResult) {
+    // change the limiter options to a more aggressive setting
+    // see https://developer.mozilla.org/en-US/docs/Web/API/DynamicsCompressorNode/DynamicsCompressorNode#options
+    ampResult.setLimiterOptions({
+      threshold: -10,
+      knee: 20,
+      ratio: 20,
+      attack: 0.001,
+      release: 0.1,
+    });
+  }
 });
 ```
 
@@ -1104,7 +1155,7 @@ tr.addLanguage("en", {
 
 /** Returns the custom pluralization identifier for the given number of items (or size of Array/NodeList) */
 function pl(num: number | unknown[] | NodeList) {
-  if(Array.isArray(num))
+  if(typeof num !== "number")
     num = num.length;
 
   if(num === 0)

package/dist/index.global.js

@@ -9,7 +9,7 @@
 // ==UserLibrary==
 // @name         UserUtils
 // @description  Library with various utilities for userscripts - register listeners for when CSS selectors exist, intercept events, manage persistent user configurations, modify the DOM more easily and more
-// @version      1.2.0
+// @version      2.0.1
 // @license      MIT
 // @copyright    Sv443 (https://github.com/Sv443)
 
@@ -315,22 +315,52 @@ var UserUtils = (function (exports) {
   function interceptWindowEvent(eventName, predicate) {
     return interceptEvent(getUnsafeWindow(), eventName, predicate);
   }
-  function amplifyMedia(mediaElement, multiplier = 1) {
+  function amplifyMedia(mediaElement, initialMultiplier = 1) {
     const context = new (window.AudioContext || window.webkitAudioContext)();
-    const result = {
-      mediaElement,
-      amplify: (multiplier2) => {
-        result.gain.gain.value = multiplier2;
+    const props = {
+      /** Sets the gain multiplier */
+      setGain(multiplier) {
+        props.gainNode.gain.setValueAtTime(multiplier, props.context.currentTime);
+      },
+      /** Returns the current gain multiplier */
+      getGain() {
+        return props.gainNode.gain.value;
+      },
+      /** Enable the amplification for the first time or if it was disabled before */
+      enable() {
+        props.source.connect(props.limiterNode);
+        props.limiterNode.connect(props.gainNode);
+        props.gainNode.connect(props.context.destination);
+      },
+      /** Disable the amplification */
+      disable() {
+        props.source.disconnect(props.limiterNode);
+        props.limiterNode.disconnect(props.gainNode);
+        props.gainNode.disconnect(props.context.destination);
+        props.source.connect(props.context.destination);
+      },
+      /**
+       * Set the options of the [limiter / DynamicsCompressorNode](https://developer.mozilla.org/en-US/docs/Web/API/DynamicsCompressorNode/DynamicsCompressorNode#options)  
+       * The default is `{ threshold: -12, knee: 30, ratio: 12, attack: 0.003, release: 0.25 }`
+       */
+      setLimiterOptions(options) {
+        for (const [key, val] of Object.entries(options))
+          props.limiterNode[key].setValueAtTime(val, props.context.currentTime);
       },
-      getAmpLevel: () => result.gain.gain.value,
       context,
       source: context.createMediaElementSource(mediaElement),
-      gain: context.createGain()
+      gainNode: context.createGain(),
+      limiterNode: context.createDynamicsCompressor()
     };
-    result.source.connect(result.gain);
-    result.gain.connect(context.destination);
-    result.amplify(multiplier);
-    return result;
+    props.setLimiterOptions({
+      threshold: -12,
+      knee: 30,
+      ratio: 12,
+      attack: 3e-3,
+      release: 0.25
+    });
+    props.setGain(initialMultiplier);
+    return props;
   }
   function isScrollable(element) {
     const { overflowX, overflowY } = getComputedStyle(element);

package/dist/index.js

@@ -294,22 +294,52 @@ function interceptEvent(eventObject, eventName, predicate) {
 function interceptWindowEvent(eventName, predicate) {
   return interceptEvent(getUnsafeWindow(), eventName, predicate);
 }
-function amplifyMedia(mediaElement, multiplier = 1) {
+function amplifyMedia(mediaElement, initialMultiplier = 1) {
   const context = new (window.AudioContext || window.webkitAudioContext)();
-  const result = {
-    mediaElement,
-    amplify: (multiplier2) => {
-      result.gain.gain.value = multiplier2;
+  const props = {
+    /** Sets the gain multiplier */
+    setGain(multiplier) {
+      props.gainNode.gain.setValueAtTime(multiplier, props.context.currentTime);
+    },
+    /** Returns the current gain multiplier */
+    getGain() {
+      return props.gainNode.gain.value;
+    },
+    /** Enable the amplification for the first time or if it was disabled before */
+    enable() {
+      props.source.connect(props.limiterNode);
+      props.limiterNode.connect(props.gainNode);
+      props.gainNode.connect(props.context.destination);
+    },
+    /** Disable the amplification */
+    disable() {
+      props.source.disconnect(props.limiterNode);
+      props.limiterNode.disconnect(props.gainNode);
+      props.gainNode.disconnect(props.context.destination);
+      props.source.connect(props.context.destination);
+    },
+    /**
+     * Set the options of the [limiter / DynamicsCompressorNode](https://developer.mozilla.org/en-US/docs/Web/API/DynamicsCompressorNode/DynamicsCompressorNode#options)  
+     * The default is `{ threshold: -12, knee: 30, ratio: 12, attack: 0.003, release: 0.25 }`
+     */
+    setLimiterOptions(options) {
+      for (const [key, val] of Object.entries(options))
+        props.limiterNode[key].setValueAtTime(val, props.context.currentTime);
     },
-    getAmpLevel: () => result.gain.gain.value,
     context,
     source: context.createMediaElementSource(mediaElement),
-    gain: context.createGain()
+    gainNode: context.createGain(),
+    limiterNode: context.createDynamicsCompressor()
   };
-  result.source.connect(result.gain);
-  result.gain.connect(context.destination);
-  result.amplify(multiplier);
-  return result;
+  props.setLimiterOptions({
+    threshold: -12,
+    knee: 30,
+    ratio: 12,
+    attack: 3e-3,
+    release: 0.25
+  });
+  props.setGain(initialMultiplier);
+  return props;
 }
 function isScrollable(element) {
   const { overflowX, overflowY } = getComputedStyle(element);

package/dist/index.mjs

@@ -292,22 +292,52 @@ function interceptEvent(eventObject, eventName, predicate) {
 function interceptWindowEvent(eventName, predicate) {
   return interceptEvent(getUnsafeWindow(), eventName, predicate);
 }
-function amplifyMedia(mediaElement, multiplier = 1) {
+function amplifyMedia(mediaElement, initialMultiplier = 1) {
   const context = new (window.AudioContext || window.webkitAudioContext)();
-  const result = {
-    mediaElement,
-    amplify: (multiplier2) => {
-      result.gain.gain.value = multiplier2;
+  const props = {
+    /** Sets the gain multiplier */
+    setGain(multiplier) {
+      props.gainNode.gain.setValueAtTime(multiplier, props.context.currentTime);
+    },
+    /** Returns the current gain multiplier */
+    getGain() {
+      return props.gainNode.gain.value;
+    },
+    /** Enable the amplification for the first time or if it was disabled before */
+    enable() {
+      props.source.connect(props.limiterNode);
+      props.limiterNode.connect(props.gainNode);
+      props.gainNode.connect(props.context.destination);
+    },
+    /** Disable the amplification */
+    disable() {
+      props.source.disconnect(props.limiterNode);
+      props.limiterNode.disconnect(props.gainNode);
+      props.gainNode.disconnect(props.context.destination);
+      props.source.connect(props.context.destination);
+    },
+    /**
+     * Set the options of the [limiter / DynamicsCompressorNode](https://developer.mozilla.org/en-US/docs/Web/API/DynamicsCompressorNode/DynamicsCompressorNode#options)  
+     * The default is `{ threshold: -12, knee: 30, ratio: 12, attack: 0.003, release: 0.25 }`
+     */
+    setLimiterOptions(options) {
+      for (const [key, val] of Object.entries(options))
+        props.limiterNode[key].setValueAtTime(val, props.context.currentTime);
     },
-    getAmpLevel: () => result.gain.gain.value,
     context,
     source: context.createMediaElementSource(mediaElement),
-    gain: context.createGain()
+    gainNode: context.createGain(),
+    limiterNode: context.createDynamicsCompressor()
   };
-  result.source.connect(result.gain);
-  result.gain.connect(context.destination);
-  result.amplify(multiplier);
-  return result;
+  props.setLimiterOptions({
+    threshold: -12,
+    knee: 30,
+    ratio: 12,
+    attack: 3e-3,
+    release: 0.25
+  });
+  props.setGain(initialMultiplier);
+  return props;
 }
 function isScrollable(element) {
   const { overflowX, overflowY } = getComputedStyle(element);

package/dist/lib/dom.d.ts

@@ -45,28 +45,51 @@ export declare function interceptEvent<TEvtObj extends EventTarget, TPredicateEv
 export declare function interceptWindowEvent<TEvtKey extends keyof WindowEventMap>(eventName: TEvtKey, predicate: (event: WindowEventMap[TEvtKey]) => boolean): void;
 /**
  * Amplifies the gain of the passed media element's audio by the specified multiplier.
- * This function supports any media element like `<audio>` or `<video>`
+ * Also applies a limiter to prevent clipping and distortion.
+ * This function supports any MediaElement instance like `<audio>` or `<video>`
  *
- * This function has to be run in response to a user interaction event, else the browser will reject it because of the strict autoplay policy.
+ * This is the audio processing workflow:
+ * `MediaElement (source)` => `DynamicsCompressorNode (limiter)` => `GainNode` => `AudioDestinationNode (output)`
  *
+ * ⚠️ This function has to be run in response to a user interaction event, else the browser will reject it because of the strict autoplay policy.
+ * ⚠️ Make sure to call the returned function `enable()` after calling this function to actually enable the amplification.
+ *
+ * @param mediaElement The media element to amplify (e.g. `<audio>` or `<video>`)
+ * @param initialMultiplier The initial gain multiplier to apply (floating point number, default is `1.0`)
  * @returns Returns an object with the following properties:
  * | Property | Description |
  * | :-- | :-- |
- * | `mediaElement` | The passed media element |
- * | `amplify()` | A function to change the amplification level |
- * | `getAmpLevel()` | A function to return the current amplification level |
+ * | `setGain()` | Used to change the gain multiplier |
+ * | `getGain()` | Returns the current gain multiplier |
+ * | `enable()` | Call to enable the amplification for the first time or if it was disabled before |
+ * | `disable()` | Call to disable amplification |
+ * | `setLimiterOptions()` | Used for changing the [options of the DynamicsCompressorNode](https://developer.mozilla.org/en-US/docs/Web/API/DynamicsCompressorNode/DynamicsCompressorNode#options) - the default is `{ threshold: -2, knee: 40, ratio: 12, attack: 0.003, release: 0.25 }` |
  * | `context` | The AudioContext instance |
  * | `source` | The MediaElementSourceNode instance |
- * | `gain` | The GainNode instance |
+ * | `gainNode` | The GainNode instance |
+ * | `limiterNode` | The DynamicsCompressorNode instance used for limiting clipping and distortion |
  */
-export declare function amplifyMedia<TElem extends HTMLMediaElement>(mediaElement: TElem, multiplier?: number): {
-    mediaElement: TElem;
-    amplify: (multiplier: number) => void;
-    getAmpLevel: () => number;
+export declare function amplifyMedia<TElem extends HTMLMediaElement>(mediaElement: TElem, initialMultiplier?: number): {
+    /** Sets the gain multiplier */
+    setGain(multiplier: number): void;
+    /** Returns the current gain multiplier */
+    getGain(): number;
+    /** Enable the amplification for the first time or if it was disabled before */
+    enable(): void;
+    /** Disable the amplification */
+    disable(): void;
+    /**
+     * Set the options of the [limiter / DynamicsCompressorNode](https://developer.mozilla.org/en-US/docs/Web/API/DynamicsCompressorNode/DynamicsCompressorNode#options)
+     * The default is `{ threshold: -12, knee: 30, ratio: 12, attack: 0.003, release: 0.25 }`
+     */
+    setLimiterOptions(options: Partial<Record<"threshold" | "knee" | "ratio" | "attack" | "release", number>>): void;
     context: AudioContext;
     source: MediaElementAudioSourceNode;
-    gain: GainNode;
+    gainNode: GainNode;
+    limiterNode: DynamicsCompressorNode;
 };
+/** An object which contains the results of `amplifyMedia()` */
+export type AmplifyMediaResult = ReturnType<typeof amplifyMedia>;
 /** Checks if an element is scrollable in the horizontal and vertical directions */
 export declare function isScrollable(element: Element): {
     vertical: boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sv443-network/userutils",
-  "version": "1.2.0",
+  "version": "2.0.1",
   "description": "Library with various utilities for userscripts - register listeners for when CSS selectors exist, intercept events, manage persistent user configurations, modify the DOM more easily and more",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -9,10 +9,10 @@
     "lint": "tsc --noEmit && eslint .",
     "build-types": "tsc --emitDeclarationOnly --declaration --outDir dist",
     "build-common": "tsup lib/index.ts --format cjs,esm --clean --treeshake",
-    "build-global": "tsup lib/index.ts --format cjs,esm,iife --treeshake --onSuccess \"npm run post-build-global\"",
+    "build-global": "tsup lib/index.ts --format cjs,esm,iife --treeshake --onSuccess \"npm run post-build-global && echo Finished building.\"",
     "build": "npm run build-common -- && npm run build-types",
     "post-build-global": "npm run node-ts -- ./tools/post-build-global.mts",
-    "dev": "npm run build-common -- --sourcemap --watch --onSuccess \"npm run build-types\"",
+    "dev": "npm run build-common -- --sourcemap --watch --onSuccess \"npm run build-types && echo Finished building.\"",
     "publish-package": "changeset publish",
     "node-ts": "node --no-warnings=ExperimentalWarning --enable-source-maps --loader ts-node/esm"
   },