@viji-dev/core 0.11.5 → 0.11.7

package/dist/docs-api.js

@@ -1,7 +1,7 @@
 export const docsApi = {
   "version": "1.1.0",
-  "coreVersion": "0.11.5",
-  "generatedAt": "2026-07-19T11:29:49.493Z",
+  "coreVersion": "0.11.7",
+  "generatedAt": "2026-07-24T15:25:39.379Z",
   "navigation": [
     {
       "id": "getting-started",

package/dist/{essentia-wasm.web-BjQ6Tlu7.js → essentia-wasm.web-QxZd-8n4.js}

@@ -1,4 +1,4 @@
-import { g as kn } from "./index-CFKPh6Ia.js";
+import { g as kn } from "./index-zKfpXJhf.js";
 function jn(Oe, ot) {
   for (var ve = 0; ve < ot.length; ve++) {
     const Z = ot[ve];
@@ -3374,4 +3374,4 @@ const xn = /* @__PURE__ */ kn(yi), Ln = /* @__PURE__ */ jn({
 export {
   Ln as e
 };
-//# sourceMappingURL=essentia-wasm.web-BjQ6Tlu7.js.map
+//# sourceMappingURL=essentia-wasm.web-QxZd-8n4.js.map

package/dist/{index-CFKPh6Ia.js → index-zKfpXJhf.js}

@@ -547,7 +547,7 @@ class lB {
       }
   }
 }
-const nB = "" + new URL("assets/viji.worker-Dz7THSog.js", import.meta.url).href;
+const nB = "" + new URL("assets/viji.worker-BKg5vsqf.js", import.meta.url).href;
 class dB {
   constructor(A, B, I) {
     this.iframeManager = A, this.sceneCode = B, this.init = I;
@@ -1518,7 +1518,7 @@ class HB {
     if (!this.isInitialized)
       return this.initPromise ? this.initPromise : (this.initPromise = (async () => {
         try {
-          const A = await import("./essentia.js-core.es-CC_3Ap1i.js"), B = await import("./essentia-wasm.web-BjQ6Tlu7.js").then((g) => g.e), I = A.Essentia || A.default?.Essentia || A.default;
+          const A = await import("./essentia.js-core.es-CC_3Ap1i.js"), B = await import("./essentia-wasm.web-QxZd-8n4.js").then((g) => g.e), I = A.Essentia || A.default?.Essentia || A.default;
           let Q = B.default || B.EssentiaWASM || B.default?.EssentiaWASM;
           if (!Q)
             throw new Error("WASM module not found - check essentia-wasm.web.js export");
@@ -5179,6 +5179,16 @@ class eA {
   // Shared AudioContext (one for all channels)
   audioContext = null;
   workletRegistered = !1;
+  /**
+   * Persistent export capture tap (main channel only). Created lazily by
+   * `getAudioCaptureStream()`, lives for the AudioSystem lifetime, and is
+   * torn down only in `resetAudioState()`. Deliberately NOT severed by
+   * `disconnectMainStream()`: on mid-recording disconnect the tap stream
+   * goes silent while its tracks stay live, and `connectChannel()` re-wires
+   * each new main source node into it, so the exposed MediaStream stays
+   * stable across `setAudioStream()` swaps (a recorder never renegotiates).
+   */
+  captureDestination = null;
   // Main audio channel (index 0, full analysis with beat detection)
   mainChannel;
   // Additional audio channels (lightweight analysis, no beat detection)
@@ -5598,6 +5608,20 @@ class eA {
   getAudioState() {
     return { ...this.mainChannel.audioState };
   }
+  /**
+   * Get a recordable MediaStream carrying the main channel's audio, for
+   * host-side export recording. Main channel only — additional channels and
+   * source-fed device channels (analysis values, no PCM) are not included.
+   *
+   * The underlying destination node is created lazily on first call and then
+   * persists for the AudioSystem lifetime: on a source swap the stream keeps
+   * flowing with the new audio, and on disconnect it goes silent with tracks
+   * still live. Returns `null` when the main channel is not connected at
+   * call time (or after teardown).
+   */
+  getAudioCaptureStream() {
+    return this.destroyed || !this.mainChannel.audioState.isConnected || !this.audioContext ? null : (this.captureDestination || (this.captureDestination = this.audioContext.createMediaStreamDestination()), this.mainChannel.mediaStreamSource && this.mainChannel.mediaStreamSource.connect(this.captureDestination), this.captureDestination.stream);
+  }
   /**
    * Initialize Essentia.js (async WASM loading)
    */
@@ -5659,7 +5683,7 @@ class eA {
     }
     try {
       const g = await this.ensureAudioContext();
-      A.mediaStreamSource = g.createMediaStreamSource(B), await this.setupChannelWorklet(A, I) && A.workletNode ? (A.analysisMode = "worklet", A.currentSampleRate = g.sampleRate, A.mediaStreamSource.connect(A.workletNode), A.workletNode.connect(g.destination), this.debugLog(`Audio worklet enabled for channel ${A.streamIndex}`), A.workletWatchdog = setTimeout(() => {
+      A.mediaStreamSource = g.createMediaStreamSource(B), I && this.captureDestination && A.mediaStreamSource.connect(this.captureDestination), await this.setupChannelWorklet(A, I) && A.workletNode ? (A.analysisMode = "worklet", A.currentSampleRate = g.sampleRate, A.mediaStreamSource.connect(A.workletNode), A.workletNode.connect(g.destination), this.debugLog(`Audio worklet enabled for channel ${A.streamIndex}`), A.workletWatchdog = setTimeout(() => {
         if (A.workletWatchdog = null, A.analysisMode === "worklet" && A.workletFrameCount === 0) {
           if (this.debugLog(`[AudioSystem] Worklet silent for channel ${A.streamIndex}, falling back to analyser.`), A.analysisMode = "analyser", A.workletNode) {
             try {
@@ -5943,7 +5967,13 @@ class eA {
     this.destroyed = !0, this.stopAnalysisLoop(), this.stopStalenessTimer(), this.stopIdleTicker(), this.resetEssentiaBandHistories();
     for (const B of this.additionalChannels.values())
       B.destroy();
-    this.additionalChannels.clear(), this.mainChannel.disconnectNodes(), this.mainChannel.audioState.isConnected = !1, this.mainChannel.isAnalysisRunning = !1, this.mainChannel.currentStream = null;
+    if (this.additionalChannels.clear(), this.mainChannel.disconnectNodes(), this.mainChannel.audioState.isConnected = !1, this.mainChannel.isAnalysisRunning = !1, this.mainChannel.currentStream = null, this.captureDestination) {
+      try {
+        this.captureDestination.disconnect();
+      } catch {
+      }
+      this.captureDestination = null;
+    }
     const A = this.audioContext;
     if (this.audioContext = null, A && A.state !== "closed")
       try {
@@ -9124,6 +9154,16 @@ class sA {
   getMainAudioStream() {
     return this.mainAudioStream;
   }
+  /**
+   * Recordable tap on the main channel's audio, for export recording.
+   * Pure read: uses the non-materializing `audio` getter — a capture stream
+   * can only exist once the audio engine is already live, so a headless
+   * preview constructs nothing here. No connectivity edge: capability state
+   * is unchanged.
+   */
+  getAudioCaptureStream() {
+    return this.audio?.getAudioCaptureStream() ?? null;
+  }
   get hasMainAudio() {
     return this.mainAudioStream !== null;
   }
@@ -9793,7 +9833,9 @@ class rA {
     const B = A.format || "blob", I = await this.workerManager.sendMessage("capture-frame", {
       format: B,
       type: B === "blob" ? A.type : void 0,
-      resolution: A.resolution
+      quality: B === "blob" ? A.quality : void 0,
+      resolution: A.resolution,
+      frame: A.frame
     }, 1e4);
     return B === "bitmap" ? I.bitmap : I.blob;
   }
@@ -9821,11 +9863,17 @@ class rA {
   /**
    * Enable auto-capture. Captured frames are retrieved via getLatestFrame().
    * @param format.flipY — true for WebGL texture consumers, false for 2D canvas drawImage.
+   * @param format.frame — frame role: `'plate'` (default) captures the clean
+   * pre-overlay frame (thumbnails, VJ sources); `'display'` captures the
+   * composited frame the viewer sees, including the branding overlay when the
+   * session applies it. Headless cores degrade `'display'` to `'plate'`.
+   * Omitting the field on a re-enable keeps the previously set role.
    */
   enableAutoCapture(A) {
     this.autoCaptureEnabled = !0, this.workerManager && this.workerManager.postMessage("enable-auto-capture", {
       enabled: !0,
-      flipY: A?.flipY
+      flipY: A?.flipY,
+      frame: A?.frame
     });
     const B = A ? ` with flipY=${A.flipY}` : "";
     this.debugLog(`[AutoCapture] ENABLED${B}`);
@@ -10878,6 +10926,38 @@ class rA {
   getAudioStream() {
     return this.engineGroup.getMainAudioStream();
   }
+  /**
+   * Gets a recordable MediaStream carrying the main audio channel's signal,
+   * for client-side export recording (e.g. feeding a WebCodecs
+   * `AudioEncoder` or `MediaRecorder` while capturing scene video).
+   *
+   * The returned stream is stable across `setAudioStream()` swaps: obtain it
+   * once at record start and keep recording — a source change flows into the
+   * same stream with no renegotiation. If audio is disconnected
+   * mid-recording the stream goes **silent** (tracks stay live, the A/V
+   * timeline stays continuous); its tracks end only when the media engines
+   * are disposed (last core sharing them destroyed).
+   *
+   * Scope: main channel only. Additional audio channels and remote-device
+   * audio (analysis values only, no PCM host-side) are not included.
+   * Engine-scoped — identical for all cores sharing this core's media
+   * engines, like {@link getAudioStream}.
+   *
+   * @returns The capture stream, or `null` when no main audio is connected
+   * at call time.
+   *
+   * @example
+   * ```ts
+   * const audioTap = core.getAudioCaptureStream();
+   * if (audioTap) {
+   *   const [track] = audioTap.getAudioTracks();
+   *   // feed track into MediaStreamTrackProcessor → AudioEncoder
+   * }
+   * ```
+   */
+  getAudioCaptureStream() {
+    return this.engineGroup.getAudioCaptureStream();
+  }
   /**
    * Enables or disables user interactions (mouse, keyboard, touch) at runtime
    */
@@ -11551,7 +11631,7 @@ function HI(D) {
     expectedVersion: 1
   } : typeof A.senderTime != "number" ? { code: "invalid-field", details: "senderTime must be a number", field: "senderTime" } : null;
 }
-const mI = "0.11.5";
+const mI = "0.11.7";
 export {
   eA as A,
   LI as C,
@@ -11562,4 +11642,4 @@ export {
   J as c,
   gI as g
 };
-//# sourceMappingURL=index-CFKPh6Ia.js.map
+//# sourceMappingURL=index-zKfpXJhf.js.map

package/dist/index.d.ts

@@ -239,6 +239,16 @@ declare interface AudioStreamAPI {
 export declare class AudioSystem {
     private audioContext;
     private workletRegistered;
+    /**
+     * Persistent export capture tap (main channel only). Created lazily by
+     * `getAudioCaptureStream()`, lives for the AudioSystem lifetime, and is
+     * torn down only in `resetAudioState()`. Deliberately NOT severed by
+     * `disconnectMainStream()`: on mid-recording disconnect the tap stream
+     * goes silent while its tracks stay live, and `connectChannel()` re-wires
+     * each new main source node into it, so the exposed MediaStream stays
+     * stable across `setAudioStream()` swaps (a recorder never renegotiates).
+     */
+    private captureDestination;
     private mainChannel;
     private additionalChannels;
     private analysisInterval;
@@ -372,6 +382,18 @@ export declare class AudioSystem {
             flatness: number;
         };
     };
+    /**
+     * Get a recordable MediaStream carrying the main channel's audio, for
+     * host-side export recording. Main channel only — additional channels and
+     * source-fed device channels (analysis values, no PCM) are not included.
+     *
+     * The underlying destination node is created lazily on first call and then
+     * persists for the AudioSystem lifetime: on a source swap the stream keeps
+     * flowing with the new audio, and on disconnect it goes silent with tracks
+     * still live. Returns `null` when the main channel is not connected at
+     * call time (or after teardown).
+     */
+    getAudioCaptureStream(): MediaStream | null;
     /**
      * Initialize Essentia.js (async WASM loading)
      */
@@ -894,6 +916,13 @@ export declare interface CaptureFrameOptions {
     format?: 'blob' | 'bitmap';
     /** MIME type for `'blob'` output (ignored for `'bitmap'`). Examples: `'image/png'`, `'image/jpeg'`, `'image/webp'`. */
     type?: string;
+    /**
+     * Encoding quality for lossy `'blob'` formats (`'image/jpeg'`, `'image/webp'`),
+     * from `0` (smallest) to `1` (best). Values outside the range are clamped.
+     * Ignored for `'image/png'` and for `format: 'bitmap'`. When omitted, the
+     * browser's default quality is used.
+     */
+    quality?: number;
     /**
      * Target resolution.
      * - `number`: scale factor relative to the current canvas size (e.g., `0.5` = 50%).
@@ -901,6 +930,16 @@ export declare interface CaptureFrameOptions {
      *   canvas, the source is center-cropped before scaling.
      */
     resolution?: number | Resolution;
+    /**
+     * Frame role to capture. `'plate'` (default) captures the clean pre-overlay
+     * frame — thumbnails and VJ source frames, identical to previous behavior.
+     * `'display'` captures the composited frame the viewer sees, including the
+     * branding overlay when the session applies it. On headless cores no
+     * overlay is ever drawn, so `'display'` degrades to `'plate'`. Note:
+     * center-cropping via `resolution` can crop the edge-anchored overlay out
+     * of a `'display'` capture — display captures are intended at canvas aspect.
+     */
+    frame?: 'plate' | 'display';
 }
 
 /**
@@ -2832,7 +2871,7 @@ declare type TrackingState = 'TRACKING' | 'LOCKED' | 'BREAKDOWN' | 'LOST';
 /** Returned by `on*` listener registration calls; invoke to unsubscribe. */
 export declare type Unsubscribe = () => void;
 
-export declare const VERSION = "0.11.5";
+export declare const VERSION = "0.11.7";
 
 /**
  * Real-time video API: drawable frame, dimensions, and the source-side
@@ -3262,9 +3301,15 @@ export declare class VijiCore {
     /**
      * Enable auto-capture. Captured frames are retrieved via getLatestFrame().
      * @param format.flipY — true for WebGL texture consumers, false for 2D canvas drawImage.
+     * @param format.frame — frame role: `'plate'` (default) captures the clean
+     * pre-overlay frame (thumbnails, VJ sources); `'display'` captures the
+     * composited frame the viewer sees, including the branding overlay when the
+     * session applies it. Headless cores degrade `'display'` to `'plate'`.
+     * Omitting the field on a re-enable keeps the previously set role.
      */
     enableAutoCapture(format?: {
         flipY: boolean;
+        frame?: 'plate' | 'display';
     }): void;
     /**
      * Disable auto-capture and release any pending frame buffer.
@@ -3735,6 +3780,36 @@ export declare class VijiCore {
      * sharing this core's media engines)
      */
     getAudioStream(): MediaStream | null;
+    /**
+     * Gets a recordable MediaStream carrying the main audio channel's signal,
+     * for client-side export recording (e.g. feeding a WebCodecs
+     * `AudioEncoder` or `MediaRecorder` while capturing scene video).
+     *
+     * The returned stream is stable across `setAudioStream()` swaps: obtain it
+     * once at record start and keep recording — a source change flows into the
+     * same stream with no renegotiation. If audio is disconnected
+     * mid-recording the stream goes **silent** (tracks stay live, the A/V
+     * timeline stays continuous); its tracks end only when the media engines
+     * are disposed (last core sharing them destroyed).
+     *
+     * Scope: main channel only. Additional audio channels and remote-device
+     * audio (analysis values only, no PCM host-side) are not included.
+     * Engine-scoped — identical for all cores sharing this core's media
+     * engines, like {@link getAudioStream}.
+     *
+     * @returns The capture stream, or `null` when no main audio is connected
+     * at call time.
+     *
+     * @example
+     * ```ts
+     * const audioTap = core.getAudioCaptureStream();
+     * if (audioTap) {
+     *   const [track] = audioTap.getAudioTracks();
+     *   // feed track into MediaStreamTrackProcessor → AudioEncoder
+     * }
+     * ```
+     */
+    getAudioCaptureStream(): MediaStream | null;
     /**
      * Enables or disables user interactions (mouse, keyboard, touch) at runtime
      */

package/dist/index.js

@@ -1,4 +1,4 @@
-import { A as e, C as i, I as r, V as o, a as C, c as E, b as A } from "./index-CFKPh6Ia.js";
+import { A as e, C as i, I as r, V as o, a as C, c as E, b as A } from "./index-zKfpXJhf.js";
 export {
   e as AudioSystem,
   i as CV_FEATURE_KEYS,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@viji-dev/core",
-  "version": "0.11.5",
+  "version": "0.11.7",
   "description": "Universal execution engine for Viji Creative scenes",
   "type": "module",
   "main": "./dist/index.js",