@gjsify/webrtc 0.4.0 → 0.4.3

package/src/index.ts

@@ -1,104 +0,0 @@
-// W3C WebRTC API for GJS — backed by GStreamer webrtcbin.
-//
-// This module has no side effects. Importing @gjsify/webrtc gives named
-// access to the classes but does NOT register globals. Use
-// @gjsify/webrtc/register (or a granular subpath) to set globalThis.RTCPeerConnection etc.
-
-export { RTCPeerConnection } from './rtc-peer-connection.js';
-export type {
-    RTCConfiguration,
-    RTCIceServer,
-    RTCOfferOptions,
-    RTCAnswerOptions,
-    RTCDataChannelInit,
-    RTCSignalingState,
-    RTCPeerConnectionState,
-    RTCIceConnectionState,
-    RTCIceGatheringState,
-    RTCIceTransportPolicy,
-    RTCBundlePolicy,
-    RTCRtcpMuxPolicy,
-} from './rtc-peer-connection.js';
-
-export { RTCDataChannel } from './rtc-data-channel.js';
-export type { RTCDataChannelState, BinaryType } from './rtc-data-channel.js';
-
-export { RTCSessionDescription } from './rtc-session-description.js';
-export type { RTCSessionDescriptionInit, RTCSdpType } from './rtc-session-description.js';
-
-export { RTCIceCandidate } from './rtc-ice-candidate.js';
-export type {
-    RTCIceCandidateInit,
-    RTCIceComponent,
-    RTCIceProtocol,
-    RTCIceCandidateType,
-    RTCIceTcpCandidateType,
-} from './rtc-ice-candidate.js';
-
-export { RTCError } from './rtc-error.js';
-export type { RTCErrorInit, RTCErrorDetailType } from './rtc-error.js';
-
-export {
-    RTCPeerConnectionIceEvent,
-    RTCDataChannelEvent,
-    RTCErrorEvent,
-} from './rtc-events.js';
-export type {
-    RTCPeerConnectionIceEventInit,
-    RTCDataChannelEventInit,
-    RTCErrorEventInit,
-} from './rtc-events.js';
-
-export { RTCRtpSender } from './rtc-rtp-sender.js';
-export type {
-    RTCRtpTransceiverDirection,
-    RTCRtpCapabilities,
-    RTCRtpCodecCapability,
-    RTCRtpHeaderExtensionCapability,
-    RTCRtpSendParameters,
-    RTCRtpEncodingParameters,
-    RTCRtpCodecParameters,
-    RTCRtpHeaderExtensionParameters,
-    RTCRtcpParameters,
-} from './rtc-rtp-sender.js';
-
-export { RTCRtpReceiver } from './rtc-rtp-receiver.js';
-export type { RTCRtpReceiveParameters } from './rtc-rtp-receiver.js';
-
-export { RTCRtpTransceiver } from './rtc-rtp-transceiver.js';
-
-export { MediaStream } from './media-stream.js';
-export { MediaStreamTrackEvent } from './media-stream.js';
-
-export { MediaStreamTrack } from './media-stream-track.js';
-export type { MediaStreamTrackInit } from './media-stream-track.js';
-
-export { RTCTrackEvent } from './rtc-track-event.js';
-export type { RTCTrackEventInit } from './rtc-track-event.js';
-
-export type { RTCRtpTransceiverInit } from './rtc-peer-connection.js';
-
-export { getUserMedia } from './get-user-media.js';
-export type { MediaStreamConstraints, MediaTrackConstraints } from './get-user-media.js';
-
-export { MediaDevices } from './media-devices.js';
-export { MediaDeviceInfo } from './media-device-info.js';
-export type { MediaDeviceKind } from './media-device-info.js';
-
-export { RTCStatsReport } from './rtc-stats-report.js';
-export type { RTCStats } from './rtc-stats-report.js';
-
-export { RTCDtlsTransport } from './rtc-dtls-transport.js';
-export type { RTCDtlsTransportState } from './rtc-dtls-transport.js';
-
-export { RTCIceTransport } from './rtc-ice-transport.js';
-export type { RTCIceTransportState, RTCIceRole, RTCIceParameters, RTCIceCandidatePair } from './rtc-ice-transport.js';
-
-export { RTCSctpTransport } from './rtc-sctp-transport.js';
-export type { RTCSctpTransportState } from './rtc-sctp-transport.js';
-
-export { RTCDTMFSender, RTCDTMFToneChangeEvent } from './rtc-dtmf-sender.js';
-export type { RTCDTMFToneChangeEventInit } from './rtc-dtmf-sender.js';
-
-export { RTCCertificate } from './rtc-certificate.js';
-export type { RTCDtlsFingerprint, AlgorithmIdentifier } from './rtc-certificate.js';

