@algorisys/tinyfly 0.101.0 → 0.103.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 +17 -6
- package/bin/tinyfly.mjs +9 -3
- package/docs/DEPLOYMENT.md +2 -0
- package/docs/api-reference.md +61 -0
- package/docs/dance.md +150 -1
- package/docs/editor-guide.md +11 -4
- package/docs/examples.md +22 -1
- package/docs/getting-started.md +1 -1
- package/docs/gsap-compat.md +1 -1
- package/docs/llm-guide.md +38 -3
- package/docs/maps.md +2 -2
- package/docs/scene-3d.md +138 -6
- package/docs/teaching.md +1 -1
- package/docs/video-rendering.md +44 -1
- package/lib/addons/adapters.js +168 -123
- package/lib/addons/characters.js +5802 -5506
- package/lib/addons/scene-3d-webgl.js +30 -30
- package/lib/addons/scene-3d.js +650 -341
- 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 +14 -14
- package/lib/browser/tinyfly.js +5798 -5467
- package/lib/browser/tinyfly.umd.js +14 -14
- package/lib/engine/tinyfly-engine.js +1207 -1172
- package/lib/engine/tinyfly-engine.umd.cjs +2 -2
- package/lib/headless/headless.js +150 -6
- package/lib/types/adapters/canvas/framing.d.ts +27 -0
- package/lib/types/adapters/canvas/index.d.ts +1 -0
- package/lib/types/characters/capabilities.d.ts +1 -0
- package/lib/types/characters/character-script-3d.d.ts +34 -4
- package/lib/types/characters/dance-circle.d.ts +59 -0
- package/lib/types/characters/dance-contact.d.ts +52 -0
- package/lib/types/characters/human-dance.d.ts +86 -0
- package/lib/types/characters/index.d.ts +5 -1
- package/lib/types/characters/rig/reach.d.ts +6 -3
- package/lib/types/characters/staging-3d.d.ts +56 -0
- package/lib/types/engine/authoring/framing.d.ts +48 -0
- package/lib/types/engine/authoring/index.d.ts +1 -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 +1 -0
- package/lib/types/headless/node-audio.d.ts +19 -0
- package/lib/types/headless/node-video.d.ts +2 -0
- package/lib/types/headless/video-scene.d.ts +12 -0
- package/lib/types/scene-3d/index.d.ts +3 -0
- package/lib/types/scene-3d/lighting.d.ts +58 -0
- package/lib/types/scene-3d/resolve-scene.d.ts +5 -1
- package/lib/types/scene-3d/scene-3d-adapter.d.ts +2 -0
- package/lib/types/scene-3d/scene-types.d.ts +14 -2
- 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 +474 -23
- package/llms.txt +29 -29
- package/package.json +1 -1
- package/skills/tinyfly/SKILL.md +32 -1
- package/lib/types/characters/polyline.d.ts +0 -12
- package/lib/types/characters/sketch.d.ts +0 -54
- package/lib/types/compat/gsap/playhead-crossings.d.ts +0 -47
|
@@ -4,11 +4,13 @@ import { GAITS } from './gaits';
|
|
|
4
4
|
import { type HumanPoseName } from './species/human';
|
|
5
5
|
import { type HumanGagName } from './species/human-motion';
|
|
6
6
|
import { type GroundPoint } from './ground-path';
|
|
7
|
+
import { type HumanDanceName } from './human-dance';
|
|
7
8
|
/**
|
|
8
9
|
* Characters in world metres, for 3D scenes: a v2 character walks to a point
|
|
9
10
|
* or along a path through points, turning to face the way first, its gait's
|
|
10
11
|
* phase keyed with the distance so its feet stay planted; it faces things,
|
|
11
|
-
*
|
|
12
|
+
* spins full signed turns, dances native routines, strikes poses and plays
|
|
13
|
+
* gags. It writes the scene object's tracks: `x`,
|
|
12
14
|
* `z`, `rotateY`, its walk (`walk`, `walking`, `gait`, which the character
|
|
13
15
|
* object turns into the stepping pose as it draws) and pose fields.
|
|
14
16
|
*
|
|
@@ -23,11 +25,19 @@ import { type GroundPoint } from './ground-path';
|
|
|
23
25
|
* ```
|
|
24
26
|
*/
|
|
25
27
|
export interface CharacterBeat3D {
|
|
26
|
-
/** A gait
|
|
28
|
+
/** A gait, `face` (shortest turn), `spin` (signed/fractional turns), `dance`, `hold`, `pose`, `gag`, `place`, `say`, or `look`. */
|
|
27
29
|
do: string;
|
|
30
|
+
/** `spin`: signed revolutions, default 1. Positive turns toward +x. */
|
|
31
|
+
turns?: number;
|
|
32
|
+
/** `dance`: a native human routine. */
|
|
33
|
+
dance?: HumanDanceName;
|
|
34
|
+
/** `dance`: tempo, beats per minute (default the style's tempo). */
|
|
35
|
+
bpm?: number;
|
|
36
|
+
/** `dance`: length in beats; defaults to one routine, or for * bpm / 60000 when for is given. With both, beats are fitted into for ms. */
|
|
37
|
+
beats?: number;
|
|
28
38
|
/** When it starts, ms (default: when the beat before ends) */
|
|
29
39
|
at?: number;
|
|
30
|
-
/**
|
|
40
|
+
/** Positive finite duration, ms: move defaults to distance at gait pace, pose to 500, spin to 1000. face consumes it even without turning. */
|
|
31
41
|
for?: number;
|
|
32
42
|
/** A move: where to, [x, z] metres */
|
|
33
43
|
to?: GroundPoint;
|
|
@@ -41,11 +51,31 @@ export interface CharacterBeat3D {
|
|
|
41
51
|
pose?: HumanPoseName | Pose;
|
|
42
52
|
/** `gag`: a gag's name (`take`, `doubleTake`, `windUp`…) */
|
|
43
53
|
gag?: HumanGagName;
|
|
54
|
+
/** `say`: the line spoken, lip-synced, with a talking head; the beat lasts as long as the line (or `for`) */
|
|
55
|
+
say?: string;
|
|
56
|
+
/** `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 */
|
|
57
|
+
look?: GroundPoint | [number, number, number] | 'camera';
|
|
44
58
|
}
|
|
45
|
-
export declare const CHARACTER_BEAT_3D_FIELDS: readonly ["do", "at", "for", "to", "through", "toward", "speed", "pose", "gag"];
|
|
59
|
+
export declare const CHARACTER_BEAT_3D_FIELDS: readonly ["do", "at", "for", "to", "through", "toward", "speed", "pose", "gag", "say", "look", "turns", "dance", "bpm", "beats"];
|
|
60
|
+
/** How long a line takes to say, ms: by its length, never shorter than a beat. */
|
|
61
|
+
export declare const speechLength: (text: string) => number;
|
|
62
|
+
/**
|
|
63
|
+
* Where to turn the head and eyes to look at a point from a place and a
|
|
64
|
+
* heading: the pose fields `head.turn` (toward the character's left, +),
|
|
65
|
+
* `head.nod` (down, +), `lookX` and `lookY` (the eyes, −1..1). A point behind
|
|
66
|
+
* turns the head as far as it goes and the eyes the rest of the way.
|
|
67
|
+
*/
|
|
68
|
+
export declare function lookFields(from: {
|
|
69
|
+
x: number;
|
|
70
|
+
z: number;
|
|
71
|
+
heading: number;
|
|
72
|
+
eyeHeight: number;
|
|
73
|
+
}, at: [number, number, number]): Pose;
|
|
46
74
|
export interface CharacterScript3DOptions {
|
|
47
75
|
/** The scene's id: the tracks target `<scene>/<id>` */
|
|
48
76
|
scene: string;
|
|
77
|
+
/** Where the camera is, metres, for `look: 'camera'` (default [0, 1.6, 8]) */
|
|
78
|
+
camera?: [number, number, number];
|
|
49
79
|
/** Where it was placed, [x, z] metres (its object's position) */
|
|
50
80
|
position?: GroundPoint;
|
|
51
81
|
/** Which way it faces at first, degrees (its object's rotation about y; 0 faces +z) */
|
|
@@ -0,0 +1,59 @@
|
|
|
1
|
+
import { type Character } from './character';
|
|
2
|
+
import { type DancePartner } from './dance-contact';
|
|
3
|
+
import { type HumanDanceName, type HumanDanceStyle } from './human-dance';
|
|
4
|
+
import type { Pose } from './rig/body-plan';
|
|
5
|
+
import type { GroundPoint } from './ground-path';
|
|
6
|
+
import type { Track } from '../engine/types';
|
|
7
|
+
export interface DanceCircleOptions {
|
|
8
|
+
/** Ground center [x,z], default [0,0]. */
|
|
9
|
+
center?: GroundPoint;
|
|
10
|
+
/** Positive radius in the same units as character height. */
|
|
11
|
+
radius: number;
|
|
12
|
+
/** Positive integer member count, default 8 for direct sampling; must match targets when baking. */
|
|
13
|
+
count?: number;
|
|
14
|
+
/** Beats per revolution, positive; default 32. */
|
|
15
|
+
beatsPerTurn?: number;
|
|
16
|
+
/** Initial angle in degrees: 0 places the first dancer along +z. */
|
|
17
|
+
angle?: number;
|
|
18
|
+
/** Clockwise viewed from above (+1, default), or counterclockwise (-1). */
|
|
19
|
+
direction?: 1 | -1;
|
|
20
|
+
/** Default inward; numeric heading in degrees (0 faces +z, 90 faces +x). */
|
|
21
|
+
facing?: 'inward' | 'outward' | 'tangent' | number;
|
|
22
|
+
/** Extra signed/fractional body revolutions per orbit, independent of travel. Default 0. */
|
|
23
|
+
spins?: number;
|
|
24
|
+
/** Local routine, default garba. */
|
|
25
|
+
style?: HumanDanceName | HumanDanceStyle;
|
|
26
|
+
/** Body used for contact geometry, default a human of height 1.7. Match the rendered build. */
|
|
27
|
+
character?: Character;
|
|
28
|
+
/** Base pose; formation heading overrides turn. Use the same base when rendering baked tracks. */
|
|
29
|
+
pose?: Pose;
|
|
30
|
+
/** Lock each support toe during its stance, then release smoothly. Default true. */
|
|
31
|
+
plantFeet?: boolean;
|
|
32
|
+
}
|
|
33
|
+
export interface DanceCircleMember extends DancePartner {
|
|
34
|
+
/** World heading in degrees, also included in pose.turn as quarter-turns. */
|
|
35
|
+
heading: number;
|
|
36
|
+
strike: number;
|
|
37
|
+
/** True only for a reachable plant at full stance weight; false during release or with planting disabled. */
|
|
38
|
+
planted: boolean;
|
|
39
|
+
}
|
|
40
|
+
/**
|
|
41
|
+
* A deterministic circle formation: world x/z travel, body heading and the
|
|
42
|
+
* local dance have separate phases. Sample by absolute beat, in any order.
|
|
43
|
+
* All placement units match the character's height (default 1.7 metres).
|
|
44
|
+
*/
|
|
45
|
+
export declare function danceCircleAt(beat: number, options: DanceCircleOptions): DanceCircleMember[];
|
|
46
|
+
/**
|
|
47
|
+
* Bake a formation into ordinary scene tracks. With zero roll, heading uses
|
|
48
|
+
* rotateY; rolled poses keep heading in turn and set rotateY to zero so yaw
|
|
49
|
+
* precedes roll and grounding exactly as in direct sampling.
|
|
50
|
+
* Requires beats; bpm defaults to 120 (independent of style), start to 0 ms
|
|
51
|
+
* and samplesPerBeat to 16. Member count comes from targets.length. Keys are
|
|
52
|
+
* linear; unchanged base/rest pose fields are omitted, placement is retained.
|
|
53
|
+
*/
|
|
54
|
+
export declare function danceCircleTracks(targets: string[], options: DanceCircleOptions & {
|
|
55
|
+
bpm?: number;
|
|
56
|
+
beats: number;
|
|
57
|
+
start?: number;
|
|
58
|
+
samplesPerBeat?: number;
|
|
59
|
+
}): Track[];
|
|
@@ -0,0 +1,52 @@
|
|
|
1
|
+
import type { Character } from './character';
|
|
2
|
+
import type { Pose, Vec3 } from './rig/body-plan';
|
|
3
|
+
/** Position and height use the same units (pixels in 2D, metres in a 3D scene). */
|
|
4
|
+
export interface DancePartner {
|
|
5
|
+
character: Character;
|
|
6
|
+
pose: Pose;
|
|
7
|
+
position: Vec3;
|
|
8
|
+
}
|
|
9
|
+
/**
|
|
10
|
+
* A joint in world space, with pose.turn (quarter-turns), roll, ground contact
|
|
11
|
+
* and position applied. Scene object rotations are not read. Index 2 is the
|
|
12
|
+
* wrist/ankle, and leg index 3 is the toe.
|
|
13
|
+
*/
|
|
14
|
+
export declare function danceJoint(partner: DancePartner, chain: string, joint: number): Vec3;
|
|
15
|
+
export interface DanceFootPlant extends DancePartner {
|
|
16
|
+
/** Joint error is less than 0.002 times the character height. */
|
|
17
|
+
reached: boolean;
|
|
18
|
+
}
|
|
19
|
+
/**
|
|
20
|
+
* Keep one ankle or toe at a world point while the body travels or turns.
|
|
21
|
+
* Apply the returned position as well as the pose: its y correction carries
|
|
22
|
+
* weight onto the supporting leg. An unreachable target is reported, never
|
|
23
|
+
* hidden by translating the body sideways.
|
|
24
|
+
*/
|
|
25
|
+
export declare function plantDanceFoot(partner: DancePartner, side: 'left' | 'right', target: Vec3, point?: 'ankle' | 'toe'): DanceFootPlant;
|
|
26
|
+
export interface DandiyaStick {
|
|
27
|
+
grip: Vec3;
|
|
28
|
+
tip: Vec3;
|
|
29
|
+
}
|
|
30
|
+
export interface DandiyaMeeting {
|
|
31
|
+
/** Solved poses for the two partners; positions are unchanged. */
|
|
32
|
+
a: Pose;
|
|
33
|
+
b: Pose;
|
|
34
|
+
sticks: [DandiyaStick, DandiyaStick];
|
|
35
|
+
point: Vec3;
|
|
36
|
+
/** Both tips are within 0.002 times the shorter height of point. */
|
|
37
|
+
reached: boolean;
|
|
38
|
+
}
|
|
39
|
+
/**
|
|
40
|
+
* Both sticks reach one shared 3D strike point. Stick length defaults to
|
|
41
|
+
* 0.22 of the shorter dancer's height; the point defaults to chest height
|
|
42
|
+
* between them. Draw the returned grip→tip segments with each arm's depth.
|
|
43
|
+
* Call on strike frames, or blend its poses with recovery poses between hits.
|
|
44
|
+
* Both selected hands default to right and use the hold shape. Inspect
|
|
45
|
+
* reached before applying a solve: unreachable tips are not snapped to point.
|
|
46
|
+
*/
|
|
47
|
+
export declare function meetDandiya(a: DancePartner, b: DancePartner, options?: {
|
|
48
|
+
sideA?: 'left' | 'right';
|
|
49
|
+
sideB?: 'left' | 'right';
|
|
50
|
+
point?: Vec3;
|
|
51
|
+
length?: number;
|
|
52
|
+
}): DandiyaMeeting;
|
|
@@ -0,0 +1,86 @@
|
|
|
1
|
+
import type { Pose } from './rig/body-plan';
|
|
2
|
+
import type { Track } from '../engine/types';
|
|
3
|
+
/**
|
|
4
|
+
* Native, body-local dance keys. Heading belongs to the caller, not the clip.
|
|
5
|
+
* Foot plants assume left/right alternation each integer beat, starting left,
|
|
6
|
+
* with stance through 0.6 of the beat. Custom footwork that changes that
|
|
7
|
+
* pattern should use danceCircleAt with plantFeet: false and supply its own contacts.
|
|
8
|
+
*/
|
|
9
|
+
export interface HumanDanceStyle {
|
|
10
|
+
label: string;
|
|
11
|
+
bpm: number;
|
|
12
|
+
beats: number;
|
|
13
|
+
keys: Array<{
|
|
14
|
+
beat: number;
|
|
15
|
+
pose: Pose;
|
|
16
|
+
}>;
|
|
17
|
+
/** Claps or stick strikes, in beats from the start of the loop. */
|
|
18
|
+
strikes: number[];
|
|
19
|
+
}
|
|
20
|
+
export interface HumanDanceFrame {
|
|
21
|
+
pose: Pose;
|
|
22
|
+
/** Alternating support side and absolute integer planting beat; weight is 1 through phase 0.6, then fades to 0. */
|
|
23
|
+
contact: {
|
|
24
|
+
side: 'left' | 'right';
|
|
25
|
+
start: number;
|
|
26
|
+
weight: number;
|
|
27
|
+
};
|
|
28
|
+
/** 1 on a strike, fading to 0 a quarter beat either side. */
|
|
29
|
+
strike: number;
|
|
30
|
+
}
|
|
31
|
+
/** Simple stylised routines, editable as JSON; not a motion-capture recording. */
|
|
32
|
+
export declare const HUMAN_DANCES: {
|
|
33
|
+
garba: {
|
|
34
|
+
label: string;
|
|
35
|
+
bpm: number;
|
|
36
|
+
beats: number;
|
|
37
|
+
strikes: number[];
|
|
38
|
+
keys: {
|
|
39
|
+
beat: number;
|
|
40
|
+
pose: Pose;
|
|
41
|
+
}[];
|
|
42
|
+
};
|
|
43
|
+
garbaThreeClap: {
|
|
44
|
+
label: string;
|
|
45
|
+
bpm: number;
|
|
46
|
+
beats: number;
|
|
47
|
+
strikes: number[];
|
|
48
|
+
keys: {
|
|
49
|
+
beat: number;
|
|
50
|
+
pose: Pose;
|
|
51
|
+
}[];
|
|
52
|
+
};
|
|
53
|
+
dandiya: {
|
|
54
|
+
label: string;
|
|
55
|
+
bpm: number;
|
|
56
|
+
beats: number;
|
|
57
|
+
strikes: number[];
|
|
58
|
+
keys: {
|
|
59
|
+
beat: number;
|
|
60
|
+
pose: Pose;
|
|
61
|
+
}[];
|
|
62
|
+
};
|
|
63
|
+
};
|
|
64
|
+
export type HumanDanceName = keyof typeof HUMAN_DANCES;
|
|
65
|
+
/** Random-access evaluation: turning never changes the authored local limb motion. */
|
|
66
|
+
export declare function humanDanceFrame(style: HumanDanceName | HumanDanceStyle, beat: number, base?: Pose): HumanDanceFrame;
|
|
67
|
+
export interface HumanDanceTrackOptions {
|
|
68
|
+
/** A native name or custom JSON routine. */
|
|
69
|
+
style: HumanDanceName | HumanDanceStyle;
|
|
70
|
+
/** Beats per minute; default the style's tempo. Positive and finite. */
|
|
71
|
+
bpm?: number;
|
|
72
|
+
/** Length from beat 0; default one routine. Positive and finite. */
|
|
73
|
+
beats?: number;
|
|
74
|
+
/** Start time in milliseconds, default 0; finite. */
|
|
75
|
+
start?: number;
|
|
76
|
+
/** Base pose, default HUMAN_REST; use the same pose on the rendered target. */
|
|
77
|
+
pose?: Pose;
|
|
78
|
+
/** Sampling density, default 16; positive and finite. */
|
|
79
|
+
samplesPerBeat?: number;
|
|
80
|
+
}
|
|
81
|
+
/**
|
|
82
|
+
* Ordinary linear JSON pose tracks, including hands; view/roll remain
|
|
83
|
+
* independently animated. Unchanged base/rest fields are omitted. Between
|
|
84
|
+
* samples, linear playback approximates the smoothly evaluated frame.
|
|
85
|
+
*/
|
|
86
|
+
export declare function humanDanceTracks(target: string, options: HumanDanceTrackOptions): Track[];
|
|
@@ -6,12 +6,16 @@
|
|
|
6
6
|
*/
|
|
7
7
|
export * from './stick-figure';
|
|
8
8
|
export * from './dance';
|
|
9
|
+
export * from './human-dance';
|
|
10
|
+
export * from './dance-circle';
|
|
11
|
+
export * from './dance-contact';
|
|
9
12
|
export * from './gaits';
|
|
10
13
|
export * from './acrobatics';
|
|
11
14
|
export { stickToHuman } from './stick-to-human';
|
|
12
15
|
export { skeletonInView, solvePlanSpace, stagePlanSpace, type ViewProjection, type PlanSpace, type StagedSpace } from './rig/skeleton';
|
|
13
16
|
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';
|
|
17
|
+
export { characterScript3D, checkCharacterBeats3D, lookFields, speechLength, CHARACTER_GAIT_SPEEDS, CHARACTER_BEAT_3D_FIELDS, type CharacterBeat3D, type CharacterScript3DOptions, type CharacterScript3DResult } from './character-script-3d';
|
|
18
|
+
export { characterLookAtTracks, objectPositionAt, stageSpots, type LookAtTracksOptions, type StageSpotsOptions } from './staging-3d';
|
|
15
19
|
export { type GroundPoint } from './ground-path';
|
|
16
20
|
export * from '../adapters/canvas/sketch';
|
|
17
21
|
export * from '../adapters/canvas/camera';
|
|
@@ -1,11 +1,14 @@
|
|
|
1
1
|
import type { BodyPlan, Pose, Vec3 } from './body-plan';
|
|
2
2
|
export interface ReachOptions {
|
|
3
|
-
/**
|
|
3
|
+
/** Character height in the same units as target (pixels or scene metres). */
|
|
4
4
|
height: number;
|
|
5
5
|
}
|
|
6
6
|
/**
|
|
7
7
|
* The pose with chain `chainId` reaching for `target`, a point in the
|
|
8
|
-
* character's 3D space in
|
|
9
|
-
*
|
|
8
|
+
* character's unplaced 3D space, in the same units as height (+x its left,
|
|
9
|
+
* +y up, +z forward). Body turn, roll, lift and grounding are excluded from
|
|
10
|
+
* the solve. The chain must hang down at rest (arms, legs). Authored bone
|
|
11
|
+
* yaw, including human hip turn-out, is retained; reaching the existing
|
|
12
|
+
* endpoint returns the original pose, including a straight limb at full reach.
|
|
10
13
|
*/
|
|
11
14
|
export declare function reachPose(plan: BodyPlan, pose: Pose, chainId: string, target: Vec3, options: ReachOptions): Pose;
|
|
@@ -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,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,40 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* A sound mix on plain samples: a music bed, narration, sound effects at
|
|
3
|
+
* times, each with a gain and fades, the music ducked under the voice, all
|
|
4
|
+
* summed into one track for the video. Pure (no Node, no DOM); `renderMix`
|
|
5
|
+
* decodes files into it and writes the WAV.
|
|
6
|
+
*/
|
|
7
|
+
export interface MixLayer {
|
|
8
|
+
/** A name other layers' `duck` can point at */
|
|
9
|
+
id?: string;
|
|
10
|
+
/** Mono samples at the mix's sample rate */
|
|
11
|
+
samples: Float32Array;
|
|
12
|
+
/** When it starts, ms (default 0); with `at`, where each copy goes instead */
|
|
13
|
+
start?: number;
|
|
14
|
+
/** A sound effect: a copy at each of these times, ms */
|
|
15
|
+
at?: number[];
|
|
16
|
+
/** Volume, 1 as recorded (default 1) */
|
|
17
|
+
gain?: number;
|
|
18
|
+
/** Fades, ms (default none) */
|
|
19
|
+
fadeIn?: number;
|
|
20
|
+
fadeOut?: number;
|
|
21
|
+
/** Repeat the samples to the end of the mix (a bed shorter than the film) */
|
|
22
|
+
loop?: boolean;
|
|
23
|
+
/** Make way for another layer: while `under` sounds, drop to `1 − amount` (default 0.7 of the way down) */
|
|
24
|
+
duck?: {
|
|
25
|
+
under: string;
|
|
26
|
+
amount?: number;
|
|
27
|
+
attack?: number;
|
|
28
|
+
release?: number;
|
|
29
|
+
threshold?: number;
|
|
30
|
+
};
|
|
31
|
+
}
|
|
32
|
+
export interface MixOptions {
|
|
33
|
+
sampleRate: number;
|
|
34
|
+
/** The mix's length, ms */
|
|
35
|
+
duration: number;
|
|
36
|
+
/** Volume of the whole mix (default 1); the result is soft-limited so peaks do not clip */
|
|
37
|
+
master?: number;
|
|
38
|
+
}
|
|
39
|
+
/** Sum the layers into one mono track `duration` ms long, ducked where asked, soft-limited. */
|
|
40
|
+
export declare function mixAudio(layers: ReadonlyArray<MixLayer>, options: MixOptions): Float32Array;
|
|
@@ -16,6 +16,8 @@ export interface FfmpegOptions {
|
|
|
16
16
|
crf?: number;
|
|
17
17
|
/** x264 preset (default `medium`) */
|
|
18
18
|
preset?: string;
|
|
19
|
+
/** `h264` (default): an MP4 for the web. `prores`: Apple ProRes 422 HQ in a .mov for editing elsewhere (10-bit, PCM audio) */
|
|
20
|
+
codec?: 'h264' | 'prores';
|
|
19
21
|
}
|
|
20
22
|
export declare function ffmpegArgs(options: FfmpegOptions): string[];
|
|
21
23
|
/** Decode any audio file ffmpeg reads to mono 32-bit float samples on stdout. */
|
|
@@ -36,8 +36,14 @@ export declare class FrameRenderer {
|
|
|
36
36
|
id: string;
|
|
37
37
|
time: number;
|
|
38
38
|
}>;
|
|
39
|
-
/**
|
|
39
|
+
/**
|
|
40
|
+
* Clear the context and draw the scene at `time` ms. With `supersample` the
|
|
41
|
+
* frame is drawn larger and scaled down; with `motionBlur` it is the average
|
|
42
|
+
* of several drawings across the shutter's time.
|
|
43
|
+
*/
|
|
40
44
|
render(ctx: CanvasRenderingContext2D, time: number, index?: number): void;
|
|
45
|
+
/** One drawing of the scene at `time` on a context, at an output scale. */
|
|
46
|
+
private paint;
|
|
41
47
|
/** Run scene code without letting its context changes leak into the rest. */
|
|
42
48
|
private drawIsolated;
|
|
43
49
|
}
|
|
@@ -11,4 +11,5 @@ export * from './narration-audio';
|
|
|
11
11
|
export * from './node-audio';
|
|
12
12
|
export * from './loop-check';
|
|
13
13
|
export * from './loop-audio';
|
|
14
|
+
export * from './audio-mix';
|
|
14
15
|
export { toSRT, toWebVTT, captionCuesFromTimeline, type CaptionCue } from '../engine/export/captions';
|
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
import { type NarrationLine, type NarrationOptions, type NarrationPlan } from '../engine/authoring/narration';
|
|
2
|
+
import { type MixLayer, type MixOptions } from './audio-mix';
|
|
2
3
|
/**
|
|
3
4
|
* Voice-over for a video: time the lines from their recorded clips and write
|
|
4
5
|
* the narration track.
|
|
@@ -59,6 +60,24 @@ export interface CutAudioToLoopOptions {
|
|
|
59
60
|
* shorter), and write the WAV to pass as the scene's `audio`.
|
|
60
61
|
*/
|
|
61
62
|
export declare function cutAudioToLoop(file: string, options: CutAudioToLoopOptions): Promise<string>;
|
|
63
|
+
export interface MixFileLayer extends Omit<MixLayer, 'samples'> {
|
|
64
|
+
/** The audio file, relative to `baseDir` (any format ffmpeg reads) */
|
|
65
|
+
file: string;
|
|
66
|
+
}
|
|
67
|
+
export interface RenderMixOptions extends Omit<MixOptions, 'sampleRate'> {
|
|
68
|
+
/** WAV file to write, relative to `baseDir` */
|
|
69
|
+
output: string;
|
|
70
|
+
baseDir?: string;
|
|
71
|
+
sampleRate?: number;
|
|
72
|
+
ffmpeg?: string;
|
|
73
|
+
}
|
|
74
|
+
/**
|
|
75
|
+
* A film's sound: decode a music bed, the narration and sound effects, mix
|
|
76
|
+
* them (gains, fades, effects at times, the music ducked under the voice)
|
|
77
|
+
* and write the WAV to pass as the scene's `audio`; ffmpeg muxes it with the
|
|
78
|
+
* picture. `mixAudio` is the pure step.
|
|
79
|
+
*/
|
|
80
|
+
export declare function renderMix(layers: MixFileLayer[], options: RenderMixOptions): Promise<string>;
|
|
62
81
|
/** Decode an audio file to mono float samples with ffmpeg. */
|
|
63
82
|
export declare function decodeAudio(file: string, options?: {
|
|
64
83
|
sampleRate?: number;
|
|
@@ -22,6 +22,8 @@ export interface RenderVideoOptions extends HeadlessOptions {
|
|
|
22
22
|
preset?: string;
|
|
23
23
|
/** ffmpeg executable (default `ffmpeg`) */
|
|
24
24
|
ffmpeg?: string;
|
|
25
|
+
/** `h264` (default) or `prores` (a .mov for editing) */
|
|
26
|
+
codec?: 'h264' | 'prores';
|
|
25
27
|
/** Called after each frame */
|
|
26
28
|
onProgress?: (done: number, total: number) => void;
|
|
27
29
|
}
|
|
@@ -67,6 +67,18 @@ export interface VideoScene {
|
|
|
67
67
|
* See `applyBloom`.
|
|
68
68
|
*/
|
|
69
69
|
bloom?: boolean | BloomOptions;
|
|
70
|
+
/**
|
|
71
|
+
* Motion blur by sub-frame sampling: each frame is the average of `samples`
|
|
72
|
+
* drawings spread over the shutter's open time (`shutter` as a share of the
|
|
73
|
+
* frame, default 0.5: a 180° shutter). Deterministic; `samples` times the
|
|
74
|
+
* work.
|
|
75
|
+
*/
|
|
76
|
+
motionBlur?: {
|
|
77
|
+
samples: number;
|
|
78
|
+
shutter?: number;
|
|
79
|
+
};
|
|
80
|
+
/** Anti-aliasing by supersampling: draw at this many times the size and scale down (2 is plenty; 4× the work) */
|
|
81
|
+
supersample?: number;
|
|
70
82
|
/** Soundtrack to mux into the video, relative to the scene file */
|
|
71
83
|
audio?: string;
|
|
72
84
|
/** Font files to register before drawing, by family, relative to the scene file */
|
|
@@ -19,3 +19,6 @@ export { MeshBuilder, meshEdges, type Mesh, type MeshEdge } from './geometry/mes
|
|
|
19
19
|
export { extrudeMesh, type ExtrudeOptions } from './geometry/extrude';
|
|
20
20
|
export { triangulate, signedArea, pointInPolygon, type Point2 } from './geometry/triangulate';
|
|
21
21
|
export { penroseTriangle3D, type PenroseTriangle3DOptions } from './impossible-3d';
|
|
22
|
+
export { SoftwareRenderer, drawResolvedSceneWithDepth, rasterizeResolvedScene, type RasterImage, type RasterOptions } from './software-renderer';
|
|
23
|
+
export { shotAt, checkShots, snapShotsToBeats, shotTracks, shotMarkers, transitionAt, withActiveCamera, cameraPoseAt, cameraMoveTracks, cameraFollowTracks, cameraHandheldTracks, type Shot, type ShotTransition, type ActiveTransition, type CameraPose, type CameraMoveOptions, type CameraFollowOptions, type HandheldOptions } from './shots';
|
|
24
|
+
export { LIGHTING_PRESETS, lightingPreset, lightingTracks, ground, type LightingMood, type LightingPresetName, type LightingOptions, type LightingTrackOptions, type GroundOptions } from './lighting';
|
|
@@ -0,0 +1,58 @@
|
|
|
1
|
+
import type { Track } from '../engine/types';
|
|
2
|
+
import type { LightObject, MeshObject, Material3D, Scene3D, SkyGradient } from './scene-types';
|
|
3
|
+
/**
|
|
4
|
+
* Light for mood, as data: presets (day, dusk, night, a stage spotlight)
|
|
5
|
+
* that give a scene its lights, sky and fog in one go, tracks that take the
|
|
6
|
+
* lights from one mood to another over a span, and a ground to stand things
|
|
7
|
+
* on. Every preset uses the same light ids (`key`, `fill`, `sky`, `spot`),
|
|
8
|
+
* so a change of mood is a change of values, never of objects.
|
|
9
|
+
*/
|
|
10
|
+
export interface LightingMood {
|
|
11
|
+
/** The lights, with the ids `key`, `fill`, `sky` and `spot` (a spot only where the mood has one) */
|
|
12
|
+
lights: Array<Omit<LightObject, 'id'> & {
|
|
13
|
+
id: 'key' | 'fill' | 'sky' | 'spot';
|
|
14
|
+
}>;
|
|
15
|
+
background: SkyGradient;
|
|
16
|
+
fog: NonNullable<Scene3D['fog']>;
|
|
17
|
+
}
|
|
18
|
+
export declare const LIGHTING_PRESETS: Record<'day' | 'dusk' | 'night' | 'stage', LightingMood>;
|
|
19
|
+
export type LightingPresetName = keyof typeof LIGHTING_PRESETS;
|
|
20
|
+
export interface LightingOptions {
|
|
21
|
+
/** Put this before each light's id (default none): `set-key`, `set-fill`… */
|
|
22
|
+
prefix?: string;
|
|
23
|
+
}
|
|
24
|
+
/** A mood's lights as scene objects, with its sky and fog to spread into the scene. */
|
|
25
|
+
export declare function lightingPreset(name: LightingPresetName, options?: LightingOptions): {
|
|
26
|
+
objects: LightObject[];
|
|
27
|
+
background: SkyGradient;
|
|
28
|
+
fog: NonNullable<Scene3D['fog']>;
|
|
29
|
+
};
|
|
30
|
+
export interface LightingTrackOptions extends LightingOptions {
|
|
31
|
+
scene: string;
|
|
32
|
+
/** ms */
|
|
33
|
+
start: number;
|
|
34
|
+
end: number;
|
|
35
|
+
easing?: Track['keyframes'][number]['easing'];
|
|
36
|
+
}
|
|
37
|
+
/**
|
|
38
|
+
* Tracks that take a scene's lights from one mood to another over a span:
|
|
39
|
+
* each light's `color`, `intensity`, `position` and `target` keyed at the
|
|
40
|
+
* start and the end. A light one mood has and the other lacks fades out (or
|
|
41
|
+
* in). The scene must hold the preset's lights (see `lightingPreset`).
|
|
42
|
+
*/
|
|
43
|
+
export declare function lightingTracks(from: LightingPresetName, to: LightingPresetName, options: LightingTrackOptions): Track[];
|
|
44
|
+
export interface GroundOptions {
|
|
45
|
+
id?: string;
|
|
46
|
+
/** Metres across (default 24) */
|
|
47
|
+
size?: number;
|
|
48
|
+
color?: string;
|
|
49
|
+
/** Faces per side (default 24): more lets light pools and fog fall across it */
|
|
50
|
+
segments?: number;
|
|
51
|
+
/** Its height (default 0, the scene's ground) */
|
|
52
|
+
y?: number;
|
|
53
|
+
}
|
|
54
|
+
/** A ground to stand things on: a floor plane on layer −1 and its material, to spread into a scene. */
|
|
55
|
+
export declare function ground(options?: GroundOptions): {
|
|
56
|
+
objects: MeshObject[];
|
|
57
|
+
materials: Record<string, Material3D>;
|
|
58
|
+
};
|
|
@@ -58,6 +58,8 @@ export interface DrawTriangle {
|
|
|
58
58
|
screen: [ScreenPoint, ScreenPoint, ScreenPoint];
|
|
59
59
|
/** Distance in front of the camera, metres: what the draw order sorts by */
|
|
60
60
|
depth: number;
|
|
61
|
+
/** Each screen corner's distance in front of the camera, metres (a depth buffer interpolates these) */
|
|
62
|
+
depths: [number, number, number];
|
|
61
63
|
/** World centre of the face (lighting, fog) */
|
|
62
64
|
centroid: Vec3;
|
|
63
65
|
/** World face normal, unit, toward the viewer */
|
|
@@ -71,6 +73,8 @@ export interface DrawTriangle {
|
|
|
71
73
|
opacity: number;
|
|
72
74
|
/** Edges to ink on top of this triangle (silhouettes, creases, open rims), when it has an `ink` */
|
|
73
75
|
outline: Array<[ScreenPoint, ScreenPoint]>;
|
|
76
|
+
/** The ink edges' end depths, metres, in `outline`'s order */
|
|
77
|
+
outlineDepths: Array<[number, number]>;
|
|
74
78
|
/** The outline's look: the material's, with the object's `outlineWidth` and `outlineColor` over it */
|
|
75
79
|
ink?: {
|
|
76
80
|
width: number;
|
|
@@ -104,7 +108,7 @@ export interface ResolvedScene3D {
|
|
|
104
108
|
height: number;
|
|
105
109
|
/** ms: the moment drawn (for looks that move with time, such as a boiling pencil line) */
|
|
106
110
|
time: number;
|
|
107
|
-
background?:
|
|
111
|
+
background?: Scene3D['background'];
|
|
108
112
|
fog?: Scene3D['fog'];
|
|
109
113
|
camera: ResolvedCamera;
|
|
110
114
|
lights: ResolvedLight[];
|