@myzonerocks/gosslens 0.9.0 → 0.10.0

package/dist/src/mic-input.d.ts

@@ -0,0 +1,12 @@
+import type { GossSession } from "./index";
+export declare class GossMicInput {
+    private session;
+    private context;
+    private stream;
+    private node;
+    private source;
+    constructor(session: GossSession);
+    start(): Promise<void>;
+    stop(): Promise<void>;
+}
+//# sourceMappingURL=mic-input.d.ts.map

package/dist/src/mic-input.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mic-input.d.ts","sourceRoot":"","sources":["../../src/mic-input.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAiB3C,qBAAa,YAAY;IACvB,OAAO,CAAC,OAAO,CAAc;IAC7B,OAAO,CAAC,OAAO,CAA6B;IAC5C,OAAO,CAAC,MAAM,CAA4B;IAC1C,OAAO,CAAC,IAAI,CAAiC;IAC7C,OAAO,CAAC,MAAM,CAA2C;IAEzD,YAAY,OAAO,EAAE,WAAW,EAE/B;IAKK,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAuB3B;IAGK,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAU1B;CACF"}

package/dist/src/mic-input.js

@@ -0,0 +1,67 @@
+/// Captures the microphone and feeds it to the engine's audio analysis,
+/// so the level and beat triggers a lens reads fire on web the same way
+/// submitted audio drives them on the native SDKs. A worklet forwards
+/// each block to the main thread, which hands it to submitAudio.
+const captureProcessor = `
+class GossMicCapture extends AudioWorkletProcessor {
+  process(inputs) {
+    const chan = inputs[0] && inputs[0][0];
+    if (chan && chan.length) this.port.postMessage(chan.slice());
+    return true;
+  }
+}
+registerProcessor("goss-mic-capture", GossMicCapture);
+`;
+export class GossMicInput {
+    session;
+    context = null;
+    stream = null;
+    node = null;
+    source = null;
+    constructor(session) {
+        this.session = session;
+    }
+    /// Requests the microphone and starts forwarding its PCM to the
+    /// engine. Call from a user gesture; browsers gate both getUserMedia
+    /// and the AudioContext behind one.
+    async start() {
+        if (this.context)
+            return;
+        const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
+        const context = new AudioContext();
+        const moduleUrl = URL.createObjectURL(new Blob([captureProcessor], { type: "text/javascript" }));
+        try {
+            await context.audioWorklet.addModule(moduleUrl);
+        }
+        finally {
+            URL.revokeObjectURL(moduleUrl);
+        }
+        const source = context.createMediaStreamSource(stream);
+        const node = new AudioWorkletNode(context, "goss-mic-capture", { numberOfOutputs: 0 });
+        const rate = context.sampleRate;
+        node.port.onmessage = (event) => {
+            const block = event.data;
+            this.session.submitAudio(block, block.length, rate, 1);
+        };
+        source.connect(node);
+        await context.resume();
+        this.context = context;
+        this.stream = stream;
+        this.source = source;
+        this.node = node;
+    }
+    /// Stops the capture and releases the microphone.
+    async stop() {
+        this.source?.disconnect();
+        this.node?.disconnect();
+        this.source = null;
+        this.node = null;
+        this.stream?.getTracks().forEach((track) => track.stop());
+        this.stream = null;
+        const context = this.context;
+        this.context = null;
+        if (context)
+            await context.close();
+    }
+}
+//# sourceMappingURL=mic-input.js.map

