@camstack/addon-pipeline 0.1.8

package/dist/audio-analyzer/index.js

@@ -0,0 +1,723 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+Object.defineProperties(exports, { __esModule: { value: true }, [Symbol.toStringTag]: { value: "Module" } });
+const types = require("@camstack/types");
+const path = require("node:path");
+const fs = require("node:fs");
+const core = require("@camstack/core");
+function _interopNamespaceDefault(e) {
+  const n = Object.create(null, { [Symbol.toStringTag]: { value: "Module" } });
+  if (e) {
+    for (const k in e) {
+      if (k !== "default") {
+        const d = Object.getOwnPropertyDescriptor(e, k);
+        Object.defineProperty(n, k, d.get ? d : {
+          enumerable: true,
+          get: () => e[k]
+        });
+      }
+    }
+  }
+  n.default = e;
+  return Object.freeze(n);
+}
+const path__namespace = /* @__PURE__ */ _interopNamespaceDefault(path);
+const fs__namespace = /* @__PURE__ */ _interopNamespaceDefault(fs);
+async function createAudioPipeline(modelsDir, logger, options) {
+  const backend = options?.backend ?? (process.platform === "darwin" ? "apple-soundanalysis" : "yamnet-onnx");
+  if (backend === "apple-soundanalysis") {
+    return new AppleSoundAnalysisPipeline(logger);
+  }
+  return new YamnetOnnxPipeline(modelsDir, logger);
+}
+const YAMNET_MODEL_URL = `${types.HF_BASE_URL}/audioClassification/yamnet/onnx/camstack-yamnet.onnx`;
+const YAMNET_LABELS_URL = `${types.HF_BASE_URL}/audioClassification/yamnet/camstack-yamnet-labels.json`;
+class YamnetOnnxPipeline {
+  constructor(modelsDir, logger) {
+    this.modelsDir = modelsDir;
+    this.log = logger;
+  }
+  session = null;
+  inputName = "";
+  labels = [];
+  log;
+  async initialize() {
+    const ort = await import("onnxruntime-node");
+    const modelPath = path__namespace.join(this.modelsDir, "camstack-yamnet.onnx");
+    const labelsPath = path__namespace.join(this.modelsDir, "camstack-yamnet-labels.json");
+    if (!fs__namespace.existsSync(modelPath)) {
+      this.log.info("YAMNet ONNX model not found locally — downloading from HuggingFace", {
+        meta: { url: YAMNET_MODEL_URL, dest: modelPath }
+      });
+      await core.downloadFile(YAMNET_MODEL_URL, modelPath);
+      this.log.info("YAMNet ONNX model downloaded", {
+        meta: { sizeBytes: fs__namespace.statSync(modelPath).size }
+      });
+    }
+    if (!fs__namespace.existsSync(labelsPath)) {
+      this.log.info("YAMNet labels not found locally — downloading from HuggingFace", {
+        meta: { url: YAMNET_LABELS_URL, dest: labelsPath }
+      });
+      await core.downloadFile(YAMNET_LABELS_URL, labelsPath);
+    }
+    this.session = await ort.InferenceSession.create(modelPath);
+    this.inputName = this.session.inputNames[0] ?? "waveform";
+    if (fs__namespace.existsSync(labelsPath)) {
+      this.labels = JSON.parse(fs__namespace.readFileSync(labelsPath, "utf8"));
+    } else {
+      this.log.warn("YAMNet labels file not found — classifications will use numeric indices");
+    }
+    this.log.info(`YAMNet ONNX pipeline initialized (${this.labels.length} labels)`);
+  }
+  async classify(chunk) {
+    if (!this.session) {
+      throw new Error("YAMNet pipeline not initialized");
+    }
+    const start = Date.now();
+    const ort = await import("onnxruntime-node");
+    const waveform = chunk.sampleRate === 16e3 && chunk.channels === 1 ? chunk.data : resampleMono16k(chunk);
+    const tensor = new ort.Tensor("float32", waveform, [waveform.length]);
+    const feeds = { [this.inputName]: tensor };
+    const results = await this.session.run(feeds);
+    const scoresData = results[this.session.outputNames[0]];
+    if (!scoresData) {
+      throw new Error("YAMNet returned no output");
+    }
+    const scores = scoresData.data;
+    const numClasses = 521;
+    const numFrames = scores.length / numClasses;
+    const avgScores = new Float32Array(numClasses);
+    for (let f = 0; f < numFrames; f++) {
+      for (let c = 0; c < numClasses; c++) {
+        avgScores[c] += scores[f * numClasses + c];
+      }
+    }
+    for (let c = 0; c < numClasses; c++) {
+      avgScores[c] = avgScores[c] / numFrames;
+    }
+    const minScore = 0.05;
+    const classifications = [];
+    for (let c = 0; c < numClasses; c++) {
+      const score = avgScores[c];
+      if (score >= minScore) {
+        const label = c < this.labels.length ? this.labels[c] : String(c);
+        classifications.push({ className: label, score: Math.round(score * 1e3) / 1e3 });
+      }
+    }
+    classifications.sort((a, b) => b.score - a.score);
+    return {
+      classifications: classifications.slice(0, 10),
+      inferenceMs: Date.now() - start
+    };
+  }
+  async dispose() {
+    if (this.session) {
+      await this.session.release();
+      this.session = null;
+    }
+  }
+}
+class AppleSoundAnalysisPipeline {
+  log;
+  process = null;
+  receiveBuffer = Buffer.alloc(0);
+  pendingResolve = null;
+  pendingReject = null;
+  binaryPath = null;
+  debugCount = 0;
+  constructor(logger) {
+    this.log = logger;
+  }
+  async initialize() {
+    this.binaryPath = await this.resolveSwiftBinary();
+    if (!this.binaryPath) {
+      throw new Error("Apple SoundAnalysis: Swift CLI not found and compilation failed. macOS with Xcode CLI tools required.");
+    }
+    const { spawn } = await import("node:child_process");
+    this.process = spawn(this.binaryPath, ["--sample-rate=16000", "--top-k=10"], {
+      stdio: ["pipe", "pipe", "pipe"]
+    });
+    this.process.stderr?.on("data", (chunk) => {
+      const lines = chunk.toString().split("\n");
+      for (const line of lines) {
+        const trimmed = line.trim();
+        if (trimmed) this.log.warn(trimmed);
+      }
+    });
+    this.process.on("error", (err) => {
+      this.log.error("Swift process error", { meta: { error: err.message } });
+      this.pendingReject?.(err);
+      this.pendingReject = null;
+      this.pendingResolve = null;
+    });
+    this.process.on("exit", (code) => {
+      if (code !== 0 && code !== null) {
+        this.log.error("Swift process exited", { meta: { code } });
+        const err = new Error(`Apple SoundAnalysis: process exited with code ${code}`);
+        this.pendingReject?.(err);
+        this.pendingReject = null;
+        this.pendingResolve = null;
+      }
+    });
+    this.process.stdout.on("data", (chunk) => {
+      this.receiveBuffer = Buffer.concat([this.receiveBuffer, chunk]);
+      this.tryReceive();
+    });
+    const ready = await this.receiveMessage();
+    if (ready["status"] !== "ready") {
+      throw new Error(`Apple SoundAnalysis: unexpected init response: ${JSON.stringify(ready)}`);
+    }
+    this.log.info("Apple SoundAnalysis pipeline initialized (macOS built-in, Swift CLI bridge)");
+  }
+  async classify(chunk) {
+    if (!this.process?.stdin) {
+      throw new Error("Apple SoundAnalysis: process not initialized");
+    }
+    const waveform = chunk.sampleRate === 16e3 && chunk.channels === 1 ? chunk.data : resampleMono16k(chunk);
+    const audioBuffer = Buffer.from(waveform.buffer, waveform.byteOffset, waveform.byteLength);
+    const lengthBuf = Buffer.allocUnsafe(4);
+    lengthBuf.writeUInt32LE(audioBuffer.length, 0);
+    this.process.stdin.write(Buffer.concat([lengthBuf, audioBuffer]));
+    const result = await this.receiveMessage();
+    const classifications = result["classifications"] ?? [];
+    const inferenceMs = result["inferenceMs"] ?? 0;
+    if (this.debugCount < 3) {
+      const keys = Object.keys(result);
+      this.log.info("classify debug sample", {
+        meta: {
+          phase: "apple-sa",
+          index: this.debugCount,
+          keys,
+          classifications: classifications.length,
+          inferenceMs,
+          audioBytes: Buffer.from(chunk.data.buffer, chunk.data.byteOffset, chunk.data.byteLength).length,
+          sampleRate: chunk.sampleRate,
+          channels: chunk.channels
+        }
+      });
+      if (result["error"]) {
+        this.log.error("Swift error", { meta: { phase: "apple-sa", error: result["error"] } });
+      }
+      this.debugCount++;
+    }
+    return { classifications, inferenceMs };
+  }
+  async dispose() {
+    const proc = this.process;
+    if (!proc) return;
+    this.process = null;
+    proc.stdin?.end();
+    proc.kill("SIGTERM");
+    const exited = await new Promise((resolve) => {
+      const timer = setTimeout(() => resolve(false), 5e3);
+      proc.once("exit", () => {
+        clearTimeout(timer);
+        resolve(true);
+      });
+    });
+    if (!exited) {
+      try {
+        proc.kill("SIGKILL");
+      } catch {
+      }
+      this.log.warn("Swift process did not exit gracefully — sent SIGKILL");
+    }
+  }
+  receiveMessage() {
+    return new Promise((resolve, reject) => {
+      this.pendingResolve = resolve;
+      this.pendingReject = reject;
+    });
+  }
+  tryReceive() {
+    if (this.receiveBuffer.length < 4) return;
+    const length = this.receiveBuffer.readUInt32LE(0);
+    if (this.receiveBuffer.length < 4 + length) return;
+    const jsonBytes = this.receiveBuffer.subarray(4, 4 + length);
+    this.receiveBuffer = this.receiveBuffer.subarray(4 + length);
+    const resolve = this.pendingResolve;
+    const reject = this.pendingReject;
+    this.pendingResolve = null;
+    this.pendingReject = null;
+    if (!resolve) return;
+    try {
+      const parsed = JSON.parse(jsonBytes.toString("utf8"));
+      resolve(parsed);
+    } catch (err) {
+      reject?.(err instanceof Error ? err : new Error(String(err)));
+    }
+  }
+  /** Find pre-compiled binary or compile from Swift source. */
+  async resolveSwiftBinary() {
+    const candidates = [
+      path__namespace.join(__dirname, "../../swift/audio-analyzer/apple-sound-classifier"),
+      // Fallback for in-tree dev (src/<id>/swift/) and pre-merge layouts.
+      path__namespace.join(__dirname, "../swift/apple-sound-classifier"),
+      path__namespace.join(__dirname, "../../swift/apple-sound-classifier"),
+      path__namespace.join(__dirname, "../../../swift/apple-sound-classifier")
+    ];
+    for (const p of candidates) {
+      if (fs__namespace.existsSync(p)) {
+        this.log.info("Found pre-compiled Swift CLI", { meta: { path: p } });
+        return p;
+      }
+    }
+    const sourceCandidates = [
+      path__namespace.join(__dirname, "../../swift/audio-analyzer/apple-sound-classifier.swift"),
+      path__namespace.join(__dirname, "../swift/apple-sound-classifier.swift"),
+      path__namespace.join(__dirname, "../../swift/apple-sound-classifier.swift"),
+      path__namespace.join(__dirname, "../../../swift/apple-sound-classifier.swift")
+    ];
+    const sourcePath = sourceCandidates.find((p) => fs__namespace.existsSync(p));
+    if (!sourcePath) {
+      this.log.error("Swift source not found", { meta: { searched: sourceCandidates } });
+      return null;
+    }
+    const outputPath = sourcePath.replace(".swift", "");
+    this.log.info("Compiling Swift CLI...", { meta: { source: sourcePath, output: outputPath } });
+    const { execFileSync } = await import("node:child_process");
+    try {
+      execFileSync("swiftc", ["-O", "-o", outputPath, sourcePath], {
+        timeout: 6e4,
+        stdio: "pipe"
+      });
+      this.log.info("Swift CLI compiled successfully");
+      return outputPath;
+    } catch (err) {
+      this.log.error("Swift compilation failed — install Xcode Command Line Tools", {
+        meta: { error: types.errMsg(err) }
+      });
+      return null;
+    }
+  }
+}
+function resampleMono16k(chunk) {
+  const { data, sampleRate, channels } = chunk;
+  const numSamples = data.length / channels;
+  const mono = new Float32Array(numSamples);
+  for (let i = 0; i < numSamples; i++) {
+    let sum = 0;
+    for (let c = 0; c < channels; c++) {
+      sum += data[i * channels + c];
+    }
+    mono[i] = sum / channels;
+  }
+  const ratio = 16e3 / sampleRate;
+  const outLen = Math.floor(numSamples * ratio);
+  const out = new Float32Array(outLen);
+  for (let i = 0; i < outLen; i++) {
+    const srcIdx = i / ratio;
+    const lo = Math.floor(srcIdx);
+    const hi = Math.min(lo + 1, numSamples - 1);
+    const frac = srcIdx - lo;
+    out[i] = mono[lo] * (1 - frac) + mono[hi] * frac;
+  }
+  return out;
+}
+const AUDIO_MODEL_OPTIONS = [
+  { value: "", label: "Auto (matches backend)" },
+  { value: "yamnet-onnx", label: "YAMNet (ONNX)" },
+  { value: "apple-soundanalysis", label: "Apple SoundAnalysis (built-in)" }
+];
+const CLASSIFY_ERROR_SUPPRESS_MS = 3e4;
+const CLASSIFY_MIN_INTERVAL_MS = 500;
+const GLOBAL_DEVICE_KEY = -1;
+class AudioAnalyzerProvider {
+  constructor(logger, pipeline, backendName, deviceSettingsResolver, deviceContributionResolver, deviceSettingsPatcher, reprobeImpl) {
+    this.pipeline = pipeline;
+    this.deviceSettingsResolver = deviceSettingsResolver;
+    this.deviceContributionResolver = deviceContributionResolver;
+    this.deviceSettingsPatcher = deviceSettingsPatcher;
+    this.reprobeImpl = reprobeImpl;
+    this.log = logger;
+    this.backendName = backendName;
+  }
+  log;
+  classifyCallCount = 0;
+  lastClassifyErrorMs = 0;
+  suppressedClassifyErrors = 0;
+  classifyCount = 0;
+  backendName = "unknown";
+  /** Per-camera in-flight state. Key = deviceId (or GLOBAL_DEVICE_KEY for legacy callers). */
+  cameraState = /* @__PURE__ */ new Map();
+  /** Global pipeline lock — Apple SA and ONNX are single-channel: only one classify() can
+   *  run at a time. Without this, concurrent calls from different cameras overwrite the
+   *  single pendingResolve slot in AppleSoundAnalysisPipeline, causing 30s timeouts. */
+  pipelineBusy = false;
+  // ── Device-details aggregator contribution ──────────────────────────────
+  async getDeviceSettingsContribution(input) {
+    return this.deviceContributionResolver(input.deviceId);
+  }
+  async getDeviceLiveContribution(_input) {
+    return null;
+  }
+  async applyDeviceSettingsPatch(input) {
+    await this.deviceSettingsPatcher(input.deviceId, input.patch);
+    return { success: true };
+  }
+  /**
+   * Return the effective per-device audio-analyzer settings, resolved via
+   * the kernel's 3-level settings resolver (schema default → global →
+   * device override). Orchestrator consumers call this method so they
+   * never need to know the audio-analyzer schema field names.
+   */
+  async resolveDeviceSettings({ deviceId }) {
+    return this.deviceSettingsResolver(deviceId);
+  }
+  async analyseChunk({
+    chunk,
+    settings
+  }) {
+    const samples = chunk.data;
+    let sumSquares = 0;
+    for (let i = 0; i < samples.length; i++) {
+      sumSquares += samples[i] * samples[i];
+    }
+    const rms = Math.sqrt(sumSquares / samples.length);
+    const dbfs = rms > 0 ? 20 * Math.log10(rms) : -96;
+    const level = {
+      rms: Math.round(rms * 1e4) / 1e4,
+      dbfs: Math.round(dbfs * 10) / 10
+    };
+    let classification;
+    try {
+      const result = await this.classify(chunk);
+      if (this.classifyCallCount < 3) {
+        const topRaw = result.labels.slice(0, 5).map((l) => `${l.className}(${(l.score * 100).toFixed(0)}%)`).join(", ");
+        this.log.info("classify debug sample", {
+          tags: chunk.deviceId !== void 0 ? { deviceId: chunk.deviceId } : void 0,
+          meta: {
+            index: this.classifyCallCount,
+            labelCount: result.labels.length,
+            top: topRaw,
+            inferenceMs: result.inferenceMs,
+            minConf: settings.minConfidence,
+            allowedClasses: settings.allowedClasses
+          }
+        });
+      }
+      this.classifyCallCount++;
+      if (result.inferenceMs > 0) {
+        const minConf = settings.minConfidence;
+        const allowedSet = settings.allowedClasses.length > 0 ? new Set(settings.allowedClasses.map((c) => c.toLowerCase())) : null;
+        let filtered = result.labels.filter((c) => c.score >= minConf);
+        if (allowedSet) {
+          filtered = filtered.filter((c) => allowedSet.has(c.className.toLowerCase()));
+        }
+        if (filtered.length > 0) {
+          classification = {
+            labels: filtered,
+            inferenceMs: result.inferenceMs
+          };
+        }
+      }
+    } catch (err) {
+      const now = Date.now();
+      const sinceLastMs = now - this.lastClassifyErrorMs;
+      if (sinceLastMs >= CLASSIFY_ERROR_SUPPRESS_MS) {
+        const suppressed = this.suppressedClassifyErrors;
+        this.suppressedClassifyErrors = 0;
+        this.lastClassifyErrorMs = now;
+        const msg = types.errMsg(err);
+        const stack = err instanceof Error ? err.stack : void 0;
+        this.log.warn("Audio classification failed", {
+          tags: chunk.deviceId !== void 0 ? { deviceId: chunk.deviceId } : void 0,
+          meta: { error: msg, stack, suppressedSince: suppressed > 0 ? suppressed : void 0 }
+        });
+      } else {
+        this.suppressedClassifyErrors++;
+      }
+    }
+    return { level, classification, timestamp: chunk.timestamp };
+  }
+  async classify(chunk) {
+    const camKey = chunk.deviceId ?? GLOBAL_DEVICE_KEY;
+    const now = Date.now();
+    const state = this.cameraState.get(camKey);
+    if (state?.inProgress || state !== void 0 && now - state.lastEndMs < CLASSIFY_MIN_INTERVAL_MS) {
+      return { labels: [], rawLabels: [], inferenceMs: 0 };
+    }
+    if (this.pipelineBusy) {
+      return { labels: [], rawLabels: [], inferenceMs: 0 };
+    }
+    this.cameraState.set(camKey, { inProgress: true, lastEndMs: state?.lastEndMs ?? 0 });
+    this.pipelineBusy = true;
+    const result = await this.pipeline.classify({
+      data: chunk.data,
+      sampleRate: chunk.sampleRate,
+      channels: chunk.channels
+    }).finally(() => {
+      this.pipelineBusy = false;
+      this.cameraState.set(camKey, { inProgress: false, lastEndMs: Date.now() });
+    });
+    if (this.classifyCount < 3 || this.classifyCount % 100 === 0) {
+      const rawTop = result.classifications.slice(0, 5).map((c) => `"${c.className}"(${(c.score * 100).toFixed(0)}%)`).join(", ");
+      this.log.info("classify debug sample", {
+        tags: chunk.deviceId !== void 0 ? { deviceId: chunk.deviceId } : void 0,
+        meta: {
+          index: this.classifyCount,
+          engine: this.backendName,
+          rawLabelCount: result.classifications.length,
+          top: rawTop,
+          inferenceMs: result.inferenceMs
+        }
+      });
+    }
+    this.classifyCount++;
+    const macroAccum = /* @__PURE__ */ new Map();
+    for (const c of result.classifications) {
+      const macro = types.mapAudioLabelToMacro(c.className);
+      if (!macro) continue;
+      const prev = macroAccum.get(macro);
+      if (!prev || c.score > prev.score) {
+        macroAccum.set(macro, { score: c.score, rawTop: c.className });
+      }
+    }
+    const labels = [...macroAccum.entries()].sort((a, b) => b[1].score - a[1].score).map(([className, { score, rawTop }]) => ({ className, originalClass: rawTop, score }));
+    const rawLabels = [...result.classifications].sort((a, b) => b.score - a.score).map((c) => ({ className: c.className, originalClass: c.className, score: c.score }));
+    return { labels, rawLabels, inferenceMs: result.inferenceMs };
+  }
+  isReady() {
+    return this.pipeline !== null;
+  }
+  async dispose() {
+    await this.pipeline.dispose();
+  }
+  // Expose via the cap so the reprobe button in the UI reaches the
+  // right worker. Delegates to the addon-owned reprobe (it touches
+  // `ctx.settings.writeAddonStore` which only the addon has access to).
+  async reprobeAudioEngine() {
+    return this.reprobeImpl();
+  }
+}
+class AudioAnalyzerAddon extends types.BaseAddon {
+  id = "audio-analyzer";
+  provider = null;
+  pipeline = null;
+  constructor() {
+    super(types.DEFAULT_AUDIO_ANALYZER_CONFIG);
+  }
+  globalSettingsSchema() {
+    return {
+      sections: [
+        {
+          id: "audio-engine",
+          title: "Audio",
+          // Co-located with detection-pipeline's `engine` section under
+          // a single "Engine" tab. Both sections handle inference-engine
+          // selection but for different modalities — distinct purposes
+          // are conveyed through section titles ("Detection engine" vs
+          // "Audio inference engine") and descriptions, not separate
+          // tabs.
+          tab: "engine",
+          // Renders after detection-pipeline's `engine` section
+          // (`order: 0`) on the "Inference Engine" tab.
+          order: 10,
+          description: 'Audio classification backend (Apple SoundAnalysis or YAMNet ONNX). Independent from the vision-detection engine above. "Auto" picks Apple SoundAnalysis on macOS, YAMNet on Linux. Click the refresh icon next to "Probed best" to re-run the probe.',
+          // Field order — `probedBest*` lives at the top so the operator
+          // sees the auto-detected hint first and can compare it against
+          // their override below at a glance. Same convention as the
+          // detection-pipeline section.
+          fields: [
+            {
+              type: "text",
+              key: "probedBestAudioBackend",
+              label: "Probed best",
+              description: "Auto-detected best audio backend on this host. Click the refresh icon to re-run the probe.",
+              readonlyField: true,
+              default: "",
+              actions: [
+                { action: "reprobe-audio-engine", icon: "refresh-cw", tooltip: "Re-probe audio engine" }
+              ]
+            },
+            {
+              type: "select",
+              key: "audioBackend",
+              label: "Audio backend",
+              options: types.AUDIO_BACKEND_CHOICES.map((o) => ({ value: o.value, label: o.label })),
+              default: types.DEFAULT_AUDIO_ANALYZER_CONFIG.audioBackend,
+              immediate: true,
+              requiresRestart: true
+            },
+            {
+              type: "select",
+              key: "selectedAudioModel",
+              label: "Classification model",
+              description: "Empty = auto (matches backend). Device-level settings can only inherit / enable / disable this step; model + class filters live here at the node level.",
+              options: AUDIO_MODEL_OPTIONS.map((o) => ({ value: o.value, label: o.label })),
+              default: types.DEFAULT_AUDIO_ANALYZER_CONFIG.selectedAudioModel,
+              immediate: true,
+              requiresRestart: true
+            }
+          ]
+        }
+      ]
+    };
+  }
+  /**
+   * Cascade override — narrow the `selectedAudioModel` options to the
+   * subset compatible with the currently-selected `audioBackend`.
+   *
+   * Same pattern as detection-pipeline's `engineRuntime → engineBackend
+   *  → engineDevice` cascade: the base schema ships every option
+   *  (Auto + YAMNet + Apple SA); this override drops the rows that
+   *  belong to a backend the operator didn't pick. With `immediate:
+   *  true` on the `audioBackend` select, the UI refetches schema after
+   *  every flip and the model dropdown updates instantly.
+   *
+   * `overlay` carries the operator's tentative choices for benchmark/
+   *  preview mode (operator typed but didn't save yet) — same
+   *  semantics detection-pipeline relies on.
+   */
+  async getGlobalSettings(overlay) {
+    const ctx = this.ctxIfReady;
+    const stored = ctx?.settings ? await ctx.settings.readAddonStore() ?? {} : {};
+    const merged = overlay ? { ...stored, ...overlay } : stored;
+    const operatorChoice = typeof merged.audioBackend === "string" ? merged.audioBackend : types.DEFAULT_AUDIO_ANALYZER_CONFIG.audioBackend;
+    const effectiveBackend = operatorChoice === "apple-soundanalysis" ? "apple-soundanalysis" : operatorChoice === "yamnet-onnx" ? "yamnet-onnx" : process.platform === "darwin" ? "apple-soundanalysis" : "yamnet-onnx";
+    const filteredModels = AUDIO_MODEL_OPTIONS.filter(
+      (o) => o.value === "" || o.value === effectiveBackend
+    );
+    const storedModel = typeof merged.selectedAudioModel === "string" ? merged.selectedAudioModel : "";
+    const validModel = filteredModels.find((o) => o.value === storedModel)?.value ?? "";
+    const raw = { ...merged, selectedAudioModel: validModel };
+    const schema = this.globalSettingsSchema();
+    const patched = {
+      ...schema,
+      sections: schema.sections.map((section) => ({
+        ...section,
+        fields: section.fields.map((field) => {
+          if (field.type === "select" && field.key === "selectedAudioModel") {
+            return { ...field, options: filteredModels.map((o) => ({ value: o.value, label: o.label })) };
+          }
+          return field;
+        })
+      }))
+    };
+    return types.hydrateSchema(patched, raw);
+  }
+  /**
+   * Re-run the platform probe and persist the detected backend into
+   * `probedBestAudioBackend`. Operator `audioBackend` setting is not
+   * touched — only the hint.
+   */
+  async reprobeAudioEngine() {
+    const backend = process.platform === "darwin" ? "apple-soundanalysis" : "yamnet-onnx";
+    await this.ctx.settings?.writeAddonStore({ probedBestAudioBackend: backend });
+    this.ctx.logger.info("reprobeAudioEngine: wrote probedBestAudioBackend", { meta: { backend } });
+    return { backend };
+  }
+  /** Resolve the effective backend from the operator choice, falling back to the platform heuristic when 'auto'. */
+  resolveAudioBackend() {
+    const choice = this.config.audioBackend;
+    if (choice === "apple-soundanalysis") return "apple-soundanalysis";
+    if (choice === "yamnet-onnx") return "yamnet-onnx";
+    return process.platform === "darwin" ? "apple-soundanalysis" : "yamnet-onnx";
+  }
+  async onInitialize() {
+    const logger = this.ctx.logger;
+    const modelsDir = await this.ctx.api.storage.resolve.query({ location: "models", relativePath: "" }).catch(() => "camstack-data/models");
+    const backend = this.resolveAudioBackend();
+    logger.info("audio-analyzer: resolving pipeline", {
+      meta: { operatorChoice: this.config.audioBackend, effectiveBackend: backend, selectedModel: this.config.selectedAudioModel || null }
+    });
+    const p = await createAudioPipeline(modelsDir, logger, { backend });
+    await p.initialize();
+    this.pipeline = p;
+    if (!this.config.probedBestAudioBackend) {
+      this.reprobeAudioEngine().catch((err) => {
+        logger.warn("audio: auto-reprobe failed", {
+          meta: { error: err instanceof Error ? err.message : String(err) }
+        });
+      });
+    }
+    const self = this;
+    const deviceSettingsResolver = async (deviceId) => {
+      try {
+        const resolved = await self.ctx.api.pipelineOrchestrator.resolvePipeline.query({ deviceId });
+        const stepSettings = resolved.audio?.settings ?? {};
+        const minConfidence = typeof stepSettings["minConfidence"] === "number" ? stepSettings["minConfidence"] : 0.3;
+        const allowedClasses = Array.isArray(stepSettings["enabledAudioClasses"]) ? stepSettings["enabledAudioClasses"] : [];
+        return { minConfidence, allowedClasses };
+      } catch (err) {
+        logger.warn("audio: resolveDeviceSettings via orchestrator failed", {
+          tags: { deviceId },
+          meta: { error: err instanceof Error ? err.message : String(err) }
+        });
+        return null;
+      }
+    };
+    const deviceContributionResolver = async (_deviceId) => {
+      return null;
+    };
+    const deviceSettingsPatcher = async (_deviceId, _patch) => {
+    };
+    this.provider = new AudioAnalyzerProvider(
+      logger,
+      this.pipeline,
+      backend,
+      deviceSettingsResolver,
+      deviceContributionResolver,
+      deviceSettingsPatcher,
+      () => this.reprobeAudioEngine()
+    );
+    return [
+      { capability: types.audioAnalyzerCapability, provider: this.provider },
+      {
+        capability: types.audioAnalysisCapability,
+        provider: this.provider,
+        kind: "wrapper",
+        defaultActive: true
+      }
+    ];
+  }
+  async onShutdown() {
+    if (this.provider) {
+      await this.provider.dispose();
+      this.provider = null;
+    }
+    this.pipeline = null;
+  }
+  // ── Standard ICamstackAddon — three-level settings API ─────
+  //
+  // Per-device audio settings (audio class filter + minConfidence) moved
+  // to the audio-classifier pipeline step's `getConfigSchema()` and the
+  // orchestrator owns the audio node assignment (`audioNodeId`). No
+  // device-level settings remain on this addon.
+  buildDeviceSchema() {
+    return { sections: [] };
+  }
+  async getDeviceSettings(deviceId) {
+    const raw = await this.ctx?.settings?.readDeviceStore(deviceId) ?? {};
+    return types.hydrateSchema(this.buildDeviceSchema(), raw);
+  }
+  async updateDeviceSettings(deviceId, patch) {
+    await this.ctx?.settings?.writeDeviceStore(deviceId, patch);
+  }
+}
+exports.AudioAnalyzerAddon = AudioAnalyzerAddon;
+exports.AudioAnalyzerProvider = AudioAnalyzerProvider;
+exports.createAudioPipeline = createAudioPipeline;
+exports.default = AudioAnalyzerAddon;
+//# sourceMappingURL=index.js.map