nuxt-module-essentia 1.0.0

package/README.md

@@ -0,0 +1,54 @@
+# nuxt-module-essentia
+
+Nuxt модуль для интеграции Essentia.js WASM библиотеки анализа аудио.
+Работает на Nuxt 3 и 4
+
+## Установка
+
+```bash
+npm install nuxt-module-essentia
+```
+
+### Подключение модуля
+
+```typescript
+// nuxt.config.ts
+export default defineNuxtConfig({
+  modules: ["nuxt-module-essentia"],
+
+  essentia: {
+    publicAssetsPath: "/essentia/", // опционально
+  },
+});
+```
+
+### Использование композабла
+
+```typescript
+// Автоматически доступен в компонентах
+const {
+  getKeyMoodAndBpm,
+  keyBpmResults,
+  moodResults,
+  resetMoodResults,
+  essentia,
+  essentiaAnalysis,
+  featureExtractionWorker
+} = useAudioAnalizer();
+```
+
+## Разработка
+
+```bash
+# Сборка модуля
+npm run build
+
+# Режим разработки с watch
+npm run dev
+```
+
+## Структура
+
+- `src/module.ts` - основной файл модуля
+- `src/runtime/` - runtime файлы (копируются в public)
+- `src/runtime/composables/` - композаблы (автоимпорт)

package/dist/module.d.ts

@@ -0,0 +1,5 @@
+export interface ModuleOptions {
+    publicAssetsPath: string;
+}
+declare const _default: import("@nuxt/schema").NuxtModule<ModuleOptions, ModuleOptions, false>;
+export default _default;

package/dist/module.js

@@ -0,0 +1,31 @@
+import { defineNuxtModule as a, createResolver as r, addTemplate as l, addImportsDir as c } from "@nuxt/kit";
+const u = a({
+  meta: {
+    name: "nuxt-module-essentia",
+    configKey: "essentia",
+    compatibility: {
+      nuxt: "^3.0.0 || ^4.0.0"
+    }
+  },
+  defaults: {
+    publicAssetsPath: "/essentia/"
+  },
+  setup(e, s) {
+    var i;
+    const t = r(import.meta.url), o = t.resolve("../src/runtime"), n = t.resolve("../src/runtime/composables");
+    (i = s.options.nitro).publicAssets || (i.publicAssets = []), s.options.nitro.publicAssets.push({
+      dir: o,
+      baseURL: e.publicAssetsPath,
+      maxAge: 60 * 60 * 24 * 365
+      // 1 год
+    }), l({
+      filename: "essentia-config.mjs",
+      getContents: () => `export const essentiaConfig = ${JSON.stringify({
+        publicAssetsPath: e.publicAssetsPath
+      })}`
+    }), c(n);
+  }
+});
+export {
+  u as default
+};

package/dist/runtime/composables/useAudioAnalizer.d.ts

@@ -0,0 +1,44 @@
+import { type Ref } from "vue";
+export declare const useAudioAnalizer: () => {
+    getKeyMoodAndBpm: () => void;
+    keyBpmResults: Ref<{}, {}>;
+    moodResults: Ref<{}, {}>;
+    resetMoodResults: () => void;
+    essentia?: undefined;
+    essentiaAnalysis?: undefined;
+    featureExtractionWorker?: undefined;
+} | {
+    getKeyMoodAndBpm: (file: File) => Promise<void>;
+    keyBpmResults: Ref<{
+        key: string;
+        bpm: number;
+        scale: string;
+    } | null, {
+        key: string;
+        bpm: number;
+        scale: string;
+    } | null>;
+    moodResults: Ref<{
+        color: string;
+        icon: string;
+        title: string;
+        key: string;
+        value: number;
+    }[], {
+        color: string;
+        icon: string;
+        title: string;
+        key: string;
+        value: number;
+    }[] | {
+        color: string;
+        icon: string;
+        title: string;
+        key: string;
+        value: number;
+    }[]>;
+    resetMoodResults: () => void;
+    essentia: any;
+    essentiaAnalysis: undefined;
+    featureExtractionWorker: any;
+};

package/dist/runtime/index.d.ts

@@ -0,0 +1 @@
+export { useAudioAnalizer } from "./composables/useAudioAnalizer";

package/dist/runtime/utils/config.d.ts

