@gjsify/webaudio 0.1.9

package/lib/types/audio-context.d.ts

@@ -0,0 +1,34 @@
+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';
+export declare class AudioContext {
+    state: AudioContextState;
+    readonly sampleRate = 44100;
+    readonly destination: AudioDestinationNode;
+    readonly listener: {};
+    private _startTime;
+    constructor();
+    /** Monotonically increasing time in seconds since context creation. */
+    get currentTime(): number;
+    createGain(): GainNode;
+    createBufferSource(): AudioBufferSourceNode;
+    createBuffer(numberOfChannels: number, length: number, sampleRate: number): AudioBuffer;
+    /**
+     * 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>;
+    resume(): Promise<void>;
+    suspend(): Promise<void>;
+    close(): Promise<void>;
+    createAnalyser(): any;
+    createDynamicsCompressor(): AudioNode;
+    createBiquadFilter(): any;
+    createConvolver(): AudioNode;
+    createPanner(): AudioNode;
+    createStereoPanner(): AudioNode;
+    addEventListener(_type: string, _listener: any): void;
+    removeEventListener(_type: string, _listener: any): void;
+}

package/lib/types/audio-destination-node.d.ts

@@ -0,0 +1,5 @@
+import { AudioNode } from './audio-node.js';
+export declare class AudioDestinationNode extends AudioNode {
+    readonly maxChannelCount = 2;
+    constructor();
+}

package/lib/types/audio-node.d.ts

@@ -0,0 +1,12 @@
+export declare class AudioNode {
+    /** @internal downstream connections */
+    _outputs: Set<AudioNode>;
+    /** @internal upstream connections */
+    _inputs: Set<AudioNode>;
+    readonly numberOfInputs: number;
+    readonly numberOfOutputs: number;
+    readonly channelCount: number;
+    constructor(numberOfInputs?: number, numberOfOutputs?: number);
+    connect(destination: AudioNode): AudioNode;
+    disconnect(destination?: AudioNode): void;
+}

package/lib/types/audio-param.d.ts

@@ -0,0 +1,20 @@
+export declare class AudioParam {
+    readonly defaultValue: number;
+    readonly minValue: number;
+    readonly maxValue: number;
+    /** @internal callback invoked when value changes */
+    _onChange: ((value: number) => void) | null;
+    private _value;
+    private _rampTimerId;
+    constructor(defaultValue?: number, minValue?: number, maxValue?: number);
+    get value(): number;
+    set value(v: number);
+    setValueAtTime(value: number, _startTime: number): AudioParam;
+    linearRampToValueAtTime(value: number, _endTime: number): AudioParam;
+    exponentialRampToValueAtTime(value: number, _endTime: number): AudioParam;
+    setTargetAtTime(target: number, _startTime: number, timeConstant: number): AudioParam;
+    setValueCurveAtTime(_values: Float32Array, _startTime: number, _duration: number): AudioParam;
+    cancelScheduledValues(_startTime: number): AudioParam;
+    cancelAndHoldAtTime(_cancelTime: number): AudioParam;
+    private _cancelRamp;
+}

package/lib/types/gain-node.d.ts

@@ -0,0 +1,9 @@
+import { AudioNode } from './audio-node.js';
+import { AudioParam } from './audio-param.js';
+import type { GstPlayer } from './gst-player.js';
+export declare class GainNode extends AudioNode {
+    readonly gain: AudioParam;
+    /** @internal active players that need volume updates */
+    _activePlayers: Set<GstPlayer>;
+    constructor();
+}

package/lib/types/gst-decoder.d.ts

