CameraModule.CaptureSession
ClassStill-capture camera session for SPECS.
- Snapchat: not supported
- SPECS: fully supported
- Camera Kit Web: not supported
- Camera Kit Mobile: not supported
- 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
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
Properties
Methods
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
readonlyonStatusChanged: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
| Parameter | Type | Description |
|---|---|---|
overrides? | StreamConfigOverrides | Optional 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()
staticgetTypeName():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
getTypeName()
getTypeName():
string
Returns the name of this object's type.
Returns
string
Inherited from
isOfType()
isOfType(
type):boolean
Returns true if the object matches or derives from the passed in type.
Parameters
| Parameter | Type |
|---|---|
type | string |
Returns
boolean
Inherited from
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
| Parameter | Type |
|---|---|
other | ScriptObject |
Returns
boolean
Inherited from
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
| Parameter | Type | Description |
|---|---|---|
config? | StreamConfig | Stream configuration whose stream's operation is Capture. Its crop is the default for every capture unless a capture overrides it. |
Returns
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
Success; NotStarted when the session is not running; SessionStopped after a Disconnected status.
Since
Lens Scripting Version 368