シグナリング設定¶

概要¶

Sora に接続するにはシグナリングの設定が必要です。シグナリングとは、 Sora とクライアント間で接続のネゴシエーションを行うための仕組みです。

Sora のシグナリングの詳細については Sora のドキュメント WebSocket 経由のシグナリングをご確認ください。

必須項目¶

Sora に接続するには シグナリング URL と チャネル ID 、 ロール を指定する必要があります。

final config = SoraConnectionConfig(
  signalingUrls: <String>[
    'wss://example.com/signaling',
  ],
  channelId: 'example-channel',
  role: SoraRole.sendrecv,
);

シグナリング URL¶

項目:: signalingUrls
型:: List<String>

Sora に接続するシグナリング URL をリストで指定してください。接続先が一つの場合でもリストで指定してください。

複数指定した場合は先頭から順番に接続を試みます
不正な URL が会った場合は接続は行わずエラーになります

シグナリングを URL を一つだけ設定する例¶

final config = SoraConnectionConfig(
  signalingUrls: <String>[
    'wss://example.com/signaling',
  ],
  channelId: 'example-channel',
  role: SoraRole.sendrecv,
);

シグナリング URL を複数設定する例¶

final config = SoraConnectionConfig(
  signalingUrls: <String>[
    'wss://1.example.com/signaling',
    'wss://2.example.com/signaling',
    'wss://3.example.com/signaling',
  ],
  channelId: 'example-channel',
  role: SoraRole.sendrecv,
);

チャネル ID¶

項目:: channelId
型:: String

接続する Sora のチャネル ID を文字列で指定してください。

チャネル ID に指定できる最小文字列の長さは 1 バイトです
チャネル ID で指定できる最大文字列の長さは 255 バイトです
チャネル ID の長さが正常では無い場合は接続は行わずエラーになります

ロール¶

項目:: role
型:: SoraRole

Sora に接続する際のロールを指定してください。

SoraRole.sendrecv¶

双方向での通信を行いたい場合は SoraRole.sendrecv を指定します。

SoraRole.sendonly¶

音声や映像のみを配信するだけで、視聴はしない場合は SoraRole.sendonly を指定します。

SoraRole.recvonly¶

配信はせず、音声や映像を視聴するだけの場合は SoraRole.recvonly を指定します。

音声¶

項目:: audio
型:: bool?
デフォルト:: null

音声を利用するかどうかを指定します。

この項目はロールに寄って挙動が変わります。

SoraRole.sendrecv と SoraRole.sendonly での場合は音声を配信するかどうか
SoraRole.recvonly の場合は音声を受信するかどうか

この項目はあくまでクライアントと Sora の間で音声をやりとりするかどうかの指定であり、音声デバイスから取得した音声を送るかどうかや、受信した音声を再生するかどうかとは別の設定です。これらはメディアデバイスガイドと音声再生ガイドをご確認ください。

final config = SoraConnectionConfig(
  signalingUrls: <String>[
    'wss://example.com/signaling',
  ],
  channelId: 'example-channel',
  role: SoraRole.sendrecv,
  audio: true,
);

音声コーデック指定¶

項目:: audioCodecType
型:: AudioCodecType?
デフォルト:: null

未指定の場合は Sora 側のデフォルトコーデックが利用されます。 Sora は音声コーデックに AudioCodecType.opus のみを利用するため、この項目を明示的に指定するする必要はありません。

final config = SoraConnectionConfig(
  signalingUrls: <String>[
    'wss://example.com/signaling',
  ],
  channelId: 'example-channel',
  role: SoraRole.sendrecv,
  audio: true,
  audioCodecType: 'OPUS',
);

音声ビットレート指定¶

項目:: audioBitRate
型:: int?
デフォルト:: null

音声ビットレートはデフォルトは 32 kbps が採用されます。 WebRTC ではステレオがデフォルトのため 64 kbps になります。ビットレートを明示的に指定する必要は基本的に必要ありません。

詳細は Sora のオーディオビットレート指定をご確認ください。

映像¶

項目:: video
型:: bool
デフォルト:: true

final config = SoraConnectionConfig(
  signalingUrls: <String>['wss://sora.example.com/signaling'],
  channelId: 'example-channel',
  role: SoraRole.sendrecv,
  video: true,
);]

映像コーデック指定¶

項目:: videoCodecType
型:: VideoCodecType?
デフォルト:: null

映像コーデックには VideoCodecType.{vp8, vp9, av1, h264, h265} が指定できます。未指定の場合は Sora 側で指定しているデフォルト映像コーデックが利用されます。

final config = SoraConnectionConfig(
  signalingUrls: <String>['wss://sora.example.com/signaling'],
  channelId: 'example-channel',
  role: SoraRole.sendrecv,
  video: true,
  videoCodecType: VideoCodecType.vp9,
);

映像ビットレート指定¶

項目:: videoBitRate
型:: int?
デフォルト:: null

映像ビットレートのデフォルトは Sora 側の設定に依存します。ビットレートの設定は映像の内容や解像度、フレームレート、コーデックにより様々なので、最適なビットレートはケースバイケースです。

final config = SoraConnectionConfig(
  signalingUrls: <String>['wss://sora.example.com/signaling'],
  channelId: 'example-channel',
  role: SoraRole.sendrecv,
  video: true,
  videoBitRate: 1500,
);

