waa-play 0.1.0

package/dist/types-DUrbEbPl.d.ts

@@ -0,0 +1,177 @@
+/** Possible states of a Playback instance. */
+type PlaybackState = "playing" | "paused" | "stopped";
+/** Options accepted by `play()`. */
+interface PlayOptions {
+    /** Start offset in seconds within the buffer. @default 0 */
+    offset?: number;
+    /** Whether the source should loop. @default false */
+    loop?: boolean;
+    /** Loop region start in seconds. */
+    loopStart?: number;
+    /** Loop region end in seconds. */
+    loopEnd?: number;
+    /** Playback speed multiplier. @default 1 */
+    playbackRate?: number;
+    /**
+     * A chain of AudioNodes the source should route through before reaching the
+     * destination. The first node receives the source output; the last node is
+     * connected to `destination`.
+     */
+    through?: AudioNode[];
+    /**
+     * Final destination node. Defaults to `ctx.destination`.
+     */
+    destination?: AudioNode;
+    /**
+     * Interval (ms) for `timeupdate` events. @default 50
+     */
+    timeupdateInterval?: number;
+    /**
+     * Enable pitch-preserving time-stretch via WSOLA.
+     * When true, `playbackRate` controls tempo without changing pitch.
+     * @default true
+     */
+    preservePitch?: boolean;
+}
+/** Stretcher snapshot extension (re-declared here to avoid static import). */
+interface StretcherSnapshotExtension {
+    tempo: number;
+    converting: boolean;
+    conversionProgress: number;
+    bufferHealth: "healthy" | "low" | "critical" | "empty";
+    aheadSeconds: number;
+    buffering: boolean;
+    chunkStates: ("pending" | "queued" | "converting" | "ready" | "failed" | "skipped" | "evicted")[];
+    currentChunkIndex: number;
+    activeWindowStart: number;
+    activeWindowEnd: number;
+    totalChunks: number;
+    windowConversionProgress: number;
+}
+/** An immutable snapshot of a Playback's current state. */
+interface PlaybackSnapshot {
+    state: PlaybackState;
+    position: number;
+    duration: number;
+    progress: number;
+    stretcher?: StretcherSnapshotExtension;
+}
+/** Event map emitted by a Playback instance. */
+interface PlaybackEventMap {
+    play: void;
+    pause: void;
+    resume: void;
+    seek: {
+        position: number;
+    };
+    stop: void;
+    ended: void;
+    loop: void;
+    statechange: {
+        state: PlaybackState;
+    };
+    timeupdate: {
+        position: number;
+        duration: number;
+    };
+    buffering: {
+        reason: "initial" | "seek" | "tempo-change" | "underrun";
+    };
+    buffered: {
+        stallDuration: number;
+    };
+}
+/** The object returned by `play()`. */
+interface Playback {
+    /** Current playback state. */
+    getState(): PlaybackState;
+    /** Current playback position in seconds (AudioContext‑accurate). */
+    getCurrentTime(): number;
+    /** Total duration of the underlying buffer in seconds. */
+    getDuration(): number;
+    /** Current progress as a ratio 0 – 1. */
+    getProgress(): number;
+    pause(): void;
+    resume(): void;
+    togglePlayPause(): void;
+    seek(position: number): void;
+    stop(): void;
+    setPlaybackRate(rate: number): void;
+    setLoop(loop: boolean): void;
+    /** Subscribe to a playback event. Returns an unsubscribe function. */
+    on<K extends keyof PlaybackEventMap>(event: K, handler: (data: PlaybackEventMap[K]) => void): () => void;
+    /** Unsubscribe a previously registered handler. */
+    off<K extends keyof PlaybackEventMap>(event: K, handler: (data: PlaybackEventMap[K]) => void): void;
+    /** Release all resources (source node, timers, listeners). */
+    dispose(): void;
+}
+/** Options for `loadBuffer`. */
+interface LoadBufferOptions {
+    /** Progress callback receiving a value between 0 and 1 (if available). */
+    onProgress?: (progress: number) => void;
+}
+/** Information about an AudioBuffer. */
+interface BufferInfo {
+    duration: number;
+    numberOfChannels: number;
+    sampleRate: number;
+    length: number;
+}
+/** Options for waveform extraction functions. */
+interface ExtractPeaksOptions {
+    /** Number of output data points. @default 200 */
+    resolution?: number;
+    /** Channel index to analyze. @default 0 */
+    channel?: number;
+}
+/** A min/max pair representing a single segment of the waveform. */
+interface PeakPair {
+    min: number;
+    max: number;
+}
+/** Curve types for fade operations. */
+type FadeCurve = "linear" | "exponential" | "equal-power";
+/** Options for fade functions. */
+interface FadeOptions {
+    /** Duration of the fade in seconds. @default 1 */
+    duration?: number;
+    /** Easing curve. @default "linear" */
+    curve?: FadeCurve;
+}
+/** Options for crossfade. */
+interface CrossfadeOptions extends FadeOptions {
+}
+/** Options for autoFade. */
+interface AutoFadeOptions {
+    /** Fade-in duration at the start in seconds. @default 0 */
+    fadeIn?: number;
+    /** Fade-out duration before the end in seconds. @default 0 */
+    fadeOut?: number;
+    /** Curve for both fades. @default "linear" */
+    curve?: FadeCurve;
+}
+/** Options for `createScheduler`. */
+interface SchedulerOptions {
+    /** How far ahead (seconds) to schedule events. @default 0.1 */
+    lookahead?: number;
+    /** Interval (ms) between scheduler ticks. @default 25 */
+    interval?: number;
+}
+/** A scheduled event entry. */
+interface ScheduledEvent {
+    id: string;
+    time: number;
+    callback: (time: number) => void;
+}
+/** Options for `createClock`. */
+interface ClockOptions {
+    /** Beats per minute. @default 120 */
+    bpm?: number;
+}
+/** Options for `createContext`. */
+interface CreateContextOptions {
+    sampleRate?: number;
+    latencyHint?: AudioContextLatencyCategory | number;
+}
+
+export type { AutoFadeOptions as A, BufferInfo as B, ClockOptions as C, ExtractPeaksOptions as E, FadeCurve as F, LoadBufferOptions as L, PeakPair as P, ScheduledEvent as S, CreateContextOptions as a, CrossfadeOptions as b, FadeOptions as c, PlayOptions as d, Playback as e, PlaybackEventMap as f, PlaybackSnapshot as g, PlaybackState as h, SchedulerOptions as i, StretcherSnapshotExtension as j };

