Skip to main content
Version: 7.1

Camera control

This guide explains camera behavior and management in PlanetKit, including:

  • How PlanetKit internally determines when the camera turns on or off based on video transmission, active previews, and call state
  • Camera functions that applications can control
Supported call typeMinimum SDK version
1-to-1 call, group call (conference)PlanetKit 5.5

Camera on/off behavior​

PlanetKit turns the camera on when at least one of the following conditions is met:

  • Video is being transmitted to the remote peer.
  • At least one camera preview is active.

The camera turns off only when neither condition is met.

Condition: One or more previews are activeCondition: Video is being transmittedResult: Camera device status
NoNoOff
YesNoOn
NoYesOn
YesYesOn

The following functions also affect the camera status:

  • Initial video state
    • The initial video transmission state is controlled by the value of initialMyVideoState property/parameter passed to makeCall(), acceptCall(), joinConference(), or enableVideo().
      • PlanetKitInitialMyVideoState.resume (default): Video starts active, camera turns on at call start.
      • PlanetKitInitialMyVideoState.pause: Video starts paused, camera stays off until resumeMyVideo() is called.
    • For more information on configuring the initial video state, see Initial video state.
  • Hold/unhold
    • Calling hold() turns the camera off and disables video transmission.
    • Calling unhold() turns the camera back on and enables video transmission.
    • For more information on holding/unholding the call, see Call hold.
  • Pause/resume video
    • Calling pauseMyVideo() turns the camera off and disables video transmission.
    • Calling resumeMyVideo() turns the camera back on and enables video transmission.
note

In a 1-to-1 video call, when the callee enters the responder preparation status before the call is fully connected, PlanetKit may turn the camera on before video is transmitted to the network. pauseMyVideo() and resumeMyVideo() toggle the camera normally during this phase, but actual video transmission only begins after preparation finishes.

Camera control functions​

PlanetKitCameraManager provides camera management APIs for switching camera devices, configuring capture preset and frame rate, starting and stopping previews, handling camera-related events.

Switch camera​

On macOS, enumerate available cameras from deviceInfos and call change(deviceInfo:) to select a specific device.

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:) throws PlanetKitNSErrorCode.cameraDeviceCannotBeSetWhileUsingCustomCamera if a custom video source is currently active.

Set capture preset and frame rate​

Configure preferredPreset and preferredFrameRate on a PlanetKitVideoCaptureDeviceInfo before passing it to change(deviceInfo:).

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 is of type PlanetKitCameraPreset, which is a typealias for AVCaptureSession.Preset. See Apple's documentation for all available values.

If the device does not support the specified preset, PlanetKit falls back to the nearest supported preset.

Camera preview​

You can start and stop a camera preview independently of a call using startPreview() and stopPreview().

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

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

Handle device change events​

Register a PlanetKitCameraDeviceChangeDelegate to be notified when cameras are connected, disconnected, or selected.

note

PlanetKit updates its internal camera state automatically when devices are connected or disconnected. Implement this delegate only if your app needs to update its UI — for example, to refresh a device selection list.

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)

Access the native camera device​

Focus, zoom, and exposure are not exposed as PlanetKit APIs. Access the underlying AVCaptureDevice directly for native control.

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)")
    }
}

APIs related to camera control are as follows:

Classes/protocols​

Enums​

Methods​

Events​