Streaming Stability Improvements (February 2026)

Commit: 14a1e1bbe558c0626a78f3d6e93197eb2e5d1a96
Author: Shaw (@lalalune)

Summary

Improved RTMP streaming reliability and WebGPU renderer initialization through increased stability thresholds, soft CDP recovery, and best-effort GPU limit negotiation.

Changes

1. CDP Stall Threshold

Increased: 2 → 4 intervals (60s → 120s before restart)

// packages/server/src/streaming/browser-capture.ts
const CDP_STALL_THRESHOLD = 4;  // Was: 2

Rationale: 2-interval threshold caused false restarts during legitimate pauses (loading screens, scene transitions). 4 intervals provides better tolerance for temporary stalls while still detecting real hangs. Impact:

Fewer false restarts
More stable long-running streams
Better handling of scene complexity spikes

2. Soft CDP Recovery

Added: Restart screencast without browser/FFmpeg teardown

// Try soft recovery first (no stream gap)
await this.restartScreencast();

// Only do full restart if soft recovery fails
if (stillStalled) {
  await this.fullRestart();
}

Benefits:

No stream interruption during recovery
Faster recovery (no browser restart overhead)
Preserves browser state (cookies, localStorage)

Fallback: Full restart if soft recovery fails after 3 attempts

3. FFmpeg Restart Attempts

Increased: 5 → 8 attempts

const MAX_RESTART_ATTEMPTS = 8;  // Was: 5

Rationale: FFmpeg can fail transiently due to:

Network hiccups
RTMP server temporary unavailability
Encoder initialization delays

8 attempts provides better resilience without infinite retry loops.

4. Capture Recovery Max Failures

Increased: 2 → 4 failures before full teardown

const CAPTURE_RECOVERY_MAX_FAILURES = 4;  // Was: 2

Rationale: Allows more soft recovery attempts before giving up and doing full browser/FFmpeg restart.

5. WebGPU Best-Effort Initialization

Added: Retry with default limits if GPU rejects custom limits

// Try with custom limits first
try {
  const adapter = await navigator.gpu.requestAdapter();
  const device = await adapter.requestDevice({
    requiredLimits: {
      maxTextureArrayLayers: 2048  // Custom limit
    }
  });
} catch (error) {
  // Retry with default limits (no requiredLimits)
  const device = await adapter.requestDevice();
}

Rationale: Some GPUs reject custom limits even if they support the feature. Best-effort approach tries custom limits first, falls back to defaults if rejected. Result: Always WebGPU (never falls back to WebGL in this path).

6. WebGL Fallback for Streaming

Added: Automatic WebGL fallback when WebGPU fails or is disabled

// packages/shared/src/utils/rendering/RendererFactory.ts
if (forceWebGL || disableWebGPU || !navigator.gpu) {
  return createWebGLRenderer();
}

try {
  return await createWebGPURenderer();
} catch (error) {
  console.warn('WebGPU failed, falling back to WebGL:', error);
  return createWebGLRenderer();
}

Query Params:

?page=stream&forceWebGL=1 - Force WebGL
?page=stream&disableWebGPU=1 - Disable WebGPU

Environment Variable:

STREAM_CAPTURE_DISABLE_WEBGPU=true

Use Cases:

Docker containers (WebGPU often unavailable)
Vast.ai instances (GPU passthrough issues)
Headless browsers (software rendering)

7. Swiftshader ANGLE Backend

Updated: ecosystem.config.cjs to use swiftshader for reliable software rendering

// ecosystem.config.cjs
env: {
  STREAM_CAPTURE_DISABLE_WEBGPU: 'true',
  ANGLE_DEFAULT_PLATFORM: 'swiftshader',
  // ... other vars
}

Rationale: Swiftshader provides reliable software rendering when GPU is unavailable or unstable.

Configuration

Environment Variables

packages/server/.env:

# CDP stall detection (intervals before restart)
CDP_STALL_THRESHOLD=4                    # Default: 4 (120s)

# FFmpeg restart attempts
FFMPEG_MAX_RESTART_ATTEMPTS=8            # Default: 8

# Capture recovery failures before full teardown
CAPTURE_RECOVERY_MAX_FAILURES=4          # Default: 4

# Disable WebGPU for streaming (use WebGL fallback)
STREAM_CAPTURE_DISABLE_WEBGPU=false      # Default: false

Tuning Guide

Aggressive (fast recovery, more restarts):

CDP_STALL_THRESHOLD=2
FFMPEG_MAX_RESTART_ATTEMPTS=5
CAPTURE_RECOVERY_MAX_FAILURES=2

Conservative (fewer restarts, longer tolerance):

CDP_STALL_THRESHOLD=6
FFMPEG_MAX_RESTART_ATTEMPTS=12
CAPTURE_RECOVERY_MAX_FAILURES=6

Headless/Docker (reliable software rendering):

STREAM_CAPTURE_DISABLE_WEBGPU=true
CDP_STALL_THRESHOLD=6
FFMPEG_MAX_RESTART_ATTEMPTS=10

Debugging

Check CDP Stall Detection

# In server logs, look for:
[StreamCapture] CDP stalled for 4 intervals, attempting soft recovery
[StreamCapture] Soft recovery successful
# or
[StreamCapture] Soft recovery failed, attempting full restart

Check FFmpeg Restart Attempts

# In server logs, look for:
[StreamCapture] FFmpeg restart attempt 3/8
[StreamCapture] FFmpeg restarted successfully
# or
[StreamCapture] FFmpeg restart failed after 8 attempts, giving up

Check WebGPU Initialization

# In browser console (streaming page):
WebGPU initialized with custom limits
# or
WebGPU initialization failed, retrying with default limits
# or
WebGPU unavailable, using WebGL fallback

