@gjsify/webrtc 0.1.15

package/src/media-devices.ts

@@ -0,0 +1,191 @@
+// W3C MediaDevices for GJS.
+//
+// Phase 3: getUserMedia via GStreamer sources.
+// Phase 4.3: enumerateDevices via GStreamer Device Monitor,
+//            getSupportedConstraints returns supported constraints.
+//
+// Reference: W3C Media Capture and Streams spec § 10.2
+// Reference: refs/webkit/Source/WebCore/platform/mediastream/gstreamer/GStreamerCaptureDeviceManager.cpp
+
+import '@gjsify/dom-events/register/event-target';
+
+import { ensureGstInit, Gst } from './gst-init.js';
+import { getUserMedia, type MediaStreamConstraints } from './get-user-media.js';
+import { MediaDeviceInfo, type MediaDeviceKind } from './media-device-info.js';
+import type { MediaStream } from './media-stream.js';
+
+/** Map GStreamer device class strings to W3C MediaDeviceKind. */
+const DEVICE_CLASS_MAP: Record<string, MediaDeviceKind> = {
+    'Audio/Source': 'audioinput',
+    'Video/Source': 'videoinput',
+    'Audio/Sink': 'audiooutput',
+};
+
+/** Whether getUserMedia has been successfully called (unlocks full device info). */
+let _permissionGranted = false;
+
+/**
+ * Check if GStreamer device monitoring is safe to use.
+ * On some GJS/GStreamer combinations (e.g. Fedora 44 / GJS 1.88 in Docker),
+ * DeviceMonitor and DeviceProviderFactory can SIGSEGV in native code — a crash
+ * that JS error handling cannot intercept. We skip device monitoring entirely
+ * when DISPLAY is absent (headless/CI) since there are typically no audio/video
+ * devices in containers anyway.
+ */
+function isDeviceMonitorSafe(): boolean {
+    try {
+        // Import GLib to check environment — avoid crashing GStreamer APIs
+        const GLib = imports.gi.GLib;
+        // Skip in CI environments or headless containers
+        if (GLib.getenv('CI')) return false;
+        // No display = likely a container without devices
+        if (!GLib.getenv('DISPLAY') && !GLib.getenv('WAYLAND_DISPLAY')) return false;
+        return true;
+    } catch {
+        return false;
+    }
+}
+
+export class MediaDevices extends EventTarget {
+    private _ondevicechange: ((ev: Event) => void) | null = null;
+
+    get ondevicechange(): ((ev: Event) => void) | null { return this._ondevicechange; }
+    set ondevicechange(v: ((ev: Event) => void) | null) { this._ondevicechange = v; }
+
+    async getUserMedia(constraints?: MediaStreamConstraints): Promise<MediaStream> {
+        if (!constraints) {
+            throw new TypeError(
+                "Failed to execute 'getUserMedia' on 'MediaDevices': At least one of audio or video must be requested",
+            );
+        }
+        const stream = await getUserMedia(constraints);
+        _permissionGranted = true;
+        return stream;
+    }
+
+    async enumerateDevices(): Promise<MediaDeviceInfo[]> {
+        ensureGstInit();
+
+        let monitor: InstanceType<typeof Gst.DeviceMonitor> | null = null;
+        const result: MediaDeviceInfo[] = [];
+
+        try {
+            // Guard: on CI containers without PipeWire/PulseAudio, DeviceMonitor
+            // can SIGSEGV in native GStreamer code. Check for device providers first.
+            if (!isDeviceMonitorSafe()) {
+                return result;
+            }
+
+            monitor = new Gst.DeviceMonitor();
+            monitor.set_show_all_devices(true);
+            const audioCaps = Gst.Caps.from_string('audio/x-raw');
+            const videoCaps = Gst.Caps.from_string('video/x-raw');
+            if (audioCaps) {
+                monitor.add_filter('Audio/Source', audioCaps);
+                monitor.add_filter('Audio/Sink', audioCaps);
+            }
+            if (videoCaps) {
+                monitor.add_filter('Video/Source', videoCaps);
+            }
+
+            if (!monitor.start()) {
+                // DeviceMonitor failed to start — return empty list gracefully
+                return result;
+            }
+
+            let gstDevices: any[];
+            try {
+                gstDevices = monitor.get_devices() ?? [];
+            } catch {
+                // get_devices() can crash on some GStreamer/GJS versions — return empty
+                return result;
+            }
+
+            for (const device of gstDevices) {
+                const deviceClass = device.get_device_class?.() ?? '';
+                const kind = DEVICE_CLASS_MAP[deviceClass];
+                if (!kind) continue;
+
+                const displayName = device.get_display_name?.() ?? '';
+                let deviceId = '';
+                let groupId = '';
+
+                // Extract persistent-id from device properties if available
+                try {
+                    const props = device.get_properties?.();
+                    if (props) {
+                        const n = props.n_fields();
+                        for (let i = 0; i < n; i++) {
+                            const name = props.nth_field_name(i);
+                            if (name === 'persistent-id' || name === 'node.name') {
+                                const val = props.get_value(name);
+                                if (val && !deviceId) deviceId = String(val);
+                            }
+                            if (name === 'group-id') {
+                                const val = props.get_value(name);
+                                if (val) groupId = String(val);
+                            }
+                        }
+                    }
+                } catch { /* properties may not be available */ }
+
+                // Fallback deviceId from display name hash
+                if (!deviceId) {
+                    deviceId = displayName || `${kind}-${result.length}`;
+                }
+
+                // Per W3C: before getUserMedia permission, expose only empty
+                // deviceId/label/groupId (one device per kind max).
+                if (_permissionGranted) {
+                    result.push(new MediaDeviceInfo({
+                        deviceId,
+                        kind,
+                        label: displayName,
+                        groupId,
+                    }));
+                } else {
+                    // Check if we already have a device of this kind
+                    if (!result.some(d => d.kind === kind)) {
+                        result.push(new MediaDeviceInfo({
+                            deviceId: '',
+                            kind,
+                            label: '',
+                            groupId: '',
+                        }));
+                    }
+                }
+            }
+        } catch {
+            // DeviceMonitor or device enumeration crashed — return whatever we have
+            return result;
+        } finally {
+            try { monitor?.stop(); } catch { /* ignore stop errors */ }
+        }
+
+        // W3C ordering: audioinput first, then videoinput, then audiooutput
+        const order: Record<string, number> = { audioinput: 0, videoinput: 1, audiooutput: 2 };
+        result.sort((a, b) => (order[a.kind] ?? 3) - (order[b.kind] ?? 3));
+
+        return result;
+    }
+
+    getSupportedConstraints(): Record<string, boolean> {
+        return {
+            deviceId: true,
+            width: true,
+            height: true,
+            frameRate: true,
+            sampleRate: true,
+            channelCount: true,
+            // Not yet supported — return false
+            aspectRatio: false,
+            facingMode: false,
+            resizeMode: false,
+            echoCancellation: false,
+            autoGainControl: false,
+            noiseSuppression: false,
+            latency: false,
+            groupId: false,
+        };
+    }
+}

