Skip to content
Jami3D
Developer docs menu

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.

NameTypeDescription
projectIdstring

The project to play (its embed document is {host}/p/{projectId}). Give it or listing; it wins when both are given.

listingstring

Added within v1 (P8): instead of projectId, a marketplace listing's slug (the {slug} of jami.live/w/{slug}). The facade reads the listing's card (/v1/listings/{slug}/card), which names the project the iframe then plays; an unlisted listing opens to its slug, and a listing that cannot be read is the facade's "can't be played here" card.

releasestring

latest — the project's live release, or the one the key pins — or a published release's id.

Read by the player: refused there if malformed, and reported in the Welcome.
publishableKeystring

A publishable key (pk_live_… / pk_test_…) whose allowed origins include this page.

viewerTokenstring | (() => Promise<string>)

A secure embed (an LMS, a hospital): the single-use grant the integrator's backend got from POST /v1/viewer-tokens, or a function the SDK calls for a fresh one whenever the iframe starts a session (an expired session is renewed with a new grant).

autoplayboolean | "muted"

Start without the poster's Play; muted starts silent with "Tap to unmute".

Read by the player: refused there if malformed, and reported in the Welcome.
controlsPlayerControls

controls: all, none, a minimal transport, or part by part (a part left out is shown).

Read by the player: refused there if malformed, and reported in the Welcome.
results"show" | "hide"

hide: no Results screen (the host listens to quizresult and sessioncomplete instead).

Read by the player: refused there if malformed, and reported in the Welcome.
startPlayerStart

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).

Read by the player: refused there if malformed, and reported in the Welcome.
localestring

The viewer's language: live AI replies in it (the UI keeps the platform's).

Read by the player: refused there if malformed, and reported in the Welcome.
captionsboolean | "auto"

Captions on at the start; auto follows the viewer's own preference.

Read by the player: refused there if malformed, and reported in the Welcome.
themePlayerTheme

theme: a mode alone, or overrides — precedence: this option, the project's accent, the platform's.

Read by the player: refused there if malformed, and reported in the Welcome.
aspectRationumber

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. letterbox keeps the whole frame, with bars of the project's letterbox colour around it; fill covers the container, cropping the frame's edges; balanced (the default) crops as far as the project allows and letterboxes the rest. An iframe that predates the option ignores it (named back in the Welcome's ignoredOptions) and plays balanced.

Read by the player: refused there if malformed, and reported in the Welcome.
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.

Read by the player: refused there if malformed, and reported in the Welcome.
cardTokenstring | (() => Promise<string>)

Lets the facade read the card of a private or secure-only project: the cardToken that came with the viewer-token grant (valid five minutes), or a function that fetches one.

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.

exclusivePlaybackboolean

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 on("*", …) hears it.

hoststring

The embed host (default https://embed.jami.live): staging, or a local development stack.

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 ready event); 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); audio says whether sound runs or waits for a tap.

pause(): Promise<void>
seek(target: SdkSeekTarget): Promise<SdkSeekResult>

Milliseconds on the story's axis (as timeupdate reports), 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 answers unsupported): runs a named action of an object's Interaction Graph — ref is the object's alias or entity id — with flat arguments (≤ 4 KB as JSON). Only an action its author marked hostControllable runs, else {ok: false, reason: "not_allowed"}; unsupported for no such object or one without a graph, unavailable before 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_ready while no story runs, and with invalid_input for no such object or one without a graph.

on<T extends SdkEventType>(type: T, handler: (event: SdkEventOf<T>) => void): () => void

Listens to one type of event, or to every one (*); returns the unsubscribe.

on(type: "*", handler: (event: SdkEvent) => void): () => void
destroy(): 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).

FieldTypeDescription
durationMsnumber

The timeline scenes' length (interactive scenes add none).

interactiveboolean

Viewers act in it: Beats, or an interactive scene.

statechange

The phase changed (SDK_PLAYER_PHASES, read open).

FieldTypeDescription
phasestring

timeupdate

The playhead, at most four times a second.

FieldTypeDescription
positionMsnumber

A non-negative integer count or time in milliseconds.

durationMsnumber

A non-negative integer count or time in milliseconds.

sceneenter

A scene began: its id, and its place in the story (from 0).

FieldTypeDescription
sceneIdstring

