ref!: remove amplifyMedia function

.changeset/weak-dolphins-tickle.md

@@ -0,0 +1,5 @@
+---
+"@sv443-network/userutils": major
+---
+
+Removed `amplifyMedia` function due to massive inconsistencies in sound quality

README-summary.md

@@ -24,7 +24,6 @@ If you like using this library, please consider [supporting the development ❤
     - [openInNewTab()](https://github.com/Sv443-Network/UserUtils#openinnewtab) - open a link in a new tab
     - [interceptEvent()](https://github.com/Sv443-Network/UserUtils#interceptevent) - conditionally intercepts events registered by `addEventListener()` on any given EventTarget object
     - [interceptWindowEvent()](https://github.com/Sv443-Network/UserUtils#interceptwindowevent) - conditionally intercepts events registered by `addEventListener()` on the window object
-    - [amplifyMedia()](https://github.com/Sv443-Network/UserUtils#amplifymedia) - amplify an audio or video element's volume past the maximum of 100%
     - [isScrollable()](https://github.com/Sv443-Network/UserUtils#isscrollable) - check if an element has a horizontal or vertical scroll bar
 - Math:
     - [clamp()](https://github.com/Sv443-Network/UserUtils#clamp) - constrain a number between a min and max value

README.md

@@ -30,7 +30,6 @@ View the documentation of previous major releases: [2.0.1](https://github.com/Sv
     - [openInNewTab()](#openinnewtab) - open a link in a new tab
     - [interceptEvent()](#interceptevent) - conditionally intercepts events registered by `addEventListener()` on any given EventTarget object
     - [interceptWindowEvent()](#interceptwindowevent) - conditionally intercepts events registered by `addEventListener()` on the window object
-    - [amplifyMedia()](#amplifymedia) - amplify an audio or video element's volume past the maximum of 100%
     - [isScrollable()](#isscrollable) - check if an element has a horizontal or vertical scroll bar
   - [**Math:**](#math)
     - [clamp()](#clamp) - constrain a number between a min and max value
@@ -649,101 +648,6 @@ interceptWindowEvent("beforeunload");
 
 <br>
 
-### amplifyMedia()
-Usage:  
-```ts
-amplifyMedia(mediaElement: HTMLMediaElement, initialGain?: number): AmplifyMediaResult
-```
-  
-Amplifies the volume of a media element (like `<audio>` or `<video>`) by the given gain value.  
-This is how you can increase the volume of a media element beyond the default maximum volume of 100%.  
-Make sure to limit the value to a reasonable value ([clamp()](#clamp) is good for this), as it may otherwise cause bleeding eardrums.  
-  
-The default gain value passed to the GainNode is `1.0`  
-It may be read and changed at any point by calling the `getGain()` and `setGain()` methods of the returned object.  
-  
-To activate the amplification for the first time, call the `enable()` method of the returned object.  
-  
-This is the processing workflow applied to the media element:  
-`MediaElement (source)` => `GainNode (pre-amplifier)` => 10x `BiquadFilterNode` => `GainNode (post-amplifier)` => `destination`  
-  
-⚠️ 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 object of the type `AmplifyMediaResult` has the following properties:  
-**Important properties:**
-| Property | Description |
-| :-- | :-- |
-| `enable()` | Call to enable the amplification for the first time or re-enable it if it was disabled before |
-| `disable()` | Call to disable amplification |
-| `enabled` | Whether the amplification is currently enabled |
-| `setGain()` | Used to change the gain value from the default given by the parameter `initialGain` |
-| `getGain()` | Returns the current gain value |
-
-**Other properties:**
-| Property | Description |
-| :-- | :-- |
-| `context` | The AudioContext instance used as the audio destination and context within the nodes are created |
-| `sourceNode` | A MediaElementSourceNode instance created from the passed `mediaElement` |
-| `gainNode` | The GainNode instance used for volume amplification |
-  
-<br>
-
-<details><summary><b>Example - click to view</b></summary>
-
-```ts
-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 updateGainValue(gainValue: number) {
-  if(!ampResult)
-    return;
-  // constrain the value to between 0 and 3 for safety
-  ampResult.setGain(clamp(gainValue, 0, 3));
-
-  console.log("Gain set to", ampResult.getGain());
-}
-
-
-const amplifyButton = document.querySelector<HTMLButtonElement>("button#amplify");
-
-// 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 it to ~2x
-    ampResult = amplifyMedia(audioElement, 2.0);
-  }
-  if(!ampResult.enabled) {
-    // enable the amplification
-    ampResult.enable();
-  }
-
-  updateGainValue(3.5); // try to set gain to ~3.5x
-
-  console.log(ampResult.getGain()); // 3.0 (because of the clamp())
-});
-
-
-const disableButton = document.querySelector<HTMLButtonElement>("button#disable");
-
-disableButton.addEventListener("click", () => {
-  if(ampResult) {
-    // disable the amplification
-    ampResult.disable();
-  }
-});
-```
-
-</details>
-
-<br>
-
 ### isScrollable()
 Usage:  
 ```ts

lib/dom.ts

@@ -132,82 +132,6 @@ export function interceptWindowEvent<TEvtKey extends keyof WindowEventMap>(
   return interceptEvent(getUnsafeWindow(), eventName, predicate);
 }
 
-/** An object which contains the results of {@linkcode amplifyMedia()} */
-export type AmplifyMediaResult = ReturnType<typeof amplifyMedia>;
-
-/**
- * Amplifies the gain of the passed media element's audio by the specified value.  
- * This function supports any MediaElement instance like `<audio>` or `<video>`  
- *   
- * This is the audio processing workflow:  
- * `MediaElement (source)` => `GainNode (amplification)` => `destination`  
- *   
- * ⚠️ 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.  
- * ⚠️ You should implement a safety limit by using the [`clamp()`](https://github.com/Sv443-Network/UserUtils#clamp) function to prevent any accidental bleeding eardrums.  
- *   
- * @param mediaElement The media element to amplify (e.g. `<audio>` or `<video>`)
- * @param initialGain The initial gain to apply to the GainNode responsible for volume amplification (floating point number, default is `1.0`)
- * @returns Returns an object with the following properties:  
- * **Important properties:**
- * | Property | Description |
- * | :-- | :-- |
- * | `enable()` | Call to enable the amplification for the first time or re-enable it if it was disabled before |
- * | `disable()` | Call to disable amplification |
- * | `enabled` | Whether the amplification is currently enabled |
- * | `setGain()` | Used to change the gain value from the default given by the parameter {@linkcode initialGain} |
- * | `getGain()` | Returns the current gain value |
- * 
- * **Other properties:**
- * | Property | Description |
- * | :-- | :-- |
- * | `context` | The AudioContext instance |
- * | `sourceNode` | A MediaElementSourceNode instance created from the passed {@linkcode mediaElement} |
- * | `gainNode` | The GainNode instance used for volume amplification |
- */
-export function amplifyMedia<TElem extends HTMLMediaElement>(mediaElement: TElem, initialGain = 1.0) {
-  // @ts-ignore
-  const context = new (window.AudioContext || window.webkitAudioContext)();
-  const props = {
-    context,
-    sourceNode: context.createMediaElementSource(mediaElement),
-    gainNode: context.createGain(),
-    /** Sets the gain of the amplifying GainNode */
-    setGain(gain: number) {
-      props.gainNode.gain.value = gain;
-    },
-    /** Returns the current gain of the amplifying GainNode */
-    getGain() {
-      return props.gainNode.gain.value;
-    },
-    /** Whether the amplification is currently enabled */
-    enabled: false,
-    /** Enable the amplification for the first time or if it was disabled before */
-    enable() {
-      if(props.enabled)
-        return;
-      props.enabled = true;
-
-      props.sourceNode.connect(props.gainNode);
-      props.gainNode.connect(props.context.destination);
-    },
-    /** Disable the amplification */
-    disable() {
-      if(!props.enabled)
-        return;
-      props.enabled = false;
-      props.sourceNode.disconnect(props.gainNode);
-      props.gainNode.disconnect(props.context.destination);
-
-      props.sourceNode.connect(props.context.destination);
-    },
-  };
-
-  props.setGain(initialGain);
-
-  return props;
-}
-
 /** Checks if an element is scrollable in the horizontal and vertical directions */
 export function isScrollable(element: Element) {
   const { overflowX, overflowY } = getComputedStyle(element);