package/src/media-stream-track.ts

@@ -0,0 +1,159 @@
+// W3C MediaStreamTrack for GJS.
+//
+// Phase 2: lightweight API surface with event dispatch.
+// Phase 3: optional GStreamer source integration — tracks created by
+// getUserMedia carry a GStreamer source element reference that the
+// RTCRtpSender wires into the webrtcbin pipeline.
+//
+// Reference: refs/node-gst-webrtc/src/media/MediaStreamTrack.ts (ISC)
+// Reference: W3C MediaStreamTrack spec
+
+import '@gjsify/dom-events/register/event-target';
+
+import GLib from 'gi://GLib?version=2.0';
+
+import { Gst } from './gst-init.js';
+
+/** @internal GStreamer backing for tracks created by getUserMedia */
+export interface MediaStreamTrackGstInit {
+    source: any;       // Gst.Element
+    pipeline: any;     // Gst.Pipeline
+}
+
+export interface MediaStreamTrackInit {
+    kind: 'audio' | 'video';
+    label?: string;
+    id?: string;
+    muted?: boolean;
+    /** @internal */
+    _gst?: MediaStreamTrackGstInit;
+}
+
+export class MediaStreamTrack extends EventTarget {
+    readonly id: string;
+    readonly kind: 'audio' | 'video';
+    readonly label: string;
+
+    private _enabled = true;
+    private _muted: boolean;
+    private _ended = false;
+    private _contentHint = '';
+
+    private _onended: ((ev: Event) => void) | null = null;
+    private _onmute: ((ev: Event) => void) | null = null;
+    private _onunmute: ((ev: Event) => void) | null = null;
+
+    /** @internal GStreamer source element (e.g. pulsesrc, audiotestsrc) */
+    _gstSource: any = null;
+    /** @internal Pipeline the source currently lives in (updated by VideoBridge) */
+    _gstPipeline: any = null;
+    /** @internal Tee element inserted by VideoBridge for preview fan-out */
+    _gstTee: any = null;
+    /** @internal TeeMultiplexer for multi-PC fan-out (created on second addTrack) */
+    _teeMultiplexer: any = null;
+    /** @internal Callback set by RTCRtpSender to control valve drop property */
+    private _enableCallback: ((enabled: boolean) => void) | null = null;
+
+    constructor(init: MediaStreamTrackInit) {
+        super();
+        this.id = init.id ?? GLib.uuid_string_random();
+        this.kind = init.kind;
+        this.label = init.label ?? '';
+        this._muted = init.muted ?? false;
+
+        if (init._gst) {
+            this._gstSource = init._gst.source;
+            this._gstPipeline = init._gst.pipeline;
+        }
+    }
+
+    get enabled(): boolean { return this._enabled; }
+    set enabled(v: boolean) {
+        const val = !!v;
+        if (this._enabled === val) return;
+        this._enabled = val;
+        this._enableCallback?.(val);
+    }
+
+    get muted(): boolean { return this._muted; }
+
+    get readyState(): 'live' | 'ended' { return this._ended ? 'ended' : 'live'; }
+
+    get contentHint(): string { return this._contentHint; }
+    set contentHint(v: string) {
+        if (this.kind === 'audio') {
+            if (v !== '' && v !== 'speech' && v !== 'speech-recognition' && v !== 'music') return;
+        } else {
+            if (v !== '' && v !== 'motion' && v !== 'detail' && v !== 'text') return;
+        }
+        this._contentHint = v;
+    }
+
+    get onended(): ((ev: Event) => void) | null { return this._onended; }
+    set onended(v: ((ev: Event) => void) | null) { this._onended = v; }
+    get onmute(): ((ev: Event) => void) | null { return this._onmute; }
+    set onmute(v: ((ev: Event) => void) | null) { this._onmute = v; }
+    get onunmute(): ((ev: Event) => void) | null { return this._onunmute; }
+    set onunmute(v: ((ev: Event) => void) | null) { this._onunmute = v; }
+
+    clone(): MediaStreamTrack {
+        const cloned = new MediaStreamTrack({
+            kind: this.kind,
+            label: this.label,
+            muted: this._muted,
+        });
+        cloned._enabled = this._enabled;
+        return cloned;
+    }
+
+    stop(): void {
+        if (this._ended) return;
+        this._ended = true;
+
+        // Clean up GStreamer source and pipeline if present
+        if (this._gstSource || this._gstPipeline) {
+            try {
+                // Set pipeline to NULL first (this stops all children)
+                this._gstPipeline?.set_state(Gst.State.NULL);
+            } catch { /* ignore */ }
+            try {
+                this._gstSource?.set_state(Gst.State.NULL);
+            } catch { /* ignore */ }
+            this._gstSource = null;
+            this._gstPipeline = null;
+        }
+
+        const ev = new Event('ended');
+        this._onended?.call(this, ev);
+        this.dispatchEvent(ev);
+    }
+
+    getCapabilities(): Record<string, unknown> { return {}; }
+    getConstraints(): Record<string, unknown> { return {}; }
+    getSettings(): Record<string, unknown> { return {}; }
+
+    applyConstraints(_constraints?: unknown): Promise<void> {
+        return Promise.reject(new DOMException(
+            'applyConstraints is not supported',
+            'NotSupportedError',
+        ));
+    }
+
+    /** @internal — used by RTCRtpReceiver to toggle mute state */
+    _setMuted(muted: boolean): void {
+        if (this._muted === muted) return;
+        this._muted = muted;
+        const ev = new Event(muted ? 'mute' : 'unmute');
+        if (muted) {
+            this._onmute?.call(this, ev);
+        } else {
+            this._onunmute?.call(this, ev);
+        }
+        this.dispatchEvent(ev);
+    }
+
+    /** @internal — called by RTCRtpSender to wire valve control */
+    _setEnableCallback(cb: ((enabled: boolean) => void) | null): void {
+        this._enableCallback = cb;
+    }
+}

