@gjsify/webaudio 0.1.9

package/src/gst-decoder.ts

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

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

package/src/gst-player.ts

@@ -0,0 +1,178 @@
+// GStreamer playback pipeline: AudioBuffer PCM → audio output
+//
+// Pipeline: appsrc(F32LE) → audioconvert → volume → autoaudiosink
+// Each GstPlayer instance is single-use (matches W3C AudioBufferSourceNode).
+//
+// Reference: GStreamer 1.0 via gi://Gst
+
+import { ensureGstInit, Gst } from './gst-init.js';
+import type { AudioBuffer } from './audio-buffer.js';
+
+// Force GstApp typelib load
+import GstApp from 'gi://GstApp?version=1.0';
+void GstApp;
+
+export interface GstPlayerOptions {
+    audioBuffer: AudioBuffer;
+    volume: number;
+    loop: boolean;
+    offset: number;      // start offset in seconds
+    duration?: number;    // play duration in seconds (undefined = full)
+    playbackRate: number;
+    onEnded: () => void;
+}
+
+/**
+ * Manages a single GStreamer playback pipeline for one AudioBufferSourceNode.start() call.
+ */
+export class GstPlayer {
+    private _pipeline: any = null;
+    private _volumeElement: any = null;
+    private _busWatchId: number | null = null;
+    private _ended = false;
+    private _loop: boolean;
+    private _onEnded: () => void;
+    private _audioBuffer: AudioBuffer;
+
+    constructor(options: GstPlayerOptions) {
+        ensureGstInit();
+        this._loop = options.loop;
+        this._onEnded = options.onEnded;
+        this._audioBuffer = options.audioBuffer;
+
+        const { audioBuffer, volume, offset, duration, playbackRate } = options;
+        const sr = audioBuffer.sampleRate;
+        const ch = audioBuffer.numberOfChannels;
+
+        // Build interleaved PCM data
+        const pcmData = this._interleave(audioBuffer, offset, duration);
+        if (pcmData.length === 0) {
+            // Empty buffer — fire ended immediately
+            this._fireEnded();
+            return;
+        }
+
+        // Build pipeline — format=3 (TIME) ensures downstream gets TIME-based
+        // segments, preventing gst_segment_to_stream_time assertion failures.
+        const capsStr = `audio/x-raw,format=F32LE,rate=${sr},channels=${ch},layout=interleaved`;
+        const desc = `appsrc name=src caps="${capsStr}" format=3 ! audioconvert ! volume name=vol ! autoaudiosink`;
+        this._pipeline = Gst.parse_launch(desc);
+        this._volumeElement = this._pipeline.get_by_name('vol');
+        const appsrc = this._pipeline.get_by_name('src')!;
+
+        // Set volume
+        this._volumeElement.set_property('volume', Math.max(0, Math.min(volume, 10)));
+
+        // Set up bus watch for EOS/ERROR
+        const bus = this._pipeline.get_bus();
+        this._busWatchId = bus.add_watch(0, (_bus: any, msg: any) => {
+            if (msg.type === Gst.MessageType.EOS) {
+                if (this._loop && !this._ended) {
+                    // Restart: push data again
+                    this._restartPlayback(appsrc, pcmData);
+                } else {
+                    this._fireEnded();
+                }
+            } else if (msg.type === Gst.MessageType.ERROR) {
+                this._fireEnded();
+            }
+            return true; // keep watching
+        });
+
+        // Push PCM data with proper timestamps for TIME-format segments
+        const gstBuf = Gst.Buffer.new_wrapped(pcmData);
+        const totalFrames = pcmData.length / (4 * ch);
+        gstBuf.pts = 0;
+        gstBuf.duration = Math.floor((totalFrames / sr) * Number(Gst.SECOND));
+        appsrc.push_buffer(gstBuf);
+        appsrc.end_of_stream();
+
+        // Apply playback rate if not 1.0
+        if (playbackRate !== 1.0) {
+            this._pipeline.set_state(Gst.State.PAUSED);
+            // Seek with rate change
+            this._pipeline.seek(
+                playbackRate,
+                Gst.Format.TIME,
+                Gst.SeekFlags.FLUSH | Gst.SeekFlags.ACCURATE,
+                Gst.SeekType.SET, 0,
+                Gst.SeekType.NONE, -1
+            );
+        }
+
+        this._pipeline.set_state(Gst.State.PLAYING);
+    }
+
+    /** Update volume on a running pipeline */
+    setVolume(value: number): void {
+        if (this._volumeElement && !this._ended) {
+            this._volumeElement.set_property('volume', Math.max(0, Math.min(value, 10)));
+        }
+    }
+
+    /** Update loop flag */
+    setLoop(value: boolean): void {
+        this._loop = value;
+    }
+
+    /** Stop playback and clean up */
+    stop(): void {
+        if (this._ended) return;
+        this._fireEnded();
+    }
+
+    /** Whether playback has ended */
+    get ended(): boolean {
+        return this._ended;
+    }
+
+    private _restartPlayback(appsrc: any, pcmData: Uint8Array): void {
+        // For looping: seek pipeline to start
+        if (this._pipeline) {
+            this._pipeline.seek_simple(Gst.Format.TIME, Gst.SeekFlags.FLUSH, 0);
+        }
+    }
+
+    private _fireEnded(): void {
+        if (this._ended) return;
+        this._ended = true;
+        this._cleanup();
+        this._onEnded();
+    }
+
+    private _cleanup(): void {
+        if (this._pipeline) {
+            this._pipeline.set_state(Gst.State.NULL);
+            this._pipeline = null;
+        }
+        if (this._busWatchId !== null) {
+            // Bus watch is automatically removed when pipeline is disposed
+            this._busWatchId = null;
+        }
+        this._volumeElement = null;
+    }
+
+    /**
+     * Interleave AudioBuffer's per-channel Float32Arrays into a single Uint8Array.
+     * Applies offset (seconds) and optional duration (seconds).
+     */
+    private _interleave(buf: AudioBuffer, offsetSec: number, durationSec?: number): Uint8Array {
+        const ch = buf.numberOfChannels;
+        const startFrame = Math.min(Math.floor(offsetSec * buf.sampleRate), buf.length);
+        const maxFrames = buf.length - startFrame;
+        const frames = durationSec !== undefined
+            ? Math.min(Math.floor(durationSec * buf.sampleRate), maxFrames)
+            : maxFrames;
+
+        if (frames <= 0) return new Uint8Array(0);
+
+        const interleaved = new Float32Array(frames * ch);
+        for (let frame = 0; frame < frames; frame++) {
+            for (let c = 0; c < ch; c++) {
+                interleaved[frame * ch + c] = buf._channelData[c][startFrame + frame];
+            }
+        }
+
+        return new Uint8Array(interleaved.buffer);
+    }
+}

