Data streams v2

.changeset/slick-geese-happen.md

@@ -0,0 +1,5 @@
+---
+'livekit-client': patch
+---
+
+Add support for data streams v2

examples/data-stream-benchmark/README.md

@@ -0,0 +1,42 @@
+# Data Stream Benchmark
+
+Measures the end-to-end latency of LiveKit **v2 data streams** across a grid of network conditions
+(X axis) and payload sizes (Y axis).
+
+Two participants (`bench-sender` and `bench-receiver`) join a shared room in the same browser tab.
+For each box in the grid the sender sends a fixed number of data streams (default 10) of random,
+realistic JSON data to the receiver. Each stream header carries a `checksum` (XOR of the payload
+bytes) and a `sendTs` timestamp; the receiver verifies the checksum and computes the end-to-end
+latency. Each cell shows the average latency over the checksum-matching streams, or `N/A`.
+
+## Running
+
+1. Create `.env.local` with `LIVEKIT_API_KEY`, `LIVEKIT_API_SECRET`, and `LIVEKIT_URL`.
+2. Install dependencies: `pnpm install`
+3. Start the server: `pnpm dev`
+4. Open the local URL (typically http://localhost:5173).
+5. Click **Connect**, then **Run Benchmark**. Click **Disconnect** when done.
+
+## Network conditioning (macOS only)
+
+The **X axis** (Edge / 3G / LTE / Wi-Fi / None) is driven by the macOS **Network Link Conditioner**.
+The server (`api.ts`) toggles it via `osascript` through `POST /api/network-condition`.
+
+Prerequisites:
+
+- The **Network Link Conditioner** preference pane must be installed
+  (`/Library/PreferencePanes/Network Link Conditioner.prefPane`, from Apple's "Additional Tools for
+  Xcode").
+- The process running `vite`/node needs macOS **Accessibility** permission (System Settings →
+  Privacy & Security → Accessibility) so it can drive System Settings.
+- The preset names must match the conditioner's menu exactly: `Edge`, `3G`, `LTE`, `Wi-Fi`.
+
+The benchmark always resets the conditioner to **off** when it finishes, errors, or you disconnect.
+
+## Notes
+
+- The v2 single-packet (inline) optimization only changes behavior for payloads under the ~15 KB
+  header budget (10 B–10 KB); 100 KB and 1 MB are multi-packet regardless.
+- `Edge`/`3G` × `1 MB` can be slow; each send has a 60 s timeout (`SEND_TIMEOUT_MS` in
+  `benchmark.ts`) and slow boxes show `N/A`. Repeat count and timeout are constants at the top of
+  `benchmark.ts`.

examples/data-stream-benchmark/api.ts

@@ -0,0 +1,121 @@
+import { exec } from 'child_process';
+import dotenv from 'dotenv';
+import express from 'express';
+import { AccessToken } from 'livekit-server-sdk';
+import { promisify } from 'util';
+import type { Express } from 'express';
+
+dotenv.config({ path: '.env.local' });
+
+const execAsync = promisify(exec);
+
+const LIVEKIT_API_KEY = process.env.LIVEKIT_API_KEY;
+const LIVEKIT_API_SECRET = process.env.LIVEKIT_API_SECRET;
+const LIVEKIT_URL = process.env.LIVEKIT_URL;
+
+/** Network Link Conditioner presets we allow the client to request. */
+const ALLOWED_PRESETS = ['Edge', '3G', 'LTE', 'Wi-Fi', 'Very Bad Network'];
+
+const app = express();
+app.use(express.json());
+
+app.post('/api/get-token', async (req, res) => {
+  const { identity, roomName } = req.body;
+
+  if (!LIVEKIT_API_KEY || !LIVEKIT_API_SECRET) {
+    res.status(500).json({ error: 'Server misconfigured' });
+    return;
+  }
+
+  const token = new AccessToken(LIVEKIT_API_KEY, LIVEKIT_API_SECRET, {
+    identity,
+  });
+  token.addGrant({
+    room: roomName,
+    roomJoin: true,
+    canPublish: true,
+    canSubscribe: true,
+  });
+
+  res.json({
+    token: await token.toJwt(),
+    url: LIVEKIT_URL,
+  });
+});
+
+/**
+ * Enables the macOS Network Link Conditioner at the given preset. The preset name is read from the
+ * `mode` environment variable via `system attribute "mode"`.
+ */
+const ENABLE_SCRIPT = `osascript <<'EOF'
+set mode to system attribute "mode"
+do shell script "open '/Library/PreferencePanes/Network Link Conditioner.prefPane'"
+delay 2
+tell application "System Settings" to activate
+tell application "System Events"
+    tell process "System Settings"
+        tell window "Network Link Conditioner"
+            tell scroll area 1 of group 3 of splitter group 1 of group 1
+                tell group 1
+                    click pop up button 1
+                    delay 0.3
+                    click menu item mode of menu 1 of pop up button 1
+                end tell
+                delay 0.3
+                click button "ON"
+            end tell
+        end tell
+    end tell
+end tell
+EOF`;
+
+/** Disables the macOS Network Link Conditioner, returning to the host network speed. */
+const DISABLE_SCRIPT = `osascript <<'EOF'
+do shell script "open '/Library/PreferencePanes/Network Link Conditioner.prefPane'"
+delay 2
+tell application "System Settings" to activate
+tell application "System Events"
+    tell process "System Settings"
+        tell window "Network Link Conditioner"
+            tell scroll area 1 of group 3 of splitter group 1 of group 1
+                click button "OFF"
+            end tell
+        end tell
+    end tell
+end tell
+EOF`;
+
+app.post('/api/network-condition', async (req, res) => {
+  const { preset } = req.body as { preset?: string };
+
+  if (preset === 'off') {
+    try {
+      await execAsync(DISABLE_SCRIPT, { timeout: 30_000 });
+      res.json({ ok: true, preset: 'off' });
+    } catch (error) {
+      res.status(500).json({ error: `Failed to disable network conditioner: ${String(error)}` });
+    }
+    return;
+  }
+
+  if (!preset || !ALLOWED_PRESETS.includes(preset)) {
+    res
+      .status(400)
+      .json({ error: `Invalid preset "${preset}". Allowed: ${ALLOWED_PRESETS.join(', ')}, off` });
+    return;
+  }
+
+  try {
+    await execAsync(ENABLE_SCRIPT, {
+      timeout: 30_000,
+      env: { ...process.env, mode: preset },
+    });
+    res.json({ ok: true, preset });
+  } catch (error) {
+    res
+      .status(500)
+      .json({ error: `Failed to set network conditioner to ${preset}: ${String(error)}` });
+  }
+});
+
+export const handler: Express = app;