Enable multi-client cameras

You can enable multiple clients to simultaneously access a camera. To do so, use the Java and Android NDK system APIs described on this page to share access to system camera clients.

  • Primary client: Highest priority client among shared clients. A primary client can create capture requests and modify capture parameters.

  • Secondary client: All other shared clients are secondary clients. Secondary clients can't create capture requests nor can they modify capture parameters. Secondary clients can only send requests to start or stop streaming.

    For streaming, the camera service uses the default capture request parameters for the preview template. If the primary client is streaming, the service uses the capture request parameters specified by the primary client.

Configure a shared session

To share a camera device, provide the shared session configuration in the file named shared_session_config.xml located in /system_ext/etc/. In this code sample, camera ID 0 supports camera sharing with a configuration that includes two streams, ImageReader and SurfaceView.

<SharedCameraSessionConfigurations colorSpace="-1">
    <!-- colorSpace: ANDROID_REQUEST_AVAILABLE_COLOR_SPACE_PROFILES_MAP_UNSPECIFIED -->
    <SharedCameraSessionConfiguration cameraId="0">
        <!-- First OutputConfiguration: All optional fields are provided -->
        <OutputConfiguration>
            <!-- surfaceType: SURFACE_TYPE_IMAGE_READER -->
            <surfaceType>4</surfaceType>
            <width>1920</width>
            <height>1080</height>
            <!-- physicalCameraId is omitted; defaults to "" -->
            <!-- streamUseCase: ANDROID_SCALER_AVAILABLE_STREAM_USE_CASES_DEFAULT -->
            <streamUseCase>0</streamUseCase>
            <!-- timestampBase: TIMESTAMP_BASE_DEFAULT -->
            <timestampBase>0</timestampBase>
            <!-- mirrorMode: MIRROR_MODE_AUTO -->
            <mirrorMode>0</mirrorMode>
            <useReadoutTimestamp>0</useReadoutTimestamp>
            <!-- format: HAL_PIXEL_FORMAT_RGBA_8888 -->
            <format>1</format>
            <!-- usage: AHARDWAREBUFFER_USAGE_CPU_READ_OFTEN -->
            <usage>3</usage>
            <!-- dataSpace: HAL_DATASPACE_UNKNOWN -->
            <dataSpace>0</dataSpace>
        </OutputConfiguration>
        <!-- Second OutputConfiguration: All optional fields are provided -->
        <OutputConfiguration>
            <!-- surfaceType: SURFACE_TYPE_SURFACE_VIEW -->
            <surfaceType>0</surfaceType>
            <width>1920</width>
            <height>1080</height>
            <!-- physicalCameraId is omitted; defaults to "" -->
            <!-- streamUseCase: ANDROID_SCALER_AVAILABLE_STREAM_USE_CASES_DEFAULT -->
            <streamUseCase>0</streamUseCase>
            <!-- timestampBase: TIMESTAMP_BASE_DEFAULT -->
            <timestampBase>0</timestampBase>
            <!-- mirrorMode: MIRROR_MODE_AUTO -->
            <mirrorMode>0</mirrorMode>
            <useReadoutTimestamp>0</useReadoutTimestamp>
            <!-- format: HAL_PIXEL_FORMAT_IMPLEMENTATION_DEFINED -->
            <format>34</format>
            <!-- usage: AHARDWAREBUFFER_USAGE_GPU_SAMPLED_IMAGE|AHARDWAREBUFFER_USAGE_COMPOSER_OVERLAY -->
            <usage>256|2048</usage>
            <!-- dataSpace: HAL_DATASPACE_UNKNOWN -->

            <dataSpace>0</dataSpace>
        </OutputConfiguration>
      </SharedCameraSessionConfiguration>
</SharedCameraSessionConfigurations>

To query a shared session configuration, clients use CameraCharacteristics for SHARED_SESSION_CONFIGURATION. Clients that access a camera in shared mode must use the shared session configuration. When the session configuration passed by a client doesn't match the shared session configuration, a createCaptureSession call fails.

Java APIs

CameraManager and CameraDevice provide APIs to open cameras in shared mode.

CameraManager APIs

CameraManager provides these APIs:

CameraDevice.StateCallback APIs

CameraDevice.StateCallback provides these APIs:

  • onOpenedInSharedMode: Clients receive this callback when the camera is opened in shared mode. The callback indicates whether the client is the primary or secondary client.

  • onClientSharedAccessPriorityChanged: When a shared session is opened, this callback is triggered when a client's priority is changed because a higher priority client opened or closed the same camera.

CameraSharedCaptureSession

The CameraSharedCaptureSession class represents a shared capture session. In shared camera mode, a client that creates a session must use the SESSION_SHARED session type.

When the system creates a session, cast CameraCaptureSession to CameraSharedCaptureSession.

Secondary clients can't use createCaptureRequest. Instead, secondary clients use the startStreaming API to start streaming on specified surfaces and the stopStreaming API to stop streaming.

Android NDK APIs

Built-in apps use these Android NDK APIs to open a camera in shared mode:

Test shared cameras

See these tests specific to multi-client cameras:

Restrictions

Shared camera mode doesn't support these options:

  • Burst capture requests
  • Extension sessions
  • High-speed sessions
  • Offline sessions
  • OutputConfiguration with surface sharing
  • Reprocessable capture sessions
  • Third-party apps

When a higher priority client opens a camera in normal mode, the system evicts all shared camera clients.