開発ガイド

目次

Sora iOS SDK 全般

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

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

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

Logger.shared.level = .debug

WebRTC

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

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

WebRTC ライブラリの API を使う

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

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

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

import WebRTC

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

メディア制約を指定する

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

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

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

シグナリング

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

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

接続

サーバーに接続する

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

  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 の稼働状況に依存します。 運用の仕方に応じて待ち時間を調節してください。

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

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

  • WebSocket (WebSocketHandlers)

  • シグナリング (SignalingHandlers)

  • ピア接続 (PeerConnectionHandlers)

  • メディアストリーム (MediaStreamHandlers)

  • メディアチャネル (MediaChannelHandlers)

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

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

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

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

映像と音声

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

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

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

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

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

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

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

映像は 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" を指定します。

_images/videoview_customclass.png

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

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

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

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

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

任意の音声を送信したい

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

カメラとマイク

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

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

カメラを起動・停止する

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

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

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

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

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

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

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

マイクをミュートする

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

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

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

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

  • ダイアログを表示するタイミングを制御できない。 ダイアログはカメラやマイクへのアクセスがあると起動されますが、アクセスがなくても表示される場合があります。 これは libwebrtc の仕様であり、 iOS の仕様です。