カメラコントロール

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

カメラの切り替え

macOSでは、deviceInfosから利用可能なカメラを列挙し、change(deviceInfo:)を呼び出して特定のデバイスを選択します。

let cameraManager = PlanetKitCameraManager.shared

// List all available cameras
let cameras = cameraManager.deviceInfos
for camera in cameras {
    print("Camera: \(camera.name) (\(camera.uniqueID))")
}

// Select a specific camera
if let externalCamera = cameras.first(where: { $0.device.deviceType == .external }) {
    try cameraManager.change(deviceInfo: externalCamera)
}

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)

デバイス変更イベントの処理

カメラが接続、切断、または選択されたときに通知を受け取るには、PlanetKitCameraDeviceChangeDelegateを登録します。

Note

PlanetKitはデバイスが接続または切断されたときに内部のカメラ状態を自動的に更新します。このデリゲートは、アプリがUIを更新する必要がある場合（例えばデバイス選択リストを更新するなど）にのみ実装してください。

class MyCameraObserver: PlanetKitCameraDeviceChangeDelegate {
    func didCameraDeviceConnect(deviceInfo: PlanetKitVideoCaptureDeviceInfo) {
        print("Camera connected: \(deviceInfo.name)")
    }

    func didCameraDeviceDisconnect(deviceInfo: PlanetKitVideoCaptureDeviceInfo) {
        print("Camera disconnected: \(deviceInfo.name)")
        // Switch to another camera if needed
    }

    func didCameraDeviceSelect(deviceInfo: PlanetKitVideoCaptureDeviceInfo, preset: PlanetKitCameraPreset) {
        print("Camera selected: \(deviceInfo.name), preset: \(preset)")
    }
}

let observer = MyCameraObserver()
cameraManager.addDeviceChangeDelegate(observer)

// Remove when no longer needed
cameraManager.removeDeviceChangeDelegate(observer)

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

フォーカス、ズーム、露出は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

• PlanetKitCameraDeviceChangeDelegate

列挙型

• 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のaddDeviceChangeDelegate(_:)
• PlanetKitCameraManagerのremoveDeviceChangeDelegate(_:)

イベント

• PlanetKitCameraDeviceChangeDelegateのdidCameraDeviceConnect(deviceInfo:)
• PlanetKitCameraDeviceChangeDelegateのdidCameraDeviceDisconnect(deviceInfo:)
• PlanetKitCameraDeviceChangeDelegateのdidCameraDeviceSelect(deviceInfo:preset:)

関連ドキュメント

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