nimeet 文档中心
English

Flutter 快速开始与功能指南

Flutter:前置条件、安装、Token、加入频道、发布订阅、事件、错误处理与排障;接口名与签名在构建时取自公开 SDK 接口定义。

接口小节由公开 SDK 接口定义生成

版本 v1.1.0 · 更新于 2026-10-26 · 修订 1

Flutter 端是 Dart 语言的 RtcEngine 形状(与 Android/iOS 同构):RtcEngine + RtcEngineEventHandler,返回值用 Future 包装。

前置条件

  • Flutter 3.22+、Dart 3.4+。
  • 各平台原生权限:Android 的 CAMERA/RECORD_AUDIO,iOS 的 NSCameraUsageDescription/NSMicrophoneUsageDescription。
  • 已拿到 appId 与 Token 服务(见 控制台开通服务与获取凭证)。

安装

yaml
# pubspec.yaml —— 本地路径依赖
dependencies:
  nimeet_rtc:
    path: ../ni-meet/sdk/flutter

获取 Token

Flutter 客户端不能持有 customerSecret;Token 由你的后端签发,Flutter 侧通过 TokenProvider 注入:

dart
final provider = FallbackTokenProvider([
  CallbackTokenProvider((channel, uid, role) => authApi.fetchRtcToken(channel, uid, role)),
  StaticTokenProvider(Platform.environment['NIMEET_TEST_TOKEN'] ?? ''),
]);

加入频道

dart
import 'package:nimeet_rtc/nimeet_rtc.dart';

class MeetingController extends RtcEngineEventHandler {
  late final RtcEngine engine;

  Future<void> start(String appId, String token) async {
    engine = await RtcEngine.create(RtcEngineConfig(appId: appId));
    engine.registerEventHandler(this);

    await engine.setChannelProfile(ChannelProfileType.channelProfileLiveBroadcasting);
    await engine.enableVideo();
    await engine.setupLocalVideo(const VideoCanvas(uid: 0));
    await engine.startPreview();

    await engine.joinChannel(
      token: token,
      channelId: 'weekly-sync',
      uid: 10001,
      options: const ChannelMediaOptions(clientRoleType: ClientRoleType.clientRoleBroadcaster),
    );
  }

  @override
  void onJoinChannelSuccess(RtcConnection connection, int elapsed) {
    // 入会成功
  }

  @override
  void onUserJoined(RtcConnection connection, int remoteUid, int elapsed) {
    // 远端用户加入
  }

  @override
  void onUserOffline(RtcConnection connection, int remoteUid, UserOfflineReasonType reason) {
    // 远端用户离开
  }

  @override
  void onTokenPrivilegeWillExpire(String token) {
    // 续期后调用 engine.renewToken(newToken)
  }
}

发布与订阅

dart
await engine.muteLocalAudioStream(true);   // 静音麦克风
await engine.muteLocalVideoStream(true);   // 关本地画面
await engine.enableLocalVideo(false);      // 停止采集
await engine.updateChannelMediaOptions(options);

屏幕共享:getScreenCaptureSources() 枚举源 → startScreenCapture(...);停止用 stopScreenCapture()。

事件

RtcEngineEventHandler 是回调类,覆盖 onJoinChannelSuccess、onUserJoined、onUserOffline、 onFirstRemoteVideoDecoded、onTokenPrivilegeWillExpire、onError、onConnectionStateChanged 等。 Flutter 回调默认回到主 isolate,可以直接 setState。

错误处理

  • Future 失败会抛 RtcException(携带 code/sdkCode/message/retryable);
  • 异步错误走 onError 回调;
  • 未实现能力抛 -4(ERR_NOT_SUPPORTED)。

排障

现象原因处理
iOS 构建失败Pod 未安装 / 平台最低版本不满足cd ios && pod install,提升 platform :ios
安卓黑屏未申请运行时权限宿主 App 主动请求 CAMERA/RECORD_AUDIO
热重载后回调丢失handler 被重建在 initState 注册、dispose 反注册
编译期 MissingPluginException原生端未注册插件全量重启(flutter run 而不是热重载)
Token 过期后无法恢复未处理 onTokenPrivilegeWillExpire续期并 renewToken

下一步

平台信息

项值
平台Flutter
语言Dart
SDK 包nimeet_rtc
接口版本6.6.4
兼容参考声网 flutter 端 API

本端公开接口与声网 flutter 端 API 对齐;安装与运行要求见上面前置条件。

