Skip to main content

CameraModule.CaptureSession

Class

Still-capture camera session for SPECS.

  • Snapchat: not supported
  • SPECS: fully supported
  • Camera Kit Web: not supported
  • Camera Kit Mobile: not supported
1 platform note
  • SnapchatNot supported — Available on SPECS only
  • SPECSFully supported
    • Restricted when the Lens uses internet-connected APIs (see Privacy Restrictions).
  • Camera Kit WebNot supported — Available on SPECS only
  • Camera Kit MobileNot supported — Available on SPECS only

Platform details

  • Snapchat — Not supported — Available on SPECS only.

  • SPECS — Fully supported. Restricted when the Lens uses internet-connected APIs (see Privacy Restrictions)

  • Camera Kit Web — Not supported — Available on SPECS only.

  • Camera Kit Mobile — Not supported — Available on SPECS only.

Since Lens Scripting v368Exposes user data

Still-capture camera session for SPECS. Created via CameraModule#createCaptureSession. After CameraModule.CaptureSession#start pre-warms the pipeline, individual snapshots are triggered with CameraModule.CaptureSession#capture, which returns a Promise that resolves with the captured Frame.

Index

Remarks

start() prepares the capture pipeline and the first capture() also pays for warm-up, so start the session early (e.g. on Lens load) rather than at shutter press. Later captures resolve faster; larger and MFNR captures take longer.

To save power, the camera service ends a capture session that has gone 60 seconds without a capture. CameraModule.CaptureSession#onStatusChanged reports Disconnected, and later capture() calls reject. Each capture() restarts the 60-second timer. After Disconnected, create a new session to capture again.

Sessions are restartable: stop() releases the camera, start() can be called again with a new (or the same) StreamConfig.

Example

//@input Component.MeshVisual mesh

let cameraModule = require('LensStudio:CameraModule');
let session = cameraModule.createCaptureSession();

// Select the largest JPEG snapshot capability on the RGB camera.
let rgb = cameraModule.getCameras().find(function (c) { return c.type == CameraModule.CameraType.Rgb; });
let stream = rgb && rgb.getStreams().find(function (s) {
return s.operation == CameraModule.Operation.Capture && s.imageFormat == CameraModule.ImageFormat.Jpeg;
});
let ready = false;
if (stream) {
let config = new CameraModule.StreamConfig();
config.stream = stream;
ready = session.start(config) == CameraModule.Result.Success; // pre-warm at Lens start
}
if (!ready) print('Capture unavailable');

session.onStatusChanged.add(function (status) {
if (status == CameraModule.StreamStatus.Disconnected) ready = false; // create a new session
});

// One capture may be in flight at a time.
let busy = false;
async function takePhoto() {
if (!ready || busy) return;
busy = true;
try {
let frame = await session.capture();
if (frame.texture) script.mesh.mainPass.baseTex = frame.texture;
} catch (e) {
print('Capture failed: ' + e);
} finally {
busy = false;
}
}

// Capture two seconds after start; call takePhoto() from your own trigger instead.
let delay = script.createEvent('DelayedCallbackEvent');
delay.bind(takePhoto);
delay.reset(2);

Extends

Properties

onStatusChanged

readonly onStatusChanged: event1<StreamStatus, void>

Exposes user dataSPECS

Event triggered when session status changes (interruption, disconnection).

Since

Lens Scripting Version 368

Methods

capture()

capture(overrides?): Promise<Frame>

Exposes user dataSPECS

Trigger a single still capture. Returns a Promise that resolves with the captured CameraModule.Frame once the frame is delivered. The first capture after start() includes pipeline warm-up (up to 0.9 s measured on SPECS); later captures typically resolve within a few hundred ms.

Only one capture may be in flight per session: await the returned Promise before calling capture() again.

The Promise rejects when:

  • the session is not started or was stopped/disconnected,
  • another capture is already in flight,
  • the crop (session default or override) is not finite,
  • the camera service rejects the request,
  • stop() is called before the frame lands,
  • no frame is delivered within 30 seconds (pipeline stall backstop).

If the camera service delivers a frame whose image data cannot be read, the Promise still resolves, with a Frame whose CameraModule.Frame#texture and CameraModule.Frame#imageData are null; check before using them.

Parameters

ParameterTypeDescription
overrides?StreamConfigOverridesOptional per-shot overrides (e.g. crop region). Pass null or omit to use the session's defaults; an empty overrides object does not clear the session's crop.

Returns

Promise<Frame>

Promise resolving with the captured Frame.

Since

Lens Scripting Version 368


getTypeName()

static getTypeName(): TypeName<CaptureSession>

Exposes user dataSPECS

Returns the fully-qualified JavaScript type name for this class (for example, "Component.Camera"). This is a static accessor (no instance required) and returns the same value as the instance getTypeName().

Returns

TypeName<CaptureSession>

Since

Lens Scripting Version 368

Overrides

ScriptObject.getTypeName


getTypeName()

getTypeName(): string

Returns the name of this object's type.

Returns

string

Inherited from

ScriptObject.getTypeName


isOfType()

isOfType(type): boolean

Returns true if the object matches or derives from the passed in type.

Parameters

ParameterType
typestring

Returns

boolean

Inherited from

ScriptObject.isOfType


isSame()

isSame(other): boolean

Returns true if this object is the same as other. Useful for checking if two references point to the same thing.

Parameters

ParameterType
otherScriptObject

Returns

boolean

Inherited from

ScriptObject.isSame


start()

start(config?): Result

Exposes user dataSPECS

Pre-warm the capture pipeline. Call early (e.g. on Lens load) for low shutter latency. No frames are delivered until CameraModule.CaptureSession#capture is invoked.

Throws when only one of outputWidth and outputHeight is set, when the still size is larger than the stream, or when minFrameRate, rounded up to a whole Hz, exceeds the stream's maxFrameRate.

Parameters

ParameterTypeDescription
config?StreamConfigStream configuration whose stream's operation is Capture. Its crop is the default for every capture unless a capture overrides it.

Returns

Result

Success if the pipeline is ready for capture(). AlreadyStarted if it is already running; SessionStopped after a Disconnected status (create a new session); InvalidArgument for a missing stream, invalid tuning values or a non-finite crop; InvalidConfig when the stream's operation is not Capture or the camera has no stills; NotInitialized when the session's camera client is not available; ErrorGeneric when the camera service cannot be reached or cannot open the camera, or the Lens already has a started capture session or more than one started streaming session.

Since

Lens Scripting Version 368


stop()

stop(): Result

Exposes user dataSPECS

Stop the session and release the underlying capture pipeline. Restartable: call CameraModule.CaptureSession#start again. A pending capture() rejects.

Returns

Result

Success; NotStarted when the session is not running; SessionStopped after a Disconnected status.

Since

Lens Scripting Version 368