@gjsify/webaudio 0.32.0 → 0.34.0

package/lib/esm/audio-context.js

@@ -1 +1 @@
-import"./_virtual/_rolldown/runtime.js";import{AudioNode as e}from"./audio-node.js";import{ensureGstInit as t}from"./gst-init.js";import{stopAllPipelines as n}from"./gst-teardown.js";import{GainNode as r}from"./gain-node.js";import{AudioBufferSourceNode as i}from"./audio-buffer-source-node.js";import{AudioBuffer as a}from"./audio-buffer.js";import{AudioDestinationNode as o}from"./audio-destination-node.js";import{decodeAudioDataSync as s}from"./gst-decoder.js";import c from"gi://GLib?version=2.0";var AudioContext=class{state=`suspended`;sampleRate=44100;destination;listener={};_startTime;constructor(){t(),this._startTime=c.get_monotonic_time(),this.destination=new o}get currentTime(){return(c.get_monotonic_time()-this._startTime)/1e6}createGain(){return new r}createBufferSource(){return new i}createBuffer(e,t,n){return new a({numberOfChannels:e,length:t,sampleRate:n})}decodeAudioData(e,t,n){try{let n=s(e);return t?.(n),Promise.resolve(n)}catch(e){let t=e instanceof DOMException?e:new DOMException(`Unable to decode audio data`,`EncodingError`);return n?.(t),Promise.reject(t)}}async resume(){this.state=`running`}async suspend(){this.state=`suspended`}async close(){this.state=`closed`,n()}createAnalyser(){return{connect:()=>{},disconnect:()=>{},fftSize:2048,frequencyBinCount:1024,getByteFrequencyData:()=>{},getFloatFrequencyData:()=>{}}}createDynamicsCompressor(){return new e}createBiquadFilter(){return new e}createConvolver(){return new e}createPanner(){return new e}createStereoPanner(){return new e}addEventListener(e,t){}removeEventListener(e,t){}};export{AudioContext};
+import"./_virtual/_rolldown/runtime.js";import{AudioNode as e}from"./audio-node.js";import{tryEnsureGstInit as t}from"./gst-init.js";import{stopAllPipelines as n}from"./gst-teardown.js";import{GainNode as r}from"./gain-node.js";import{AudioBufferSourceNode as i}from"./audio-buffer-source-node.js";import{AudioBuffer as a}from"./audio-buffer.js";import{AudioDestinationNode as o}from"./audio-destination-node.js";import{decodeAudioDataSync as s}from"./gst-decoder.js";import c from"gi://GLib?version=2.0";var AudioContext=class{state=`suspended`;sampleRate=44100;destination;listener={};_startTime;constructor(){let e=t();e!==null&&console.warn(`[webaudio] AudioContext: GStreamer is unavailable, continuing SILENT — ${e}\n  Audio needs GStreamer 1.0 with gst-plugins-base. The @gjsify/gtk-runtime-* bundles do not ship it, so install it system-wide (Fedora: gstreamer1 gstreamer1-plugins-base; Windows: an MSYS2/gvsbuild GStreamer on PATH).`),this._startTime=c.get_monotonic_time(),this.destination=new o}get currentTime(){return(c.get_monotonic_time()-this._startTime)/1e6}createGain(){return new r}createBufferSource(){return new i}createBuffer(e,t,n){return new a({numberOfChannels:e,length:t,sampleRate:n})}decodeAudioData(e,t,n){try{let n=s(e);return t?.(n),Promise.resolve(n)}catch(e){let t=e instanceof DOMException?e:new DOMException(`Unable to decode audio data`,`EncodingError`);return n?.(t),Promise.reject(t)}}async resume(){this.state=`running`}async suspend(){this.state=`suspended`}async close(){this.state=`closed`,n()}createAnalyser(){return{connect:()=>{},disconnect:()=>{},fftSize:2048,frequencyBinCount:1024,getByteFrequencyData:()=>{},getFloatFrequencyData:()=>{}}}createDynamicsCompressor(){return new e}createBiquadFilter(){return new e}createConvolver(){return new e}createPanner(){return new e}createStereoPanner(){return new e}addEventListener(e,t){}removeEventListener(e,t){}};export{AudioContext};

package/lib/esm/gst-init.js

