@gjsify/webaudio 0.4.0 → 0.4.4

package/package.json

@@ -1,53 +1,56 @@
 {
-  "name": "@gjsify/webaudio",
-  "version": "0.4.0",
-  "description": "Web Audio API for GJS using GStreamer as audio backend",
-  "type": "module",
-  "module": "lib/esm/index.js",
-  "types": "lib/types/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./lib/types/index.d.ts",
-      "default": "./lib/esm/index.js"
+    "name": "@gjsify/webaudio",
+    "version": "0.4.4",
+    "description": "Web Audio API for GJS using GStreamer as audio backend",
+    "type": "module",
+    "module": "lib/esm/index.js",
+    "types": "lib/types/index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./lib/types/index.d.ts",
+            "default": "./lib/esm/index.js"
+        },
+        "./register": {
+            "types": "./lib/types/register.d.ts",
+            "default": "./lib/esm/register.js"
+        }
     },
-    "./register": {
-      "types": "./lib/types/register.d.ts",
-      "default": "./lib/esm/register.js"
+    "files": [
+        "lib"
+    ],
+    "sideEffects": [
+        "./lib/esm/register.js"
+    ],
+    "scripts": {
+        "clear": "rm -rf lib tsconfig.tsbuildinfo tsconfig.types.tsbuildinfo test.gjs.mjs || exit 0",
+        "check": "tsc --noEmit",
+        "build": "gjsify run build:gjsify && gjsify run build:types",
+        "build:gjsify": "gjsify build --library 'src/**/*.{ts,js}' --exclude 'src/**/*.spec.{mts,ts}' 'src/test.{mts,ts}'",
+        "build:types": "tsc",
+        "build:test": "gjsify run build:test:gjs",
+        "build:test:gjs": "gjsify build src/test.mts --app gjs --outfile test.gjs.mjs",
+        "test": "gjsify run build:gjsify && gjsify run build:test && gjsify run test:gjs",
+        "test:gjs": "gjsify run test.gjs.mjs"
+    },
+    "keywords": [
+        "gjs",
+        "webaudio",
+        "gstreamer",
+        "audio-api"
+    ],
+    "dependencies": {
+        "@gjsify/dom-events": "^0.4.4"
+    },
+    "devDependencies": {
+        "@girs/gjs": "4.0.0-rc.15",
+        "@girs/glib-2.0": "2.88.0-4.0.0-rc.15",
+        "@girs/gst-1.0": "1.28.1-4.0.0-rc.15",
+        "@girs/gstapp-1.0": "1.0.0-4.0.0-rc.15",
+        "@girs/gstaudio-1.0": "1.0.0-4.0.0-rc.15",
+        "@girs/gstbase-1.0": "1.0.0-4.0.0-rc.15",
+        "@gjsify/cli": "^0.4.4",
+        "@gjsify/unit": "^0.4.4",
+        "@types/node": "^25.6.2",
+        "typescript": "^6.0.3"
     }
-  },
-  "sideEffects": [
-    "./lib/esm/register.js"
-  ],
-  "scripts": {
-    "clear": "rm -rf lib tsconfig.tsbuildinfo tsconfig.types.tsbuildinfo test.gjs.mjs || exit 0",
-    "check": "tsc --noEmit",
-    "build": "yarn build:gjsify && yarn build:types",
-    "build:gjsify": "gjsify build --library 'src/**/*.{ts,js}' --exclude 'src/**/*.spec.{mts,ts}' 'src/test.{mts,ts}'",
-    "build:types": "tsc",
-    "build:test": "yarn build:test:gjs",
-    "build:test:gjs": "gjsify build src/test.mts --app gjs --outfile test.gjs.mjs",
-    "test": "yarn build:gjsify && yarn build:test && yarn test:gjs",
-    "test:gjs": "gjsify run test.gjs.mjs"
-  },
-  "keywords": [
-    "gjs",
-    "webaudio",
-    "gstreamer",
-    "audio-api"
-  ],
-  "dependencies": {
-    "@gjsify/dom-events": "^0.4.0"
-  },
-  "devDependencies": {
-    "@girs/gjs": "4.0.0-rc.15",
-    "@girs/glib-2.0": "2.88.0-4.0.0-rc.15",
-    "@girs/gst-1.0": "1.28.1-4.0.0-rc.15",
-    "@girs/gstapp-1.0": "1.0.0-4.0.0-rc.15",
-    "@girs/gstaudio-1.0": "1.0.0-4.0.0-rc.15",
-    "@girs/gstbase-1.0": "1.0.0-4.0.0-rc.15",
-    "@gjsify/cli": "^0.4.0",
-    "@gjsify/unit": "^0.4.0",
-    "@types/node": "^25.6.2",
-    "typescript": "^6.0.3"
-  }
-}
+}

