@sorisdk/web-audio 0.1.0 → 0.1.1

package/README.md

@@ -1,98 +1,83 @@
 # @sorisdk/web-audio
 
-Browser microphone capture and real-time matching SDK for NADA.
+Web SDK for integrating SORI audio recognition into browser-based services.
 
-## Purpose
+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.
 
-This package owns browser-only concerns that do not belong in `@sorisdk/matcher`:
+Public integration guide: https://docs.soriapi.com/ko/integration/web
 
-- microphone permission and `getUserMedia`
-- Web Audio graph setup
-- PCM chunk capture
-- rolling fingerprint generation with `@sorisdk/afpgen`
-- rolling query matching with `@sorisdk/matcher`
+## Requirements
 
-## API
+- 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
 
-```ts
-import { AudioRecognizer } from "@sorisdk/web-audio";
-
-const recognizer = new AudioRecognizer({
-  appId: "app-1",
-  ephemeralKeyEndpoint: "https://site.example.com/api/ephemeral-key"
-});
-
-recognizer.on("campaign", (event) => {
-  console.log(event.campaign);
-});
+## Installation
 
-await recognizer.start();
-await recognizer.stop();
-await recognizer.destroy();
+```bash
+npm install @sorisdk/web-audio
 ```
 
-By default, `AudioRecognizer` uses the SORI API prefix `https://console.soriapi.com/api`
-and derives:
-
-- auth: `/auth`
-- activity: `/activity/`
-
-So direct ephemeral key usage can be as small as:
+Vite-based apps need `vite-plugin-wasm`.
 
 ```ts
-const recognizer = new AudioRecognizer({
-  appId: "app-1",
-  ephemeralKey: "ek-..."
-});
-```
+import wasm from "vite-plugin-wasm";
 
-## Notes
+export default {
+  plugins: [wasm()]
+};
+```
 
-- This package is browser-only.
-- It uses `AudioWorkletNode` when available and falls back to `ScriptProcessorNode`.
-- Matching window size and matching-quality-sensitive runtime tuning stay internal to the SDK.
+## Minimal example
 
-## Session Utility
+```ts
+import { AudioRecognizer } from "@sorisdk/web-audio";
 
-When you need direct control over the browser session identifier, use the built-in
-session manager instead of handling `localStorage` yourself:
+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;
+  }
+});
 
-```ts
-import { createLocalStorageSessionManager } from "@sorisdk/web-audio";
+recognizer.on("campaign", (event) => {
+  console.log(event.campaign);
+});
 
-const sessions = createLocalStorageSessionManager({
-  key: "sorisdk:web-audio:session:app-1"
+recognizer.on("error", ({ error }) => {
+  console.error(error);
 });
 
-const sessionId = sessions.getSessionId();
+await recognizer.start();
 ```
 
-## Low-Level Auth Cache Helper
-
-When `/api/auth` requires a `v` value, the browser package can keep the last successful
-`version + packUrl` metadata in `localStorage` while leaving the actual audiopack bytes to
-the browser HTTP cache:
+Call `stop()` or `destroy()` when recognition should end or when the page is being cleaned up.
 
 ```ts
-import {
-  authenticateAndLoadAudioPack,
-  createLocalStorageAudioPackStore
-} from "@sorisdk/web-audio";
+await recognizer.stop();
+await recognizer.destroy();
+```
 
-const store = createLocalStorageAudioPackStore({
-  key: "sorisdk:matcher:app-1"
-});
+## Integration flow
 
-const result = await authenticateAndLoadAudioPack({
-  loader: microphoneMatcher,
-  auth: {
-    endpoint: "https://console.example.com/api/auth",
-    appId: "app-1",
-    ephemeralKey: "ek-...",
-    sessionId: "browser-device-1"
-  },
-  store
-});
+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.
 
-console.log(result.token, result.loadedPackUrl, result.persistedVersion);
-```
+## 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.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sorisdk/web-audio",
-  "version": "0.1.0",
-  "description": "Browser microphone capture and real-time matching SDK for NADA",
+  "version": "0.1.1",
+  "description": "Web SDK for browser-based audio recognition with SORI API",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -32,18 +32,10 @@
   ],
   "author": "comfuture",
   "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/iplateia/nada.git",
-    "directory": "packages/web-audio"
-  },
-  "homepage": "https://github.com/iplateia/nada/tree/main/packages/web-audio",
-  "bugs": {
-    "url": "https://github.com/iplateia/nada/issues"
-  },
+  "homepage": "https://docs.soriapi.com/ko/integration/web",
   "dependencies": {
-    "@sorisdk/afpgen": "0.1.0",
-    "@sorisdk/matcher": "0.1.0"
+    "@sorisdk/afpgen": "0.1.1",
+    "@sorisdk/matcher": "0.1.1"
   },
   "devDependencies": {
     "tsup": "^8.5.1",