package/dist/src/mic-input.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mic-input.js","sourceRoot":"","sources":["../../src/mic-input.ts"],"names":[],"mappings":"AAEA,wEAAwE;AACxE,wEAAwE;AACxE,sEAAsE;AACtE,iEAAiE;AACjE,MAAM,gBAAgB,GAAG;;;;;;;;;CASxB,CAAC;AAEF,MAAM,OAAO,YAAY;IACf,OAAO,CAAc;IACrB,OAAO,GAAwB,IAAI,CAAC;IACpC,MAAM,GAAuB,IAAI,CAAC;IAClC,IAAI,GAA4B,IAAI,CAAC;IACrC,MAAM,GAAsC,IAAI,CAAC;IAEzD,YAAY,OAAoB;QAC9B,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACzB,CAAC;IAED,gEAAgE;IAChE,qEAAqE;IACrE,oCAAoC;IACpC,KAAK,CAAC,KAAK;QACT,IAAI,IAAI,CAAC,OAAO;YAAE,OAAO;QACzB,MAAM,MAAM,GAAG,MAAM,SAAS,CAAC,YAAY,CAAC,YAAY,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QAC1E,MAAM,OAAO,GAAG,IAAI,YAAY,EAAE,CAAC;QACnC,MAAM,SAAS,GAAG,GAAG,CAAC,eAAe,CAAC,IAAI,IAAI,CAAC,CAAC,gBAAgB,CAAC,EAAE,EAAE,IAAI,EAAE,iBAAiB,EAAE,CAAC,CAAC,CAAC;QACjG,IAAI,CAAC;YACH,MAAM,OAAO,CAAC,YAAY,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC;QAClD,CAAC;gBAAS,CAAC;YACT,GAAG,CAAC,eAAe,CAAC,SAAS,CAAC,CAAC;QACjC,CAAC;QACD,MAAM,MAAM,GAAG,OAAO,CAAC,uBAAuB,CAAC,MAAM,CAAC,CAAC;QACvD,MAAM,IAAI,GAAG,IAAI,gBAAgB,CAAC,OAAO,EAAE,kBAAkB,EAAE,EAAE,eAAe,EAAE,CAAC,EAAE,CAAC,CAAC;QACvF,MAAM,IAAI,GAAG,OAAO,CAAC,UAAU,CAAC;QAChC,IAAI,CAAC,IAAI,CAAC,SAAS,GAAG,CAAC,KAAK,EAAE,EAAE;YAC9B,MAAM,KAAK,GAAG,KAAK,CAAC,IAAoB,CAAC;YACzC,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,KAAK,EAAE,KAAK,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;QACzD,CAAC,CAAC;QACF,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QACrB,MAAM,OAAO,CAAC,MAAM,EAAE,CAAC;QACvB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;IAED,kDAAkD;IAClD,KAAK,CAAC,IAAI;QACR,IAAI,CAAC,MAAM,EAAE,UAAU,EAAE,CAAC;QAC1B,IAAI,CAAC,IAAI,EAAE,UAAU,EAAE,CAAC;QACxB,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC;QACnB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,MAAM,EAAE,SAAS,EAAE,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC;QAC1D,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC;QACnB,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC;QAC7B,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;QACpB,IAAI,OAAO;YAAE,MAAM,OAAO,CAAC,KAAK,EAAE,CAAC;IACrC,CAAC;CACF"}

package/dist/src/video-texture.d.ts

@@ -0,0 +1,14 @@
+import type { GossSession } from "./index";
+export declare class GossVideoTexture {
+    private session;
+    private name;
+    private video;
+    private canvas;
+    private ctx;
+    private running;
+    constructor(session: GossSession, name: string, url: string);
+    start(): Promise<void>;
+    pump(): void;
+    stop(): void;
+}
+//# sourceMappingURL=video-texture.d.ts.map

package/dist/src/video-texture.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"video-texture.d.ts","sourceRoot":"","sources":["../../src/video-texture.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAM3C,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,OAAO,CAAc;IAC7B,OAAO,CAAC,IAAI,CAAS;IACrB,OAAO,CAAC,KAAK,CAAmB;IAChC,OAAO,CAAC,MAAM,CAAoB;IAClC,OAAO,CAAC,GAAG,CAAkC;IAC7C,OAAO,CAAC,OAAO,CAAS;IAExB,YAAY,OAAO,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAU1D;IAIK,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAK3B;IAKD,IAAI,IAAI,IAAI,CAYX;IAGD,IAAI,IAAI,IAAI,CAKX;CACF"}

package/dist/src/video-texture.js

@@ -0,0 +1,58 @@
+/// Plays an MP4 through a hidden video element, the browser's own
+/// decoder, and feeds each frame to a named engine source a lens
+/// composites, so a web lens shows a video texture with no wasm
+/// decoder. The `video.texture` node stays native; this serves web.
+export class GossVideoTexture {
+    session;
+    name;
+    video;
+    canvas;
+    ctx;
+    running = false;
+    constructor(session, name, url) {
+        this.session = session;
+        this.name = name;
+        this.video = document.createElement("video");
+        this.video.src = url;
+        this.video.loop = true;
+        this.video.muted = true;
+        this.video.playsInline = true;
+        this.canvas = document.createElement("canvas");
+        this.ctx = this.canvas.getContext("2d", { willReadFrequently: true });
+    }
+    /// Registers the source and starts playback; pumps run from the
+    /// frame loop. Call from a user gesture so autoplay is allowed.
+    async start() {
+        if (this.running)
+            return;
+        this.session.defineSource(this.name);
+        await this.video.play();
+        this.running = true;
+    }
+    /// Grabs the current video frame and submits it to the source. Call
+    /// once per frame from the same loop that renders the session; a no-op
+    /// until the first frame has enough data to draw.
+    pump() {
+        if (!this.running || !this.ctx)
+            return;
+        if (this.video.readyState < 2 || this.video.videoWidth === 0)
+            return;
+        const w = this.video.videoWidth;
+        const h = this.video.videoHeight;
+        if (this.canvas.width !== w || this.canvas.height !== h) {
+            this.canvas.width = w;
+            this.canvas.height = h;
+        }
+        this.ctx.drawImage(this.video, 0, 0, w, h);
+        const rgba = this.ctx.getImageData(0, 0, w, h).data;
+        this.session.submitSourceFrameRgba(this.name, new Uint8Array(rgba.buffer), w, h, w * 4);
+    }
+    /// Stops playback and releases the element.
+    stop() {
+        this.running = false;
+        this.video.pause();
+        this.video.removeAttribute("src");
+        this.video.load();
+    }
+}
+//# sourceMappingURL=video-texture.js.map

