CameraSession

interface CameraSession extends HybridObject

Represents a Camera Session.

A Camera Session can have CameraSessionConnections to stream from an input device (CameraDevice) to an output (CameraOutput).

It is recommended to configure the CameraSession properly before starting it (start()) to avoid reconfiguration hiccups.

You can create and use a Camera Session via the useCamera(...) hook, or by using the imperative APIs directly, which gives you more control over individual properties like mirrorMode per output, or multi-cam CameraSessions.

Examples

Create a Camera Session using the hooks:

const device = ...
const photoOutput = ...
const camera = useCamera({
  isActive: true,
  input: device,
  outputs: [photoOutput]
})

Create a single Camera Session using the imperative API:

const session = await HybridCameraFactory.createCameraSession(false)
const [controller] = await session.configure([
  {
    input: device,
    outputs: [
      { output: previewOutput, mirrorMode: 'auto' },
      { output: photoOutput, mirrorMode: 'auto' },
    ],
    config: {}
  }
])
await session.start()

Create a multi-cam Camera Session to stream from both the front-, and back-Camera using the imperative API:

if (HybridCameraFactory.supportsMultiCamSessions) {
  const session = await HybridCameraFactory.createCameraSession(true)
  const [frontController, backController] = await session.configure([
    // Front Camera
    {
      input: frontDevice,
      outputs: [
        { output: frontPreviewOutput, mirrorMode: 'on' },
        { output: frontPhotoOutput, mirrorMode: 'off' },
      ],
      config: {}
    },
    // Back Camera
    {
      input: backDevice,
      outputs: [
        { output: backPreviewOutput, mirrorMode: 'off' },
        { output: backPhotoOutput, mirrorMode: 'off' },
      ],
      config: {}
    }
  ])
  await session.start()
}

Properties

isRunning

readonly isRunning: boolean

Gets whether this CameraSession is currently running, or not.

Methods

addOnErrorListener()

addOnErrorListener(onError: (error: Error) => void): ListenerSubscription

Adds a listener to when the CameraSession encountered an error.

addOnInterruptionEndedListener()

addOnInterruptionEndedListener(onInterruptionEnded: () => void): ListenerSubscription

Adds a listener to when a CameraSession interruption has ended and the Camera continues to run again.

addOnInterruptionStartedListener()

addOnInterruptionStartedListener(onInterruptionStarted: (reason: InterruptionReason) => void): ListenerSubscription

Adds a listener to when the CameraSession was interrupted, for example when the phone overheated, or the user received a FaceTime call.

addOnStartedListener()

addOnStartedListener(onStarted: () => void): ListenerSubscription

Adds a listener to when the CameraSession started running.

addOnStoppedListener()

addOnStoppedListener(onStopped: () => void): ListenerSubscription

Adds a listener to when the CameraSession stopped running.

configure()

configure(connections: CameraSessionConnection[], config?: CameraSessionConfiguration): Promise<CameraController[]>

Configures the CameraSession with the given connections, and returns one CameraController per CameraSessionConnection.

One CameraSessionConnection defines a connection from one CameraDevice (the input) to multiple CameraOutputs (the outputs).

Parameters

connections

The list of connections from one input to multiple outputs. If this CameraSession was created as a multi-cam session (see createCameraSession(enableMultiCam)), you can add multiple CameraSessionConnections.

config

Configures session-wide configuration, such as CameraSessionConfiguration.automaticallyAdjustsColorSpace.

Returns

One CameraController per CameraSessionConnection.

Throws

If Camera Permission has not been granted - see CameraFactory.cameraPermissionStatus

Throws

If multiple connections are added, but the CameraSession was not created as a multi-cam session.

Examples

Creating a simple Preview + Photo connection:

const session = ...
const device = ...
const [controller] = await session.configure([
  {
    input: device,
    outputs: [
      { output: previewOutput, mirrorMode: 'auto' },
      { output: photoOutput, mirrorMode: 'auto' },
    ],
    config: {}
  }
])

Selecting a custom format:

const session = ...
const device = ...
const format = getCameraFormat(device, [
  { fps: 60 }
])
const [controller] = await session.configure([
  {
    input: device,
    outputs: [
      { output: previewOutput, mirrorMode: 'auto' },
      { output: photoOutput, mirrorMode: 'auto' },
    ],
    config: {
      format: format,
      fps: [format.maxFps, format.maxFps]
    }
  }
])
await session.start()

Creating a multi-cam session with front- and back Camera:

if (HybridCameraFactory.supportsMultiCamSessions) {
  const session = await HybridCameraFactory.createCameraSession(true)
  const [frontController, backController] = await session.configure([
    // Front Camera
    {
      input: frontDevice,
      outputs: [
        { output: frontPreviewOutput, mirrorMode: 'on' },
        { output: frontPhotoOutput, mirrorMode: 'off' },
      ],
      config: {}
    },
    // Back Camera
    {
      input: backDevice,
      outputs: [
        { output: backPreviewOutput, mirrorMode: 'off' },
        { output: backPhotoOutput, mirrorMode: 'off' },
      ],
      config: {}
    }
  ])
  await session.start()
}

start()

start(): Promise<void>

Starts the CameraSession.

To avoid any runtime hiccups, it's good practice to configure everything via configure(...) before starting the CameraSession.

stop()

stop(): Promise<void>

Stops the CameraSession.

On this page