[FEAT] Unify WebRTC streaming on LiveKit and remove aiortc

[lzx1413]

Description

This PR makes LiveKit the single WebRTC streaming transport for TeleFuser.

It adds LiveKit-backed session APIs, admission scheduling, scoped token issuance, room workers, media bridging, reliable control messages, and browser reconnection support for both ServerPushService and BidirectionalService.

It also removes the legacy direct-aiortc transport, SDP endpoints, browser clients, unsupported WebRTC benchmark assets, and duplicate streaming paths. The documentation now includes a complete coturn + LiveKit + TeleFuser + browser workflow.

Motivation

TeleFuser previously maintained two WebRTC implementations with different session, control, media, and cache-lifecycle behavior. The direct aiortc path was difficult to operate reliably and did not provide the room lifecycle, reconnection handling, and transport management required by long-running interactive generation.

Using LiveKit as the single transport provides:

• Stable room and participant lifecycle management.
• Reliable control and status messages.
• Browser reconnection support.
• Centralized media transport through an SFU.
• Clear ownership between one LiveKit room, one model worker, and one pipeline session.
• A unified API for server-push and bidirectional pipelines.
• Consistent cache cleanup and session admission behavior.

Type of Change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Performance improvement
• Code refactoring
• Documentation update
• Other (please describe):

Changes Made

• Added the LiveKit streaming runtime:

  • LiveKit configuration and CLI options.
  • Session registry and admission scheduler.
  • Scoped controller, viewer, admin, and worker tokens.
  • Room workers and worker-pool lifecycle management.
  • Video/audio media bridging.
  • Reliable tf.control, tf.status, and tf.metrics data topics.
  • Session creation, inspection, token issuance, deletion, and health APIs.

• Unified telefuser stream-serve on LiveKit:

  • Supports both ServerPushService and BidirectionalService.
  • Uses /v1/stream/sessions as the canonical session API.
  • Adds worker capacity, queue, timeout, and GPU-group configuration.
  • Moves the LiveKit Python SDKs into the base dependencies.

• Added the maintained browser control Demo:

  • LiveKit room connection and video playback.
  • Keyboard and on-page camera controls.
  • Reliable control-state delivery.
  • Streaming status and latency telemetry.
  • Forced TCP TURN relay for VS Code Remote SSH development.
  • Complete session cleanup and reconnect handling.

• Improved LingBot real-time streaming:

  • Preserved actor-stage overlap for encode, DiT, and decode.
  • Separated queue, pipeline, output-cadence, and applied-control latency.
  • Unified LingBot-World v2 camera intrinsics with offline inference.
  • Rebalanced translation control normalization.
  • Improved stop handling and actor-owned cache cleanup.