package/src/audio-buffer-source-node.ts

@@ -1,84 +0,0 @@
-// AudioBufferSourceNode — single-use audio playback node backed by GStreamer.
-//
-// W3C spec: each source node can only be started once. Excalibur creates a new
-// AudioBufferSourceNode for every play via _createNewBufferSource().
-//
-// Audio graph: AudioBufferSourceNode → GainNode → AudioDestinationNode
-//
-// Reference: https://developer.mozilla.org/en-US/docs/Web/API/AudioBufferSourceNode
-
-import { AudioNode } from './audio-node.js';
-import { AudioParam } from './audio-param.js';
-import { GstPlayer } from './gst-player.js';
-import { GainNode } from './gain-node.js';
-import type { AudioBuffer } from './audio-buffer.js';
-
-export class AudioBufferSourceNode extends AudioNode {
-    buffer: AudioBuffer | null = null;
-    loop = false;
-    loopStart = 0;
-    loopEnd = 0;
-    readonly playbackRate: AudioParam;
-    onended: (() => void) | null = null;
-
-    private _player: GstPlayer | null = null;
-    private _started = false;
-
-    constructor() {
-        super(0, 1); // 0 inputs (source node), 1 output
-        this.playbackRate = new AudioParam(1, 0.0625, 16);
-    }
-
-    start(when = 0, offset = 0, duration?: number): void {
-        if (this._started) {
-            throw new DOMException('AudioBufferSourceNode can only be started once', 'InvalidStateError');
-        }
-        this._started = true;
-
-        if (!this.buffer) return;
-
-        // Walk connection chain to find GainNode and its volume
-        const gainNode = this._findGainNode();
-        const volume = gainNode ? gainNode.gain.value : 1;
-
-        this._player = new GstPlayer({
-            audioBuffer: this.buffer,
-            volume,
-            loop: this.loop,
-            offset,
-            duration,
-            playbackRate: this.playbackRate.value,
-            onEnded: () => {
-                // Unregister from GainNode
-                if (gainNode) {
-                    gainNode._activePlayers.delete(this._player!);
-                }
-                this._player = null;
-                this.onended?.();
-            },
-        });
-
-        // Register with GainNode for live volume updates
-        if (gainNode && this._player) {
-            gainNode._activePlayers.add(this._player);
-        }
-    }
-
-    stop(_when = 0): void {
-        if (this._player) {
-            this._player.stop();
-        }
-    }
-
-    /** Walk the output chain to find a GainNode */
-    private _findGainNode(): GainNode | null {
-        for (const node of this._outputs) {
-            if (node instanceof GainNode) return node;
-            // Check one level deeper (in case of intermediary nodes)
-            for (const inner of node._outputs) {
-                if (inner instanceof GainNode) return inner;
-            }
-        }
-        return null;
-    }
-}

package/src/audio-buffer.ts

