Flutter ライブストリーミングプラグイン
aibuds_live_stream_flutter は、ネイティブの AIBudsLiveStream ミドルウェアを Flutter へ橋渡しします。再生用の iOS Platform View と、RTSP 入力を RTMP 配信先へ中継する独立したコントローラーを提供します。
このページでは Flutter とネイティブ側の管理責任を説明します。デバイスの対応確認、ホットスポット設定、RTSP URL の取得については、RTSP ライブストリーミングを参照してください。
デバイスストリームと Flutter 側の利用先
1 つのデバイス RTSP セッションが生成するアドレスを、共通のホストライフサイクル管理下でネイティブプレビュー、任意の中継、またはその両方へ渡します。
RTSP セッションを開始
対応確認とホットスポット連携を完了します。
RTSP URL を受信
このセッションで有効なアドレスを保持します。
ネイティブプレイヤー
再生コマンドを送る前にコントローラーを接続します。
プレビューを描画
ネイティブイベントをマウント済み UI の状態へ反映します。
RTMP 中継
独立して管理するストリーマーのライフサイクルで配信します。
- RTSP セッションを開始continues toRTSP URL を受信
- RTSP URL を受信previewネイティブプレイヤー
- ネイティブプレイヤーcontinues toプレビューを描画
- RTSP URL を受信optional relayRTMP 中継
対応プラットフォームとパッケージング
- iOS に対応しています。Android は未実装です。
- Dart 3.3 以降、Flutter 3.19 以降、iOS 13 以降が必要です。
- プラグインは
AIBudsLiveStreamFlutterPlugin.xcframeworkをラップし、AIBudsSDK/LiveStreamに依存します。 - RTSP と RTMP は実機の iOS デバイスで検証してください。
提供される XCFramework とリソースは、プラグインターゲットの iOS パッケージング工程に含めます。Runner ターゲットへ競合するコピーを追加せず、プラグイン側でリンクを解決してください。
実行時アーキテクチャ
1 つのプレイヤーコントローラーが 1 つのネイティブ Platform View に対応します。AIBudsLiveStreamPlayerView が作成・接続されるまでコマンドは使用できません。ストリーマーコントローラーは、別のネイティブ中継ライフサイクルを管理します。
View・イベント・コントローラーをまとめて管理する
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 で 1 つのコントローラーを使い回さないでください。
デバイス状態とプレイヤー状態を分離する
LiveStreamingAPI はデバイス／ホットスポットセッションを管理し、Flutter プレイヤーはネイティブ描画を管理します。プレイヤーの成功はデバイスセッションの正常性を保証せず、デバイス側の開始もフレーム描画を保証しません。デバイスセッション、ネットワーク経路、プレイヤー、UI の状態を個別に追跡してください。
停止時や画面遷移時は、新しい操作を抑止し、プレイヤー／ストリーマー、デバイスセッションを停止して、Dart の購読を解除し、ネイティブコントローラーと保持中の URL を破棄します。中断によって一方がすでに停止していても安全にクリーンアップできるようにしてください。
RTSP から RTMP への中継
AIBudsLiveStreamStreamerController は独立した運用機能として扱います。
- コールバック処理の外で配信先の認証を確認する。
- 開始前にイベントを購読する。
- 対象ネットワークに合わせて、ビットレート、解像度、フレームレート、音声、タイムアウト、適応ビットレート、再接続ポリシーを設定する。
- プレビュー成功だけで配信成功と判断しない。
- デバイスセッション終了時にストリーマーを停止・破棄する。
- 配信用認証情報を Dart ソースや診断情報へ埋め込まない。
プレビューと中継で同じ RTSP ソースを共有する場合は、最低サポート端末でリソース消費と再接続動作を検証してください。
パフォーマンスと復旧
- 通常の状態変化で Platform View を再構築しない。
- 高頻度イベントは
setStateの前で間引く。 - バックグラウンド移行、ホットスポット切断、デバイス切断、View 破棄を別々の中断として扱う。
- 自動再接続に上限を設け、ユーザーが再試行できるようにする。
- 古いセッションを継続できない場合は、デバイスからプレイヤーまでの処理全体を作り直す。
トラブルシューティング
| 症状 | 確認する境界 |
|---|---|
| 再生前にコマンドが失敗する | Platform View がまだ接続されていません。 |
| iOS 以外でプレースホルダーが表示される | 現在のプラグイン実装は iOS のみです。 |
| URL はあるが映像が表示されない | プレイヤーイベント、ホットスポット経路、実機への到達性を確認します。 |
| RTMP 配信先に届かない | プレビュー状態とは分けてストリーマーイベントを診断します。 |
| 画面遷移後もイベントが届く | 購読を解除し、対応するネイティブコントローラーを破棄します。 |
| シンボルが重複する | 競合するネイティブ依存関係のコピーを削除します。 |