package/src/media-stream.ts

@@ -0,0 +1,96 @@
+// W3C MediaStream for GJS.
+//
+// Pure-JS collection container for MediaStreamTrack instances.
+// No GStreamer pipeline integration — that is Phase 2.5.
+//
+// Reference: refs/node-gst-webrtc/src/media/MediaStream.ts (ISC)
+// Reference: W3C MediaStream spec
+
+import '@gjsify/dom-events/register/event-target';
+
+import GLib from 'gi://GLib?version=2.0';
+
+import { MediaStreamTrack } from './media-stream-track.js';
+
+export class MediaStream extends EventTarget {
+    readonly id: string;
+    private _tracks = new Map<string, MediaStreamTrack>();
+
+    private _onaddtrack: ((ev: Event) => void) | null = null;
+    private _onremovetrack: ((ev: Event) => void) | null = null;
+
+    constructor(streamOrTracks?: MediaStream | MediaStreamTrack[]) {
+        super();
+        this.id = GLib.uuid_string_random();
+
+        if (streamOrTracks instanceof MediaStream) {
+            for (const track of streamOrTracks.getTracks()) {
+                this._tracks.set(track.id, track.clone());
+            }
+        } else if (Array.isArray(streamOrTracks)) {
+            for (const track of streamOrTracks) {
+                this._tracks.set(track.id, track);
+            }
+        }
+    }
+
+    get active(): boolean {
+        for (const track of this._tracks.values()) {
+            if (track.readyState === 'live') return true;
+        }
+        return false;
+    }
+
+    get onaddtrack(): ((ev: Event) => void) | null { return this._onaddtrack; }
+    set onaddtrack(v: ((ev: Event) => void) | null) { this._onaddtrack = v; }
+    get onremovetrack(): ((ev: Event) => void) | null { return this._onremovetrack; }
+    set onremovetrack(v: ((ev: Event) => void) | null) { this._onremovetrack = v; }
+
+    getTracks(): MediaStreamTrack[] {
+        return [...this._tracks.values()];
+    }
+
+    getAudioTracks(): MediaStreamTrack[] {
+        return this.getTracks().filter((t) => t.kind === 'audio');
+    }
+
+    getVideoTracks(): MediaStreamTrack[] {
+        return this.getTracks().filter((t) => t.kind === 'video');
+    }
+
+    getTrackById(id: string): MediaStreamTrack | null {
+        return this._tracks.get(id) ?? null;
+    }
+
+    addTrack(track: MediaStreamTrack): void {
+        if (this._tracks.has(track.id)) return;
+        this._tracks.set(track.id, track);
+        const ev = new MediaStreamTrackEvent('addtrack', { track });
+        this._onaddtrack?.call(this, ev);
+        this.dispatchEvent(ev);
+    }
+
+    removeTrack(track: MediaStreamTrack): void {
+        if (!this._tracks.delete(track.id)) return;
+        const ev = new MediaStreamTrackEvent('removetrack', { track });
+        this._onremovetrack?.call(this, ev);
+        this.dispatchEvent(ev);
+    }
+
+    clone(): MediaStream {
+        return new MediaStream(this);
+    }
+}
+
+export interface MediaStreamTrackEventInit extends EventInit {
+    track: MediaStreamTrack;
+}
+
+export class MediaStreamTrackEvent extends Event {
+    readonly track: MediaStreamTrack;
+
+    constructor(type: string, init: MediaStreamTrackEventInit) {
+        super(type, init);
+        this.track = init.track;
+    }
+}

