voxa_rtc_engine 0.2.6

Drop-in, Agora-API-compatible RTC SDK for Flutter on self-hosted infrastructure: same classes, signatures, error codes, and callback ordering as agora_rtc_engine 6.x, over a LiveKit-based media engine.

voxa_rtc_engine

A drop-in, Agora-API-compatible RTC engine for Flutter — on infrastructure you own.

VoxaRTC replicates the public API of agora_rtc_engine (compat line 6.x, pinned to 6.6.3) on top of a self-hosted, LiveKit-based media backend. Same classes, same method signatures, same enums, same error codes, same callback ordering — so an existing Agora Flutter app migrates without rewriting business logic.

⚠️ Early development. The Tier-1/Tier-2 API surface below is implemented and behavior-verified; everything else fails gracefully. Not yet recommended for production traffic.

Migration from Agora

1. Swap the dependency:

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

2. Swap the import (find & replace):

// before
import 'package:agora_rtc_engine/agora_rtc_engine.dart';
// after
import 'package:voxa_rtc_engine/voxa_rtc_engine.dart';

3. Point the SDK at your VoxaRTC gateway — the only new line:

import 'package:voxa_rtc_engine/voxa.dart';

void main() {
  VoxaRtc.serverUrl = 'https://gate.example.com';
  runApp(const MyApp());
}

Everything else stays: createAgoraRtcEngine(), RtcEngine, joinChannel(), RtcEngineEventHandler, AgoraVideoView, and your existing tokens — the gateway verifies both Agora token formats (legacy 006 from agora-access-token and 007 AccessToken2), so most token servers migrate by changing credentials only. Drop-in voxa-token libraries for Node and Go are available if you'd rather swap the library.

Android permissions

The package's Android module declares the RTC permissions (CAMERA, RECORD_AUDIO, MODIFY_AUDIO_SETTINGS, INTERNET, ACCESS_NETWORK_STATE, Bluetooth), so they merge into your app exactly as agora_rtc_engine does — no manifest edit needed when migrating. Your app still requests them at runtime as before (e.g. with permission_handler).

On iOS/macOS, add the usual usage descriptions to Info.plist (NSCameraUsageDescription, NSMicrophoneUsageDescription) — same as with Agora.

Known dependency conflict: wakelock_plus

Apps that use wakelock_plus (common in live-streaming apps) will hit a version-solve failure: our media engine pulls device_info_plus 12.x, which pins win32 5.x, while wakelock_plus needs win32 6.x. Lift device_info_plus — 13.x uses win32 6.x and satisfies both:

dependency_overrides:
  device_info_plus: ^13.2.0

Quick example

final engine = createAgoraRtcEngine();
await engine.initialize(const RtcEngineContext(
  appId: '<your VoxaRTC app id>',
  channelProfile: ChannelProfileType.channelProfileLiveBroadcasting,
));

engine.registerEventHandler(RtcEngineEventHandler(
  onJoinChannelSuccess: (connection, elapsed) => print('joined'),
  onUserJoined: (connection, remoteUid, elapsed) => print('peer $remoteUid'),
));

await engine.setClientRole(role: ClientRoleType.clientRoleBroadcaster);
await engine.enableVideo();
await engine.startPreview();
await engine.joinChannel(
  token: token, channelId: 'demo', uid: 0,
  options: const ChannelMediaOptions(),
);

// Rendering — unchanged from Agora:
AgoraVideoView(
  controller: VideoViewController(
    rtcEngine: engine,
    canvas: const VideoCanvas(uid: 0),
  ),
);

What's implemented

Channel & lifecycle — initialize, release, joinChannel, leaveChannel, renewToken, connection-state machine, auto-reconnect (onRejoinChannelSuccess), token lifecycle (onTokenPrivilegeWillExpire, onRequestToken).

Media — enable/disable audio & video, local/remote mute (incl. muteAllRemote*), roles (broadcaster/audience) via setClientRole or updateChannelMediaOptions, switchCamera, speakerphone routing, pre-join startPreview, setVideoEncoderConfiguration, dual-stream/simulcast (enableDualStreamMode, setRemoteVideoStreamType), screen share, volume indication, in-call stats (onRtcStats, onNetworkQuality).

Behavioral compatibility — callback order, error codes, and idempotency quirks (double-join, mute-before-join, uid 0 auto-assign…) are verified against recordings from the real Agora service via a golden-transcript test harness, not just written from documentation.

Not supported at this stage (calls return AgoraRtcException(-4, errNotSupported) instead of crashing): media player, spatial audio, channel media relay, raw frame observers, RTM.

Platform	Status
Android	✅ tested on devices
macOS	✅ tested
iOS	🟡 expected to work (LiveKit-based), not yet CI-verified
Web	❌ not yet

Backend required

This SDK talks to a self-hosted VoxaRTC backend: a Compat Gateway (Agora token verification → media-server credentials) in front of a LiveKit cluster. Deployment configs, the gateway, server-side token builders, and the parity harness live in the VoxaRTC repository.

License

MIT © Zaman Sheikh (VoxaRTC). Portions of the API-surface declarations are derived from agora_rtc_engine (MIT) — see THIRD_PARTY_LICENSES. "Agora" is a trademark of Agora, Inc.; this project is an independent, API-compatible implementation and is not affiliated with or endorsed by Agora, Inc.