カメラ制御

このガイドでは、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を提供します。

カメラの切り替え

iOSでは、switchPosition()を呼び出してフロントカメラとバックカメラを切り替えるか、change(deviceInfo:)を呼び出してdeviceInfosから特定のデバイスを選択します。

let cameraManager = PlanetKitCameraManager.shared

// Toggle between front and back
cameraManager.switchPosition()

// Or switch to a specific device
if let backCamera = cameraManager.deviceInfos.first(where: { $0.cameraPosition == .back }) {
    try cameraManager.change(deviceInfo: backCamera)
}

change(deviceInfo:)は、カスタムビデオソースが現在アクティブな場合、PlanetKitNSErrorCode.cameraDeviceCannotBeSetWhileUsingCustomCameraをスローします。

キャプチャープリセットとフレームレートの設定

change(deviceInfo:)に渡す前に、PlanetKitVideoCaptureDeviceInfoのpreferredPresetとpreferredFrameRateを設定します。

guard let deviceInfo = cameraManager.deviceInfos.first else { return }

// Set preferred capture preset (resolution)
deviceInfo.preferredPreset = .hd1280x720   // default

// Set preferred frame rate
deviceInfo.preferredFrameRate = PlanetKitFrameRate(minFps: 15, maxFps: 30)  // default max: 30fps

try cameraManager.change(deviceInfo: deviceInfo)

preferredPresetはPlanetKitCameraPreset型で、AVCaptureSession.Presetのtypealiasです。利用可能なすべての値についてはAppleのドキュメントを参照してください。

デバイスが指定されたプリセットをサポートしていない場合、PlanetKitは最も近いサポートされているプリセットにフォールバックします。

カメラプレビュー

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

// Start preview — pass a delegate that receives PlanetKitVideoBuffer frames
cameraManager.startPreview(delegate: myVideoOutputDelegate)

// Stop preview
cameraManager.stopPreview(delegate: myVideoOutputDelegate)

カメラ割り込みの処理

iOSでは、別のアプリ（FaceTimeやカメラアプリなど）がビデオデバイスを占有した場合、アプリがバックグラウンドに移行した場合、またはシステムが熱圧力下にある場合にカメラの割り込みが発生します。PlanetKitCameraInterruptDelegateを登録して通知を受け取ります。

Note

PlanetKitはメディアパイプラインを維持するためにカメラの割り込みを内部的に処理します。このデリゲートは、アプリがUI上で反応する必要がある場合（例えば「ビデオ一時停止中」のオーバーレイを表示するなど）にのみ実装してください。

class MyCameraInterruptHandler: PlanetKitCameraInterruptDelegate {
    func camDidInterruptBegin(_ reason: AVCaptureSession.InterruptionReason) {
        print("Camera interrupted: \(reason)")
        // Update UI to indicate video is paused
    }

    func camDidInterruptEnd() {
        print("Camera interruption ended, capture resumed")
        // Restore UI
    }
}

let handler = MyCameraInterruptHandler()
cameraManager.addInterruptReceiver(handler)

// Remove when no longer needed
cameraManager.removeInterruptReceiver(handler)

ネイティブカメラデバイスへのアクセス

フォーカス、ズーム、露出はPlanetKit APIとして公開されていません。ネイティブ制御のために、基盤となるAVCaptureDeviceに直接アクセスします。

if let deviceInfo = cameraManager.currentDeviceInfo {
    let avDevice = deviceInfo.device
    do {
        try avDevice.lockForConfiguration()
        // Example: set exposure mode
        if avDevice.isExposureModeSupported(.continuousAutoExposure) {
            avDevice.exposureMode = .continuousAutoExposure
        }
        avDevice.unlockForConfiguration()
    } catch {
        print("Failed to configure device: \(error)")
    }
}

関連API

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

クラス/プロトコル

• PlanetKitCameraManager
• PlanetKitVideoCaptureDeviceInfo
• PlanetKitFrameRate

• PlanetKitCameraInterruptDelegate

列挙型

• PlanetKitCameraPosition
• PlanetKitCameraPreset
• PlanetKitNSErrorCode

メソッド

• PlanetKitCameraManagerのshared
• PlanetKitCameraManagerのdeviceInfos
• PlanetKitCameraManagerのcurrentDeviceInfo
• PlanetKitCameraManagerのchange(deviceInfo:)
• PlanetKitCameraManagerのstartPreview(delegate:)
• PlanetKitCameraManagerのstopPreview(delegate:)
• PlanetKitVideoCaptureDeviceInfoのcameraPosition
• PlanetKitVideoCaptureDeviceInfoのpreferredPreset
• PlanetKitVideoCaptureDeviceInfoのpreferredFrameRate
• PlanetKitVideoCaptureDeviceInfoのdevice
• PlanetKitFrameRateのinit(minFps:maxFps:)
• PlanetKitNSErrorCodeのcameraDeviceCannotBeSetWhileUsingCustomCamera

• PlanetKitCameraManagerのswitchPosition()
• PlanetKitCameraManagerのaddInterruptReceiver(_:)
• PlanetKitCameraManagerのremoveInterruptReceiver(_:)

イベント

• PlanetKitCameraInterruptDelegateのcamDidInterruptBegin(_:)
• PlanetKitCameraInterruptDelegateのcamDidInterruptEnd()

関連ドキュメント

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