オーディオルート制御
Androidでは、オーディオルーティングによって、スピーカーフォン、受話口、Bluetoothデバイス、有線ヘッドセットのどれから音声を出力するかが決まります。PlanetKitAudioSwitchを使用すると、通話中の有効なオーディオルートを制御できます。
| 通話タイプ | SDKの最低バージョン |
|---|---|
| 1対1通話、グループ通話（カンファレンス） | PlanetKit 3.7 |
オーディオルートの値
PlanetKitは現在のルートをPlanetKitAudioRouteで表します。
| 値 | 説明 |
|---|---|
UNDEFINED | ルートが定義されていないか、まだ決定されていません。 |
SPEAKER | 端末のスピーカーフォン |
HANDSET | 端末の受話口 |
BLUETOOTH | Bluetoothオーディオデバイス |
PLUGGED | 有線ヘッドセット |
オーディオルートを制御するかどうかを設定する
デフォルトでは、PlanetKitが通話のオーディオルートを管理します。この動作を設定するには、AudioDefaultAttributes.Builder.controlAudioRoute()を設定し、PlanetKitの初期化時にその属性を渡してください。
val audioAttributes = AudioDefaultAttributes.Builder()
.controlAudioRoute(true) // Default: true
.build()
val configurationBuilder = PlanetKit.PlanetKitConfiguration.Builder(context)
// Configure the other required PlanetKit settings on configurationBuilder.
configurationBuilder.setAudioDefaultAttributes(audioAttributes)
val configuration = configurationBuilder.build()
// Pass configuration to PlanetKit.initialize(configuration, listener).
controlAudioRoute(false)を設定すると、PlanetKitは通話のオーディオルートを管理しません。この場合、setAudioRoute()とsetSpeakerOn()によるルート選択要求はfalseを返します。
通話中にオーディオルートを確認または変更するには、アクティブなセッションからPlanetKitAudioSwitchを取得してください。
// 1-to-1 call
val audioSwitch = call.getAudioSwitch()
// Group call
val audioSwitch = conference.getAudioSwitch()
PlanetKitAudioSwitchの有効期間は、これを作成したPlanetKitCallまたはPlanetKitConferenceと同じです。
現在のルートと利用可能なルートを確認する
現在のルートはselectedAudioRouteで読み取り、現在利用可能なルートはavailableAudioRoutesで確認してください。
現在選択されているルートだけが必要な場合は、PlanetKitCall.audioRouteまたはPlanetKitConference.audioRouteを使用してください。いずれもPlanetKitAudioSwitch.selectedAudioRouteと同じ値を返します。利用可能なルートも確認する場合やルート変更を要求する場合は、PlanetKitAudioSwitchを使用してください。
// Current active route
val current = audioSwitch.selectedAudioRoute
Log.d(TAG, "Current route: $current")
// Available routes at this moment
val available = audioSwitch.availableAudioRoutes
Log.d(TAG, "Available routes: $available")
特定のルートに切り替える
アクティブな通話のPlanetKitAudioSwitchでsetAudioRoute()を呼び出してください。要求するルートはavailableAudioRoutesに含まれている必要があります。戻り値は、PlanetKitが要求を受け付けて切り替えを試みたかどうかを示すもので、実際にルートが変わったことは保証しません。呼び出し後にselectedAudioRouteを読み取るか、ルート変更リスナーを使用して、PlanetKitが現在選択しているルートを確認してください。この値はPlanetKitによる選択を示すものであり、OSがルートの適用を確定したことを示すものではありません（たとえば、Bluetooth SCO接続には数秒かかったり、接続に失敗したりする場合があります）。その後、そのルートを使用できないとPlanetKitが判断した場合、別のルート変更イベントを通知することがあります。
val audioSwitch = call.getAudioSwitch()
// Request Bluetooth if available
if (audioSwitch.availableAudioRoutes.contains(PlanetKitAudioRoute.BLUETOOTH)) {
audioSwitch.setAudioRoute(PlanetKitAudioRoute.BLUETOOTH)
val selectedByPlanetKit = audioSwitch.selectedAudioRoute == PlanetKitAudioRoute.BLUETOOTH
Log.d(TAG, "Bluetooth selected by PlanetKit: $selectedByPlanetKit")
}
setAudioRoute()の戻り値は次のことを示します。
true：PlanetKitは要求を受け付け、切り替えを試みました。OSが切り替えを拒否した場合など、ルートはまだ変わっていない可能性があります。false：要求したルートがavailableAudioRoutesにない、オーディオルート制御が無効、または要求したルートがすでに現在のルートです。
Android 12以降では、アプリにBluetooth接続権限がなくても、OSがルートを公開していればavailableAudioRoutesにBluetoothルートが表示されることがあります。この場合、PlanetKitはBluetoothをSDKのオーディオルートとして選択しません。Bluetoothを選択可能なルートとして提示する前に、必要なBluetooth権限を要求してください。権限なしでsetAudioRoute()を使用してBluetoothルートを要求してもtrueが返るため、戻り値ではなくselectedAudioRouteでPlanetKitが選択したルートを確認してください。
スピーカーフォンを切り替える
setSpeakerOn()は、スピーカーフォンと、スピーカーフォン以外で最も優先度の高いルートを切り替えるための便利なメソッドです。
// Enable speakerphone
audioSwitch.setSpeakerOn(true)
// Disable speakerphone — falls back to highest-priority available route
audioSwitch.setSpeakerOn(false)
// Query current state
val isSpeakerOn = audioSwitch.isSpeakerOn
ルートの優先順位を設定する
PlanetKitがルートを自動選択する必要がある場合は、優先順位リストを使用します。setPreferredAudioRoutesAtDisconnect()でリストを設定してください。
この優先順位リストは、外部デバイスが切断されたとき、外部ルートが選択されていない状態でオーディオが始まるとき、スピーカーフォンをオフにしたとき、外部ルートがない状態でビデオ通話を有効にしたときに使用されます。新しく接続された外部デバイスを検出した場合の動作は、このリストでは決まりません。PlanetKitはリストの順序に関係なく、新しい有線ルートまたはBluetoothルートを要求します。
優先順位リストを設定しない場合、PlanetKitは次のデフォルト値を使用します。
| 通話タイプ | 優先順位 |
|---|---|
| 音声通話／カンファレンス | BLUETOOTH → PLUGGED → HANDSET → SPEAKER |
| ビデオ通話／カンファレンス | BLUETOOTH → PLUGGED → SPEAKER → HANDSET |
リストには、選択可能な4つのPlanetKitAudioRoute値をそれぞれ1回ずつ、希望する優先順位で含める必要があります。
音声通話とビデオ通話の優先順位リストは別々に設定してください。ビデオ通話のリストにはwhenOnVideoCall = trueを使用します。次の例では、PlanetKitがルートを自動選択する際に有線ヘッドセットを優先する、音声通話用のリストを設定します。
val audioSwitch = call.getAudioSwitch()
val audioCallPriority = listOf(
PlanetKitAudioRoute.PLUGGED,
PlanetKitAudioRoute.BLUETOOTH,
PlanetKitAudioRoute.HANDSET,
PlanetKitAudioRoute.SPEAKER
)
val success = audioSwitch.setPreferredAudioRoutesAtDisconnect(
whenOnVideoCall = false,
list = audioCallPriority
)
リストの項目数が誤っているか重複があるなど、リストが無効な場合はsetPreferredAudioRoutesAtDisconnect()がfalseを返します。
自動的なルート変更
オーディオルート制御が有効な場合、PlanetKitはオーディオ開始時にすでに選択されている有線またはBluetoothルートを維持します。通話が有効になった時点で両方が接続されている場合、Android 7以降では、OSがBluetoothルートを選択しているときにのみBluetoothを使用し、それ以外は有線ルートを使用します。Android 6以前ではBluetoothを使用します。これらの動作には必要なBluetooth権限が必要です。
ビデオ通話を有効にした場合、PlanetKitは有線またはBluetoothルートを維持します。それ以外の場合は、ビデオ通話用の優先順位リストで最初に利用可能なルートを選択します。ビデオ通話を無効にしても、それだけではルートは変わりません。
ルートと利用可能なルートの変更を監視する
選択されたルートの変更と利用可能なルートのリストの更新を受け取るには、PlanetKitCallまたはPlanetKitConferenceのインスタンスにリスナーを登録してください。
call.setOnAudioRouteChangeListener { newRoute ->
Log.d(TAG, "Audio route changed to: $newRoute")
// Update UI to reflect new route
}
// Also listen for changes to the available route list
call.setOnAudioRouteAvailableListChangeListener { availableRoutes ->
Log.d(TAG, "Available routes updated: $availableRoutes")
// Refresh route selection UI
}
// The same listener APIs are available on PlanetKitConference.
関連API
オーディオルート制御に関連するAPIは次のとおりです。