package/dist/src/video-texture.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"video-texture.js","sourceRoot":"","sources":["../../src/video-texture.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@myzonerocks/gosslens",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Web SDK for the gosslens camera and AR engine, over the wasm core.",
   "license": "Apache-2.0",
   "repository": {

package/src/audio-output.ts

@@ -0,0 +1,102 @@
+import type { GossSession } from "./index";
+
+/// The worklet drains chunks the page posts it, so the audio thread
+/// never touches the wasm heap and the engine's graph-thread pull
+/// contract holds; an underrun renders silence.
+const processorSource = `
+class GossLensAudioProcessor extends AudioWorkletProcessor {
+  constructor() {
+    super();
+    this.queue = [];
+    this.offset = 0;
+    this.queued = 0;
+    this.port.onmessage = (event) => {
+      this.queue.push(event.data);
+      this.queued += event.data.length;
+      while (this.queue.length > 1 && this.queued - this.queue[0].length + this.offset > 16384) {
+        this.queued -= this.queue[0].length;
+        this.queue.shift();
+        this.offset = 0;
+      }
+    };
+  }
+  process(_inputs, outputs) {
+    const out = outputs[0][0];
+    if (!out) return true;
+    for (let i = 0; i < out.length; i += 1) {
+      const head = this.queue[0];
+      if (!head) {
+        out[i] = 0;
+        continue;
+      }
+      out[i] = head[this.offset] / 32768;
+      this.offset += 1;
+      if (this.offset >= head.length) {
+        this.queued -= head.length;
+        this.queue.shift();
+        this.offset = 0;
+      }
+    }
+    return true;
+  }
+}
+registerProcessor("goss-lens-audio", GossLensAudioProcessor);
+`;
+
+/// Routes the lens mixer to the page's speakers. The engine pull is
+/// graph-thread only, so pump() runs in the frame loop on the main
+/// thread and posts each block to an AudioWorklet that plays it.
+export class GossAudioOutput {
+  /// The lens mixer's fixed output format.
+  static readonly sampleRate = 48_000;
+
+  private session: GossSession;
+  private context: AudioContext | null = null;
+  private node: AudioWorkletNode | null = null;
+
+  constructor(session: GossSession) {
+    this.session = session;
+  }
+
+  /// Stands the worklet up; browsers require a user gesture before an
+  /// AudioContext runs, so call this from one and await it.
+  async start(): Promise<void> {
+    if (this.context) return;
+    const context = new AudioContext({ sampleRate: GossAudioOutput.sampleRate });
+    const moduleUrl = URL.createObjectURL(new Blob([processorSource], { type: "text/javascript" }));
+    try {
+      await context.audioWorklet.addModule(moduleUrl);
+    } finally {
+      URL.revokeObjectURL(moduleUrl);
+    }
+    const node = new AudioWorkletNode(context, "goss-lens-audio", {
+      numberOfInputs: 0,
+      numberOfOutputs: 1,
+      outputChannelCount: [1],
+    });
+    node.connect(context.destination);
+    await context.resume();
+    this.context = context;
+    this.node = node;
+  }
+
+  /// Pulls the next mixer block and hands it to the worklet. Call once
+  /// per frame from the same loop that ticks the lens. The post
+  /// transfers the block's buffer, which detaches it, so each pump is
+  /// one fresh small block by design rather than a reusable buffer.
+  pump(frames = 800): void {
+    const node = this.node;
+    if (!node) return;
+    const block = this.session.pullAudio(frames);
+    node.port.postMessage(block, [block.buffer]);
+  }
+
+  /// Tears the worklet and context down.
+  async stop(): Promise<void> {
+    this.node?.disconnect();
+    this.node = null;
+    const context = this.context;
+    this.context = null;
+    if (context) await context.close();
+  }
+}

package/src/index.ts

@@ -2854,3 +2854,6 @@ export class GossPreviewSession {
 
 export { GossWebXRWorldSource } from "./world";
 export type { GossXRFrameLike } from "./world";
+export { GossAudioOutput } from "./audio-output";
+export { GossMicInput } from "./mic-input";
+export { GossVideoTexture } from "./video-texture";

package/src/mic-input.ts

@@ -0,0 +1,69 @@
+import type { GossSession } from "./index";
+
+/// Captures the microphone and feeds it to the engine's audio analysis,
+/// so the level and beat triggers a lens reads fire on web the same way
+/// submitted audio drives them on the native SDKs. A worklet forwards
+/// each block to the main thread, which hands it to submitAudio.
+const captureProcessor = `
+class GossMicCapture extends AudioWorkletProcessor {
+  process(inputs) {
+    const chan = inputs[0] && inputs[0][0];
+    if (chan && chan.length) this.port.postMessage(chan.slice());
+    return true;
+  }
+}
+registerProcessor("goss-mic-capture", GossMicCapture);
+`;
+
+export class GossMicInput {
+  private session: GossSession;
+  private context: AudioContext | null = null;
+  private stream: MediaStream | null = null;
+  private node: AudioWorkletNode | null = null;
+  private source: MediaStreamAudioSourceNode | null = null;
+
+  constructor(session: GossSession) {
+    this.session = session;
+  }
+
+  /// Requests the microphone and starts forwarding its PCM to the
+  /// engine. Call from a user gesture; browsers gate both getUserMedia
+  /// and the AudioContext behind one.
+  async start(): Promise<void> {
+    if (this.context) return;
+    const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
+    const context = new AudioContext();
+    const moduleUrl = URL.createObjectURL(new Blob([captureProcessor], { type: "text/javascript" }));
+    try {
+      await context.audioWorklet.addModule(moduleUrl);
+    } finally {
+      URL.revokeObjectURL(moduleUrl);
+    }
+    const source = context.createMediaStreamSource(stream);
+    const node = new AudioWorkletNode(context, "goss-mic-capture", { numberOfOutputs: 0 });
+    const rate = context.sampleRate;
+    node.port.onmessage = (event) => {
+      const block = event.data as Float32Array;
+      this.session.submitAudio(block, block.length, rate, 1);
+    };
+    source.connect(node);
+    await context.resume();
+    this.context = context;
+    this.stream = stream;
+    this.source = source;
+    this.node = node;
+  }
+
+  /// Stops the capture and releases the microphone.
+  async stop(): Promise<void> {
+    this.source?.disconnect();
+    this.node?.disconnect();
+    this.source = null;
+    this.node = null;
+    this.stream?.getTracks().forEach((track) => track.stop());
+    this.stream = null;
+    const context = this.context;
+    this.context = null;
+    if (context) await context.close();
+  }
+}

package/src/video-texture.ts

@@ -0,0 +1,60 @@
+import type { GossSession } from "./index";
+
+/// Plays an MP4 through a hidden video element, the browser's own
+/// decoder, and feeds each frame to a named engine source a lens
+/// composites, so a web lens shows a video texture with no wasm
+/// decoder. The `video.texture` node stays native; this serves web.
+export class GossVideoTexture {
+  private session: GossSession;
+  private name: string;
+  private video: HTMLVideoElement;
+  private canvas: HTMLCanvasElement;
+  private ctx: CanvasRenderingContext2D | null;
+  private running = false;
+
+  constructor(session: GossSession, name: string, url: string) {
+    this.session = session;
+    this.name = name;
+    this.video = document.createElement("video");
+    this.video.src = url;
+    this.video.loop = true;
+    this.video.muted = true;
+    this.video.playsInline = true;
+    this.canvas = document.createElement("canvas");
+    this.ctx = this.canvas.getContext("2d", { willReadFrequently: true });
+  }
+
+  /// Registers the source and starts playback; pumps run from the
+  /// frame loop. Call from a user gesture so autoplay is allowed.
+  async start(): Promise<void> {
+    if (this.running) return;
+    this.session.defineSource(this.name);
+    await this.video.play();
+    this.running = true;
+  }
+
+  /// Grabs the current video frame and submits it to the source. Call
+  /// once per frame from the same loop that renders the session; a no-op
+  /// until the first frame has enough data to draw.
+  pump(): void {
+    if (!this.running || !this.ctx) return;
+    if (this.video.readyState < 2 || this.video.videoWidth === 0) return;
+    const w = this.video.videoWidth;
+    const h = this.video.videoHeight;
+    if (this.canvas.width !== w || this.canvas.height !== h) {
+      this.canvas.width = w;
+      this.canvas.height = h;
+    }
+    this.ctx.drawImage(this.video, 0, 0, w, h);
+    const rgba = this.ctx.getImageData(0, 0, w, h).data;
+    this.session.submitSourceFrameRgba(this.name, new Uint8Array(rgba.buffer), w, h, w * 4);
+  }
+
+  /// Stops playback and releases the element.
+  stop(): void {
+    this.running = false;
+    this.video.pause();
+    this.video.removeAttribute("src");
+    this.video.load();
+  }
+}