@sorisdk/web-audio

Web SDK for integrating SORI audio recognition into browser-based services.

This package provides the browser-side flow needed for web recognition, including authentication bootstrap, pack caching, microphone input, audio fingerprint generation, matching, and campaign events.

Public integration guide: https://docs.soriapi.com/ko/integration/web

Requirements

• A secure context such as https:// or http://localhost
• A modern browser with AudioContext and MediaDevices.getUserMedia()
• An ephemeral key issued by your server
• Microphone permission granted by the user

Installation

npm install @sorisdk/web-audio

Vite-based apps need vite-plugin-wasm.

import wasm from "vite-plugin-wasm";

export default {
  plugins: [wasm()]
};

The default wasm initialization path is intended to work in both Vite dev/build and Nuxt client production bundles without extra loader patching.

Minimal example

import { AudioRecognizer } from "@sorisdk/web-audio";

const recognizer = new AudioRecognizer({
  appId: "YOUR_APP_ID",
  ephemeralKey: async () => {
    const response = await fetch("/api/ephemeral-key", {
      method: "POST"
    });

    if (!response.ok) {
      throw new Error(`Ephemeral key request failed: HTTP ${response.status}`);
    }

    const { ephemeral_key } = await response.json();
    return ephemeral_key;
  }
});

recognizer.on("campaign", (event) => {
  console.log(event.campaign);
});

recognizer.on("error", ({ error }) => {
  console.error(error);
});

await recognizer.start();

Call stop() or destroy() when recognition should end or when the page is being cleaned up.

await recognizer.stop();
await recognizer.destroy();

Advanced wasm loading overrides

If you need to pin explicit generated modules, use the nested wasm options:

import { AudioRecognizer } from "@sorisdk/web-audio";

const recognizer = new AudioRecognizer({
  appId: "YOUR_APP_ID",
  ephemeralKey: async () => "YOUR_EPHEMERAL_KEY",
  wasm: {
    afpgen: {
      loader: () => import("@sorisdk/afpgen/generated/core.js")
    },
    matcher: {
      loader: () => import("@sorisdk/matcher/generated/core.js")
    },
    matchWindow: {
      loader: () => import("@sorisdk/web-audio/generated/window.js")
    }
  }
});

Integration flow

1. Prepare your appId and ephemeral key flow.
2. Create an AudioRecognizer.
3. Subscribe to the events you need, such as campaign, match, and error.
4. Call start() to begin recognition.
5. Call stop() or destroy() when leaving the page or stopping capture.

Recommendations

• Do not hardcode ephemeral keys in the browser. Issue them from your server.
• Show clear UI while the microphone is active.
• Use the public documentation for full setup details and caveats.