package/dist/waveform.cjs

@@ -0,0 +1,20 @@
+'use strict';
+
+var chunkQFFQQMU4_cjs = require('./chunk-QFFQQMU4.cjs');
+
+
+
+Object.defineProperty(exports, "extractPeakPairs", {
+  enumerable: true,
+  get: function () { return chunkQFFQQMU4_cjs.extractPeakPairs; }
+});
+Object.defineProperty(exports, "extractPeaks", {
+  enumerable: true,
+  get: function () { return chunkQFFQQMU4_cjs.extractPeaks; }
+});
+Object.defineProperty(exports, "extractRMS", {
+  enumerable: true,
+  get: function () { return chunkQFFQQMU4_cjs.extractRMS; }
+});
+//# sourceMappingURL=waveform.cjs.map
+//# sourceMappingURL=waveform.cjs.map

package/dist/waveform.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"waveform.cjs"}

package/dist/waveform.d.cts

@@ -0,0 +1,22 @@
+import { E as ExtractPeaksOptions, P as PeakPair } from './types-DUrbEbPl.cjs';
+
+/**
+ * Extract normalised peak amplitude values from an `AudioBuffer`.
+ * Returns an array of numbers in the range `[0, 1]`.
+ */
+declare function extractPeaks(buffer: AudioBuffer, options?: ExtractPeaksOptions): number[];
+/**
+ * Extract min/max peak pairs for detailed waveform rendering.
+ */
+declare function extractPeakPairs(buffer: AudioBuffer, options?: ExtractPeaksOptions): PeakPair[];
+/**
+ * Extract RMS (root mean square) values representing perceived loudness.
+ * Returns values in the range `[0, 1]`.
+ *
+ * When `channel` is set to `-1`, all channels are averaged.
+ */
+declare function extractRMS(buffer: AudioBuffer, options?: ExtractPeaksOptions & {
+    channel?: number;
+}): number[];
+
+export { extractPeakPairs, extractPeaks, extractRMS };

