@algorisys/tinyfly 0.100.0 → 0.102.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.
- package/README.md +6 -6
- package/bin/tinyfly.mjs +16 -6
- package/docs/character-appearance.md +26 -0
- package/docs/editor-guide.md +1 -1
- package/docs/examples.md +1 -1
- package/docs/getting-started.md +1 -1
- package/docs/gsap-compat.md +1 -1
- package/docs/llm-guide.md +22 -4
- package/docs/maps.md +2 -2
- package/docs/scene-3d.md +140 -9
- package/docs/teaching.md +1 -1
- package/docs/video-rendering.md +198 -1
- package/lib/addons/adapters.js +431 -332
- package/lib/addons/characters.js +3889 -3773
- package/lib/addons/load-scene-oWNsYYC1.js +372 -0
- package/lib/addons/scene-3d-webgl.js +31 -31
- package/lib/addons/scene-3d.js +669 -314
- package/lib/addons/shading-0lPgnXmD.js +96 -0
- package/lib/browser/tinyfly-scene-3d-webgl.iife.js +2 -2
- package/lib/browser/tinyfly-scene-3d.iife.js +2 -2
- package/lib/browser/tinyfly.iife.js +15 -15
- package/lib/browser/tinyfly.js +6232 -5723
- package/lib/browser/tinyfly.umd.js +15 -15
- package/lib/engine/tinyfly-engine.js +1563 -1170
- package/lib/engine/tinyfly-engine.umd.cjs +2 -2
- package/lib/headless/headless.js +189 -6
- package/lib/types/adapters/canvas/framing.d.ts +27 -0
- package/lib/types/adapters/canvas/impossible.d.ts +15 -0
- package/lib/types/adapters/canvas/index.d.ts +4 -0
- package/lib/types/adapters/canvas/nested-zoom.d.ts +40 -0
- package/lib/types/adapters/canvas/zoom-blur.d.ts +49 -0
- package/lib/types/characters/character-script-3d.d.ts +21 -1
- package/lib/types/characters/character.d.ts +23 -3
- package/lib/types/characters/head/face.d.ts +19 -2
- package/lib/types/characters/index.d.ts +2 -1
- package/lib/types/characters/staging-3d.d.ts +56 -0
- package/lib/types/engine/authoring/beat-loop.d.ts +46 -0
- package/lib/types/engine/authoring/curve.d.ts +26 -0
- package/lib/types/engine/authoring/framing.d.ts +48 -0
- package/lib/types/engine/authoring/index.d.ts +4 -0
- package/lib/types/engine/authoring/periodic.d.ts +89 -0
- package/lib/types/engine/path/goo.d.ts +103 -0
- package/lib/types/engine/path/impossible.d.ts +92 -0
- package/lib/types/engine/path/index.d.ts +6 -0
- package/lib/types/engine/path/similarity.d.ts +48 -0
- package/lib/types/headless/audio-mix.d.ts +40 -0
- package/lib/types/headless/ffmpeg-args.d.ts +2 -0
- package/lib/types/headless/frame-renderer.d.ts +7 -1
- package/lib/types/headless/index.d.ts +2 -0
- package/lib/types/headless/loop-audio.d.ts +21 -0
- package/lib/types/headless/node-audio.d.ts +39 -0
- package/lib/types/headless/node-video.d.ts +2 -0
- package/lib/types/headless/video-scene.d.ts +21 -0
- package/lib/types/scene-3d/camera.d.ts +11 -2
- package/lib/types/scene-3d/geometry/mesh.d.ts +2 -0
- package/lib/types/scene-3d/geometry/primitives.d.ts +7 -0
- package/lib/types/scene-3d/impossible-3d.d.ts +29 -0
- package/lib/types/scene-3d/index.d.ts +7 -3
- package/lib/types/scene-3d/lighting.d.ts +58 -0
- package/lib/types/scene-3d/resolve-scene.d.ts +18 -2
- package/lib/types/scene-3d/scene-3d-adapter.d.ts +4 -0
- package/lib/types/scene-3d/scene-types.d.ts +43 -6
- package/lib/types/scene-3d/shading.d.ts +2 -0
- package/lib/types/scene-3d/shots.d.ts +162 -0
- package/lib/types/scene-3d/software-renderer.d.ts +40 -0
- package/llms-full.txt +395 -23
- package/llms.txt +29 -29
- package/package.json +1 -1
- package/skills/tinyfly/SKILL.md +11 -1
- package/lib/addons/load-scene-CQvcFWGJ.js +0 -331
- package/lib/addons/shading-o5T_v9DT.js +0 -89
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
import { type Similarity } from '../../engine/path/similarity';
|
|
2
|
+
/**
|
|
3
|
+
* A nested zoom (a Droste picture): one drawing repeated inside itself, each
|
|
4
|
+
* level a `step` smaller and turned, and the camera diving in so that after
|
|
5
|
+
* one step every level is where the next one was. That is the whole loop: a
|
|
6
|
+
* video whose duration is one step repeats exactly.
|
|
7
|
+
*
|
|
8
|
+
* draw(ctx, frame) {
|
|
9
|
+
* nestedZoom(ctx, {
|
|
10
|
+
* step: similarityAbout(0.5, 12, { x: 640, y: 360 }),
|
|
11
|
+
* phase: frame.time / frame.period,
|
|
12
|
+
* extent: 1600,
|
|
13
|
+
* coversAbove: 1,
|
|
14
|
+
* draw: (ctx, level) => drawFrame(ctx),
|
|
15
|
+
* })
|
|
16
|
+
* }
|
|
17
|
+
*
|
|
18
|
+
* Only the levels that show are drawn: those smaller than a pixel are
|
|
19
|
+
* skipped, and so is everything behind a level that covers the whole frame.
|
|
20
|
+
*/
|
|
21
|
+
export interface NestedZoomOptions {
|
|
22
|
+
/** The step from a level to the one inside it: a shrink (and turn) about the zoom's centre (`similarityAbout`) */
|
|
23
|
+
step: Similarity;
|
|
24
|
+
/** How far into one step the zoom is, 0..1: at 1 every level has moved to where the next was */
|
|
25
|
+
phase: number;
|
|
26
|
+
/** The levels considered, outermost to innermost (default −4 to 24) */
|
|
27
|
+
levels?: [number, number];
|
|
28
|
+
/** The size of a level's drawing at level 0, px (how far it reaches): with `step`, which levels are big enough to see */
|
|
29
|
+
extent: number;
|
|
30
|
+
/** A level whose drawing is smaller than this many px is skipped (default 1) */
|
|
31
|
+
minSize?: number;
|
|
32
|
+
/** A level drawn at this screen scale or more covers the whole frame, so nothing behind it is drawn (default: nothing covers) */
|
|
33
|
+
coversAbove?: number;
|
|
34
|
+
/** Draw one level in level-0 coordinates; the transform is already applied. `scale` is its size on screen */
|
|
35
|
+
draw: (ctx: CanvasRenderingContext2D, level: number, scale: number) => void;
|
|
36
|
+
}
|
|
37
|
+
/** Where level `level` sits at a `phase` of the zoom: `step` to the power `level − phase`. */
|
|
38
|
+
export declare function nestedZoomTransform(step: Similarity, level: number, phase: number): Similarity;
|
|
39
|
+
/** Draw the levels of a nested zoom that show, outermost first. Returns the levels drawn. */
|
|
40
|
+
export declare function nestedZoom(ctx: CanvasRenderingContext2D, options: NestedZoomOptions): number[];
|
|
@@ -0,0 +1,49 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The dive: a zoom blur streaks the picture out from a point, and dive lines
|
|
3
|
+
* stream past the camera. Both are deterministic: the blur is a fixed set of
|
|
4
|
+
* scaled copies, the lines are seeded, and a `phase` moves them round a loop.
|
|
5
|
+
*/
|
|
6
|
+
export interface ZoomBlurOptions {
|
|
7
|
+
/** The point the blur radiates from, canvas px (default the centre) */
|
|
8
|
+
centre?: {
|
|
9
|
+
x: number;
|
|
10
|
+
y: number;
|
|
11
|
+
};
|
|
12
|
+
/** How far the streaks reach, as a fraction of each point's distance from the centre (default 0.08) */
|
|
13
|
+
strength?: number;
|
|
14
|
+
/** Copies blended (default 8): more is smoother and slower */
|
|
15
|
+
samples?: number;
|
|
16
|
+
/** `normal` (default) averages the copies; `add` adds their light, for neon on dark */
|
|
17
|
+
blend?: 'normal' | 'add';
|
|
18
|
+
/** How much of the blur shows over the original, 0..1 (default 1) */
|
|
19
|
+
amount?: number;
|
|
20
|
+
}
|
|
21
|
+
/** Add a zoom blur to what is drawn on `ctx` (its whole canvas, in device pixels). */
|
|
22
|
+
export declare function applyZoomBlur(ctx: CanvasRenderingContext2D, options?: ZoomBlurOptions): void;
|
|
23
|
+
export interface DiveLinesOptions {
|
|
24
|
+
/** The point the lines radiate from, canvas px (default the centre) */
|
|
25
|
+
centre?: {
|
|
26
|
+
x: number;
|
|
27
|
+
y: number;
|
|
28
|
+
};
|
|
29
|
+
/** How many (default 28) */
|
|
30
|
+
count?: number;
|
|
31
|
+
/** Where they start and end, px from the centre (defaults: 15% and 110% of the canvas's half-diagonal) */
|
|
32
|
+
inner?: number;
|
|
33
|
+
outer?: number;
|
|
34
|
+
/** Each line's length as a fraction of outer − inner (default 0.35) */
|
|
35
|
+
length?: number;
|
|
36
|
+
/** 0..1, moves the lines outward one line-length per unit; `phaseOf(time, period)` loops them */
|
|
37
|
+
phase?: number;
|
|
38
|
+
/** Which way they stream: `out` (default, diving in) or `in` */
|
|
39
|
+
direction?: 'out' | 'in';
|
|
40
|
+
seed?: number | string;
|
|
41
|
+
color?: string;
|
|
42
|
+
/** Stroke width at the thick end, px (default 3) */
|
|
43
|
+
width?: number;
|
|
44
|
+
opacity?: number;
|
|
45
|
+
/** `add` adds light (`'lighter'`) for neon on dark (default `normal`) */
|
|
46
|
+
blend?: 'normal' | 'add';
|
|
47
|
+
}
|
|
48
|
+
/** Streaks radiating from a point, each a fading line, in canvas space. */
|
|
49
|
+
export declare function drawDiveLines(ctx: CanvasRenderingContext2D, options?: DiveLinesOptions): void;
|
|
@@ -41,11 +41,31 @@ export interface CharacterBeat3D {
|
|
|
41
41
|
pose?: HumanPoseName | Pose;
|
|
42
42
|
/** `gag`: a gag's name (`take`, `doubleTake`, `windUp`…) */
|
|
43
43
|
gag?: HumanGagName;
|
|
44
|
+
/** `say`: the line spoken, lip-synced, with a talking head; the beat lasts as long as the line (or `for`) */
|
|
45
|
+
say?: string;
|
|
46
|
+
/** `look`: a point [x, z] (at eye height) or [x, y, z] to look at with the head and eyes, or `camera` for the viewer; `toward` as `face` takes it */
|
|
47
|
+
look?: GroundPoint | [number, number, number] | 'camera';
|
|
44
48
|
}
|
|
45
|
-
export declare const CHARACTER_BEAT_3D_FIELDS: readonly ["do", "at", "for", "to", "through", "toward", "speed", "pose", "gag"];
|
|
49
|
+
export declare const CHARACTER_BEAT_3D_FIELDS: readonly ["do", "at", "for", "to", "through", "toward", "speed", "pose", "gag", "say", "look"];
|
|
50
|
+
/** How long a line takes to say, ms: by its length, never shorter than a beat. */
|
|
51
|
+
export declare const speechLength: (text: string) => number;
|
|
52
|
+
/**
|
|
53
|
+
* Where to turn the head and eyes to look at a point from a place and a
|
|
54
|
+
* heading: the pose fields `head.turn` (toward the character's left, +),
|
|
55
|
+
* `head.nod` (down, +), `lookX` and `lookY` (the eyes, −1..1). A point behind
|
|
56
|
+
* turns the head as far as it goes and the eyes the rest of the way.
|
|
57
|
+
*/
|
|
58
|
+
export declare function lookFields(from: {
|
|
59
|
+
x: number;
|
|
60
|
+
z: number;
|
|
61
|
+
heading: number;
|
|
62
|
+
eyeHeight: number;
|
|
63
|
+
}, at: [number, number, number]): Pose;
|
|
46
64
|
export interface CharacterScript3DOptions {
|
|
47
65
|
/** The scene's id: the tracks target `<scene>/<id>` */
|
|
48
66
|
scene: string;
|
|
67
|
+
/** Where the camera is, metres, for `look: 'camera'` (default [0, 1.6, 8]) */
|
|
68
|
+
camera?: [number, number, number];
|
|
49
69
|
/** Where it was placed, [x, z] metres (its object's position) */
|
|
50
70
|
position?: GroundPoint;
|
|
51
71
|
/** Which way it faces at first, degrees (its object's rotation about y; 0 faces +z) */
|
|
@@ -93,7 +93,7 @@ export interface CharacterOptions extends HeadLookOptions {
|
|
|
93
93
|
handSize?: number;
|
|
94
94
|
/** The feet's shape: `round` (default), `flat`, `pointed` or `big` */
|
|
95
95
|
feet?: FootShape;
|
|
96
|
-
/**
|
|
96
|
+
/** The face's extras: `teeth` and a `tongue` in an open mouth, a `nose`, and `inPupil` to draw inside the pupils (default none) */
|
|
97
97
|
face?: FaceOptions;
|
|
98
98
|
}
|
|
99
99
|
/** A character, with every option resolved. Plain data plus its plan. */
|
|
@@ -116,8 +116,11 @@ export interface Character {
|
|
|
116
116
|
head: HeadLook;
|
|
117
117
|
/** What each hand holds (drawn by its layers) */
|
|
118
118
|
holding: Holding;
|
|
119
|
-
/**
|
|
120
|
-
face:
|
|
119
|
+
/** The face's extras (see `FaceOptions`) */
|
|
120
|
+
face: FaceOptions & {
|
|
121
|
+
teeth: boolean;
|
|
122
|
+
tongue: boolean;
|
|
123
|
+
};
|
|
121
124
|
}
|
|
122
125
|
export declare function character(options?: CharacterOptions): Character;
|
|
123
126
|
/** Where every part of a character is, as drawn, in its drawing space (feet at 0, 0; up is -y). */
|
|
@@ -198,6 +201,23 @@ export interface CharacterPartInView {
|
|
|
198
201
|
* behind and in front of the whole figure go with its first and last parts.
|
|
199
202
|
*/
|
|
200
203
|
export declare function characterPartsInView(character: Character, pose: Pose, projection: ViewProjection, options: Pick<InViewOptions, 'height'>): CharacterPartInView[];
|
|
204
|
+
export interface HeadCloseUpOptions {
|
|
205
|
+
/** Where the head's centre goes, px */
|
|
206
|
+
x: number;
|
|
207
|
+
y: number;
|
|
208
|
+
/** The head's radius on screen, px */
|
|
209
|
+
radius: number;
|
|
210
|
+
/** ms: the pencil's boil frame and layer hooks */
|
|
211
|
+
time?: number;
|
|
212
|
+
}
|
|
213
|
+
/**
|
|
214
|
+
* A head close-up: just the head (hair, hat, glasses, ears, the face) drawn
|
|
215
|
+
* big, its centre at `x`, `y` and its radius `radius` px, in the character's
|
|
216
|
+
* own look with its line weight scaled to the size. The pose turns and nods
|
|
217
|
+
* it and sets the face; the body is not drawn. With `face.inPupil` the pupils
|
|
218
|
+
* hold another drawing (the same head again, for a Droste face).
|
|
219
|
+
*/
|
|
220
|
+
export declare function drawCharacterHead(ctx: CanvasRenderingContext2D, character: Character, pose: Pose, options: HeadCloseUpOptions): void;
|
|
201
221
|
/** A full blend of two poses: `t` 0 is `from`, 1 is `to`. Fields in only one keep its value. */
|
|
202
222
|
export declare function mixPoses(from: Pose, to: Pose, t: number): Pose;
|
|
203
223
|
/**
|
|
@@ -14,9 +14,26 @@ export declare function faceToScreen(head: SolvedHead, points: Point[], centre:
|
|
|
14
14
|
points: Point[];
|
|
15
15
|
facing: number;
|
|
16
16
|
};
|
|
17
|
-
/**
|
|
17
|
+
/** The pupil's circle on the screen, for drawing inside it. */
|
|
18
|
+
export interface PupilCircle {
|
|
19
|
+
x: number;
|
|
20
|
+
y: number;
|
|
21
|
+
r: number;
|
|
22
|
+
side: 'left' | 'right';
|
|
23
|
+
}
|
|
24
|
+
/** What an open mouth shows: a row of upper teeth, and a tongue (default neither, as the plain face); a nose; what is in the pupils. */
|
|
18
25
|
export interface FaceOptions {
|
|
19
26
|
teeth?: boolean;
|
|
20
27
|
tongue?: boolean;
|
|
28
|
+
/** A small nose between the eyes and the mouth (default none) */
|
|
29
|
+
nose?: boolean;
|
|
30
|
+
/** The head's fill, for lids that cover the eye (default white) */
|
|
31
|
+
skin?: string;
|
|
32
|
+
/**
|
|
33
|
+
* Draw inside each pupil: the context is clipped to the pupil's circle and
|
|
34
|
+
* the hook draws there in screen space (another scene, the same head again
|
|
35
|
+
* for a Droste face). Needs the context passed to `drawFace`.
|
|
36
|
+
*/
|
|
37
|
+
inPupil?: (ctx: CanvasRenderingContext2D, pupil: PupilCircle) => void;
|
|
21
38
|
}
|
|
22
|
-
export declare function drawFace(pen: Pen, head: SolvedHead, pose: Pose, lineWidth: number, options?: FaceOptions): void;
|
|
39
|
+
export declare function drawFace(pen: Pen, head: SolvedHead, pose: Pose, lineWidth: number, options?: FaceOptions, ctx?: CanvasRenderingContext2D): void;
|
|
@@ -11,7 +11,8 @@ export * from './acrobatics';
|
|
|
11
11
|
export { stickToHuman } from './stick-to-human';
|
|
12
12
|
export { skeletonInView, solvePlanSpace, stagePlanSpace, type ViewProjection, type PlanSpace, type StagedSpace } from './rig/skeleton';
|
|
13
13
|
export { characterObjects } from './scene-objects';
|
|
14
|
-
export { characterScript3D, checkCharacterBeats3D, CHARACTER_GAIT_SPEEDS, CHARACTER_BEAT_3D_FIELDS, type CharacterBeat3D, type CharacterScript3DOptions, type CharacterScript3DResult } from './character-script-3d';
|
|
14
|
+
export { characterScript3D, checkCharacterBeats3D, lookFields, speechLength, CHARACTER_GAIT_SPEEDS, CHARACTER_BEAT_3D_FIELDS, type CharacterBeat3D, type CharacterScript3DOptions, type CharacterScript3DResult } from './character-script-3d';
|
|
15
|
+
export { characterLookAtTracks, objectPositionAt, stageSpots, type LookAtTracksOptions, type StageSpotsOptions } from './staging-3d';
|
|
15
16
|
export { type GroundPoint } from './ground-path';
|
|
16
17
|
export * from '../adapters/canvas/sketch';
|
|
17
18
|
export * from '../adapters/canvas/camera';
|
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
import type { Track } from '../engine/types';
|
|
2
|
+
/**
|
|
3
|
+
* Staging characters in a 3D scene: looking at something that moves (another
|
|
4
|
+
* character, the camera), and spots to stand several figures on without
|
|
5
|
+
* overlap. Pure functions over tracks: the result is more tracks.
|
|
6
|
+
*/
|
|
7
|
+
export type Vec3 = [number, number, number];
|
|
8
|
+
/** Where an object is at a time, from its tracks over its authored place: `x`, `y`, `z` or a `position` track. */
|
|
9
|
+
export declare function objectPositionAt(tracks: ReadonlyArray<Track>, target: string, base?: Vec3): (time: number) => Vec3;
|
|
10
|
+
export interface LookAtTracksOptions {
|
|
11
|
+
scene: string;
|
|
12
|
+
/** The character's object id */
|
|
13
|
+
character: string;
|
|
14
|
+
/** Where it looks: a point, a function of time, an object's id (sampled from the tracks over `objects`), or `camera` (the camera's id) */
|
|
15
|
+
at: Vec3 | ((time: number) => Vec3) | {
|
|
16
|
+
object: string;
|
|
17
|
+
eyeHeight?: number;
|
|
18
|
+
} | {
|
|
19
|
+
camera: string;
|
|
20
|
+
};
|
|
21
|
+
start: number;
|
|
22
|
+
end: number;
|
|
23
|
+
/** The character's height, metres (default 1.7): its eyes are near the top */
|
|
24
|
+
height?: number;
|
|
25
|
+
/** Authored positions of objects the tracks move from, by id (the character's own too) */
|
|
26
|
+
objects?: Record<string, Vec3>;
|
|
27
|
+
/** Key spacing, ms (default 66) */
|
|
28
|
+
every?: number;
|
|
29
|
+
}
|
|
30
|
+
/**
|
|
31
|
+
* Tracks that keep a character's head and eyes on something as both move:
|
|
32
|
+
* `head.turn`, `head.nod`, `lookX` and `lookY` keyed from where the
|
|
33
|
+
* character stands and faces (its `x`, `z`, `rotateY` tracks) and where the
|
|
34
|
+
* target is at each moment. Add them after the character's own tracks.
|
|
35
|
+
*/
|
|
36
|
+
export declare function characterLookAtTracks(tracks: ReadonlyArray<Track>, options: LookAtTracksOptions): Track[];
|
|
37
|
+
export interface StageSpotsOptions {
|
|
38
|
+
/** How many figures */
|
|
39
|
+
count: number;
|
|
40
|
+
/** The middle of the group, [x, z] metres (default the origin) */
|
|
41
|
+
centre?: [number, number];
|
|
42
|
+
/** Room between figures, metres (default 1.2: shoulder to shoulder with a gap) */
|
|
43
|
+
spacing?: number;
|
|
44
|
+
/** `line` (across, facing +z), `arc` (a shallow curve facing its middle), `circle` (facing in), `cluster` (a loose group, seeded) */
|
|
45
|
+
shape?: 'line' | 'arc' | 'circle' | 'cluster';
|
|
46
|
+
/** `line` and `arc`: the way the line runs, degrees (default 90: along x) */
|
|
47
|
+
heading?: number;
|
|
48
|
+
/** `arc`: how far it bends, degrees (default 60) */
|
|
49
|
+
bend?: number;
|
|
50
|
+
seed?: number;
|
|
51
|
+
}
|
|
52
|
+
/** Places and headings for several figures that do not overlap. */
|
|
53
|
+
export declare function stageSpots(options: StageSpotsOptions): Array<{
|
|
54
|
+
position: [number, number];
|
|
55
|
+
heading: number;
|
|
56
|
+
}>;
|
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
import { type BeatGrid } from './beats';
|
|
2
|
+
/**
|
|
3
|
+
* Beats and sound for loops. A loop closes when its length is a whole number
|
|
4
|
+
* of beats, so the pulse on its last beat runs straight into its first:
|
|
5
|
+
* `loopBeats` fits a grid to a period (or a period to a grid), `beatPulse`
|
|
6
|
+
* is a pulse that spikes on every beat, and `audioEnvelope` turns samples
|
|
7
|
+
* into a level per frame for motion that follows the music. All pure.
|
|
8
|
+
*/
|
|
9
|
+
/** How many ms a whole number of beats takes. */
|
|
10
|
+
export declare function beatPeriod(grid: Pick<BeatGrid, 'bpm'>, beats: number): number;
|
|
11
|
+
/**
|
|
12
|
+
* Cut a tempo to a loop: the nearest whole number of beats in `period` ms,
|
|
13
|
+
* and the tempo nudged so they fit it exactly (a drone or riser stretched a
|
|
14
|
+
* hair, never cut mid-beat). The grid's `offset` is kept.
|
|
15
|
+
*/
|
|
16
|
+
export declare function loopBeats(period: number, grid: BeatGrid): {
|
|
17
|
+
beats: number;
|
|
18
|
+
grid: BeatGrid;
|
|
19
|
+
};
|
|
20
|
+
export interface BeatPulseOptions {
|
|
21
|
+
/** How fast the pulse rises, as a share of a beat (default 0.05) */
|
|
22
|
+
attack?: number;
|
|
23
|
+
/** How long it takes to fall back, as a share of a beat (default 0.4) */
|
|
24
|
+
decay?: number;
|
|
25
|
+
/** Stress the first beat of each bar this much more, 0.. (default 0: all beats alike) */
|
|
26
|
+
barAccent?: number;
|
|
27
|
+
}
|
|
28
|
+
/**
|
|
29
|
+
* A pulse that spikes to 1 on every beat and decays, as a function of time:
|
|
30
|
+
* scale a shape by `1 + 0.2 * beatPulse(t, grid)` and it bobs to the music.
|
|
31
|
+
* Over a loop that is a whole number of beats (`loopBeats`), it repeats
|
|
32
|
+
* exactly.
|
|
33
|
+
*/
|
|
34
|
+
export declare function beatPulse(time: number, grid: BeatGrid, options?: BeatPulseOptions): number;
|
|
35
|
+
export interface EnvelopeOptions {
|
|
36
|
+
/** Levels per second (default 30: one per video frame) */
|
|
37
|
+
fps?: number;
|
|
38
|
+
/** How much each level keeps of the last, 0..1 (default 0.5): higher is smoother, slower to fall */
|
|
39
|
+
smoothing?: number;
|
|
40
|
+
/** Scale so the loudest level is 1 (default true) */
|
|
41
|
+
normalize?: boolean;
|
|
42
|
+
}
|
|
43
|
+
/** The loudness of audio over time: one level (0..1) per frame, smoothed. Deterministic. */
|
|
44
|
+
export declare function audioEnvelope(samples: Float32Array, sampleRate: number, options?: EnvelopeOptions): Float32Array;
|
|
45
|
+
/** The envelope's level at a time, between its frames; with `period` the time wraps, for a loop. */
|
|
46
|
+
export declare function envelopeAt(levels: Float32Array, time: number, fps?: number, period?: number): number;
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
import type { AnimatableValue, EasingType, TrackInterpolation } from '../types';
|
|
2
|
+
/**
|
|
3
|
+
* A keyframe curve over any input, not just time: the same keys and easings a
|
|
4
|
+
* track has, read at a number of your own. A face that opens its eyes as it
|
|
5
|
+
* grows on screen, a colour that cools with depth, a line width that follows
|
|
6
|
+
* a zoom's scale.
|
|
7
|
+
*
|
|
8
|
+
* const glow = curve([{ at: 0, value: '#223' }, { at: 300, value: '#ff2bd6', easing: 'ease-out' }])
|
|
9
|
+
* ctx.strokeStyle = glow(distanceToCamera)
|
|
10
|
+
*
|
|
11
|
+
* Before the first key the curve holds its first value, after the last its
|
|
12
|
+
* last; between keys it eases exactly as a track does.
|
|
13
|
+
*/
|
|
14
|
+
export interface CurveKey<T extends AnimatableValue = number> {
|
|
15
|
+
/** The input this key is at */
|
|
16
|
+
at: number;
|
|
17
|
+
value: T;
|
|
18
|
+
/** Easing into this key from the one before (ignored on the first) */
|
|
19
|
+
easing?: EasingType;
|
|
20
|
+
}
|
|
21
|
+
export interface CurveOptions {
|
|
22
|
+
/** How values blend (default by their type: numbers, colours, arrays) */
|
|
23
|
+
interpolation?: TrackInterpolation;
|
|
24
|
+
}
|
|
25
|
+
/** A function of the input from keys, holding the first and last values beyond them. */
|
|
26
|
+
export declare function curve<T extends AnimatableValue = number>(keys: ReadonlyArray<CurveKey<T>>, options?: CurveOptions): (x: number) => T;
|
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Frames and safe areas: the picture's aspect, letterbox bars when a film is
|
|
3
|
+
* wider or taller than its canvas, and the areas titles and action must stay
|
|
4
|
+
* inside. Pure geometry; `drawLetterbox` and `drawSafeAreas` paint them.
|
|
5
|
+
*/
|
|
6
|
+
/** Common aspects, width over height. */
|
|
7
|
+
export declare const FRAME_ASPECTS: {
|
|
8
|
+
readonly '16:9': number;
|
|
9
|
+
readonly '2.39:1': 2.39;
|
|
10
|
+
readonly '4:3': number;
|
|
11
|
+
readonly '1:1': 1;
|
|
12
|
+
readonly '9:16': number;
|
|
13
|
+
readonly '4:5': number;
|
|
14
|
+
};
|
|
15
|
+
export type FrameAspectName = keyof typeof FRAME_ASPECTS;
|
|
16
|
+
export interface FrameRect {
|
|
17
|
+
x: number;
|
|
18
|
+
y: number;
|
|
19
|
+
width: number;
|
|
20
|
+
height: number;
|
|
21
|
+
}
|
|
22
|
+
/** An aspect by name or as width over height. */
|
|
23
|
+
export declare const aspectOf: (aspect: FrameAspectName | number) => number;
|
|
24
|
+
/** The frame of the given aspect that fits centred in a canvas: the picture inside the letterbox (or pillarbox) bars. */
|
|
25
|
+
export declare function frameRect(canvas: {
|
|
26
|
+
width: number;
|
|
27
|
+
height: number;
|
|
28
|
+
}, aspect: FrameAspectName | number): FrameRect;
|
|
29
|
+
/** A size of the given aspect at a width (or a height), whole pixels, even so video encoders are happy. */
|
|
30
|
+
export declare function frameSize(aspect: FrameAspectName | number, size: {
|
|
31
|
+
width: number;
|
|
32
|
+
} | {
|
|
33
|
+
height: number;
|
|
34
|
+
}): {
|
|
35
|
+
width: number;
|
|
36
|
+
height: number;
|
|
37
|
+
};
|
|
38
|
+
export interface SafeAreas {
|
|
39
|
+
/** Action safe: what must be seen on every screen (default 90% of the frame) */
|
|
40
|
+
action: FrameRect;
|
|
41
|
+
/** Title safe: where text goes (default 80%) */
|
|
42
|
+
title: FrameRect;
|
|
43
|
+
}
|
|
44
|
+
/** The safe areas of a frame, as rectangles inset from it. */
|
|
45
|
+
export declare function safeAreas(frame: FrameRect, shares?: {
|
|
46
|
+
action?: number;
|
|
47
|
+
title?: number;
|
|
48
|
+
}): SafeAreas;
|
|
@@ -0,0 +1,89 @@
|
|
|
1
|
+
import type { EasingFunction, EasingType } from '../types';
|
|
2
|
+
/**
|
|
3
|
+
* Motion that repeats exactly over a period, for videos that loop.
|
|
4
|
+
*
|
|
5
|
+
* A loop closes when the frame at time = duration is the first frame, so
|
|
6
|
+
* every motion must repeat over the duration: a whole number of cycles, a
|
|
7
|
+
* zoom that steps one level, noise that comes back to where it started. These
|
|
8
|
+
* helpers are periodic by construction. Each takes the `period` in ms (a
|
|
9
|
+
* looping video scene's `frame.period` is its duration) and gives the same
|
|
10
|
+
* value at `time` and `time + period` to the last bit, so a loop check
|
|
11
|
+
* reports "closes" rather than "seamless".
|
|
12
|
+
*
|
|
13
|
+
* draw(ctx, frame) {
|
|
14
|
+
* const sway = wobble(frame.time, { period: frame.period, cycles: 2, amplitude: 12 })
|
|
15
|
+
* const drift = loopNoise(frame.time, { period: frame.period, seed: 'tree' }) * 30
|
|
16
|
+
* }
|
|
17
|
+
*
|
|
18
|
+
* Everything is a pure function of time: frames render in any order, and the
|
|
19
|
+
* same scene gives the same video.
|
|
20
|
+
*/
|
|
21
|
+
/** Where in its cycle a periodic motion is at `time`: 0 (inclusive) to 1 (exclusive). `cycles` whole cycles per period. */
|
|
22
|
+
export declare function phaseOf(time: number, period: number, cycles?: number): number;
|
|
23
|
+
/** 0 → 1 → 0 over one unit: `u` in 0..1 goes up to 1 at 0.5 and back, the same at 0 and 1. */
|
|
24
|
+
export declare function pingPong(u: number): number;
|
|
25
|
+
export interface WobbleOptions {
|
|
26
|
+
/** The period, ms: the motion repeats exactly every `period` */
|
|
27
|
+
period: number;
|
|
28
|
+
/** Whole cycles per period (default 1); a fraction would not repeat */
|
|
29
|
+
cycles?: number;
|
|
30
|
+
/** Peak value (default 1): the result swings between −amplitude and +amplitude */
|
|
31
|
+
amplitude?: number;
|
|
32
|
+
/** Start part way round the cycle, 0..1 (default 0) */
|
|
33
|
+
phase?: number;
|
|
34
|
+
/** The wave: a sine (default), a triangle, or a square */
|
|
35
|
+
shape?: 'sine' | 'triangle' | 'square';
|
|
36
|
+
}
|
|
37
|
+
/** A wave that repeats exactly every period: `cycles` whole cycles of a sine (or triangle, square). */
|
|
38
|
+
export declare function wobble(time: number, options: WobbleOptions): number;
|
|
39
|
+
export interface LoopEaseOptions {
|
|
40
|
+
/** The period, ms */
|
|
41
|
+
period: number;
|
|
42
|
+
/** Whole cycles per period (default 1) */
|
|
43
|
+
cycles?: number;
|
|
44
|
+
/** Easing for the way up, mirrored on the way down (default `ease-in-out`): a name or a function */
|
|
45
|
+
easing?: EasingType | EasingFunction;
|
|
46
|
+
/** Start part way round the cycle, 0..1 (default 0) */
|
|
47
|
+
phase?: number;
|
|
48
|
+
}
|
|
49
|
+
/**
|
|
50
|
+
* An eased there-and-back: 0 at the start of each cycle, 1 half way, 0 again
|
|
51
|
+
* at the end, the easing applied on the way up and mirrored on the way down.
|
|
52
|
+
* Unlike an easing of `time / period`, it repeats exactly.
|
|
53
|
+
*/
|
|
54
|
+
export declare function loopEase(time: number, options: LoopEaseOptions): number;
|
|
55
|
+
export interface LoopNoiseOptions {
|
|
56
|
+
/** The period, ms */
|
|
57
|
+
period: number;
|
|
58
|
+
/** The seed: a number or any string (default 0). Different seeds give unrelated motion */
|
|
59
|
+
seed?: number | string;
|
|
60
|
+
/** How many wiggles per period (default 1): the noise's own cycles round its circle */
|
|
61
|
+
cycles?: number;
|
|
62
|
+
/** Layers of finer, fainter detail (default 1, up to 6) */
|
|
63
|
+
octaves?: number;
|
|
64
|
+
/** Start part way round (default 0) */
|
|
65
|
+
phase?: number;
|
|
66
|
+
}
|
|
67
|
+
/**
|
|
68
|
+
* Smooth random motion that repeats exactly every period: value noise read
|
|
69
|
+
* round a circle, so the end joins the start. About −1..1, seeded, and the
|
|
70
|
+
* same for the same time, seed and options anywhere.
|
|
71
|
+
*/
|
|
72
|
+
export declare function loopNoise(time: number, options: LoopNoiseOptions): number;
|
|
73
|
+
export interface TorusNoiseOptions {
|
|
74
|
+
/** The period of the first input (time), ms */
|
|
75
|
+
period: number;
|
|
76
|
+
/** The period of the second input (a position along something): the noise repeats along it too */
|
|
77
|
+
periodAlong: number;
|
|
78
|
+
seed?: number | string;
|
|
79
|
+
/** Wiggles per period of time, and per period along (default 1 each) */
|
|
80
|
+
cycles?: number;
|
|
81
|
+
cyclesAlong?: number;
|
|
82
|
+
octaves?: number;
|
|
83
|
+
}
|
|
84
|
+
/**
|
|
85
|
+
* Noise periodic in two inputs, read round a torus: a field along a line
|
|
86
|
+
* (ripples, a flag, grass) that repeats over the loop's period in time and
|
|
87
|
+
* joins up along its length. About −1..1.
|
|
88
|
+
*/
|
|
89
|
+
export declare function torusNoise(time: number, along: number, options: TorusNoiseOptions): number;
|
|
@@ -0,0 +1,103 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Satisfying matter, as plain geometry: metaballs that merge and split, drips
|
|
3
|
+
* that form and fall, bubbles that grow, wobble and pop, and squash and
|
|
4
|
+
* stretch that keeps a blob's area (or volume). Everything is a pure function
|
|
5
|
+
* of its inputs, so a frame draws the same at any time and in any order.
|
|
6
|
+
*/
|
|
7
|
+
export interface GooPoint {
|
|
8
|
+
x: number;
|
|
9
|
+
y: number;
|
|
10
|
+
}
|
|
11
|
+
export interface Ball {
|
|
12
|
+
x: number;
|
|
13
|
+
y: number;
|
|
14
|
+
r: number;
|
|
15
|
+
}
|
|
16
|
+
export interface MetaballOptions {
|
|
17
|
+
/** Where the surface is: the field is 1 at each ball's own radius (default 1; lower is fatter, blobs merge sooner) */
|
|
18
|
+
threshold?: number;
|
|
19
|
+
/** Grid cell size, px (default 4): smaller is finer and slower */
|
|
20
|
+
cell?: number;
|
|
21
|
+
/** Round the contour's corners (default true) */
|
|
22
|
+
smooth?: boolean;
|
|
23
|
+
/** The area to trace, px (default: round the balls) */
|
|
24
|
+
bounds?: {
|
|
25
|
+
x: number;
|
|
26
|
+
y: number;
|
|
27
|
+
width: number;
|
|
28
|
+
height: number;
|
|
29
|
+
};
|
|
30
|
+
}
|
|
31
|
+
/** The metaball field at a point: each ball adds r² / d², so it is 1 at its own edge. */
|
|
32
|
+
export declare function metaballField(balls: ReadonlyArray<Ball>, x: number, y: number): number;
|
|
33
|
+
/**
|
|
34
|
+
* The outlines of merged balls, as closed polygons (marching squares over the
|
|
35
|
+
* field, corners rounded). Two balls near each other join through a neck;
|
|
36
|
+
* apart, each is its own circle.
|
|
37
|
+
*/
|
|
38
|
+
export declare function metaballContours(balls: ReadonlyArray<Ball>, options?: MetaballOptions): GooPoint[][];
|
|
39
|
+
export interface DripOptions {
|
|
40
|
+
/** Where it hangs from, px */
|
|
41
|
+
x: number;
|
|
42
|
+
y: number;
|
|
43
|
+
/** How far it reaches when fully formed, px */
|
|
44
|
+
length: number;
|
|
45
|
+
/** Its width at the top, px */
|
|
46
|
+
width: number;
|
|
47
|
+
/** 0: nothing yet; 1: fully stretched, the head about to let go */
|
|
48
|
+
progress: number;
|
|
49
|
+
/** Points round the head (default 12) */
|
|
50
|
+
segments?: number;
|
|
51
|
+
}
|
|
52
|
+
/**
|
|
53
|
+
* A drip forming under a surface: a neck that thins as it stretches, a round
|
|
54
|
+
* head that swells, as a closed polygon (y down). `progress` runs it.
|
|
55
|
+
*/
|
|
56
|
+
export declare function dripPath(options: DripOptions): GooPoint[];
|
|
57
|
+
export interface BubbleOptions {
|
|
58
|
+
x: number;
|
|
59
|
+
y: number;
|
|
60
|
+
/** Radius when fully grown, px */
|
|
61
|
+
r: number;
|
|
62
|
+
/** 0..1 grows it from nothing (default 1) */
|
|
63
|
+
grow?: number;
|
|
64
|
+
/** ms, for the wobble; with `period` the wobble repeats exactly */
|
|
65
|
+
time?: number;
|
|
66
|
+
period?: number;
|
|
67
|
+
/** How much the surface wobbles, as a share of the radius (default 0.05) */
|
|
68
|
+
wobble?: number;
|
|
69
|
+
/** Points round it (default 48) */
|
|
70
|
+
segments?: number;
|
|
71
|
+
/** Start the wobble somewhere else */
|
|
72
|
+
seed?: number;
|
|
73
|
+
}
|
|
74
|
+
/** A bubble: a circle whose surface wobbles with three gentle lobes, growing from nothing. */
|
|
75
|
+
export declare function bubblePath(options: BubbleOptions): GooPoint[];
|
|
76
|
+
export interface PopOptions {
|
|
77
|
+
x: number;
|
|
78
|
+
y: number;
|
|
79
|
+
r: number;
|
|
80
|
+
/** 0: the moment it pops; 1: the pieces are gone */
|
|
81
|
+
progress: number;
|
|
82
|
+
/** Fragments round the rim (default 8) */
|
|
83
|
+
pieces?: number;
|
|
84
|
+
}
|
|
85
|
+
/** A bubble popping: arcs of its rim flying outward and shrinking, as polylines. Empty before and after. */
|
|
86
|
+
export declare function bubblePop(options: PopOptions): GooPoint[][];
|
|
87
|
+
/**
|
|
88
|
+
* Squash and stretch that keeps the amount of stuff: stretched taller by
|
|
89
|
+
* `amount` (−1..1: negative squashes), the width gives way so the area stays
|
|
90
|
+
* (`keep: 'area'`, the default, for flat drawings) or the volume stays
|
|
91
|
+
* (`keep: 'volume'`, each side across shrinking by the square root).
|
|
92
|
+
*/
|
|
93
|
+
export declare function squashStretch(amount: number, options?: {
|
|
94
|
+
keep?: 'area' | 'volume';
|
|
95
|
+
}): {
|
|
96
|
+
sx: number;
|
|
97
|
+
sy: number;
|
|
98
|
+
};
|
|
99
|
+
/** Scale points about a point (default the origin): a blob squashed where it lands. */
|
|
100
|
+
export declare function scalePoints(points: ReadonlyArray<GooPoint>, scale: {
|
|
101
|
+
sx: number;
|
|
102
|
+
sy: number;
|
|
103
|
+
}, about?: GooPoint): GooPoint[];
|