An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is scene:{sceneId}), an entity, a behaviour, a rule, a variable, a quiz, a question, a choice.

indexnumber

sceneexit

The story left a scene.

FieldTypeDescription
sceneIdstring

An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is scene:{sceneId}), an entity, a behaviour, a rule, a variable, a quiz, a question, a choice.

indexnumber

beatenter

A Beat opened (its lead-in began); alias is the author's name for it (may be empty).

FieldTypeDescription
beatIdstring

An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is scene:{sceneId}), an entity, a behaviour, a rule, a variable, a quiz, a question, a choice.

aliasstring

beatexit

A Beat closed: continued, timer, satisfied, timeout, jump, seek, rewind, sceneExit.

FieldTypeDescription
beatIdstring

An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is scene:{sceneId}), an entity, a behaviour, a rule, a variable, a quiz, a question, a choice.

aliasstring
reasonstring

objectclick

The viewer activated an interactive object: clicked it on the stage, or chose it in the Objects list.

FieldTypeDescription
entityIdstring

An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is scene:{sceneId}), an entity, a behaviour, a rule, a variable, a quiz, a question, a choice.

aliasstring | null

quizresult

A quiz answer was graded (the server grades; the answer key never reaches the page).

FieldTypeDescription
quizIdstring

An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is scene:{sceneId}), an entity, a behaviour, a rule, a variable, a quiz, a question, a choice.

questionIdstring

An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is scene:{sceneId}), an entity, a behaviour, a rule, a variable, a quiz, a question, a choice.

correctboolean
pointsnumber

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.

FieldTypeDescription
modestring
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).

FieldTypeDescription
levelstring
reasonsstring[]

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}).

FieldTypeDescription
idstring
rolestring
speakerKeystring | null
toKeystring | null
textstring

custom

An author's rule ran emitSdkEvent: its name and flat payload.

FieldTypeDescription
namestring
payloadSdkObjectActionArgs

deprecation

Something this SDK uses will stop working: what, why, and from when (an ISO date).

FieldTypeDescription
featurestring
messagestring
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).

FieldTypeDescription
codestring
fatalboolean
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.

FieldTypeDescription
objectstring

The object as the host names it (ref): its alias when it has one, else its entity id.

entityIdstring

An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is scene:{sceneId}), an entity, a behaviour, a rule, a variable, a quiz, a question, a choice.

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.

FieldTypeDescription
objectstring

The object as the host names it (ref): its alias when it has one, else its entity id.

entityIdstring

An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is scene:{sceneId}), an entity, a behaviour, a rule, a variable, a quiz, a question, a choice.

eventstring

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.

CodeDescription
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: ask with no Beat open, complete outside a showcase.

destroyed

The player was destroyed.

handshake_timeout

The iframe never answered the handshake: blocked by frame-ancestors, or unreachable.

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 (Promise.withResolvers).

invalid_option

A host option failed the iframe's strict schema and was ignored (an error event, not fatal).

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; }
FieldTypeDescription
playingboolean
audiostring

running, suspended (no gesture reached the frame) or unavailable (no Web Audio).

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.

SdkObjectActionArgs

SdkObjectActionArgs

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>; }
FieldTypeDescription
objectstring

The object as the host names it back (ref): its alias when it has one, else its entity id.

entityIdstring

An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is scene:{sceneId}), an entity, a behaviour, a rule, a variable, a quiz, a question, a choice.

aliasstring | null
paramsRecord<string, SdkObjectParamValue>

Param → value.

statesRecord<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[]; }; }
FieldTypeDescription
phasestring

SDK_PLAYER_PHASES, read open (idle before a session, suspended by the registry).

positionMsnumber

A non-negative integer count or time in milliseconds.

durationMsnumber

A non-negative integer count or time in milliseconds.

ratenumber
sceneIdstring | 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.

volumenumber
mutedboolean
captionsboolean
camera{ mode: string; focus: { entityId: string; alias: string | null; } | null; }
ai{ level: string; reasons: string[]; }

Live AI now (voice, text, off) and why.

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.

  • idle
  • booting
  • entering
  • awaitingGesture
  • playing
  • paused
  • beat
  • showcase
  • speechHold
  • transition
  • buffering
  • seeking
  • ended
  • error
  • suspended