package/src/register/data-channel.ts

@@ -0,0 +1,11 @@
+// Registers: RTCDataChannel, RTCDataChannelEvent.
+
+import { RTCDataChannel } from '../rtc-data-channel.js';
+import { RTCDataChannelEvent } from '../rtc-events.js';
+
+if (typeof (globalThis as any).RTCDataChannel === 'undefined') {
+    (globalThis as any).RTCDataChannel = RTCDataChannel;
+}
+if (typeof (globalThis as any).RTCDataChannelEvent === 'undefined') {
+    (globalThis as any).RTCDataChannelEvent = RTCDataChannelEvent;
+}

package/src/register/error.ts

@@ -0,0 +1,11 @@
+// Registers: RTCError, RTCErrorEvent.
+
+import { RTCError } from '../rtc-error.js';
+import { RTCErrorEvent } from '../rtc-events.js';
+
+if (typeof (globalThis as any).RTCError === 'undefined') {
+    (globalThis as any).RTCError = RTCError;
+}
+if (typeof (globalThis as any).RTCErrorEvent === 'undefined') {
+    (globalThis as any).RTCErrorEvent = RTCErrorEvent;
+}

package/src/register/media-devices.ts

@@ -0,0 +1,10 @@
+// Register navigator.mediaDevices on globalThis for GJS.
+
+import { MediaDevices } from '../media-devices.js';
+
+if (typeof (globalThis as any).navigator === 'undefined') {
+    (globalThis as any).navigator = {} as any;
+}
+if (typeof (globalThis as any).navigator.mediaDevices === 'undefined') {
+    (globalThis as any).navigator.mediaDevices = new MediaDevices();
+}