可用性

该端 SDK:正式可用。本页代码片段使用公开 API;运行时的能力边界以实际发布的 SDK 包为准。

加入频道链路

下列方法名、参数类型与返回值与同端 API 参考一致。一个平台若有多个重载,这里展示最常用的那一个;完整重载见同端 API 参考页。

步骤接口方法重载数
订阅远端媒体BaseSpatialAudioEnginemuteRemoteAudioStream1
创建实例 / 初始化LocalSpatialAudioEngineinitialize1
续期 TokenMusicContentCenterrenewToken1
开启视频与本地预览RtcEngineenableVideo1
加入频道RtcEnginejoinChannel1
离开频道RtcEngineleaveChannel1
频道场景RtcEnginesetChannelProfile1
切换角色RtcEnginesetClientRole1
绑定本地画面RtcEnginesetupLocalVideo1
typescript
muteRemoteAudioStream(mute: int uid,required bool): Future
initialize(): Future
renewToken(token: String): Future
enableVideo(): Future
joinChannel(options: String token,required String channelId,required int uid,required ChannelMediaOptions): Future
leaveChannel(options?: LeaveChannelOptions?): Future
setChannelProfile(profile: ChannelProfileType): Future
setClientRole(options?: ClientRoleType role,ClientRoleOptions?): Future
setupLocalVideo(canvas: VideoCanvas): Future

事件与回调

回调注册在 RtcEngineEventHandler 上;不同端的命名可能不同,完整清单见同端 API 参考页。

回调签名用途
onConnectionStateChangedonConnectionStateChanged(connection: RtcConnection, state: ConnectionStateType, reason: ConnectionChangedReasonType): void入会结果 / 连接状态变化:据此更新 UI 并决定是否重连。
onUserJoinedonUserJoined(connection: RtcConnection, remoteUid: int, elapsed: int): void远端用户加入:分配画面容器。
onFirstRemoteVideoDecodedonFirstRemoteVideoDecoded(connection: RtcConnection, remoteUid: int, width: int, height: int, elapsed: int): void远端视频状态:首帧解码后即可渲染。
onUserOfflineonUserOffline(connection: RtcConnection, remoteUid: int, reason: UserOfflineReasonType): void远端用户离开:释放容器与订阅。
onRequestTokenonRequestToken(connection: RtcConnection): voidToken 即将过期:调用服务端续期后 `renewToken`。
onErroronError(err: ErrorCodeType, msg: String): void运行时错误:`err` 为声网错误号,按错误码表分流。
onNetworkQualityonNetworkQuality(connection: RtcConnection, remoteUid: int, txQuality: QualityType, rxQuality: QualityType): void网络质量:上报到水晶球或提示用户。

错误码

常量值
RtcEnginenull
errAborted20
errAdmGeneralError1005
errAdmInitPlayout1008
errAdmInitRecording1011
errAdmStartPlayout1009
errAdmStartRecording1012
errAdmStopPlayout1010
errAdmStopRecording1013
errAlreadyInUse19
errBitrateLimit115
errBufferTooSmall6
errClientIsBannedByServer123
errConnectionInterrupted111
errConnectionLost112
errDatastreamDecryptionFailed122
errDecryptionFailed120
errEncryptedStreamNotAllowedPublish130
errFailed1
errInitNetEngine21
errInvalidAppId101
errInvalidArgument2
errInvalidChannelName102
errInvalidState8
errInvalidTokennull
errInvalidUserAccount134
errInvalidUserId121
errJoinChannelRejected17
errLeaveChannelRejected18
errLoadMediaEngine1001
errNoPermission9
errNoServerResources103
errNotInChannel113
errNotInitialized7
errNotReady3
errNotSupported4
errOk0
errPcmsendBufferoverflow201
errPcmsendFormat200
errRefused5
errResourceLimited22
errSetClientRoleNotAuthorized119
errSizeTooLarge114
errStreamMessageTimeout117
errTimedout10
errTokenExpired109
errTooManyDataStreams116
errVdmCameraNotAuthorized1501

平台 REST 层用 REST 错误码;SDK 层把连接/鉴权失败映射成声网错误号,映射表见 各端 SDK 错误标识。

本页由文档构建流水线生成 · 2026-10-31 01:24:02 UTC · 文档中心 v1.1.0.

内容依据公开 API 定义.

ni-meet 是自建 RTC PaaS,媒体面基于 LiveKit(Apache-2.0),并与声网 API 兼容。