@@ -0,0 +1,9 @@
+import { AudioBuffer } from './audio-buffer.js';
+/**
+ * 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 declare function decodeAudioDataSync(arrayBuffer: ArrayBuffer): AudioBuffer;

package/lib/types/gst-init.d.ts

@@ -0,0 +1,3 @@
+import Gst from 'gi://Gst?version=1.0';
+export declare function ensureGstInit(): void;
+export { Gst };

package/lib/types/gst-player.d.ts

@@ -0,0 +1,39 @@
+import type { AudioBuffer } from './audio-buffer.js';
+export interface GstPlayerOptions {
+    audioBuffer: AudioBuffer;
+    volume: number;
+    loop: boolean;
+    offset: number;
+    duration?: number;
+    playbackRate: number;
+    onEnded: () => void;
+}
+/**
+ * Manages a single GStreamer playback pipeline for one AudioBufferSourceNode.start() call.
+ */
+export declare class GstPlayer {
+    private _pipeline;
+    private _volumeElement;
+    private _busWatchId;
+    private _ended;
+    private _loop;
+    private _onEnded;
+    private _audioBuffer;
+    constructor(options: GstPlayerOptions);
+    /** Update volume on a running pipeline */
+    setVolume(value: number): void;
+    /** Update loop flag */
+    setLoop(value: boolean): void;
+    /** Stop playback and clean up */
+    stop(): void;
+    /** Whether playback has ended */
+    get ended(): boolean;
+    private _restartPlayback;
+    private _fireEnded;
+    private _cleanup;
+    /**
+     * Interleave AudioBuffer's per-channel Float32Arrays into a single Uint8Array.
+     * Applies offset (seconds) and optional duration (seconds).
+     */
+    private _interleave;
+}

package/lib/types/html-audio-element.d.ts

@@ -0,0 +1,17 @@
+export declare class HTMLAudioElement {
+    src: string;
+    volume: number;
+    loop: boolean;
+    paused: boolean;
+    currentTime: number;
+    duration: number;
+    readyState: number;
+    private _pipeline;
+    canPlayType(type: string): CanPlayTypeResult;
+    play(): Promise<void>;
+    pause(): void;
+    load(): void;
+    addEventListener(_type: string, _listener: any): void;
+    removeEventListener(_type: string, _listener: any): void;
+    private _cleanup;
+}

package/lib/types/index.d.ts

@@ -0,0 +1,8 @@
+export { AudioContext } from './audio-context.js';
+export { AudioBuffer } from './audio-buffer.js';
+export { AudioNode } from './audio-node.js';
+export { AudioDestinationNode } from './audio-destination-node.js';
+export { AudioBufferSourceNode } from './audio-buffer-source-node.js';
+export { GainNode } from './gain-node.js';
+export { AudioParam } from './audio-param.js';
+export { HTMLAudioElement } from './html-audio-element.js';

package/lib/types/register.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/types/webaudio.spec.d.ts

@@ -0,0 +1,2 @@
+declare const _default: () => Promise<void>;
+export default _default;

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@gjsify/webaudio",
+  "version": "0.1.9",
+  "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"
+    }
+  },
+  "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": "gjs -m test.gjs.mjs"
+  },
+  "keywords": [
+    "gjs",
+    "webaudio",
+    "gstreamer",
+    "audio-api"
+  ],
+  "dependencies": {
+    "@gjsify/dom-events": "^0.1.9"
+  },
+  "devDependencies": {
+    "@girs/gjs": "^4.0.0-rc.2",
+    "@girs/glib-2.0": "^2.88.0-4.0.0-rc.2",
+    "@girs/gst-1.0": "^1.28.1-4.0.0-rc.2",
+    "@girs/gstapp-1.0": "^1.0.0-4.0.0-rc.2",
+    "@girs/gstaudio-1.0": "^1.0.0-4.0.0-rc.2",
+    "@girs/gstbase-1.0": "^1.0.0-4.0.0-rc.2",
+    "@gjsify/cli": "^0.1.9",
+    "@gjsify/unit": "^0.1.9",
+    "@types/node": "^25.6.0",
+    "typescript": "^6.0.2"
+  }
+}

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

@@ -0,0 +1,84 @@
+// 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

@@ -0,0 +1,47 @@
+// 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

@@ -0,0 +1,102 @@
+// 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

@@ -0,0 +1,12 @@
+// 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

@@ -0,0 +1,37 @@
+// 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

@@ -0,0 +1,103 @@
+// 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

@@ -0,0 +1,23 @@
+// 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);
+            }
+        };
+    }
+}