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 iOS, call switchPosition() to toggle between front and back cameras, or call change(deviceInfo:) to select a specific device from 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:) 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 camera interruptions​

On iOS, camera interruptions occur when another app (such as FaceTime or the Camera app) takes the video device, when the app moves to the background, or when the system is under thermal pressure. Register a PlanetKitCameraInterruptDelegate to be notified.

note

PlanetKit handles camera interruptions internally to keep the media pipeline running. Implement this delegate only if your app needs to react in the UI — for example, by showing a "video paused" overlay.

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)

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​