外部映像入力ガイド¶

概要¶

sora_sdk の外部映像入力 API の使い方と振る舞いをまとめます。

外部映像入力 API とは¶

SDK 管理のカメラ入力 (MediaDevices.getUserMedia() 経由) の代わりに、アプリ側で用意した任意の映像フレームを送信する API です。画面キャプチャ、動画ファイル再生、 camera パッケージからの取り込み、合成映像、テストパターンなど、カメラ以外の入力を扱うために用意されています。

..note::

SDK 内蔵の SoraCameraCapturer を通さず、アプリ側が AdaptedVideoTrackSource に直接 I420 フレームを流し込む経路となります

API 一覧¶

• MediaDevices.createMediaStream(): トラックを保持しない LocalMediaStream を生成します
• MediaDevices.createAudioTrack(): LocalAudioTrack を生成します (音声入力が必要な場合)
• MediaDevices.createExternalVideoTrack(): 外部映像入力用の LocalVideoTrack を生成します
• LocalVideoTrack.writeFrame(ExternalVideoFrame): 生成した映像トラックに I420 フレームを投入します
• LocalVideoTrack.captureType: VideoTrackCaptureType を返します (camera / external)
• LocalVideoTrack.dispose(): トラックと内部の映像ソース参照を解放します
• ExternalVideoFrame: 1 フレーム分の I420 データ構造体

カメラ入力との違い¶

外部映像入力トラックを使っているあいだは SDK 側のカメラキャプチャが動かないため、 LocalVideoTrack.textureId からのローカルプレビューは提供されません。ローカルでプレビューしたい場合はアプリ側でフレームを別途描画してください。

基本の流れ¶

1. MediaDevices.createMediaStream() で LocalMediaStream を作る
2. 必要に応じて createAudioTrack() を作成し stream.addTrack() で追加する
3. MediaDevices.createExternalVideoTrack() で映像トラックを作成し stream.addTrack() で追加する
4. SoraConnection.connect(stream) で接続する
5. 任意のタイミングで track.writeFrame(ExternalVideoFrame(...)) を呼ぶ
6. 使い終わったら client.disconnect() → track.dispose() / stream.dispose()

import 'dart:typed_data';

import 'package:sora_sdk/sora_sdk.dart';

Future<void> startExternalVideo() async {
  final client = await Sora.createConnection(
    SoraConnectionConfig(
      signalingUrls: <String>['wss://sora.example.com/signaling'],
      channelId: 'example-channel',
      role: SoraRole.sendonly,
      audio: true,
      video: true,
    ),
  );

  // トラックを保持しない LocalMediaStream を生成
  final stream = MediaDevices.createMediaStream();
  // 音声入力が必要な場合は音声トラックを生成
  final audio = MediaDevices.createAudioTrack();
  // 外部映像入力用の映像トラックを生成
  final video = MediaDevices.createExternalVideoTrack();
  // 音声・映像トラックを LocalMediaStream に関連付ける
  stream.addTrack(audio);
  stream.addTrack(video);

  await client.connect(stream);

  // 以降、任意のタイミングで I420 フレームを流し込む
  video.writeFrame(buildFrame());

  // 終了時の解放
  await client.disconnect();
  await video.dispose();
  await audio.dispose();
  await stream.dispose();
  await client.dispose();
}

MediaStream.dispose() は中のトラックを自動解放しません。 LocalVideoTrack.dispose() を明示的に呼ぶと、ネイティブ側の AdaptedVideoTrackSource の参照もまとめて release されます。

ExternalVideoFrame のフィールド¶

色空間は I420 (YUV 4:2:0 planar) 固定です。他のフォーマットを扱う場合はアプリ側で I420 に変換してください。

writeFrame() の振る舞い¶

カメラと外部入力を切り替える¶

replaceVideoTrack(stream, track) で差し替えられます。前提条件として確認されるのはトラック種別 (LocalVideoTrack) と role / config.video であり、 captureType の違いは制限されません。

以下のように切り替わります。

