Sora に接続する¶
概要¶
Sora への接続処理の概要について記載しています。
接続の手順¶
Sora への接続は次の手順で行います。
Configuration を生成する。
Sora オブジェクトの connect メソッド を呼ぶ。
import Sora
// シグナリング URL とチャネル ID を指定する
let url = URL(string: "wss://sora.example.com/signaling")!
let soraChannelId = "sora"
let config = Configuration(url: url,
channelId: soraChannelId,
role: .recvonly)
// 接続する
Sora.shared.connect(configuration: config) { mediaChannel, error in
// 接続に失敗するとエラーが渡される。
// 接続に成功すると error は nil
if let error = error {
// 接続エラー時の処理
...
}
// 接続成功時の処理
// 映像を描画するビューをストリームにセットする等
...
}
}
Configuration は Sora への接続情報などの設定を保持するオブジェクトです。 Sora のシグナリング URL 、チャネル ID 、ロールをセットします。
次に Configuration を引数として Sora オブジェクトの connect メソッド を呼びます。このとき Sora オブジェクトは Sora.shared プロパティでシングルトンを取得できます。
このメソッドは Sora への接続を行い、接続の成否に関わらず handler: に指定されたブロックを実行します。
接続が成功すると MediaChannel がブロックの引数として渡されます。
MediaChannel は接続後の操作を行うためのオブジェクトです。
connect メソッド の型と引数は次の通りです。
func connect(configuration: Configuration,
webRTCConfiguration: WebRTCConfiguration = WebRTCConfiguration(),
handler: (_ mediaChannel: MediaChannel?, _ error: Error?) -> Void)
configuration: 接続情報です。シグナリング URL とチャネル ID を指定します。webRTCConfiguration: WebRTC に関する設定です (省略可) 。handler: 接続試行後に実行するブロックです。ブロックの型は(MediaChannel?, Error?) -> Voidです。ブロックの引数は次の通りです。mediaChannel: 接続に成功するとメディアチャネルが渡されます。失敗時はnilです。error: 接続に失敗するとエラーが渡されます。成功時はnilです。
MediaChannel は映像データを扱うストリームを複数保持します。 映像はストリームを通じて Sora と送受信されます。
ストリームは送信か受信のいずれかを担当し、ロールによって扱う数が異なります。 シングルストリームにおいて、送信と受信のストリームはそれぞれ 1 つです。 つまり、シングルストリームでは 1 回の接続につき送信か受信かのいずれか一方しか行えません。 1 台の端末で映像の送受信を行う場合は、送信と受信で 2 回の接続が必要です。
接続後の映像の送受信については 映像を描画する を参考にしてください
DataChannel 経由のシグナリング¶
Sora と DataChannel を経由したシグナリング通信を行うための接続方法について記載します。 詳しい仕様は Sora のドキュメント を参照してください。
DataChannel 経由のシグナリングを有効にするには、 Configuration の dataChannelSignaling プロパティに true をセットしてください。
WebSocket が閉じたときに Sora に接続が切断されたと判断して欲しくない場合は ignoreDisconnectWebSocket プロパティに true をセットしてください。
var config = Configuration(url: url,
channelId: channelId,
role: .sendrecv)
// DataChannel 経由のシグナリングを有効にする
config.dataChannelSignaling = true
// WebSocket が閉じたことを無視する
config.ignoreDisconnectWebSocket = true
イベントハンドラ¶
DataChannel に関するイベントハンドラは MediaChannelHandlers に用意しています。 主なイベントハンドラは以下の通りです。
/// シグナリングが DataChannel 経由に切り替わったタイミングで呼ばれるクロージャー
public var onDataChannel: ((MediaChannel) -> Void)?
/// DataChannel のメッセージ受信時に呼ばれるクロージャー
public var onDataChannelMessage: ((MediaChannel, String, Data) -> Void)?
音声コーデックの設定¶
Sora 接続時に送信する音声についてコーデックの指定ができます。
音声のコーデックは Configuration の
audioCodecに AudioCodec を設定します。
var config = Configuration(url: url,
channelId: channelId,
role: .sendrecv)
// 音声コーデックを opus に設定する
config.audioCodec = .opus
音声ビットレートの設定¶
Sora 接続時に送信する音声についてビットレートの指定ができます。
音声のビットレートは Configuration の
audioBitRateに設定します。
var config = Configuration(url: url,
channelId: channelId,
role: .sendrecv)
// 音声ビットレートを 32 kbps に設定する
config.audioBitRate = 32
映像コーデックの設定¶
Sora 接続時に送信する映像についてコーデックの指定ができます。
映像のコーデックは Configuration の
videoCodecに VideoCodec を設定します。利用できる映像コーデックは VP8 / VP9 / H.264 / H.265 / AV1 です。未指定の場合は Sora のデフォルト値が設定されます。
var config = Configuration(url: url,
channelId: channelId,
role: .sendrecv)
// 映像コーデックを VP8 に設定する
config.videoCodec = .vp8
映像ビットレートの設定¶
Sora 接続時に送信する映像についてビットレートの指定ができます。
映像のビットレートは Configuration の
videoBitRateに設定します。
var config = Configuration(url: url,
channelId: channelId,
role: .sendrecv)
// ビデオビットレートを 3000 kbps に設定する
config.videoBitRate = 3000
映像コーデックパラメーターの設定¶
送信する映像コーデックの設定と合わせて、映像コーデックのパラメータを指定可能です。
この機能は role が sendrecv または sendonly の場合に利用できます。
指定できる値の内容については以下の Sora ドキュメントを参照してください。
var config = Configuration(url: url,
channelId: channelId,
role: .sendrecv)
// 映像コーデックの設定は VP9 / AV1 / H.264 のいずれか 1 種類のみです
// 利用しない映像コーデックパラメーターは設定しないでください
// VP9 の場合は profile_id の設定が可能です
config.videoCodec = .vp9
config.videoVp9Params = ["profile_id": 0]
// AV1 の場合は profile の設定が可能です
// config.videoCodec = .av1
// config.videoAv1Params = ["profile": 0]
// H.264 の場合は profile_level_id の設定が可能です
// config.videoCodec = .h264
// config.videoH264Params = ["profile_level_id": "42e01f"]
転送フィルターの設定¶
転送フィルター機能は、Sora 側でクライアントへ転送する音声や映像のパケットをフィルターする機能です。 詳しくは Sora ドキュメント を参照してください。
この機能は role が sendrecv または recvonly の場合にのみ利用できます。
フィルターを設定する¶
Sora 接続時に Configuration.forwardingFilters を設定します。
設定例¶
以下の例は、自分の接続に対して、次の条件で映像または音声の受信をブロックします。
connection_id が "S8YEN0TSE13JDC2991NG4XZ150" の場合は音声と映像の受信をブロックする、または client_id が "screen-share" の場合は音声の受信をブロックする
var config = Configuration(url: url,
channelId: channelId,
role: .sendrecv)
let forwardingFilter = ForwardingFilter(
action: .block,
rules: [
[
ForwardingFilterRule(field: .connectionId,
operator: .isIn,
values: ["S8YEN0TSE13JDC2991NG4XZ150"]),
],
[
ForwardingFilterRule(field: .clientId,
operator: .isIn,
values: ["screen-share"]),
ForwardingFilterRule(field: .kind,
operator: .isIn,
values: ["audio"]),
]
],
)
config.forwardingFilters = [forwardingFilter]
プロキシ・サーバーの設定¶
プロキシ・サーバーを経由した通信を行う場合は、 Configuration の proxy プロパティにプロキシ情報をセットしてください。
HTTP プロキシに対応しています
SOCKS プロキシも設定できますが、動作を確認していません
HTTP の CONNECT メソッドは HTTPS ではなく HTTP で送信します
Proxy-Authorization ヘッダーを利用した Basic 認証に対応しています
iOS の Wi-Fi に設定されたプロキシの項目を参照しません
var config = Configuration(url: url,
channelId: channelId,
role: .sendrecv)
// proxy 情報の設定を行う
config.proxy = Proxy(host: "proxy.example.com",
port: 3128,
agent: nil,
username: "ham",
password: "egg")
複数のシグナリング URL を指定する¶
Sora iOS SDK では、 urlCandidates に複数のシグナリング URL を指定することができます。
Sora iOS SDK は全ての URL に対して接続を試行し、最初に成功した接続をシグナリングに使用します。 このため、１台でも正常なサーバーが残っていれば Sora への接続が成功します。 クラスター機能は複数の URL を指定しなくても利用できますが、冗長性を高めるために複数 URL の指定を推奨します。
let urlCandidates = [
URL(string: "wss://sora1.example.com/signaling")!,
URL(string: "wss://sora2.example.com/signaling")!,
URL(string: "wss://sora3.example.com/signaling")!
]
var config = Configuration(urlCandidates: urlCandidates,
channelId: channelId,
role: .sendrecv)
実際にシグナリングに利用されている URL は
MediaChannelクラスのconnectedUrlフィールドから確認できます。
クラスター機能利用時のシグナリングのリダイレクト¶
クラスター機能を有効にすると、 Sora から、 type: offer の代わりに type: redirect が送られてくることがあります。 この場合、Sora iOS SDK は Sora の接続を一度切断し、 type: redirect で指定された location に再接続します。
CPU やネットワーク帯域等逼迫時における映像品質優先項目の設定¶
映像の配信中に、CPU やネットワーク帯域などの制約を受けて、指定された解像度やフレームレートを維持できないことがあります。 そのような場合に、優先する項目を設定することができます。
例えば、文章が中心のスライドを利用するプレゼンテーションなど、フレームレートより解像度を優先した映像の配信を行いたい場合に、解像度を優先するように設定できます。
設定は Configuration の webRTCConfiguration.degradationPreference から行います。
degradationPreference には以下の値を設定できます。
disabled ... 何もしない
balanced ... バランスを取る
maintainResolution ... 解像度の維持を優先する
maintainFramerate ... フレームレートの維持を優先する (デフォルトの挙動です)
let config = Configuration(url: url,
channelId: soraChannelId,
role: .sendonly)
// リソースが逼迫した場合は解像度の維持を優先する
config.webRTCConfiguration.degradationPreference = .maintainResolution