@@ -1,47 +0,0 @@
-// AudioBuffer — holds decoded PCM audio data as per-channel Float32Arrays.
-// Reference: https://developer.mozilla.org/en-US/docs/Web/API/AudioBuffer
-
-export interface AudioBufferOptions {
-    numberOfChannels: number;
-    length: number;
-    sampleRate: number;
-}
-
-export class AudioBuffer {
-    readonly sampleRate: number;
-    readonly length: number;
-    readonly duration: number;
-    readonly numberOfChannels: number;
-    /** @internal */
-    _channelData: Float32Array[];
-
-    constructor(options: AudioBufferOptions) {
-        this.sampleRate = options.sampleRate;
-        this.length = options.length;
-        this.numberOfChannels = options.numberOfChannels;
-        this.duration = this.length / this.sampleRate;
-        this._channelData = [];
-        for (let i = 0; i < this.numberOfChannels; i++) {
-            this._channelData.push(new Float32Array(this.length));
-        }
-    }
-
-    getChannelData(channel: number): Float32Array {
-        if (channel < 0 || channel >= this.numberOfChannels) {
-            throw new RangeError(`channel index ${channel} out of range [0, ${this.numberOfChannels})`);
-        }
-        return this._channelData[channel];
-    }
-
-    copyFromChannel(destination: Float32Array, channelNumber: number, bufferOffset = 0): void {
-        const src = this.getChannelData(channelNumber);
-        const len = Math.min(destination.length, src.length - bufferOffset);
-        destination.set(src.subarray(bufferOffset, bufferOffset + len));
-    }
-
-    copyToChannel(source: Float32Array, channelNumber: number, bufferOffset = 0): void {
-        const dest = this.getChannelData(channelNumber);
-        const len = Math.min(source.length, dest.length - bufferOffset);
-        dest.set(source.subarray(0, len), bufferOffset);
-    }
-}

package/src/audio-context.ts

@@ -1,102 +0,0 @@
-// AudioContext — top-level Web Audio API entry point backed by GStreamer.
-//
-// Phase 1: covers Excalibur.js needs (decodeAudioData, createBufferSource,
-// createGain, currentTime, resume/suspend/close).
-//
-// Reference: https://developer.mozilla.org/en-US/docs/Web/API/AudioContext
-
-import GLib from 'gi://GLib?version=2.0';
-import { ensureGstInit } from './gst-init.js';
-import { AudioBuffer } from './audio-buffer.js';
-import { AudioNode } from './audio-node.js';
-import { AudioDestinationNode } from './audio-destination-node.js';
-import { AudioBufferSourceNode } from './audio-buffer-source-node.js';
-import { GainNode } from './gain-node.js';
-import { decodeAudioDataSync } from './gst-decoder.js';
-
-export class AudioContext {
-    state: AudioContextState = 'suspended';
-    readonly sampleRate = 44100;
-    readonly destination: AudioDestinationNode;
-    readonly listener = {};
-
-    private _startTime: number;
-
-    constructor() {
-        ensureGstInit();
-        this._startTime = GLib.get_monotonic_time();
-        this.destination = new AudioDestinationNode();
-    }
-
-    /** Monotonically increasing time in seconds since context creation. */
-    get currentTime(): number {
-        return (GLib.get_monotonic_time() - this._startTime) / 1_000_000;
-    }
-
-    createGain(): GainNode {
-        return new GainNode();
-    }
-
-    createBufferSource(): AudioBufferSourceNode {
-        return new AudioBufferSourceNode();
-    }
-
-    createBuffer(numberOfChannels: number, length: number, sampleRate: number): AudioBuffer {
-        return new AudioBuffer({ numberOfChannels, length, sampleRate });
-    }
-
-    /**
-     * Decode encoded audio data (MP3, WAV, OGG, etc.) into an AudioBuffer.
-     * Uses GStreamer's decodebin for format-agnostic decoding.
-     */
-    decodeAudioData(
-        arrayBuffer: ArrayBuffer,
-        successCallback?: (buffer: AudioBuffer) => void,
-        errorCallback?: (error: DOMException) => void
-    ): Promise<AudioBuffer> {
-        try {
-            const buffer = decodeAudioDataSync(arrayBuffer);
-            successCallback?.(buffer);
-            return Promise.resolve(buffer);
-        } catch (err) {
-            const domErr = err instanceof DOMException
-                ? err
-                : new DOMException('Unable to decode audio data', 'EncodingError');
-            errorCallback?.(domErr);
-            return Promise.reject(domErr);
-        }
-    }
-
-    async resume(): Promise<void> {
-        this.state = 'running';
-    }
-
-    async suspend(): Promise<void> {
-        this.state = 'suspended';
-    }
-
-    async close(): Promise<void> {
-        this.state = 'closed';
-    }
-
-    // Stub methods for APIs not yet backed by GStreamer (Phase 3)
-    createAnalyser(): any {
-        return {
-            connect: () => {},
-            disconnect: () => {},
-            fftSize: 2048,
-            frequencyBinCount: 1024,
-            getByteFrequencyData: () => {},
-            getFloatFrequencyData: () => {},
-        };
-    }
-
-    createDynamicsCompressor(): AudioNode { return new AudioNode(); }
-    createBiquadFilter(): any { return new AudioNode(); }
-    createConvolver(): AudioNode { return new AudioNode(); }
-    createPanner(): AudioNode { return new AudioNode(); }
-    createStereoPanner(): AudioNode { return new AudioNode(); }
-
-    addEventListener(_type: string, _listener: any): void {}
-    removeEventListener(_type: string, _listener: any): void {}
-}

