Egatari Player 1.0 — Editor’s Draft

Status: Editor’s Draft, split from the Egatari format specification on 2026-10-25. Not stable. Dated snapshots follow the format’s (CHANGES.md; latest: WD 2026-11-15). It is versioned separately from the format: a player states which Egatari format versions it plays and which version of this document it follows. Editors: Gendo Kumoi (Nagaoka University of Technology). Companion: Egatari 1.0, the format (referred to as format). References written §n are to the format; references written Pn are to this document. License of this document: CC BY 4.0.

The format describes what a lesson is: its slides, steps, narration, article, audio and components, and how they are stored in one HTML file. This document describes how a player shows a lesson. Players are separate from the format and anyone may write one (format §4.1); every Egatari file carries one conforming player, the bundled player, so that it plays anywhere.

P0. Conventions

The key words MUST, MUST NOT, SHOULD, SHOULD NOT and MAY are to be interpreted as in BCP 14 [RFC 2119] [RFC 8174] when they appear in all capitals.

P1. Display modes

Mode Who drives Time Typical use
talk (default) the presenter step by step, or anyone through playback: start, pause, previous/next, jump, playback rate real time of each step; during playback, advances along the timeline (format §5.5) with narration audio live presentation, class, self-study, LMS
video nobody (no controls) advances along the timeline recording and video export

When a lesson opens in video for a viewer (not an export, e.g. through offer.open), the player shows one start control, because audio needs a user gesture (P3), and then advances along the timeline without further controls.

Self-study is not a mode: a learner plays the lesson in talk with playback. What a learner adds on top (annotations, saved progress, a library of lessons) belongs to the application that opens the file, not to the player (P5). Earlier drafts defined a third mode, learn; a player that meets learn in offer, an address parameter or an embedding command treats it as talk.

Preview of later steps is an option of every interactive mode, not a mode: steps not yet reached are either hidden (default) or shown faintly. The current step renders and animates as usual; only content of later steps is shown faintly, and components keep rendering their current step. Content marked data-preview="none" (format §8.4), and components that declare preview: "none" (format §8.4), keep their later steps hidden under preview: they are answers the audience is meant to work out first. Players draw faint content at the opacity given by the theme’s --preview-opacity (default 0.45).

Playback. In talk, a player MUST offer playback: a start/pause control that advances along the timeline with the narration audio, and previous/next and jump that seek while keeping the playing state. During playback it MUST offer playback rates of at least 0.75, 1, 1.25, 1.5 and 2, keeping the pitch of speech; the timeline clock advances at the same rate, so the screen stays a function of (i, k, t). Stepping by hand (the presenter’s step keys) pauses playback; the playback controls for previous/next, going to a page number and choosing from the slide list seek and keep the playing state. Presenter tools (presenter view, laser, pen) stay available; a player MAY tuck them away when the screen is narrow.

When embedded by a host (P8, format §10), the host MAY hide the player’s own controls (controls=0) and provide equivalent ones itself (chapter list, playback rate, pause), and MAY restrict forward navigation as a course policy. The requirement to offer controls is then met by the host.

Offered views. Players SHOULD show only the modes and faces in deck-meta.offer (format §1.2) and open as offer.open states (defaults: all modes, the faces present, metadata.primary). What a player opens in is decided in this order, the first that applies winning: the viewer’s or host’s explicit choice (an address parameter such as ?mode=, the embedding interface P8), then offer.open, then metadata.primary (face only), then the defaults by context (P2). Players MAY let the viewer override the offer.

P2. Layouts and panes

Independently of the mode, a player arranges the lesson in panes. A layout is an arrangement of panes; every pane shows the same position, and layouts are views of one source (format §1.0), not different documents.

Pane Shows In the file
stage the talk face: one 16:9 slide stage at a time, animated yes
text the read face: the article (format §9C) when present, otherwise the narration of each step as body text, with each slide’s stage scaled (not re-flowed) at its place yes

A pane of kind text is either scrolled (a vertical document) or paginated (single pages or a two-page spread). Page breaks MUST NOT split a step’s block, a figure, a table or a display equation; a block taller than a page is scaled down to fit rather than split. Players choose the page breaks and the pairing of pages in a spread; page breaks can be switched off. Page breaks depend on the pane’s size, fonts and language and are not part of the (i, k, t) determinism (format §1), which covers the stage; conformance tests of video frames and stage rendering do not cover pagination. A stage pane can also be paginated (one slide per page, for printing and handouts).

