@snap/camera-kit/dist/session/CameraKitSession.d.ts

Camera Kit Web

import type { Observable } from "rxjs";
import type { Lens } from "../lens/Lens";
import type { LensLaunchData } from "../lens/LensLaunchData";
import { TypedEventTarget } from "../events/TypedEventTarget";
import type { CameraKitDeviceOptions, CameraKitSource } from "../media-sources/CameraKitSource";
import type { LogEntry } from "../logger/logger";
import type { PageVisibility } from "../common/pageVisibility";
import type { LensCore } from "../lens-core-module/lensCore";
import { LensPerformanceMetrics } from "./LensPerformanceMetrics";
import type { LensState } from "./lensState";
import type { SessionState } from "./sessionState";
import type { Keyboard, LensKeyboard } from "./LensKeyboard";
import type { CameraKitSessionEvents } from "./CameraKitSessionEvents";
import type { FrameEvent } from "./frameEvents";
import type { ScreenRegions } from "./screenRegions";
/**
 * Enumerates the supported render targets.
 *
 * Lenses may render to different render targets, as designed by the lens creator. In CameraKit, it's possible to choose
 * which render target to render, and the result for each target is available as a separate `<canvas>` element.
 *
 * @category Rendering
 * @category Lenses
 */
export type RenderTarget = "live" | "capture";
/**
 * A CameraKitSession represents a single rendering pipeline connecting an input media source to output `<canvas>`
 * elements. When a Lens is applied to the session, CameraKit uses the Lens to transform the input media into rendered
 * output.
 *
 * CameraKitSession is the primary object that applications interact with when integrating the CameraKit SDK.
 *
 * A CameraKitSession instance is obtained by calling {@link CameraKit.createSession}.
 *
 * @example
 * ```ts
 * const cameraKit = await bootstrapCameraKit(config)
 * const session = await cameraKit.createSession()
 * ```
 *
 * @category Rendering
 * @category Lenses
 */