package/src/register/media.ts

@@ -0,0 +1,15 @@
+// Registers: MediaStream, MediaStreamTrack, RTCTrackEvent.
+
+import { MediaStream } from '../media-stream.js';
+import { MediaStreamTrack } from '../media-stream-track.js';
+import { RTCTrackEvent } from '../rtc-track-event.js';
+
+if (typeof (globalThis as any).MediaStream === 'undefined') {
+    (globalThis as any).MediaStream = MediaStream;
+}
+if (typeof (globalThis as any).MediaStreamTrack === 'undefined') {
+    (globalThis as any).MediaStreamTrack = MediaStreamTrack;
+}
+if (typeof (globalThis as any).RTCTrackEvent === 'undefined') {
+    (globalThis as any).RTCTrackEvent = RTCTrackEvent;
+}

package/src/register/peer-connection.ts

@@ -0,0 +1,20 @@
+// Registers: RTCPeerConnection, RTCSessionDescription, RTCIceCandidate,
+// RTCPeerConnectionIceEvent.
+
+import { RTCPeerConnection } from '../rtc-peer-connection.js';
+import { RTCSessionDescription } from '../rtc-session-description.js';
+import { RTCIceCandidate } from '../rtc-ice-candidate.js';
+import { RTCPeerConnectionIceEvent } from '../rtc-events.js';
+
+if (typeof (globalThis as any).RTCPeerConnection === 'undefined') {
+    (globalThis as any).RTCPeerConnection = RTCPeerConnection;
+}
+if (typeof (globalThis as any).RTCSessionDescription === 'undefined') {
+    (globalThis as any).RTCSessionDescription = RTCSessionDescription;
+}
+if (typeof (globalThis as any).RTCIceCandidate === 'undefined') {
+    (globalThis as any).RTCIceCandidate = RTCIceCandidate;
+}
+if (typeof (globalThis as any).RTCPeerConnectionIceEvent === 'undefined') {
+    (globalThis as any).RTCPeerConnectionIceEvent = RTCPeerConnectionIceEvent;
+}

