@beeson-group/tycho 0.1.0 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (44) hide show
  1. package/AUTHORS +8 -0
  2. package/LICENSE +202 -0
  3. package/NOTICE +14 -0
  4. package/README.md +38 -0
  5. package/THIRD_PARTY_NOTICES.md +68 -0
  6. package/dist/tycho.esm.js +1517 -760
  7. package/dist/tycho.js +1517 -760
  8. package/dist/types/container.d.ts +64 -0
  9. package/dist/types/errors.d.ts +9 -0
  10. package/dist/types/evaluate/clock.d.ts +36 -0
  11. package/dist/types/evaluate/frames.d.ts +63 -0
  12. package/dist/types/evaluate/index.d.ts +21 -0
  13. package/dist/types/evaluate/layers.d.ts +108 -0
  14. package/dist/types/evaluate/resolve.d.ts +50 -0
  15. package/dist/types/evaluate/sets.d.ts +50 -0
  16. package/dist/types/evaluate/timeline.d.ts +60 -0
  17. package/dist/types/evaluate/types.d.ts +87 -0
  18. package/dist/types/index.d.ts +22 -0
  19. package/dist/types/runtime/colormaps.d.ts +10 -0
  20. package/dist/types/runtime/colors.d.ts +121 -0
  21. package/dist/types/runtime/element.d.ts +290 -0
  22. package/dist/types/runtime/export.d.ts +129 -0
  23. package/dist/types/runtime/geometry.d.ts +217 -0
  24. package/dist/types/runtime/icons.d.ts +66 -0
  25. package/dist/types/runtime/layout.d.ts +34 -0
  26. package/dist/types/runtime/outline.d.ts +29 -0
  27. package/dist/types/runtime/overlay.d.ts +33 -0
  28. package/dist/types/runtime/paint.d.ts +110 -0
  29. package/dist/types/runtime/raster.d.ts +33 -0
  30. package/dist/types/runtime/readouts.d.ts +136 -0
  31. package/dist/types/runtime/renderer.d.ts +551 -0
  32. package/dist/types/runtime/state.d.ts +104 -0
  33. package/dist/types/runtime/tiles.d.ts +33 -0
  34. package/dist/types/scene.d.ts +51 -0
  35. package/dist/types/scene.gen.d.ts +2033 -0
  36. package/dist/types/validate.d.ts +9 -0
  37. package/package.json +63 -35
  38. package/src/colormaps.ts +0 -42
  39. package/src/container.ts +0 -126
  40. package/src/element.ts +0 -1034
  41. package/src/frames.ts +0 -204
  42. package/src/index.ts +0 -14
  43. package/src/layout.ts +0 -82
  44. package/src/viewer.ts +0 -864
