コールバック

Sora Android SDK には WebRTC API のイベントや Sora 固有の機能のイベントをハンドリングするためのコールバックを用意しています。

ここではそのコールバックの利用方法について説明します。

onAddLocalStream

ローカルストリーム（自分）が追加されたときに呼び出されるコールバックです。

Sora では各 MediaStream の videoTracks には 1 つしか VideoTrack が含まれないため、MediaStream.videoTracks[0] で VideoTrack を取得できます。

private var localAudioTrack: AudioTrack? = null

private val channelListener = object : SoraMediaChannel.Listener {

   // ローカル(送信用)の MediaStream が準備できたときに呼ばれます。
   // メディア送信時に必要となる設定をここで行います。
   // SoraMediaOption で、音声や映像を upstream で送信する指定を行っていない場合は
   // このメソッドを実装する必要はありません。
   override fun onAddLocalStream(mediaChannel: SoraMediaChannel, ms: MediaStream) {

      // 動画の表示(UI)に関係する処理になるので、
      // Activity の runOnUiThread メソッドを利用し、UIスレッドで実行することを推奨します。
      runOnUiThread {
         if (ms.videoTracks.size > 0) {
            // 予め用意しておいた、localRenderer(SurfaceViewRendererオブジェクト)を
            // 以下のように、videoTrackに紐付けておきます
            // ただし、自分が送信するデータを表示したくない場合には、これらの処理は必要ありません
            val track = ms.videoTracks[0]
            track.setEnabled(true)
            track.addSink(localRenderer)
            capturer?.startCapture(400, 400, 30)
         }

         if (ms.audioTracks.size > 0) {
            // 必要であれば AudioTrack をここで掴んでおきます。
            localAudioTrack = ms.audioTracks[0]
         }
      }
   }
}

// onAddLocalStream で AudioTrack を掴んでおくと、一時的にミュートしたい場合などに便利です。
private fun muteAudio() {
   localAudioTrack?.setEnabled(false)
}

private fun unmuteAudio() {
   localAudioTrack?.setEnabled(true)
}

onAddRemoteStream

リモートストリームが追加されたときに呼び出されるコールバックです。

Sora では各 MediaStream の videoTracks には 1 つしか VideoTrack が含まれないため、MediaStream.videoTracks[0] で VideoTrack を取得できます。

private val channelListener = object : SoraMediaChannel.Listener {

   // リモート(受信用)の MediaStream が準備できたときに呼ばれます。
   // メディア受信時に必要となる設定をここで行います。
   // SoraMediaOption で、音声や映像を downstream で受信する設定を行っていない場合は
   // このメソッドを実装する必要はありません。
   override fun onAddRemoteStream(mediaChannel: SoraMediaChannel, ms: MediaStream) {

      // 動画の表示(UI)に関係する処理になるので、
      // Activity の runOnUiThread メソッドを利用し、UIスレッドで実行することを推奨します。
      runOnUiThread {
         if (ms.videoTracks.size > 0) {
            // 予め用意しておいた、remoteRenderer(SurfaceViewRendererオブジェクト)を
            // 以下のように、videoTrackに紐付けておきます
            // ただし、受信する映像を表示したくない場合には、これらの処理は必要ありません
            val track = ms.videoTracks[0]
            track.setEnabled(true)
            track.addSink(remoteRenderer)
         }
      }
   }
}

onRemoveRemoteStream

リモートストリームが削除されたときに呼び出されるコールバックです。

private val channelListener = object : SoraMediaChannel.Listener {
   override fun onRemoveRemoteStream(mediaChannel: SoraMediaChannel, label: String) {
      runOnUiThread {
         // 例: リモートストリームの描画領域をクリア
         binding.remoteRenderer.clearImage()
      }
   }
}

onConnect

Sora との接続が確立されたときに呼び出されるコールバックです。

private val channelListener = object : SoraMediaChannel.Listener {

   override fun onConnect(mediaChannel: SoraMediaChannel) {
      // 接続が確立されたときの処理を記述する
   }
}