package/src/audio-destination-node.ts

@@ -1,12 +0,0 @@
-// AudioDestinationNode — represents the final audio output (speakers).
-// Reference: https://developer.mozilla.org/en-US/docs/Web/API/AudioDestinationNode
-
-import { AudioNode } from './audio-node.js';
-
-export class AudioDestinationNode extends AudioNode {
-    readonly maxChannelCount = 2;
-
-    constructor() {
-        super(1, 0); // 1 input, 0 outputs (terminal node)
-    }
-}

package/src/audio-node.ts

@@ -1,37 +0,0 @@
-// AudioNode — base class for all audio graph nodes.
-// Reference: https://developer.mozilla.org/en-US/docs/Web/API/AudioNode
-
-export class AudioNode {
-    /** @internal downstream connections */
-    _outputs: Set<AudioNode> = new Set();
-    /** @internal upstream connections */
-    _inputs: Set<AudioNode> = new Set();
-
-    readonly numberOfInputs: number;
-    readonly numberOfOutputs: number;
-    readonly channelCount: number;
-
-    constructor(numberOfInputs = 1, numberOfOutputs = 1) {
-        this.numberOfInputs = numberOfInputs;
-        this.numberOfOutputs = numberOfOutputs;
-        this.channelCount = 2;
-    }
-
-    connect(destination: AudioNode): AudioNode {
-        this._outputs.add(destination);
-        destination._inputs.add(this);
-        return destination;
-    }
-
-    disconnect(destination?: AudioNode): void {
-        if (destination) {
-            this._outputs.delete(destination);
-            destination._inputs.delete(this);
-        } else {
-            for (const node of this._outputs) {
-                node._inputs.delete(this);
-            }
-            this._outputs.clear();
-        }
-    }
-}

package/src/audio-param.ts