declare class CameraKitSession {
    private readonly innerKeyboard;
    private readonly lensCore;
    private readonly sessionState;
    private readonly lensState;
    private frameEvents;
    /**
     * CameraKitSession renders video output to a `<canvas>` element. In fact, each session contains two canvas outputs
     * corresponding to the RenderTargets used by Lens creators, when using LensStudio to create a Lens.
     *
     * The `live` output renders content suitable for the Lens user (e.g. it may contain additional UI elements
     * applicable only to the person applying the lens). The `capture` output renders content suitable for sharing with
     * other users (e.g. sent to the other members of a video call, or saved to disk for sharing later).
     *
     * For many lenses, these outputs are identical – but each lens is free to render differently, based on its own
     * use-case.
     */
    readonly output: {
        live: HTMLCanvasElement;
        capture: HTMLCanvasElement;
    };
    /**
     * Indicates whether or not the session is currently rendering. If `false`, rendering is stopped. Otherwise the
     * value indicates which output is being rendered.
     */
    playing: {
        live: boolean;
        capture: boolean;
    };
    /**
     * Add event listeners here to handle events which occur during the CameraKitSession.
     *
     * **Note:** Applications may want to handle the `error` event, and check the contained error type -- if the type
     * is {@link LensExecutionError}, this means the current lens was unable to render and CameraKit will automatically
     * remove the lens.
     *
     * @example
     * ```ts
     * cameraKitSession.events.addEventListener('error', ({ detail }) => {
     *   if (detail.error.name === 'LensExecutionError') {
     *     console.log(`Lens ${detail.lens.name} encountered an error and was removed. Please pick a different lens.`)
     *   }
     * })
     * ```
     */
    readonly events: TypedEventTarget<CameraKitSessionEvents>;
    /**
     * Use this to measure current lens performance.
     */
    readonly metrics: LensPerformanceMetrics;
    /**
     * The {@link Keyboard} API enables applications to handle keyboard input requests from lenses.
     * When a lens requests a keyboard, the app displays it in its preferred UI. As users type,
     * the app sends the text back to the lens for display. The lens can also request keyboard dismissal,
     * prompting the app to remove the displayed keyboard.
     */
    readonly keyboard: Keyboard;
    private readonly removePageVisibilityHandlers;
    private source?;
    private subscriptions;
    /**
     * @internal
     */
    constructor(innerKeyboard: LensKeyboard, lensCore: LensCore, sessionState: SessionState, lensState: LensState, logEntries: Observable<LogEntry>, pageVisibility: PageVisibility, frameEvents: Observable<FrameEvent>);
    /**
     * Apply a Lens to this session.
     *
     * This method will download (and cache) the Lens executable, and then use that Lens for rendering. If the session
     * is currently playing, this will immediately update the rendered output. Otherwise, the new Lens will be used
     * when session playback in resumed.
     *
     * Calling `applyLens` replaces any prior Lens – only one Lens is allowed at a time (per session).
     *
     * **NOTE**: Errors may occur after the Lens is applied. If the Lens encounters errors while rendering,
     * Camera Kit will automatically remove the Lens from the session and emit a {@link LensExecutionError} event.
     * Applications may want to listen for this error and, for example,
     * prevent the Lens from being selected again by the user.
     *
     * ```ts
     * session.events.addEventListener("error", ({ detail }) => {
     *   if (detail.error.name === "LensExecutionError") {
     *     preventFutureLensSelection(detail.lens);
     *     showMessage("We're sorry, but the Lens you selected encountered an error. Please choose a different Lens.");
     *   }
     * });
     * ```
     *
     * @param lens The Lens to apply to this session.
     * @param launchData This can optionally be provided to pass some initial data to the Lens – only certain Lenses
     * expect launch data.
     * @returns A promise which can have the following results:
     * 1. Resolved with `true`: the Lens has been applied.
     * 2. Resolved with `false`: the Lens has not been applied, but no error occurred – this can happen if a
     * subsequent call to `applyLens` interrupted the Lens application.
     * 3. Rejected: the Lens has not been applied because an error occurred. This can happen if:
     *   - The Lens ID cannot be found in the LensRepository (use LensRepository to load the Lens before calling this
     *     method)
     *   - Lens content download fails, or the download of any required lens assets fails.
     *   - An internal failure occurs in the Lens rendering engine when attempting to apply the Lens.
     */
    applyLens(lens: Lens, launchData?: LensLaunchData): Promise<boolean>;
    /**
     * Remove a Lens from this session.
     *
     * When a Lens is removed, rendering continues if the session is playing. It will just render the session input
     * directly to the outputs without any image processing.
     *
     * @returns A promise which can have the following results:
     * 1. Resolved with `true`: the session's rendered output has no lens applied.
     * 2. Resolved with `false`: the current lens has been removed, but a subsequent call to `applyLens` means that the
     * session's rendered output will still have a (new) lens applied.
     * 3. Rejected: the lens has failed to be removed. This can happen if an internal failure occurs in the Lens
     * rendering engine when attempting to remove the lens.
     */
    removeLens(): Promise<boolean>;
    /**
     * Start/resume session playback – LensCore will begin rendering frames to the output.
     *
     * If no source has been set for the session, calling `play()` will update the playing state, but no actual image
     * processing will occur until `setSource()` is called.
     *
     * @example
     * ```ts
     * const cameraKitSession = await cameraKit.createSession()
     * await cameraKitSession.setSource(mySource)
     * await cameraKitSession.play()
     *
     * // If you call `play` before `setSource`, the call to `play` will resolve but playback will only begin once a
     * // media source has been set.
     * ```
     *
     * @param target Specify the {@link RenderTarget} to render. Defaults to the `live` RenderTarget.
     * @returns Promise resolves when playback state has been updated. If no source has been set, this means `play` will
     * resolve before any frames are processed -- but once a source is set, frames will immediately begin processing.
     */
    play(target?: RenderTarget): Promise<void>;
    /**
     * Pause session playback – LensCore will stop rendering frames to the output.
     *
     * @param target Specify the RenderTarget to pause playback. May be either `'live'` or `'capture'`.
     * Default is `'live'`.
     * @returns Promise resolves when playback has stopped.
     */
    pause(target?: RenderTarget): Promise<void>;
    /**
     * Mute all sounds (default SDK state is unmuted).
     *
     * @param fade Do we want audio to fade out?
     */
    mute(fade?: boolean): void;
    /**
     * Unmute all sounds.
     *
     * @param fade Do we want audio to fade in?
     */
    unmute(fade?: boolean): void;
    /**
     * Set the media source for this session.
     *
     * Sessions may only have one source at a time - if `setSource` is called multiple times, subsequent calls replace
     * the prior source. Setting the source does not trigger rendering (that’s done by `session.play()`). If the session
     * is already playing, setting the source will immediately begin rendering the new source.
     *
     * The CameraKit SDK provides implementations for various common sources, which applications can create using the
     * following functions:
     * - {@link createMediaStreamSource}
     * - {@link createVideoSource}
     * - {@link createImageSource}
     *
     * **Important:** Once a source has been set for a session, it cannot be set again, even if it has been replaced
     * by another one. You must provide a new instance of {@link CameraKitSource} to {@link CameraKitSession.setSource}.
     * If you want to reuse the existing source, you can use its {@link CameraKitSource.copy} method to create a new
     * instance.
     *
     * @param source A CameraKitSource object representing input media (e.g. a webcam stream, video, or some other
     * source of image data), which CameraKit will supply to Lenses in order for them to render effects on top of that
     * source.
     * @returns Promise is resolved when the source has successfully been set. If the session was already in the playing
     * state, the Promise resolves when the first frame from the new source has been rendered. The resolved value is
     * the {@link CameraKitSource} object attached to the session.
     */
    setSource(source: CameraKitSource): Promise<CameraKitSource>;
    setSource(source: MediaStream | HTMLVideoElement, options?: Partial<CameraKitDeviceOptions>): Promise<CameraKitSource>;
    /**
     * Set an FPS limit.
     *
     * This may be useful to reduce CPU/GPU resource usage by CameraKit if, for example, the input
     * media source has a low FPS – CameraKit would then not try to render more frequently than the source produces
     * new frames.
     *
     * This may also be useful to gracefully degrade performance in situations where lowering FPS is preferable over
     * alternatives.
     *
     * @param fpsLimit A maximum FPS, rendering will not exceed this limit
     * @returns Promise is resolved when the limit is successfully set.
     */
    setFPSLimit(fpsLimit: number): Promise<void>;
    /**
     * Set screen regions for the current Lens.
     *
     * Screen regions define areas of the screen that have special meaning for Lens rendering,
     * such as safe rendering areas, UI button locations, keyboard areas, etc.
     * This allows lenses to adapt their content placement based on the host application's UI layout.
     *
     * Only the regions specified will be active - any previously set regions not included
     * will be automatically removed.
     *
     * @param regions Configuration object containing the current set of screen regions
     * @returns Promise that resolves when the screen regions have been successfully set
     */
    setScreenRegions(regions: ScreenRegions): Promise<void>;
    /**
     * Destroy the session.
     *
     * The session will become inoperable. Frame processing stops, and any session-scoped graphical resources are freed.
     */
    destroy(): Promise<void>;
    private renderTargetToCanvasType;
    private safelyDetachSource;
}
export { CameraKitSession };
/**
 * @internal
 */
