開発ガイド¶

Sora iOS SDK 全般¶

Sora iOS SDK の構成要素¶

Sora iOS SDK は次の要素を中心に構成されます。

メディアチャネル¶

メディアチャネル ( MediaChannel ) は WebRTC のメディアチャネルを表します。 Sora iOS SDK ではメディアチャネルの ID を指定して Sora に接続します。

ロール¶

ロール (Role) はメディアチャネルが扱う音声と映像の送受信の方向を表します。ロールは接続 1 つにつき 1 つです。ロールの種類を次に示します。

送信のみ (Role.sendonly) は端末の音声と映像を Sora に送信します。
受信のみ (Role.recvonly) は Sora から音声と映像を受信します。
送受信 (Role.sendrecv) は送信と受信の両方を行います。

メディアストリーム¶

メディアストリーム ( MediaStream ) は音声と映像のストリームを表すオブジェクトです。マルチストリーム機能では同チャネルへの接続数と同じ数のストリームが使用されます。

メディアストリームの取得方法は 2 種類あります。

メディアチャネル ( MediaChannel ) のプロパティから取得する

Sora への接続後、 MediaChannel の以下のプロパティより接続中の MediaStream の取得が行えます

streams: 全てのメディアストリームのリスト
senderStream: 送信されるメディアストリーム
receiverStreams: 受信したメディアストリームのリスト
mainStream: 先頭のメディアストリーム
- 単一映像を受信のみするケース、単一映像を送信のみするケースでの利用を想定しています

メディアチャネル ( MediaChannel ) のイベントハンドラから取得する

Sora への接続後、 MediaChannel のイベントハンドラである MediaChannelHandlers より追加、または削除された MediaStream の取得が行えます

onAddStream: 追加されたメディアストリーム
onRemoveStream: 削除されたメディアストリーム

映像ビュー¶

映像ビュー (VideoView) はメディアストリームの音声と映像を描画するビューオブジェクトです。いずれのロールの映像も描画できます。

SDK のログをコンソールに出力する¶

Logger の level プロパティでログレベルの指定が可能です。デフォルトのログレベルは .info です。

例: デバッグログを出力する

Logger.shared.level = .debug

WebRTC¶

WebRTC ライブラリのバージョンを知りたい¶

WebRTCInfo の version プロパティで Sora iOS SDK が使用する WebRTC のバージョンを取得できます。メジャーバージョンがリリースブランチを表します。

WebRTC ライブラリの API を使う¶

WebRTC ライブラリの API (接頭辞が RTC のもの) を使うには、 WebRTC フレームワークをインポートする必要があります。ファイルの先頭に import WebRTC を記述してください。

WebRTC ライブラリのログをコンソールに出力する¶

WebRTC の挙動について Sora iOS SDK より詳細なログを出力したい場合は、 Sora オブジェクトの setWebRTCLogLevel() を使ってログレベルを指定します。

// 最も詳細なログを表示する
Sora.setWebRTCLogLevel(.verbose)

メディア制約を指定する¶

メディア制約は MediaConstraints で表されます。 MediaConstraints を WebRTCConfiguration の constraints プロパティにセットすることでメディア制約を指定可能です。

ICE サーバーの URL を指定する¶

ICE サーバーの情報は ICEServerInfo で表されます。サーバーの URL をセットした ICEServerInfo を WebRTCConfiguration の iceServerInfos プロパティに指定します。

シグナリング¶

メタデータを指定する¶

任意の JSON 値の送受信を参照してください。

送受信されたシグナリングの内容を確認する¶

シグナリングの内容はデバッグログを有効にするとコンソールに出力されます。設定方法は SDK のログをコンソールに出力するを参照してください。

接続¶

Sora に接続する¶

大まかな手順を次に示します。 Sora に接続するも参考にしてください。

Configuration を生成します。Sora のシグナリング URL 、チャネル ID 、ロールをセットします。
Sora オブジェクトの connect(configuration:webRTCConfiguration:handler:) を実行します。実行後は handler: に渡したブロックが実行されます。
接続が成功するとストリームが生成されます。このストリームは mainStream プロパティでアクセスできます。

マルチストリーム機能を有効にして接続する¶

詳しくはマルチストリーム機能を参照してください。

接続試行時のタイムアウトを設定する¶

接続試行時のタイムアウトまでの秒数は、 Configuration の connectionTimeout プロパティで指定可能です。 connect(configuration:webRTCConfiguration:handler:) で接続が成立せずにタイムアウトになると、 handler ラベルに指定したブロックが実行されます。このとき、ブロックの引数にタイムアウトを示すエラー (SoraError.connectionTimeout) が渡されます。

接続試行をキャンセルする¶

接続試行中に処理をキャンセルしたい場合は、 connect(configuration:webRTCConfiguration:handler:) の戻り値である ConnectionTask オブジェクトの cancel() を実行します。すでに接続済み、またはキャンセル済みの場合は何も起こりません。

再接続を行う¶

予期しない原因で接続が解除されたときに再接続を行いたい場合は、接続解除を検知する onDisconnectHandler イベントハンドラを利用して実装可能です。

