Player SDK
jami3d 0.1.0, protocol 1: every option, command, event and error code, generated from the contract the SDK and the player share.
Options
What createPlayer(container, options) takes. A container with a height of its own is filled; one without takes aspectRatio's height.
| Name | Type | Description |
|---|---|---|
projectId | string | The project to play (its embed document is |
listing | string | Added within v1 (P8): instead of |
release | string |
|
publishableKey | string | A publishable key ( |
viewerToken | string | (() => Promise<string>) | A secure embed (an LMS, a hospital): the single-use grant the integrator's backend got from |
autoplay | boolean | "muted" | Start without the poster's Play; |
controls | PlayerControls |
|
results | "show" | "hide" |
|
start | PlayerStart |
|
locale | string | The viewer's language: live AI replies in it (the UI keeps the platform's). |
captions | boolean | "auto" | Captions on at the start; |
theme | PlayerTheme |
|
aspectRatio | number | The player's width / height when its container has no height of its own (default 16 / 9). |
fit | "fill" | "letterbox" | "balanced" | Added within v1: how a container of another shape than the project's frame shows it. |
lazy | "viewport" | "click" | "eager" | When the iframe mounts: viewport entry (default), the facade's Play, or at once. |
preload | "metadata" | "auto" | What the iframe loads before Play: its poster only (default) or the experience. |
cardToken | string | (() => Promise<string>) | Lets the facade read the card of a private or secure-only project: the |
poster | { url?: string; title?: string; } | The facade's poster when the card cannot describe the project (private, secure-only). |
allow | { voice?: boolean; fullscreen?: boolean; } | Features this page does not delegate to the iframe: the microphone (voice), fullscreen. |
exclusivePlayback | boolean | Only one player of the page plays at a time: this one pauses the others, and they it. |
onEvent | ((event: SdkEvent) => void) | Every event, as |
host | string | The embed host (default |
JamiPlayer
What createPlayer returns. A command called before the iframe is mounted mounts it, one called before the handshake waits for it, and a failed one rejects with a JamiPlayerError.
readonly ready: Promise<void>Resolves once the experience is on screen (the
readyevent); rejects with the reason it never will be (a refused origin, a failed handshake,destroy()).readonly capabilities: readonly string[]The method names and minor features the iframe announced in its Welcome (empty before).
play(): Promise<SdkPlayResult>Plays (from the poster too);
audiosays whether sound runs or waits for a tap.pause(): Promise<void>seek(target: SdkSeekTarget): Promise<SdkSeekResult>Milliseconds on the story's axis (as
timeupdatereports), or an instant of a scene.goToBeat(aliasOrTag: string): Promise<SdkSeekResult>A chapter, by the Beat's alias, navigation tag or id.
nextBeat(): Promise<SdkSeekResult>prevBeat(): Promise<SdkSeekResult>continueBeat(): Promise<void>Continue at an Open Beat (or a skippable Timed one); a showcase's Continue.
setRate(rate: number): Promise<void>0.5 … 2.
resetCamera(): Promise<void>cameraBack(): Promise<void>focusObject(alias: string): Promise<SdkCommandResult>Focus the camera on an object, by alias or entity id.
setVolume(volume: number): Promise<void>0 … 1.
setMuted(muted: boolean): Promise<void>setLocale(locale: string): Promise<void>The language live AI replies in.
setTheme(theme: PlayerTheme): Promise<void>setCaptions(on: boolean): Promise<void>setViewerContext(values: SdkViewerContext): Promise<void>Flat values (≤ 200 characters of text each, ≤ 4 KB in all) the session records.
ask(addressee: string, text: string): Promise<SdkCommandResult>A typed question to a speaker (alias or speaker key), only while a Beat is open.
complete(): Promise<SdkCommandResult>Ends a showcase (an interactive scene):
sessioncomplete.getState(): Promise<SdkState>objectAction(ref: string, action: string, args?: SdkObjectActionArgs): Promise<SdkCommandResult>Added within v1 (feature
objectControl; an older iframe answersunsupported): runs a named action of an object's Interaction Graph —refis the object's alias or entity id — with flat arguments (≤ 4 KB as JSON). Only an action its author markedhostControllableruns, else{ok: false, reason: "not_allowed"};unsupportedfor no such object or one without a graph,unavailablebefore the story has begun.setObjectParam(ref: string, param: string, value: SdkObjectParamValue): Promise<SdkCommandResult>Sets a param of an object's graph to a flat value or a list of them (≤ 4 KB as JSON): only a param its author marked
hostWritable, else{ok: false, reason: "not_allowed"}.getObjectState(ref: string): Promise<SdkObjectState>An object's graph state now: the params of its interface and its session layers' states. A read, it never starts the experience: it rejects with
not_readywhile no story runs, and withinvalid_inputfor no such object or one without a graph.on<T extends SdkEventType>(type: T, handler: (event: SdkEventOf<T>) => void): () => voidListens to one type of event, or to every one (
*); returns the unsubscribe.on(type: "*", handler: (event: SdkEvent) => void): () => voiddestroy(): Promise<void>Ends the session, removes the iframe and the facade, and frees the page registry's slot.
Events
Listen with player.on(type, handler), with player.on("*", handler), or with the onEvent option.
ready
The experience is on screen (the curtain lifted on its first frame).
| Field | Type | Description |
|---|---|---|
durationMs | number | The timeline scenes' length (interactive scenes add none). |
interactive | boolean | Viewers act in it: Beats, or an interactive scene. |
statechange
The phase changed (SDK_PLAYER_PHASES, read open).
| Field | Type | Description |
|---|---|---|
phase | string |
timeupdate
The playhead, at most four times a second.
| Field | Type | Description |
|---|---|---|
positionMs | number | A non-negative integer count or time in milliseconds. |
durationMs | number | A non-negative integer count or time in milliseconds. |
sceneenter
A scene began: its id, and its place in the story (from 0).
| Field | Type | Description |
|---|---|---|
sceneId | string | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
index | number |
sceneexit
The story left a scene.
| Field | Type | Description |
|---|---|---|
sceneId | string | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
index | number |
beatenter
A Beat opened (its lead-in began); alias is the author's name for it (may be empty).
| Field | Type | Description |
|---|---|---|
beatId | string | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
alias | string |
beatexit
A Beat closed: continued, timer, satisfied, timeout, jump, seek, rewind, sceneExit.
| Field | Type | Description |
|---|---|---|
beatId | string | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
alias | string | |
reason | string |
objectclick
The viewer activated an interactive object: clicked it on the stage, or chose it in the Objects list.
| Field | Type | Description |
|---|---|---|
entityId | string | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
alias | string | null |
quizresult
A quiz answer was graded (the server grades; the answer key never reaches the page).
| Field | Type | Description |
|---|---|---|
quizId | string | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
questionId | string | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
correct | boolean | |
points | number |
sessioncomplete
The story ended (or the host completed a showcase).
No fields beyond its type.
camera
The camera's mode (authored, free, focus, returning, travel) or focus changed.
| Field | Type | Description |
|---|---|---|
mode | string | |
focus | { entityId: string; alias: string | null; } | null | An object the viewer focused or clicked: its entity id and, when it has one, its alias. |
ailevel
What live AI the viewer has now: voice, text or off, and why (an open vocabulary).
| Field | Type | Description |
|---|---|---|
level | string | |
reasons | string[] |
aimessage
A message of the conversation, once final: the viewer's question (role: viewer, toKey the addressee) or a character's reply (role: reply). Speakers are speaker keys (narrator, cast:{castId}).
| Field | Type | Description |
|---|---|---|
id | string | |
role | string | |
speakerKey | string | null | |
toKey | string | null | |
text | string |
custom
An author's rule ran emitSdkEvent: its name and flat payload.
| Field | Type | Description |
|---|---|---|
name | string | |
payload | SdkObjectActionArgs |
deprecation
Something this SDK uses will stop working: what, why, and from when (an ISO date).
| Field | Type | Description |
|---|---|---|
feature | string | |
message | string | |
removeAfter? | string |
error
Something went wrong (SDK_ERROR_CODES and the player's own codes, read open); fatal: the experience cannot go on (the player shows why).
| Field | Type | Description |
|---|---|---|
code | string | |
fatal | boolean | |
message? | string |
objectstate
Added within v1 (feature objectControl): an object's Interaction Graph committed new state — the params of its interface and the states of its session layers that changed.
| Field | Type | Description |
|---|---|---|
object | string | The object as the host names it ( |
entityId | string | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
params? | Record<string, SdkObjectParamValue> | The params that changed, with their new values. |
states? | Record<string, string> | The session layers whose state changed, with their new states. |
objectevent
Added within v1 (feature objectControl): an object's graph raised an event its author marked for the host page — its name and flat payload.
| Field | Type | Description |
|---|---|---|
object | string | The object as the host names it ( |
entityId | string | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
event | string | The event's name, as the author gave it. |
payload? | SdkObjectActionArgs | Its flat values, when it has any. |
Error codes
A JamiPlayerError's code, and an error event's. The player's own codes arrive too: read them as text.
| Code | Description |
|---|---|
unsupported | The peer does not implement the method or the feature: it is older than the caller. |
invalid_input | The arguments are not what the contract takes. |
not_ready | The experience was not ready for the command in time (still loading, or failed to load). |
not_allowed | Not possible now: |
destroyed | The player was destroyed. |
handshake_timeout | The iframe never answered the handshake: blocked by |
origin_not_allowed | The publishable key does not allow this page's origin. |
key_invalid | The publishable key is unknown, revoked or expired. |
release_not_found | Nothing this page may play: no live release, or a project that cannot be embedded here. |
browser_unsupported | The browser lacks what the SDK needs ( |
invalid_option | A host option failed the iframe's strict schema and was ignored (an |
viewer_token_failed | A secure embed's viewer token could not be had from the host page. |
Types
PlayerTheme
theme: a mode alone, or overrides — precedence: this option, the project's accent, the platform's.
"dark" | "light" | "auto" | { accent?: string; mode?: "dark" | "light" | "auto"; radius?: "small" | "none" | "medium" | "large"; font?: "inter" | "system" | "serif" | "rounded"; captionSize?: "small" | "medium" | "large" | "xlarge"; }PlayerControls
controls: all, none, a minimal transport, or part by part (a part left out is shown).
boolean | "minimal" | { transport?: boolean; chapters?: boolean; conversation?: boolean; share?: boolean; fullscreen?: boolean; reportButton?: boolean; }PlayerStart
start: where a FRESH session starts (a resumed one keeps its place) — a chapter (a Beat's alias, tag or id), an instant of a scene (sceneId, tMs into it), or an instant of the whole story (tMs alone, on the axis timeupdate reports).
{ beat: string; } | { sceneId?: string; tMs?: number; }SdkSeekTarget
seek(t): milliseconds on the story's axis (the timeline scenes laid end to end, as timeupdate reports it), or an instant of one scene.
number | { sceneId: string; tMs: number; }SdkPlayResult
play(): whether the story runs, and whether sound does (else "Tap to unmute" shows).
{ playing: boolean; audio: string; }| Field | Type | Description |
|---|---|---|
playing | boolean | |
audio | string |
|
SdkSeekResult
Where a move landed: ok at atMs; needs-rewind-confirm — the target lies before interaction history, the player asks the viewer (nothing moved yet); gate-locked — a required Gate not completed stands in the way, the playhead stopped just before it.
{ kind: "ok"; atMs: number; } | { kind: "needs-rewind-confirm"; targetMs: number; lostMessages: number; lostEvents: number; lostQuizAnswers: number; } | { kind: "gate-locked"; beatId: string; stoppedAtMs: number; }SdkCommandResult
A command the player could not carry out says why (unavailable, not_allowed, busy, …).
{ ok: true; } | { ok: false; reason: string; }SdkViewerContext
setViewerContext(values): flat values the AI and the session's results may read (the viewer.context fact) — text up to 200 characters, numbers, booleans; at most 4 KB as JSON.
SdkObjectActionArgsSdkObjectActionArgs
objectAction(ref, action, args?): the action's arguments — flat values under names of up to 48 characters, at most 4 KB as JSON.
Record<string, string | number | boolean>SdkObjectParamValue
setObjectParam(ref, param, value): a boolean, a number, text up to 200 characters, or a list of up to 1024 of them — at most 4 KB as JSON.
string | number | boolean | (string | number | boolean)[]SdkObjectState
getObjectState(ref): an object's Interaction Graph now — the params of its interface as committed, and the state each of its session layers is in.
{ object: string; entityId: string; alias: string | null; params: Record<string, SdkObjectParamValue>; states: Record<string, string>; }| Field | Type | Description |
|---|---|---|
object | string | The object as the host names it back ( |
entityId | string | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
alias | string | null | |
params | Record<string, SdkObjectParamValue> | Param → value. |
states | Record<string, string> | Session layer → its state now. |
SdkState
getState(): where the player stands.
{ phase: string; positionMs: number; durationMs: number; rate: number; sceneId: string | null; beat: { beatId: string; alias: string; mode: string; canContinue: boolean; } | null; volume: number; muted: boolean; captions: boolean; camera: { mode: string; focus: { entityId: string; alias: string | null; } | null; }; ai: { level: string; reasons: string[]; }; }| Field | Type | Description |
|---|---|---|
phase | string |
|
positionMs | number | A non-negative integer count or time in milliseconds. |
durationMs | number | A non-negative integer count or time in milliseconds. |
rate | number | |
sceneId | string | null | The scene now; null before the story is in. |
beat | { beatId: string; alias: string; mode: string; canContinue: boolean; } | null | The Beat that is open; null between Beats. |
volume | number | |
muted | boolean | |
captions | boolean | |
camera | { mode: string; focus: { entityId: string; alias: string | null; } | null; } | |
ai | { level: string; reasons: string[]; } | Live AI now ( |
SdkEvent
Every event the host hears, one branch per type. An object's objectstate or objectevent is at most 4 KB as JSON, whole.
{ type: "ready"; durationMs: number; interactive: boolean; } | { type: "statechange"; phase: string; } | { type: "timeupdate"; positionMs: number; durationMs: number; } | { type: "sceneenter"; sceneId: string; index: number; } | { type: "sceneexit"; sceneId: string; index: number; } | { type: "beatenter"; beatId: string; alias: string; } | { type: "beatexit"; beatId: string; alias: string; reason: string; } | { type: "objectclick"; entityId: string; alias: string | null; } | { type: "quizresult"; quizId: string; questionId: string; correct: boolean; points: number; } | { type: "sessioncomplete"; } | { type: "camera"; mode: string; focus: { entityId: string; alias: string | null; } | null; } | { type: "ailevel"; level: string; reasons: string[]; } | { type: "aimessage"; id: string; role: string; speakerKey: string | null; toKey: string | null; text: string; } | { type: "custom"; name: string; payload: SdkObjectActionArgs; } | { type: "deprecation"; feature: string; message: string; removeAfter?: string; } | { type: "error"; code: string; fatal: boolean; message?: string; } | { type: "objectstate"; object: string; entityId: string; params?: Record<string, SdkObjectParamValue>; states?: Record<string, string>; } | { type: "objectevent"; object: string; entityId: string; event: string; payload?: SdkObjectActionArgs; }Player phases
What statechange reports and getState answers. A newer player may report a phase this list does not have yet.
idlebootingenteringawaitingGestureplayingpausedbeatshowcasespeechHoldtransitionbufferingseekingendederrorsuspended