@@ -1,103 +0,0 @@
-// AudioParam — holds a value with scheduling support.
-// Phase 1: direct .value + setTargetAtTime (used by Excalibur.js).
-// Reference: https://developer.mozilla.org/en-US/docs/Web/API/AudioParam
-
-import GLib from 'gi://GLib?version=2.0';
-
-export class AudioParam {
-    readonly defaultValue: number;
-    readonly minValue: number;
-    readonly maxValue: number;
-
-    /** @internal callback invoked when value changes */
-    _onChange: ((value: number) => void) | null = null;
-
-    private _value: number;
-    private _rampTimerId: number | null = null;
-
-    constructor(defaultValue = 0, minValue = -3.4028235e38, maxValue = 3.4028235e38) {
-        this.defaultValue = defaultValue;
-        this.minValue = minValue;
-        this.maxValue = maxValue;
-        this._value = defaultValue;
-    }
-
-    get value(): number {
-        return this._value;
-    }
-
-    set value(v: number) {
-        this._cancelRamp();
-        this._value = Math.max(this.minValue, Math.min(this.maxValue, v));
-        this._onChange?.(this._value);
-    }
-
-    setValueAtTime(value: number, _startTime: number): AudioParam {
-        // Phase 1: apply immediately (ignore scheduling)
-        this.value = value;
-        return this;
-    }
-
-    linearRampToValueAtTime(value: number, _endTime: number): AudioParam {
-        // Phase 1: apply immediately
-        this.value = value;
-        return this;
-    }
-
-    exponentialRampToValueAtTime(value: number, _endTime: number): AudioParam {
-        // Phase 1: apply immediately
-        this.value = value;
-        return this;
-    }
-
-    setTargetAtTime(target: number, _startTime: number, timeConstant: number): AudioParam {
-        // Exponential approach used by Excalibur for smooth volume transitions.
-        // After each timeConstant interval, value moves ~63.2% closer to target.
-        this._cancelRamp();
-
-        if (timeConstant <= 0) {
-            this.value = target;
-            return this;
-        }
-
-        const stepMs = Math.max(10, Math.round(timeConstant * 100)); // ~10 steps per timeConstant
-        this._rampTimerId = GLib.timeout_add(GLib.PRIORITY_DEFAULT, stepMs, () => {
-            const diff = target - this._value;
-            if (Math.abs(diff) < 0.001) {
-                this._value = target;
-                this._onChange?.(this._value);
-                this._rampTimerId = null;
-                return GLib.SOURCE_REMOVE;
-            }
-            // Exponential approach: move 1 - e^(-dt/tc) closer per step
-            const factor = 1 - Math.exp(-stepMs / (timeConstant * 1000));
-            this._value += diff * factor;
-            this._onChange?.(this._value);
-            return GLib.SOURCE_CONTINUE;
-        });
-
-        return this;
-    }
-
-    setValueCurveAtTime(_values: Float32Array, _startTime: number, _duration: number): AudioParam {
-        // Phase 1: no-op
-        return this;
-    }
-
-    cancelScheduledValues(_startTime: number): AudioParam {
-        this._cancelRamp();
-        return this;
-    }
-
-    cancelAndHoldAtTime(_cancelTime: number): AudioParam {
-        this._cancelRamp();
-        return this;
-    }
-
-    private _cancelRamp(): void {
-        if (this._rampTimerId !== null) {
-            GLib.source_remove(this._rampTimerId);
-            this._rampTimerId = null;
-        }
-    }
-}

package/src/gain-node.ts

@@ -1,23 +0,0 @@
-// GainNode — controls audio volume via an AudioParam.
-// Reference: https://developer.mozilla.org/en-US/docs/Web/API/GainNode
-
-import { AudioNode } from './audio-node.js';
-import { AudioParam } from './audio-param.js';
-import type { GstPlayer } from './gst-player.js';
-
-export class GainNode extends AudioNode {
-    readonly gain: AudioParam;
-
-    /** @internal active players that need volume updates */
-    _activePlayers: Set<GstPlayer> = new Set();
-
-    constructor() {
-        super(1, 1);
-        this.gain = new AudioParam(1, 0, 10);
-        this.gain._onChange = (value) => {
-            for (const player of this._activePlayers) {
-                player.setVolume(value);
-            }
-        };
-    }
-}

package/src/gst-decoder.ts

