Flutter 라이브 스트리밍 플러그인

aibuds_live_stream_flutter는 네이티브 AIBudsLiveStream 미들웨어를 Flutter와 연결합니다. 재생용 iOS 플랫폼 뷰와 RTSP 입력을 RTMP 대상으로 중계하는 별도 컨트롤러를 제공합니다.

이 페이지에서는 Flutter와 네이티브 사이의 관리 범위를 설명합니다. 기기 기능 지원 여부, 핫스팟 설정, RTSP URL 획득은 RTSP 라이브 스트리밍을 따릅니다.

Animated flow map

기기 스트림과 Flutter 사용 경로

하나의 기기 RTSP 세션에서 받은 주소를 단일 호스트 수명 주기 관리 아래 네이티브 미리보기, 선택적 중계 또는 두 경로 모두에 사용할 수 있습니다.

기기 세션

RTSP 세션 시작

기능 지원 여부 확인과 핫스팟 연결을 완료합니다.

공유 입력

RTSP URL 수신

현재 세션의 신뢰할 수 있는 주소를 보관합니다.

플랫폼 뷰

네이티브 플레이어

재생 명령 전에 컨트롤러를 뷰에 연결합니다.

Flutter UI

미리보기 표시

네이티브 이벤트를 마운트된 화면 상태에 반영합니다.

선택적 경로

RTMP 중계

별도로 관리하는 스트리머 수명 주기로 송출합니다.

RTSP 세션 시작continues toRTSP 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와 리소스를 플러그인 대상의 iOS 패키징 흐름에 유지하세요. Runner 대상에 충돌하는 복사본을 추가하지 말고 플러그인 쪽에서 링크 문제를 해결합니다.

런타임 아키텍처

플레이어 컨트롤러 하나는 네이티브 플랫폼 뷰 하나를 나타냅니다. AIBudsLiveStreamPlayerView가 생성되어 연결되기 전에는 명령을 사용할 수 없습니다. 스트리머 컨트롤러는 별도의 네이티브 중계 수명 주기를 관리합니다.

뷰, 이벤트, 컨트롤러를 함께 관리하기

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();
  }
}

플랫폼 뷰와 기기 RTSP URL이 모두 준비될 때까지 기다리세요. 어느 쪽이든 먼저 준비될 수 있습니다. 동시에 마운트된 여러 뷰에서 하나의 컨트롤러를 재사용하지 마세요.

기기 상태와 플레이어 상태 분리하기

LiveStreamingAPI는 기기와 핫스팟 세션을 관리합니다. Flutter 플레이어는 네이티브 렌더링을 관리합니다. 플레이어 성공이 기기 세션의 정상 상태를 보장하지 않으며, 기기 시작 성공도 프레임 표시를 보장하지 않습니다. 기기 세션, 네트워크 경로, 플레이어, UI 상태를 각각 추적하세요.

중지하거나 화면을 벗어날 때는 새 작업을 막고 플레이어와 스트리머, 기기 세션을 중지한 뒤 Dart 구독을 취소하고 네이티브 컨트롤러와 보관한 URL을 정리합니다. 한쪽이 이미 중단된 경우에도 정리 작업이 안전해야 합니다.

RTSP를 RTMP로 중계하기

AIBudsLiveStreamStreamerController는 독립적인 운영 기능으로 다루세요.

콜백 경로 밖에서 송출 대상의 인증을 확인합니다.
시작 전에 이벤트를 구독합니다.
대상 네트워크에 맞춰 비트 전송률, 크기, 프레임률, 오디오, 제한 시간, 적응형 비트 전송률, 재연결 정책을 선택합니다.
미리보기 성공만으로 송출 성공을 판단하지 않습니다.
기기 세션이 끝나면 스트리머를 중지하고 해제합니다.
Dart 소스나 진단 정보에 송출 인증 정보를 포함하지 않습니다.

미리보기와 중계가 같은 RTSP 소스를 사용한다면 지원하는 가장 낮은 사양의 기기에서 리소스 사용량과 재연결 동작을 테스트하세요.

성능과 복구

일반적인 상태 변경 때 플랫폼 뷰를 다시 만들지 않습니다.
빈도가 높은 이벤트는 간격을 조절한 뒤 setState를 호출합니다.
백그라운드 전환, 핫스팟 연결 해제, 기기 연결 해제, 뷰 해제를 각각 별도의 중단 상황으로 처리합니다.
자동 재연결 횟수를 제한하고 사용자가 직접 재시도할 수 있게 합니다.
이전 세션을 더 이상 신뢰할 수 없다면 기기부터 플레이어까지 전체 파이프라인을 다시 만듭니다.

문제 해결

증상	확인할 경계
재생 전에 명령이 실패함	플랫폼 뷰가 아직 연결되지 않았습니다.
iOS가 아닌 플랫폼에서 자리 표시자 표시	현재 플러그인은 iOS만 구현합니다.
URL은 있지만 영상이 없음	플레이어 이벤트, 핫스팟 경로, 실제 기기 연결을 확인하세요.
RTMP 대상에 아무것도 송출되지 않음	미리보기 상태와 별개로 스트리머 이벤트를 진단하세요.
화면을 벗어난 뒤에도 이벤트가 계속됨	구독을 취소하고 네이티브 컨트롤러를 해제하세요.
심볼 중복	충돌하는 네이티브 의존성 복사본을 제거하세요.

RTSP 세션 시작

RTSP URL 수신

네이티브 플레이어

미리보기 표시

RTMP 중계

플랫폼 및 패키징 경계​

런타임 아키텍처​

뷰, 이벤트, 컨트롤러를 함께 관리하기​

기기 상태와 플레이어 상태 분리하기​

RTSP를 RTMP로 중계하기​

성능과 복구​

문제 해결​