onClose

Sora との接続が切断されたときに呼び出されるコールバックです。Sora から切断された場合、closeEvent に切断理由が設定されます。

このコールバックが呼び出されたとき、SoraMediaChannel 内部ではすでに切断処理が行われた後の状態になっており、Sora との接続に関わるオブジェクトは破棄されています。 そのため、再接続を行う場合は、SoraMediaChannel を作成し直す必要があります。

以下のようなタイミングで呼び出されます。

• SoraMediaChannel.disconnect() を呼び出したとき

• Sora から切断されたことを検知したとき

• PeerConnection の state が切断になったとき

• 上記以外で何かしら異常が発生したとき

closeEvent について

closeEvent は Sora から切断された場合のステータスコードと理由が設定されます。

closeEvent は SoraCloseEvent オブジェクトで、以下のプロパティを持ちます。

• code

  • Sora から切断されたときのステータスコード

  • Sora からの切断メッセージが取得できない場合は 1000 が設定されます

• reason

  • Sora から切断されたときの理由

  • Sora からの切断メッセージが取得できない場合は NO-ERROR が設定されます

Sora からの切断メッセージがが取得できない場合は以下のようなケースです。

• SoraMediaChannel.disconnect() を呼び出しなど、クライアント契機の切断

• ネットワークの切断や Sora のサーバーの障害など、Sora からの切断メッセージが受信できなかった場合

• DataChannel 経由のシグナリングを利用する場合、かつ ignore_disconnect_websocket が true の場合 - 上記の設定の場合、 Sora の切断メッセージを受信するには data_channel_signaling_close_message を有効にする必要があります - data_channel_signaling_close_message が有効の場合も、 切断メッセージの受信より先に DataChannel の切断をクライアントが検知した場合は切断メッセージの受信は行われません

private val channelListener = object : SoraMediaChannel.Listener {

   override fun onClose(mediaChannel: SoraMediaChannel, closeEvent: SoraCloseEvent) {
      when {
          closeEvent.code != 1000 -> Log.e(TAG, "onClose: エラーにより Sora から切断されました: $closeEvent")
          else -> Log.d(TAG, "onClose: Sora から切断されました: $closeEvent")
      }
      // 切断されたときの処理を記述する
   }
}

onError

Sora との通信やメディアでエラーが発生したときに呼び出されるコールバックです。

onError が発生した場合も、onClose は呼び出されるため、終了処理は onClose に実装されていれば問題ありません。

private val channelListener = object : SoraMediaChannel.Listener {

   override fun onError(mediaChannel: SoraMediaChannel, reason: SoraErrorReason, message: String) {
      // エラーが発生したときの処理を記述する
   }
}

onWarning

Sora との通信やメディアで警告が発生したときに呼び出されるコールバックです。

private val channelListener = object : SoraMediaChannel.Listener {

   override fun onWarning(mediaChannel: SoraMediaChannel, reason: SoraErrorReason) {
      // 警告が発生したときの処理を記述する
   }
}

onAttendeesCountUpdated

接続しているチャネルの参加者が増減したときに呼び出されるコールバックです。

ChannelAttendeesCount は、ロールごとに接続数を保持しているオブジェクトです。

例えば、視聴者数 (recvonly の数) の更新を UI に反映させる場合は以下のようにします。

private val channelListener = object : SoraMediaChannel.Listener {

   override fun onAttendeesCountUpdated(
      mediaChannel: SoraMediaChannel,
      attendees: ChannelAttendeesCount
   ) {
      // 例: 視聴者数を更新する
      updateViewerCount(attendees.numberOfRecvonlyConnections)
   }
}

onOfferMessage

Sora から type: offer メッセージを受信したときに呼び出されるコールバックです。

private val channelListener = object : SoraMediaChannel.Listener {

   override fun onOfferMessage(mediaChannel: SoraMediaChannel, offer: OfferMessage) {
      // offer メッセージを受信したときの処理を記述する
   }
}

onNotificationMessage

