@blockcast/mmt-transport 0.2.0

package/src/abr-controller.ts

@@ -0,0 +1,227 @@
+/**
+ * @blockcast/transport - Adaptive Bitrate Controller
+ *
+ * Progressive adaptive bitrate increase based on network conditions.
+ * Monitors received bandwidth and packet loss to adjust quality levels.
+ *
+ * Per draft-ramadan-moq-fec-00, ABR decisions should use the **effective loss rate**
+ * after FEC recovery, not the raw transport-level loss rate. This allows FEC to
+ * mask burst losses without unnecessarily downgrading quality.
+ */
+
+import type { QualityLevel } from "./types.js";
+
+/**
+ * FEC statistics for ABR decisions
+ */
+export interface FecStatsForAbr {
+	/** Raw loss rate before FEC recovery (0.0-1.0) */
+	rawLossRate: number;
+	/** Effective loss rate after FEC recovery (0.0-1.0) */
+	effectiveLossRate: number;
+	/** FEC recovery rate (percentage of lost packets recovered) */
+	recoveryRate: number;
+	/** Whether FEC is enabled */
+	fecEnabled: boolean;
+}
+
+/**
+ * Standard quality levels for progressive ABR
+ */
+export const QUALITY_LEVELS: QualityLevel[] = [
+	{ name: "240p", bitrate: 300_000, width: 426, height: 240, fps: 15 },
+	{ name: "360p", bitrate: 500_000, width: 640, height: 360, fps: 24 },
+	{ name: "480p", bitrate: 1_000_000, width: 854, height: 480, fps: 30 },
+	{ name: "720p", bitrate: 2_500_000, width: 1280, height: 720, fps: 30 },
+	{ name: "1080p", bitrate: 5_000_000, width: 1920, height: 1080, fps: 30 },
+	{ name: "1440p", bitrate: 8_000_000, width: 2560, height: 1440, fps: 30 },
+	{ name: "4K", bitrate: 15_000_000, width: 3840, height: 2160, fps: 30 },
+];
+
+/**
+ * Progressive Adaptive Bitrate Controller
+ *
+ * Features:
+ * - Monitors bandwidth via received bytes over time window
+ * - Tracks packet loss rate (raw and effective after FEC)
+ * - Uses effective loss rate for ABR decisions per draft-ramadan-moq-fec-00
+ * - Progressive quality upgrades (waits for stability)
+ * - Fast quality downgrades on congestion
+ */
+export class AdaptiveBitrateController {
+	private currentQualityIndex: number;
+	private history: { timestamp: number; bytesReceived: number; packetsLost: number }[] = [];
+	private readonly historyWindow = 10_000; // 10 second window
+	private readonly upgradeThreshold = 0.8; // 80% of target bitrate sustained
+	private readonly downgradeThreshold = 0.5; // 50% of target bitrate triggers downgrade
+	private readonly stabilityPeriod = 5_000; // Wait 5s before upgrading
+
+	private lastQualityChange = 0;
+	private onQualityChange?: (quality: QualityLevel) => void;
+
+	// FEC stats for effective loss rate calculation
+	private fecStats: FecStatsForAbr = {
+		rawLossRate: 0,
+		effectiveLossRate: 0,
+		recoveryRate: 1,
+		fecEnabled: false,
+	};
+
+	constructor(initialQuality?: QualityLevel) {
+		this.currentQualityIndex = initialQuality ? QUALITY_LEVELS.findIndex((q) => q.name === initialQuality.name) : 0;
+
+		if (this.currentQualityIndex < 0) this.currentQualityIndex = 0;
+	}
+
+	setCallback(callback: (quality: QualityLevel) => void) {
+		this.onQualityChange = callback;
+	}
+
+	getCurrentQuality(): QualityLevel {
+		return QUALITY_LEVELS[this.currentQualityIndex];
+	}
+
+	/**
+	 * Record network sample for bitrate adaptation
+	 *
+	 * @param bytesReceived - Bytes received in this sample
+	 * @param packetsLost - Packets lost (raw, before FEC recovery)
+	 */
+	recordSample(bytesReceived: number, packetsLost: number) {
+		const now = Date.now();
+
+		this.history.push({ timestamp: now, bytesReceived, packetsLost });
+
+		// Prune old samples
+		this.history = this.history.filter((s) => now - s.timestamp < this.historyWindow);
+
+		// Calculate metrics
+		const { measuredBitrate, lossRate: rawLossRate } = this.calculateMetrics();
+		const currentQuality = this.getCurrentQuality();
+
+		// Per draft-ramadan-moq-fec-00: Use effective loss rate after FEC for ABR decisions
+		// This allows FEC to mask burst losses without triggering unnecessary downgrades
+		const effectiveLossRate = this.fecStats.fecEnabled
+			? this.fecStats.effectiveLossRate
+			: rawLossRate;
+
+		// Decision logic
+		if (now - this.lastQualityChange < this.stabilityPeriod) {
+			return; // Wait for stability
+		}
+
+		// Check for downgrade - use effective loss rate (post-FEC)
+		// Only downgrade if FEC cannot recover the losses
+		if (effectiveLossRate > 0.05 || measuredBitrate < currentQuality.bitrate * this.downgradeThreshold) {
+			this.downgrade();
+			return;
+		}
+
+		// Check for upgrade (progressive increase) - use effective loss rate
+		if (
+			measuredBitrate > currentQuality.bitrate * this.upgradeThreshold &&
+			effectiveLossRate < 0.01 &&
+			this.currentQualityIndex < QUALITY_LEVELS.length - 1
+		) {
+			this.upgrade();
+		}
+	}
+
+	/**
+	 * Update FEC statistics for ABR decisions
+	 *
+	 * Per draft-ramadan-moq-fec-00, ABR should use the effective loss rate
+	 * (after FEC recovery) rather than raw transport loss rate.
+	 *
+	 * @param stats - FEC statistics from the FEC decoder
+	 */
+	setFecStats(stats: FecStatsForAbr) {
+		this.fecStats = stats;
+	}
+
+	/**
+	 * Get current FEC statistics
+	 */
+	getFecStats(): FecStatsForAbr {
+		return { ...this.fecStats };
+	}
+
+	private calculateMetrics() {
+		if (this.history.length < 2) {
+			return { measuredBitrate: 0, lossRate: 0 };
+		}
+
+		const totalBytes = this.history.reduce((sum, s) => sum + s.bytesReceived, 0);
+		const totalLost = this.history.reduce((sum, s) => sum + s.packetsLost, 0);
+		const duration = (this.history[this.history.length - 1].timestamp - this.history[0].timestamp) / 1000;
+
+		const measuredBitrate = duration > 0 ? (totalBytes * 8) / duration : 0;
+		const lossRate = totalLost / (this.history.length + totalLost);
+
+		return { measuredBitrate, lossRate };
+	}
+
+	private upgrade() {
+		if (this.currentQualityIndex >= QUALITY_LEVELS.length - 1) return;
+
+		this.currentQualityIndex++;
+		this.lastQualityChange = Date.now();
+
+		const newQuality = this.getCurrentQuality();
+		console.log(`[ABR] Upgrading to ${newQuality.name} (${newQuality.bitrate / 1_000_000}Mbps)`);
+
+		this.onQualityChange?.(newQuality);
+	}
+
+	private downgrade() {
+		if (this.currentQualityIndex <= 0) return;
+
+		this.currentQualityIndex--;
+		this.lastQualityChange = Date.now();
+
+		const newQuality = this.getCurrentQuality();
+		console.log(`[ABR] Downgrading to ${newQuality.name} (${newQuality.bitrate / 1_000_000}Mbps)`);
+
+		this.onQualityChange?.(newQuality);
+	}
+
+	/**
+	 * Force quality level (for testing)
+	 */
+	setQuality(name: string) {
+		const index = QUALITY_LEVELS.findIndex((q) => q.name === name);
+		if (index >= 0) {
+			this.currentQualityIndex = index;
+			this.lastQualityChange = Date.now();
+			this.onQualityChange?.(this.getCurrentQuality());
+		}
+	}
+
+	/**
+	 * Get current metrics including both raw and effective loss rates
+	 */
+	getMetrics(): {
+		measuredBitrate: number;
+		rawLossRate: number;
+		effectiveLossRate: number;
+		fecEnabled: boolean;
+		sampleCount: number;
+	} {
+		const { measuredBitrate, lossRate: rawLossRate } = this.calculateMetrics();
+		return {
+			measuredBitrate,
+			rawLossRate,
+			effectiveLossRate: this.fecStats.fecEnabled ? this.fecStats.effectiveLossRate : rawLossRate,
+			fecEnabled: this.fecStats.fecEnabled,
+			sampleCount: this.history.length,
+		};
+	}
+
+	/**
+	 * Reset history and start fresh
+	 */
+	reset() {
+		this.history = [];
+		this.lastQualityChange = 0;
+	}
+}