SessionConfig

public class SessionConfig

Known direct subclasses
ExtensionSessionConfig

A SessionConfig for extension sessions.
HighSpeedVideoSessionConfig

A SessionConfig for high-speed video recording sessions.

Represents the configuration for establishing and managing a camera session within CameraX.

When used with camera-lifecycle, this SessionConfig is expected to be used for starting a camera session (e.g. by being bound to the androidx.lifecycle.LifecycleOwner via androidx.camera.lifecycle.ProcessCameraProvider.bindToLifecycle API which allows the lifecycle events to start and stop the camera session with this given configuration).

It consists of a collection of UseCase, session parameters to be applied on the camera session, and common properties like the field-of-view defined by ViewPort, the CameraEffect, frame rate, required or preferred GroupableFeature groups etc.

Constraints

useCases: This cannot be empty.

frameRateRange:

requiredFeatureGroup and preferredFeatureGroup:

  • Avoid using non-groupable APIs for any feature that is groupable (see GroupableFeature to know which features are groupable). Doing so can lead to conflicting configurations.

  • Avoid setting multiple GroupableFeatures with the same GroupableFeature.featureType as required, as they conflict with each other. If they are set as preferred, only one will be selected according to the feature priorities, which are defined by the ordering in the preferredFeatureGroup list.

Not complying with these constraints will lead to an IllegalArgumentException. The following code sample explains this further.

import androidx.camera.core.CameraEffect
import androidx.camera.core.DynamicRange
import androidx.camera.core.ImageAnalysis
import androidx.camera.core.Preview
import androidx.camera.core.SessionConfig
import androidx.camera.core.featuregroup.GroupableFeature.Companion.FPS_60
import androidx.camera.core.featuregroup.GroupableFeature.Companion.HDR_HLG10
import androidx.camera.core.featuregroup.GroupableFeature.Companion.PREVIEW_STABILIZATION
import androidx.camera.video.GroupableFeatures.FHD_RECORDING
import androidx.camera.video.GroupableFeatures.UHD_RECORDING
import androidx.camera.video.Recorder
import androidx.camera.video.VideoCapture

// Create a session config where HDR is mandatory while 60 FPS (higher priority) and preview
// stabilization are optional
SessionConfig(
    useCases = listOf(Preview.Builder().build()),
    requiredFeatureGroup = setOf(HDR_HLG10),
    preferredFeatureGroup = listOf(FPS_60, PREVIEW_STABILIZATION),
)

// Creating the following SessionConfig will throw an exception as there are conflicting
// information. HDR is mentioned once as required and then again as preferred, it can't be both!
SessionConfig(
    useCases = listOf(Preview.Builder().build()),
    requiredFeatureGroup = setOf(HDR_HLG10),
    preferredFeatureGroup = listOf(FPS_60, HDR_HLG10),
)

// Creating the following SessionConfig will throw an exception as a groupable feature (HDR) is
// configured with non-grouping API while using grouping API as well. HDR is configured to the
// with a non-grouping API through the Preview use case, so it can't be grouped together
// properly with the other groupable features. Instead, it should be configured like the first
// SessionConfig construction in this code snippet.
SessionConfig(
    useCases =
        listOf(Preview.Builder().apply { setDynamicRange(DynamicRange.HLG_10_BIT) }.build()),
    preferredFeatureGroup = listOf(FPS_60, PREVIEW_STABILIZATION),
)

// Creating the following SessionConfig will throw an exception due to the conflicting
// information. The features UHD_RECORDING and FHD_RECORDING share the same type
// (FEATURE_TYPE_RECORDING_QUALITY), meaning both can't be simultaneously required. This is
// akin to requesting the final video recording size to be both UHD and FHD at the same time.
SessionConfig(
    useCases =
        listOf(Preview.Builder().build(), VideoCapture.withOutput(Recorder.Builder().build())),
    requiredFeatureGroup = setOf(HDR_HLG10, UHD_RECORDING, FHD_RECORDING),
    preferredFeatureGroup = listOf(FPS_60),
)

// Creating the following SessionConfig will throw an exception as ImageAnalysis is not yet
// supported with groupable features.
SessionConfig(
    useCases = listOf(ImageAnalysis.Builder().build()),
    requiredFeatureGroup = setOf(HDR_HLG10),
    preferredFeatureGroup = listOf(FPS_60, HDR_HLG10),
)

// Creating the following SessionConfig will throw an exception as CameraEffect is not yet
// supported with groupable features.
SessionConfig(
    useCases = listOf(Preview.Builder().build()),
    requiredFeatureGroup = setOf(HDR_HLG10),
    preferredFeatureGroup = listOf(FPS_60, HDR_HLG10),
    effects = effects,
)
Throws
kotlin.IllegalArgumentException

If the combination of config options are conflicting or unsupported, or if the useCases list is empty.
See also
bindToLifecycle

Summary

Nested types
public final class SessionConfig.Builder

Builder for SessionConfig

Public constructors

Creates the SessionConfig from use cases only.
SessionConfig(
    @NonNull List<@NonNull UseCase> useCases,
    ViewPort viewPort,
    @NonNull List<@NonNull CameraEffect> effects,
    @NonNull Range<@NonNull Integer> frameRateRange,
    @NonNull Set<@NonNull GroupableFeature> requiredFeatureGroup,
    @NonNull List<@NonNull GroupableFeature> preferredFeatureGroup
)