@@ -0,0 +1,121 @@
1
+ /**
2
+ * Colors for drawing: the theme, a layer's color as a constant or a colormap over
3
+ * a parameter or a channel of its set, and the body colors. Colors are sRGB in [0, 1] and are
4
+ * written to the canvas as they are, without color management.
5
+ */
6
+ import type { SetData } from '../evaluate/sets.js';
7
+ import type { ColormapByChoice, ColormapName, ColorSpec, Scene } from '../scene.js';
8
+ import { type ColormapId } from './colormaps.js';
9
+ export type Rgb = [number, number, number];
10
+ export interface Theme {
11
+ background: string;
12
+ foreground: string;
13
+ grid: string;
14
+ /** A CSS font family for every text of the page and of a video. */
15
+ font?: string;
16
+ /** The color of the panel area and of the gutters between panels, on the page and in a video, by default a blend of the foreground and the background. */
17
+ gutter?: string;
18
+ /** The foreground and the background of the scene's own theme, which the colors equal to them follow. */
19
+ sceneForeground?: string;
20
+ sceneBackground?: string;
21
+ }
22
+ /**
23
+ * A color of the scene as the viewer draws it: a color equal to the foreground or the background of the scene's theme is drawn
24
+ * in the viewer's foreground or background, so that black lines and white marker fills of a scene written for a white page follow
25
+ * a palette that replaces its theme, e.g. the dark one of a slide. Any other color is drawn as it is.
26
+ */
27
+ export declare function themed(hex: string, theme: Theme): string;
28
+ /** A layer's color with its fixed colors themed. */
29
+ export declare function themedSpec(spec: ColorSpec | undefined, theme: Theme): ColorSpec | undefined;
30
+ /** A marker with its fill and its edge themed. */
31
+ export declare function themedMarker<M extends {
32
+ color?: string;
33
+ edge?: string;
34
+ }>(m: M, theme: Theme): M;
35
+ export declare const DEFAULT_THEME: Theme;
36
+ export declare function sceneTheme(scene: Scene): Theme;
37
+ /** The palettes of the `theme` attribute of `<tycho-viewer>`, which match the dark and light modes of the Beeson group's slide theme. */
38
+ export declare const PALETTES: {
39
+ readonly dark: {
40
+ readonly background: '#050505';
41
+ readonly foreground: '#f2f2ef';
42
+ readonly grid: '#232320';
43
+ };
44
+ readonly light: {
45
+ readonly background: '#faf8f3';
46
+ readonly foreground: '#141413';
47
+ readonly grid: '#e3e0d8';
48
+ };
49
+ };
50
+ /**
51
+ * The value of a CSS color as `#rrggbb`, or null when `value` is empty or is not a color. A form other than `#rgb` and
52
+ * `#rrggbb` is read only in a browser, by painting it on a canvas. A canvas keeps its previous fill for a color that it rejects,
53
+ * hence such a color is detected by two different previous fills.
54
+ */
55
+ export declare function cssColorHex(value: string): string | null;
56
+ /**
57
+ * The theme that a viewer draws with. `base` is the scene's theme, a `name` of a palette replaces it, and a color read from one of
58
+ * the custom properties `--tycho-background`, `--tycho-foreground`, and `--tycho-grid` takes precedence over both.
59
+ */
60
+ export declare function hostTheme(base: Theme, name: string | null, read: (property: string) => string): Theme;
61
+ /** The brand colors of the viewer's controls. Orange marks what is current, and violet what the pointer or the keyboard touches. */
62
+ export declare const ACCENT: {
63
+ readonly accent: '#f0a050';
64
+ readonly hover: '#ffb366';
65
+ readonly press: '#d98a3a';
66
+ readonly violet: '#c050f0';
67
+ readonly violetText: '#d98cff';
68
+ readonly error: '#ff7a7a';
69
+ };
70
+ /**
71
+ * The colors of the controls as CSS custom properties. The neutrals are
72
+ * the theme's foreground mixed toward its background, and the orange and violet accents are
73
+ * fixed. Every value is a color, hence the result can be put into a style sheet as it is.
74
+ */
75
+ export declare function controlsTokens(theme: Theme): Record<string, string>;
76
+ /** Parses `hex`, written as `#rrggbb`, into three numbers in [0, 1], and returns white, [1, 1, 1], for any other string. */
77
+ export declare function hexRgb(hex: string): Rgb;
78
+ /** The color `a` blended toward `b` by the fraction `t`, as `#rrggbb`. */
79
+ export declare function mixHex(a: string, b: string, t: number): string;
80
+ /**
81
+ * A value's position on a colormap. The interval `range` maps to [0, 1], a value outside it is
82
+ * clamped, and the result maps onto the part of the colormap that `truncate` specifies.
83
+ */
84
+ export declare function colormapPosition(value: number, range: readonly [number, number], truncate?: readonly [number, number]): number;
85
+ /** A colormapped color's values over a set, one per trajectory or one per sample, with its range and truncation. */
86
+ export interface ColorScale {
87
+ id: ColormapId;
88
+ name: string;
89
+ perTrajectory: boolean;
90
+ values: ArrayLike<number>;
91
+ range: [number, number];
92
+ truncate: [number, number];
93
+ }
94
+ /** A function from which a color reads a choice. It returns the current value of `input`, or undefined when `input` does not have one. */
95
+ export type ChoiceValue = (input: string) => string | undefined;
96
+ /**
97
+ * The colormap given by `colormap`, or for a map keyed by a choice, its entry for the choice's
98
+ * current value. The map's first entry is used without a value or for a value that the map lacks.
99
+ */
100
+ export declare function colormapName(colormap: ColormapName | ColormapByChoice, value?: ChoiceValue): ColormapId;
101
+ /** A color given by thresholds of a channel (section 2.7), which is not a colormap and does not have a colorbar. */
102
+ export type ThresholdColor = Extract<ColorSpec, {
103
+ thresholds: unknown;
104
+ }>;
105
+ export declare const isThreshold: (spec: ColorSpec | undefined) => spec is ThresholdColor;
106
+ /** The index of the color of a threshold color at value `x`, i.e. the count of thresholds below `x`. */
107
+ export declare function thresholdIndex(thresholds: readonly number[], x: number): number;
108
+ export declare function colorScale(spec: Exclude<ColorSpec, string | ThresholdColor>, set: SetData, value?: ChoiceValue): ColorScale;
109
+ /** A layer's color on its set, either one constant or one color per sample (a trajectory's color repeated over its samples). */
110
+ export type Coloring = {
111
+ kind: 'constant';
112
+ rgb: Rgb;
113
+ } | {
114
+ kind: 'sample';
115
+ rgb: Float32Array;
116
+ };
117
+ export declare function coloring(spec: ColorSpec | undefined, set: SetData, fallback: Rgb, value?: ChoiceValue): Coloring;
118
+ /** Colors along the part of a colormap that a scale uses, from 0 at the low end to 1 at the high end. */
119
+ export declare function gradientStops(scale: ColorScale, stops?: number): [number, string][];
120
+ /** A CSS gradient from the bottom up over the part of a colormap that a scale uses. */
121
+ export declare function gradientCss(scale: ColorScale, stops?: number): string;
@@ -0,0 +1,290 @@
1
+ import type { Readout, State } from '../scene.js';
2
+ import { type ExportOptions } from './export.js';
3
+ import { type DropZone } from './layout.js';
4
+ import { type ReadoutTile } from './readouts.js';
5
+ /** A readout's elements, which are stat tiles when its text splits, or else one line that also shows an error. */
6
+ export interface ReadoutDom {
7
+ parts: Readout['parts'];
8
+ tiles: ReadoutTile[] | null;
9
+ root: HTMLDivElement;
10
+ list: HTMLElement | null;
11
+ values: HTMLElement[];
12
+ line: HTMLDivElement;
13
+ }
14
+ /**
15
+ * A chip holds a grip and a label in a body that drags, then a caret. The caret is a menu button for `menu`. For `select` it
16
+ * is a chevron under a native select at opacity 0, which opens the platform's picker, and for `none` it is left out. The caret
17
+ * never starts a drag.
18
+ */
19
+ export declare function buildChip(text: string, caret: 'menu' | 'select' | 'none'): {
20
+ root: HTMLDivElement;
21
+ body: HTMLSpanElement;
22
+ label: HTMLSpanElement;
23
+ button: HTMLButtonElement | null;
24
+ select: HTMLSelectElement | null;
25
+ };
26
+ /** A readout's elements, as stat tiles when `readoutTiles` splits its parts, in a row under the panel area or stacked in a panel. */
27
+ export declare function buildReadout(parts: Readout['parts'], cls: 'wide' | 'stack'): ReadoutDom;
28
+ /** Writes a readout: its value parts into the tiles, or the whole text, or an error, as a line. */
29
+ export declare function fillReadout(r: ReadoutDom, pieces: string[] | {
30
+ error: string;
31
+ }): void;
32
+ /** The words inside a drop marker. */
33
+ export declare function dropText(payload: {
34
+ kind: string;
35
+ }, zone: DropZone): string;
36
+ /** HTMLElement where there is one, so that importing this module under Node does not throw. */
37
+ declare const Base: typeof HTMLElement;
38
+ /**
39
+ * The class of the `<tycho-viewer>` element. It reads its attributes once, when it connects, apart from `theme`, and shows the
40
+ * error of a scene that cannot be read in place of the panels.
41
+ */
42
+ export declare class TychoViewerElement extends Base {
43
+ static readonly observedAttributes: string[];
44
+ private scene;
45
+ private sceneText;
46
+ private geometry;
47
+ private store;
48
+ private renderer;
49
+ /** The colors in use, or null before a scene loads. */
50
+ private theme;
51
+ private kiosk;
52
+ /**
53
+ * What a twin made by `exportVideo` shows, or null for a viewer on the page. A twin is hidden, is drawn only by the export, and
54
+ * does not save its state. As `kiosk` it is the picture of a kiosk viewer, and as `picture` the panel area over its caption readouts.
55
+ */
56
+ private twin;
57
+ private minimal;
58
+ private keepPanels;
59
+ private loading;
60
+ /** Counts the loads begun, so that a load that a later one overtook drops its result. */
61
+ private loads;
62
+ /** The per-panel choice that a panel's header chip shows. */
63
+ private choice;
64
+ private root;
65
+ private header;
66
+ private titleEl;
67
+ private varsEl;
68
+ private addEl;
69
+ private panelArea;
70
+ private panelsEl;
71
+ private statusEl;
72
+ private statsEl;
73
+ private footer;
74
+ private canvas;
75
+ /** The 2D canvas over the panel area, on which labels, boxes, and overlays are painted. */
76
+ private paintCanvas;
77
+ /** The held progress, valid while the frame index is the one it was taken at. */
78
+ private get heldProgress();
79
+ private set heldProgress(value);
80
+ /** The progress shown while paused at a time between two frame indices, e.g. after `seek`, or null. */
81
+ private heldValue;
82
+ /** The frame index at which `heldValue` was taken. Any other frame index, e.g. after a scrub, drops it. */
83
+ private heldFrame;
84
+ /** The loop position, unwrapped from the anchor of playback, at which `playTo` pauses, and the step it stops at. */
85
+ private stopAt;
86
+ private readonly panelDom;
87
+ private readonly gutterDom;
88
+ private gutters;
89
+ private sceneWidgets;
90
+ private captions;
91
+ private addChips;
92
+ private addButton;
93
+ private addGroup;
94
+ private playback;
95
+ private menu;
96
+ /** Closes the export row when it is open, and returns whether it was open. */
97
+ private closeExport;
98
+ private raf;
99
+ /** The panel under the pointer, on which the keys of a 3d camera act, or null. */
100
+ private hovered;
101
+ /** Whether the element intersects the viewport. It stays true where IntersectionObserver does not exist. */
102
+ private intersecting;
103
+ /** Whether the animation loop may run, i.e. the element intersects the viewport and the page is visible. */
104
+ private shown;
105
+ private viewObserver;
106
+ private readonly onVisibility;
107
+ private dirty;
108
+ private anchor;
109
+ /** The progress that playback last reached, between two frame indices, or null while paused. */
110
+ private playProgress;
111
+ private speed;
112
+ private readonly meter;
113
+ /** The panel area's size in CSS pixels, kept by the resize observer so that a draw never forces a layout. */
114
+ private panelAreaSize;
115
+ private saveTimer;
116
+ private resizeObserver;
117
+ /** Watches the header and the colorbars of every panel, whose sizes the labels are kept clear of. */
118
+ private overlayObserver;
119
+ private readonly onPageHide;
120
+ private unsubscribe;
121
+ private lastPanels;
122
+ private lastLayout;
123
+ /** Restates the export's length when the speed changes. */
124
+ private refreshExport;
125
+ connectedCallback(): void;
126
+ disconnectedCallback(): void;
127
+ attributeChangedCallback(): void;
128
+ private buildShell;
129
+ private fail;
130
+ /** The element that `selector` matches, or null when it does not match any or is not a valid selector, as most URLs are not. */
131
+ private select;
132
+ /** The block or the URL of the scene or the data, by the order given at the top of this file, or null when the page gives neither. */
133
+ private source;
134
+ private read;
135
+ /** Loads the scene that the page gives this viewer. A viewer without any source stays empty until a caller invokes `load`. */
136
+ private loadFromSources;
137
+ /**
138
+ * Loads a scene from the text of scene.tys and the bytes of data.tyd, and resolves once the scene or
139
+ * its error shows. A load begun later takes precedence over this one.
140
+ */
141
+ load(sceneText: string, dataBytes: Uint8Array): Promise<void>;
142
+ private start;
143
+ private stop;
144
+ /** The computed value of a custom property on the host, or an empty string when it is not set. */
145
+ private hostProperty;
146
+ /** Recolors the controls and a live renderer from the scene's theme, the `theme` attribute, and the custom properties of the host. */
147
+ private applyTheme;
148
+ private recall;
149
+ private save;
150
+ private flushSave;
151
+ /** Returns to the scene's initial state and discards the stored state. */
152
+ reset(): void;
153
+ /** The current state snapshot of section 2.8, or null before a scene loads. */
154
+ get state(): State | null;
155
+ private onChange;
156
+ private invalidate;
157
+ private schedule;
158
+ /** Stops the animation loop when the element stops being shown, and restarts it when the element comes back, with the clock where it paused. */
159
+ private syncShown;
160
+ /** The loop position that playback last reached, between two frame indices, so that a new anchor does not move the picture back to a frame index. */
161
+ private playPosition;
162
+ /**
163
+ * One animation frame. In live playback it maps wall time to a loop position, whose integer part is the
164
+ * frame index the controls show, and draws at the fractional progress every frame. Otherwise it draws
165
+ * if anything changed.
166
+ */
167
+ private tick;
168
+ /** Feeds the frame rate shown in the Playback group with a draw presented at `now`. */
169
+ private countDraw;
170
+ private showRate;
171
+ /** Reads the panel area's size once per resize, so that the draw loop never forces a layout. */
172
+ private measurePanelArea;
173
+ /** Draws the panel area and its overlays at the pixel ratio of the screen, at most 2, or at `ratio` when it is given. */
174
+ private draw;
175
+ /** Whether a split of the layout moves with the timeline, so that the panels' elements follow it at every frame. */
176
+ private get animatedLayout();
177
+ /** Paints the labels, the boxes, the panel fades, and the overlays over the panel area at progress `q`. */
178
+ private paint;
179
+ private pieces;
180
+ private firstPanel;
181
+ private hasPlayback;
182
+ /** Whether the clock is set to run. It stays true while the clock waits for the element to be shown. */
183
+ get playing(): boolean;
184
+ /** Starts the clock, at once or when the element is next shown. It does not do anything before a scene loads. */
185
+ play(): void;
186
+ /** Stops the clock. It does not do anything before a scene loads. */
187
+ pause(): void;
188
+ private step;
189
+ /** The steps of the scene, in order of time. */
190
+ get steps(): {
191
+ id: string;
192
+ at: number;
193
+ label?: string;
194
+ }[];
195
+ /** The time of the timeline shown, in seconds, or 0 before a scene loads. */
196
+ get time(): number;
197
+ /** The id of the last step at or before the time shown, or null when there is none. */
198
+ get currentStep(): string | null;
199
+ private stepIndex;
200
+ /** Shows time `t` of the timeline, in seconds, paused. A time at the end of the loop holds its last picture. */
201
+ seek(t: number): void;
202
+ /** Shows a step, given by its id or its index, paused. */
203
+ goto(step: string | number): void;
204
+ /** Plays from the time shown, and pauses at the time of a step, given by its id or index. A step behind the time shown is reached on the next loop. */
205
+ playTo(step: string | number): void;
206
+ /** Plays to the next step, and returns its id, or null when the time shown is at or past the last step. */
207
+ next(): string | null;
208
+ /** Shows the step before the time shown, paused, and returns its id, or null when there is none. */
209
+ previous(): string | null;
210
+ private reachStep;
211
+ /** Goes to a frame, playing on from there when playing. */
212
+ private seekFrame;
213
+ private onKey;
214
+ /**
215
+ * Acts on a key that reached the element, and returns whether the viewer used it. A key used by a focused control counts as
216
+ * used, since a listener on the document, such as reveal.js's, sees the event retargeted to the element and cannot tell.
217
+ */
218
+ private useKey;
219
+ /** Returns every panel with camera keyframes to its keyframes, and fits every other panel's camera to what it draws. */
220
+ fitAll(): void;
221
+ private fitPanel;
222
+ /** Moves the first shared slider by `by` stops, and returns false when there is not a slider with stops to move. */
223
+ private stepSlider;
224
+ private buildFooter;
225
+ /**
226
+ * Exports a video of the current state, at the viewer's playback speed unless `options.speed` is set, and resolves to an MP4
227
+ * blob. The frames show what a kiosk viewer of this size shows when `options.kiosk` is true, which is the default for a kiosk
228
+ * viewer, and the panel area over its caption readouts otherwise. It rejects for the reasons that exportVideo in export.ts lists, and
229
+ * when the viewer has not loaded a scene.
230
+ */
231
+ exportVideo(options?: ExportOptions): Promise<Blob>;
232
+ /** The size in CSS pixels of what an export shows at the size of this viewer, i.e. the whole viewer for a kiosk, and the panel area over the caption readouts otherwise. */
233
+ private pictureSize;
234
+ /**
235
+ * Lays out a hidden twin of this viewer at w by h CSS pixels, with a frozen copy of the state, for an export to draw. The twin
236
+ * lives in this viewer's shadow root, hence it inherits the font, the custom properties, and the theme of this viewer.
237
+ */
238
+ private openTwin;
239
+ /** Draws a twin at frame index `index` and progress `q`, at `ratio` canvas pixels per CSS pixel. */
240
+ private drawAt;
241
+ private buildExport;
242
+ private makeWidget;
243
+ /** The per-panel choice that a panel header chip shows, i.e. the one that the frame of a declared panel reads, or else the first. */
244
+ private templateChoice;
245
+ /** What the Add panel group offers, i.e. every declared panel by its label or id. */
246
+ private templates;
247
+ private buildTopBar;
248
+ private buildAddGroup;
249
+ /** Shows the Add panel chips on one line, or the single Add panel menu button when they would wrap. */
250
+ private fitAddGroup;
251
+ /** The menu of a chip in the top bar, with Add panel, then Split right, Split below, and Replace for every panel. */
252
+ private chipEntries;
253
+ private addPanel;
254
+ private isTall;
255
+ /** A shown panel's name in the menus, which is its declared panel when the scene declares several, then what its header chip shows. */
256
+ private panelName;
257
+ /** Opens a menu under `anchor`, or closes it when it is the one open. */
258
+ private openMenu;
259
+ private closeMenu;
260
+ private syncWidgets;
261
+ private panelValue;
262
+ private syncPanels;
263
+ private createPanelDom;
264
+ private observeOverlay;
265
+ /**
266
+ * Measures the header of a panel and writes its height as --header-height, which places the colorbars under it, hides the colorbars when
267
+ * they do not have room, and gives the renderer both boxes, which the labels are kept clear of. It reads the layout, hence it
268
+ * runs when the observer reports a change of size, or before a frame of an export, but not in the draw loop.
269
+ */
270
+ private measureOverlay;
271
+ private removePanelDom;
272
+ /** Places panels and gutters where the layout tiles the panel area. */
273
+ private layoutDom;
274
+ private startResize;
275
+ /** Writes a panel's colorbars from the renderer's data, in place, so that a drag on one survives the redraw it causes. */
276
+ private syncBars;
277
+ private makeBar;
278
+ private barStops;
279
+ /** Sets the bar's parameter input to the stop nearest the value at `t` along the bar, as the top bar's slider does. */
280
+ private setFromBar;
281
+ private stepBar;
282
+ private startDrag;
283
+ private dropOn;
284
+ }
285
+ /**
286
+ * Registers TychoViewerElement as the custom element `tag`, which a page passes when the default name is taken. It does
287
+ * not do anything when an element named `tag` is already defined or where the environment lacks custom elements (e.g. Node).
288
+ */
289
+ export declare function define(tag?: string): void;
290
+ export {};
@@ -0,0 +1,129 @@
1
+ import type { Clock } from '../scene.js';
2
+ export interface ExportLimits {
3
+ frames: number;
4
+ seconds: number;
5
+ }
6
+ /** The longest export allowed by default, in frames and in seconds. A longer export is refused unless `limits` of ExportOptions raises them. */
7
+ export declare const EXPORT_LIMITS: Readonly<ExportLimits>;
8
+ export declare const EXPORT_FPS: readonly [24, 30, 60];
9
+ export declare const EXPORT_LOOPS: readonly [1, 2, 3, 4];
10
+ export interface Schedule {
11
+ /** The number of output frames. */
12
+ count: number;
13
+ /** The length of the video in seconds. */
14
+ duration: number;
15
+ /** The frame index shown at output frame `k`, which its readouts' clock parts show. */
16
+ index(k: number): number;
17
+ /** The progress drawn at output frame `k`, between two frame indices as live playback draws it. */
18
+ progress(k: number): number;
19
+ }
20
+ /**
21
+ * Every output frame, as live playback would draw it at the time of the frame. A loop of `frameCount` frames lasts
22
+ * `seconds / speed`, where `seconds` is the clock's loopSeconds. Output frame `k` is drawn at time
23
+ * `k / fps`, at the progress reached then, with the integer part of the loop position as its index.
24
+ */
25
+ export declare function frameSchedule(frameCount: number, fps: number, loops: number, speed?: number, start?: number, seconds?: number): Schedule;
26
+ /** Why an export of `count` frames at `fps` is refused under `limits`, or null when it is not. */
27
+ export declare function checkExport(count: number, fps: number, limits?: ExportLimits): string | null;
28
+ /**
29
+ * The frame rate an export row starts at, i.e. the highest of EXPORT_FPS at which one loop at
30
+ * `speed` stays within EXPORT_LIMITS, or null when every rate in EXPORT_FPS exceeds them.
31
+ */
32
+ export declare function defaultExportFps(frameCount: number, speed: number, seconds?: number): number | null;
33
+ export type SizePreset = '720p' | '1080p' | 'panels';
34
+ export interface ExportSize {
35
+ /** The size of the video in pixels, as `width` and `height`. */
36
+ width: number;
37
+ height: number;
38
+ /** Video pixels per CSS pixel. The layout, the fit, the line widths, and the text are laid out at a width of width / pixelRatio CSS pixels. */
39
+ pixelRatio: number;
40
+ }
41
+ /**
42
+ * A preset's size at `fps`. The presets 720p and 1080p share one layout of 1280 by 720 CSS pixels,
43
+ * at pixel ratios of 1 and 1.5. The preset `panels` is the size of the panel area rounded down to even pixels,
44
+ * at the whole pixel ratio nearest the screen's, at most 2. Where H.264 cannot hold the size and the
45
+ * rate there, the ratio is lowered in eighths to the largest at which it can. Both sides are kept even, as required by H.264.
46
+ */
47
+ export declare function sizePreset(preset: SizePreset, panelArea?: {
48
+ w: number;
49
+ h: number;
50
+ }, devicePixelRatio?: number, fps?: number): ExportSize;
51
+ /**
52
+ * The widest side an export takes. The H.264 hardware encoder of macOS does not accept a wider side (VideoToolbox
53
+ * does not open a session at 4352 by 2160), and Chrome there falls back to software beyond it.
54
+ */
55
+ export declare const AVC_MAX_SIDE = 4096;
56
+ /** Whether H.264 holds a size and rate, i.e. whether both sides are even, a level up to 5.2 holds them, and neither side exceeds AVC_MAX_SIDE. */
57
+ export declare function avcFits(width: number, height: number, fps: number): boolean;
58
+ /** The H.264 codec string for a size and rate, at the lowest level that holds them, or null past level 5.2. */
59
+ export declare function avcCodec(width: number, height: number, fps: number, profile?: 'high' | 'main' | 'baseline'): string | null;
60
+ /** A target bitrate of 0.08 bits per pixel per frame, ample for lines on a plain background, within 1 to 40 Mbit/s. */
61
+ export declare function exportBitrate(width: number, height: number, fps: number): number;
62
+ /**
63
+ * MP4 muxing of encoded H.264 chunks, through mp4-muxer's raw path, so that it runs without
64
+ * WebCodecs. The moov box goes before the media data.
65
+ */
66
+ export declare class Mp4Writer {
67
+ private readonly muxer;
68
+ constructor(width: number, height: number, fps: number);
69
+ /** Adds one encoded frame. Times are in microseconds. */
70
+ add(data: Uint8Array, key: boolean, timestamp: number, duration: number, meta?: EncodedVideoChunkMetadata): void;
71
+ finish(): Uint8Array;
72
+ }
73
+ export interface ExportOptions {
74
+ /** A preset, or an explicit size. Defaults to 720p. */
75
+ size?: SizePreset | ExportSize;
76
+ fps?: number;
77
+ loops?: number;
78
+ /** The playback speed, at which a revolution of the clock lasts 8 s divided by the speed. Defaults to 1. */
79
+ speed?: number;
80
+ /** The frame index of the first frame. Defaults to 0. */
81
+ start?: number;
82
+ /**
83
+ * Whether each frame is the picture of a kiosk viewer of the video's size in CSS pixels, i.e. the panel area alone. Otherwise a frame
84
+ * holds the panel area over the caption readouts. Defaults to whether the viewer has the attribute `kiosk`.
85
+ */
86
+ kiosk?: boolean;
87
+ /** The longest export allowed, by default EXPORT_LIMITS. */
88
+ limits?: ExportLimits;
89
+ bitrate?: number;
90
+ /** The number of frames from one key frame to the next, by default twice the frame rate. Infinity makes the first frame the only key frame. */
91
+ keyFrameInterval?: number;
92
+ /** The hardware acceleration asked of the H.264 encoder, by default `no-preference`. */
93
+ hardwareAcceleration?: HardwareAcceleration;
94
+ /** Called with the encoder configuration the browser accepted, before the first frame. */
95
+ onConfig?: (config: VideoEncoderConfig) => void;
96
+ /** Called with each frame, as a canvas of the video's size, after it is drawn and before it is encoded. */
97
+ onFrame?: (frame: HTMLCanvasElement, k: number) => void;
98
+ onProgress?: (done: number, total: number) => void;
99
+ signal?: AbortSignal;
100
+ }
101
+ /** A picture laid out at a size, which an export draws at each frame. */
102
+ export interface Picture {
103
+ /** Draws frame index `index` at progress `q` onto `g`, whose transform maps the picture's CSS pixels to the canvas. */
104
+ draw(g: CanvasRenderingContext2D, index: number, q: number): void;
105
+ close(): void;
106
+ }
107
+ /** What an export draws, as the viewer gives it. */
108
+ export interface ExportSource {
109
+ clock: Clock;
110
+ /** The size of the picture on the page in CSS pixels, which the `panels` preset starts from. */
111
+ panelArea: {
112
+ w: number;
113
+ h: number;
114
+ };
115
+ /** Lays out the picture at w by h CSS pixels, to be drawn at `ratio` video pixels per CSS pixel, and resolves once it can be drawn. */
116
+ open(w: number, h: number, ratio: number): Promise<Picture>;
117
+ }
118
+ export declare function webCodecsMissing(): string | null;
119
+ /**
120
+ * The first H.264 configuration this browser's encoder accepts, at the lowest level that holds the
121
+ * size and rate. The profiles high, main, and baseline are tried in turn, in the avc format used in an MP4.
122
+ */
123
+ export declare function chooseConfig(width: number, height: number, fps: number, bitrate: number, hardwareAcceleration?: HardwareAcceleration): Promise<VideoEncoderConfig>;
124
+ /**
125
+ * Exports a video of `source` and resolves to an MP4 blob of H.264. Rejects with an AbortError
126
+ * when `options.signal` aborts, and with an Error that gives the reason when WebCodecs is missing, when
127
+ * the browser does not have an H.264 encoder for the size, or when the export would exceed its limits.
128
+ */
129
+ export declare function exportVideo(source: ExportSource, options?: ExportOptions): Promise<Blob>;