@aelionsdk/audio 1.2.0-rc.1 → 1.2.0-rc.3

package/README.md

@@ -8,7 +8,7 @@ Audio scheduling and deterministic PCM processing primitives for AelionSDK.
 npm install @aelionsdk/audio@next
 ```
 
-`next` currently resolves to `1.2.0-rc.1`. Product applications should prefer
+`next` currently resolves to `1.2.0-rc.3`. Product applications should prefer
 `@aelionsdk/sdk`; use this package directly when building a custom audio host,
 analysis pipeline or renderer integration.
 
@@ -18,6 +18,8 @@ analysis pipeline or renderer integration.
 - streaming resampling and pitch-preserving time stretch;
 - SharedArrayBuffer and transferable PCM queues;
 - AudioWorklet clocks, device state and video scheduling.
+- bounded beat and audio-energy change analysis. Audio analysis does not claim
+  pixel-based video scene detection.
 
 Queue and clock instances own browser and buffer resources. Stop producers,
 cancel pending work and dispose the owning session or primitive when playback

package/dist/analysis.d.ts

@@ -22,18 +22,26 @@ export interface BeatDetectionResult {
     readonly totalFrames: number;
     readonly beats: readonly BeatMarker[];
 }
-/** A single detected scene boundary. */
-export interface SceneBoundary {
-    /** Frame where the scene change is detected. */
+/** A candidate boundary inferred from a discontinuity in audio energy. */
+export interface AudioEnergyBoundary {
+    /** Audio frame where the energy change is detected. */
     readonly frame: number;
     /** Normalized change magnitude, 0..1. */
     readonly magnitude: number;
 }
-/** Result of scene-boundary detection over a PCM source. */
+/** Result of audio-energy change detection over a PCM source. */
+export interface AudioEnergyChangeDetectionResult {
+    readonly sampleRate: number;
+    readonly totalFrames: number;
+    readonly changes: readonly AudioEnergyBoundary[];
+}
+/** @deprecated Use AudioEnergyBoundary; audio alone cannot detect video scenes. */
+export type SceneBoundary = AudioEnergyBoundary;
+/** @deprecated Use AudioEnergyChangeDetectionResult. */
 export interface SceneDetectionResult {
     readonly sampleRate: number;
     readonly totalFrames: number;
-    readonly scenes: readonly SceneBoundary[];
+    readonly scenes: readonly AudioEnergyBoundary[];
 }
 /**
  * Detect beats from an interleaved PCM source using a bounded energy-envelope
@@ -46,13 +54,22 @@ export declare function detectBeats(options: AnalysisSource & {
     readonly minimumOnsetDb?: number;
 }): Promise<BeatDetectionResult>;
 /**
- * Detect scene boundaries as audio-energy discontinuities. A scene change in
- * video is usually accompanied by an abrupt change in the audio envelope, so a
- * large window-to-window energy jump is reported as a candidate boundary.
- * This is a deterministic, media-agnostic approximation driven by the same
- * readFrames source; it does not inspect video pixels.
+ * Detect audio-energy discontinuities as editing candidates. This function
+ * does not inspect video pixels and therefore deliberately makes no claim to
+ * detect scene boundaries.
+ */
+export declare function detectAudioEnergyChanges(options: AnalysisSource & {
+    readonly minimumJumpDb?: number;
+}): Promise<AudioEnergyChangeDetectionResult>;
+/**
+ * @deprecated Audio-only input cannot detect video scenes. Use
+ * `detectAudioEnergyChanges` and treat the result as editing candidates.
  */
 export declare function detectScenes(options: AnalysisSource & {
     readonly minimumJumpDb?: number;
-}): Promise<SceneDetectionResult>;
+}): Promise<{
+    sampleRate: number;
+    totalFrames: number;
+    scenes: readonly AudioEnergyBoundary[];
+}>;
 //# sourceMappingURL=analysis.d.ts.map

package/dist/analysis.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"analysis.d.ts","sourceRoot":"","sources":["../src/analysis.ts"],"names":[],"mappings":"AAEA,6FAA6F;AAC7F,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,UAAU,EAAE,CACnB,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,EAClB,MAAM,CAAC,EAAE,WAAW,KACjB,OAAO,CAAC,YAAY,CAAC,CAAC;IAC3B,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IAC9B,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;CAClD;AAED,8BAA8B;AAC9B,MAAM,WAAW,UAAU;IACzB,wBAAwB;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,iEAAiE;IACjE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,sCAAsC;IACtC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,kDAAkD;AAClD,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,KAAK,EAAE,SAAS,UAAU,EAAE,CAAC;CACvC;AAED,wCAAwC;AACxC,MAAM,WAAW,aAAa;IAC5B,gDAAgD;IAChD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,yCAAyC;IACzC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,4DAA4D;AAC5D,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,SAAS,aAAa,EAAE,CAAC;CAC3C;AAID;;;;;;GAMG;AACH,wBAAsB,WAAW,CAC/B,OAAO,EAAE,cAAc,GAAG;IAAE,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAA;CAAE,GAC7D,OAAO,CAAC,mBAAmB,CAAC,CAgC9B;AAED;;;;;;GAMG;AACH,wBAAsB,YAAY,CAChC,OAAO,EAAE,cAAc,GAAG;IAAE,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAA;CAAE,GAC5D,OAAO,CAAC,oBAAoB,CAAC,CA6B/B"}
+{"version":3,"file":"analysis.d.ts","sourceRoot":"","sources":["../src/analysis.ts"],"names":[],"mappings":"AAEA,6FAA6F;AAC7F,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,UAAU,EAAE,CACnB,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,EAClB,MAAM,CAAC,EAAE,WAAW,KACjB,OAAO,CAAC,YAAY,CAAC,CAAC;IAC3B,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IAC9B,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;CAClD;AAED,8BAA8B;AAC9B,MAAM,WAAW,UAAU;IACzB,wBAAwB;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,iEAAiE;IACjE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,sCAAsC;IACtC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,kDAAkD;AAClD,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,KAAK,EAAE,SAAS,UAAU,EAAE,CAAC;CACvC;AAED,0EAA0E;AAC1E,MAAM,WAAW,mBAAmB;IAClC,uDAAuD;IACvD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,yCAAyC;IACzC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,iEAAiE;AACjE,MAAM,WAAW,gCAAgC;IAC/C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,OAAO,EAAE,SAAS,mBAAmB,EAAE,CAAC;CAClD;AAED,mFAAmF;AACnF,MAAM,MAAM,aAAa,GAAG,mBAAmB,CAAC;AAEhD,wDAAwD;AACxD,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,SAAS,mBAAmB,EAAE,CAAC;CACjD;AAmBD;;;;;;GAMG;AACH,wBAAsB,WAAW,CAC/B,OAAO,EAAE,cAAc,GAAG;IAAE,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAA;CAAE,GAC7D,OAAO,CAAC,mBAAmB,CAAC,CAkC9B;AAED;;;;GAIG;AACH,wBAAsB,wBAAwB,CAC5C,OAAO,EAAE,cAAc,GAAG;IAAE,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAA;CAAE,GAC5D,OAAO,CAAC,gCAAgC,CAAC,CA+B3C;AAED;;;GAGG;AACH,wBAAsB,YAAY,CAAC,OAAO,EAAE,cAAc,GAAG;IAAE,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAA;CAAE;;;;GAO/F"}

package/dist/analysis.js

@@ -1,5 +1,19 @@
 import { throwIfAborted } from '@aelionsdk/core';
 const MIN_CHANGE_DB = 6;
+function validateSource(options, threshold, label) {
+    if (!Number.isSafeInteger(options.sampleRate) || options.sampleRate <= 0) {
+        throw new RangeError(`${label} sampleRate must be a positive safe integer`);
+    }
+    if (!Number.isSafeInteger(options.channelCount) || options.channelCount <= 0) {
+        throw new RangeError(`${label} channelCount must be a positive safe integer`);
+    }
+    if (!Number.isSafeInteger(options.totalFrames) || options.totalFrames < 0) {
+        throw new RangeError(`${label} totalFrames must be a non-negative safe integer`);
+    }
+    if (!Number.isFinite(threshold) || threshold < 0) {
+        throw new RangeError(`${label} threshold must be a non-negative finite number`);
+    }
+}
 /**
  * Detect beats from an interleaved PCM source using a bounded energy-envelope
  * onset detector. The signal is processed in fixed windows, computing a local
@@ -12,6 +26,7 @@ export async function detectBeats(options) {
     const channelCount = options.channelCount;
     const totalFrames = options.totalFrames;
     const minimumOnsetDb = options.minimumOnsetDb ?? MIN_CHANGE_DB;
+    validateSource(options, minimumOnsetDb, 'Beat detection');
     const windowFrames = Math.max(1, Math.round(sampleRate / 20));
     const beats = [];
     let previousDb = 0;
@@ -33,28 +48,29 @@ export async function detectBeats(options) {
         const onset = db - floor > minimumOnsetDb && db > previousDb;
         if (onset && startFrame - lastBeatFrame >= windowFrames) {
             const strength = Math.min(1, Math.max(0, (db - floor) / 24));
-            beats.push({ frame: startFrame, frameCount: windowFrames, strength });
+            beats.push({ frame: startFrame, frameCount, strength });
             lastBeatFrame = startFrame;
         }
         previousDb = db;
         options.onProgress?.((startFrame + frameCount) / totalFrames);
     }
+    if (totalFrames === 0)
+        options.onProgress?.(1);
     return { sampleRate, totalFrames, beats };
 }
 /**
- * Detect scene boundaries as audio-energy discontinuities. A scene change in
- * video is usually accompanied by an abrupt change in the audio envelope, so a
- * large window-to-window energy jump is reported as a candidate boundary.
- * This is a deterministic, media-agnostic approximation driven by the same
- * readFrames source; it does not inspect video pixels.
+ * Detect audio-energy discontinuities as editing candidates. This function
+ * does not inspect video pixels and therefore deliberately makes no claim to
+ * detect scene boundaries.
  */
-export async function detectScenes(options) {
+export async function detectAudioEnergyChanges(options) {
     const sampleRate = options.sampleRate;
     const channelCount = options.channelCount;
     const totalFrames = options.totalFrames;
     const minimumJumpDb = options.minimumJumpDb ?? MIN_CHANGE_DB;
+    validateSource(options, minimumJumpDb, 'Audio energy analysis');
     const windowFrames = Math.max(1, Math.round(sampleRate / 10));
-    const scenes = [];
+    const changes = [];
     let previousDb = 0;
     for (let startFrame = 0; startFrame < totalFrames; startFrame += windowFrames) {
         throwIfAborted(options.signal, 'Scene detection');
@@ -71,11 +87,25 @@ export async function detectScenes(options) {
         if (startFrame > 0) {
             const jump = Math.abs(db - previousDb);
             if (jump >= minimumJumpDb) {
-                scenes.push({ frame: startFrame, magnitude: Math.min(1, jump / 24) });
+                changes.push({ frame: startFrame, magnitude: Math.min(1, jump / 24) });
             }
         }
         previousDb = db;
         options.onProgress?.((startFrame + frameCount) / totalFrames);
     }
-    return { sampleRate, totalFrames, scenes };
+    if (totalFrames === 0)
+        options.onProgress?.(1);
+    return { sampleRate, totalFrames, changes };
+}
+/**
+ * @deprecated Audio-only input cannot detect video scenes. Use
+ * `detectAudioEnergyChanges` and treat the result as editing candidates.
+ */
+export async function detectScenes(options) {
+    const result = await detectAudioEnergyChanges(options);
+    return {
+        sampleRate: result.sampleRate,
+        totalFrames: result.totalFrames,
+        scenes: result.changes,
+    };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aelionsdk/audio",
-  "version": "1.2.0-rc.1",
+  "version": "1.2.0-rc.3",
   "description": "AudioWorklet clock, PCM buffering and audio mixing for AelionSDK",
   "license": "MIT",
   "repository": {
@@ -34,8 +34,8 @@
     "provenance": true
   },
   "dependencies": {
-    "@aelionsdk/core": "1.2.0-rc.1",
-    "@aelionsdk/render-ir": "1.2.0-rc.1"
+    "@aelionsdk/core": "1.2.0-rc.3",
+    "@aelionsdk/render-ir": "1.2.0-rc.3"
   },
   "scripts": {
     "build": "tsc -b",