次に MediaChannel のイベントハンドラを使う例を示します:

mediaChannel.handlers.onDisconnectHandler = { error in
    // 予期しない接続解除の場合のみ再接続する
    if error != nil {
        // 10 秒後に再接続する
        DispatchQueue.main.asyncAfter(deadline: DispatchTime.now() + 10) {
            Sora.shared.connect(configuration: configuration) { chan, error in
                ...
            }
        }
        return
    }
}

再接続を実装する際は次の点に注意してください:

この方法による再接続とは「新しい接続」であり、接続解除前の状態を引き継ぐものではないので注意してください。 Sora は再接続に対応していません。
同一のチャネル ID に再接続する場合、再接続を行うまでの時間が短いと、シグナリング時にチャネル ID 重複エラー (DUPLICATED-CHANNEL-ID) が発生する可能性があります。このエラーが頻発する場合は、ある程度時間を空けてから再接続を行ってください。現在の Sora の仕様では、待ち時間は Sora の稼働状況に依存します。運用の仕方に応じて待ち時間を調節してください。

イベントハンドラを使用する¶

Sora iOS SDK は次のイベントハンドラを提供しています。詳しくは API リファレンスを参照してください。

WebSocket (WebSocketHandlers)
メディアストリーム (MediaStreamHandlers)
メディアチャネル (MediaChannelHandlers)

配信ストリームを取得する¶

配信ストリーム (端末のカメラとマイクのメディアデータを送信するストリーム) は MediaChannel の senderStream プロパティで取得できます。

受信ストリームのリストを取得する¶

受信ストリームのリストは MediaChannel の receiverStreams プロパティで取得できます。

受信ストリームに紐づく Sora のコネクション ID を取得する¶

MediaStream の streamId プロパティにはストリームを送信したクライアントのコネクション ID が設定されています。受信した MediaStream は MediaChannel の receiverStreams プロパティや、 MediaChannel のイベントハンドラである MediaChannelHandlers から取得できます。

映像と音声¶

映像と音声の可否を指定する¶

映像なら Configuration の videoEnabled プロパティ、音声なら audioEnable プロパティで指定可能です。

映像・音声コーデックを指定する¶

映像コーデックなら Configuration の videoCodec プロパティ、音声コーデックなら audioCodec プロパティで指定可能です。

映像ビットレートを指定する¶

Configuration の videoBitRate プロパティで指定可能です。

送受信された映像を描画する¶

映像は VideoView で描画できます。 VideoView をストリームの videoRenderer プロパティにセットします。詳しくは映像を描画するを参照してください。

サンプルコード:

let config = Configuration(url:
    URL(string: "ws://192.168.0.2:5000/signaling")!,
                           channelId: "soraapp",
                           role: .sendonly,
                           multistreamEnabled: false)
Sora.shared.connect(configuration: config) { chan, error in
    if let error = error {
        // エラー処理
        return
    }

    // VideoView をストリームにセット
    chan!.mainStream?.videoRenderer = self.videoView
}

映像フレームを加工・編集する¶

映像フレームを加工・編集するを参照してください。

Interface Builder で VideoView を配置する¶

ウィンドウに View コンポーネントを配置し、インスペクタの Custom Class の "Class" に "VideoView" を、 "Module" に "Sora" を指定します。

音声をミュートする、音量を変更する¶

音声の操作を参照してください。

映像と音声の送受信を一時的に停止する¶

接続中に映像または音声の送受信を一時的に停止・再開するには、 MediaStream の次のプロパティを利用します。

映像の停止と再開: videoEnabled プロパティ
音声の停止と再開: audioEnabled プロパティ

それぞれのプロパティに false をセットすると、送受信を停止します。 true をセットすると送受信を再開します。

任意の音声を送信したい¶

WebRTC ライブラリの制約により、 Sora iOS SDK ではマイク入力以外の音声を送信できません。ご了承ください。

カメラとマイク¶

カメラとマイクを初期化する¶

映像送信時、 Sora への接続に成功すると、端末のカメラとマイクが自動的に準備されます。必ず事前に Info.plist の設定をしておいてください。無設定だとアプリケーションが強制終了します。

マイクをミュートする¶

Sora iOS SDK ではマイクをミュートする API を用意していません。 AVAudioSession などを利用してください。

カメラ（マイク）のアクセス権をユーザーに要求しない¶

カメラ（またはマイク）の初回起動時は、カメラとマイクへのアクセス権を求めるダイアログが表示されます。ダイアログの表示に関しては次の制限があります。

使わないデバイスのダイアログを非表示にできない。 映像のみ、または音声のみの利用であっても、カメラとマイクに関する 2 つのダイアログが表示されます。これは libwebrtc の仕様であり、 Sora iOS SDK では変更できません。
ダイアログを表示するタイミングを制御できない。 ダイアログはカメラやマイクへのアクセスがあると起動されますが、アクセスがなくても表示される場合があります。これは libwebrtc の仕様であり、 iOS の仕様です。