Monitor Stream Health

# Check RTMP connection
ffprobe rtmp://your-server/live/stream

# Check HLS playlist
curl http://your-server/live/stream.m3u8

# Monitor FFmpeg logs
tail -f /path/to/ffmpeg.log

Performance Impact

CDP Recovery

Soft Recovery:

Time: ~2-5 seconds
Stream gap: None (screencast restarts, FFmpeg continues)
Browser state: Preserved

Full Restart:

Time: ~10-20 seconds
Stream gap: 5-10 seconds (browser + FFmpeg restart)
Browser state: Lost (fresh browser instance)

WebGPU vs WebGL

WebGPU (preferred):

Better performance
Lower CPU usage
More features (compute shaders)

WebGL (fallback):

More compatible (works in Docker/headless)
Slightly higher CPU usage
Proven reliability with software rendering

Known Issues

WebGPU Fails in Docker

Symptom: WebGPU initialization fails in Docker containers Cause: GPU passthrough not configured or unavailable Solution: Use WebGL fallback:

STREAM_CAPTURE_DISABLE_WEBGPU=true

CDP Stalls During Scene Transitions

Symptom: CDP stalls during arena transitions or complex scenes Cause: Browser busy with rendering, doesn’t respond to CDP in time Solution: Increase threshold:

CDP_STALL_THRESHOLD=6  # 180s tolerance

FFmpeg Crashes on Startup

Symptom: FFmpeg fails to start, restarts repeatedly Cause: RTMP server unavailable or invalid stream key Solution:

Verify RTMP server is running
Check stream key is correct

Test with local nginx-rtmp:

docker run -d -p 1935:1935 tiangolo/nginx-rtmp

Testing

Local RTMP Test

# Start local RTMP server
docker run -d -p 1935:1935 tiangolo/nginx-rtmp

# Configure server
export CUSTOM_RTMP_URL=rtmp://localhost:1935/live
export CUSTOM_STREAM_KEY=test

# Start streaming
bun run stream:test

# View stream
ffplay rtmp://localhost:1935/live/test

Headless Rendering Test

# Force WebGL fallback
export STREAM_CAPTURE_DISABLE_WEBGPU=true

# Start streaming
bun run stream:rtmp

# Verify WebGL is used (check logs)
grep "WebGL" logs/stream-capture.log

Stability Test

# Run stream for extended period
bun run stream:rtmp

# Monitor restart count
grep "restart attempt" logs/stream-capture.log | wc -l

# Should be low (<5 restarts per hour)

Modified

packages/server/src/streaming/browser-capture.ts - CDP stall detection
packages/server/src/streaming/stream-capture.ts - FFmpeg restart logic
packages/shared/src/utils/rendering/RendererFactory.ts - WebGPU/WebGL fallback
ecosystem.config.cjs - Swiftshader ANGLE backend

Configuration

packages/server/.env.example - Environment variable documentation
.github/workflows/deploy-vast.yml - CI/CD deployment

References

Chrome DevTools Protocol - CDP documentation
FFmpeg Documentation - FFmpeg reference
WebGPU Specification - WebGPU API
ANGLE Project - OpenGL ES implementation

Configuration

Operations

Streaming stability feb2026

Streaming Stability Improvements (February 2026)

Summary

Changes

1. CDP Stall Threshold

2. Soft CDP Recovery

3. FFmpeg Restart Attempts

4. Capture Recovery Max Failures

5. WebGPU Best-Effort Initialization

6. WebGL Fallback for Streaming

7. Swiftshader ANGLE Backend

Configuration

Environment Variables

Tuning Guide

Debugging

Check CDP Stall Detection

Check FFmpeg Restart Attempts

Check WebGPU Initialization

Monitor Stream Health

Performance Impact

CDP Recovery

WebGPU vs WebGL

Known Issues

WebGPU Fails in Docker

CDP Stalls During Scene Transitions

FFmpeg Crashes on Startup

Testing

Local RTMP Test

Headless Rendering Test

Stability Test

Modified

Configuration

References

​Streaming Stability Improvements (February 2026)

​Summary

​Changes

​1. CDP Stall Threshold

​2. Soft CDP Recovery

​3. FFmpeg Restart Attempts

​4. Capture Recovery Max Failures

​5. WebGPU Best-Effort Initialization

​6. WebGL Fallback for Streaming

​7. Swiftshader ANGLE Backend

​Configuration

​Environment Variables

​Tuning Guide

​Debugging

​Check CDP Stall Detection

​Check FFmpeg Restart Attempts

​Check WebGPU Initialization

​Monitor Stream Health

​Performance Impact

​CDP Recovery

​WebGPU vs WebGL

​Known Issues

​WebGPU Fails in Docker

​CDP Stalls During Scene Transitions

​FFmpeg Crashes on Startup

​Testing

​Local RTMP Test

​Headless Rendering Test

​Stability Test

​Related Files

​Modified

​Configuration

​References

Streaming Stability Improvements (February 2026)

Summary

Changes

1. CDP Stall Threshold

2. Soft CDP Recovery

3. FFmpeg Restart Attempts

4. Capture Recovery Max Failures

5. WebGPU Best-Effort Initialization

6. WebGL Fallback for Streaming

7. Swiftshader ANGLE Backend

Configuration

Environment Variables

Tuning Guide

Debugging

Check CDP Stall Detection

Check FFmpeg Restart Attempts

Check WebGPU Initialization

Monitor Stream Health

Performance Impact

CDP Recovery

WebGPU vs WebGL

Known Issues

WebGPU Fails in Docker

CDP Stalls During Scene Transitions

FFmpeg Crashes on Startup

Testing

Local RTMP Test

Headless Rendering Test

Stability Test

Related Files

Modified

Configuration

References