@@ -1,109 +0,0 @@
-// GStreamer decode pipeline: ArrayBuffer (MP3/WAV/OGG) → AudioBuffer (PCM Float32)
-//
-// Pipeline: appsrc → decodebin → audioconvert → audioresample → capsfilter(F32LE) → appsink
-// Uses try_pull_sample() for synchronous decoding (avoids GJS thread-safety issues).
-//
-// Reference: GStreamer 1.0 via gi://Gst, GstApp via gi://GstApp
-
-import { ensureGstInit, Gst } from './gst-init.js';
-import { AudioBuffer } from './audio-buffer.js';
-
-// Force GstApp typelib load so get_by_name() resolves AppSrc/AppSink types
-import GstApp from 'gi://GstApp?version=1.0';
-void GstApp;
-
-const PIPELINE_DESC =
-    'appsrc name=src ! decodebin ! audioconvert ! audioresample ! ' +
-    'capsfilter caps=audio/x-raw,format=F32LE,layout=interleaved ! ' +
-    'appsink name=sink sync=false';
-
-/**
- * Decode encoded audio data (MP3, WAV, OGG, FLAC, etc.) into an AudioBuffer
- * containing PCM Float32 channel data.
- *
- * This is a synchronous operation that blocks until decoding completes.
- * It must be called from the main thread (GJS requirement).
- */
-export function decodeAudioDataSync(arrayBuffer: ArrayBuffer): AudioBuffer {
-    ensureGstInit();
-
-    // Reject non-ArrayBuffer / empty input before touching GStreamer —
-    // gst_memory_new_wrapped() asserts data != NULL and empty TypedArrays
-    // marshal to a NULL pointer through GI.
-    if (!(arrayBuffer instanceof ArrayBuffer) || arrayBuffer.byteLength === 0) {
-        throw new DOMException('Unable to decode audio data', 'EncodingError');
-    }
-
-    const pipeline = Gst.parse_launch(PIPELINE_DESC) as Gst.Bin;
-    const appsrc = pipeline.get_by_name('src')!;
-    const appsink = pipeline.get_by_name('sink')!;
-
-    pipeline.set_state(Gst.State.PLAYING);
-
-    // Push encoded data into the pipeline
-    const data = new Uint8Array(arrayBuffer);
-    (appsrc as any).push_buffer(Gst.Buffer.new_wrapped(data));
-    (appsrc as any).end_of_stream();
-
-    // Pull decoded PCM samples
-    const chunks: Uint8Array[] = [];
-    let sampleRate = 0;
-    let channels = 0;
-
-    while (true) {
-        const sample = (appsink as any).try_pull_sample(2 * Number(Gst.SECOND));
-        if (!sample) break;
-
-        // Read format from the first sample's negotiated caps
-        if (sampleRate === 0) {
-            const caps = sample.get_caps();
-            if (caps) {
-                const struct = caps.get_structure(0);
-                [, sampleRate] = struct.get_int('rate');
-                [, channels] = struct.get_int('channels');
-            }
-        }
-
-        const buffer = sample.get_buffer();
-        if (!buffer) continue;
-
-        const [ok, mapInfo] = buffer.map(Gst.MapFlags.READ);
-        if (ok) {
-            // Copy data — mapInfo.data is only valid until unmap
-            chunks.push(new Uint8Array(mapInfo.data));
-            buffer.unmap(mapInfo);
-        }
-    }
-
-    pipeline.set_state(Gst.State.NULL);
-
-    if (sampleRate === 0 || channels === 0) {
-        throw new DOMException('Unable to decode audio data', 'EncodingError');
-    }
-
-    // Concatenate chunks into a single interleaved Float32 buffer
-    let totalBytes = 0;
-    for (const c of chunks) totalBytes += c.length;
-    const totalFrames = totalBytes / (4 * channels);
-
-    const audioBuffer = new AudioBuffer({
-        numberOfChannels: channels,
-        length: totalFrames,
-        sampleRate,
-    });
-
-    // De-interleave into per-channel Float32Arrays
-    let offset = 0;
-    for (const chunk of chunks) {
-        const f32 = new Float32Array(chunk.buffer, chunk.byteOffset, chunk.length / 4);
-        const framesInChunk = f32.length / channels;
-        for (let frame = 0; frame < framesInChunk; frame++) {
-            for (let ch = 0; ch < channels; ch++) {
-                audioBuffer._channelData[ch][offset + frame] = f32[frame * channels + ch];
-            }
-        }
-        offset += framesInChunk;
-    }
-
-    return audioBuffer;
-}

package/src/gst-init.ts

@@ -1,15 +0,0 @@
-// Lazy GStreamer initialization — call ensureGstInit() before any Gst API usage.
-// Reference: GStreamer 1.0 via gi://Gst
-
-import Gst from 'gi://Gst?version=1.0';
-
-let initialized = false;
-
-export function ensureGstInit(): void {
-    if (!initialized) {
-        Gst.init(null);
-        initialized = true;
-    }
-}
-
-export { Gst };