コーデック固有パラメータ¶

コーデック毎に固有のパラメータを指定できます。

videoVp9Params¶

final config = SoraConnectionConfig(
  signalingUrls: <String>['wss://sora.example.com/signaling'],
  channelId: 'example-channel',
  role: SoraRole.sendrecv,
  video: true,
  videoCodecType: VideoCodecType.vp9,
  videoVp9Params: <String, Object?>{
   'profileId': 1,
  },
);

詳細は Sora のドキュメントビデオの VP9 設定指定をご確認ください。

videoAv1Params¶

詳細は Sora のドキュメントビデオの AV1 設定指定をご確認ください。

videoH264Params¶

詳細は Sora のドキュメントビデオの H.264 設定指定をご確認ください。

videoH265Params¶

詳細は Sora のドキュメントビデオの H265 設定指定をご確認ください。

認証メタデータ¶

項目:: metadata
型:: Object?
デフォルト:: null

Sora に接続する際に Sora の認証ウェブフックに渡すメタデータを指定します。 Sora の認証ウェブフックは接続単位で認証するための仕組みです。

final config = SoraConnectionConfig(
  signalingUrls: <String>['wss://sora.example.com/signaling'],
  channelId: 'example-channel',
  role: SoraRole.sendrecv,
  video: true,
  videoCodecType: VideoCodecType.vp9,
  metadata: <String, Object?>{
    'jwt': 'a.b.c',
  },
);

クライアント ID¶

項目:: clientId
型:: String?
デフォルト:: null

任意のクライアント ID を指定します

バンドル ID¶

項目:: bundleId
型:: String?
デフォルト:: null

任意のバンドル ID を指定します。接続の束ね方を制御したい場合に使います。

サイマルキャスト¶

項目:: simulcast
型:: bool?
デフォルト:: null

サイマルキャストは同一映像で複数の画質の映像を同時に配信する仕組みです。

詳細は Sora のドキュメントサイマルキャスト機能をご確認ください。

送信側¶

サイマルキャストで同時に送れる映像の本数は、コーデック、解像度、ビットレートに依存しています。また仕様は WebRTC ライブラリによって異なります。

Sora の SDK で採用している WebRTC ライブラリである libwebrtc の仕様は Sora ドキュメントのサイマルキャストの仕様をご確認ください。

視聴側¶

項目:: simulcastRequestRid

サイマルキャストを視聴する側は接続時にどの画質の映像を受信するかを指定できます。これは接続後に Sora の HTTP API や RPC 機能を使って変更することができます。

final config = SoraConnectionConfig(
  signalingUrls: <String>['wss://sora.example.com/signaling'],
  channelId: 'example-channel',
  role: SoraRole.recvonly,
  simulcast: true,
  simulcastRequestRid: SimulcastRequestRid.r1,
);

スポットライト¶

項目:: spotlight
型:: bool?
デフォルト:: null

スポットライト機能は「直近で話をしている N 人」の映像の画質を上げる機能です。スポットライト機能を有効にすると、 Sora は話者の切り替わりを検知して、直近で話をしている N 人の映像の画質を上げます。

詳細は Sora のドキュメントスポットライト機能をご確認ください。

スポットライトがフォーカスした際に利用する映像の ID¶

項目:: spotlightForcusRid
型:: SpotlightRid?
デフォルト:: sora の設定に依存

音声が一定時間以上続いた場合、その話者にスポットライトがフォーカスします。その際に利用する映像の ID を指定します。ID は Sora 側で設定している spotlight_encodings の rid と一致させる必要があります。

rid は none / r0 / r1 / r2 のいずれかを指定します。

スポットライトがアンフォーカスした際に利用する映像の ID¶

項目:: spotlightUnfocusRid
型:: SpotlightRid?
デフォルト:: sora の設定に依存

音声が一定時間以上続かなかったり、他の話者が話し始めた場合、スポットライトがアンフォーカスします。その際に利用する映像の ID を指定します。ID は Sora 側で設定している spotlight_encodings の rid と一致させる必要があります。

rid は none / r0 / r1 / r2 のいずれかを指定します。

シグナリング通知メタデータ¶

signalingNotifyMetadata
型: Object?
デフォルト: null
シグナリング通知に含めるメタデータを指定します

タイムアウト¶

timeoutOptions¶

型: SoraTimeoutOptions?
WebRTC 接続ライフサイクルのタイムアウト設定です

SoraTimeoutOptions では次の項目を設定できます。

connectionTimeout (Duration、デフォルト: 30 秒): WebSocket 接続から PeerConnection 接続完了まで
disconnectWaitTimeout (Duration、デフォルト: 10 秒): disconnect() のリソース解放待機
signalingCandidateTimeout (Duration、デフォルト: 5 秒): WebSocket 接続確立時間

final config = SoraConnectionConfig(
  signalingUrls: <String>['wss://sora.example.com/signaling'],
  channelId: 'example-channel',
  role: SoraRole.sendrecv,
  timeoutOptions: SoraTimeoutOptions(
    connectionTimeout: Duration(seconds: 60),
    disconnectWaitTimeout: Duration(seconds: 15),
    signalingCandidateTimeout: Duration(seconds: 10),
  ),
);

詳しくはタイムアウト機能を参照してください。