Interface IChoreoSDK

The main SDK interface that external apps use to interact with Choreo Display. Both the real SDK and mock SDK implement this interface.

interface IChoreoSDK {
    log: {
        debug(
            message: string,
            context?: Record<string, unknown>,
        ): Promise<{ ok: boolean }>;
        error(
            message: string,
            context?: Record<string, unknown>,
        ): Promise<{ ok: boolean }>;
        info(
            message: string,
            context?: Record<string, unknown>,
        ): Promise<{ ok: boolean }>;
        warn(
            message: string,
            context?: Record<string, unknown>,
        ): Promise<{ ok: boolean }>;
        (
            level: "error" | "debug" | "info" | "warn",
            message: string,
            context?: Record<string, unknown>,
        ): Promise<{ ok: boolean }>;
    };
    destroy(): void;
    detectFace(
        imageBitmap: ImageBitmap,
        options?: FaceDetectionOptions,
    ): Promise<FaceDetectionResult>;
    detectFacePresence(
        imageBitmap: ImageBitmap,
        options?: FaceDetectionOptions,
    ): Promise<FacePresenceResult>;
    exitApp(options?: ExitOptions): Promise<ExitResult>;
    generateQRCode(
        options?: { content?: string; recordingId?: string },
    ): Promise<QRCodeResult>;
    getCameraStream(
        options?: { height?: number; width?: number },
    ): Promise<CameraStreamInfo>;
    getConfig(): Promise<SDKConfig>;
    getRecording(recordingId?: string): Promise<RecordingInfo>;
    getRecordingStatus(): Promise<RecordingStatus>;
    getSelectedCamera(): Promise<CameraInfo>;
    getUploadStatus(taskId: string): Promise<UploadStatus>;
    getVideos(): Promise<VideoInfo[]>;
    getVideoUrl(videoId: string): Promise<string>;
    isReady(): boolean;
    listVideos(): Promise<VideoInfo[]>;
    navigateTo(slideId: string): Promise<NavigateResult>;
    off<T extends SDKEventType>(
        event: T,
        callback: (data: SDKEventData[T]) => void,
    ): void;
    on<T extends SDKEventType>(
        event: T,
        callback: (data: SDKEventData[T]) => void,
    ): void;
    once<T extends SDKEventType>(
        event: T,
        callback: (data: SDKEventData[T]) => void,
    ): void;
    playVideo(videoId: string): Promise<PlayVideoResult>;
    queueUpload(
        options: { recordingId?: string; uploadUrl: string },
    ): Promise<UploadResult>;
    ready(): Promise<boolean>;
    releaseCamera(): Promise<void>;
    releaseUrl(url: string): void;
    startRecording(
        options?: { durationMs?: number },
    ): Promise<RecordingStartResult>;
    stopRecording(): Promise<StopRecordingResult>;
}

Properties

log

Methods

destroy detectFace detectFacePresence exitApp generateQRCode getCameraStream getConfig getRecording getRecordingStatus getSelectedCamera getUploadStatus getVideos getVideoUrl isReady listVideos navigateTo off on once playVideo queueUpload ready releaseCamera releaseUrl startRecording stopRecording

Properties

log

log: {
    debug(
        message: string,
        context?: Record<string, unknown>,
    ): Promise<{ ok: boolean }>;
    error(
        message: string,
        context?: Record<string, unknown>,
    ): Promise<{ ok: boolean }>;
    info(
        message: string,
        context?: Record<string, unknown>,
    ): Promise<{ ok: boolean }>;
    warn(
        message: string,
        context?: Record<string, unknown>,
    ): Promise<{ ok: boolean }>;
    (
        level: "error" | "debug" | "info" | "warn",
        message: string,
        context?: Record<string, unknown>,
    ): Promise<{ ok: boolean }>;
}

Send a log message to the parent app's logger (Sentry + console). Logs are tagged with source: 'external-app', the app URL, and slide name. Silently fails if the parent doesn't support the log method (backward compatible).

Type declaration

    • (
          level: "error" | "debug" | "info" | "warn",
          message: string,
          context?: Record<string, unknown>,
      ): Promise<{ ok: boolean }>

    • Parameters

      • level: "error" | "debug" | "info" | "warn"

        Log level: 'debug', 'info', 'warn', 'error'

      • message: string

        Log message

      • Optionalcontext: Record<string, unknown>

        Optional context data

      Returns Promise<{ ok: boolean }>

  • debug:function
    • debug(
          message: string,
          context?: Record<string, unknown>,
      ): Promise<{ ok: boolean }>

    • Debug log (console only, not sent to Sentry)

      Parameters

      • message: string
      • Optionalcontext: Record<string, unknown>

      Returns Promise<{ ok: boolean }>

  • error:function
    • error(
          message: string,
          context?: Record<string, unknown>,
      ): Promise<{ ok: boolean }>

    • Error log (sent to Sentry Logs + creates Sentry issue)

      Parameters

      • message: string
      • Optionalcontext: Record<string, unknown>

      Returns Promise<{ ok: boolean }>

  • info:function
    • info(
          message: string,
          context?: Record<string, unknown>,
      ): Promise<{ ok: boolean }>

    • Info log

      Parameters

      • message: string
      • Optionalcontext: Record<string, unknown>

      Returns Promise<{ ok: boolean }>

  • warn:function
    • warn(
          message: string,
          context?: Record<string, unknown>,
      ): Promise<{ ok: boolean }>

    • Warning log (sent to Sentry Logs)

      Parameters

      • message: string
      • Optionalcontext: Record<string, unknown>

      Returns Promise<{ ok: boolean }>