Sora のシグナリング通知機能の通知を受信したときに呼び出されるコールバックです。

詳しくは Sora ドキュメントの シグナリング通知機能 を参照してください。

private val channelListener = object : SoraMediaChannel.Listener {

   override fun onNotificationMessage(
      mediaChannel: SoraMediaChannel,
      notification: NotificationMessage
   ) {
      // 通知を受信したときの処理を記述する
   }
}

onPushMessage

Sora のプッシュ API によりメッセージを受信したときに呼び出されるコールバックです。

詳しくは Sora ドキュメントの プッシュ API を参照してください。

private val channelListener = object : SoraMediaChannel.Listener {

   override fun onPushMessage(mediaChannel: SoraMediaChannel, push: PushMessage) {
      Log.d("onPushMessage", "push=$push")
      val data = push.data
      if (data is Map<*, *>) {
         data.forEach { (key, value) ->
             Log.d("onPushMessage", "received push data: $key=$value")
         }
      }
   }
}

onPeerConnectionStatsReady

PeerConnection の getStats() 統計情報を取得したときに呼び出されるコールバックです。

SoraMediaChannel 初期化時に PeerConnectionOption の getStatsIntervalMSec に 0 より大きい値を設定すると、getStatsIntervalMSec ミリ秒ごとにこのコールバックが呼び出されます。

private val channelListener = object : SoraMediaChannel.Listener {

   override fun onPeerConnectionStatsReady(
      mediaChannel: SoraMediaChannel,
      statsReport: RTCStatsReport
   ) {
      // RTCStatsReport の解析処理を記述する
   }
}

onSenderEncodings

サイマルキャスト配信のエンコーダー設定を変更するためのコールバックです。

引数の encodings は Sora が送ってきた設定を反映した RtpParameters.Encoding のリストです。 このコールバックを実装し、引数のオブジェクトを変更することで、アプリケーションの要件に従った設定をエンコーダーにわたすことができます。

private val channelListener = object : SoraMediaChannel.Listener {

   override fun onSenderEncodings(
      mediaChannel: SoraMediaChannel,
      encodings: List<RtpParameters.Encoding>
   ) {
      // 例: エンコーダー設定を変更する処理を記述する
   }
}

参考

Web 標準の対応 API は次のとおりです。libwebrtc の native(C++) と android の実装は異なりますので注意してください。

• https://www.w3.org/TR/webrtc/#dom-rtcrtpencodingparameters

• https://www.w3.org/TR/webrtc/#dom-rtcrtpsender-setparameters

onDataChannel

データチャネルが利用可能になったときに呼び出されるコールバックです。

private val channelListener = object : SoraMediaChannel.Listener {

   // DataChannel が利用可能になったタイミングで実行されるコールバック
   override fun onDataChannel(mediaChannel: SoraMediaChannel, dataChannels: List<Map<String, Any>>?) {
      // リアルタイムメッセージングで利用できる DataChannel 一覧をログに出力する
      Log.d("onDataChannel", "$dataChannels")
   }
}

onDataChannelMessage

リアルタイムメッセージング機能のメッセージを受信したときに呼び出されるコールバックです。 ラベルが # から始まるメッセージのみが通知されます。

private val channelListener = object : SoraMediaChannel.Listener {

   // DataChannel メッセージ受信時のコールバック
   override fun onDataChannelMessage(mediaChannel: SoraMediaChannel, label: String, data: ByteBuffer) {
      // ByteBuffer を String に変換して出力する
      val message = mediaChannel.dataToString(data)
      Log.d("onDataChannelMessage", message)
   }
}

コンテンツ

• コールバック
  • onAddLocalStream
  • onAddRemoteStream
  • onRemoveRemoteStream
  • onConnect
  • onClose
    • closeEvent について
  • onError
  • onWarning
  • onAttendeesCountUpdated
  • onOfferMessage
  • onNotificationMessage
  • onPushMessage
  • onPeerConnectionStatsReady
  • onSenderEncodings
    • 参考
  • onDataChannel
  • onDataChannelMessage