@blockcast/mmt-transport 0.2.0

package/src/types.ts

@@ -0,0 +1,420 @@
+/**
+ * @blockcast/transport - Type Definitions
+ *
+ * Shared interfaces for unified transport (WebTransport, SSM, AMT, DRIAD) and FEC.
+ */
+
+/** window.Multicast API type (from IWA/Chrome Direct Sockets) */
+export interface MulticastAPI {
+	subscribeSSM?: (config: {
+		group: string;
+		source: string;
+		port: number;
+		protocol?: string;
+		fec?: boolean;
+	}) => Promise<MulticastSubscription>;
+	subscribe?: (config: {
+		group: string;
+		port: number;
+		protocol?: string;
+		fec?: boolean;
+	}) => Promise<MulticastSubscription>;
+	connectAMT?: (config: {
+		relay: string;
+		group: string;
+		source?: string;
+		port: number;
+	}) => Promise<{ onpacket?: (event: { data: ArrayBuffer }) => void; close: () => void }>;
+	fecDecode?: boolean;
+}
+
+export interface MulticastSubscription {
+	onpacket?: (event: { data: ArrayBuffer }) => void;
+	onerror?: (error: Error) => void;
+	unsubscribe: () => void;
+}
+
+declare global {
+	interface Window {
+		Multicast?: MulticastAPI;
+		UDPSocket?: unknown;
+	}
+}
+
+/** Transport configuration for multicast subscriptions */
+export interface TransportConfig {
+	/** Multicast group address (232.x.x.x for SSM) */
+	group: string;
+	/** Source address for SSM filtering */
+	source: string;
+	/** UDP port */
+	port: number;
+	/** Stream type */
+	streamType: "video" | "audio";
+	/** Optional AMT relay host for unicast tunneling */
+	amtRelay?: string;
+	/** DRIAD discovery enabled */
+	driadEnabled?: boolean;
+	/** Initial bitrate quality level */
+	initialQuality?: QualityLevel;
+}
+
+/** @deprecated Use TransportConfig instead */
+export type SSMConfig = TransportConfig;
+
+export interface QualityLevel {
+	name: string;
+	bitrate: number;
+	width: number;
+	height: number;
+	fps: number;
+}
+
+export interface TransportCapabilities {
+	nativeSSM: boolean;
+	nativeIGMP: boolean;
+	directSockets: boolean;
+	amt: boolean;
+	driad: boolean;
+	fecDecode: boolean;
+}
+
+export type TransportMode = "ssm" | "igmp" | "amt" | "driad" | "moq" | "disconnected";
+
+export interface TransportState {
+	mode: TransportMode;
+	connected: boolean;
+	group?: string;
+	source?: string;
+	amtRelay?: string;
+	driadRelay?: string;
+	quality?: QualityLevel;
+	packetsReceived: number;
+	bytesReceived: number;
+	lastPacketTime: number;
+}
+
+/** Transport subscription handle */
+export interface TransportSubscription {
+	id: string;
+	config: TransportConfig;
+	onpacket?: (data: ArrayBuffer) => void;
+	onerror?: (error: Error) => void;
+	onqualitychange?: (quality: QualityLevel) => void;
+	close: () => void;
+}
+
+/** @deprecated Use TransportSubscription instead */
+export type SSMSubscription = TransportSubscription;
+
+/** DRIAD Relay information (RFC 8777) */
+export interface DRIADRelay {
+	host: string;
+	port: number;
+	priority: number;
+	weight: number;
+	asn: number;
+	rtt?: number;
+}
+
+/** AMT Relay information */
+export interface AmtRelayInfo {
+	address: string;
+	port: number;
+	discoveryMethod: "driad" | "manual";
+	discoveredAt: number;
+}
+
+/** Group key for multicast subscriptions */
+export interface GroupKey {
+	group: string;
+	port: number;
+	source?: string;
+}
+
+/** Packet metadata */
+export interface PacketMetadata {
+	sourceAddress: string;
+	sourcePort: number;
+	transport: "native" | "tunnel" | "websocket";
+	timestamp: number;
+}
+
+/** MFU Fragment for reassembly */
+export interface MfuFragment {
+	mpuSequenceNumber: number;
+	fragmentationIndicator: number; // 0=complete, 1=first, 2=middle, 3=last
+	fragmentCounter: number;
+	data: Uint8Array;
+	timestamp: bigint;
+}
+
+/** Reassembled MFU */
+export interface ReassembledMfu {
+	mpuSequenceNumber: number;
+	data: Uint8Array;
+	timestamp: bigint;
+	fragmentCount: number;
+	recoveredViaFec: boolean;
+}
+
+/** FEC + MFU processing statistics */
+export interface ProcessingStats {
+	// MFU stats
+	mfuComplete: number;
+	mfuReassembled: number;
+	mfuTimedOut: number;
+
+	// FEC stats
+	fecSourcePackets: number;
+	fecRepairPackets: number;
+	fecBlocksComplete: number;
+	fecBlocksRecovered: number;
+	fecBlocksFailed: number;
+	fecRecoveryRate: number;
+
+	// Green-fill stats
+	greenFillFrames: number;
+}
+
+/** Options for MmtFecClient */
+export interface MmtFecClientOptions {
+	/** Interleave depth for FEC (default: 30 for ~1s at 30fps) */
+	interleaveDepth?: number;
+
+	/** Block timeout in milliseconds (default: 2000) */
+	blockTimeoutMs?: number;
+
+	/** MFU timeout in milliseconds (default: 1000) */
+	mfuTimeoutMs?: number;
+
+	/** Enable green-fill for failed frames (default: true) */
+	greenFillEnabled?: boolean;
+
+	/** Callback when MFU is ready */
+	onMfuReady?: (mfu: ReassembledMfu) => void;
+
+	/** Callback for green-fill frame */
+	onGreenFill?: (timestamp: bigint) => void;
+
+	/** Callback for stats update */
+	onStatsUpdate?: (stats: ProcessingStats) => void;
+}
+
+/** Time types (microseconds) */
+export type Micro = number & { readonly __micro: unique symbol };
+
+/** Sync decision for A/V synchronization */
+export type SyncDecision = "render" | "hold" | "discard";
+
+// ============================================================
+// Multicast Bridge Types (consolidated from @blockcast/multicast)
+// ============================================================
+
+/** Transport mode for multicast subscription (auto-selection) */
+export type MulticastTransportMode = "auto" | "native" | "tunnel";
+
+/** Multicast subscription configuration */
+export interface MulticastConfig {
+	group: string;
+	port: number;
+	source?: string;
+	mode?: MulticastTransportMode;
+	onPacket: (data: ArrayBuffer, source: PacketSource) => void;
+	onStateChange?: (state: SubscriptionState) => void;
+	onError?: (error: Error) => void;
+	amtRelay?: string;
+	amtRelayPort?: number;
+	nativeFallbackTimeout?: number;
+}
+
+/** Packet source information */
+export interface PacketSource {
+	address: string;
+	port: number;
+	transport: "native" | "tunnel";
+	recovered?: boolean;
+}
+
+/** Subscription state */
+export type SubscriptionState = "initializing" | "joining" | "active" | "suspended" | "closed" | "error";
+
+/** Subscription statistics */
+export interface SubscriptionStats {
+	packetsReceived: number;
+	bytesReceived: number;
+	packetsLost: number;
+	packetsRecovered: number;
+	bitrate: number;
+	uptime: number;
+}
+
+/** Multicast subscription handle */
+export interface MulticastSubscriptionHandle {
+	readonly state: SubscriptionState;
+	readonly group: string;
+	readonly source?: string;
+	readonly port: number;
+	readonly transport: "native" | "tunnel";
+	readonly stats: SubscriptionStats;
+	close(): Promise<void>;
+}
+
+/** FEC Configuration for MMT streams */
+export interface FecConfig {
+	enabled?: boolean;
+	oti?: Uint8Array;
+	interleaveDepth?: number;
+	blockTimeoutMs?: number;
+	greenFillEnabled?: boolean;
+}
+
+/** FEC Statistics */
+export interface FecStats {
+	sourcePackets: number;
+	repairPackets: number;
+	blocksComplete: number;
+	blocksRecovered: number;
+	blocksFailed: number;
+	recoveryRate: number;
+	greenFillFrames: number;
+}
+
+/** Extended MulticastConfig with FEC support */
+export interface MulticastConfigWithFec extends MulticastConfig {
+	fec?: FecConfig;
+	onFecStats?: (stats: FecStats) => void;
+}
+
+/** Main Multicast Bridge API */
+export interface MulticastBridge {
+	subscribe(config: MulticastConfig | MulticastConfigWithFec): Promise<MulticastSubscriptionHandle>;
+	getSubscriptions(): Promise<MulticastSubscriptionHandle[]>;
+	isNativeSupported(): Promise<boolean>;
+	getFecStats?(): FecStats | null;
+}
+
+// ============================================================
+// FEC Constants and Utilities per draft-ramadan-moq-fec-00
+// ============================================================
+
+/**
+ * FEC_CONFIG message type per draft-ramadan-moq-fec-00
+ * Used to signal FEC configuration to subscribers
+ */
+export const FEC_CONFIG_MESSAGE_TYPE = 0x50;
+
+/**
+ * Repair track suffix per draft-ramadan-moq-fec-00 Section 5.1
+ * Repair tracks are named by appending this suffix to the source track path
+ */
+export const REPAIR_TRACK_SUFFIX = "repair";
+
+/**
+ * Get the repair track path for a given source track
+ *
+ * Per draft-ramadan-moq-fec-00 Section 5.1, the repair track is named
+ * by appending "repair" to the source track path.
+ *
+ * @param sourceTrack - The source track path (e.g., "live/video")
+ * @returns The repair track path (e.g., "live/video/repair")
+ *
+ * @example
+ * repairTrackPath("live/video") // returns "live/video/repair"
+ * repairTrackPath("broadcast/video/1080p") // returns "broadcast/video/1080p/repair"
+ */
+export function repairTrackPath(sourceTrack: string): string {
+	if (!sourceTrack || sourceTrack.length === 0) {
+		return REPAIR_TRACK_SUFFIX;
+	}
+	return `${sourceTrack}/${REPAIR_TRACK_SUFFIX}`;
+}
+
+/**
+ * Check if a track path is a repair track
+ *
+ * @param path - The track path to check
+ * @returns True if the path ends with the repair track suffix
+ *
+ * @example
+ * isRepairTrack("live/video/repair") // returns true
+ * isRepairTrack("repair") // returns true
+ * isRepairTrack("live/video") // returns false
+ */
+export function isRepairTrack(path: string): boolean {
+	return path === REPAIR_TRACK_SUFFIX || path.endsWith(`/${REPAIR_TRACK_SUFFIX}`);
+}
+
+/**
+ * Get the source track path from a repair track path
+ *
+ * @param repairTrack - The repair track path
+ * @returns The source track path, or null if not a valid repair track
+ *
+ * @example
+ * sourceTrackFromRepair("live/video/repair") // returns "live/video"
+ * sourceTrackFromRepair("repair") // returns ""
+ * sourceTrackFromRepair("live/video") // returns null
+ */
+export function sourceTrackFromRepair(repairTrack: string): string | null {
+	if (repairTrack === REPAIR_TRACK_SUFFIX) {
+		return "";
+	}
+	const suffix = `/${REPAIR_TRACK_SUFFIX}`;
+	if (repairTrack.endsWith(suffix)) {
+		return repairTrack.slice(0, -suffix.length);
+	}
+	return null;
+}
+
+/**
+ * MoQ FEC Configuration per draft-ramadan-moq-fec-00
+ *
+ * This configuration is sent via FEC_CONFIG message after SUBSCRIBE_OK
+ * to inform subscribers about FEC parameters.
+ */
+export interface MoqFecConfig {
+	/** Subscribe ID this config applies to */
+	subscribeId: number;
+	/** Whether FEC is enabled */
+	enabled: boolean;
+	/** FEC algorithm (0=none, 1=XOR, 2=RaptorQ) */
+	algorithm: MoqFecAlgorithm;
+	/** Number of source symbols per FEC block (K) */
+	sourceSymbolsPerBlock: number;
+	/** Number of repair symbols per FEC block (P) */
+	repairSymbolsPerBlock: number;
+	/** Interleave depth for burst loss protection */
+	interleaveDepth: number;
+	/** Symbol size in bytes */
+	symbolSize: number;
+	/** RFC 6330 Object Transmission Information (12 bytes) - only for RaptorQ */
+	oti?: Uint8Array;
+}
+
+/**
+ * FEC algorithm identifier per draft-ramadan-moq-fec-00
+ */
+export enum MoqFecAlgorithm {
+	/** No FEC (disabled) */
+	None = 0,
+	/** Simple XOR parity */
+	Xor = 1,
+	/** RaptorQ (RFC 6330) - recommended for burst loss */
+	RaptorQ = 2,
+}
+
+/**
+ * Repair object header per draft-ramadan-moq-fec-00 Section 6.1
+ *
+ * Each object on a repair track contains repair symbols for one source block.
+ * The object payload begins with this header, followed by concatenated repair symbols.
+ */
+export interface RepairObjectHeader {
+	/** Source block number being protected (matches group_id of source objects) */
+	sourceBlockNumber: number;
+	/** First Repair Symbol ESI (Encoding Symbol ID) - for RaptorQ, repair ESIs >= K */
+	firstRepairEsi: number;
+	/** Number of repair symbols in this object */
+	numRepairSymbols: number;
+}