サーバーに接続する

概要

サーバーへの接続と設定内容について記載します。 サーバーへの接続設定内容については Sora ドキュメント WebSocket 経由のシグナリング も参考にしてください。

接続の手順

サーバーへの接続は次の手順で行います。

  1. SoraMediaChannel.Listener を準備する

  2. SoraMediaOption を準備する

  3. SoraMediaChannel を生成し接続する

使用例

// (1) SoraMediaChannel.Listener の実装の準備
private val channelListener = object : SoraMediaChannel.Listener {

  override fun onConnect(mediaChannel: SoraMediaChannel) {
    ...
  }
  // その他の Listener インタフェースの実装
}

fun start() {

  // (2) SoraMediaOption の準備
  val option = SoraMediaOption().apply {
    // Optionの設定
  }

  // (3) SoraMediaChannel の作成、接続
  mediaChannel = SoraMediaChannel(
    context           = this,
    signalingEndpoint = "wss://sora.example.com/signaling",
    channelId         = "sora",
    mediaOption       = option,
    listener          = channelListener)

  mediaChannel.connect()
}

fun stop() {
  mediaChannel.disconnect()
}

接続時の主な設定内容

SoraMediaOption の主な設定内容

SoraMediaOption の主な設定内容を次に示します。 デフォルトの設定はいずれも無効です。

  • enableVideoUpstream(): 映像を送信します。引数にキャプチャーと EGL コンテキストを与えます。

  • enableVideoDownstream(): 映像を受信します。引数に EGL コンテキストを与えます。

  • enableAudioUpstream(): 音声を送信します。

  • enableAudioDownstream(): 音声を受信します。

  • videoCodec: 映像コーデックを指定します。デフォルトは VP9 です。

  • videoBitrate: 映像ビットレートを指定します。

  • audioCodec: 音声コーデックを指定します。デフォルトは OPUS です。

  • audioBitrate: 音声ビットレートを指定します。

  • enableMultistream(): マルチストリーム機能 を有効にします。

  • enableSimulcast(): サイマルキャスト機能 を有効にします。

  • enableSpotlight(): スポットライト機能 を有効にします。

  • proxy: プロキシ・サーバーの設定 を行います。

  • hardwareVideoEncoderResolutionAdjustment: 解像度の縦横のピクセル数が指定した値の整数倍となるように調整します。デフォルトは 16 です。

SoraMediaChannel の主な設定内容

SoraMediaChannel の主な設定内容を次に示します。

  • context: android.content.Context

  • signalingEndpoint: シグナリング URL を指定します。複数指定する場合は signalingEndpointCandidates にて指定してください。

  • signalingEndpointCandidates: シグナリング URL を複数指定します。詳細は 複数のシグナリング URL を指定する をご確認ください。

  • channelId: 接続するチャネル ID を指定します。

  • mediaOption: SoraMediaOption

  • listener: SoraMediaChannel.Listener

  • dataChannelSignaling: DataChannel 経由のシグナリング を有効にします

  • dataChannels: メッセージング機能 利用時に使用します

  • signalingMetadata: 認証時にサーバーに送信する任意のメタデータを指定します。詳細は メタデータの送信 をご確認ください。

  • signalingNotifyMetadata: シグナリング通知時に連携される任意のメタデータを指定します。詳細は メタデータの送信 をご確認ください。

  • clientId: 接続時に任意に指定可能な ID を指定します。

  • bundleId: マルチストリーム利用時、同一の bundle_id が設定されている別の接続からの音声や映像、メッセージングを受信しなくなります。

role の自動設定について

映像または音声の送受信の設定によりサーバー接続時のロールが自動的に判定されます。 明示的に SoraMediaOption.role に設定することも可能です。 ロールについては Sora ドキュメント ロール の項も参考にしてください。

role が明示的に指定されていない場合は SoraMediaOption への送受信の設定内容から判定されます SoraChannelRole.SENDRECV と判定された場合、マルチストリーム機能 も有効に設定されます

  • 送信と受信両方の設定が行われている : SoraChannelRole.SENDRECV

  • 送信のみの設定が行われている : SoraChannelRole.SENDONLY

  • 受信のみの設定が行われている : SoraChannelRole.RECVONLY

// 以下は映像と音声の送受信を設定しているのでサーバー接続時のロールは SoraChannelRole.SENDRECV となります。
val option = SoraMediaOption().apply {

  enableVideoUpstream(capturer, egl.eglBaseContext)
  enableAudioUpstream()
  enableVideoDownstream()
  enableAudioDownstream()
  ...
}

メタデータの送受信について

サーバとの接続時にメタデータの送信を行うことができます。また、サーバから接続時、シグナリング通知によりメタデータを受信できます。 関連する箇所に Sora ドキュメント のリンクを記載しますので合わせて参考にしてください。

メタデータの送信

