@snap/camera-kit 0.7.0

package/lib/session/CameraKitSession.d.ts

@@ -0,0 +1,252 @@
+import { Observable } from "rxjs";
+import { Lens } from "../lens";
+import { LensCoreModule } from "../lens-core-module";
+import { LensLaunchParams } from "../lens/LensLaunchParams";
+import { TypedEventTarget } from "../events/TypedEventTarget";
+import { CameraKitDeviceInfo, CameraKitSource } from "../media-sources/CameraKitSource";
+import { LogEntry } from "../logger/logger";
+import { LensPerformanceMetrics } from "./LensPerformanceMetrics";
+import { LensState } from "./lensState";
+import { SessionState } from "./sessionState";
+import { Keyboard, LensKeyboard } from "./LensKeyboard";
+import { CameraKitSessionEvents } from "./CameraKitSessionEvents";
+/**
+ * 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 declare 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
+ */
+export declare class CameraKitSession {
+    /**
+     * Use this to interact with lenses which require text input.
+     */
+    readonly keyboard: Keyboard;
+    private readonly lensCore;
+    private readonly sessionState;
+    private readonly lensState;
+    /**
+     * 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: false | RenderTarget;
+    /**
+     * 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;
+    private readonly removePageVisibilityHandlers;
+    private source?;
+    private subscriptions;
+    /**
+     * @internal
+     */
+    constructor(
+    /**
+     * Use this to interact with lenses which require text input.
+     */
+    keyboard: Keyboard, lensCore: LensCoreModule, sessionState: SessionState, lensState: LensState, logEntries: Observable<LogEntry>);
+    /**
+     * 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 launchParams: 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, launchParams?: LensLaunchParams): 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 createUserMediaSource}
+     * - {@link createMediaStreamSource}
+     * - {@link createVideoSource}
+     * - {@link createImageSource}
+     *
+     * @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 be 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<CameraKitDeviceInfo>): 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>;
+    /**
+     * 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;
+}
+/**
+ * @internal
+ */
+export declare const cameraKitSessionFactory: {
+    (args_0: LensCoreModule, 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").State<"inactive", undefined> | import("@snap/state-management").State<"active", CameraKitSession>>, args_4: import("@snap/state-management").StateMachine<import("@snap/state-management").Action<"applyLens", {
+        lens: Lens;
+        launchParams?: LensLaunchParams | 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<"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>>): CameraKitSession;
+    token: "CameraKitSession";
+    dependencies: readonly ["lensCore", "logEntries", "lensKeyboard", "sessionState", "lensState"];
+};