@blockcast/mmt-container 0.1.0-main.149f78a4adae

package/src/track-pipeline.ts

@@ -0,0 +1,332 @@
+/**
+ * TrackPipeline — per-track transport promotion + ABR integration.
+ *
+ * Coordinates transport promotion (MoQ → multicast/AMT) on a per-track basis.
+ * Shared by both web players (moq-lib, moqtail) and the IWA.
+ *
+ * Responsibilities:
+ *   1. Takes per-track transport preferences and current capabilities
+ *   2. Runs the pure resolveTransports() function to get assignments
+ *   3. Calls MediaRouter.setTrackSource() per-track with the resolved policy
+ *   4. Re-resolves when capabilities change (network switch, multicast detected)
+ *   5. Integrates ABR quality changes with track-level subscription management
+ *
+ * NOT responsible for:
+ *   - Socket management (that's MulticastTransport / NativeMulticastManager)
+ *   - FEC decode (that's FECManager)
+ *   - MMTP parsing (that's MmtpRouter)
+ *   - Binary MoQ↔multicast switching (that's MediaRouter.feedMoq/feedMulticast)
+ *
+ * Usage:
+ *   const pipeline = new TrackPipeline(mediaRouter);
+ *   pipeline.setPreferences(prefs);
+ *   pipeline.updateCapabilities(caps);
+ *   // pipeline calls mediaRouter.setTrackSource() automatically
+ *   // listen for transport changes:
+ *   pipeline.onTransportChange((trackName, from, to, policy) => { ... });
+ */
+
+import type { MediaRouter, TrackSource } from './media-router.js'
+import type { MigrationPolicy } from './media-router.js'
+
+// Inline transport types to avoid dep on @blockcast/shared at runtime.
+// These MUST stay compatible with @blockcast/shared/transport-settings.
+export type TrackTransport = 'multicast' | 'amt' | 'moq' | 'auto'
+
+export interface TrackTransportPreference {
+  trackName: string
+  /** Actual media type from catalog (never inferred from name). */
+  trackType: 'video' | 'audio'
+  preferred: TrackTransport[]
+  maxLatencyMs?: number
+  migrationPolicy?: MigrationPolicy
+}
+
+export interface TransportCapabilityReport {
+  nativeMulticast: { confirmed: boolean; lastPacketAt?: number }
+  amt: { available: boolean; relay?: string; rttMs?: number }
+  moqRelay: { reachable: boolean; rttMs?: number }
+  networkHint?: 'wifi' | 'cellular' | 'ethernet' | 'unknown'
+  observedAt: number
+}
+
+export interface TrackTransportResolution {
+  trackName: string
+  assignedTransport: TrackTransport
+  reason: 'preferred' | 'fallback' | 'capability-limited' | 'latency-gated' | 'abr-override'
+  migrationPolicy: MigrationPolicy
+}
+
+/** Callback for transport change events */
+type TransportChangeCb = (
+  trackName: string,
+  from: TrackTransport | null,
+  to: TrackTransport,
+  policy: MigrationPolicy,
+) => void
+
+/** Callback for ABR quality change requests */
+type QualityChangeCb = (trackName: string, quality: { name: string; bitrate: number }) => void
+
+/** Factory that creates a TrackSource for a given transport + track */
+export type TrackSourceFactory = (
+  trackName: string,
+  transport: TrackTransport,
+) => TrackSource | null
+
+// Default auto expansion: multicast → amt → moq
+const AUTO_CHAIN: Exclude<TrackTransport, 'auto'>[] = ['multicast', 'amt', 'moq']
+
+// Default migration policies
+const DEFAULT_POLICY: Record<string, MigrationPolicy> = {
+  audio: 'crossfade',
+  video: 'wait',
+}
+
+/** Per-track state tracked by the pipeline */
+interface TrackState {
+  currentTransport: TrackTransport | null
+  preference: TrackTransportPreference
+  resolution: TrackTransportResolution | null
+}
+
+export class TrackPipeline {
+  #router: MediaRouter
+  #sourceFactory: TrackSourceFactory | null = null
+  #tracks = new Map<string, TrackState>()
+  #capabilities: TransportCapabilityReport | null = null
+  #onTransportChange: TransportChangeCb | null = null
+  #onQualityChange: QualityChangeCb | null = null
+
+  constructor(router: MediaRouter) {
+    this.#router = router
+  }
+
+  // ---------------------------------------------------------------------------
+  // Configuration
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Register a factory that creates TrackSource instances for a given transport.
+   * The factory is called when the pipeline resolves a track to a new transport
+   * and needs to wire it into the MediaRouter.
+   *
+   * The factory returns null if the transport is not available for that track
+   * (e.g., no multicast socket for this group).
+   */
+  setSourceFactory(factory: TrackSourceFactory): void {
+    this.#sourceFactory = factory
+  }
+
+  /** Listen for transport change events (after setTrackSource is called). */
+  onTransportChange(cb: TransportChangeCb): void {
+    this.#onTransportChange = cb
+  }
+
+  /** Listen for ABR-driven quality change requests. */
+  onQualityChange(cb: QualityChangeCb): void {
+    this.#onQualityChange = cb
+  }
+
+  // ---------------------------------------------------------------------------
+  // Preferences + Capabilities
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Set per-track transport preferences. Triggers resolution if capabilities
+   * are already known. Safe to call multiple times (replaces previous prefs).
+   */
+  setPreferences(prefs: TrackTransportPreference[]): void {
+    for (const pref of prefs) {
+      const existing = this.#tracks.get(pref.trackName)
+      this.#tracks.set(pref.trackName, {
+        currentTransport: existing?.currentTransport ?? null,
+        preference: pref,
+        resolution: existing?.resolution ?? null,
+      })
+    }
+    // Remove tracks no longer in prefs
+    for (const name of this.#tracks.keys()) {
+      if (!prefs.find(p => p.trackName === name)) {
+        this.#router.clearTrackSource(name)
+        this.#tracks.delete(name)
+      }
+    }
+    if (this.#capabilities) this.#resolve()
+  }
+
+  /**
+   * Update capability snapshot. Triggers re-resolution against current prefs.
+   * Called by the IWA's CapabilityObserver, or by the player's extension bridge
+   * on capability change events.
+   */
+  updateCapabilities(caps: TransportCapabilityReport): void {
+    this.#capabilities = caps
+    if (this.#tracks.size > 0) this.#resolve()
+  }
+
+  /**
+   * Force a specific transport for a track (e.g., user override, debug).
+   * Skips the resolver; applies immediately.
+   */
+  forceTransport(trackName: string, transport: TrackTransport, policy?: MigrationPolicy): void {
+    const state = this.#tracks.get(trackName)
+    if (!state) return
+
+    const effectivePolicy = policy ?? this.#defaultPolicy(state.preference.trackType)
+    this.#applyTransport(trackName, transport, effectivePolicy)
+  }
+
+  // ---------------------------------------------------------------------------
+  // ABR Integration
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Notify the pipeline of an ABR quality change. The pipeline adjusts the
+   * transport ceiling and may trigger a transport switch if the new quality
+   * exceeds the current transport's capacity.
+   */
+  notifyQualityChange(trackName: string, quality: { name: string; bitrate: number }): void {
+    this.#onQualityChange?.(trackName, quality)
+    // Re-resolve: ABR quality may push a track to a different transport
+    if (this.#capabilities) this.#resolve()
+  }
+
+  // ---------------------------------------------------------------------------
+  // Query
+  // ---------------------------------------------------------------------------
+
+  /** Current transport for a track (null if not yet resolved). */
+  getTransport(trackName: string): TrackTransport | null {
+    return this.#tracks.get(trackName)?.currentTransport ?? null
+  }
+
+  /** Current resolution for a track (null if not yet resolved). */
+  getResolution(trackName: string): TrackTransportResolution | null {
+    return this.#tracks.get(trackName)?.resolution ?? null
+  }
+
+  /** All track names managed by this pipeline. */
+  get trackNames(): string[] {
+    return [...this.#tracks.keys()]
+  }
+
+  // ---------------------------------------------------------------------------
+  // Teardown
+  // ---------------------------------------------------------------------------
+
+  dispose(): void {
+    for (const name of this.#tracks.keys()) {
+      this.#router.clearTrackSource(name)
+    }
+    this.#tracks.clear()
+    this.#capabilities = null
+    this.#onTransportChange = null
+    this.#onQualityChange = null
+  }
+
+  // ---------------------------------------------------------------------------
+  // Internal
+  // ---------------------------------------------------------------------------
+
+  /** Run the resolver and apply transport changes. */
+  #resolve(): void {
+    const caps = this.#capabilities!
+    for (const [trackName, state] of this.#tracks) {
+      const resolution = this.#resolveTrack(state.preference, caps)
+      state.resolution = resolution
+
+      if (resolution.assignedTransport !== state.currentTransport) {
+        this.#applyTransport(trackName, resolution.assignedTransport, resolution.migrationPolicy)
+      }
+    }
+  }
+
+  /** Pure per-track resolution (inline, no dependency on @blockcast/shared). */
+  #resolveTrack(
+    pref: TrackTransportPreference,
+    caps: TransportCapabilityReport,
+  ): TrackTransportResolution {
+    const chain = this.#expandPreferred(pref.preferred)
+
+    for (let i = 0; i < chain.length; i++) {
+      const transport = chain[i]!
+      if (!this.#isAvailable(transport, caps)) continue
+
+      return {
+        trackName: pref.trackName,
+        assignedTransport: transport,
+        reason: i === 0 ? 'preferred' : 'fallback',
+        migrationPolicy: pref.migrationPolicy ?? this.#defaultPolicy(pref.trackType),
+      }
+    }
+
+    // Nothing available — stay on current or fall back to moq
+    return {
+      trackName: pref.trackName,
+      assignedTransport: 'moq',
+      reason: 'capability-limited',
+      migrationPolicy: pref.migrationPolicy ?? this.#defaultPolicy(pref.trackType),
+    }
+  }
+
+  /** Apply a resolved transport to a track via MediaRouter. */
+  #applyTransport(trackName: string, transport: TrackTransport, policy: MigrationPolicy): void {
+    const state = this.#tracks.get(trackName)
+    if (!state) return
+
+    const prev = state.currentTransport
+
+    // MoQ is the default binary path — clear per-track source to fall back
+    if (transport === 'moq') {
+      this.#router.clearTrackSource(trackName)
+      state.currentTransport = 'moq'
+      if (prev !== 'moq') {
+        this.#onTransportChange?.(trackName, prev, 'moq', policy)
+      }
+      return
+    }
+
+    // For multicast/amt: create a TrackSource via the factory
+    if (!this.#sourceFactory) {
+      console.warn(`[TrackPipeline] No source factory registered; cannot create source for ${trackName}/${transport}`)
+      return
+    }
+
+    const source = this.#sourceFactory(trackName, transport)
+    if (!source) {
+      console.warn(`[TrackPipeline] Factory returned null for ${trackName}/${transport}; keeping current transport`)
+      return
+    }
+
+    // Clear previous per-track source (if any) before setting new one
+    if (prev && prev !== 'moq') {
+      this.#router.clearTrackSource(trackName)
+    }
+
+    this.#router.setTrackSource(trackName, source, { policy })
+    state.currentTransport = transport
+    this.#onTransportChange?.(trackName, prev, transport, policy)
+  }
+
+  #expandPreferred(preferred: TrackTransport[]): Exclude<TrackTransport, 'auto'>[] {
+    const out: Exclude<TrackTransport, 'auto'>[] = []
+    for (const t of preferred) {
+      if (t === 'auto') out.push(...AUTO_CHAIN)
+      else out.push(t)
+    }
+    return out
+  }
+
+  #isAvailable(transport: Exclude<TrackTransport, 'auto'>, caps: TransportCapabilityReport): boolean {
+    switch (transport) {
+      case 'multicast': return caps.nativeMulticast.confirmed
+      case 'amt': return caps.amt.available
+      case 'moq': return caps.moqRelay.reachable
+    }
+  }
+
+  #defaultPolicy(trackType: 'video' | 'audio'): MigrationPolicy {
+    return DEFAULT_POLICY[trackType]!
+  }
+}