• camera → external: platform のカメラが止まる。以降は writeFrame() でフレームを供給する必要がある
• external → camera: platform のカメラ入力が再開し、 LocalVideoTrack.textureId からのローカルプレビューも再開する

final next = MediaDevices.createExternalVideoTrack();
await client.replaceVideoTrack(stream, next);
await previous.dispose();

差し替え前のトラックは replaceVideoTrack() 内で stream から removeTrack() されますが、 dispose() は呼ばれません。使わなくなったトラックはアプリ側で dispose() してください。

接続と送信の前提¶

• SoraConnectionConfig.video が false のとき、または role: recvonly のときは connect() が stream を受け付けません。外部映像入力も video: true の sendonly / sendrecv でのみ使えます
• audio トラックを含める場合は config.audio = true、含めない場合は config.audio = false にしてください (同じ検証が走ります)
• ローカルプレビューを表示したい場合は、 writeFrame() 用のフレームをアプリ側で別ウィジェット (たとえば CustomPaint) に描画してください。SDK からのローカルプレビュー (LocalVideoTrack.textureId) は外部入力時には提供されません

エラーハンドリングの指針¶

writeFrame() が StateError を投げるのは API 使用ミス (dispose 済み、captureType 誤り、入力バイト列不足) があったことを表します。フレームの欠落やネットワーク調整を理由にスキップされる場合は例外にならず、そのまま返ります。アプリ側では以下を目安に設計すると整理しやすくなります。

• フレーム生成側でバッファ長と stride を検証し、不整合があれば assert で早期検出する
• 送信レートを制御する layer (タイマー / producer) をアプリ側に置き、SDK から解像度要求を通知する API は使わない (公開されていないため)
• 状態遷移は client.events (SoraConnectionStateChangedEvent) と組み合わせて、接続完了前のフレーム投入を避ける

コード例¶

ExternalVideoFrame buildSolidColorFrame({
  required int width,
  required int height,
  required int y,
  required int u,
  required int v,
}) {
  final chromaWidth = (width + 1) ~/ 2;
  final chromaHeight = (height + 1) ~/ 2;
  final yPlane = Uint8List(width * height)..fillRange(0, width * height, y);
  final uPlane = Uint8List(chromaWidth * chromaHeight)
    ..fillRange(0, chromaWidth * chromaHeight, u);
  final vPlane = Uint8List(chromaWidth * chromaHeight)
    ..fillRange(0, chromaWidth * chromaHeight, v);
  return ExternalVideoFrame(
    width: width,
    height: height,
    yPlane: yPlane,
    uPlane: uPlane,
    vPlane: vPlane,
    yStride: width,
    uStride: chromaWidth,
    vStride: chromaWidth,
  );
}

Timer? timer;

void startPublishing(LocalVideoTrack track) {
  timer = Timer.periodic(const Duration(milliseconds: 33), (_) {
    track.writeFrame(buildSolidColorFrame(
      width: 640,
      height: 480,
      y: 128,
      u: 128,
      v: 128,
    ));
  });
}

Future<void> stopPublishing() async {
  timer?.cancel();
  timer = null;
}

注意点¶

• createExternalVideoTrack() はネイティブ側に映像ソースを確保します。作成したトラックは必ず dispose() してください。 dispose() 内で adaptedVideoTrackSourceRelease が呼ばれます
• 外部入力トラック 1 本に対する writeFrame() は送信キューに 1 フレーム投入する操作です。同じトラックで並列に呼んだ場合の順序は保証されないため、アプリ側で排他制御してください
• 解像度や fps の上限は libwebrtc 側の判断に従います。送信側の品質調整 (videoBitRate / simulcast / spotlight) と組み合わせた挙動は Sora サーバー設定にも依存します
• カメラトラックで writeFrame() を呼ぶと必ず StateError になります。誤用を防ぐため、 track.captureType == VideoTrackCaptureType.external のガードを書いてから呼ぶと安全です

あわせて読むとよいページ¶

• メディアデバイスガイド
• 外部カメラ利用ガイド
• 映像レンダリングガイド
• シグナリング設定
• simulcast
• イベント