@@ -0,0 +1 @@
+export declare function getEssentiaConfig(): Promise<any>;

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "nuxt-module-essentia",
+  "version": "1.0.0",
+  "description": "Nuxt module for Essentia WASM integration",
+  "type": "module",
+  "main": "./dist/module.js",
+  "types": "./dist/module.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/module.js",
+      "types": "./dist/module.d.ts"
+    },
+    "./runtime": {
+      "import": "./src/runtime/index.ts",
+      "types": "./src/runtime/index.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "src/runtime"
+  ],
+  "scripts": {
+    "build": "vite build && tsc --emitDeclarationOnly",
+    "dev": "vite build --watch",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@nuxt/kit": "^3.0.0"
+  },
+  "devDependencies": {
+    "@nuxt/schema": "^3.0.0",
+    "nuxt": "^3.0.0",
+    "typescript": "^5.0.0",
+    "vite": "^5.0.0"
+  },
+  "peerDependencies": {
+    "nuxt": "^3.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nikitakashin/nuxt-module-essentia.git"
+  },
+  "author": {
+    "name": "Kashin Nikita",
+    "url": "https://github.com/nikitakashin/",
+    "email": "dev@nkashin.ru"
+  },
+  "published": "11.2025",
+  "keywords": [
+    "nuxt",
+    "nuxt-module",
+    "essentia",
+    "essentia-wasm",
+    "audio-analysis",
+    "music-information-retrieval",
+    "wasm",
+    "web-audio",
+    "audio-processing",
+    "machine-learning",
+    "signal-processing",
+    "feature-extraction",
+    "nuxt3",
+    "nuxt4"
+  ],
+  "license": "ISC",
+  "bugs": {
+    "url": "https://github.com/nikitakashin/nuxt-module-essentia/issues"
+  },
+  "homepage": "https://github.com/nikitakashin/nuxt-module-essentia"
+}

package/src/runtime/composables/useAudioAnalizer.ts