@@ -1 +1 @@
-import"./_virtual/_rolldown/runtime.js";import e from"gi://Gst?version=1.0";import t from"gi://GstApp?version=1.0";let n=!1;function ensureGstAppLoaded(){if(t.AppSrc===void 0)throw Error(`GstApp typelib is unavailable — install gstreamer1-plugins-base (gst-plugins-base)`)}function ensureGstInit(){n||=(e.init(null),ensureGstAppLoaded(),!0)}export{e as Gst,ensureGstInit};
+import"./_virtual/_rolldown/runtime.js";import e from"gi://Gst?version=1.0";import t from"gi://GstApp?version=1.0";let n=!1;function ensureGstAppLoaded(){if(t.AppSrc===void 0)throw Error(`GstApp typelib is unavailable — install gstreamer1-plugins-base (gst-plugins-base)`)}const defaultInitializer=()=>{e.init(null),ensureGstAppLoaded()};let r=`pending`;function tryEnsureGstInit(e=defaultInitializer){let t=e===defaultInitializer;if(t&&r!==`pending`)return r===`ready`?null:r.failed;try{return e(),t&&(r=`ready`,n=!0),null}catch(e){let n=e instanceof Error?e.message:String(e);return t&&(r={failed:n}),n}}function primeGstOutcomeForTests(e){if(e===void 0){r=`pending`,n=!1;return}r=e===null?`ready`:{failed:e},n=e===null}function ensureGstInit(){if(n)return;let e=tryEnsureGstInit();if(e!==null)throw Error(e)}export{e as Gst,ensureGstInit,primeGstOutcomeForTests,tryEnsureGstInit};

package/lib/esm/html-audio-element.js

@@ -1 +1 @@
-import"./_virtual/_rolldown/runtime.js";import{Gst as e,ensureGstInit as t}from"./gst-init.js";import{stopPipeline as n,trackPipeline as r}from"./gst-teardown.js";const i=new Set([`audio/mpeg`,`audio/mp3`,`audio/wav`,`audio/x-wav`,`audio/ogg`,`audio/webm`,`audio/flac`,`audio/x-flac`,`audio/aac`,`audio/mp4`]);var HTMLAudioElement=class{src=``;volume=1;loop=!1;paused=!0;currentTime=0;duration=0;readyState=0;_pipeline=null;canPlayType(e){let t=e.split(`;`)[0].trim().toLowerCase();return i.has(t)?`maybe`:``}play(){return!this.src||(t(),this._cleanup(),this._pipeline=e.ElementFactory.make(`playbin`,`player`),!this._pipeline)?Promise.resolve():(r(this._pipeline),this._pipeline.set_property(`uri`,this.src),this._pipeline.set_property(`volume`,this.volume),this._pipeline.set_state(e.State.PLAYING),this.paused=!1,Promise.resolve())}pause(){this._pipeline&&(this._pipeline.set_state(e.State.PAUSED),this.paused=!0)}load(){this._cleanup()}addEventListener(e,t){}removeEventListener(e,t){}_cleanup(){this._pipeline&&=(n(this._pipeline),null)}};export{HTMLAudioElement};
+import"./_virtual/_rolldown/runtime.js";import{Gst as e,tryEnsureGstInit as t}from"./gst-init.js";import{stopPipeline as n,trackPipeline as r}from"./gst-teardown.js";const i=new Set([`audio/mpeg`,`audio/mp3`,`audio/wav`,`audio/x-wav`,`audio/ogg`,`audio/webm`,`audio/flac`,`audio/x-flac`,`audio/aac`,`audio/mp4`]);var HTMLAudioElement=class{src=``;volume=1;loop=!1;paused=!0;currentTime=0;duration=0;readyState=0;_pipeline=null;canPlayType(e){let t=e.split(`;`)[0].trim().toLowerCase();return i.has(t)?`maybe`:``}play(){if(!this.src)return Promise.resolve();let n=t();return n===null?(this._cleanup(),this._pipeline=e.ElementFactory.make(`playbin`,`player`),this._pipeline?(r(this._pipeline),this._pipeline.set_property(`uri`,this.src),this._pipeline.set_property(`volume`,this.volume),this._pipeline.set_state(e.State.PLAYING),this.paused=!1,Promise.resolve()):Promise.resolve()):(console.warn(`[webaudio] Audio.play: GStreamer is unavailable, staying silent — ${n}`),Promise.resolve())}pause(){this._pipeline&&(this._pipeline.set_state(e.State.PAUSED),this.paused=!0)}load(){this._cleanup()}addEventListener(e,t){}removeEventListener(e,t){}_cleanup(){this._pipeline&&=(n(this._pipeline),null)}};export{HTMLAudioElement};

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

