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>;
    getAssets(): Promise<AssetInfo[]>;
    getAssetUrl(assetId: string): Promise<string>;
    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

`Optional`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 }>
  - Defined in index.ts:433
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 }>
  - Defined in index.ts:448
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 }>
  - Defined in index.ts:438
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 }>
  - Defined in index.ts:443

Example

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

Methods

`Optional`destroy

destroy?(): void
Tear down the SDK: clear caches, cancel timers, remove listeners. Safe to call multiple times. Optional — older SDK builds may not implement this.

Returns void
- Defined in index.ts:354

`Optional`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
- imageBitmap: ImageBitmap
- Optionaloptions: FaceDetectionOptions
Returns Promise<FaceDetectionResult>
Example
```
const bitmap = await createImageBitmap(canvas);
const { descriptor, box } = await sdk.detectFace(bitmap);
if (descriptor) {
  const vec = new Float32Array(descriptor);
}
```
- Defined in index.ts:470

`Optional`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
- imageBitmap: ImageBitmap
- Optionaloptions: FaceDetectionOptions
Returns Promise<FacePresenceResult>
Example
```
const bitmap = await createImageBitmap(canvas);
const { detected } = await sdk.detectFacePresence(bitmap);
```
- Defined in index.ts:483

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
- Optionaloptions: ExitOptions
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' } });
```
- Defined in index.ts:402

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>
- Defined in index.ts:382

getAssets

getAssets(): Promise<AssetInfo[]>
Get all files configured for this slide, in editor order. Resolves every cached file to an iframe-owned URL eagerly. Cache misses return network URLs, which require connectivity. URLs remain valid until releaseUrl(), destroy(), or iframe unload. Videos are included.

Returns Promise<AssetInfo[]>
- Defined in index.ts:254

getAssetUrl

getAssetUrl(assetId: string): Promise<string>
Get an iframe-usable URL for one configured asset. Rejects when the ID is not configured on this slide. The returned URL can be assigned to a media element or fetched to read JSON, text, or bytes.
Parameters
- assetId: string
Returns Promise<string>
- Defined in index.ts:261

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>
- Defined in index.ts:301

getConfig

getConfig(): Promise<SDKConfig>
Get SDK configuration.

Returns Promise<SDKConfig>
- Defined in index.ts:246

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>
- Defined in index.ts:338

getRecordingStatus

getRecordingStatus(): Promise<RecordingStatus>
Get current recording status.

Returns Promise<RecordingStatus>
- Defined in index.ts:332

getSelectedCamera

getSelectedCamera(): Promise<CameraInfo>
Get the selected camera info.

Returns Promise<CameraInfo>
- Defined in index.ts:295

getUploadStatus

getUploadStatus(taskId: string): Promise<UploadStatus>
Get upload status for a task.
Parameters
- taskId: string
Returns Promise<UploadStatus>
- Defined in index.ts:372

getVideos

getVideos(): Promise<VideoInfo[]>
Get all available videos configured for this slide.

Returns Promise<VideoInfo[]>
- Defined in index.ts:270

getVideoUrl

getVideoUrl(videoId: string): Promise<string>
Get URL for a specific video.
Parameters
- videoId: string
Returns Promise<string>
- Defined in index.ts:275

isReady

isReady(): boolean
Check if the SDK is ready.

Returns boolean
- Defined in index.ts:241

listVideos(): Promise<VideoInfo[]>
List all available videos (alias for getVideos).

Returns Promise<VideoInfo[]>
- Defined in index.ts:286

navigateTo

navigateTo(slideId: string): Promise<NavigateResult>
Navigate to another slide by ID.
Parameters
- slideId: string
Returns Promise<NavigateResult>
- Defined in index.ts:407

off

off<T extends SDKEventType>(
event: T,
callback: (data: SDKEventData[T]) => void,
): void
Unsubscribe from SDK events.
Type Parameters
- T extends SDKEventType
Parameters
- event: T
- callback: (data: SDKEventData[T]) => void
Returns void
- Defined in index.ts:503

on

on<T extends SDKEventType>(
event: T,
callback: (data: SDKEventData[T]) => void,
): void
Subscribe to SDK events.
Type Parameters
- T extends SDKEventType
Parameters
- event: T
- callback: (data: SDKEventData[T]) => void
Returns void
- Defined in index.ts:495

once

once<T extends SDKEventType>(
event: T,
callback: (data: SDKEventData[T]) => void,
): void
Subscribe to an event once.
Type Parameters
- T extends SDKEventType
Parameters
- event: T
- callback: (data: SDKEventData[T]) => void
Returns void
- Defined in index.ts:511

playVideo

playVideo(videoId: string): Promise<PlayVideoResult>
Play a video by ID. Returns the video URL and ID for playback.
Parameters
- videoId: string
Returns Promise<PlayVideoResult>
- Defined in index.ts:281

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>
- Defined in index.ts:364

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
- Defined in index.ts:236

releaseCamera

releaseCamera(): Promise<void>
Release the camera stream.

Returns Promise<void>
- Defined in index.ts:309

`Optional`releaseUrl

releaseUrl?(url: string): void
Release an object URL returned by an asset, video, or recording method. Allows the SDK to revoke blob URLs and free memory. Asset and video methods share URLs for the same video: release only after every consumer of that URL is finished. Network URLs are unaffected. Optional — older SDK builds may not implement this.
Parameters
- url: string
Returns void
- Defined in index.ts:347

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>
- Defined in index.ts:320

stopRecording

stopRecording(): Promise<StopRecordingResult>
Stop recording early (if needed).

Returns Promise<StopRecordingResult>
- Defined in index.ts:327

Interface IChoreoSDK

Index

Properties

Methods

Properties

Optionallog

Type Declaration

Parameters

Returns Promise<{ ok: boolean }>

debug: function

Parameters

Returns Promise<{ ok: boolean }>

error: function

Parameters

Returns Promise<{ ok: boolean }>

info: function

Parameters

Returns Promise<{ ok: boolean }>

warn: function

Parameters

Returns Promise<{ ok: boolean }>

Example

Methods

Optionaldestroy

Returns void

OptionaldetectFace

Parameters

Returns Promise<FaceDetectionResult>

Example

OptionaldetectFacePresence

Parameters

Returns Promise<FacePresenceResult>

Example

exitApp

Parameters

Returns Promise<ExitResult>

Example

generateQRCode

Parameters

Returns Promise<QRCodeResult>

getAssets

Returns Promise<AssetInfo[]>

getAssetUrl

Parameters

Returns Promise<string>

getCameraStream

Parameters

Returns Promise<CameraStreamInfo>

getConfig

Returns Promise<SDKConfig>

getRecording

Parameters

Returns Promise<RecordingInfo>

getRecordingStatus

Returns Promise<RecordingStatus>

getSelectedCamera

Returns Promise<CameraInfo>

getUploadStatus

Parameters

Returns Promise<UploadStatus>

getVideos

Returns Promise<VideoInfo[]>

getVideoUrl

Parameters

Returns Promise<string>

isReady

Returns boolean

listVideos

Returns Promise<VideoInfo[]>

navigateTo

Parameters

Returns Promise<NavigateResult>

off

Type Parameters

Parameters

Returns void

on

Type Parameters

Parameters

Returns void

`Optional`log

`Optional`destroy

`Optional`detectFace

`Optional`detectFacePresence

`Optional`releaseUrl