hypnosound 1.2.0 → 1.2.1

package/README.md

@@ -1,2 +1,57 @@
 # hypnosound
-A little library for analyzing audio
+A little library for extracting audio features, and optionally applying statistics to them.
+
+## Usage
+Check out [index.html](./index.html) for a simple example. You can run it via `npm run start`.
+
+You can either use the AudioProcessor, which maintains state and calculates the statistics for you, or use of the functions directly in a functional way. Everything can be used functionally except for spectralFlux, which requires state.
+
+### AudioProcessor
+
+```javascript
+  import AudioProcessor from 'hypnosound';
+  const a = new AudioProcessor();
+  console.log({
+    energy: a.energy(fft),
+    spectralCentroid: a.spectralCentroid(fft),
+    spectralCrest: a.spectralCrest(fft),
+    spectralEntropy: a.spectralEntropy(fft),
+    spectralFlux: a.spectralFlux(fft),
+    spectralKurtosis: a.spectralKurtosis(fft),
+    spectralRolloff: a.spectralRolloff(fft),
+    spectralRoughness: a.spectralRoughness(fft),
+    spectralSkew: a.spectralSkew(fft),
+    spectralSpread: a.spectralSpread(fft),
+  });
+
+  ```
+
+  Each audio feature comes with statistics, which are calculated automatically. You can access them like so:
+  ```javascript
+  const {value, stats} = a.energy(fft)
+  console.log(`the current value for energy is ${value}`);
+  console.log(`here are some stats: zScore: ${stats.zScore}, normalized: ${stats.normalized}, standardDeviation: ${stats.standardDeviation}, median: ${stats.median}, mean: ${stats.mean}, min: ${stats.min}, max: ${stats.max}`);
+  ```
+⚠️ __Warning: Each call to a function will update the statistics for that feature. so I'd recommend saving the result of the function call to a variable and then use that__
+
+### Functional
+```javascript
+import {energy} from 'hypnosound'; // or any other audio feature EXCEPT spectralFlux
+console.log(energy(fft)); // returns the instantaneous energy value.
+```
+
+You may want to calculate statistics for the audio features on your own, but still use the functional style.
+Since statistics require state, this must be managed outside the function in purely functional mode.
+Here's an example of how you might do that:
+
+```javascript
+import { makeCalculateStats, spectralCentroid } from 'hypnosound'
+const calculateStats = makeCalculateStats()
+
+const value = spectralCentroid(fft)
+const stats = calculateStats(value) // WARNING: each call to calculateStats will update the state.
+
+console.log({value, stats})
+```
+
+

package/index.html

@@ -9,7 +9,8 @@
     <button id="start">Start Listening</button>
     <script type="module">
         import AudioProcessor from './index.js'
