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,
multistreamEnabled: false)
// 接続する
Sora.shared.connect(configuration: config) { mediaChannel, error in
// 接続に失敗するとエラーが渡される。
// 接続に成功すると error は nil
if let error = error {
// 接続エラー時の処理
...
}
// 接続成功時の処理
// 映像を描画するビューをストリームにセットする等
...
}
}
Configuration はサーバーへの接続情報などの設定を保持するオブジェクトです。 サーバーの URL 、チャネル ID 、ロール、マルチストリームの可否をセットします。
次に Configuration を引数として Sora オブジェクトの connect メソッド を呼びます。このとき Sora オブジェクトは Sora.shared プロパティでシングルトンを取得できます。
このメソッドはサーバーへの接続を行い、接続の成否に関わらず 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 は映像データを扱うストリームを複数保持します。 映像はストリームを通じて Web ブラウザやサーバーと送受信されます。
ストリームは送信か受信のいずれかを担当し、ロールによって扱う数が異なります。 シングルストリームにおいて、送信と受信のストリームはそれぞれ 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,
multistreamEnabled: true)
// 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,
multistreamEnabled: true)
// 音声コーデックを opus に設定する
config.audioCodec = .opus
音声ビットレートの設定¶
Sora 接続時に送信する音声についてビットレートの指定ができます。
音声のビットレートは Configuration の
audioBitRateに設定します。
var config = Configuration(url: url,
channelId: channelId,
role: .sendrecv,
multistreamEnabled: true)
// 音声ビットレートを 32 kbps に設定する
config.audioBitRate = 32
映像コーデックの設定¶
Sora 接続時に送信する映像についてコーデックの指定ができます。
映像のコーデックは Configuration の
videoCodecに VideoCodec を設定します。
var config = Configuration(url: url,
channelId: channelId,
role: .sendrecv,
multistreamEnabled: true)
// ビデオコーデックを VP8 に設定する
config.videoCodec = .vp8
映像ビットレートの設定¶
Sora 接続時に送信する映像についてビットレートの指定ができます。
映像のビットレートは Configuration の
videoBitRateに設定します。
var config = Configuration(url: url,
channelId: channelId,
role: .sendrecv,
multistreamEnabled: true)
// ビデオビットレートを 3000 kbps に設定する
config.videoBitRate = 3000
映像コーデックパラメーターの設定¶
送信する映像コーデックの設定と合わせて、映像コーデックのパラメータを指定可能です。
この機能は role が sendrecv または sendonly の場合に利用できます。
指定できる値の内容については以下の Sora ドキュメントを参照してください。
var config = Configuration(url: url,
channelId: channelId,
role: .sendrecv,
multistreamEnabled: true)
// 映像コーデックの設定は VP9 / AV1 / H.264 のいずれか 1 種類のみです
// 利用しない映像コーデックパラメーターは設定しないでください
// VP9 の場合は profile_id の設定が可能です
config.videoCodec = .vp9
config.videoVp9Params = ["profile_id": 0]
// AV1 の場合は profile の設定が可能です
// config.videoCodec = .av1
// config.videoVp9Params = ["profile": 0]
// H.264 の場合は profile_level_id の設定が可能です
// config.videoCodec = .h264
// config.videoH264Params = ["profile_level_id": "42e01f"]
転送フィルターの設定¶
転送フィルター機能は、Sora 側でクライアントへ転送する音声や映像のパケットをフィルターする機能です。 詳しくは Sora ドキュメント を参照してください。
この機能は role が sendrecv または recvonly の場合にのみ利用できます。
フィルターを設定する¶
サーバー接続時に Configuration.forwardingFilter を設定します。
設定例¶
以下の例は、自分の接続に対して、以下の条件で映像または音声の受信をブロックします。
connection_id が "S8YEN0TSE13JDC2991NG4XZ150" の場合は音声と映像の受信をブロックする、または client_id が "screen-share" の場合は音声の受信をブロックする
var config = Configuration(url: url,
channelId: channelId,
role: .sendrecv,
multistreamEnabled: true)
config.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"]),
]
],
)
プロキシ・サーバーの設定¶
プロキシ・サーバーを 経由した通信を行う場合は、 Configuration の proxy プロパティにプロキシ情報をセットしてください。
HTTP プロキシに対応しています
SOCKS プロキシも設定できますが、動作を確認していません
HTTP の CONNECT メソッドは HTTPS ではなく HTTP で送信します
Proxy-Authorization ヘッダーを利用した Basic 認証に対応しています
iOS の Wi-Fi に設定されたプロキシの項目を参照しません
var config = Configuration(url: url,
channelId: channelId,
role: .sendrecv,
multistreamEnabled: true)
// proxy 情報の設定を行う
configuration.proxy = Proxy(host: "proxy.example.com",
port: 3128,
agent: nil,
username: "ham",
password: "egg")