@@ -9,6 +9,27 @@ export declare class AudioContext {
     readonly destination: AudioDestinationNode;
     readonly listener: {};
     private _startTime;
+    /**
+     * CONSTRUCTING A CONTEXT IS NOT PLAYING AUDIO, so a missing audio backend
+     * may not be fatal here. `ensureGstInit()` threw, and it killed whole
+     * applications: on the batteries-included GTK runtime bundles (win32-x64,
+     * darwin) GStreamer is not shipped, and Excalibur's boot-time audio unlock
+     * constructs a context before the first frame — so `gjsify showcase
+     * excalibur-jelly-jumper --runtime node` on Windows died with "Failed to
+     * require Gst 1.0: Typelib file for namespace 'Gst' not found" and the game
+     * never rendered.
+     *
+     * In a browser `new AudioContext()` always succeeds; a page that cannot play
+     * sound still runs. This matches that. The rule was already written down one
+     * level below — `AudioBufferSourceNode.start()` degrades to silent rather
+     * than throw, "a single failed audio node must NEVER crash the whole app" —
+     * it just had not been applied to the constructor.
+     *
+     * Warned ONCE per context and not per sound: a game loading forty samples
+     * would otherwise bury its own output. Everything downstream already copes —
+     * `start()` degrades to silent and `decodeAudioData` rejects with an
+     * `EncodingError`, which is what the spec says a failed decode does.
+     */
     constructor();
     /** Monotonically increasing time in seconds since context creation. */
     get currentTime(): number;

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

@@ -1,3 +1,42 @@
 import Gst from 'gi://Gst?version=1.0';
+/** The GStreamer bring-up. A parameter so its FAILURE branch is executable. */
+export type GstInitializer = () => void;
+/**
+ * Bring GStreamer up and REPORT the outcome instead of throwing.
+ *
+ * Returns `null` on success, or a human-readable reason. Every caller that can
+ * carry on without audio should use this one — see `AudioContext`.
+ *
+ * `initializer` is injectable for the same reason `dirLinkTarget` takes its link
+ * kind: the interesting branch here is the one where GStreamer is ABSENT, and on
+ * a developer's Linux box it never is. A branch nobody can execute is how the
+ * throwing version below shipped as the only entry point.
+ *
+ * The memo applies to the DEFAULT initializer only. A test passing its own is
+ * asking to exercise one specific outcome, and must neither be answered from the
+ * process-wide memo nor poison it.
+ */
+export declare function tryEnsureGstInit(initializer?: GstInitializer): string | null;
+/**
+ * TEST SEAM — answer the next bring-up with `reason` (or `null` for success)
+ * without touching the real GStreamer, and `undefined` to forget again.
+ *
+ * The injectable initializer above covers `tryEnsureGstInit` itself, but not its
+ * CALLERS: `new AudioContext()` has no initializer to hand it, and "constructing
+ * a context on a host with no GStreamer does not throw" is the exact property
+ * whose absence killed the game. Priming the memo is what lets that be asserted
+ * on a developer machine, where GStreamer is always installed.
+ */
+export declare function primeGstOutcomeForTests(reason: string | null | undefined): void;
+/**
+ * Bring GStreamer up, or throw.
+ *
+ * For the callers that genuinely cannot proceed without it — decoding bytes,
+ * building a playback pipeline. Constructing an `AudioContext` is NOT one of
+ * them, and treating it as one is what killed whole applications: on the
+ * batteries-included GTK runtime bundles (win32-x64, darwin) GStreamer is not
+ * shipped at all, so `new AudioContext()` threw "Failed to require Gst 1.0"
+ * during Excalibur's boot-time audio unlock and the game never rendered a frame.
+ */
 export declare function ensureGstInit(): void;
 export { Gst };

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gjsify/webaudio",
-    "version": "0.32.0",
+    "version": "0.34.0",
     "description": "Web Audio API for GJS using GStreamer as audio backend",
     "type": "module",
     "module": "lib/esm/index.js",
@@ -42,7 +42,7 @@
         "audio-api"
     ],
     "dependencies": {
-        "@gjsify/dom-events": "^0.32.0"
+        "@gjsify/dom-events": "^0.34.0"
     },
     "devDependencies": {
         "@girs/gio-2.0": "^4.1.0",
@@ -52,8 +52,8 @@
         "@girs/gstapp-1.0": "^4.1.0",
         "@girs/gstaudio-1.0": "^4.1.0",
         "@girs/gstbase-1.0": "^4.1.0",
-        "@gjsify/cli": "^0.32.0",
-        "@gjsify/unit": "^0.32.0",
+        "@gjsify/cli": "^0.34.0",
+        "@gjsify/unit": "^0.34.0",
         "@types/node": "^25.9.2",
         "typescript": "^6.0.3"
     },