カメラ制御

このガイドでは、PlanetKitにおけるカメラの動作と管理について説明します。

• ビデオ送信、アクティブなプレビュー、通話状態に基づいてPlanetKitが内部的にカメラのオン/オフを決定する仕組み
• アプリケーションが制御できるカメラ機能

対応通話タイプ	最小SDKバージョン
1対1通話、グループ通話（カンファレンス）	PlanetKit 5.5

カメラのオン/オフ動作

PlanetKitは、以下の条件のうち少なくとも1つが満たされた場合にカメラをオンにします。

• リモートピアにビデオが送信されている。
• 少なくとも1つのカメラプレビューがアクティブである。

カメラがオフになるのは、どちらの条件も満たされていない場合のみです。

条件：1つ以上のプレビューがアクティブ	条件：ビデオが送信中	結果：カメラデバイスの状態
いいえ	いいえ	オフ
はい	いいえ	オン
いいえ	はい	オン
はい	はい	オン

以下の機能もカメラの状態に影響します。

• ビデオの初期状態
  • 初期ビデオ送信状態は、makeCall()、acceptCall()、joinConference()、またはenableVideo()に渡されるinitialMyVideoStateプロパティ/パラメーターの値によって制御されます。
    • PlanetKitInitialMyVideoState.RESUME（デフォルト）：ビデオはアクティブな状態で開始し、通話開始時にカメラがオンになります。
    • PlanetKitInitialMyVideoState.PAUSE：ビデオは一時停止状態で開始し、resumeMyVideo()が呼び出されるまでカメラはオフのままです。
  • ビデオの初期状態の設定の詳細については、ビデオの初期状態を参照してください。
• 通話の一時停止/再開
  • hold()を呼び出すとカメラがオフになり、ビデオ送信が無効になります。
  • unhold()を呼び出すとカメラが再びオンになり、ビデオ送信が有効になります。
  • 通話の保留/保留解除の詳細については、通話の一時停止を参照してください。
• ビデオの一時停止/再開
  • pauseMyVideo()を呼び出すとカメラがオフになり、ビデオ送信が無効になります。
  • resumeMyVideo()を呼び出すとカメラが再びオンになり、ビデオ送信が有効になります。

Note

1対1のビデオ通話において、通話が完全に接続される前に着信側が応答者の準備状態に入ると、PlanetKitはネットワークへのビデオ送信前にカメラをオンにすることがあります。pauseMyVideo()とresumeMyVideo()はこのフェーズ中も通常通りカメラを切り替えますが、実際のビデオ送信は準備が完了した後にのみ開始されます。

カメラ制御機能

PlanetKitCameraManagerは、カメラデバイスの切り替え、キャプチャー解像度の設定、プレビューの開始と停止、カメラ関連イベントの処理を行うカメラ管理APIを提供します。

カメラデバイスタイプ

PlanetKitは以下のカメラタイプをサポートしています。

タイプ	説明
FRONT	フロントカメラ
BACK	リアカメラ
EXTERNAL	USB外部カメラ（デバイス依存）

カメラの切り替え

アクティブなカメラを切り替えるには、PlanetKitCameraManagerのcameraTypeを設定します。

val cameraManager = PlanetKit.getCameraManager()

// Switch to back camera
cameraManager.cameraType = PlanetKitCameraType.BACK

// Switch to front camera
cameraManager.cameraType = PlanetKitCameraType.FRONT

カメラタイプが変更されたときに通知を受け取るには、CameraTypeChangedListenerを登録します。

val cameraTypeChangedListener = PlanetKitCameraManager.CameraTypeChangedListener { cameraType ->
    Log.d(TAG, "Camera type changed to: $cameraType")
}

cameraManager.addCameraTypeChangedListener(cameraTypeChangedListener)

// Unregister when no longer needed
cameraManager.removeCameraTypeChangedListener(cameraTypeChangedListener)

キャプチャー解像度の設定

特定のキャプチャー解像度を設定するには、setManualResolution()を呼び出します。デバイス最適なデフォルトに戻すには、setDefaultResolution()を呼び出します。

// Set resolution to VGA
cameraManager.setManualResolution(PlanetKitCameraResolution.VGA)

// Restore device-optimal default resolution
cameraManager.setDefaultResolution()