package/src/register.spec.ts

@@ -0,0 +1,55 @@
+// WebRTC globals registration tests — verifies the granular /register
+// subpaths wire each identifier onto globalThis.
+//
+// These tests must run AFTER importing the register subpaths — in `test.mts`
+// the register module is imported alongside the spec, so the assertions below
+// run post-registration.
+
+import { describe, it, expect } from '@gjsify/unit';
+
+import '@gjsify/webrtc/register';
+
+export default async () => {
+    await describe('@gjsify/webrtc/register', async () => {
+        await it('registers RTCPeerConnection', async () => {
+            expect(typeof (globalThis as any).RTCPeerConnection).toBe('function');
+        });
+        await it('registers RTCSessionDescription', async () => {
+            expect(typeof (globalThis as any).RTCSessionDescription).toBe('function');
+        });
+        await it('registers RTCIceCandidate', async () => {
+            expect(typeof (globalThis as any).RTCIceCandidate).toBe('function');
+        });
+        await it('registers RTCPeerConnectionIceEvent', async () => {
+            expect(typeof (globalThis as any).RTCPeerConnectionIceEvent).toBe('function');
+        });
+        await it('registers RTCDataChannel', async () => {
+            expect(typeof (globalThis as any).RTCDataChannel).toBe('function');
+        });
+        await it('registers RTCDataChannelEvent', async () => {
+            expect(typeof (globalThis as any).RTCDataChannelEvent).toBe('function');
+        });
+        await it('registers RTCError', async () => {
+            expect(typeof (globalThis as any).RTCError).toBe('function');
+        });
+        await it('registers RTCErrorEvent', async () => {
+            expect(typeof (globalThis as any).RTCErrorEvent).toBe('function');
+        });
+
+        await it('RTCError extends DOMException', async () => {
+            const err = new (globalThis as any).RTCError({ errorDetail: 'data-channel-failure' }, 'test');
+            const DOMExceptionCtor = (globalThis as any).DOMException;
+            if (DOMExceptionCtor) {
+                expect(err instanceof DOMExceptionCtor).toBeTruthy();
+            }
+            expect(err.errorDetail).toBe('data-channel-failure');
+        });
+
+        await it('RTCPeerConnectionIceEvent is a subclass of Event', async () => {
+            const RTCPeerConnectionIceEventCtor = (globalThis as any).RTCPeerConnectionIceEvent;
+            const ev = new RTCPeerConnectionIceEventCtor('icecandidate', { candidate: null });
+            expect(ev instanceof Event).toBeTruthy();
+            expect(ev.candidate).toBeNull();
+        });
+    });
+};

package/src/register.ts

@@ -0,0 +1,10 @@
+// Catch-all side-effect module: registers all WebRTC globals on GJS.
+// Prefer granular imports (e.g. '@gjsify/webrtc/register/data-channel')
+// when only specific globals are needed — the --globals auto mode does this
+// automatically.
+
+import './register/peer-connection.js';
+import './register/data-channel.js';
+import './register/error.js';
+import './register/media.js';
+import './register/media-devices.js';