認証時にサーバーに送信する metadata については Sora ドキュメント メタデータ の項を参照してください。

シグナリング通知時に連携されるメタデータ signaling_notify_metadata については シグナリング通知メタデータ を参照してください。

Sora Android SDK では上記の metadata 、 signaling_notify_metadata を、それぞれ SoraMediaChannel の signalingMetadata 、 signalingNotifyMetadata に値を設定します。 JSON 形式に変換可能なデータを設定してください。設定したデータは Gson により変換されます。

// 接続して映像を送受信します
// signalingMetadata, signalingNotifyMetadata には JSON 形式に変換可能なデータを設定します
val mediaChannel = SoraMediaChannel(
              context                     = this,
              signalingEndpoint           = "wss://example.com/signaling",
              channelId                   = "sora",
              signalingMetadata           = "abc",
              signalingNotifyMetadata     = mapOf("spam" to "egg"),
              mediaOption                 = option,
              listener                    = channelListener)

mediaChannel.connect()

メタデータの受信

認証サーバから受信した metadata については Sora ドキュメント "type": "offer" の項を参照してください。 シグナリング通知時に連携されるメタデータについては シグナリング通知メタデータ を参照してください。

Sora Android SDK では上記の metadata 、 シグナリング通知メタデータが、それぞれ SoraMediaChannel.Listener の onOfferMessage 、 onNotificationMessage で通知されます。

// 接続通知を受信するための Listener を宣言します。
private val channelListener = object : SoraMediaChannel.Listener {

  // Sora から type: offer メッセージを受信した際に呼び出されるコールバック
  override fun onOfferMessage(mediaChannel: SoraMediaChannel, offer: OfferMessage) {

    // 認証サーバから返却された metadata が返却されます
    val offerMetadata = offer.metadata
    ...
  }

  // Sora のシグナリング通知機能の通知を受信したときに呼び出されるコールバック
  override fun onNotificationMessage(mediaChannel: SoraMediaChannel, notification: NotificationMessage) {

    when (notification.eventType) {

      // シグナリング通知に設定された各種 metadata が返却されます
      // 項目の詳細については Sora のドキュメントをご確認ください
      // https://sora-doc.shiguredo.jp/SIGNALING_NOTIFY_METADATA
      "connection.created", "connection.destroyed", "connection.updated" -> {

        var signalingNotifyConnectionId  = notification.clientId
        var signalingNotifyAuthMetadata  = notification.authnMetadata
        var signalingNotifyAutzMetadata  = notification.authzMetadata
        var signalingNotifyDataList      = notification.data
      }
    }

  }
  ...
}

DataChannel 経由のシグナリング

DataChannel 経由のシグナリングについては Sora ドキュメント DataChannel 経由のシグナリング を参照してください。

Sora Android SDK で Sora と DataChannel を経由したシグナリング通信を行う場合は SoraMediaChannel の dataChannelSignaling に true を設定します。 デフォルトの設定はいずれも無効です。

ignoreDisconnectWebsocket プロパティに true をセットした場合、 DataChannel への切り替え完了後に Android SDK は WebSocket を切断します。

// 接続して映像を送受信します
// DataChannel 経由のシグナリングを有効にしています
// ignoreDisconnectWebSocket = true にすると DataChannel への切り替え完了後に WebSocket は切断されます
val mediaChannel = SoraMediaChannel(
              context                     = this,
              signalingEndpoint           = "wss://example.com/signaling",
              channelId                   = "sora",
              dataChannelSignaling        = true,
              ignoreDisconnectWebSocket   = true,
              mediaOption                 = option,
              listener                    = channelListener)

mediaChannel.connect()

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

Sora Android SDK はプロキシ・サーバーを経由した通信を行うことができます。

  • HTTP プロキシに対応しています

    • SOCKS プロキシも設定できますが、動作を確認していません

  • HTTP の CONNECT メソッドは HTTPS ではなく HTTP で送信します

  • Proxy-Authorization ヘッダーを利用した Basic 認証に対応しています

  • Android OS の Wi-Fi に設定されたプロキシの項目を参照しません

プロキシ・サーバーの情報は SoraMediaOption.proxy に設定します。

val mediaOption = SoraMediaOption()

...

mediaOption.proxy.type = ProxyType.HTTPS

// ホスト名、または IP アドレスを指定します
mediaOption.proxy.hostname = "proxy.example.com"
mediaOption.proxy.port = 3128

// プロキシに認証が設定されている場合は username と password を指定します
mediaOption.proxy.username = "ham"
mediaOption.proxy.password = "egg"

// エージェントの設定は任意です
// 未設定の場合は、シグナリング・メッセージに含まれる `sora_client` の値が使用されます
mediaOption.proxy.agent = "spam"

...
© Copyright 2018-2022, Shiguredo Inc. Created using Sphinx 5.0.2