voxa_rtc_engine 0.1.0

Agora-API-compatible real-time voice/video SDK for Flutter. Drop-in replacement for agora_rtc_engine (compat line: 6.x, pinned to 6.6.3), powered by a LiveKit-based media engine.

voxa_rtc_engine

Agora-API-compatible RTC engine for Flutter, powered by LiveKit. Compat pin: agora_rtc_engine 6.6.3. Workspace plan: ../plan-docs-tracks/plan.md.

Migration

dependencies:
  voxa_rtc_engine: ^0.1.0   # was: agora_rtc_engine: ^6.6.3

import 'package:voxa_rtc_engine/voxa_rtc_engine.dart'; // was: agora_rtc_engine
// One Voxa-specific addition, at app startup:
import 'package:voxa_rtc_engine/voxa.dart';
VoxaRtc.serverUrl = 'wss://<your-voxa-gateway>';

Everything else — createAgoraRtcEngine(), RtcEngine, joinChannel, RtcEngineEventHandler, AgoraVideoView — keeps Agora's exact names and signatures.

Architecture

lib/
├── voxa_rtc_engine.dart      # Barrel, mirrors agora_rtc_engine.dart exports
├── voxa.dart                 # VoxaRtc.serverUrl + transport DI (tests)
└── src/
    ├── agora_*.dart          # API surface derived verbatim from upstream
    │                         #   (MIT, see THIRD_PARTY_LICENSES; keep
    │                         #   byte-identical — verified in CI)
    ├── impl/
    │   ├── agora_rtc_engine_impl.dart   # Tier-1 state machine
    │   ├── event_translator.dart        # transport events → Agora callbacks
    │   └── *_impl.dart                  # view/controller impls & Tier-3 stubs
    └── transport/
        ├── transport.dart               # media-engine-agnostic interface
        └── livekit_adapter.dart         # ONLY file importing livekit_client

Status (Phase 1, in progress)

Implemented (unit-tested against the golden ordering contract, test/): engine lifecycle, join/leave with Agora callback sequences, error codes (-2/-3/-7/-17/-102/-109/-110), idempotency quirks (double-join, leave-before- join, mute-before-join queuing), int uid semantics incl. 0 = auto-assign, local/remote mute, roles (audience/broadcaster), camera switch, speakerphone routing, remote media state callbacks, AgoraVideoView rendering LiveKit tracks.

Known gaps: pre-join camera preview (startPreview before joinChannel shows black until join); token renewal is a no-op until the Compat Gateway lands; string user accounts; everything Tier-2/3 throws AgoraRtcException(-4, errNotSupported).

The golden sequences in test/engine_lifecycle_test.dart encode Agora's documented contract; they must be re-validated against transcripts recorded from a real Agora app before beta (plan §7.1).

Verify

flutter analyze   # must be clean
flutter test      # 26 tests: surface parity + golden ordering + idempotency