package/src/html-audio-element.ts

@@ -0,0 +1,76 @@
+// HTMLAudioElement — format detection + basic playback via GStreamer playbin.
+// Used by Excalibur.js for canPlayType() format sniffing.
+//
+// Reference: https://developer.mozilla.org/en-US/docs/Web/API/HTMLAudioElement
+
+import { ensureGstInit, Gst } from './gst-init.js';
+
+// GStreamer-supported MIME types (common on GNOME systems)
+const SUPPORTED_TYPES = new Set([
+    'audio/mpeg',
+    'audio/mp3',
+    'audio/wav',
+    'audio/x-wav',
+    'audio/ogg',
+    'audio/webm',
+    'audio/flac',
+    'audio/x-flac',
+    'audio/aac',
+    'audio/mp4',
+]);
+
+export class HTMLAudioElement {
+    src = '';
+    volume = 1;
+    loop = false;
+    paused = true;
+    currentTime = 0;
+    duration = 0;
+    readyState = 0;
+
+    private _pipeline: any = null;
+
+    canPlayType(type: string): CanPlayTypeResult {
+        // Strip codecs parameter: "audio/ogg; codecs=vorbis" → "audio/ogg"
+        const mime = type.split(';')[0].trim().toLowerCase();
+        return SUPPORTED_TYPES.has(mime) ? 'maybe' : '';
+    }
+
+    play(): Promise<void> {
+        if (!this.src) return Promise.resolve();
+
+        ensureGstInit();
+        this._cleanup();
+
+        this._pipeline = Gst.ElementFactory.make('playbin', 'player');
+        if (!this._pipeline) return Promise.resolve();
+
+        this._pipeline.set_property('uri', this.src);
+        this._pipeline.set_property('volume', this.volume);
+        this._pipeline.set_state(Gst.State.PLAYING);
+        this.paused = false;
+
+        return Promise.resolve();
+    }
+
+    pause(): void {
+        if (this._pipeline) {
+            this._pipeline.set_state(Gst.State.PAUSED);
+            this.paused = true;
+        }
+    }
+
+    load(): void {
+        this._cleanup();
+    }
+
+    addEventListener(_type: string, _listener: any): void {}
+    removeEventListener(_type: string, _listener: any): void {}
+
+    private _cleanup(): void {
+        if (this._pipeline) {
+            this._pipeline.set_state(Gst.State.NULL);
+            this._pipeline = null;
+        }
+    }
+}

package/src/index.ts

@@ -0,0 +1,14 @@
+// Web Audio API for GJS — backed by GStreamer 1.0.
+//
+// This module has no side effects. Importing @gjsify/webaudio gives
+// named access to Web Audio classes but does NOT register globals.
+// Use @gjsify/webaudio/register to set globalThis.AudioContext, etc.
+
+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/src/register.ts

@@ -0,0 +1,17 @@
+// Side-effect module: registers Web Audio API globals on GJS.
+// On Node.js the alias layer routes this to @gjsify/empty.
+
+import { AudioContext, HTMLAudioElement } from './index.js';
+
+if (typeof (globalThis as any).AudioContext === 'undefined') {
+    (globalThis as any).AudioContext = AudioContext;
+}
+if (typeof (globalThis as any).webkitAudioContext === 'undefined') {
+    (globalThis as any).webkitAudioContext = AudioContext;
+}
+if (typeof (globalThis as any).Audio === 'undefined') {
+    (globalThis as any).Audio = HTMLAudioElement;
+}
+if (typeof (globalThis as any).HTMLAudioElement === 'undefined') {
+    (globalThis as any).HTMLAudioElement = HTMLAudioElement;
+}

package/src/test.mts

@@ -0,0 +1,5 @@
+import webaudioSpec from './webaudio.spec.js';
+
+const results = {
+    webaudio: await webaudioSpec(),
+};