@blockcast/mmt-transport 0.2.0

package/dist/amt-gateway.js

@@ -0,0 +1,390 @@
+/**
+ * @blockcast/transport - AMT Gateway
+ *
+ * Consolidated AMT (Automatic Multicast Tunneling) implementation
+ * supporting both Service Worker and Direct Sockets approaches.
+ *
+ * RFC 7450: Automatic Multicast Tunneling
+ */
+import { DRIADDiscovery } from "./driad-discovery.js";
+/** Default AMT port (RFC 7450) */
+const DEFAULT_AMT_PORT = 2268;
+/** AMT message types */
+const AMT_MESSAGE_TYPES = {
+    RELAY_DISCOVERY: 1,
+    RELAY_ADVERTISEMENT: 2,
+    REQUEST: 3,
+    MEMBERSHIP_QUERY: 4,
+    MEMBERSHIP_UPDATE: 5,
+    MULTICAST_DATA: 6,
+    TEARDOWN: 7,
+};
+/** AMT gateway states */
+const GATEWAY_STATES = {
+    IDLE: "idle",
+    DISCOVERING: "discovering",
+    REQUESTING: "requesting",
+    QUERYING: "querying",
+    ACTIVE: "active",
+    LEAVING: "leaving",
+    CLOSED: "closed",
+};
+/** Check if address is IPv4 */
+function isIPv4(address) {
+    return /^\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(address);
+}
+/**
+ * AMT Gateway Manager (Service Worker based)
+ *
+ * Manages AMT tunnel subscriptions using Service Worker for UDP communication.
+ * Handles DRIAD discovery, AMT handshake, and packet decapsulation.
+ */
+export class AMTGatewayManager {
+    subscriptions = new Map();
+    messageHandler;
+    pendingPackets = new Map();
+    driad = new DRIADDiscovery();
+    constructor() {
+        // Set up message handler for packets from service worker
+        this.messageHandler = (event) => {
+            const data = event.data;
+            console.log(`[AMT] SW message received:`, data.type);
+            if (data.type === "UDP_PACKET") {
+                this.handlePacket(data);
+            }
+            else if (data.type === "SOCKET_ERROR") {
+                this.handleSocketError(data);
+            }
+            else if (data.type === "DEBUG_LOG") {
+                console.log(`[AMT SW Debug] ${data.message}`);
+            }
+        };
+        // Register message handler
+        if (typeof navigator !== "undefined" && navigator.serviceWorker) {
+            navigator.serviceWorker.addEventListener("message", this.messageHandler);
+            console.log("[AMT] Registered service worker message handler");
+        }
+        else {
+            console.warn("[AMT] Service worker not available");
+        }
+    }
+    /**
+     * Subscribe via AMT tunnel
+     */
+    async subscribe(config) {
+        const { key } = config;
+        const keyStr = this.getKeyString(key);
+        if (this.subscriptions.has(keyStr)) {
+            throw new Error(`Already subscribed to ${keyStr}`);
+        }
+        try {
+            let relayAddress;
+            let discoveryMethod;
+            const relayPort = config.relayPort || DEFAULT_AMT_PORT;
+            if (config.relayAddress) {
+                relayAddress = config.relayAddress;
+                discoveryMethod = "manual";
+                console.log(`[AMT] Using configured relay ${relayAddress}:${relayPort}`);
+            }
+            else if (key.source) {
+                // DRIAD (RFC 8777) discovers relays based on SOURCE address, not group
+                console.log(`[AMT] No relay configured, discovering via DRIAD for source ${key.source}...`);
+                const relays = await this.driad.discoverRelays(key.source);
+                const bestRelay = await this.driad.selectBestRelay(relays);
+                if (!bestRelay) {
+                    throw new Error(`AMT relay discovery failed for source ${key.source}. ` +
+                        `Please specify a relay address in the subscription configuration.`);
+                }
+                relayAddress = bestRelay.host;
+                discoveryMethod = "driad";
+                console.log(`[AMT] Discovered relay via DRIAD: ${relayAddress}:${relayPort}`);
+            }
+            else {
+                throw new Error(`AMT relay discovery requires a source address for SSM (RFC 8777). ` +
+                    `Please specify either a relay address or source address.`);
+            }
+            const subscriptionId = keyStr;
+            // Initialize packet queue for handshake
+            this.pendingPackets.set(subscriptionId, []);
+            // Create subscription
+            const subscription = {
+                key,
+                subscriptionId,
+                config,
+                handshakeComplete: false,
+                relay: {
+                    address: relayAddress,
+                    port: relayPort,
+                    discoveryMethod,
+                    discoveredAt: Date.now(),
+                },
+            };
+            this.subscriptions.set(keyStr, subscription);
+            // Note: Actual UDP socket creation and handshake would require
+            // Service Worker communication - this is a simplified version
+            console.log(`[AMT] Subscription created for ${keyStr} via ${relayAddress}:${relayPort}`);
+            return keyStr;
+        }
+        catch (error) {
+            const subscription = this.subscriptions.get(keyStr);
+            if (subscription) {
+                this.subscriptions.delete(keyStr);
+                this.pendingPackets.delete(subscription.subscriptionId);
+            }
+            throw new Error(`Failed to subscribe via AMT: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    /**
+     * Unsubscribe from AMT tunnel
+     */
+    async unsubscribe(handle) {
+        const subscription = this.subscriptions.get(handle);
+        if (!subscription) {
+            throw new Error(`Subscription ${handle} not found`);
+        }
+        try {
+            // Stop keep-alive timer
+            if (subscription.keepAliveTimer) {
+                clearInterval(subscription.keepAliveTimer);
+            }
+            console.log(`[AMT] Unsubscribed from ${handle}`);
+        }
+        catch (error) {
+            console.error("[AMT] Error during unsubscribe:", error);
+        }
+        finally {
+            this.subscriptions.delete(handle);
+            this.pendingPackets.delete(subscription.subscriptionId);
+        }
+    }
+    /**
+     * Get list of active subscriptions
+     */
+    getSubscriptions() {
+        return Array.from(this.subscriptions.keys());
+    }
+    /**
+     * Handle packet from service worker
+     */
+    handlePacket(message) {
+        const { subscriptionId, data } = message;
+        if (!subscriptionId)
+            return;
+        const subscription = this.subscriptions.get(subscriptionId);
+        if (!subscription) {
+            console.warn(`[AMT] Received packet for unknown subscription: ${subscriptionId}`);
+            return;
+        }
+        // During handshake, queue packets
+        if (!subscription.handshakeComplete) {
+            const queue = this.pendingPackets.get(subscriptionId);
+            const packetData = data;
+            if (queue) {
+                queue.push({
+                    data: packetData.data,
+                    remoteAddress: packetData.remoteAddress,
+                    remotePort: packetData.remotePort,
+                });
+            }
+            return;
+        }
+        // After handshake, forward to callback
+        const packetData = data;
+        const metadata = {
+            sourceAddress: subscription.relay?.address || "unknown",
+            sourcePort: subscription.relay?.port || 0,
+            transport: "tunnel",
+            timestamp: performance.now(),
+        };
+        subscription.config.onPacket(packetData.data, metadata);
+    }
+    /**
+     * Handle socket error from service worker
+     */
+    handleSocketError(message) {
+        const { subscriptionId, error } = message;
+        if (!subscriptionId)
+            return;
+        const subscription = this.subscriptions.get(subscriptionId);
+        if (!subscription) {
+            console.warn(`[AMT] Received error for unknown subscription: ${subscriptionId}`);
+            return;
+        }
+        subscription.config.onError(new Error(error || "Unknown error"));
+    }
+    /**
+     * Cleanup on destroy
+     */
+    destroy() {
+        if (this.messageHandler && typeof navigator !== "undefined" && navigator.serviceWorker) {
+            navigator.serviceWorker.removeEventListener("message", this.messageHandler);
+        }
+        const handles = Array.from(this.subscriptions.keys());
+        for (const handle of handles) {
+            this.unsubscribe(handle).catch((err) => {
+                console.error(`[AMT] Error unsubscribing ${handle}:`, err);
+            });
+        }
+    }
+    /**
+     * Get key string for HashMap
+     */
+    getKeyString(key) {
+        const source = key.source ? `@${key.source}` : "";
+        return `${key.group}:${key.port}${source}`;
+    }
+}
+/**
+ * AMT Gateway Client (Direct Sockets based)
+ *
+ * Connects to an AMT relay to receive multicast data via unicast tunnel.
+ * Implements the gateway side of RFC 7450.
+ * Supports multiple (S,G) groups over a single AMT tunnel.
+ */
+export class AMTGateway {
+    relayAddress;
+    relayPort;
+    groups = new Map();
+    // Callbacks
+    onPacket;
+    onStateChange;
+    onError;
+    onLog;
+    // State
+    state = GATEWAY_STATES.IDLE;
+    nonce = null;
+    responseMAC = null;
+    relayConfirmedAddress = null;
+    lastDataTime = 0;
+    // Stats
+    stats = {
+        packetsReceived: 0,
+        bytesReceived: 0,
+        queriesReceived: 0,
+        updatesSet: 0,
+    };
+    constructor(options) {
+        this.relayAddress = options.relayAddress;
+        this.relayPort = options.relayPort || DEFAULT_AMT_PORT;
+        this.onPacket = options.onPacket || (() => { });
+        this.onStateChange = options.onStateChange || (() => { });
+        this.onError = options.onError || ((err) => console.error("AMT Error:", err));
+        this.onLog = options.onLog || ((msg) => console.log("AMT:", msg));
+    }
+    /**
+     * Generate random nonce
+     */
+    generateNonce() {
+        const nonce = new Uint8Array(4);
+        crypto.getRandomValues(nonce);
+        return nonce;
+    }
+    /**
+     * Set gateway state
+     */
+    setState(newState) {
+        const oldState = this.state;
+        this.state = newState;
+        this.onLog(`State: ${oldState} -> ${newState}`);
+        this.onStateChange(newState, oldState);
+    }
+    /**
+     * Join a multicast group
+     */
+    async joinGroup(groupAddress, groupPort, sourceAddress = null, onPacket = null) {
+        const groupKey = `${sourceAddress || "*"},${groupAddress}`;
+        if (this.groups.has(groupKey)) {
+            this.onLog(`Group already joined: ${groupKey}`);
+            return groupKey;
+        }
+        this.groups.set(groupKey, {
+            groupPort,
+            onPacket,
+            joinedAt: Date.now(),
+        });
+        this.onLog(`Joined group: ${groupKey} (port ${groupPort})`);
+        return groupKey;
+    }
+    /**
+     * Leave a multicast group
+     */
+    async leaveGroup(groupAddress, sourceAddress = null) {
+        const groupKey = `${sourceAddress || "*"},${groupAddress}`;
+        if (!this.groups.has(groupKey)) {
+            this.onLog(`Group not found: ${groupKey}`);
+            return false;
+        }
+        this.groups.delete(groupKey);
+        this.onLog(`Left group: ${groupKey} (${this.groups.size} remaining)`);
+        if (this.groups.size === 0) {
+            this.onLog("No groups remaining - closing AMT tunnel");
+            await this.close();
+        }
+        return true;
+    }
+    /**
+     * Get list of active groups
+     */
+    getGroups() {
+        return Array.from(this.groups.entries()).map(([key, info]) => {
+            const [source, group] = key.split(",");
+            return {
+                groupKey: key,
+                groupAddress: group,
+                sourceAddress: source !== "*" ? source : null,
+                groupPort: info.groupPort,
+                joinedAt: info.joinedAt,
+            };
+        });
+    }
+    /**
+     * Open connection to AMT relay
+     */
+    async open() {
+        if (this.state !== GATEWAY_STATES.IDLE) {
+            throw new Error(`Cannot open in state: ${this.state}`);
+        }
+        this.setState(GATEWAY_STATES.DISCOVERING);
+        this.onLog(`Connecting to AMT relay ${this.relayAddress}:${this.relayPort}`);
+        this.onLog(`Active groups: ${this.groups.size}`);
+        // Generate session nonce
+        this.nonce = this.generateNonce();
+        this.onLog(`Generated nonce: ${Array.from(this.nonce).map((b) => b.toString(16).padStart(2, "0")).join("")}`);
+        // Note: Actual UDPSocket connection would go here
+        // This is a simplified version showing the state machine
+    }
+    /**
+     * Close connection
+     */
+    async close() {
+        if (this.state === GATEWAY_STATES.CLOSED) {
+            return;
+        }
+        this.setState(GATEWAY_STATES.LEAVING);
+        // Clear all groups
+        this.groups.clear();
+        this.setState(GATEWAY_STATES.CLOSED);
+        this.onLog("AMT Gateway closed");
+    }
+    /**
+     * Get current statistics
+     */
+    getStats() {
+        return { ...this.stats };
+    }
+    /**
+     * Get current state
+     */
+    getState() {
+        return this.state;
+    }
+    /**
+     * Check if gateway is active and receiving data
+     */
+    isActive() {
+        return this.state === GATEWAY_STATES.ACTIVE;
+    }
+}
+// Export singleton manager instance
+export const amtGatewayManager = new AMTGatewayManager();
+//# sourceMappingURL=amt-gateway.js.map

package/dist/amt-gateway.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"amt-gateway.js","sourceRoot":"","sources":["../src/amt-gateway.ts"],"names":[],"mappings":"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"}

package/dist/clock.d.ts

@@ -0,0 +1,104 @@
+/**
+ * @blockcast/transport - SharedClock
+ *
+ * A/V Synchronization via First Sample Anchor
+ *
+ * Based on ExoPlayer MMT Plugin implementation:
+ * - MMTExtractor.java:46-47 (SystemClockAnchor, MfuClockAnchor)
+ * - MMTExtractor.java:625-631 (anchor setting)
+ * - SystemClockSynchronizedSimpleDecoderAudioRenderer.java:576 (getPositionUs)
+ *
+ * This class provides a shared clock anchor across video and audio tracks
+ * to ensure A/V synchronization. The anchor is set on the first sample
+ * received from ANY track, establishing a common reference point.
+ */
+import type { Micro, SyncDecision } from "./types.js";
+/** Sync tolerance window in microseconds (66ms = ~2 video frames at 30fps) */
+export declare const SYNC_TOLERANCE_US: Micro;
+/** PTS offset for decoder timing (from ExoPlayer MMTExtractor.java:37) */
+export declare const PTS_OFFSET_US: Micro;
+/**
+ * Shared clock for A/V synchronization.
+ *
+ * Usage:
+ * ```typescript
+ * const clock = new SharedClock();
+ *
+ * // In video/audio source, on first decoded frame:
+ * clock.setAnchor(frame.timestamp);
+ *
+ * // Before rendering each frame:
+ * const decision = clock.shouldRender(frame.timestamp);
+ * if (decision === "render") { ... }
+ * else if (decision === "hold") { await sleep(10); retry(); }
+ * else { frame.close(); } // discard
+ * ```
+ */
+export declare class SharedClock {
+    #private;
+    constructor(bufferDelayMs?: number);
+    /**
+     * Set the anchor on first sample received from ANY track.
+     * This should be called once per session, typically on the first keyframe.
+     *
+     * @param mediaTimestamp - The presentation timestamp of the first sample (microseconds)
+     */
+    setAnchor(mediaTimestamp: Micro): void;
+    /**
+     * Get the current playback position in microseconds.
+     *
+     * @returns Current position in microseconds, or 0 if anchor not set
+     */
+    getPositionUs(): Micro;
+    /**
+     * Determine whether a frame should be rendered, held, or discarded.
+     *
+     * - HOLD: Frame is ahead of clock by more than 66ms (wait for clock)
+     * - DISCARD: Frame is behind clock by more than 66ms (too late)
+     * - RENDER: Within +/-66ms tolerance window
+     *
+     * @param frameTimestamp - The presentation timestamp of the frame (microseconds)
+     * @returns "render", "hold", or "discard"
+     */
+    shouldRender(frameTimestamp: Micro): SyncDecision;
+    /**
+     * Get how long to wait before a held frame can be rendered.
+     *
+     * @param frameTimestamp - The presentation timestamp of the frame (microseconds)
+     * @returns Wait time in milliseconds, or 0 if frame should be rendered now
+     */
+    getWaitTimeMs(frameTimestamp: Micro): number;
+    /**
+     * Get the delta between a frame timestamp and current position.
+     * Positive = frame is ahead, negative = frame is behind.
+     *
+     * @param frameTimestamp - The presentation timestamp of the frame (microseconds)
+     * @returns Delta in microseconds
+     */
+    getDeltaUs(frameTimestamp: Micro): number;
+    /**
+     * Check if the anchor has been set.
+     */
+    hasAnchor(): boolean;
+    /**
+     * Get the MFU clock anchor (minimum PTS across all tracks).
+     * Used for A/V sync reference point.
+     */
+    getMfuClockAnchor(): Micro;
+    /**
+     * Reset the clock anchor (e.g., on seek or error recovery).
+     */
+    reset(): void;
+    /**
+     * Get debug info about the current clock state.
+     */
+    getDebugInfo(): {
+        hasAnchor: boolean;
+        positionUs: Micro;
+        mfuClockAnchor: Micro;
+        bufferDelayMs: number;
+    };
+}
+export declare function getSharedClock(bufferDelayMs?: number): SharedClock;
+export declare function resetSharedClock(): void;
+//# sourceMappingURL=clock.d.ts.map

package/dist/clock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"clock.d.ts","sourceRoot":"","sources":["../src/clock.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAEtD,8EAA8E;AAC9E,eAAO,MAAM,iBAAiB,EAAY,KAAK,CAAC;AAQhD,0EAA0E;AAC1E,eAAO,MAAM,aAAa,EAAa,KAAK,CAAC;AAE7C;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,WAAW;;gBAaX,aAAa,GAAE,MAAgC;IAI3D;;;;;OAKG;IACH,SAAS,CAAC,cAAc,EAAE,KAAK,GAAG,IAAI;IAatC;;;;OAIG;IACH,aAAa,IAAI,KAAK;IAYtB;;;;;;;;;OASG;IACH,YAAY,CAAC,cAAc,EAAE,KAAK,GAAG,YAAY;IAgBjD;;;;;OAKG;IACH,aAAa,CAAC,cAAc,EAAE,KAAK,GAAG,MAAM;IAU5C;;;;;;OAMG;IACH,UAAU,CAAC,cAAc,EAAE,KAAK,GAAG,MAAM;IAIzC;;OAEG;IACH,SAAS,IAAI,OAAO;IAIpB;;;OAGG;IACH,iBAAiB,IAAI,KAAK;IAI1B;;OAEG;IACH,KAAK,IAAI,IAAI;IAOb;;OAEG;IACH,YAAY,IAAI;QACf,SAAS,EAAE,OAAO,CAAC;QACnB,UAAU,EAAE,KAAK,CAAC;QAClB,cAAc,EAAE,KAAK,CAAC;QACtB,aAAa,EAAE,MAAM,CAAC;KACtB;CAQD;AAQD,wBAAgB,cAAc,CAAC,aAAa,CAAC,EAAE,MAAM,GAAG,WAAW,CAKlE;AAED,wBAAgB,gBAAgB,IAAI,IAAI,CAGvC"}