package/src/internal/gst-types.ts

@@ -1,122 +0,0 @@
-// SPDX-License-Identifier: MIT
-// Internal type helpers for @gjsify/webrtc — narrowing the broad
-// Gst.Element / Gst.Pad surface to the concrete element shapes our
-// implementation reads and writes at runtime.
-//
-// Background: `@girs/gst-1.0` declares every GStreamer element as the
-// base `Gst.Element` class — element-specific GObject properties (e.g.
-// `webrtcbin`'s `stun_server`, `signaling_state`, or `vp8enc`'s
-// `keyframe_max_dist`) are not exposed in the GIR-generated typings
-// because they are registered at element-class init time, not on the
-// base class. Rather than reach for `(el as any).foo` at every call
-// site, we declare thin interfaces here and narrow once through helper
-// casts.
-//
-// These types are PURE compile-time constructs — no runtime behavior is
-// added. Following AGENTS.md Rule 2c, this module lives under
-// `src/internal/` and is NOT in `package.json#exports`; it is a private
-// implementation helper, not part of the public API surface.
-//
-// References:
-//  - GStreamer webrtcbin element properties:
-//      https://gstreamer.freedesktop.org/documentation/webrtc/index.html
-//  - vp8enc / opusenc / capsfilter / valve / payloader properties:
-//      https://gstreamer.freedesktop.org/documentation/
-
-import type Gst from 'gi://Gst?version=1.0';
-import type GstWebRTC from 'gi://GstWebRTC?version=1.0';
-
-/**
- * The `webrtcbin` GStreamer element — declares every GObject property
- * our implementation accesses. The base `Gst.Element` class is preserved
- * so all the inherited methods (`emit`, `get_parent`, `set_state`,
- * `request_pad_simple`, `sync_state_with_parent`, …) keep their proper
- * typings.
- *
- * All properties below correspond to runtime GObject properties on
- * `webrtcbin` (verify with `gst-inspect-1.0 webrtcbin`).
- */
-export interface WebRtcBin extends Gst.Element {
-    stun_server: string | null;
-    turn_server: string | null;
-    ice_transport_policy: GstWebRTC.WebRTCICETransportPolicy;
-    bundle_policy: GstWebRTC.WebRTCBundlePolicy;
-    signaling_state: GstWebRTC.WebRTCSignalingState;
-    connection_state: GstWebRTC.WebRTCPeerConnectionState;
-    ice_connection_state: GstWebRTC.WebRTCICEConnectionState;
-    ice_gathering_state: GstWebRTC.WebRTCICEGatheringState;
-    local_description: GstWebRTC.WebRTCSessionDescription | null;
-    remote_description: GstWebRTC.WebRTCSessionDescription | null;
-    current_local_description: GstWebRTC.WebRTCSessionDescription | null;
-    current_remote_description: GstWebRTC.WebRTCSessionDescription | null;
-    pending_local_description: GstWebRTC.WebRTCSessionDescription | null;
-    pending_remote_description: GstWebRTC.WebRTCSessionDescription | null;
-}
-
-/**
- * Narrow a `Gst.Element` returned by `Gst.ElementFactory.make('webrtcbin', …)`
- * to the augmented `WebRtcBin` shape. Pure type-level cast — no runtime
- * validation is performed because every webrtcbin instance has these
- * properties (they are class-installed by GstWebRTCBin).
- */
-export const asWebRtcBin = (el: Gst.Element): WebRtcBin => el as WebRtcBin;
-
-/**
- * GStreamer pad augmented with the `transceiver` field that webrtcbin's
- * SRC pads carry. The base `Gst.Pad` typing has no concept of this — it
- * is set at pad-creation time inside webrtcbin and points back to the
- * `GstWebRTCRTPTransceiver` the pad serves.
- */
-export interface WebRtcSrcPad extends Gst.Pad {
-    transceiver: GstWebRTC.WebRTCRTPTransceiver | null;
-}
-
-/** Narrow a webrtcbin SRC `Gst.Pad` to the augmented shape. */
-export const asWebRtcSrcPad = (pad: Gst.Pad): WebRtcSrcPad => pad as WebRtcSrcPad;
-
-/**
- * GStreamer element with a settable `drop` GObject property — the
- * `valve` element used to gate media flow when a track is disabled.
- */
-export interface ValveElement extends Gst.Element {
-    drop: boolean;
-}
-
-/** Narrow a `valve` element to the augmented shape. */
-export const asValveElement = (el: Gst.Element): ValveElement => el as ValveElement;
-
-/**
- * GStreamer element with a settable `pt` GObject property — RTP payloader
- * elements (`rtpopuspay`, `rtpvp8pay`, …) accept the payload type.
- */
-export interface RtpPayloaderElement extends Gst.Element {
-    pt: number;
-}
-
-/** Narrow an RTP payloader element to the augmented shape. */
-export const asRtpPayloaderElement = (el: Gst.Element): RtpPayloaderElement =>
-    el as RtpPayloaderElement;
-
-/**
- * GStreamer `capsfilter` element — exposes a settable `caps` property
- * that pins the negotiated caps of a pipeline branch.
- */
-export interface CapsFilterElement extends Gst.Element {
-    caps: Gst.Caps;
-}
-
-/** Narrow a `capsfilter` element to the augmented shape. */
-export const asCapsFilterElement = (el: Gst.Element): CapsFilterElement =>
-    el as CapsFilterElement;
-
-/**
- * GStreamer `vp8enc` encoder — the small set of properties we tune for
- * realtime WebRTC video encoding.
- */
-export interface Vp8EncElement extends Gst.Element {
-    deadline: number;
-    keyframe_max_dist: number;
-}
-
-/** Narrow a `vp8enc` element to the augmented shape. */
-export const asVp8EncElement = (el: Gst.Element): Vp8EncElement => el as Vp8EncElement;

package/src/media-device-info.ts

@@ -1,33 +0,0 @@
-// W3C MediaDeviceInfo for GJS — backed by GStreamer Device Monitor.
-//
-// Reference: W3C Media Capture and Streams spec § 10.2.1
-
-export type MediaDeviceKind = 'audioinput' | 'audiooutput' | 'videoinput';
-
-export class MediaDeviceInfo {
-    readonly deviceId: string;
-    readonly kind: MediaDeviceKind;
-    readonly label: string;
-    readonly groupId: string;
-
-    constructor(init: {
-        deviceId: string;
-        kind: MediaDeviceKind;
-        label: string;
-        groupId?: string;
-    }) {
-        this.deviceId = init.deviceId;
-        this.kind = init.kind;
-        this.label = init.label;
-        this.groupId = init.groupId ?? '';
-    }
-
-    toJSON(): object {
-        return {
-            deviceId: this.deviceId,
-            kind: this.kind,
-            label: this.label,
-            groupId: this.groupId,
-        };
-    }
-}

package/src/media-devices.ts

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

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