Sora に接続する¶

概要¶

Sora への接続処理の概要について記載しています。

接続の手順¶

Sora への接続は次の手順で行います。

1. Configuration を生成する。
2. 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 と送受信されます。

接続後の映像の送受信については 映像を描画する を参考にしてください

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 経由に切り替わったタイミングで呼ばれるクロージャー
public var onDataChannel: ((MediaChannel) -> Void)?

/// DataChannel のメッセージ受信時に呼ばれるクロージャー
public var onDataChannelMessage: ((MediaChannel, String, Data) -> Void)?

音声の設定¶

var config = Configuration(url: url,
                           channelId: channelId,
                           role: .sendrecv)

// 音声コーデックを opus に設定する
config.audioCodec = .opus

var config = Configuration(url: url,
                           channelId: channelId,
                           role: .sendrecv)

// 音声ビットレートを 32 kbps に設定する
config.audioBitRate = 32

映像の設定¶

var config = Configuration(url: url,
                           channelId: channelId,
                           role: .sendrecv)

// 映像コーデックを VP8 に設定する
config.videoCodec = .vp8

var config = Configuration(url: url,
                           channelId: channelId,
                           role: .sendrecv)

// 映像コーデックの設定は VP9 / AV1 / H.264 / H.265 のいずれか 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"]

// H.265 の場合は profile_id、level_id、tier_flag、tx_mode の設定が可能です
// config.videoCodec = .h265
// config.videoH265Params = ["profile_id": 1, "level_id": 93, "tier_flag": 0, "tx_mode": "SRST"]

var config = Configuration(url: url,
                           channelId: channelId,
                           role: .sendrecv)

// ビデオビットレートを 3000 kbps に設定する
config.videoBitRate = 3000

転送フィルターの設定¶

転送フィルター機能は、Sora 側でクライアントへ転送する音声や映像のパケットをフィルターする機能です。 詳しくは Sora ドキュメント をご確認ください。

この機能は role が sendrecv または recvonly の場合にのみ利用できます。

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]

TLS 検証¶

WebSocket シグナリングおよび TURN-TLS のサーバー証明書検証では、既定で iOS のルートストアに含まれるルート証明書を用いて、サーバー証明書の証明書チェーンを検証します。

WebSocket シグナリングは Sora とのシグナリング接続に、 TURN-TLS は ICE で利用する TURN サーバーとの TLS 接続に利用されます。

var webRTCConfiguration = WebRTCConfiguration()

// TURN-TLS の証明書検証を無効にする
let insecureICEServerInfo = ICEServerInfo(
    urls: ["turns:turn.example.com:5349?transport=tcp"],
    userName: "username",
    credential: "credential",
    tlsSecurityPolicy: .insecure
)

webRTCConfiguration.iceServerInfos = [secureICEServerInfo]

var config = Configuration(url: url,
                            channelId: channelId,
                            role: .sendrecv)

config.caCertificate = """
-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----
"""

プロキシ・サーバーの設定¶

プロキシ・サーバーを経由した通信を行う場合は、 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