Public methods
final @NonNull List<@NonNull CameraEffect>

The list of CameraEffect to be applied on the camera session.
final @NonNull Consumer<@NonNull Set<@NonNull GroupableFeature>>

Gets the feature selection listener set to this session config.
final @NonNull Executor

Gets the executor set to this session config for feature selection listener invocation.
final @NonNull Range<@NonNull Integer>

The desired frame rate range for the camera session.
final @NonNull List<@NonNull GroupableFeature>

A list of preferred GroupableFeature ordered according to priority in descending order, i.e. a feature with a lower index in the list is considered to have a higher priority.
final @NonNull Set<@NonNull GroupableFeature>

A set of GroupableFeature that are mandatory for the camera session configuration.
final @NonNull List<@NonNull UseCase>

The list of UseCase to be attached to the camera and receive camera data.
final ViewPort

The ViewPort to be applied on the camera session.
final void

Sets a listener to know which features are finally selected when a session config is bound, based on the user-defined priorities/ordering for preferredFeatureGroup and device capabilities.
@NonNull String

Public constructors

SessionConfig

Added in 1.5.0
public SessionConfig(@NonNull UseCase... useCases)

Creates the SessionConfig from use cases only.

SessionConfig

public SessionConfig(
    @NonNull List<@NonNull UseCase> useCases,
    ViewPort viewPort,
    @NonNull List<@NonNull CameraEffect> effects,
    @NonNull Range<@NonNull Integer> frameRateRange,
    @NonNull Set<@NonNull GroupableFeature> requiredFeatureGroup,
    @NonNull List<@NonNull GroupableFeature> preferredFeatureGroup
)

Public methods

getEffects

Added in 1.5.0
public final @NonNull List<@NonNull CameraEffect> getEffects()

The list of CameraEffect to be applied on the camera session. If not set, the default is no effects.

getFeatureSelectionListener

Added in 1.5.0
public final @NonNull Consumer<@NonNull Set<@NonNull GroupableFeature>> getFeatureSelectionListener()

Gets the feature selection listener set to this session config.

See also
setFeatureSelectionListener

getFeatureSelectionListenerExecutor

Added in 1.5.0
public final @NonNull Executor getFeatureSelectionListenerExecutor()

Gets the executor set to this session config for feature selection listener invocation.

See also
setFeatureSelectionListener

getFrameRateRange

Added in 1.5.0
public final @NonNull Range<@NonNull Integer> getFrameRateRange()

The desired frame rate range for the camera session. If this value is not set, the default is FRAME_RATE_RANGE_UNSPECIFIED, which means no specific frame rate. The range defines the acceptable minimum and maximum frame rate for the camera session: - A dynamic range (e.g., [15, 30]) allows the camera to adjust its frame rate within the bounds, benefiting previewing in low light by enabling longer exposures for brighter, less noisy images. - Conversely, a fixed range (e.g., [30, 30]) ensures a stable frame rate crucial for video recording, though it can lead to darker, noisier video in low light due to shorter exposure times.

getPreferredFeatureGroup

Added in 1.5.0
public final @NonNull List<@NonNull GroupableFeature> getPreferredFeatureGroup()

A list of preferred GroupableFeature ordered according to priority in descending order, i.e. a feature with a lower index in the list is considered to have a higher priority. If not set, the default is an empty list. See SessionConfig.Builder.setPreferredFeatureGroup for more info.

getRequiredFeatureGroup

Added in 1.5.0
public final @NonNull Set<@NonNull GroupableFeature> getRequiredFeatureGroup()

A set of GroupableFeature that are mandatory for the camera session configuration. If not set, the default is an empty set. See SessionConfig.Builder.setRequiredFeatureGroup for more info.

getUseCases

Added in 1.5.0
public final @NonNull List<@NonNull UseCase> getUseCases()

The list of UseCase to be attached to the camera and receive camera data.

getViewPort

Added in 1.5.0
public final ViewPort getViewPort()

The ViewPort to be applied on the camera session. If not set, the default is no viewport.

setFeatureSelectionListener

Added in 1.5.0
public final void setFeatureSelectionListener(
    @NonNull Executor executor,
    @NonNull Consumer<@NonNull Set<@NonNull GroupableFeature>> listener
)

Sets a listener to know which features are finally selected when a session config is bound, based on the user-defined priorities/ordering for preferredFeatureGroup and device capabilities.

Both the required and the selected preferred features are notified to the listener. The listener is invoked when this session config is bound to camera (e.g. when the androidx.camera.lifecycle.ProcessCameraProvider.bindToLifecycle API is invoked). It is invoked even when no preferred features are selected, providing either the required features or an empty set (if no feature was set as required).

Alternatively, the CameraInfo.isSessionConfigSupported API can be used to query if a set of features is supported before binding.

Parameters
@NonNull Executor executor

The executor in which the listener will be invoked. If not set, the main thread is used by default.
@NonNull Consumer<@NonNull Set<@NonNull GroupableFeature>> listener

The consumer to accept the final set of features when they are selected.

toString

public @NonNull String toString()