package/dist/waveform.d.ts

@@ -0,0 +1,22 @@
+import { E as ExtractPeaksOptions, P as PeakPair } from './types-DUrbEbPl.js';
+
+/**
+ * Extract normalised peak amplitude values from an `AudioBuffer`.
+ * Returns an array of numbers in the range `[0, 1]`.
+ */
+declare function extractPeaks(buffer: AudioBuffer, options?: ExtractPeaksOptions): number[];
+/**
+ * Extract min/max peak pairs for detailed waveform rendering.
+ */
+declare function extractPeakPairs(buffer: AudioBuffer, options?: ExtractPeaksOptions): PeakPair[];
+/**
+ * Extract RMS (root mean square) values representing perceived loudness.
+ * Returns values in the range `[0, 1]`.
+ *
+ * When `channel` is set to `-1`, all channels are averaged.
+ */
+declare function extractRMS(buffer: AudioBuffer, options?: ExtractPeaksOptions & {
+    channel?: number;
+}): number[];
+
+export { extractPeakPairs, extractPeaks, extractRMS };

package/dist/waveform.js

@@ -0,0 +1,3 @@
+export { extractPeakPairs, extractPeaks, extractRMS } from './chunk-CRODJ4KS.js';
+//# sourceMappingURL=waveform.js.map
+//# sourceMappingURL=waveform.js.map

package/dist/waveform.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"waveform.js"}

package/package.json

@@ -0,0 +1,123 @@
+{
+  "name": "waa-play",
+  "version": "0.1.0",
+  "description": "Composable Web Audio API utilities. BYO AudioContext. Framework-agnostic. Sample-accurate. Pitch-preserving time-stretch.",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./context": {
+      "import": {
+        "types": "./dist/context.d.ts",
+        "default": "./dist/context.js"
+      }
+    },
+    "./buffer": {
+      "import": {
+        "types": "./dist/buffer.d.ts",
+        "default": "./dist/buffer.js"
+      }
+    },
+    "./play": {
+      "import": {
+        "types": "./dist/play.d.ts",
+        "default": "./dist/play.js"
+      }
+    },
+    "./emitter": {
+      "import": {
+        "types": "./dist/emitter.d.ts",
+        "default": "./dist/emitter.js"
+      }
+    },
+    "./nodes": {
+      "import": {
+        "types": "./dist/nodes.d.ts",
+        "default": "./dist/nodes.js"
+      }
+    },
+    "./waveform": {
+      "import": {
+        "types": "./dist/waveform.d.ts",
+        "default": "./dist/waveform.js"
+      }
+    },
+    "./fade": {
+      "import": {
+        "types": "./dist/fade.d.ts",
+        "default": "./dist/fade.js"
+      }
+    },
+    "./scheduler": {
+      "import": {
+        "types": "./dist/scheduler.d.ts",
+        "default": "./dist/scheduler.js"
+      }
+    },
+    "./synth": {
+      "import": {
+        "types": "./dist/synth.d.ts",
+        "default": "./dist/synth.js"
+      }
+    },
+    "./adapters": {
+      "import": {
+        "types": "./dist/adapters.d.ts",
+        "default": "./dist/adapters.js"
+      }
+    },
+    "./stretcher": {
+      "import": {
+        "types": "./dist/stretcher.d.ts",
+        "default": "./dist/stretcher.js"
+      }
+    }
+  },
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "lint": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "web-audio",
+    "audio",
+    "sound",
+    "webaudio",
+    "audiocontext",
+    "composable",
+    "tree-shakeable"
+  ],
+  "license": "MIT",
+  "author": "ivgtr",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ivgtr/waa.git"
+  },
+  "homepage": "https://ivgtr.github.io/waa/",
+  "bugs": "https://github.com/ivgtr/waa/issues",
+  "dependencies": {},
+  "devDependencies": {
+    "tsup": "^8.4.0",
+    "typescript": "^5.7.0",
+    "vitest": "^2.1.0"
+  }
+}