@@ -0,0 +1,379 @@
+import { ref, type Ref } from "vue";
+
+export const useAudioAnalizer = () => {
+  if (!import.meta.client) {
+    return {
+      getKeyMoodAndBpm: () => {},
+      keyBpmResults: ref({}),
+      moodResults: ref({}),
+      resetMoodResults: () => {},
+    };
+  }
+
+  const DEFAULT_MOOD_VALUE = [
+    {
+      color: "light-blue-lighten-2",
+      icon: "💃",
+      title: "Танцевальный",
+      key: "danceability",
+      value: 0,
+    },
+    {
+      color: "light-blue-lighten-1",
+      icon: "😊",
+      title: "Радостный",
+      key: "mood_happy",
+      value: 0,
+    },
+    {
+      color: "light-blue-darken-1",
+      icon: "😢",
+      title: "Грустный",
+      key: "mood_sad",
+      value: 0,
+    },
+    {
+      color: "light-blue-darken-2",
+      icon: "😌",
+      title: "Расслабляющий",
+      key: "mood_relaxed",
+      value: 0,
+    },
+    {
+      color: "light-blue-darken-3",
+      icon: "😤",
+      title: "Агрессивный",
+      key: "mood_aggressive",
+      value: 0,
+    },
+  ];
+
+  const keyBpmResults: Ref<{ key: string; bpm: number; scale: string } | null> = ref(null);
+
+  const moodResults = ref(DEFAULT_MOOD_VALUE);
+
+  let audioCtx: AudioContext;
+
+  if (import.meta.client) {
+    // @ts-ignore
+    audioCtx = new (window.AudioContext || window.webkitAudioContext)();
+  }
+
+  const KEEP_PERCENTAGE = 0.15; // keep only 15% of audio file
+  let essentia: any = null;
+  // @ts-ignore
+  let essentiaAnalysis;
+  let featureExtractionWorker: any = null;
+  const modelNames = ["mood_happy", "mood_sad", "mood_relaxed", "mood_aggressive", "danceability"];
+
+  let basePath = "/essentia/";
+  let inferenceWorker: Worker;
+  let inferenceStartTime = 0;
+
+  if (import.meta.client) {
+    // Загружаем конфиг асинхронно
+    // @ts-ignore
+    import("#build/essentia-config.mjs")
+      .then((module: any) => {
+        basePath = module.essentiaConfig.publicAssetsPath;
+      })
+      .catch(() => {
+        basePath = "/essentia/"; // fallback
+      });
+
+    createInferenceWorker();
+    createFeatureExtractionWorker();
+  }
+  // @ts-ignore
+  if (import.meta.client) {
+    // Загружаем essentia через глобальный window объект
+    const script = document.createElement("script");
+    script.src = `${basePath}essentia-wasm.web.js`;
+    script.onload = () => {
+      // @ts-ignore
+      window.EssentiaWASM().then((wasmModule: any) => {
+        essentia = new wasmModule.EssentiaJS(false);
+        essentia.arrayToVector = wasmModule.arrayToVector;
+      });
+    };
+    document.head.appendChild(script);
+  }
+
+  function createInferenceWorker() {
+    inferenceWorker = new Worker(`${basePath}workers/inference.js`);
+    inferenceWorker.onmessage = function listenToWorker(msg) {
+      if (msg.data.predictions) {
+        const preds = msg.data.predictions;
+
+        moodResults.value.forEach((mood) => {
+          mood.value = Math.ceil(preds[mood.key] * 100);
+        });
+      }
+    };
+  }
+
+  function createFeatureExtractionWorker() {
+    featureExtractionWorker = new Worker(`${basePath}workers/featureExtraction.js`);
+    featureExtractionWorker.postMessage({
+      init: true,
+    });
+    featureExtractionWorker.onmessage =
+      // @ts-ignore
+      function listenToFeatureExtractionWorker(msg) {
+        // feed to models
+        if (msg.data.embeddings) {
+          inferenceStartTime = Date.now();
+          // send features off to each of the models
+          inferenceWorker.postMessage({
+            embeddings: msg.data.embeddings,
+          });
+          // msg.data.embeddings = null;
+        }
+        // free worker resource until next audio is uploaded
+        // featureExtractionWorker.terminate();
+      };
+  }
+
+  function monomix(buffer: AudioBuffer) {
+    // downmix to mono
+    let monoAudio;
+    if (buffer.numberOfChannels > 1) {
+      const leftCh = buffer.getChannelData(0);
+      const rightCh = buffer.getChannelData(1);
+      // @ts-ignore
+      monoAudio = leftCh.map((sample, i) => 0.5 * (sample + rightCh[i]));
+    } else {
+      monoAudio = buffer.getChannelData(0);
+    }
+
+    return monoAudio;
+  }
+
+  function shortenAudio(audioIn: Float32Array, keepRatio = 0.5, trim = false) {
+    /*
+        keepRatio applied after discarding start and end (if trim == true)
+    */
+    if (keepRatio < 0.15) {
+      keepRatio = 0.15; // must keep at least 15% of the file
+    } else if (keepRatio > 0.66) {
+      keepRatio = 0.66; // will keep at most 2/3 of the file
+    }
+
+    if (trim) {
+      const discardSamples = Math.floor(0.1 * audioIn.length); // discard 10% on beginning and end
+      audioIn = audioIn.subarray(discardSamples, audioIn.length - discardSamples); // create new view of buffer without beginning and end
+    }
+
+    const ratioSampleLength = Math.ceil(audioIn.length * keepRatio);
+    const patchSampleLength = 187 * 256; // cut into patchSize chunks so there's no weird jumps in audio
+    const numPatchesToKeep = Math.ceil(ratioSampleLength / patchSampleLength);
+
+    // space patchesToKeep evenly
+    const skipSize = Math.floor((audioIn.length - ratioSampleLength) / (numPatchesToKeep - 1));
+
+    let audioOut = [];
+    let startIndex = 0;
+    for (let i = 0; i < numPatchesToKeep; i++) {
+      let endIndex = startIndex + patchSampleLength;
+      let chunk = audioIn.slice(startIndex, endIndex);
+      audioOut.push(...chunk);
+      startIndex = endIndex + skipSize; // discard even space
+    }
+
+    return Float32Array.from(audioOut);
+  }
+
+  function downsampleArray(audioIn: Float32Array, sampleRateIn: number, sampleRateOut: number) {
+    if (sampleRateOut === sampleRateIn) {
+      return audioIn;
+    }
+    let sampleRateRatio = sampleRateIn / sampleRateOut;
+    let newLength = Math.round(audioIn.length / sampleRateRatio);
+    let result = new Float32Array(newLength);
+    let offsetResult = 0;
+    let offsetAudioIn = 0;
+
+    while (offsetResult < result.length) {
+      let nextOffsetAudioIn = Math.round((offsetResult + 1) * sampleRateRatio);
+      let accum = 0,
+        count = 0;
+      for (let i = offsetAudioIn; i < nextOffsetAudioIn && i < audioIn.length; i++) {
+        // @ts-ignore
+        accum += audioIn[i];
+        count++;
+      }
+      result[offsetResult] = accum / count;
+      offsetResult++;
+      offsetAudioIn = nextOffsetAudioIn;
+    }
+
+    return result;
+  }
+
+  function median(arr: number[]) {
+    if (arr.length === 0) return 0;
+    const sorted = [...arr].sort((a, b) => a - b);
+    const mid = Math.floor(sorted.length / 2);
+    return sorted.length % 2 === 0 ? (sorted[mid - 1] + sorted[mid]) / 2 : sorted[mid];
+  }
+
+  function estimateTuningFrequency(vectorSignal: any, sampleRate = 16000) {
+    // Параметры для pitch-экстракции
+    const frameSize = 2048;
+    const hopSize = 512;
+    const minFreq = 80; // игнорируем басы и шум
+    const maxFreq = 1500; // выше — уже не вокал/мелодия
+    const confidenceThreshold = 0.7;
+    const silenceThreshold = 0.001; // чувствительность к тишине
+
+    // ✅ Теперь 7 аргументов!
+    const pitchResult = essentia.PitchYinFFT(
+      vectorSignal,
+      sampleRate,
+      frameSize,
+      hopSize,
+      minFreq,
+      maxFreq,
+      silenceThreshold
+    );
+
+    const centsDeviations = [];
+
+    for (let i = 0; i < pitchResult.pitch.length; i++) {
+      const freq = pitchResult.pitch[i];
+      const conf = pitchResult.pitchConfidence[i];
+
+      // Фильтруем ненадёжные и нерелевантные частоты
+      if (freq >= minFreq && freq <= maxFreq && conf >= confidenceThreshold) {
+        // MIDI note относительно A4=440 (MIDI 69)
+        const midiNote = 69 + 12 * Math.log2(freq / 440);
+        const roundedMidi = Math.round(midiNote);
+        const cents = (midiNote - roundedMidi) * 100; // отклонение в центах
+
+        // Ограничиваем выбросы (иногда pitch скачет)
+        if (Math.abs(cents) < 50) {
+          centsDeviations.push(cents);
+        }
+      }
+    }
+
+    // Если мало данных — возвращаем 440 по умолчанию
+    if (centsDeviations.length < 10) {
+      console.warn("Недостаточно надёжных данных для оценки строя. Используется A=440.");
+      return 440;
+    }
+
+    const medianCents = median(centsDeviations);
+    const estimatedA = 440 * Math.pow(2, medianCents / 1200);
+
+    // Ограничиваем разумные пределы (обычно A=432–445)
+    return Math.max(430, Math.min(450, estimatedA));
+  }
+
+  function preprocess(audioBuffer: AudioBuffer) {
+    if (audioBuffer instanceof AudioBuffer) {
+      const mono = monomix(audioBuffer);
+      // downmix to mono, and downsample to 16kHz sr for essentia tensorflow models
+      return downsampleArray(mono, audioBuffer.sampleRate, 16000);
+    } else {
+      throw new TypeError("Input to audio preprocessing is not of type AudioBuffer");
+    }
+  }
+
+  function computeKeyBPM(audioSignal: Float32Array) {
+    let vectorSignal = essentia.arrayToVector(audioSignal);
+
+    // const estimatedA = estimateTuningFrequency(vectorSignal, 16000);
+    // console.log("Оценка строя:", estimatedA.toFixed(2), "Гц"); // например: 439.12
+
+    const keyData = essentia.KeyExtractor(
+      vectorSignal,
+      true,
+      4096,
+      4096,
+      12,
+      3500,
+      60,
+      25,
+      0.2,
+      "bgate",
+      16000,
+      0.0001,
+      440,
+      "cosine",
+      "hann"
+    );
+    const bpm = essentia.PercivalBpmEstimator(
+      vectorSignal,
+      1024,
+      2048,
+      128,
+      128,
+      210,
+      50,
+      16000
+    ).bpm;
+
+    return {
+      keyData: keyData,
+      bpm: bpm,
+    };
+  }
+
+  function processFile(arrayBuffer: ArrayBuffer) {
+    audioCtx.resume().then(() => {
+      audioCtx.decodeAudioData(arrayBuffer).then(async function handleDecodedAudio(audioBuffer) {
+        const prepocessedAudio = preprocess(audioBuffer);
+        await audioCtx.suspend();
+
+        if (essentia) {
+          essentiaAnalysis = computeKeyBPM(prepocessedAudio);
+
+          keyBpmResults.value = {
+            key: essentiaAnalysis.keyData.key,
+            scale: essentiaAnalysis.keyData.scale,
+            bpm: (essentiaAnalysis.bpm <= 69
+              ? essentiaAnalysis.bpm * 2
+              : essentiaAnalysis.bpm
+            ).toFixed(2),
+          };
+        }
+
+        // reduce amount of audio to analyse
+        let audioData = shortenAudio(prepocessedAudio, KEEP_PERCENTAGE, true); // <-- TRIMMED start/end
+
+        // send for feature extraction
+        featureExtractionWorker.postMessage(
+          {
+            audio: audioData.buffer,
+          },
+          [audioData.buffer]
+        );
+        // @ts-ignore
+        audioData = null;
+      });
+    });
+  }
+
+  const getKeyMoodAndBpm = async (file: File) => {
+    file.arrayBuffer().then((arrayBuffer: ArrayBuffer) => {
+      processFile(arrayBuffer);
+    });
+  };
+
+  const resetMoodResults = () => {
+    moodResults.value.forEach((moodResult) => {
+      moodResult.value = 0;
+    });
+  };
+
+  return {
+    getKeyMoodAndBpm,
+    keyBpmResults,
+    moodResults,
+    resetMoodResults,
+    essentia,
+    essentiaAnalysis,
+    featureExtractionWorker
+  };
+};