跳到主要内容

Flutter 直播插件

aibuds_live_stream_flutter 将原生 AIBudsLiveStream 中间件桥接到 Flutter。它提供用于播放的 iOS Platform View，以及将 RTSP 输入转发到 RTMP 目标的独立 Controller。

本页说明 Flutter 与 iOS 原生层之间的资源管理方式。设备能力检查、热点配置和 RTSP URL 获取请参阅 RTSP 直播。

Animated flow map

设备流与 Flutter 消费端

一个设备 RTSP 会话生成一个地址，由同一宿主生命周期持有者提供给原生预览、可选转发或两者。

设备会话

启动 RTSP 会话

完成能力和热点协调。

共享输入

接收 RTSP URL

保存当前直播会话返回的地址。

Platform View

原生播放器

发送播放指令前先附加 Controller。

Flutter UI

渲染预览

将原生事件映射到已挂载的展示状态。

可选分支

RTMP 转发

通过独立持有的推流器生命周期发布。

  • 启动 RTSP 会话continues to接收 RTSP URL
  • 接收 RTSP URL预览原生播放器
  • 原生播放器continues to渲染预览
  • 接收 RTSP URL可选转发RTMP 转发
播放器状态、推流器状态和设备会话相互独立；请显式停止并释放各自持有的资源。

平台与打包边界​

  • 支持 iOS；尚未实现 Android。
  • 需要 Dart 3.3+、Flutter 3.19+ 和 iOS 13+。
  • 插件封装 AIBudsLiveStreamFlutterPlugin.xcframework，并依赖 AIBudsSDK/LiveStream。
  • 在 iOS 真机上验证 RTSP 和 RTMP。

将提供的 XCFramework 和资源保留在插件 Target 的 iOS 打包流程中。在该处解决链接问题，不要向 Runner Target 引入冲突副本。

运行时架构​

一个播放器 Controller 对应一个原生 Platform View。创建并附加 AIBudsLiveStreamPlayerView 前无法使用指令。推流器 Controller 负责独立的原生转发生命周期。

集中管理 View、事件和 Controller​

DART
class LivePreviewState extends State<LivePreview> {
  final player = AIBudsLiveStreamPlayerController();
  StreamSubscription<AIBudsLiveStreamPlayerEvent>? events;

  @override
  void initState() {
    super.initState();
    events = player.events.listen((event) {
      if (!mounted) return;
      setState(() { /* map native event to presentation state */ });
    });
  }

  @override
  Widget build(BuildContext context) => AIBudsLiveStreamPlayerView(
    controller: player,
    options: const AIBudsLiveStreamPlayerOptions(
      format: AIBudsLiveStreamFormat.rtsp,
      gravityMode: AIBudsLiveStreamGravityMode.resizeAspect,
    ),
  );

  @override
  void dispose() {
    events?.cancel();
    player.disposePlayer();
    super.dispose();
  }
}

等待 Platform View 和设备 RTSP URL 都就绪，两者可能以任意顺序到达。不要在同时挂载的多个 View 之间复用一个 Controller。

分离设备和播放器状态​

LiveStreamingAPI 负责设备和热点会话，Flutter 播放器负责原生渲染。播放器成功不能证明设备会话正常，设备启动也不能证明已经渲染图像帧。请分别跟踪设备会话、网络路由、播放器和 UI 状态。

停止或离开页面时，禁止新操作，停止播放器和推流器、停止设备会话、取消 Dart 订阅、释放原生 Controller 并清理保留的 URL。即使中断已经停止其中一侧，清理也应保持安全。

RTSP 转 RTMP​

将 AIBudsLiveStreamStreamerController 视为独立运维功能：

  • 在回调路径之外验证目标端鉴权；
  • 启动前订阅事件；
  • 根据目标网络选择码率、尺寸、帧率、音频、超时、自适应码率和重连策略；
  • 不要根据预览成功推断发布成功；
  • 设备会话结束时停止并释放推流器；
  • 切勿在 Dart 源码或诊断信息中嵌入发布凭据。

如果预览和转发共享 RTSP 源，请在最低支持设备上测试资源和重连行为。

性能与恢复​

  • 避免因普通状态变化重建 Platform View。
  • 在 setState 前限制高频事件。
  • 将进入后台、热点丢失、断开连接和 View 释放视为独立中断。
  • 限制自动重连，并提供用户控制的重试。
  • 原会话失效后，重新创建设备到播放器的完整流程。

故障排除​

现象可能的边界
播放前指令失败Platform View 尚未附加。
非 iOS 占位界面插件当前只实现 iOS。
已有 URL 但没有视频检查播放器事件、热点路由和真机可达性。
RTMP 目标无输出独立于预览状态诊断推流器事件。
离开页面后事件仍继续取消订阅并释放原生 Controller。
符号重复移除冲突的原生依赖副本。