利用可能なPlanetKitCameraResolutionの値は以下のとおりです。

値	サイズ
QVGA	320×240
VGA	640×480
HD	1280×960

解像度が指定されていない場合、PlanetKitはデバイス最適なデフォルトを使用します。

カメラプレビュー

PlanetKitVideoViewとともにstartPreview()とstopPreview()を使用して、通話とは独立してカメラプレビューを開始・停止できます。

// Start preview
cameraManager.startPreview(videoView)

// Stop preview
cameraManager.stopPreview(videoView)

カメラ状態イベントの処理

StateListenerを登録して、カメラの開始、停止、エラーイベントを受け取ります。

val stateListener = object : PlanetKitCameraManager.StateListener {
    override fun onStart() {
        Log.d(TAG, "Camera started")
    }

    override fun onStop() {
        Log.d(TAG, "Camera stopped")
    }

    override fun onError(@PlanetKitCameraManager.StateListener.ErrorCode code: Int) {
        when (code) {
            PlanetKitCameraManager.StateListener.ERROR_CODE_EVICT -> {
                // Camera was taken over by another app
                Log.w(TAG, "Camera evicted by another app")
            }
            PlanetKitCameraManager.StateListener.ERROR_CODE_OPEN_FAIL -> {
                // Camera failed to open
                Log.e(TAG, "Camera failed to open")
            }
        }
    }
}

cameraManager.setStateListener(stateListener)

Note

カメラのオープンに失敗した場合、PlanetKitはonError()を通じてエラーを報告しますが、通話は接続を維持します。カメラが再び使用可能になるまでビデオキャプチャーは停止します。

USBカメラ（外部カメラ）の可用性の処理

外部カメラの可用性に関するイベントを受け取るには、UsbCameraAvailabilityListenerを登録します。イベントを使用する前に、デバイスが外部カメラをサポートしているか確認してください。

if (cameraManager.supportDeviceFeatureExternalCamera) {
    val usbListener = PlanetKitCameraManager.UsbCameraAvailabilityListener { isAvailable ->
        if (isAvailable) {
            Log.d(TAG, "External camera connected")
            // Switch to external camera if desired
            cameraManager.cameraType = PlanetKitCameraType.EXTERNAL
        } else {
            Log.d(TAG, "External camera disconnected")
            // Fall back to front or back camera
            cameraManager.cameraType = PlanetKitCameraType.FRONT
        }
    }

    cameraManager.addUsbCameraAvailabilityListener(usbListener)

    // Unregister when no longer needed
    cameraManager.removeUsbCameraAvailabilityListener(usbListener)
}

関連API

カメラ制御に関連するAPIは以下のとおりです。

クラス/インターフェース

• PlanetKitCameraManager
• PlanetKitCameraManager.CameraTypeChangedListener
• PlanetKitCameraManager.StateListener
• PlanetKitCameraManager.UsbCameraAvailabilityListener

列挙型

• PlanetKitCameraType
• PlanetKitCameraResolution
• PlanetKitCameraManager.StateListener.ErrorCode

メソッド

• PlanetKitCameraManagerのcameraType
• PlanetKitCameraManagerのsupportDeviceFeatureExternalCamera
• PlanetKitCameraManagerのsetManualResolution()
• PlanetKitCameraManagerのsetDefaultResolution()
• PlanetKitCameraManagerのstartPreview()
• PlanetKitCameraManagerのstopPreview()
• PlanetKitCameraManagerのaddCameraTypeChangedListener()
• PlanetKitCameraManagerのremoveCameraTypeChangedListener()
• PlanetKitCameraManagerのsetStateListener()
• PlanetKitCameraManagerのaddUsbCameraAvailabilityListener()
• PlanetKitCameraManagerのremoveUsbCameraAvailabilityListener()

イベント

• PlanetKitCameraManager.StateListenerのonStart
• PlanetKitCameraManager.StateListenerのonStop
• PlanetKitCameraManager.StateListenerのonError

関連ドキュメント

• ビデオの初期状態
• 1対1ビデオ通話
• グループビデオ通話
• ビデオ通話の有効化
• 通話の一時停止
• 応答者の準備状態
• カスタムビデオソース
• バーチャル背景