-        document.getElementById('start').addEventListener('click', async () => {
+        const button = document.getElementById('start')
+        button.addEventListener('click', async () => {
           const a = new AudioProcessor()
             try {
                 const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
@@ -19,7 +20,7 @@
 
                 source.connect(analyser);
                 analyser.fftSize = 32768; // Or whatever size you need
-
+                analyser.smoothingTimeConstant = 0
                 const bufferLength = analyser.frequencyBinCount;
                 const dataArray = new Uint8Array(bufferLength);
 
@@ -41,7 +42,6 @@
                       spectralSkew: a.spectralSkew(dataArray),
                       spectralSpread: a.spectralSpread(dataArray),
                     });
-                    // console.log(a.spectralCentroid(dataArray).value);
                 };
 
                 draw();

package/index.js

@@ -1,5 +1,5 @@
 import { makeCalculateStats } from './src/utils/calculateStats.js'
-
+import {applyKaiserWindow} from './src/utils/applyKaiserWindow.js'
 import energy from './src/audio/energy.js'
 import spectralCentroid from './src/audio/spectralCentroid.js'
 import spectralCrest from './src/audio/spectralCrest.js'
@@ -40,61 +40,71 @@ class AudioProcessor {
     }
 
     energy = (fft) => {
-        const value = energy(fft)
+        const windowedFft = applyKaiserWindow(fft)
+        const value = energy(windowedFft)
         const stats = this.statCalculators.energy(value)
         return { value, stats }
     }
 
     spectralCentroid = (fft) => {
-        const value = spectralCentroid(fft)
+        const windowedFft = applyKaiserWindow(fft)
+        const value = spectralCentroid(applyKaiserWindow(windowedFft))
         const stats = this.statCalculators.spectralCentroid(value)
         return { value, stats }
     }
 
     spectralCrest = (fft) => {
-        const value = spectralCrest(fft)
+        const windowedFft = applyKaiserWindow(fft)
+        const value = spectralCrest(windowedFft)
         const stats = this.statCalculators.spectralCentroid(value)
         return { value, stats }
     }
 
     spectralEntropy = (fft) => {
-        const value = spectralEntropy(fft)
+        const windowedFft = applyKaiserWindow(fft)
+        const value = spectralEntropy(windowedFft)
         const stats = this.statCalculators.spectralEntropy(value)
         return { value, stats }
     }
 
     spectralFlux = (fft) => {
-        const value = spectralFlux(fft, this.previousValue.spectralFlux)
-        this.previousValue.spectralFlux = new Uint8Array(fft)
+        const windowedFft = applyKaiserWindow(fft)
+        const value = spectralFlux(windowedFft, this.previousValue.spectralFlux)
+        this.previousValue.spectralFlux = new Uint8Array(windowedFft)
         const stats = this.statCalculators.spectralFlux(value)
         return { value, stats }
     }
     spectralKurtosis = (fft) => {
-        const value = spectralKurtosis(fft)
+        const windowedFft = applyKaiserWindow(fft)
+        const value = spectralKurtosis(windowedFft)
         const stats = this.statCalculators.spectralKurtosis(value)
         return { value, stats }
     }
 
     spectralRolloff = (fft) => {
-        const value = spectralRolloff(fft)
+        const windowedFft = applyKaiserWindow(fft)
+        const value = spectralRolloff(windowedFft)
         const stats = this.statCalculators.spectralRolloff(value)
         return { value, stats }
     }
 
     spectralRoughness = (fft) => {
-        const value = spectralRoughness(fft)
+        const windowedFft = applyKaiserWindow(fft)
+        const value = spectralRoughness(windowedFft)
         const stats = this.statCalculators.spectralRoughness(value)
         return { value, stats }
     }
 
     spectralSkew = (fft) => {
-        const value = spectralSkew(fft)
+        const windowedFft = applyKaiserWindow(fft)
+        const value = spectralSkew(windowedFft)
         const stats = this.statCalculators.spectralSkew(value)
         return { value, stats }
     }
 
     spectralSpread = (fft) => {
-        const value = spectralSpread(fft)
+        const windowedFft = applyKaiserWindow(fft)
+        const value = spectralSpread(windowedFft)
         const stats = this.statCalculators.spectralSpread(value)
         return { value, stats }
     }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "hypnosound",
   "type": "module",
-  "version": "1.2.0",
+  "version": "1.2.1",
   "description": "A small library for analyzing audio",
   "main": "index.js",
   "scripts": {

package/src/audio/spectralCentroid.js

@@ -1,17 +1,25 @@
-import mu from '../utils/mu.js'
 export default function spectralCentroid(fft) {
     const computed = calculateSpectralCentroid(fft) // Process FFT data
     return computed * 1.5
 }
-
 function calculateSpectralCentroid(ampSpectrum) {
-    const centroid = mu(1, ampSpectrum)
-    if (centroid === null) return null
+    if (!ampSpectrum.length) return null // Early exit if the spectrum is empty
+
+    let numerator = 0
+    let denominator = 0
+
+    // Calculate the weighted sum (numerator) and the sum of the amplitudes (denominator)
+    ampSpectrum.forEach((amplitude, index) => {
+        numerator += index * amplitude
+        denominator += amplitude
+    })
+
+    // Avoid dividing by zero
+    if (denominator === 0) return null
+
+    const centroidIndex = numerator / denominator
+    // Normalize the centroid index to be between 0 and 1
+    const normalizedCentroid = centroidIndex / (ampSpectrum.length - 1)
 
-    // Maximum centroid occurs when all energy is at the highest frequency bin
-    const maxCentroid = mu(
-        1,
-        ampSpectrum.map((val, index) => (index === ampSpectrum.length - 1 ? 1 : 0)),
-    )
-    return centroid / maxCentroid // Normalize the centroid
+    return normalizedCentroid
 }

package/src/utils/applyKaiserWindow.js

@@ -0,0 +1,31 @@
+export function applyKaiserWindow(audioBuffer, beta = 5.658) {
+    // Beta default based on common use
+    const N = audioBuffer.length
+    const windowedBuffer = new Float32Array(N)
+    const I0Beta = I0(beta) // Calculate the zeroth order modified Bessel function of the first kind for beta
+
+    for (let n = 0; n < N; n++) {
+        const windowValue = I0(beta * Math.sqrt(1 - Math.pow((2 * n) / (N - 1) - 1, 2))) / I0Beta
+        windowedBuffer[n] = audioBuffer[n] * windowValue
+    }
+
+    return windowedBuffer
+}
+
+// Calculate the zeroth order modified Bessel function of the first kind
+// This approximation is suitable for the window function calculation
+function I0(x) {
+    let sum = 1.0
+    let y = x / 2.0
+    let term = 1.0
+    let k = 1
+
+    while (term > 1e-6 * sum) {
+        // Continue until the added value is insignificant
+        term *= (y / k) ** 2
+        sum += term
+        k++
+    }
+
+    return sum
+}

package/cmd.js

@@ -1,3 +0,0 @@
-#!/usr/bin/env node
-import AudioProcessor from './index.js'
-console.log(AudioProcessor)