• Removed the legacy direct WebRTC implementation:

  • Removed the aiortc dependency.
  • Removed /v1/stream/webrtc/* SDP routes.
  • Removed the direct aiortc session manager and media tracks.
  • Removed the old WebRTC browser clients and Streamlit Web UI.
  • Removed obsolete direct-WebRTC integration tests.

• Removed unsupported streaming benchmark assets:

  • Removed the old aiortc AIPerf adapter configs and scripts.
  • Documented that a validated LiveKit benchmark adapter is required before stream benchmarks are restored.
  • Kept target compute metrics separate from client delivery metrics.

• Updated documentation:

  • Root English and Chinese READMEs.
  • English and Chinese stream-server guides.
  • Service, scheduler, benchmark, index, LingBot, and example documentation.
  • Complete four-service startup, verification, troubleshooting, port-forwarding, and shutdown instructions.

• Updated SageAttention loading:

  • Uses the standalone sageattention package.
  • No longer attempts to load SageAttention from tf-kernel.

Breaking Changes

• telefuser stream-serve now uses LiveKit exclusively.
• A LiveKit Cloud project or self-hosted LiveKit Server is required.
• The direct /v1/stream/webrtc/* SDP API has been removed.
• The aiortc dependency and implementation have been removed.
• Legacy WebRTC browser demos have been replaced by:
  • examples/stream_server/livekit_bidirectional_demo.py
• Existing clients must migrate to /v1/stream/sessions and join the returned LiveKit room.
• Existing direct-WebRTC AIPerf stream benchmarks are no longer available.

Testing

• Unit tests pass for the changed service and LingBot areas
• Manual testing performed
• Benchmarks updated where applicable

Test commands:

# LiveKit runtime
.venv/bin/python -m pytest \
  tests/unit/service/livekit \
  --ignore=tests/unit/service/livekit/test_demo.py \
  -q
# 42 passed

# Browser Demo
.venv/bin/python -m pytest \
  tests/unit/service/livekit/test_demo.py \
  tests/unit/pipelines/lingbot_world_fast/test_stream_example.py \
  -q
# 7 passed

# LingBot session and control behavior
.venv/bin/python -m pytest \
  tests/unit/pipelines/lingbot_world_fast/test_service_action_loop.py \
  tests/unit/pipelines/lingbot_world_fast/test_service_metrics.py \
  tests/unit/pipelines/lingbot_world_v2/test_service.py \
  -q
# 52 passed

# Complete affected service and LingBot test set
.venv/bin/python -m pytest \
  tests/unit/service \
  tests/unit/pipelines/lingbot_world_fast \
  tests/unit/pipelines/lingbot_world_v2 \
  -q
# 289 passed, 1 unrelated Pillow deprecation warning

# Attention backend
.venv/bin/python -m pytest \
  tests/unit/ops/test_attention_backends.py \
  -q
# 1 passed

# Documentation
.venv/bin/mkdocs build --strict \
  --site-dir /tmp/telefuser-docs-livekit

# Diff validation
git diff --check main..livekit

Pre-commit ruff and ruff-format hooks passed for all code commits.

Manual end-to-end validation was performed with:

• 4 × NVIDIA H100 GPUs.
• A local coturn TCP relay.
• LiveKit Server in development mode.
• The LingBot-World v2 four-GPU stream service.
• The bundled browser control Demo.
• Forced TURN relay transport.
• Camera control sent through tf.control.

The client successfully received an 832 × 464 video frame and status messages covering control application, prompt encoding, runtime allocation, denoising, VAE decoding, and chunk delivery. Session cleanup returned the worker to idle and released all session caches.

Checklist

• Code follows the project's coding standards (ruff)
• Pre-commit hooks pass for the changed code
• Affected unit tests pass
• New tests added for new functionality
• Documentation updated (README, CLAUDE.md, docstrings)
• Commit messages are clear and descriptive
• PR title follows the convention: [TYPE] Brief description
• Full repository test suite executed with pytest tests/
• pre-commit run --all-files executed

Related Issues

N/A

Additional Notes

The checked-in browser Demo intentionally forces TCP TURN relay using development credentials so it works through VS Code Remote SSH port forwarding. These credentials, loopback addresses, disabled TURN TLS, and --allow-loopback-peers must not be used in production.

The current runtime supports one in-process model worker per service process. Additional workers should use separate service processes until process-worker isolation is implemented.

The removed AIPerf stream benchmark assets depended on the old direct-WebRTC transport. A LiveKit-aware client adapter should be implemented and validated before those benchmarks are restored.

GPU Architecture Support

No CUDA or Triton kernels are added or modified by this PR.

• SM80 (Ampere, Ada Lovelace)
• SM90 (Hopper H100)
• SM100+ (Blackwell)

The end-to-end LingBot streaming workflow was manually validated on four NVIDIA H100 GPUs.

Performance Impact

This PR does not claim a model-compute speedup.

The LingBot actor scheduler continues to overlap encode, DiT, and decode stages. Runtime telemetry now separates:

• Output cadence.
• Pipeline residence time.
• Queue delay.
• Applied-control latency.
• Per-stage execution time.

The transport migration is expected to improve connection lifecycle and browser stability. Formal delivery-latency and throughput comparisons require a future LiveKit-aware AIPerf adapter.