開発ガイド

Sora iOS SDK 全般

Sora iOS SDK の構成要素

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

  • メディアチャネル (MediaChannel) は WebRTC のメディアチャネルを表します。 Sora iOS SDK ではメディアチャネルの ID を指定してサーバーに接続します。
  • ロール (Role) はメディアチャネルが扱う映像の送受信の方向を表します。ロールの種類を次に示します。
    • パブリッシャー (Role.publisher) は端末のカメラの映像をサーバーに送信します。
    • サブスクライバー (Role.subscriber) はサーバーから映像を受信します。
    • グループ (パブリッシャー) (Role.group) はマルチストリームの接続です。複数人の間で映像の送受信を行います。このアプリケーションでは扱いません。
    • グループ (サブスクライバー) (Role.groupSub) はマルチストリームの接続です。複数人の間で映像の送受信を行いますが、このロールを指定したクライアントは受信のみを行います。このアプリケーションでは扱いません。
  • メディアストリーム (MediaStream) は映像のストリームを表すオブジェクトです。グループ (マルチストリーム) では同チャネルへの接続数と同じ数のストリームが使用されます。グループ以外 (シングルストリーム) のパブリッシャーとサブスクライバーではストリームは 1 つです。
  • 映像ビュー (VideoView) はメディアストリームの映像と音声を描画するビューオブジェクトです。いずれのロールの映像も描画できます。

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

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

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

` Logger.shared.level = .debug `

WebRTC

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

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

メディア制約を指定する

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

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

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

接続

サーバーに接続する

大まかな手順を次に示します。 クイックスタート も参考にしてください。

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

マルチストリームで接続する

ロールにグループを指定します。 詳しくは マルチストリーム を参照してください。

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

接続試行時のタイムアウトまでの秒数は、 ConfigurationconnectionTimeout プロパティで指定可能です。 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 の稼働状況に依存します。 運用の仕方に応じて待ち時間を調節してください。

映像と音声

スナップショット機能を使う

ConfigurationsnapshotEnabled プロパティに true をセットします。 詳しくは スナップショット を参照してください。

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

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

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

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

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

ConfigurationvideoBitRate プロパティで指定可能です。

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

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

サンプルコード:

let config = Configuration(url:
    URL(string: "ws://192.168.0.2:5000/signaling")!,
                           channelId: "soraapp",
                           role: .publisher)
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" を指定します。

_images/videoview_customclass.png

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

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

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

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

カメラとマイク

端末のカメラとマイクを使う

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

カメラを起動・停止する

カメラは CameraVideoCapturer で操作可能です。 start() で起動、 stop() で停止します。 デフォルトの設定では、配信ストリームの接続成立で自動的にカメラが起動されます。

カメラの前面・背面を切り替える

CameraVideoCapturerposition プロパティにカメラの位置をセットするか、 flip() でカメラの前面・背面を切り替えられます。

カメラの解像度やフレームレートを変更する

カメラの設定は CameraVideoCapturer.Settings で指定可能です。 この設定を VideoCapturerDevice.camera(settings:) に渡し、 ConfigurationvideoCapturerDevice プロパティにセットします。 CameraVideoCapturer.Settings の詳細は API リファレンスを参照してください。

カメラのオートフォーカスを設定する

使用中のカメラの AVCaptureDevice を操作してください。 AVCaptureDevice は CameraVideoCapturercurrentCameraDevice プロパティで取得可能です。

マイクをミュートする

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