English | 日本語
Every user-facing option, syntax and key, one line each, taken from the code. The normative text of the slide and script syntax, the timeline, emphasis and morphs is the format specification §8 and §5.5; this page is a quick reference to Studio's implementation, and contract.md lists which section says what and adds Studio's own notes. Workflow guides: README, dev-server.md, video.md.
Contents: Slide syntax · Script · Timing · Themes · Parts · Presenting · Dev server · Quality checker · Build · TTS · Video export · Tools · Environment variables
Normative: format spec §8.0 (slides, steps, kinds of slide, math, references) and §8.1 (slide ids). The rows below add Studio's positions, hooks and warnings.
| File | Read by | Purpose |
|---|---|---|
deck.html |
build | the slides (any name; examples/minimal/deck.html is the template) |
narration.md |
build, TTS, export | script per step |
timeline.json |
build | per-step timing overrides |
macros.tex |
build | KaTeX macros (\newcommand, \renewcommand, \def; added to the default macros) |
audio/manifest.json |
build | written by tts/synth.py and the editor app's Audio panel (each step: file, dur, cues, sync, kind, inputHash, for TTS recipe; optional processing and startOffset, the encoder delay at which playback starts) |
voice.json |
TTS | voices, language, engine |
figs/*.svg, data/*.json |
build | for {{FIG:…}} / {{JSON:…}} |
components/<name>/index.js |
build | the working folder's own parts (found before the library's). The name is the tag without m- (components/foo/ for <m-foo>); the whole tag (components/m-foo/) also works, but the build stops if one tag has both |
egatari.json |
build, Egatari file | docId, metadata, attachments; components pins library part versions ({"bars": "1.0.0"}, format spec §3.3; an Egatari file's copy carries the versions its export used, and unpacking writes them, so a rebuild does not switch versions; without a pin the build uses the default in components.lock.json) |
themes/<name>/ |
build | file-local themes |
comments.json, .cache/edits/ |
dev server | written by the dev server |
out/<name>.html |
— | default build output |
| Markup | Meaning |
|---|---|
<section class="slide"> inside <div id="stage"> |
one slide (1280×720). <h2> heading, <div class="body"> body, <div class="concl"><span>…</span></div> conclusion line |
class="slide cover" |
cover. Its children are .venue (venue or course, top 120px), <h1> (title, top 200px; a subtitle goes on a second line after <br>, as in <h1>Title<br>Subtitle</h1>, or into .venue) and .au (authors and affiliation, top 450px; several lines with <br>); theme logos are added at the bottom left (.logos). These are absolutely positioned, and the cover has no .body: any other element (such as <p class="sub">) is not placed and lands at the top edge over the band. Place other text yourself with position:absolute and top in the slides' <style>, in free space. The quality check warns when text goes off the slide or overlaps other text or the band (textOffSlide, textOverlap) |
data-nologos on the cover |
no theme logos on this cover (also skipped when the cover already has a .logos element) |
class="slide sec" |
chapter divider: the title is <h1> (an <h2> is shown the same way, and the quality checker warns) (<h1> at top 300px, .lead at top 390px; other text is placed as on the cover). Starts a chapter for --full video export |
class="slide sec appendix" |
appendix divider. Page numbers after it read 付録 / Appendix. Without appendix, a sec slide whose text contains 付録 or Appendix also counts |
class="… static" |
no steps at all: everything visible, .concl is not a separate step |
class="… nostep" |
do not turn list items into steps automatically |
class="… noconcl" |
no conclusion line: the body may extend to 680px instead of 565px (by default; a theme's metrics moves both) |
class="… layout-tate" |
fully vertical slide: the heading in a vertical column at the right edge, the body in vertical writing to its left, the conclusion as a vertical column at the left edge (Japanese language arts) |
id="…" on a section |
the slide id (format §8.1). Every slide has one. See Slide id |
data-morph / data-morph="key" |
morph in from the previous slide / from the slide with that key (contract §8) |
data-chapter="name" |
start a chapter here with this name (like a sec slide) |
<div class="pn"> as a direct child |
your own page number (otherwise one is added from slide 2 on: i/N) |
<html lang="en"> |
English file: Source Sans 3 body font, English UI text, English quality-check standards, voxcpm2 TTS |
<html data-theme="name"> |
theme (overridden by --theme) |
<html data-mode="talk"> |
default mode when the URL has no ?mode= and deck-meta.offer.open names none (talk or video; a former learn is read as talk) |
<html data-feedback-url="URL"> |
where Send feedback points (default https://github.com/egatari/egatari-studio/issues/new). For a GitHub /issues/new URL, template=feedback.yml is added; version, browser, os and context (lang, mode) are added as query parameters |
<html data-feedback="off"> |
no feedback link in the ? help or the presenter view (DECK.FEEDBACK_URL = null) |
<html data-favicon="off"> |
no tab icon. By default a built file (normal, --portable, --play-only) gets the Egatari mark as a <link rel="icon"> data: URI at the top of <head> (light and dark colours in one SVG, no network request); slides that have their own <link rel="icon"> keep it and get nothing added |
<html data-font="mincho"> |
body text in BIZ UDPMincho (--font-sans: var(--font-mincho)); see Japanese language arts |
Body classes (all colors come from the theme): .sub subheading · .big main equation · .note note (27px) · .thm theorem box · .caution caution box · .caution.warn warning box (automatic labels; role="note") · .box tinted box · .cols side-by-side columns · .arrow centered arrow line · .fig / .figcap figure and caption · .cite citation (20px) · .plot box for DECK.Plot · .readout .num tabular number · td.r right-aligned cell · .term, .emph, .muted, .b colors (meanings in format §8.0) and bold · .tate vertical writing · .mincho Mincho · .tcy upright digits in vertical text · <ruby> readings (Japanese language arts).
| Attribute | Meaning |
|---|---|
data-step="k" |
appears at step k (k ≥ 1). Step 0 = what is visible on entering |
| (none on the slide) | if a slide has no data-step and no data-from, each .body > ul > li and .body > ol > li becomes steps 1, 2, … |
.concl |
always the last step (max + 1), step label [concl] |
data-at="s" |
within its step, start s seconds later (fade and .draw) |
class="draw" |
SVG stroke drawn in (needs pathLength="1"). Step = closest data-step ancestor, its own data-step, or 0. 0.7 s. On a static slide, strokes are shown drawn (no animation). |
class="draw drawslow" |
same, 1.4 s |
data-from="k" (part) |
part's first step is slide step k (default 1) |
steps="n" (part) |
override the part's step count |
data-id="ID" |
morph pairing (contract §8) |
id="ID" / data-mark="ID" |
target of {mark:ID} (contract §7) |
data-key, data-title |
added by build (slide id, plain heading); not written by authors (format §8.0) |
| Syntax | Meaning |
|---|---|
\( … \) / \[ … \] |
inline / display math, rendered by KaTeX at build time (not inside <script>, <style>, <svg>, <textarea>, comments) |
\hlE{…} \hlT{…} \hlM{…} |
color part of a formula as conclusion (--emph) / term (--term) / known result (--muted) |
\morph{ID}{…} |
morph pairing inside a formula (= \htmlData{id=ID}{…}) |
\htmlId{ID}{…}, \htmlData{mark=ID}{…} |
emphasis target inside a formula |
\htmlClass{name}{…} |
CSS class inside a formula. Only these three \html… commands are allowed |
macros.tex |
\newcommand{\R}{\mathbb{R}}, \newcommand{\v}[1]{…}, \def\x{…}; nested braces up to 3 levels |
<script type="text/x-tex-macros">…</script> |
more macros in the same syntax, inside deck.html |
| KaTeX errors | build warns and shows the source in red (.katex-error); the quality checker reports it as an error |
DECK.svgMath(…) in a part or slide script |
KaTeX is also embedded at run time (with the same macros) |
| Syntax | Meaning |
|---|---|
/*INCLUDE:file*/ |
file contents inserted verbatim (working folder, then kit/). A path that leaves these folders (../, absolute, symbolic link) is refused with a warning and replaced by nothing |
{{FIG:name}} |
figs/name.svg (or name.svg in the working folder) inlined; ids prefixed with name-, width/height removed |
{{JSON:file}} |
JSON from data/ (or the working folder), minified. Put it in <script type="application/json"> inside a part to read it as this.data |
<m-name …> |
part; components/name/index.js in the file, else the library copy vendor/components/name/<version>/index.js, loaded automatically |
{{FIG:…}}, {{JSON:…}}, narration.md, timeline.json, macros.tex and the files in audio/manifest.json are read only if they resolve (after following symbolic links) inside the working folder; otherwise the build warns (refused: …) and skips them.
| Reference | Becomes |
|---|---|
<img src>, <source src/srcset>, <img srcset>, <video src/poster>, <audio src>, <track src>, SVG <image href> |
data: URI |
url(…) and @import in the slides' <style> and style="" attributes |
data: URI / the imported CSS inlined (url() in a linked or imported CSS file is relative to that file) |
<link rel="stylesheet" href="file.css"> |
<style> with the file's contents |
<link rel="icon"> and other <link> files, <script src="file.js"> |
data: URI / inline script |
Relative paths are resolved from the working folder and must stay inside it. data:, blob:, #fragment and template values (${…}, {{…}}) are left as they are. Warnings: missing: … (file not found), refused: … (outside the working folder), external: … (an http(s) reference in an asset position, including <iframe>/<object>: left as it is, so the file is not fully offline). Ordinary links (<a href>) are not touched. Audio from audio/manifest.json is embedded only with --embed-audio.
A slide is named by its id, the slide key (spec). By format §8.1 it matches ^[A-Za-z][A-Za-z0-9_-]{0,63}$ and is unique among every id in the file, including mark targets and \htmlId{…}. npm run new gives every slide an id; npm run ids -- <deck> adds them to a file that lacks them. So that such a file can still be opened and fixed, the build uses a name made from the heading in place of the id of a slide without one, and the quality checker reports it (legacyIndex); duplicates are an error, and the build warns (slide key: …) and gives the later slides a suffix #2, #3, …. The final name is written to the section's data-key (contract §4).
Normative: format spec §8.1–§8.3.
| Syntax | Meaning |
|---|---|
## heading {#s-k3f9q2} |
the slide with that id (the heading text is for readers) |
[0] [1] … [concl] |
script for that step; following lines continue it. Steps are 0–999 without leading zeros ([01] is not a step) |
@x-<name>-<field> <value> |
extension line inside a step: kept as data for the step, never shown or spoken, not hashed |
Expert: / Novice: (E: / N:, full-width colon allowed) |
speaker turn. Lines without a speaker are Expert (single speaker) or continue the previous turn |
{cue} |
sync point within a step; matches the part's cues(k) in order |
{mark:ID} |
underline the target at this word |
{mark:ID|effect} |
effect: underline, circle, box, spot, laser |
{mark:ID|effect|hold=2} |
disappear after 2 s (default: end of step; laser 1.5 s) |
{mark:clear} |
remove this step's emphasis now |
{φ|ファイ} |
shown as φ, read as ファイ |
# title |
ignored |
<!-- … --> |
comment on its own line(s), ignored |
| a step written twice | the last one wins |
Build warns about a ## that matches no slide (the quality checker makes this an error), a step number that is not canonical, an invalid {#id}, unknown emphasis effects, and emphasis targets not found in the slides.
dur = override.dur ?? max(anim, audio ? lead + audio + pad_after : max(hold, marksEnd + pad_after)) (normative: format spec §5.5 and §8.0; contract §5).
Field in "slideKey:step" |
Default | Meaning |
|---|---|---|
dur |
— | fixed length (s); audio past lead + dur is cut |
hold |
1.2 | length of a step without audio |
lead |
0.25 with audio, else 0 | silence before the audio |
pad_after |
0.6 | pause after the audio (or after the last emphasis) |
Example: {"Update rule:2": {"pad_after": 1.0}, "Update rule:concl": {"hold": 2}}. Rebuild after editing.
Built-in durations (DECK.T, seconds): fade 0.45, draw 0.7, drawSlow 1.4, drawDelay 0.1, slide change 0.35, morph 0.9. Emphasis (DECK.MK): draw 0.5, fadeOut 0.3, gap without audio 0.9, laserHold 1.5. With prefers-reduced-motion (except ?mode=video) every step is shown in its final state.
Resolution: --theme > <html data-theme> > default. A name is looked up as a path relative to the working folder, then <deck>/themes/<name>/, then in your theme folders (each folder of EGATARI_THEMES in order, then ~/.egatari/themes if it exists), then the bundled themes/<name>/; the folder must contain tokens.css. EGATARI_THEMES is a list of folders separated by the OS path delimiter (:, or ; on Windows); a folder in it that does not exist is skipped with a warning. Before anything is read, theme.json, tokens.css, logos and every parent theme (extends, at any depth) must resolve, by real path, inside the theme's authorized root: the working folder for a theme in the working folder, themes/ for a registry theme, the theme folder (its real path, computed once, so ~/.egatari/themes may be a symbolic link) for a theme in your theme folders, the theme folder itself for one given with --theme. A parent may also come from your theme folders or themes/; "extends": "default" is the bundled default unless a theme folder has its own default. Otherwise the build warns (refused: …) and does not read it; a refused working-folder theme falls back to default (format spec §11). A theme named by the file (or by extends) that is found nowhere is not an error: the build warns theme not found: "<name>" … and uses default (or no parent); a --theme that is not found is an error. The editor app does not see EGATARI_THEMES or ~/.egatari/themes: there you choose one theme folder (Load theme… → Choose folder…, read only), which takes the place of your theme folders in the same order and under the same rules (editor); in any browser, including those without a folder picker, you can instead load themes from a ZIP file (Load theme… → Choose ZIP file…), which the editor saves in the browser as “My themes” and reads at the same place and under the same rules (when your folder and My themes both have a theme with the same name, the one chosen or loaded last wins); without it, or with the file's themes/, a file whose theme is only in your theme folders shows that warning. An Egatari file (.ega.html) stores a theme from your theme folders as the file's themes/<name>/, so it rebuilds with the same theme anywhere. Deeper than 16 levels of extends is an error.
theme.json field |
Meaning |
|---|---|
extends |
parent theme: its tokens.css is placed first (looked up next to this theme, then in your theme folders, then in themes/) |
logos |
image files (relative to the theme folder; png, jpg, svg, webp) placed on every cover. Inherited through extends when omitted; "logos": [] removes them |
name |
informational |
version |
the theme's version (bundled themes listed in themes.lock.json; see “Theme versions” below) |
fonts |
the fonts the theme chooses from the list Studio can embed (“Fonts” below): {"body": "Zen Maru Gothic", "heading": "Zen Maru Gothic"}. The build embeds them (only the files with characters the file uses); the theme's tokens.css still sets the CSS (--font-sans). A family from the list that the theme's or the slides' CSS names is embedded too |
look |
which fixed shapes the theme uses for the heading, the cover and the conclusion line ({"heading": "band", "cover": "left-bar", "concl": "left-rule"}), from kit/core/theme-shapes.mjs (the conclusion line: left-rule, rounded, or rule, a line above it in --emph with no frame or ground). Bundled themes copy each shape's CSS into tokens.css between /* look <key>: <id> */ and /* /look */; tools/test-themes.mjs checks the copy. The build does not read it |
metrics |
the theme's frame geometry for the quality checker and authoring tools ("v": 1; table below). Inherited field by field through extends; omitted fields take the defaults. Never used to draw (contract §12) |
metrics fields (stage pixels of 1280×720, numbers, decimals allowed). The defaults are today's kit/layouts.css; the limits derived from them are the checker's old constants (565, 680, 1236, 1162, 124, 44). The margins (6 and 4) are policy, not theme values. A theme that moves these boxes in its CSS should declare them (bundled and official library themes must); node tools/theme-metrics.mjs measure <theme> prints the block to paste.
| Field | Meaning | Default | Used by the checker as |
|---|---|---|---|
body.left, body.right, body.top |
the horizontal .body box (left and right as distances from the edges) |
48, 48, 122 | right limit 1280 − body.right + 4 (bodyRight) |
body.floor |
how far the body may go down without a conclusion line (noconcl; above the page number) |
680 | bottom limit with noconcl |
body.line |
the height of one body line, only for the “about n lines” in findings and fix requests | 46 | messages |
concl.top, concl.height |
the horizontal conclusion line box | 571, 72 | bottom limit concl.top − 6 (bodyBottom) |
tate.rule |
x of the rule of the vertical heading (layout-tate) |
1166 | right limit tate.rule − 4 (tateBodyHead) |
tate.conclRight, tate.left |
right edge of the vertical conclusion column; left of the body without a conclusion | 120, 48 | left limit tate.conclRight + 4 (bodyConclCol) / tate.left − 4 (bodyLeft) |
tate.floor |
bottom limit of the vertical body | 680 | bottom limit of layout-tate |
A value that is not a number, outside 0–1280 (x) or 0–720 (y), an unknown field, v other than 1, or values that do not fit together (the body top below the conclusion line, a body narrower than 320px, …) is a build warning (theme-metrics: …) and the parent's (or default) value is used. The checker compares the declaration with what the theme renders (themeMetricsDrift, below).
Bundled themes. New files choose from eight themes, shown by Japanese colour names with a small note on what each suits: 藍 Indigo (default; research and classes), 墨 Ink (sumi; reports and proposals), 国語 Kokugo (kokugo; Japanese language arts), 常盤 Evergreen (tokiwa; science, nature, schools), 江戸紫 Edo purple (murasaki; research and public talks), 焦茶 Dark brown (kogecha; humanities, history, local studies), 浅葱 Teal (asagi, in Zen Maru Gothic; primary schools, publicity, guides), 弁柄 Red ochre (bengara: warm paper, deep ink and one accent, headings in Fraunces and BIZ UDPMincho, the conclusion line as a rule; talks, reading and ceremonies). The list and the notes are kit/core/themes-list.mjs. business is no longer offered for new files (the editor's lists, npm run new); it stays bundled, so a file that names it or recorded its version builds and plays as before. sumi takes its place. All eight keep the role colours and the boxes of default (the checker's limits are the same); they change colours, rules, bands, corners and fonts only. Theme CSS is written with at least the specificity of the built-in rules (.slide h2 is 0,1,1): never wrap it in :where(), which drops it to 0 so that some declarations lose to the built-in ones (a heading band with the heading's own dark text on it). node tools/test-themes.mjs builds a sample in every bundled theme and checks: the quality check (no textContrast, secHeading, fontNotEmbedded or metrics warnings), text contrast 4.5:1 for every role colour on --bg, the conclusion line on --concl-bg, the divider, the cover title and the heading on its own ground; and colour vision simulated with Machado et al. (2009) at severity 1.0: --emph against --term at least ΔEab 35 for normal, protan and deutan vision and ΔE00 20 for all four, --emph against --fg ΔE00 20 for protan; --lit against --emph with the same limits as --emph against --term (its contrast with --bg is measured and printed, not required, since --lit is drawn with an outline); every bundled theme declares --lit in its own tokens.css; the dark colours of the part thumbnails (DARK in tools/part-thumbs.mjs, the only dark role colours: the bundled themes have no dark version) give --lit at least 3:1 on their --bg and ΔEab 35 from their --emph for all four; every bundled theme declares the eleven object colours --obj-* in its own tokens.css as hex, each recognisably its name in OKLCH (hue windows red 15–45°, orange 50–80°, yellow 85–115°, green 125–165°, blue 235–275°, purple 285–335°, pink 340–15°, each chroma ≥ 0.10; brown hue 40–80° with lightness 0.35–0.60 and chroma 0.04–0.12; white lightness ≥ 0.95, black ≤ 0.32, gray 0.50–0.75, all three chroma ≤ 0.02), adjacent names (red–orange, orange–yellow, yellow–green, green–blue, blue–purple, purple–pink, pink–red, brown–orange, brown–red, gray–white, gray–black) at least ΔE00 20 apart for normal vision (the limit used for --emph against --term; colour-vision simulation is not required, since an object colour is always shown with its name or initial), and their contrast with --bg is printed, not required; and the pen colours (below). It also checks the colour ramps (#200): every bundled theme declares --ramp-1 … --ramp-5 as hex in its own tokens.css, OKLCH lightness falls by at least 0.05 from each stop to the next, and --ramp-5 is at least 3:1 on --bg.
CSS order: the build writes, in <style id="deck-base">, the fonts, KaTeX, kit/base.css, kit/layouts.css, the theme's tokens.css (parent themes first) and, for slides whose lang is not Japanese, kit/latin.css. The theme comes after the layout CSS, so a theme rule with the same specificity overrides a layout rule (for example .cover h1{top:260px} or .body{left:96px;right:96px}); no html prefix is needed. The meaning of the color tokens (contract §12) and the quality checker's color checks still apply to such a theme. This is the same in every build path (CLI, --dev and the dev server, --portable, --play-only, the editor app).
| Token | Meaning |
|---|---|
--base |
base color; the others derive from it in themes/default/tokens.css |
--emph-hue |
hue of --emph: a theme that sets it gets --emph = oklch(0.52 0.21 <hue>) (kokugo: 38). default does not set it and fixes --emph at #BE3012 (from 1.1.0) |
--fg --bg --title --term --emph --muted --line --rule |
text, background, headings, terms, conclusions, known results, thin lines, heading rule |
--lit |
light and what it lights (the sun, a lamp, the lit side of the Moon): a fill colour, never a text colour, always drawn with an outline in --fg or --muted (format spec §8.4). A warm yellow in every bundled theme (default #F5B800, from 1.3.0); on a light background it is only about 1.4–1.8:1, so the outline carries the shape. A part that uses it gives a fallback from the other roles (var(--lit, …)) |
--obj-white --obj-black --obj-red --obj-green --obj-yellow --obj-blue --obj-brown --obj-purple --obj-pink --obj-orange --obj-gray |
object colours: colours that are themselves the content (a red ball in a bag, blue litmus paper, a green light), the eleven basic colour terms (format spec §8.4). Only where the colour is what is shown: chart categories use --series-1 … --series-4, meanings use the roles above. Never the only carrier: show the name or initial (「赤」, "R") on or beside the object, and outline shapes in --obj-white, --obj-black or a colour near the background with --fg or --muted. A part that uses one gives a fallback, which may be a literal colour of that name (var(--obj-red, #E0242B)); color-mix() of object colours makes colours between them. Every bundled theme sets all eleven (from default 1.4.0; default #FFFFFF #222222 #E0242B #2E9E44 #F5D90A #1E6FD9 #8B5A2B #8E44AD #F27BB0 #F28C1A #8C8C8C, shared by sumi, kokugo, tokiwa, murasaki and business; kogecha slightly less saturated, asagi slightly brighter) |
--caution --warn |
caution (amber) and warning (red-orange); label and icon colours, mixed with --bg in OKLCH for borders (85%) and tints (8%); text on each tint must reach 4.5:1 |
--complement --accent2 --base-tint --base-wash --comp-tint --term-tint --emph-tint |
derived colors and tints (--term-tint: .thm; --base-wash: .box; --emph-tint: not used by the kit now; kept so that existing themes and files keep working) |
--series-1 … --series-4 |
figure series colors |
--ramp-1 … --ramp-5 |
colour ramps (format spec §8.4, #200): five stops from low to high for magnitudes (heat maps, densities, speeds), in the base colour's hue; OKLCH lightness falls from stop to stop and --ramp-5 is at least 3:1 on --bg. Never for categories or meanings. Every bundled theme sets them (from default 1.5.0) |
--scrim, --scrim-strong |
a translucent ground in the background colour, to lay under text on a background picture (#141; bengara 1.0.0) |
--preview-opacity |
show later steps faintly: opacity of steps not yet reached (0.45; a theme may set it within 0.45–0.5 so that it stays readable on a projector; --lecture-dim is an alias) |
--font-sans, --weight-body |
font family and body weight |
--kicker-size, --kicker-color, --kicker-weight |
kicker (a short line above the heading): size (24px), colour (--muted), weight (700) |
--cover-bg, --logo-h |
cover background, logo height (128px) |
--sec-bg, --sec-fg |
divider background (--base) and text (white) |
--concl-bg |
conclusion line background (default: #F5F5F5 from 1.2.0; transparent before) |
--marker |
list markers in .body (--term) |
--bar, --bar-h |
progress bar color (--emph; --term during autoplay) and height (3px) |
--stage-bg |
area around the slide (#2f2f2f) |
--cap-size, --cap-bottom, --cap-side, --cap-max-lines |
caption font size (27px), distance from the bottom (18px), side margins (96px), max lines per caption chunk (3) |
--cap-rate |
caption reading speed when presenting by hand (characters/s; default ja 7, en 15; also DECK.captionRate) |
Theme versions. A bundled theme that changes how files look gets a new version in its theme.json, and the earlier version stays in vendor/themes/<name>/<version>/, listed with its identity hash and the colors that changed in themes.lock.json (npm run themes:check checks the copies against the lock; in npm test). default 1.1.0 (--emph #C50516 → #BE3012, --muted #6E6E6E → #5C5853) is the first such change; 1.0.0 is default as of Studio 0.4.6. business 1.0.1 (--emph #C2410C → #BA3C05) darkens its orange so that text on --emph-tint reaches 4.5:1. default 1.2.0 marks the conclusion row with a left bar in --emph, bold text, its fixed position and a light grey ground (--concl-bg #F5F5F5), left-aligned instead of a centred frame; position and height are unchanged, and vertical (layout-tate) slides keep the frame. default 1.3.0, business, kokugo, sumi, tokiwa, murasaki, kogecha and asagi 1.1.0 add the role --lit (no existing colour changes). default 1.4.0 and the others' 1.2.0 add the object colours --obj-* (no existing colour changes). Why these colors: themes/default/README.md. Documents at the top of a theme folder (README*, LICENSE*, *.md) are not part of the theme: the build never reads them (not even when listed as a logo) and they are not counted in its hash (spec §6). When an Egatari file carries a user theme or a theme in the file's own themes/ folder, the theme's LICENSE* files go with it (themes/<name>/LICENSE…, back in the folder on unpack), since a theme's licence (fonts, an institution's logo terms) must travel with its assets (§3.3); README* and other *.md files are left out. As for parts, a file is never restyled silently: an Egatari file records each theme's name, version and hash (index.themes) and its egatari.json pins the version ("themes": {"default": "1.1.0"}; unpacking an older file without it pins the version whose hash the file recorded). A build of a folder pinned to an earlier version uses that copy and warns theme pinned: … with the colors that would change; --update-themes (or setting the pin to the current version) updates it. A folder without a pin follows the current version. The editor rebuilds an opened file with the theme version it recorded and offers Update theme (editor). A theme that extends default uses the pinned default too. An Egatari file keeps playing with the theme CSS it embeds, whatever the editor's version.
Fonts: Japanese files (lang is ja or missing) embed BIZ UDPGothic; other languages embed Source Sans 3 and use BIZ UDPGothic only for characters past U+024F. Only the font files (or, with fonts/*.ttf and uv, the glyphs) that the file uses are embedded. BIZ UDPMincho is embedded as well, for the same characters, only when the file uses it: var(--font-mincho) in the file, its theme or a part it uses, class="mincho", or <html data-font="mincho"> (the definition of --font-mincho in kit/layouts.css does not count). --font-mincho is defined with :where(:root), so a theme can override it. Theme kokugo: Mincho body text, indigo base, vermilion emphasis, off-white background, captions in BIZ UDPGothic (--font-cap).
English italic: Source Sans 3 italic is embedded only for text the file sets in italic (<em>, <i>, <cite>, <dfn>, <var>, font-style: italic in a style attribute, a <style> in deck.html that sets italic, or a part's code that sets italic text; a part's math symbols in KaTeX_Math do not count): 400 italic for that text, 700 italic only for italic text inside bold (<b>, <strong>, headings, <th>, the conclusion line, .sub), and of each only the files with those characters. A file without italic text embeds none. In a Japanese file only Latin characters count, and Latin text in <em>, <i> and <cite> is set in Source Sans 3 italic.
A theme whose body font is a Japanese font from the list (asagi: Zen Maru Gothic) embeds BIZ UDPGothic only for characters that font does not cover.
The fonts a file can carry are a fixed list, all under the SIL Open Font License and from @fontsource (FONT_LIST in kit/core/build-core.mjs). Only the fonts a file chooses go into its file, so a longer list does not make files heavier. A font is chosen by the theme's theme.json fonts, or by naming its family in the theme's or the slides' CSS.
| Group | Fonts |
|---|---|
| Japanese | BIZ UDPGothic (default), BIZ UDPMincho, Shippori Mincho, Zen Maru Gothic, Klee One (400 and 600) |
| English | Source Sans 3 (default), Source Serif 4, Andika, Atkinson Hyperlegible Next (each with italic), Fraunces (400 and 700; the headings of bengara) |
| Monospace | Source Code Pro |
From the npm package egatari, the default fonts (BIZ UDPGothic, BIZ UDPMincho, Source Sans 3) and every font a bundled theme uses (Zen Maru Gothic of asagi, Fraunces of bengara) come with it, so every bundled theme builds from npx egatari alone. The others (Shippori Mincho, Klee One, Source Serif 4, Andika, Atkinson Hyperlegible Next, Source Code Pro), which only the slides' CSS or its own theme can name, are in the separate package @egatari/fonts-extra: install it next to egatari (npm i -D @egatari/fonts-extra, or npx -p egatari -p @egatari/fonts-extra egatari …). The build finds it from the egatari package and from the current folder. Without it, the build warns fonts-extra: … and the checker reports the error fontsExtraMissing with the install command; the font is never replaced silently. A repository checkout has every font (npm ci).
CSS may name any other font (one installed on the device, for example), but it is not embedded: each device shows its own font, or the next one in the list. The checker warns fontNotEmbedded once per file with the names (the first family of the computed font-family of slide text that is neither embedded nor generic). The offline editor (editor.html) carries only BIZ UDPGothic and Source Sans 3; a file that chooses another font is built there without it, with a warning.
| Token | Meaning |
|---|---|
--font-mincho |
Mincho family ("BIZ UDPMincho", "Hiragino Mincho ProN", "Yu Mincho", serif) |
--font-cap |
caption font (default --font-sans) |
The list of parts and their props is vendor/components/CATALOG.md (generated by node tools/catalog.mjs from the frontmatter of each README, default versions). The parts come from egatari/components: Studio carries copies of its releases in vendor/components/sha256/<hash>/, pinned in components.lock.json; npm run components:update -- vX.Y.Z brings in a release (the only networked step: it checks the tarball against the release's manifest.json and keeps every version), npm run components:check checks the copies against the lock (in npm test). New parts are proposed in egatari/components issues. The part API (DECK.define, DECK.MotionElement, static steps, static props with type: number | bool | json | string, mount, duration, cues, render) is in contract §3 and studio: parts.
Helpers on DECK for parts: el(tag, attrs, parent) (SVG; var() colors moved to style), mtext(parent, x, y, "*x*_0", attrs), svgMath(parent, x, y, tex, {size, anchor, color, w, h}), Plot(box, {xr, yr, xt, yt, xf, yf, xl, xl2, yl, noY, m}) with .x() .y() .d(f, a, b, n) .poly(pts) .clip, prog(t, start, dur), lerp, ease, clamp01, color(name).
Links to slides and menus. <a href="#<slide id>"> and <a href="#<slide id>:<stepKey>"> are ordinary links to a slide or a step (no script; allowed in Core documents); the runtime follows them inside the document and offers Back (contract §9). Use the ids that npm run ids assigns. m-menu lays such links out as a grid of cards (title, data-sub subtitle, data-icon badge, an optional "visited" check for slides shown in this session, cards appearing by step with per-step): m-menu README (1.0.2); example: slide 2 of examples/kokugo-kanbun. Links inside slides take --term with an underline.
For 国語 files (kanbun, classical and modern Japanese). The example is examples/kokugo-kanbun (theme kokugo).
- Vertical writing:
<div class="tate">…</div>inside.bodysets the text inwriting-mode: vertical-rl, filling the height of the body, columns from right to left (paragraphs are separated to the left;p.indentindents the first line)..tcysets two-digit numbers upright - Vertical slides:
<section class="slide layout-tate">sets the whole slide vertically. The<h2>is one vertical column at the right edge (1166–1232px, from 48px down, top-aligned); the theme's heading rule becomes a vertical rule on the left of that column, and the column does not wrap (about 14 full-width characters; the quality checker reports a longer one). The.body(148–1138px, 48–664px; from 48px withnoconcl) is inwriting-mode: vertical-rl: paragraphs and lists run in columns from right to left, and a.tateblock fills it. Parts, figures and tables in it (direct children other thanp,ul,ol,.sub,.note,.arrow,.tate,.box,.thm,.caution,h3,blockquote) stay horizontal at the full body width, since they measure their own box; use their vertical option (m-kobun tate,m-gendai tate;m-kanbunis always vertical). The.conclis a vertical column at the left edge (48–120px; about 19 characters). The page number stays at the bottom right, below the heading column. Only the CSS changes: slide ids, captions and the readable layer of an Egatari file take the heading text as before. Example: the 現代文 slide ofexamples/kokugo-kanbun; tests:tools/test-layout-tate.mjs - Ruby:
<ruby>漢<rt>かん</rt></ruby>;rtis 0.5em and the quality checker does not count its size. In vertical text the reading is on the right - Mincho:
.minchoor<html data-font="mincho">, or a theme that sets--font-sans: var(--font-mincho)(themekokugo) m-kanbun: kanbun in vertical writing. One line per column; after a character:(送り仮名),[返り点](レ,一二三四五,上中下,甲乙丙丁,天地人,一レ,上レ, …; a bareレalso works),{振り仮名},{=かな}(written in hiragana in the 書き下し文, e.g.不{=ず}),{-}(置き字, not read),(右|二度目)(再読文字, e.g.未(ダ|ず)),-(竪点),、。. Steps: 白文 →kunten(返り点 lower left, 送り仮名 lower right) →order(characters highlighted in kundoku order, an arc where the eye jumps back; one step per line (句) since components v1.4.0, and a return to an earlier line by a 返り点 or a 再読文字 starts a step of its own;order-by="all"keeps the whole reading order as one step, withcues(k)at the start of each column from the second) →kaki(書き下し文 on the left). Rules and details: m-kanbun README (1.6.0)m-kobun: classical Japanese split into words (春[名]/は[係助]/…), colored by part of speech, one sentence per step, and a modern translation (= …lines) in the last step. Clicking (or Enter on) an auxiliary verb[助動・基本形・意味・活用形]opens a card with its conjugation table and meanings, taken from a table inside the part (no network, text only). The card is a presenting control outsideDECK.seek(i, k, t): it closes whenever a step is entered (also the same step again), never opens in video mode and is not printed. m-kobun README (1.0.2)m-gendai: modern Japanese:__傍線__,==二重傍線==,{語句|_A,#id}/{これ|>id}(an arrow from a demonstrative to what it refers to), paragraphs@主張#p3,@具体例#p1>p3,@対比#p2~p1boxed by role and joined by lines. Horizontal ortate. m-gendai README (1.0.2)
| Parameter | Meaning |
|---|---|
?mode=talk |
default: later steps hidden, current step fades in |
?mode=talk&preview=1 |
show later steps faintly: everything visible, later steps faded (--preview-opacity, default 0.45; elements marked data-preview="none" and parts that declare preview: "none" stay hidden), the current step and earlier ones at full strength with no mark on the current step (no highlighter, no .cur class), emphasis in final state |
?mode=learn |
the former self-study mode, removed in Egatari Player 1.4.0: read as ?mode=talk, whose toolbar now has playback (Playback and progress) |
?mode=video |
for rendering: no tools or toolbar, reduced-motion ignored. Opened by a person (not by an automated browser, which is how the export and the tools capture it), video mode shows one Play button in the middle; pressing it plays the file along the timeline to the end with no other controls (Player P1). offer.open.mode video opens this way too |
?captions=1 |
start with captions on (same as s). With ?mode=video this is the only way to get captions, so a render can burn them in |
?capsize=s / m / l |
caption size (22 / 27 / 34px); overrides the remembered size; ignored with ?mode=video |
?presenter=1 |
presenter view (opened by p) |
?view=follow / ?view=next |
internal: the iframes inside the presenter view |
#N |
open at slide N (1-based); updated while navigating |
#<slide id> / #<slide id>:<stepKey> |
open at that slide (step 0) or step (0, 1, … or concl), in its final state (contract §9) |
?embed=1 |
in a frame: once the file has loaded and can take commands, post {egatari:"ready", version, docId, sourceSha256?, timeline} to the parent once (before the first position; version is the player version, docId is null in a working-folder build, sourceSha256 only in an Egatari file, timeline has one {slideIndex, slideKey, stepKey, slideTitle, dur} per step); post {egatari:"position", slideKey, stepKey, t, cause} on every step change; accept {egatari:"links", follow} from it. A host can send commands as soon as ready arrives. Messages go to target origin *. All commands and events: Embedding |
?links=0 |
with ?embed=1: links to slides do not move the player; it posts {egatari:"linkRefused", slideKey, stepKey} instead |
?layout=slides / flow / split |
open with the slides only, the book only, or slides and book side by side (Slides and book); pages opens the book scrolled for now. Wins over the layout remembered on this device. With ?embed=1 the host can also send {egatari:"layout", id?, layout}; the player answers with the same message and the layout it shows |
| Key | Action |
|---|---|
| → ↓ Space PageDown | next step |
| ← ↑ PageUp | previous step (shows it in its final state) |
| Shift+→ / Shift+↓, Shift+← / Shift+↑ | next / previous slide (step 0) |
| Home / End | first / last slide |
| digits + Enter | go to that slide (while playing, playback goes on from there) |
| f | fullscreen (where the browser has element fullscreen; on iPhone Safari, or framed without the fullscreen permission, the bar has no fullscreen button and the key list leaves f out; when the browser refuses, the player says “Could not go fullscreen”) |
| p | presenter view (p again closes it; in the presenter view, Esc or p closes it, or only leaves fullscreen) |
| a | play / pause from the current step (audio if any). Pause and play again continue from the same point. Any navigation key stops playback |
| < / > | playback speed slower / faster (0.75, 1, 1.25, 1.5, 2×) |
| l | show later steps faintly (on/off) |
| b | black screen (turns the whole window black, with a faint hint in the corner for 2 s and on mouse move; b again, Esc, a click, the arrows, Space, PageUp/PageDown or Home/End bring it back without moving the slide; the presenter view shows "Black screen", and b there toggles it on the main window; the arrows, Space and PageUp/PageDown there also only end it) |
| s | captions on/off: the current step's script (display text) at the bottom of the slide |
| Shift+s | caption size: S → M → L (22 / 27 / 34px), with a brief notice; the last choice is remembered (localStorage) |
| o | overview (arrows, Home/End, Enter/Space/click to go, Esc or o to close) |
| r | layout: Slides → Slides and book → Book (without a book: Slides and script → Read with script); remembered on this device. Not in the dev server's preview |
| x | laser pointer (hides after 2 s without movement) |
| d | pen (pressure-sensitive; ink stays per slide) |
| v | fading pen (fades 0.7 s after you stop, over 0.5 s) |
| Shift+d | pen color: Red → Blue → Black, with a brief notice "Pen color: Blue". The pen colors are fixed, whatever the theme: the red #FF4B00 and blue #005AFF of the Color Universal Design palette and black #000000 (on white 3.4, 5.4 and 21:1, at least 3:1 for lines; at least ΔE*ab 61 apart under simulated colour vision). tools/test-themes.mjs checks them on the ground of every bundled theme |
| Backspace / Shift+Backspace | while the pen or fading pen is active: clear this slide / all slides |
| Backspace / Alt+← | otherwise, after following a link to a slide: back to where the link was clicked (also the Back button at the top left and the browser's back button) |
| Tab / Shift+Tab | focus the control-bar buttons (Enter / Space presses; Esc returns to the slide) |
| Esc | leave the tool, close help |
| ? | key list (with dev-server keys when served by server/dev.mjs), and File info (title, created by, edited by, copyright, license, attribution) when the file has them |
When a file opens, the toolbar stays for about 5 s. The first time on a device (remembered in localStorage; shown every time when storage is not available), one line above it says how to bring it back: “Move the mouse to the bottom of the screen (or tap) to show the toolbar”, or on a touch device ((hover: none)) “Tap the screen to show the toolbar” (hidden from screen readers, which reach the toolbar with Tab); it goes when the toolbar hides. After that the toolbar comes back when the mouse moves (or, on a touch screen, when the slide is tapped; that tap does not advance the slide) and hides after 2.5 s without movement, unless the pointer is over it or it has focus. While it is hidden, a small faint button at the bottom left, Show toolbar, brings it back with a click, a tap or the keyboard (Tab reaches it; Enter moves focus to the first toolbar button; a click or tap leaves focus on the slide). A tap that wakes the hidden toolbar, or a tap on the handle, only shows it and never also presses a toolbar button. The handle and the hint are not shown in video mode, in the presenter view's inner screens, with embed=1&controls=0 (which also leaves out the toolbar) or after the host's {egatari:"controls", visible:false}, or in print. On a narrow screen (such as a phone held upright) the toolbar wraps onto two rows to stay within the screen, and the slide scales down to the screen width.
Buttons: previous, Play / Pause, next, Playback speed (previous, next and the speed belong to playback: while playing, previous and next keep playing), laser pointer, pen, fading pen (both pen buttons carry a dot in the current color; while a pen is active, Red/Blue/Black swatches appear after them; click one to pick it, the selected one is aria-pressed), clear ink (this slide, in any tool), overview, show later steps faintly, captions, Listen with read-aloud (not saved as audio) (only when the browser has speech synthesis and some step has a script but no audio; see Listen with read-aloud), presenter view, fullscreen, help, and a small “AI voice” badge when any step's audio is TTS (format spec §7.3). Tab moves into the bar (it stays visible while it has focus), Enter/Space presses the focused button and keeps focus there, Esc returns focus to the slide; a mouse click never leaves focus on a button. It sits in the letterbox below the slide when there are at least 44px, otherwise over the bottom edge and only when the mouse is near the bottom. Hidden in print and video.
Self-study is the slide show with playback (Player P1); the separate learn mode is gone since Egatari Player 1.4.0, and a ?mode=learn, a learn in offer or an embedding command is read as talk. A file opened directly or in an LMS opens in the slide show with the toolbar: previous, Play / Pause (a), next and Playback speed (the button shows 1× and steps through 0.75, 1, 1.25, 1.5 and 2×; < / > slower / faster), then the presenter tools, overview, view, show later steps faintly, captions, read-aloud, presenter view, fullscreen and help. The narration plays at the chosen speed with its pitch kept, and the steps advance at the same speed. Pause and play again continue from the same point. While playing, the toolbar's previous and next, digits + Enter and a choice in the overview keep playing from the new step; the presenter's step keys (→, Space, ← and the rest) pause it, as a presenter expects. Playback pauses when the page is hidden. With ?embed=1 the host can send {egatari:"play"}, {egatari:"pause"}, {egatari:"rate", value} and {egatari:"mode", id?, mode} (it answers the current mode, talk for learn, or an error with code mode: the mode is chosen when the file loads), and gets {egatari:"state", playing, rate} (and playBlocked).
Offered modes and faces. metadata.offer in egatari.json ({modes?, faces?, open?: {mode?, face?}}, format spec §1.2) is copied into deck-meta.offer by every build (the working folder's out/deck.html, the Egatari file and its play-only copy), with a former learn written as talk and unknown values dropped. The player opens in this order, the first that applies winning: ?mode= / ?layout= (or the embedding host), then the layout last chosen on this device, then offer.open, then metadata.primary (face), then <html data-mode> (mode), then the slide show in Slides. When offer.modes has no talk and offer.open names no mode, it opens in the first offered mode. Faces not in offer.faces are left out of View, r and Read in the book (talk is Slides, read the book; Slides and book needs both); an explicit ?layout= may still open them. This is the author's intent, not access control.
Progress (Player P6, format spec §9.2) is recorded through one adapter, the first found of: a SCORM 1.2 API (this window and up to 7 parents, then the opener; SCORM 1.2 binding), the parent of an ?embed=1 frame (postMessage), and this device (localStorage). A step counts as played (via: "stage") when it is reached while the slides are shown (Slides, Slides and book, Watch on slides; in the book alone only while the script's live slide is playing) by its own playback or navigation (next, play, a click on the slide, a step link); a step the slides only moved to because they followed the book is not played. A step counts as read (via: "text") when its section of the book (or its script in Read with script) stays in view for 3 seconds; scrolling past does not count. The two are kept apart. The file is complete when every step is played or read, or as metadata.completion says (visitedFraction, reachedEnd, and played: true to count only played steps). Events: started, step {slideKey, stepKey, index, total, via}, completed, suspend {location, data}. SCORM cmi.suspend_data is {"v":1,"n","h","seen","stage","text"}: seen as in the binding (played or read), stage and text the two sets (never dropped). When a SCORM API or an embedding host is found, its location wins and the device's Resumed where you left off is not applied. Nothing is recorded in the editor's preview, video or the presenter view, and nothing is written into the file. Egatari files list ["scorm12","postmessage","local"] in deck-meta.tracking; every build (the working folder's out/deck.html too) copies metadata.completion from egatari.json into deck-meta.completion.
The ? help ends with a Send feedback link and the version (for example v0.2.0). It opens the feedback form prefilled with the version (the player's; the Studio that made the file is added to the context when it differs), browser, OS, slide language and mode only; nothing from the file is sent. Not shown in video or print, or with data-feedback="off".
A host page that puts a file in an <iframe> with ?embed=1 drives it with postMessage (Player P8). The player accepts messages only from window.parent, as objects with a string member egatari, once it has sent ready; it posts to target origin *. A command may carry an id, which the reply echoes. Times are seconds; a t of null is the final state of the step.
| Command (host → player) | Effect and reply |
|---|---|
{egatari:"seek", id?, slide, step, t} |
go to that step at time t: slide is a slide id (ready.timeline[].slideKey) or an index from 0, step a step label ("0", "1", … or "concl"; a whole number is read as that step; left out = "0"), t seconds or null (left out = null). The playing state is kept: while playing, playback goes on from t (from the start of the step when t is null, as the toolbar's jump does). Replies {egatari:"seeked", id?, slideKey, stepKey, t} after the position it causes |
{egatari:"play", id?} / {egatari:"pause", id?} |
start / pause playback; playBlocked if the browser refuses to start audio |
{egatari:"rate", id?, value} |
playback rate (0.75, 1, 1.25, 1.5 or 2) |
{egatari:"mode", id?, mode} |
replies {egatari:"mode", id?, mode} with the current mode; another mode is an error (chosen when the file loads, ?mode=) |
{egatari:"layout", id?, layout} |
slides, flow or split; replies {egatari:"layout", id?, layout} |
{egatari:"preview", id?, on} |
show later steps faintly (true) or not (false), as the l key; replies {egatari:"preview", id?, on}. Not in video mode |
{egatari:"controls", id?, visible} |
show or hide the player's own controls: the toolbar, its handle and hint line, and the play and View buttons of the book (the same things as controls=0). Keys still work. Replies {egatari:"controls", id?, visible}; visible:true after controls=0 builds the toolbar |
{egatari:"links", id?, follow} |
let links to slides move the player or not; replies {egatari:"links", id?, follow} |
{egatari:"snapshot", id, …} |
not implemented (OPTIONAL in Player P8): replies {egatari:"error", id, code:"unsupported"} |
| Event (player → host) | When |
|---|---|
{egatari:"ready", version, docId, sourceSha256?, timeline} |
once per loaded document, before the first position (see ?embed=1 in URL parameters) |
{egatari:"position", slideKey, stepKey, t, cause} |
on every step change; cause is play, seek, control or link |
{egatari:"stepEnded", slideKey, stepKey} |
playback has played that step to its end. Not for steps that were skipped (next, jump, seek), nor when playback was paused or stopped first |
{egatari:"ended"} |
playback has played the last step of the timeline to its end; it comes after that step's stepEnded and the state with playing: false |
{egatari:"state", playing, rate} |
whenever the playing state or the rate changes |
{egatari:"playBlocked"} |
audio could not start without a user gesture |
{egatari:"linkRefused", slideKey, stepKey} |
a link to a slide was not followed (?links=0 or links follow:false) |
{egatari:"error", id?, code, message} |
a command failed: unsupported for snapshot and for an unknown command; otherwise the command's name (seek, preview, controls, mode, rate, layout, links) for arguments it cannot use, and the player stays as it was |
Narration turns (turn, OPTIONAL in Player P8) are not sent. The progress events of the postMessage adapter are in Playback and progress.
A file can be shown in three layouts (Player P2): Slides (the stage alone), Slides and book (the slides on the left, the book on the right, in both writing modes) and Book (the book alone). The book is the file's article (format spec §9C) when it has one; without one the text pane is Read with script: each slide small, followed by its steps' script (and Slides and script side by side). Choose with View (in the toolbar and at the top of the book) or r.
- Opening layout.
?layout=(or the embedding host), then the layout last chosen on this device for this file (localStorage; never written into the file; only when its face is offered), thenoffer.openindeck-meta, thenmetadata.primary("read"opens the book), then Slides (the book whenoffer.facesleaves out the slides). Below 609px of width, Slides and book becomes the book alone. - One position. Every layout shows the same slide and step; switching keeps it. Moving the slides scrolls the book to the section of the slide (or the step's script) only when it is off screen; scrolling the book moves the slides: to step 0 of the section's slide, then to the step of each step link to that slide as you read past it (a section linked to no slide leaves the slides where they are). The current section or step has a rule at its line start (left; top in vertical writing) and
aria-current. - During autoplay the book follows. When you scroll the book, it stops following (playback and the position go on) and Back to the playing part appears at its bottom; it brings the book back and follows again, as does starting playback again.
- Read in the book (top right of a slide that has a section, in Slides) opens Slides and book at that section (the book alone on a narrow screen); Back at the top of the book returns.
- Watch on slides (after the heading of a section linked to a slide, in the Book layout; also a step link or a small slide there) shows that slide over the book at 80% of the screen (the whole screen on a phone) and plays the step's motion. ← / → step, the autoplay button plays the audio, Esc, Close or a click outside closes it and returns to the place you were reading. Focus moves into it (a labelled dialog) and back to the button. In Slides and book, a step link moves the slides instead.
- Divider (Slides and book): drag it, or focus it and use ← / → (Shift: larger), Home / End; double-click or Enter resets it (the slides full height, up to 60% of the width). The slides keep at least 280px and the book 320px. Remembered on this device.
- In the book, the arrows, Space, PageUp / PageDown and Home / End scroll it; in vertical writing (
writing-mode: vertical-rl) the book starts at the right, the mouse wheel and ↓, ←, PageDown, Space go forward (left), and → goes back. Cross-references, citations and footnote links scroll inside the book, with Back (also Backspace). - Read with script, book alone: each slide is shown small at its final state and scrolls with the script like a figure; scrolling moves your reading position but plays no steps, and a slide never stays fixed over the text. Tap a small slide to open it in Watch on slides. During autoplay the playing slide stays live on its small slide and the book follows it; with
prefers-reduced-motion, the playing slide shows each step's final state. - Reading aids at the top of the book (Player P2): Contents lists the chapters and sections (without a book, the slide titles) and marks the one you are reading (bold, a rule,
aria-current); ↑ / ↓, Home / End and Enter choose, Esc closes. Search (also Ctrl+F / ⌘F in the book) searches the whole text, also in vertical writing and across emphasis and ruby, ignoring spaces, case and full-width / half-width; Enter / Shift+Enter go to the next / previous result, Esc closes. After a jump from the contents, a cross-reference, a citation or a footnote, Back (also Backspace) returns. A thin bar under the top shows how far you have scrolled (no page numbers). - Text and background (the Aa button): text size in six steps (85–175%, the text reflows, the slides keep their size), line spacing Normal or Wide, and background White, Sepia or Black for the book only (the slides keep the theme colours; White is the theme's own light ground). Remembered on this device for every file (
localStorage), never written into the file. These follow the user settings of EPUB reading systems (Readium CSS). - Resuming where you left off. On this device, a file that opens in Slides and book or Book returns to the slide, step and place in the book you were reading, with a one-time notice Resumed where you left off (ja 「前回の続きから」) and Start over. Not when the file opens at a
#place (other than a reload), opens in Slides, is embedded or is in the editor's preview. - Figures in the book enlarge on a click (or Enter / Space): a labelled dialog with the figure's caption; Esc, Close or a click outside returns to the figure. A small slide in Read with script opens Watch on slides.
- During autoplay, Read with script highlights the turn of the script being read (a tint; the step keeps its rule).
- Pages and two-page view and a second window come later.
s, the CC button, or ?captions=1 shows the current step's script (the display text of narration.md, readings and {mark} removed) in a bar at the bottom of the slide: --fg background, --bg text (the quality checker keeps their contrast ≥ 4.5:1). The step is split into sentence groups (about two lines; shorter at larger sizes; overlong sentences are split at commas or word boundaries) and one group is shown at a time, at most --cap-max-lines (3) lines; if a group still overflows, its last lines are shown. While presenting by hand (and in autoplay without audio) the groups advance at reading speed (ja 7 characters/s, en 15; --cap-rate or DECK.captionRate), restart at every step change, and the last group stays. During autoplay with audio, and in ?mode=video&captions=1, each group is shown for a share of the audio proportional to its length (in video without audio the whole step is shown); the size is set with Shift+s, ?capsize= or the theme's --cap-size; in video this depends only on (i, k, t). When the toolbar sits over the bottom edge, the captions move up above it while it is shown and back down when it hides. Never printed. render/render.mjs opens ?mode=video without captions; pass the parameter there to burn them in.
The speaker button in the toolbar, Listen with read-aloud (not saved as audio), reads the current step's script with this device's speech synthesis (the Web Speech API, format spec §5.6). It is for steps without audio: on a step with audio the button is greyed out and says that the step has audio (autoplay a plays it). While it reads, a label at the top left says Reading aloud; moving to another step, Esc, or pressing the button again stops it.
- Only voices that run on the device are used (
localService === true, matching the slides'<html lang>; the exact region, the device's default voice and well-known natural voices come first; robotic and novelty voices such as Eddy or Bad News come last and are not used for Novice). Network voices are never used, even when the browser offers one as its default, because they send the text off the device. With two local voices for the language, Expert and Novice get different voices; with one, it reads both. Without any, nothing is read and a notice says “This device has no read-aloud voice for this language”. - The text is each turn's
ttsPartsindeck-narration(format spec §4: the spoken pieces with{x|y}readings applied, the same value that entersinputHash), joined, with the same text pre-processing as the AI voice (join-num-counter@1). Every build writesttsParts(about 3–7 KB per sample); it is not shown and not used for fonts. A file built beforettsPartsexisted falls back to the display text, and the label then adds “Pronunciations not applied (older file)”. The reading dictionary (tts/yomi.yaml) is applied only in the editor's preview (see the editor) and the AI voice, not in the player. - It is not audio of the file: nothing is written to the file or a video, the timeline (
DECK.timeline()) and the rendering at(i, k, t)do not change, a step being read lasts as long as the reading, and there is no button in?mode=videoor print.
Not added in ?mode=video or the presenter-view iframes, and none of it changes pixels.
- Screen readers: a visually hidden
aria-live="polite"region (#deck-live) announces "Slide n of N: title" on a slide change, the text of the newly revealed step on the next step (math read from KaTeX's glyphs), or "Step k of K" when going back or when a step reveals no text. Each slide isrole="group"witharia-roledescription="slide"and anaria-label; hidden slides getaria-hidden="true"andinert, and in talk mode steps not yet shown arearia-hidden(lecture leaves them readable). - Keyboard: control-bar and presenter-view buttons have
aria-label(Japanese or English after<html lang>), toggles havearia-pressed, and a focus ring appears only on:focus-visible. The overview is adialogwhose thumbnails are labelled buttons; focus follows the arrow keys and returns to where it was on Esc. The help (?) is adialogthat takes focus and gives it back on close. The ink layer isaria-hiddenand never takes focus, so Tab and Esc keep working while drawing. prefers-reduced-motionshows every step in its final state (except in video).- The quality checker warns about
<img>withoutalt(alt=""marks decoration) and SVG figures withoutaria-label/aria-labelledby/<title>, and lists parts without a name (info).
Current screen (left; always shows the later steps of the slide faintly, like l, at the theme's --preview-opacity; this is the presenter's own view and does not change the main window), Next slide (top right; the next slide in its final state, with all its steps shown, even when the current slide still has steps to go; on the last slide, a plain “End”), script of this and the next step (bottom right; Novice turns labelled), slide/step counter, autoplay button, tool buttons (laser pointer, pen, fading pen, clear, overview, show later steps faintly; while a pen is active, the same Red/Blue/Black swatches, synced with the main window by color index), timer with reset (⟲), clock. Keys in the presenter window: → ↓ Space PageDown / ← ↑ PageUp, a, x, d, v, Shift+d, Backspace, Esc, o, l (l and its button turn showing later steps faintly on or off on the main window only). Ink drawn on the left screen appears on the main window. Communicates by postMessage, so it works from file://. The key row ends with a Send feedback link (same as in the ? help).
Printing (tools/pdf.mjs, or the browser) shows each slide in its final state, one 1280×720 page per slide, without emphasis, ink, tools or the progress bar.
DECK.seek(i, k, t, from), go(i, k, animate), next(), prev(), state() → {slide, step, max, key, mode, playing, rate, preview}, timeline(), autoplay(on) (play / pause; pausing remembers the point), playStep(d) (previous / next keeping the playing state, as the toolbar), jump(i, k) (go there keeping the playing state), playing(), rate(v) (no argument: the playback speed; RATES lists the five allowed), previewOn(), togglePreview(), offer() (the deck-meta.offer the player applies: {modes, faces, open}, null for all; a former learn read as talk), modeFrom (where the mode came from: query, offer, html or default), tracking() (→ {adapter, total, hash, rule, stage, text, completed, started, suspendData}, Playback and progress), stepKey(i, k), marks(i, k), morph(i), slides, mode, ready (true once the parts are mounted and the opening position drawn; a file started while not laid out waits for the stage to get a size, contract §3), NARRATION, AUDIO, MARKS, TIMING, VERSION (the version of the running player: player.version in deck-meta of an Egatari file; generator.version for a file from before 1.0; in a plain build the version in package.json), MADE_WITH (generator.version, or empty), FEEDBACK_URL (or null), feedbackUrl() (the prefilled form URL, or null), tools.{mode, setMode, clear, help, overview, color, readAloud} (color() is the pen color index 0–2, color(n) sets it; readAloud() says whether read-aloud is reading, readAloud(true / false) starts or stops it), ReadAloud (kit/core/read-aloud.mjs: spokenTurns, pickVoices, …), TtsNormalize, captions(on) (no argument: is it on), captionSize(z) ("s" / "m" / "l"; no argument: the current size; null in video), captionRate (characters/s), toast(msg) (brief notice), caption() (the caption text shown, or null), announce() (the live-region text), resolveFragment(f) (→ {i, k, key, id} or {error}), fragment(i, k), follow(f), back(), links() (→ {depth, follow, back}), visited(i | key) (contract §9), move(i, k, animate, cause) (go there with the position's cause, as the book pane does), fit() (place the stage again), stageBox (set by the layouts: the box the stage is placed in), panes.{layout(name), state(), watch(i, k), close(), menu(el), order(), offered()} (Slides and book; layout() reads it, layout("split") sets and remembers it; state() → {layout, detached, playing, overlay, article, vertical, ratio, marked, reading: {size, lh, bg}, find, progress, resumed, figure}; readable() → the book pane's body and its reading units {el, steps}, which tracking watches), openHash (the # the file was opened with, without #). Events on document also include deck:captions (detail = {on}), deck:tool (detail = {mode}: "laser", "pen", "vpen" or null, when the presenting tool changes) and deck:edit (detail = {on}; only the preview of the dev server and the editor app sends it, when edit mode changes: the runtime then turns the presenting tools off, see dev server). Events on document: deck:ready, deck:pos (detail = {i, k, max, n, key, nextKey, auto, cause, back}; cause is control, link, seek or play, back the title of the slide Back returns to or null), deck:turn (detail = {i, k, j}: during autoplay, the turn of the step's script being read, estimated from the audio time by its share of characters; j = -1 when playback stops).
node server/dev.mjs <deck.html> [--port 8730] [--theme name] (or npm run dev -- …). Details: dev-server.md.
| Item | Behavior |
|---|---|
--port n |
default 8730; if taken, tries the next ones (up to 20). --port 0: any free port |
--theme name |
same as the build option |
| listens on | 127.0.0.1 only |
| rebuilds on | slides file, narration.md, timeline.json, macros.tex, audio/manifest.json, data/, figs/, components/, the repository's kit/, vendor/components/, themes/, and your theme folders (EGATARI_THEMES, ~/.egatari/themes); the page reloads at the same slide and step |
| dev build | no glyph subsetting (faster), data-src on editable elements, audio from /deck/audio/…, build errors shown as a page |
e |
edit mode; double-click an h1 h2 p li td th, .big .note .sub .venue .au .thm .box .lead or a span in .concl; ⌘/Ctrl+Enter save, Esc cancel. A badge shows build warnings |
n |
script drawer for the current step (and preview of the next) |
c |
open comments; click to jump, "resolve" to close |
| Alt+click (on a Mac: ⌥ Option+click) | leave a comment (comments.json) |
m (edit mode; the slide controls' pen button reads “Marker” there; d also opens it) |
marker: draw circles or arrows (several for one comment while its box is open), then write the comment; the lines are kept as strokes (contract §13) |
| conflicts | a save is refused if the slides or script changed since it was opened |
| files written | deck.html (only the edited element), narration.md (only that step), comments.json, .cache/edits/ (last 30 copies) |
| endpoints | GET / (frame page; ?presenter=1: presenter window), GET /preview (the file document, sandboxed; the only framable endpoint; served only with the frame page's cap and Sec-Fetch-Dest: iframe, otherwise a 403 text page), /deck/<file> (inert: CSP sandbox, non-media as text/plain attachments), /__dev/shell.js, /__dev/editor-ui.js, /__dev/presenter.js, /__dev/events (SSE), GET /__dev/info, GET /__dev/source?range=a-b, POST /__dev/edit, GET/POST /__dev/narration, GET /__dev/comments, POST /__dev/comment, POST /__dev/comment/resolve |
Quality control in Egatari has three parts: the standards (R-fit, R-steps, … in the authoring guide), the quality check that reports findings against them, and the fix request that hands the findings to an AI. The quality checker comes as a command (npm run check, below, with every check) and in the browser (editor app: every check except the few listed under In the editor below).
node kit/check.mjs <deck.html | working folder> [--theme name] [--lang ja|en] [--json] [--no-browser] builds in memory, opens headless Chrome, and prints results per slide. Exit code 0 when there is no error, 1 if there is any error, 3 when a rule was left unaccounted (below), and 2 when the check did not finish because the headless browser failed to launch or crashed (the reason goes to stderr; with --json the output is {"ok": false, "status": "crashed", "counts": {…all 0}, "results": []}, so it is never mistaken for "0 errors" and never becomes a finding). --theme checks with another theme (otherwise <html data-theme>). Each finding (error or warning) says where (slide number, heading, id, step), what is wrong and how to fix it, with the id of the standard in the authoring guide where one applies (for example (R-title)), so the findings can be pasted into a fix request as they are. --lang chooses the language of the findings (default: the slides' <html lang>, Japanese when it is ja or missing, otherwise English). --no-browser starts no browser and runs only the checks of the source (build, ids, vocabulary, audio, attachments and so on), for sandboxes that cannot start a browser. The checks of how slides look and move are skipped: their rules are skipped (reason noBrowser) and --json adds "noBrowser": true. Run the full check with a browser before you share the file.
--json prints:
{"ok": false, "lang": "en", "counts": {"error": 1, "warn": 0, "info": 12},
"results": [{"slide": 2, "id": "s-k3f9q2", "key": "s-k3f9q2", "title": "The decay law", "step": "3",
"sev": "error", "code": "narrOrphan", "rule": "R-narr-steps", "data": {…},
"msg": "Slide 2 “The decay law” (s-k3f9q2), step 3: narration [3] has no matching step … (R-narr-steps)"}]}If status is crashed (exit code 2), the result is invalid: the check did not finish, so it is not a pass even though results is empty. A finished check says "status": "ok". renderNoise lists the step comparisons that differed only by anti-aliasing noise on shape edges and were accepted ({slide, id, step, data: {k, n, cap, faint}, msg}); they are not findings and are not counted, because whether they appear changes from run to run. A real difference is the error compOrder.
The result also accounts for every rule of the checker (kit/core/check-rules.mjs): the authoring rules R-* of the authoring guide and the checker's own families C-* (build, slide ids, links, audio, attachments, book, accessibility, morphs, reproducibility, fonts, listings). Every finding's code belongs to exactly one rule. Each rule ends in one state:
checked: it was looked at and has no error (it may have warnings or info);failed: it has at least one error;excused: it does not apply to this file, with areasonfrom a fixed list:noNarration,noAudio,noAttachments,noParts,noMarks,noMorphs,noLinks,noBook,tate,lang;skipped: this run could not look at it:noBrowser, ornotInEditorin the editor's quality check, which reports the same rules, ortate(R-geometry on a file whose content slides are all vertical: not measured yet, so it does not count as passed).
{"ok": true, "status": "ok", "ruleSet": "c754293364b5",
"rules": [{"id": "R-fit", "kind": "authoring", "state": "checked", "reason": null, "counts": {"error": 0, "warning": 2, "info": 0}, "codes": ["bodyBottom"]},
{"id": "C-audio", "kind": "checker", "state": "excused", "reason": "noAudio", "counts": {"error": 0, "warning": 0, "info": 0}, "codes": []}],
"summary": {"checked": 24, "excused": 6, "skipped": 0, "failed": 0, "total": 30}}reason is null for checked and failed. codes lists the codes seen in this run. ruleSet changes only when the list of rules or their codes changes. If a rule ends in none of the states, or a code turns up in an excused or skipped rule, the check is "status": "incomplete" (exit code 3, with unset and problems): it did not look at everything, so it is not a pass either. Scripts should treat exit codes 2 and 3 and these two statuses as a failure; kit/core/check-result.mjs (parseCheck) does this. The text output ends with one line: quality check items: 24 done, 5 not applicable, 0 not run, 0 failed (of 29).
| Field | Meaning |
|---|---|
slide |
slide number, from 1; null for the whole file |
id |
the slide's id, or null (a slide without id, or the whole file) |
key |
the slide id (without an id, the legacy name made from the heading) |
title |
the heading text of the slide (h2 / h1, without tags) |
step |
the step the result is about: "0", "1", … or "concl"; null when it is about the whole slide |
sev |
error, warn or info |
code |
the kind of result (stable; the list is kit/check-messages.mjs) |
rule |
the id of the standard in the authoring guide (R-title, R-fit, …), or null |
data |
the values of the result (e.g. {"px": 583, "lim": 565, "concl": true} for a body overflow; with a theme whose metrics differ from the defaults also conclTop, line, and lim for bodyRight), used by fix requests to give the amount to cut |
msg |
the whole finding in lang: where, what and how to fix |
| Quality check | Severity |
|---|---|
build warnings; a script ## that matches no slide, a non-canonical step number ([01]), an invalid {#id} |
warn; error |
slide id not matching ^[A-Za-z][A-Za-z0-9_-]{0,63}$ (slide id: …); two slides with the same slide id (slide key: …); a slide id equal to another id or \htmlId{…} in the file (slide id: …) |
error |
the heading text of a ## heading {#id} differs from that slide's heading (the id wins) |
info |
a slide named by a legacy rule: a hand-written data-key, or s<n> (no id and no heading) — slide key: legacy |
warn |
source outside the 1.0 vocabulary (format spec §8.0): the colour classes blue, red, gray (use term, emph, muted), data-steps / data-anim (steps and motion come from data-step, data-at, draw and parts), <html data-mode="lecture"> (the participant's “Show later steps faintly”) — legacyColorClass, legacyStepAttr, legacyLectureMode |
warn |
a link to a slide (#<id>, #<id>:<stepKey>, #N) whose slide does not exist, whose step is out of range, or :concl on a slide without a conclusion; a link #N or to a slide without an id; a relative link to a file that does not exist (contract §9) |
error; warn; warn |
a part's data does not match its declared shape (static shape), or the part throws while drawing (compData: which part, what differs (path, expected, got), its shape and an example; standard R-components). The step count of a slide also comes from its data-step elements and .concl, so a failing part does not turn the slide's script into orphans |
error |
a part reports a problem it can see while drawing with ctx.report(code, message) (format spec §8.4): layout is compLayout (R-fit), the other non-error codes (range, size, theme) are compReport (R-components), with the slide and the part's tag. For range (values outside the range the part shows) the message says to set the part's range attributes (such as xr and yr) so that every value fits |
warn |
a prediction (m-predict) opens its answer at the same step as the vote count (predictAnswerWithCount, standard R-steps): the part shows the count bars and the −1/+1 controls at the part's step 1, and its answer (✓, frame, note) at answer-step, so an answer-step of 1 or less shows the answer before the class counts. The value is read as the part reads it (`Math.max(1, Math.round(+value) |
|
a prediction (m-predict) never shows its answer (predictAnswerNeverShown, standard R-steps): its steps attribute (read as +value) is smaller than the answer step above, and the player stops a part at its steps. No steps means the answer step. A steps that is not a number is left to the part error (compData). When both apply, only this one is reported. The message asks for steps to be answer-step or more. Same function, editor and fix requests as above |
warn |
| console errors (the message only: stack lines and file paths, temp folders and local-server URLs are removed) | error |
| text visible at step 0 | info |
| title > 26 full-width units (Japanese) / > 60 characters (English) | error / warn |
| title ends with a colon | error |
layout-tate: the vertical title does not fit its column |
error |
conclusion > 35 units (Japanese) / > 70 characters (English); conclusion overflows its box (also the vertical column of layout-tate) |
error / warn; error |
body below 565px (680px with noconcl) or right of 1236px; with layout-tate: below 680px, right of 1162px (over the heading column), left of 124px (over the conclusion column; 44px without one). These are the defaults: the limits come from the theme's metrics (Themes) |
error |
the theme's rendered boxes differ from its metrics by more than 1px, or a theme without metrics (or the slides' own <style>) moves the body, conclusion line or vertical columns (themeMetricsDrift, once per file: each field with the declared and rendered value and whether the theme's or the slides' CSS moved it); unusable metrics values (themeMetricsInvalid, once per file); the bundled fonts did not load, so the boxes were not measured (metricsFontLoad, once per file; a fallback font is never measured) |
warn |
body text < 27px, table/plot text < 24px, SVG text < 24px (skipped on slides whose heading contains 文献; ruby readings in rt are not counted; text inside an element with data-annot, a deliberately small annotation such as m-kanbun's reading-order numbers, is not counted: contract §10) |
error |
text cut off by a box with overflow other than visible (textClipped); SVG text cut off by its viewport (viewBox) or going off the slide (svgTextOut); SVG text overflowing the <rect> around it (svgTextBox); text outside .body going off the slide or overlapping the heading, conclusion line or page number (outsideBody). Text inside an element with data-clip is not checked by these (contract §10); on a slide with bodyBottom, text in .body going off the slide is not reported again |
warn |
the <svg> directly inside a part element (m-* whose display is not inline) sticks out of the element's box by more than 2px (partSvgOut: an <svg> without width and height is as wide as its parent and as tall as its viewBox's aspect ratio makes it; give the <svg> a width and height, or width:100%;height:100%, in the part's code). Parts inside data-clip are not checked |
warn |
content of a column of a side-by-side layout (.cols) sticks out of the column by more than 2px and may cover the next column (colOverflow: text, a KaTeX formula's visual box, img, svg, video, canvas, table; columns have min-width:0, so a long formula that cannot wrap is drawn over the next column). Fix it by shortening the formula or words, putting a long formula on its own line outside the columns, or using fewer columns. Columns with overflow other than visible, content inside parts and content inside data-clip are not checked |
warn |
on any slide (cover, section divider, layout-tate, absolutely positioned layouts): on a slide without .body, text going off the 1280×720 slide (textOffSlide; with .body this is outsideBody); a text box overlapping another text box or the slide's decorative band, such as the band at the top of the cover (textOverlap: line rectangles of the two boxes intersect by more than 2px in both directions; a KaTeX formula counts as one box, its visual box; a parent and its child, text inside the same part, and SVG text are not compared; on a slide with a body-position error, body text against the heading or conclusion line is not reported again). On a cover or section divider the finding names the allowed children and where a subtitle goes. Text inside data-clip, hidden text, KaTeX's MathML and .sr-only are not checked |
warn |
a word in a table cell (td, th) breaks across lines (cellWordBreak): a cell with Japanese or Chinese characters and at most 6 characters (spaces not counted) rendered on 2 or more lines, or a break inside a word without Japanese or Chinese characters (words from Intl.Segmenter; browsers break Latin words only at spaces or hyphens unless overflow-wrap or word-break allows more). Long Japanese cells that wrap are not reported. Fix it with fewer columns, a shorter word or a wider column |
warn |
| です・ます in the body (Japanese) | error |
| unrendered math or KaTeX errors | error |
| mixed punctuation 、。 vs ,. across the file (Japanese) | warn |
| a step without a script | warn |
template leftovers from the editor's slide list (kit/core/template-text.mjs): a script line that still starts with the placeholder mark ✎ (narrPlaceholder), or slide text still equal to a template default such as “New slide heading” or “First point” (templateText). TTS would read the placeholder and it would show in the captions and the readable layer, so TTS (tools/narration-json.mjs, tts/synth.py), --portable / --play-only and the editor's TTS and exports list them first |
warn |
stale audio: a step's audio was made from another script (inputHash differs or is null; without inputHash, the TTS cache record audio/seg_<digest>.json is compared) — audioStale |
warn |
| script that reads a formula (each turn by the rules of its language, see below; a Japanese sentence that only names things in Latin letters, such as “Markdown と HTML”, is not a formula) | warn |
| turn > 200 characters (Japanese) / > 60 words (other languages) | info |
the script language differs from the slide language (narrLang) |
info |
contrast of --fg --term --emph --title --accent2 vs --bg < 4.5:1; --muted < 3:1 |
error; warn |
colours outside the theme's vocabulary in the source (format spec §8.4, R-colors), in <style> values, style attributes and the colour attributes of SVG and HTML (fill, stroke, stop-color, flood-color, lighting-color, color, bgcolor; not <script>): colours written directly (hex, rgb() hsl() hwb() lab() lch() oklab() oklch() color(), colour names in colour properties, a literal fallback in var(--x, …)), and colours derived by changing the hue with relative colour syntax: in oklch lch hsl hwb a hue channel other than h itself (calc(h + 30), a number), in rgb and color() any channel other than its own name, in lab oklab a or b changed. Allowed: var(--…) of any role (--lit and the object colours --obj-* too), a literal fallback in var(--obj-…, …) (format spec §8.4 lets an object colour fall back to a literal colour of that name; whether it matches the name is not checked), color-mix() of roles and --bg, and relative colours that keep the hue and change only lightness, chroma or alpha (as default derives --title) — colorOutside, one per kind with the values (kit/core/color-vocab.mjs); information only, so it is not part of fix requests |
info |
on each slide, text of a heading or the body against the background behind it (computed colours; not over images or gradients, not faint text) < 4.5:1, the lowest one per slide — textContrast |
warn |
the file chooses a font of @egatari/fonts-extra (its CSS or its own theme) and that package is not installed next to the npm package egatari, so the font is not embedded — fontsExtraMissing, with the install command |
error |
slide text in a font that is not embedded in the file (the first family of its computed font-family is neither embedded nor generic), so it looks different on each device — fontNotEmbedded, once per file with the names |
warn |
section kind lines in a one-file article (spec §9C.1A): unknown kind (articleSectionKindValue), extra JSON member (articleSectionKindMember), not directly before a level-2 section (articleSectionKindPosition), kinds out of order (articleSectionKindOrder), or used in a chapter file or a file whose kind is not chapter (articleSectionKindContext) |
error |
chapter-kind sections linked to no slide (articleSectionUnlinked); preface, appendix and afterword sections are exempt |
warn |
visible characters of the slides, script or book that no embedded font has (such as ∎, which @fontsource lacks), so they show in the device's font — fontNotCovered, once per file with the characters by place (also node tools/font-coverage.mjs <built HTML>) |
info |
a chapter divider (class="slide sec") with an <h2> and no <h1> (the title of a divider is <h1>; an <h2> is shown the same way) — secHeading |
warn |
a caution or warning box with no text besides its label — cautionEmpty |
error |
a handwritten label at the start of a caution or warning box (remove it; the build supplies the label) — cautionLabel |
warn |
a kicker (.kicker) longer than 24 full-width units (full-width 1, ASCII 0.5), or 40 characters in Latin script — kickerLong |
warn |
more than one kicker on a slide, or a kicker not immediately before the heading — kickerPlace |
warn |
a kicker on a cover, chapter divider (sec) or vertical slide (layout-tate) — kickerSlide |
info |
| part drawing depends on call order | error |
| emphasis target not found; list of emphasis per step | warn; info |
morph: source slide missing, no shared data-id, duplicate ids; pairs |
warn; info |
<img> without alt; SVG figure without aria-label/<title>; part without a name |
warn; warn; info |
body balance (balance, R-balance): on the final step the body (.body) is rasterised; the pixels that differ from the slide background (more than 24/255 in any channel) are the content. Reported only when the body has a visual (an m-* part, an svg outside parts and KaTeX, img, table or .katex-display) and the empty band starts right below the lowest visual (at most 20% of the body height of other content, such as a short caption, between the visual's drawn bottom edge and the band): the figure could be taller. Text-only slides are never reported, since a consistent top-aligned start is the rule. The condition on the content: its centre of mass (each pixel weighs the same) is more than 10% of the body height above the body's optical centre (45% from the top) and the empty band below the content's bounding box is more than 25% of the body height larger than the band above it (rows and columns with fewer than 2 content pixels do not count for the box). On layout-tate the same along x (also only with a visual, the band left of the leftmost visual): centre of mass more than 10% right of the middle and the left band more than 25% larger than the right. Even margins all round score about 0. The data also has the visual (count and drawn edges), the horizontal offset (two-column layouts) and the one-sided band with its side; the message gives the numbers only. The conclusion line is outside the body and not measured; cover, section divider and static slides are skipped. Never in fix requests. Only in kit/check.mjs (the editor's quality check does not take screenshots). Thresholds: BALANCE in kit/core/fill-measure.mjs; node tools/fill-report.mjs <deck.html | folder …> prints the numbers per slide |
info |
a body of only short, equal points (cardsHint, R-purpose, backlog #189): the body (.body) holds exactly one unordered list (ul) of 3 or 4 li, and at most one short lead paragraph (p, up to 60 units) — nothing else: no ol, no nested list, no part (m-*), svg, img, canvas, video, table or display equation. Each item is at most 30 characters (Japanese decks count as the checker does elsewhere, full-width 1 and half-width 0.5; other languages count characters), and the longest is at most 2× the shortest. Skipped when any item has inline math (a rendered .katex, or TeX delimiters \( \) \[ \] $…$ left in the text) or reads as a sequence (it starts with まず・次に・そこで・最後に or first・next・then・finally, case-insensitive after leading punctuation, or contains →). At most 2 per file (cap in CH): when more slides qualify, the ones whose items are most even in length (smallest longest ÷ shortest) are kept, the earlier slide on a tie. Then the message is “Short, equal points may read better as cards (m-cards)”. One per slide. Cover, section divider, static and layout-tate slides are skipped. The author decides, so it is information only and never part of fix requests (the fix-request builder drops it, and by its name too). Thresholds: CH in layoutScan (kit/core/layout-scan.mjs); the editor's quality check shows it too (the same function) |
info |
figure geometry (R-geometry, backlog #201, kit/core/geometry-check.mjs). Parts mark what they draw with data-part, each with data-part-id (the id in the source): a box is the shape itself (<rect>, <path>, <ellipse>, <polygon>, <circle>; measured by its shape) with data-part="box"; an edge is <g data-part="edge" data-part-from data-part-to> whose ends name boxes or points (a leader line from a point to its text names the point's id) and whose lines (<line>, <path>; not the arrowheads) carry data-part-line; a label is <text data-part="label" data-part-of="box|edge|mark"> (data-part-halo when it has a halo, data-part-at="outside" when it sits outside its box; a foreignObject label is measured by its contents); a point is data-part="mark". Ends whose id starts with @ are not nodes. An edge is not checked against the label of a point it names as an end, nor against the box that holds that point. data-overlap="ok" on a marked element or an ancestor <g> (the same marker as textOverlap) leaves out the overlap findings it takes part in (geoEdgeThroughBox, geoLineOverLabel, geoLabelOverlap; not geoLabelOutsideBox); parts put it only on the parts they draw overlapping on purpose. On each slide's final step, in slide coordinates: a line passing inside a box that is neither of its ends (geoEdgeThroughBox); a line crossing a label's text, except the label of its own edge (geoLineOverLabel; info when the label has a halo); two labels' text overlapping, or a label over a point it does not belong to (geoLabelOverlap); a box's label going past the box's border (geoLabelOutsideBox, overflow per side; a <rect> box by its bounding box, a <circle>, <ellipse>, <polygon> or <path> box by its shape, so a label inside the bounding box but outside a circle is reported). Frames (handoff #46; in Studio the attribute names live in WITHIN_ATTRS): a shape with data-within="name" must stay inside the frame with data-frame="name". The value is one name matching [a-z][a-z0-9-]*; any other value (a list of names, capitals, spaces, empty) is not measured and is reported once per element, naming the element and the value, so that a typo does not silently turn the check off (geoBadMarkName, also on slides without data-part). Only declared shapes are checked, at the end of every step of the slide including the conclusion step (not just the last; not during transitions): the outline of the shape (all visible shapes and text inside it, when it is a <g>; text by the same text bands; an HTML element by its bounding box) against the frame's rendered shape (isPointInFill; a <g> or HTML frame uses its bounding box), looking for frames of that name in the same figure first and then on the same slide, counting the shape's half stroke and allowing the frame's half stroke + 2px. With several frames of one name in the figure, the one that fits best is used. The warning names the shape's id, the step where it sticks out most, by how many px, and the other steps where it is outside (geoOutsideFrame). Clipped strokes (handoff #52; no mark needed): in every inline SVG (author figures and part figures), each shape with a visible stroke (<rect>, <circle>, <ellipse>, <line>, <polyline>, <polygon>, <path>; text is svgTextOut's job) is measured at the end of every step, in the same pass as frames, by its painted box (the bounding box through its transforms, grown by half the stroke width; an open line grows only across its length unless its caps are round or square) against the visible area of the SVGs that clip it (the outer <svg>'s box, a nested <svg>'s x, y, width and height; an SVG with overflow visible, by attribute or CSS, does not clip and is skipped). It is reported when more than 1px is cut off on some side and at least 90% of the painted box is inside (per-axis overlap shares multiplied; the thickness of a horizontal or vertical line is left out), so a decoration that is mostly outside on purpose is not. Not measured: shapes without a stroke (fill-only backgrounds often bleed on purpose), hidden shapes, defs and the like, KaTeX, shapes with clip-path or mask (or inside such a group), anything inside the clip marker (data-clip), and shapes with data-overlap="ok" on themselves or an ancestor <g>. The warning names the shape (its data-part-id or id, else its kind and position on the slide, such as rect#3), the cut per edge, the step where it is cut most and the other steps (geoClippedStroke); when the shape itself crosses the edge, the fix is to move or shrink the shape rather than half the stroke width. The text extent is the advance width horizontally and a fixed band above and below the baseline vertically, per font (kit/core/text-band.mjs), so the result does not depend on the font's line metrics. Half the line width + 2px is tolerated: a line ending on its box's border is a correct figure. Marked labels are left to this check (not textOverlap or svgTextBox). Vertical slides (layout-tate) are not measured (a limitation of Studio's check, not a rule of the format): when every content slide is vertical the rule is skipped (tate); in a file that mixes both, the number of vertical slides with marks is reported (geoTateSlides). Parts without marks are not checked (except for clipped strokes); a file without parts, marks or inline SVGs excuses the rule (noParts) |
warn; info |
| timeline total and per slide | info |
In the editor. The editor's quality check reports the same codes, severities and messages for every row above (the layout rows run the same kit/core/layout-scan.mjs, figure geometry the same kit/core/geometry-check.mjs, unrendered math the same kit/core/raw-math.mjs, and the source and script rows the same functions through kit/core/check-source.mjs), and its fix request includes their errors and warnings. Only in kit/check.mjs: part drawing that depends on call order (compOrder) and body balance (balance), which take screenshots; a relative link to a missing file (linkFileMissing) and fontsExtraMissing, which need the files on disk; and the info lists (text visible at step 0, palette, emphasis per step, timeline, fontNotCovered, extensionVersion). Attachments are checked in the editor's Attachments panel and on export, and the book in its Book panel, with the same rules. A part that cannot be loaded (component-requires-missing, component-not-in-catalogue) stops the build in both, with the same message. The list, with a reason for each, is CLI_ONLY in kit/core/check-parity.mjs; tools/test-check-parity.mjs fails when the command reports a code the editor lacks that is not on it. The kicker checks use the authoring source through the shared kit/core/kicker.mjs in both paths.
The slides and the script may be in different languages (for example Japanese slides with English script for subtitles). The script language is "lang" in voice.json (as for the TTS), otherwise the language of the text when nearly all turns are in another writing system than the file (no Japanese characters in a Japanese file, or Japanese in most turns of another file), otherwise the slides' <html lang>. The script checks then take each turn by its own language: a turn with Japanese characters by the Japanese rules, an English sentence by the English rules (only \ ^ _ and dense operators count as a formula).
node kit/build.mjs <deck.html | working folder> [-o out.html] [--theme name] [--dev] [--embed-audio] [--portable] [--play-only] [--scorm] (or npm run build -- …). Given a folder, it builds the deck.html inside it (without one it says what it expected and exits with 1).
| Option | Meaning |
|---|---|
-o file |
output (default <working folder>/out/<name>.html) |
--theme name |
theme (see Themes) |
--dev |
add data-src for the editor and skip glyph subsetting (used by the dev server) |
--embed-audio |
embed audio as AAC 64 kbps mono (needs ffmpeg; otherwise WAV, with a warning). Without it, audio is referenced relative to the output |
--portable, --play-only, --scorm |
an Egatari file that also carries the editable source, its play-only copy, or that copy packaged for an LMS; see Egatari file |
The summary line shows slides, math, parts, font files, script steps, audio steps, theme and size. Fonts: of the @fontsource chunks that hold the slides' characters, each is cut down to the characters used with harfbuzz (WebAssembly, harfbuzzjs, pinned in package.json), re-encoded as woff2 (wawoff2), and declared with a unicode-range of exactly the kept characters. No Python or TTF files are needed, and the editor's export gives the same bytes. The same characters, chunks and tool versions give the same bytes on every OS (tools/test-font-subset.mjs). Source Sans 3, Source Serif 4 and Source Code Pro, which have a Reserved Font Name, are not subset. EGATARI_FONT_SUBSET=0 embeds the chunks whole. --dev and the dev server do not subset. Compressed audio is cached in $TMPDIR/motion-slides-audio/. Glyphs embedded: the slide text after decoding HTML entities and \u escapes, strings in <script type="application/json"> and the script, string literals of the parts used (without CJK in non-Japanese slides), the characters a part declares it draws itself (glyphs in the parts library record, in its egatariParts.define meta or as static glyphs; a string, or {ja: …, en: …} of which the slides' language is used), printable ASCII (digits, / for page numbers), Appendix, and for Japanese slides 付録 and common Japanese punctuation. Local assets are embedded as described in Assets.
A file-local part (<deck>/components/<name>/index.js) is read only if its real path is inside the working folder, a library part only inside vendor/components/; a working-folder one that resolves outside is refused with a warning and not replaced by the registry one. Inside the working folder, the output (out/…) and egatari.json are never written through a symbolic link (the file or a folder on the way); a link there makes the build fail without writing.
The build counts while it expands and stops with build-too-large as soon as a limit is exceeded: the source (32 Mi characters), includes and embeds together (/*INCLUDE*/, {{JSON}}, {{FIG}}, data: URIs, <link rel="stylesheet">, <script src>, @import: 10 000), the size after preprocessing (64 Mi characters) and after embedding and math (256 Mi), the tags before each parse (500 000) and formulas (20 000). Every file read counts toward the include count — theme files, logos and parent themes, parts, script, audio, fonts and the runtime too — and toward one total of what was read (readChars: 256 Mi; text in bytes, base64 in characters), charged from the file size before reading, so an oversized file is refused unread; the size is an estimate, and the bytes actually read are charged too (a file that grew is refused). Sizes are always bytes (text read through an adapter that does not report bytes is charged its UTF-8 length, never its UTF-16 length). Only regular files are read: a FIFO, device or socket is refused with build-not-a-file. The whole output is checked against 256 Mi before it is joined. Audio is compressed from the bytes charged for it: the build reads the .wav once, up to its charged size, and hands ffmpeg a private copy of those bytes instead of the original path. The Egatari file export shares its build's budget for everything it reads (script, copied sources, voice.json, egatari.json, audio before compression) and checks the whole file before it builds each part: archive chunks from their projected size, the index from a lower bound before it is serialized (and against the reader's 4 MiB indexBytes), and the readable layer counted in escaped characters while it is built; base64 is encoded only after every check passed. Real files are far below (examples/tmlr2026-calibration: 11 KB source, 27 formulas, 3 400 tags). build(env, src, {limits: {...}}) changes them (BUILD_LIMITS in kit/core/build-core.mjs). In the editor app the build runs in a worker that is stopped after 60 s, and reads only the files the build references, at most 8 at a time, each up to its listed size (reserved before the read starts; a file that grew since the listing is refused). Outside the build, the dev server, the editor's own requests and npm run ids read deck.html (32 MiB), narration.md (16 MiB) and comments.json (4 MiB) with fixed limits (READ_LIMITS in kit/core/bounded-read-core.mjs), and npm run portable -- unpack refuses an input over the format's 100 MiB before reading it. All of these go through one bounded reader (kit/bounded-read.mjs on Node, app/bounded-read.js in the browser); tools/test-raw-reads.mjs fails on a raw read elsewhere.
node kit/build.mjs <deck.html> --portable writes <working folder>/<title>.ega.html (the title as the editor names its export: metadata.title, otherwise the <title> of deck.html, made safe for every OS; without a title, <deck name>.ega.html) and prints its full path: one HTML file that plays like the normal build and also carries the slides' and script's source, so it can be unpacked into a folder (or reopened by an editor) without the original folder. It follows Egatari, the open single-file format (draft 1.0); the file name extension, block ids and media type come from that spec.
- What goes in: every file the build reads from the working folder (
deck.html,narration.md,macros.tex,timeline.json, data, figures, images, styles, the working folder's own parts and themes),voice.jsonwith local paths reduced to voice names, and the audio listed inaudio/manifest.jsonfor steps that exist in the script (compressed to AAC as with--embed-audio; WAV with a warning if ffmpeg is missing). Each audio clip is stored once and the runtime plays it from there. - What stays out:
comments.json, hidden files and folders (.cache/,.git/,.env, …),out/,video/,bundle/,node_modules/, backups,*.local.json, credentials, unused audio and the TTS cache files. A file the build read but that is excluded is reported. Parts and themes from this repository are referenced by name, version and SHA-256 instead of being copied (a theme from your theme folders,EGATARI_THEMESor~/.egatari/themes, is copied in as the file'sthemes/<name>/); a registry name is a single identifier (^[a-z][a-z0-9-]{0,63}$), and the reader refuses a file whose registry names are anything else (a path,.., uppercase). - Lesson id: the first export creates
egatari.jsonin the working folder with a randomdocId; keep it with the file so later exports keep the same id. Its optionalmetadataobject may holdlicense(SPDX id or URL),copyright,attribution,creators,edits,description,accessibility,curriculum,completion,derivedFrom,authorshipandaudience;edits(format spec §3.6.1) lists, oldest first, people who changed someone else's file:[{"by": "○○高校 情報科", "note": "2 章のデータを地域のものに差し替え"}], wherebyis the name they chose to show (absent when they chose none) andnotesays what they changed; there are no dates. An entry that is not an object with textbyandnoteonly is dropped with a warning.license,copyright,attribution,creatorsandeditsare also copied to the runtime metadata (deck-meta, also in a working-folder build), so a play-only copy keeps them and the player's key list (?) shows them under File info (title, created by, edited by, copyright, license, attribution). Each entry ofeditsis a line after the creators: “Edited by: ○○高校 情報科 (2 章のデータを地域のものに差し替え)”, or “Edited from the original file” for an entry without a name. Title and language come from<title>and<html lang>. - Player and producer (spec §4.1, §7.1): the index and
deck-metacarryplayer— the bundled player,{"name": "egatari-player", "version": …, "title": "Egatari Player"}(titleis the name shown to people,namethe stable identifier; the version iskit/player.json's, with+dev.<commit>added when the player files differ from the release recorded inkit/player.lock.json;npm run player:check) — andgenerator, the software that wrote the file ({"name": "egatari-studio", "version": <Studio's version>, "title": "Egatari Studio"}).contractsis{"source": 1}. Saving without rebuilding (tier A) keepsplayerandgeneratorbyte for byte; a rebuild writes this Studio's and warns when the file carried another player (playerChange); the editor then asks before saving (see editor, “Saving with a rebuild”). - File policy (spec §4.2): a
<meta http-equiv="Content-Security-Policy">right after<meta charset>, before every script, style and link: the baseline, which connects nowhere (connect-src 'none'). A play-only copy with Live adds only the Live's endpoint toconnect-src, in place; destinations ofembed(copied intodeck-extensionsin every file) go intoframe-src. Readers report a file whose policy is missing, misplaced or differs (compared as parsed directives) as not conforming; it still plays. - Slide ids (spec §8.1): every slide in the file has an id and every script heading
{#id}. Slides and headings without one (slides an AI just wrote, older keys by heading text, hand-writtendata-keyors<n>) get one at export, written back to the working folder with the keys inaudio/manifest.json,timeline.json,comments.jsonandegatari.json(backups in.cache/edits/); the build and the quality checker still accept them. - Script readable without JavaScript: the file also contains the display text of every step as ordinary HTML (hidden while the file runs), for archiving, search and accessibility.
- Extension lines (
@x-<name>-<field> value) are collected per step into the file's index. - Attachments (format §3.8; draft, experimental, spec §3.8 draft): files for readers rather than for rendering, in
attachments/(subfolders allowed): the original source (TeX, Word), the typeset PDF, code, data, supplements. Their roles, titles and descriptions are inegatari.json, in the same shape as the file'sindex.attachments:"attachments": [{"path": "attachments/paper.pdf", "role": "pdf", "title": "Paper (PDF)", "description": "The journal version."}],roleone ofsource,pdf,code,data,supplement,titlerequired (a short name for the download list, one line of at most 120 characters, counted as Unicode code points as in the schema),descriptionoptional (one or two plain-text sentences, one line of at most 300 characters; shown under the title in the download list; other members are kept). Regular files underattachments/are packed (symbolic links are not followed; hidden files, backups and credentials stay out as above); only files with a valid role and a valid title are listed inindex.attachments, the others are packed with a warning; an invalid description is dropped with a warning and the entry is still listed.- Types per role (spec §3.8,
kit/core/attach-content.mjs):pdftakes PDF;dataCSV, TSV, JSON, text and xlsx;codeprogram source (.py,.r,.jl,.c,.mjs,.ts,.sh, …), notebooks (.ipynb) and environment definitions (requirements.txt,pyproject.toml,uv.lock,environment.yml,Dockerfile, …);sourceTeX, Markdown, text (e.g. BibTeX) and docx;supplementPNG, JPEG, WebP, PDF and text. Never attached: executables; in any role, the extensions that common operating systems run or open as scripts, exactly the spec's list (.js,.jse,.vbs,.vbe,.wsf,.wsh,.hta,.bat,.cmd,.com,.scr,.ps1,.command,.app,.jar,.reg,.lnk; attach JavaScript source as.mjs,.cjsor.ts); WebAssembly, macro-enabled Office files and legacy Office files (.xlsm,.docm,.doc,.xls,.ppt, RTF), HTML, SVG, another.ega.html, archives and containers (ZIP, TAR, 7z, …), audio and video, and any other type. The type comes from the extension and is checked against the content (magic bytes and structure), so a renamed executable, an HTML page named.txtor a file of two types (a PDF with a ZIP appended, an image with a PDF header) is refused. Each attachment's blob carries the media type of its type (application/pdf,text/csv,text/plainfor source code, …). - Content conditions, checked without running anything and within bounds (at most 64 MiB decompressed is read; ZIP entries and declared sizes are limited, entries that overlap or decompress past their declared size are refused): PDFs without JavaScript, embedded files or XFA; automatic actions (
/OpenAction,/AA) only a destination or aGoToinside the document (as LaTeX's hyperref writes); link annotations onlyGoToorURI; no other action (Launch,SubmitForm,ImportData,GoToR,GoToE,Rendition,Named, …), also inside compressed object streams; an encrypted PDF only if it opens with the empty user password (RC4, AES-128, AES-256; it is then decrypted and checked), otherwise refused. xlsx and docx (read as ZIP in memory, never extracted): no macros (vbaProject.bin, macro-enabled types), ActiveX, embedded objects, external links or other external relationships, data connections or web queries, DDE, functions that fetch external data (WEBSERVICE,RTD,IMAGE,STOCKHISTORY,CALL, …), field codes that run or fetch (DDEAUTO,INCLUDETEXT,INCLUDEPICTURE,LINK, …, or a field name built from a nested field) and remote templates. Text must be text (no NUL bytes except UTF-16 with a BOM); JSON and notebooks must parse. - What happens: the build (
--portable) leaves out an attachment of a type that must not be attached or that fails a condition, with a warning naming the rule; values in CSV, TSV or xlsx that a spreadsheet may read as formulas (starting with=,+,-,@or a tab; numbers excepted) and text that looks like a credential or a device-specific path are packed with a warning. The quality checker reports what the spec forbids (MUST NOT: forbidden types, a type the role does not take, audio and video, JavaScript in a PDF, macros, files of two types) as errors and the rest (SHOULD: the other conditions, content that does not match or cannot be checked; formula injection, credentials) as warnings. - Limits: 10 MiB per file, 20 MiB together, 100 files (base64 makes the Egatari file about 4/3 of that); files over a limit are left out with a warning (
ATTACH_LIMITSinkit/core/attachments.mjs). Attachments are not code (they do not make the file Extended), are not added torequires(a reader may ignore them) and are read within the build's byte budget. egatari.jsonin the Egatari file lists exactlyindex.attachments(spec §3.3): entries that are not listed for readers are left out of the copy in the file, with a warning; the working folder'segatari.jsonis not changed. Unpacking writesindex.attachmentsintoegatari.json(also for a file that has none), and packing a folder takes the list fromegatari.json, so unpack → pack keeps the records. A file whoseegatari.jsonlists other attachments than its index is refused (attachments-mismatch).- The player of an Egatari file lists the attachments under ? (title, description, file name, role, size) and with a paperclip button in the toolbar, download only: it offers only entries with a valid title, whose extension the role takes and whose blob has the matching media type (an
.htmlfile, a.jsfile or a CSV listed aspdfis not offered even if the index lists it), saves each under the file name of its path (a name the operating system would not accept is not offered rather than renamed), notes on code attachments “Run code only if you trust its source”, checks the index hash and each attachment's size and SHA-256, checks the first bytes against the type (a.txtthat starts as HTML is not saved), and saves the bytes asapplication/octet-streamthrough a download link, so nothing is opened or run, in the page or in a new tab. Play-only copies (--play-only) and the normal build carry no attachments (the format removes the archive layer). The quality checker also warns about missing roles or titles, unknown roles, listed files that do not exist, names that are not allowed (outsideattachments/,.., reserved names, case collisions, hidden files, links) and files over the limits
- Types per role (spec §3.8,
- Exported copy (
exportedFrom, spec §3.1): an export from a working folder (--portable,npm run portable -- pack, the editor's Egatari file export) records{"kind": "folder", "sourceSha256": …}in the index, the source hash at export. It holds no time, path or user name, so exports stay byte-reproducible and packing an unpacked file gives the same file. Saving the Egatari file in the editor keeps the marker unchanged (also when saving without rebuilding), so a source hash that differs from it shows the copy was edited after export; saving it with Save as… as a new file (a newdocId) drops the marker, and exporting from the folder again replaces it. A file whose source of truth is an Egatari file (saved by the editor without a folder, pasted or opened fromdeck.htmlalone) has none, and play-only files have no index. Unpacking makes the new folder the master:egatari.jsondoes not carry the marker, and its next export writes a fresh one. - Audio records: each step's audio keeps the hash of the script it was made from. When the TTS cache shows that the script changed after the audio was made, that hash is written as
null(unknown, so the step counts as stale); unpacking and packing keep thenull. The runtime's audio entries also carry the audio media type, so a player does not need to guess it. - Warns above 30 MiB (split long files into chapters).
| Option | Meaning |
|---|---|
--portable |
write the Egatari file (default <working folder>/<title>.ega.html, at the top of the folder; -o sets the path) |
--play-only |
write a play-only copy (default <working folder>/<title>.play.ega.html): no source, only the runtime and its audio. Use it for participants when the source or extension data should not be handed out |
--scorm |
write a SCORM 1.2 package for an LMS (default <working folder>/<title>.scorm.zip; SCORM 1.2 binding): imsmanifest.xml (one SCO, identifier egatari-<docId>, title from the file's title) and the play-only copy as index.html, byte for byte what --play-only writes. Fixed entry order and times, stored without compression, so the same file gives the same bytes. No adlcp:masteryscore: the player reports completed by metadata.completion and never sends a score. Refused when deck-meta.tracking has no scorm12 or the resume data could exceed 4096 characters (about 8,000 steps). See In an LMS with progress (SCORM) |
--without-live-results |
with --portable: leave out attachments that hold live results (participants' questions and answers). Without it, an Egatari file that contains them prints a warning. Play-only copies never contain them (Live) |
--update-themes |
rebuild with the current version of bundled themes that egatari.json pins to an earlier version (themes, below), and rewrite those pins; prints the colors that change |
npm run portable -- unpack <file> <dir> [--force] extracts the source and audio into <dir> (and writes audio/manifest.json from the audio records, so the folder builds and packs again). It reads the file as text and never runs its scripts; it checks the index and every hash, the size limits and the path rules of the spec, refuses to write outside <dir> or through symbolic links, and refuses a non-empty <dir> unless --force. npm run portable -- pack <dir> [-o file] [--play-only] [--without-live-results] is build --portable on that folder: packing an unpacked folder gives the same file again. npm run portable -- attach <dir> <results.json> [--en] adds live results downloaded from the Live server to the working folder as a data attachment (attachments/live-<room>-<date>.json, title “ライブの結果(、)”, or in English with --en); it refuses anything that is not results of the vendored schema, files over 10 MiB, files that fail the §3.8 content checks and results already attached, and warns (but adds) when the live session's id differs from extensions.live.room in egatari.json. npm run portable -- compare <file> <dir> takes a copy exported from a working folder and that folder (same docId in egatari.json) and says, by source hash, which was edited after the export: same, copy (unpack the copy to bring the edits back), folder (export again) or both (choose which to keep; nothing is merged). It writes nothing; a file without exportedFrom or a folder of another file is refused.
npx egatari ids-of <file.ega.html> […] is for organisations that manage file versions. It prints three things per file: sourceSha256 identifies the version of the source: it covers the source files and leaves out the audio and the built parts (format §3.4), so re-synthesizing audio or rebuilding does not change it; the SHA-256 of the whole file identifies the file itself, for checking at distribution or at an LMS upload (any byte change changes it); docId identifies the file across versions. Who released a file is a matter for signatures (format §10), which this version does not implement; neither hash says who made the file.
Reading an Egatari file (unpack and the editor app) also refuses an audio/manifest.json inside the archive (it is always made from the audio records) and a settings file whose docId differs from the index, and recomputes the source hash from the files: when it differs from the index or from the runtime metadata, the reader warns that the built slides and their source disagree. A file of a newer major version, or one that requires a feature the reader does not implement, can only have its source extracted (readPortable(text, {extract: true}) and the editor's Export working folder…), and only when the index and the blobs check out with the 1.x rules; it is never edited or re-exported.
kit/core/tier-a.mjs (tierA(original, files, {identity?, fonts?}), no Node or browser dependency, runs nothing) saves an edit of script, audio or timing overrides into an Egatari file without rebuilding it, as the format's tier A (§7.2). files is the edited working folder (the unpacked shape, with audio/manifest.json). It rewrites only: the changed entries of deck-narration, deck-marks, deck-timing and deck-audio (other entries keep their bytes, also their formatting); the changed <div data-step-key> of the readable layer; sourceSha256 in deck-meta (and docId with identity); the changed members of the index (files, blobs, changed audio records, requires, sourceSha256, the entries of extensions made from the extension lines that changed, and docId / metadata.derivedFrom with identity, which also removes exportedFrom) and its data-sha256; the blob blocks (new content appended, unreferenced blobs dropped); and, only when the changed script needs characters that the file's @font-face rules do not cover, a new <style id="…font-supplement-<n>"> with the @fontsource split files that cover them (fonts: {faces(key), load(file)}): <n> is one greater than the largest existing supplement number (from 0), the element follows the last style element with @font-face rules, and it has one @font-face per embedded face (family, weight, style) that lacks the characters (a file that embeds only weight 400 gets only 400; a family the file does not embed gets none, with a warning). Every other byte stays. Unknown members are kept at every level. Audio records of steps whose script changed are kept as they are (their inputHash no longer matches, so they are stale); when a step's script is removed altogether, its audio record and blob are removed too, with a warning. Script for a key that matches no slide is left out of the readable layer, with a warning. It returns {ok: true, html, index, deckMeta, changes, warnings} or {ok: false, code, reason} when the edit needs a rebuild (source-changed: a file other than narration.md, timeline.json or the settings file changed), when the built slides and the source disagree (source-mismatch), when timeline.json is not a JSON object (timeline), or when a region cannot be located (layout). Packing the unpacked result gives the same source files, audio records, runtime JSON blocks, readable layer and index; it differs in the fonts (a rebuild selects them again into deck-base and adds no supplement) and may order the blob blocks differently. tools/test-tier-a.mjs tests this with a region-aware diff (tools/tier-a-diff.mjs).
Attachments are archive entries, so adding, removing or renaming files under attachments/ and changing their roles and titles in egatari.json are tier A edits too: only the index (files, blobs, sourceSha256, attachments), the chunks and deck-meta.sourceSha256 change. It refuses (source-changed) when the slide source mentions the changed attachment's path (the build may have read it) and (attachments) when an added, changed or re-roled attachment breaks the limits, the name rules or the §3.8 types and conditions above; an attachment that was already in the file and did not change is kept as it is, with a warning if it does not meet them. When egatari.json lists attachments that are not in index.attachments (no role or title), the saved copy lists exactly index.attachments, and the result carries that text as config so that the editor writes it to its workspace too.
uv run --project tts python tts/synth.py <deckdir> [options]. Details: video.md.
| Option | Meaning |
|---|---|
--voices expert=a,novice=b |
voices (over voice.json) |
--ref-dir DIR |
reference voice folder (over IRODORI_REF_DIR; default tts/voices/, where the npm package downloads a missing default voice to the cache on first use; tts/voices.json) |
--engine irodori|voxcpm2 |
over voice.json engine and the file language |
--yomi FILE |
reading dictionary (over MOTION_YOMI; default tts/yomi.yaml). Japanese only |
--only key,… |
only these steps (slideKey:step) |
--dry-run |
no TTS: silence of estimated length (7.5 characters/s Japanese, 2.5 words/s English); separate cache |
--force |
ignore the audio cache |
--replace-recorded |
also replace recorded and imported audio (manifest kind recorded / imported, written by the editor app's Audio panel) with TTS; without it they are kept |
voice.json field |
Meaning |
|---|---|
expert, novice |
a name (<ref dir>/<name>.wav) or a path (contains / or ends in .wav; relative to the working folder). Defaults bob, alice. The reference voice is never packed into the Egatari file (.ega.html): keep it outside the working folder |
lang |
language (default: lang of the slides' HTML — the file you pass, <deckdir>/deck.html, or the only *.html in the folder — else ja) |
engine |
irodori (default for Japanese) or voxcpm2 (default otherwise) |
Writes audio/seg_<digest>.wav, audio/seg_<digest>.json and audio/manifest.json (steps removed from the script are dropped from the manifest; their wav files stay). Each manifest entry also carries kind: "tts" and inputHash, the hash of the step's script (format spec §5.4), so the editor app and the quality checker can tell when the script changed afterwards. Recorded and imported takes are kept (see --replace-recorded). The editor app can also record, import or regenerate one step at a time in the browser (editor); its post-processing uses the same numbers as tts/core.py. Warns if dry-run audio remains. When the server is not localhost, voice paths are not checked locally. Rebuild afterwards.
node render/render.mjs <built.html> --out <dir> [options] (opens the file with ?mode=video).
| Option | Meaning |
|---|---|
--out dir |
required |
--fps n |
default 30 |
--scale x |
default 1.5 (1920×1080) |
--only key,… |
only these slides or steps; the rest stay as they are. Each item is a slide id or a name made from the heading (all of that slide's steps) or slideKey:step (one step). An item that matches nothing is an error that lists the valid slide ids |
--full |
also full.mp4, and with two or more chapters chapter_NN.mp4 and chapters.json (needs all clips) |
--force |
ignore .render-cache.json |
--music file |
optional background music: one track under the whole video, quieter while the script is spoken, faded out at the end (video.md). Part of each clip's audio, so it is in the cache key |
--captions |
burn the script captions into the video (?captions=1); part of the cache key |
Outputs: clip_NNNN.mp4, clip_NNNN.png, timeline.out.json (source, fps, sampleRate, music, scale, width, height, duration, clipDuration, segments[] with index, clip, still, key, slideKey, stepKey, i, k, title, chapter, start, dur, anim, lead, audioDur, audioOffset, frames, clipDur, clipStart, start_ms, end_ms, transcript, text), .render-cache.json. Clips beyond the current number of steps are deleted.
| Command | Purpose |
|---|---|
npm run new -- <folder> [--lang en|ja] [--theme name] [--title "…"] |
new working folder (deck.html + narration.md, and egatari.json with "componentsCatalogue": "2") from a clean template; refuses a non-empty folder |
npm run ids -- <working folder | deck.html> [--dry-run] |
give every slide without an id a new id (s- + 6 random base32 characters), rewrite narration.md headings to ## heading {#id}, rename the keys in audio/manifest.json, timeline.json, comments.json and data-morph="…"; audio is not re-synthesized. Backups go to .cache/edits/, line endings are kept, a second run changes nothing. Refuses a file with duplicate keys, id collisions or invalid ids |
npm run ids-of -- <file.ega.html> […] [--json] (npx egatari ids-of) |
print the identity of Egatari files, one line each (tab-separated: docId, sourceSha256, SHA-256 of the whole file; --json: one JSON object per file with file, docId, sourceSha256, fileSha256). sourceSha256 is recomputed from the file's source, and a warning goes to stderr if it differs from the value written in the file. A play-only file has no source: sourceSha256 is - (null in JSON). A file that cannot be read or is not an Egatari file is an error on stderr and exit code 1; the other files are still printed |
npm run portable -- unpack <file> <dir> [--force], npm run portable -- pack <dir> [-o file] [--play-only] [--without-live-results], npm run portable -- attach <dir> <results.json>, npm run portable -- compare <file> <dir> |
Egatari file ↔ folder; see Egatari file |
npm run player:check [-- --strict], npm run player:bump -- patch|minor|major |
the bundled player (Egatari Player): compare its files (PLAYER_FILES in kit/core/player.mjs) with the release in kit/player.lock.json (information only; --strict fails when they differ, for the release candidate); bump writes the new version to kit/player.json and the lock and adds changes/player-<version>.md. See RELEASING.md |
npm run build:app |
build the editor app: the hosted editor in dist/ (for GitHub Pages; dist/index.html) and the Offline editor dist/editor.html. See editor.md |
node tools/test-app.mjs |
tests the editor app (OPFS folder, edit, script, comments, external changes, export, presenter) |
node tools/get-fonts.mjs |
download the BIZ UDPGothic and BIZ UDPMincho TTFs into fonts/ (enables glyph subsetting with uv) |
node tools/test-kokugo-example.mjs |
the kanbun of examples/kokugo-kanbun reads without warnings with the library's m-kanbun (no browser; the parts' own tests are in egatari/components) |
node tools/theme-metrics.mjs measure <theme> [--lang ja|en], node tools/theme-metrics.mjs check <theme> |
render a theme (a folder or a name, as for --theme) and print its metrics block measured from the rendered boxes, to paste into theme.json (whole pixels, each edge rounded outward to the more lenient limit by less than 1px; exits with 2 without measuring when the bundled fonts do not load); check compares the declaration (or the defaults) with the rendered boxes and exits with 1 when they differ |
node tools/test-theme-metrics.mjs [workdir] |
theme metrics: validation and inheritance, the theme hash, every bundled theme renders as declared (strict), the limits and themeMetricsDrift in the checker and the editor's quick check |
node tools/test-layout-tate.mjs [workdir] |
layout-tate slides in the default and kokugo themes: heading column, body, conclusion column and page number placed without overlap, seek determinism, quality-check standards, slide ids and readable layer unchanged |
node tools/test-check-colors.mjs [workdir] |
colours outside the theme's vocabulary (colorOutside): the rule for each kind of value, where the source is read, and the check on tools/fixtures/check-colors/ (var(--lit), var(--obj-red, red) and the other object colours with a literal fallback, color-mix() of roles and a hue-keeping relative colour allowed; hue-changing oklch rgb hsl lab and a literal fallback reported, as info and not in a fix request) |
node tools/test-check-cards-hint.mjs [workdir] |
the cards hint (cardsHint): fires on 3 or 4 short, equal points; stays quiet for 2 or 5 items, a long or unequal item, a nested list, ol, a part, static, vertical and cover slides; info only and absent from fix requests |
node tools/test-check-predict.mjs [workdir] |
the prediction warnings (predictAnswerWithCount, predictAnswerNeverShown): how answer-step is read (as m-predict reads it), the first fires on 1, -1 and 1.4 and stays quiet with no attribute, 0, 2, 3, abc and an empty value; the second fires when steps is below the answer step (and then replaces the first); the same findings from npm run check and the editor's path (sourceFindings); in the fix request with R-steps; the Japanese and English messages |
node tools/test-themes.mjs [workdir] [--shots <dir>] |
every bundled theme: a sample builds and passes the quality check; role-colour contrast, colour-vision simulation and the pen colours (see Themes); the look shapes in tokens.css match kit/core/theme-shapes.mjs; prints the numbers, and with --shots a contact sheet per theme |
node tools/test-fonts.mjs [workdir] |
fonts: only the chosen fonts are embedded (from theme.json fonts or named in CSS), Source Sans 3 italic in English slides and for Latin text in <em>/<i> of Japanese ones, and fontNotEmbedded for a font that is not in the file |
node tools/pdf.mjs <built.html> <out.pdf> |
PDF, one page per slide |
node tools/shot.mjs <built.html> <out.png> [i] [k] [mode] |
PNG of slide i (0-based), step k, final state |
npm run sheet -- <working folder | deck.html | built.html | .ega.html> [out.png] [--mode talk] [--cols 4] [--width 640] [--tiles] [--steps] |
contact sheet: one PNG with every slide at its final step (1-based number, and the key if short; default tile width 640 px; output <deck>/out/sheet.png); --tiles also writes each slide's PNG to <out>-tiles/. --steps instead lays out every step of each slide that has a figure or part, side by side, one row per slide (default tile width 320 px; output <deck>/out/steps.png) to check a figure's constraints step by step. Prints the path and the slide count |
npm run comment-shots -- <working folder | deck.html> [id …] [--all] |
for each open comment in comments.json (or the listed ids, or all with --all), PNGs of its step's final state with its pin (and ink strokes) drawn: <deck>/.cache/comment-shots/<id>.png (480×300 of the slide around the pin at 2×, at least the bounding box of its strokes plus 48 px, the whole slide without a pin), <id>-full.png and index.json. A comment whose step is gone is reported, not shot |
node tools/catalog.mjs |
regenerate vendor/components/CATALOG.md |
npm run components:update -- vX.Y.Z [--from <folder>] |
bring in a release of egatari/components into vendor/components/ and components.lock.json (checks sha256 against manifest.json; never replaces a version) |
npm run components:check |
vendor/components matches components.lock.json (no network) |
node tools/narration-json.mjs <narration.md> [--voice json] |
parsed script as JSON (used by synth.py) |
node tools/smoke.mjs <built.html> <outdir> |
timeline and a few screenshots |
node tools/test-components.mjs [name …] [--shots dir] |
build and test part demos |
node tools/test-tools.mjs <built.html> [outdir] |
overview, pens, laser pointer, print, presenter ink |
node tools/test-controls.mjs <built.html> [outdir] |
toolbar, help, presenter buttons |
node tools/test-autoplay.mjs <built.html> |
autoplay and its presenter-view button |
node tools/test-links.mjs [dir] |
links to slides: fragments at load, clicks in each mode, Back (button, keys, browser history), autoplay kept, embedding (position with cause: "link", linkRefused), presenter view, m-menu, quality checker errors |
node tools/test-dev-server.mjs [workdir] |
dev server on a copy of examples/minimal |
node tools/flake.mjs <built.html> <i> <k> <outdir> |
investigate a false "depends on call order" report |
| Variable | Used by | Meaning | Default |
|---|---|---|---|
CHROME_PATH |
check, pdf, shot, render, tests | browser executable | Google Chrome, then Microsoft Edge, then Playwright's Chromium |
IRODORI_URL |
TTS | OpenAI-compatible speech server | http://localhost:8882 (default) |
IRODORI_REF_DIR |
TTS | reference voice folder (--ref-dir wins) |
tts/voices/ |
MOTION_YOMI |
TTS | reading dictionary (--yomi wins) |
tts/yomi.yaml |
EGATARI_THEMES |
build, check, dev server, Egatari file | your theme folders, searched after the working folder and before the bundled themes/ (Themes); separated by : (; on Windows) |
none; ~/.egatari/themes is searched after them when it exists |