The usual layouts are named combinations:

Layout Panes Typical use
slides stage talk, video
flow text, scrolled reading, portrait phones
pages (pages=single\|spread) text, paginated — the read face as pages is a book; the talk face as pages is slides in a book books, printing
split stage + text self-study on wide screens
— stage + notes, text + notes, stage + text + notes self-study with note-taking

P3. Playback

A conforming player MUST: render any (i, k, t) deterministically; implement the modes that P9 requires and the preview option (P1); play the formats in format §5.1; start audio only after a user gesture (a visible start/resume control); pause when the page is hidden; honor prefers-reduced-motion by rendering final states, except for a component that declares elapsed time as its content (a clock or countdown, clock declared on the component, format §8.4), which still receives the real t and drops only decorative motion; and work from file:// with no network access.

Information panel. Players SHOULD show, in their information panel, the format version the file follows, the bundled player and the producer, in that order (format §4.1).

The syntax of links to slides is in format §9.1A.

Links that leave the lesson are a phishing surface like links in PDF files, and a browser shows less context than a PDF reader. A player MUST open them outside the lesson (a new browsing context, noopener, noreferrer) and MUST let the viewer see the destination’s host before leaving (a confirmation, or a preview on hover or long press). It MUST ask for confirmation, showing the full destination, when the link’s visible text names a different host than the destination, when the destination is not https:, or when it would download a file; it SHOULD NOT ask again for the same host in the same viewing session. Links within the lesson (format §9.1A) need no confirmation. Hosts that play lessons apply the same rule to links the lesson asks them to open. In detail: (a) players open only https:, http:, mailto: and tel: destinations and refuse every other scheme (javascript:, data:, blob:, file: as an absolute address, …); every destination other than plain https: is confirmed each time; (b) in a lesson opened from a file, a relative link to a neighbouring file is confirmed each time; (c) a destination carrying user information (user:pass@) or an internationalized host (xn-- labels) is treated like a different host and confirmed each time; (d) “names a different host” means any host-like token in the link’s visible text that differs from the destination’s host, ignoring a leading www., a subdomain counting as different (players MAY narrow host-like tokens with a public-suffix list to avoid needless confirmations); (e) “would download” means a download attribute (a player cannot know a server’s response in advance); (f) only plain https: hosts are remembered for the session, in memory only; where the platform needs a fresh tap to open a new browsing context (e.g. a host acting on openLink, P8, on Safari), a single tap on an open control without the warning counts as not asking again; (g) where the player cannot open a new browsing context (an editor’s sandboxed preview), it shows the destination without a way to open it; (h) links the player itself generates (e.g. joining a live room in the browser, saving an attachment) are not lesson content and need no confirmation, provided the player shows their destination host in its own interface and no lesson markup can mark a link as such; (i) a browser’s own “open in new tab” cannot be intercepted, and the browser then shows the address itself.

P5. Viewer preferences and learner data

Learner data never enters the file (format §9.1B).

P6. Tracking adapters

A player SHOULD expose progress through a tracking adapter, detected in this order: SCORM 1.2 API (window.API in a parent frame), then postMessage to the parent, then local storage. Events: started, step ({slideKey, stepKey, index, total, via}), completed, suspend ({location, data}). via is "stage" when the step was played on a stage, or "text" when it was read in a text pane: its block, or the article section of its slide (format §9C.5), was in view for a few seconds (players choose, e.g. three) and not scrolled past. A step the stage only moved to because it followed the text pane (synchronization, P2) is not played on the stage; it counts as "text" if it was read as above. Players record the two separately. The SCORM 1.2 binding is defined in bindings/scorm12.md. A player lists the adapters it implements in deck-meta.tracking; completion rules are read from deck-meta.completion so that play-only files can be tracked. Completion defaults to “every step visited”, played or read; metadata.completion MAY set {"visitedFraction": number} or {"reachedEnd": true}, and "played": true to count only steps played on a stage (format §9.2).

P7. Source extraction

A player SHOULD offer to save the archive layer as a ZIP of files plus audio/manifest.json, so the source remains recoverable without any editor.

P8. Embedding

A host page (a learning platform, an LMS plugin, a video tool) MAY embed an Egatari file in an <iframe> and drive it. A player that supports embedding MUST, when loaded with the query parameter embed=1, accept messages from window.parent via postMessage (objects with a string member egatari) and ignore messages from any other source. Query parameters mode, layout, controls=0 and preview=1 set the initial state. Every command MAY carry an id; the player echoes it in the reply or acknowledgement. Times are seconds as floating-point numbers.

