サーバーに接続する¶
概要¶
サーバーへの接続と設定内容について記載します。 サーバーへの接続設定内容については Sora ドキュメント WebSocket 経由のシグナリング も参考にしてください。
接続の手順¶
サーバーへの接続は次の手順で行います。
SoraMediaOption を準備する
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
: SoraMediaOptionlistener
: SoraMediaChannel.ListenerdataChannelSignaling
: 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"
...