export declare const cameraKitSessionFactory: {
    (args_0: LensCore, args_1: Observable<LogEntry>, args_2: LensKeyboard, args_3: import("@snap/state-management").StateMachine<import("@snap/state-management").Action<"suspend", CameraKitSession> | import("@snap/state-management").Action<"resume", CameraKitSession> | import("@snap/state-management").Action<"destroy", undefined>, import("@snap/state-management").State<"inactive", undefined> | import("@snap/state-management").State<"active", CameraKitSession> | import("@snap/state-management").State<"destroyed", undefined>>, args_4: import("@snap/state-management").StateMachine<import("@snap/state-management").Action<"applyLens", {
        lens: Lens;
        launchData?: LensLaunchData | undefined;
    }> | import("@snap/state-management").Action<"downloadComplete", Lens> | import("@snap/state-management").Action<"turnedOn", Lens> | import("@snap/state-management").Action<"resourcesLoaded", Lens> | import("@snap/state-management").Action<"firstFrameProcessed", Lens> | import("@snap/state-management").Action<"applyLensComplete", Lens> | import("@snap/state-management").Action<"applyLensFailed", {
        error: import("./lensState").LensErrors;
        lens: Lens;
    }> | import("@snap/state-management").Action<"applyLensAborted", Lens> | import("@snap/state-management").Action<"removeLens", undefined> | import("@snap/state-management").Action<"turnedOff", Lens> | import("@snap/state-management").Action<"removeLensComplete", undefined> | import("@snap/state-management").Action<"removeLensFailed", Error>, import("@snap/state-management").State<"noLensApplied", undefined> | import("@snap/state-management").State<"applyingLens", Lens> | import("@snap/state-management").State<"lensApplied", Lens>>, args_5: PageVisibility, args_6: Observable<FrameEvent>): CameraKitSession;
    token: "CameraKitSession";
    dependencies: readonly ["lensCore", "logEntries", "lensKeyboard", "sessionState", "lensState", "pageVisibility", "frameEvents"];
};
//# sourceMappingURL=CameraKitSession.d.ts.map