Example

await sdk.log('info', 'Face detected', { phase: 3 });
await sdk.log('error', 'Camera failed', { error: 'NotAllowedError' });

Methods

destroy

  • destroy(): void

  • Destroy SDK-owned runtime resources. Revokes all tracked blob URLs and removes event listeners.

    Returns void

detectFace

  • detectFace(
        imageBitmap: ImageBitmap,
        options?: FaceDetectionOptions,
    ): Promise<FaceDetectionResult>

  • Run full face detection on an ImageBitmap. Returns a 128-D descriptor (ArrayBuffer) and bounding box. The parent hosts the face-api.js worker — models persist across iframe reloads.

    Parameters

    Returns Promise<FaceDetectionResult>

    Example

    const bitmap = await createImageBitmap(canvas);
    const { descriptor, box } = await sdk.detectFace(bitmap);
    if (descriptor) {
      const vec = new Float32Array(descriptor);
    }

detectFacePresence

  • detectFacePresence(
        imageBitmap: ImageBitmap,
        options?: FaceDetectionOptions,
    ): Promise<FacePresenceResult>

  • Run lightweight face presence detection (no descriptor). Faster than detectFace — use for "is someone there?" checks.

    Parameters

    Returns Promise<FacePresenceResult>

    Example

    const bitmap = await createImageBitmap(canvas);
    const { detected } = await sdk.detectFacePresence(bitmap);

exitApp

  • exitApp(options?: ExitOptions): Promise<ExitResult>

  • Exit the external app and signal result to the gallery. The gallery configuration maps results to target slides.

    Parameters

    Returns Promise<ExitResult>

    Example

    // Success - gallery navigates to success slide
    await sdk.exitApp({ result: 'success' });

    // Error with data
    await sdk.exitApp({ result: 'error', data: { message: 'Failed' } });

generateQRCode

  • generateQRCode(
        options?: { content?: string; recordingId?: string },
    ): Promise<QRCodeResult>

  • Generate a QR code. If no options provided, generates QR for the last recording.

    Parameters

    • Optionaloptions: { content?: string; recordingId?: string }

    Returns Promise<QRCodeResult>

getCameraStream

  • getCameraStream(
        options?: { height?: number; width?: number },
    ): Promise<CameraStreamInfo>

  • Get camera stream info. The parent window manages the actual MediaStream.

    Parameters

    • Optionaloptions: { height?: number; width?: number }

    Returns Promise<CameraStreamInfo>

getConfig

getRecording

  • getRecording(recordingId?: string): Promise<RecordingInfo>

  • Get a recording by ID for playback. If no recordingId provided, returns the last recording.

    Parameters

    • OptionalrecordingId: string

    Returns Promise<RecordingInfo>

getRecordingStatus

getSelectedCamera

getUploadStatus

getVideos

getVideoUrl

  • getVideoUrl(videoId: string): Promise<string>

  • Get URL for a specific video.

    Parameters

    • videoId: string

    Returns Promise<string>

isReady

  • isReady(): boolean

  • Check if the SDK is ready.

    Returns boolean

listVideos

navigateTo

off

on

once

playVideo

queueUpload

  • queueUpload(
        options: { recordingId?: string; uploadUrl: string },
    ): Promise<UploadResult>

  • Queue a recording for background upload. The upload will continue even if the tab is closed.

    Parameters

    • options: { recordingId?: string; uploadUrl: string }

    Returns Promise<UploadResult>

ready

  • ready(): Promise<boolean>

  • Wait for the SDK to be ready. Call this before using any other SDK methods.

    Returns Promise<boolean>

    true when ready

releaseCamera

  • releaseCamera(): Promise<void>

  • Release the camera stream.

    Returns Promise<void>

releaseUrl

  • releaseUrl(url: string): void

  • Release a SDK-managed blob URL when the app is done with it. Safe to call multiple times.

    Parameters

    • url: string

    Returns void

startRecording

  • startRecording(options?: { durationMs?: number }): Promise<RecordingStartResult>

  • Start recording from the camera. Recording will automatically stop after the specified duration. Listen for 'recordingComplete' event for the result.

    Parameters

    • Optionaloptions: { durationMs?: number }

    Returns Promise<RecordingStartResult>

stopRecording

Settings

Member Visibility

On This Page

Properties
Methods