Commands (host → player):

Message Effect / reply
{egatari:"seek", id?, slide, step, t} go to (slide, step, t); slide is a slide key or index, step a step key, t seconds or null for ∞. Reply seeked
{egatari:"play", id?} / {egatari:"pause", id?} start / pause timeline playback with audio. If the browser refuses to start audio, reply playBlocked
{egatari:"rate", id?, value} playback rate (P1)
{egatari:"mode", id?, mode} / {egatari:"layout", id?, layout} / {egatari:"preview", id?, on} / {egatari:"controls", id?, visible} display mode, preview of later steps, the player’s own controls
{egatari:"snapshot", id, slide, step, t, maxWidth?} OPTIONAL: reply {egatari:"snapshot", id, png} with a data:image/png of that position (t null = ∞), without changing the visible position. A player that does not implement it replies {egatari:"error", id, code:"unsupported"}

Events (player → host; target origin *; payloads contain no private data):

Message When
{egatari:"ready", version, docId, sourceSha256?, timeline:[{slideIndex, slideKey, stepKey, slideTitle, dur}]} once per loaded document, after the parts have mounted and the opening position is settled, before the first position; commands sent in reply take effect. version is the player’s own version (deck-meta.player.version); docId is null when the file has none; slideTitle is the slide’s title as in the readable layer (format §2.1); dur is the step’s duration in seconds at rate 1
{egatari:"seeked", id?, slideKey, stepKey, t} after a seek has been applied
{egatari:"position", slideKey, stepKey, t, cause} MUST on every step change (cause: play, seek, control, link); during playback a player MAY also send it between step changes, at most 4 times per second, driven by a clock it already has (e.g. the audio element’s timeupdate); it need not add a timer for this. Scrolling or turning pages in a text pane is a seek
{egatari:"stepEnded", slideKey, stepKey} when a step has played to its end during playback (not when skipped; moving to another step by scrolling or turning pages in a text pane is a skip)
{egatari:"state", playing, rate} whenever playing state or rate changes, including by the player’s own controls
{egatari:"playBlocked", id?} audio could not start for lack of a user gesture
{egatari:"turn", slideKey, stepKey, index} OPTIONAL: when narration turn index starts; index is 0-based within the step’s turns (format §4). It marks the same moments at which a text pane highlights the current turn
{egatari:"ended"} after the last step of the timeline
{egatari:"openLink", href, text, download?} when the viewer activates a link that leaves the lesson (format §11) and the player cannot open it itself (e.g. in a sandboxed frame without popups); sent only on the viewer’s own activation. text is the link’s visible text (at most 200 characters); download: true when the link has a download attribute, which the host confirms every time or refuses. A host that acts on it treats it as untrusted and applies format §11 itself (schemes, confirmation showing the full destination, opening outside the lesson); it never opens anything without a tap in its own interface
{egatari:"error", id?, code, message} a command failed or the file cannot be played

Details of the commands and events: slide in seek is a slide key or a 0-based index (as slideIndex in ready); step is a step key, and an integer is read as that key; a missing step means "0" and a missing t means ∞. A seek replies with position (cause: "seek") and then seeked. A seek with t: null during playback continues playback from the start of that step (seeked reports t: 0); while paused it shows the step at ∞ and stays paused (seeked reports t: null). controls shows or hides exactly what controls=0 hides. preview applies only in the modes that have a preview of later steps (P1); in video it replies with error. stepEnded is sent only when playback reaches the end of a step, never for a skipped step; ended follows the last stepEnded and the state with playing: false. A command with a bad argument replies {egatari:"error", id, code} with the command’s name as code; an unknown command replies with code: "unsupported".

The first start of audio SHOULD happen through the player’s own start control, because browsers (notably Safari on iPad) may not pass a user gesture in the host page into the frame; hosts SHOULD allow autoplay on the frame and MUST handle playBlocked. Since a sandboxed frame has the origin null, hosts MUST identify the player by event.source === iframe.contentWindow. The same messages serve the postMessage tracking adapter (P6). Embedding commands are unprivileged: they can only do what a viewer could do with the controls. Narration text is not sent at run time; hosts read deck-narration from the file.

P9. Conformance

A conforming player of Egatari Player 1.0:

Accessibility of the player’s own controls (keyboard operation, accessible names, focus) is to be specified here.

References