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 resolution, starting and stopping previews, handling camera-related events.

Camera device types​

PlanetKit supports the following camera types:

TypeDescription
FRONTFront-facing camera
BACKRear-facing camera
EXTERNALUSB external camera (device-dependent)

Switch camera​

To switch the active camera, set cameraType on PlanetKitCameraManager.

val cameraManager = PlanetKit.getCameraManager()

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

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

To be notified when the camera type changes, register a 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)

Set capture resolution​

To set a specific capture resolution, call setManualResolution(). To revert to the device-optimal default, call setDefaultResolution().

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

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

Available PlanetKitCameraResolution values are as follows:

ValueDimensions
QVGA320×240
VGA640×480
HD1280×960

If no resolution is specified, PlanetKit uses the device-optimal default.

Camera preview​

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

// Start preview
cameraManager.startPreview(videoView)

// Stop preview
cameraManager.stopPreview(videoView)

Handle camera state events​

Register a StateListener to receive camera start, stop, and error events.

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

When a camera fails to open, PlanetKit reports the error through onError() but keeps the call connected. Video capture stops until the camera becomes available again.

Handle USB camera (external camera) availability​

Register a UsbCameraAvailabilityListener to receive events related to external camera availability. Before using the events, verify that the device supports external cameras.

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

APIs related to camera control are as follows:

Classes/interfaces​

Enums​

Methods​

Events​