@algorisys/tinyfly 0.70.2 → 0.74.1
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 +20 -8
- package/bin/tinyfly.mjs +95 -2
- package/lib/addons/adapters.js +31 -12
- package/lib/addons/characters.js +211 -0
- package/lib/addons/export.js +476 -440
- package/lib/browser/tinyfly.iife.js +4 -4
- package/lib/browser/tinyfly.js +1339 -1095
- package/lib/browser/tinyfly.umd.js +4 -4
- package/lib/engine/tinyfly-engine.js +313 -277
- package/lib/engine/tinyfly-engine.umd.cjs +2 -2
- package/lib/headless/headless.js +947 -0
- package/lib/types/adapters/canvas/canvas-adapter.d.ts +32 -2
- package/lib/types/browser/index.d.ts +3 -1
- package/lib/types/characters/index.d.ts +5 -0
- package/lib/types/characters/stick-figure.d.ts +174 -0
- package/lib/types/engine/authoring/index.d.ts +1 -0
- package/lib/types/engine/authoring/narration.d.ts +80 -0
- package/lib/types/engine/export/captions.d.ts +31 -0
- package/lib/types/engine/export/index.d.ts +1 -0
- package/lib/types/headless/ffmpeg-args.d.ts +28 -0
- package/lib/types/headless/frame-renderer.d.ts +45 -0
- package/lib/types/headless/index.d.ts +12 -0
- package/lib/types/headless/narration-audio.d.ts +13 -0
- package/lib/types/headless/node-audio.d.ts +46 -0
- package/lib/types/headless/node-video.d.ts +48 -0
- package/lib/types/headless/scene-captions.d.ts +4 -0
- package/lib/types/headless/video-scene.d.ts +57 -0
- package/package.json +19 -4
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import type { AnimationState } from '../../engine/types';
|
|
1
|
+
import type { AnimationState, AnimatableValue } from '../../engine/types';
|
|
2
2
|
/** Gradient stop definition */
|
|
3
3
|
export interface GradientStop {
|
|
4
4
|
offset: number;
|
|
@@ -108,8 +108,33 @@ export interface ImageTarget extends CanvasTargetBase {
|
|
|
108
108
|
/** Rounded-corner clip radius in px (default 0). */
|
|
109
109
|
borderRadius?: number;
|
|
110
110
|
}
|
|
111
|
+
/**
|
|
112
|
+
* Draws a custom target. The context is already translated to the target's
|
|
113
|
+
* `x`/`y` and has its opacity, transforms, fill, stroke and filter applied, so
|
|
114
|
+
* the function draws in local coordinates (0,0 to width,height). `time` is the
|
|
115
|
+
* timeline time in milliseconds of the state last applied.
|
|
116
|
+
*/
|
|
117
|
+
export type CustomDrawFunction = (ctx: CanvasRenderingContext2D, target: Readonly<CustomTarget>, time: number) => void;
|
|
118
|
+
/**
|
|
119
|
+
* Custom target: drawing is done by code instead of a built-in shape.
|
|
120
|
+
*
|
|
121
|
+
* The timeline stays plain data. It animates the base properties (x, y,
|
|
122
|
+
* opacity, rotate, …) as for any target, plus any value declared in `props`:
|
|
123
|
+
* a track whose property is a key of `props` writes into `props`, so the draw
|
|
124
|
+
* function reads `target.props.pose` rather than keyframes. Only keys declared
|
|
125
|
+
* in `props` are routed there, so every animated value is visible up front.
|
|
126
|
+
*/
|
|
127
|
+
export interface CustomTarget extends CanvasTargetBase {
|
|
128
|
+
type: 'custom';
|
|
129
|
+
/** Bounding box size, used for the transform pivot, clip insets and gradients */
|
|
130
|
+
width: number;
|
|
131
|
+
height: number;
|
|
132
|
+
draw: CustomDrawFunction;
|
|
133
|
+
/** Values the draw function reads, with their initial values */
|
|
134
|
+
props?: Record<string, AnimatableValue>;
|
|
135
|
+
}
|
|
111
136
|
/** Union of all canvas target types */
|
|
112
|
-
export type CanvasTarget = RectTarget | CircleTarget | TextTarget | LineTarget | PathTarget | ImageTarget;
|
|
137
|
+
export type CanvasTarget = RectTarget | CircleTarget | TextTarget | LineTarget | PathTarget | ImageTarget | CustomTarget;
|
|
113
138
|
/**
|
|
114
139
|
* CanvasAdapter manages canvas drawing objects and applies
|
|
115
140
|
* animation state to them. Call render() in your animation loop
|
|
@@ -120,6 +145,7 @@ export declare class CanvasAdapter {
|
|
|
120
145
|
private targetOrder;
|
|
121
146
|
private animationOffsets;
|
|
122
147
|
private aliases;
|
|
148
|
+
private time;
|
|
123
149
|
/**
|
|
124
150
|
* Register a canvas drawing target.
|
|
125
151
|
* @param id - The ID to register the target under
|
|
@@ -207,6 +233,10 @@ export declare class CanvasAdapter {
|
|
|
207
233
|
* Render an image.
|
|
208
234
|
*/
|
|
209
235
|
private renderImage;
|
|
236
|
+
/**
|
|
237
|
+
* Render a custom target by calling its draw function in local coordinates.
|
|
238
|
+
*/
|
|
239
|
+
private renderCustom;
|
|
210
240
|
/**
|
|
211
241
|
* Transform pivot X: the target's centre, shifted by `originX` across its
|
|
212
242
|
* own width. `originX: 0` pivots on the left edge, 100 on the right.
|
|
@@ -9,7 +9,8 @@
|
|
|
9
9
|
*
|
|
10
10
|
* The top-level `to` / `from` / `fromTo` / `set` / `timeline` are the live
|
|
11
11
|
* facade (they play on real elements). The engine, the player, the compiling
|
|
12
|
-
* `tf` facade, drivers
|
|
12
|
+
* `tf` facade, drivers, interaction and the `characters` stick figure are all
|
|
13
|
+
* available on the same global.
|
|
13
14
|
*
|
|
14
15
|
* Teaching embeds are included too: step controls (`createControls`), declarative
|
|
15
16
|
* mounting (`mountAll`, or automatically when the script tag has
|
|
@@ -44,6 +45,7 @@ export * from '../engine';
|
|
|
44
45
|
export * from '../player';
|
|
45
46
|
export * from '../drivers';
|
|
46
47
|
export * from '../interaction';
|
|
48
|
+
export * from '../characters';
|
|
47
49
|
export { tf, live, createLive, Stage, LiveTimeline, CompatTimeline, quickPlay, mapEase, CustomEase, CustomBounce, CustomWiggle, } from '../compat/gsap';
|
|
48
50
|
export { createControls, DEFAULT_LABELS } from '../embed/controls';
|
|
49
51
|
export type { Controls, ControlsOptions, ControlLabels, FullscreenControl } from '../embed/controls';
|
|
@@ -0,0 +1,174 @@
|
|
|
1
|
+
import type { CustomTarget } from '../adapters/canvas';
|
|
2
|
+
import type { EasingType, Track } from '../engine/types';
|
|
3
|
+
/**
|
|
4
|
+
* A stick-figure rig: a pose is a handful of numbers, so poses blend, walk
|
|
5
|
+
* cycles are functions of a phase, and every joint can be a timeline track.
|
|
6
|
+
*
|
|
7
|
+
* The figure is drawn facing the viewer with its feet at (0, 0) and its head
|
|
8
|
+
* up (negative y). Limb angles are degrees from hanging straight down;
|
|
9
|
+
* positive raises a limb outward, away from the body. Drawing needs only a
|
|
10
|
+
* Canvas 2D context, so it works in a browser, a Worker or Node.
|
|
11
|
+
*/
|
|
12
|
+
/** Every value is a number, so any two poses blend. */
|
|
13
|
+
export interface StickPose {
|
|
14
|
+
/** Upper-body tilt about the hips, degrees (+ leans to the figure's right, +x) */
|
|
15
|
+
lean: number;
|
|
16
|
+
/** Head tilt, degrees */
|
|
17
|
+
headTilt: number;
|
|
18
|
+
/** Upper arms: 0 hangs down, 90 is straight out, 180 straight up */
|
|
19
|
+
leftShoulder: number;
|
|
20
|
+
rightShoulder: number;
|
|
21
|
+
/** Elbow bend, added to the upper arm's angle (negative bends inward) */
|
|
22
|
+
leftElbow: number;
|
|
23
|
+
rightElbow: number;
|
|
24
|
+
/** Thighs: 0 is straight down, positive spreads outward */
|
|
25
|
+
leftHip: number;
|
|
26
|
+
rightHip: number;
|
|
27
|
+
/** Knee bend: positive swings the shin back toward the centre */
|
|
28
|
+
leftKnee: number;
|
|
29
|
+
rightKnee: number;
|
|
30
|
+
/** 0 closed, 1 wide open */
|
|
31
|
+
mouth: number;
|
|
32
|
+
/** -1 frown, 0 flat, 1 smile; with an open mouth, sets a grin (+) or a wail (-) */
|
|
33
|
+
smile: number;
|
|
34
|
+
/** Mouth width: 1 normal, 0.5 pursed, 1.5 wide */
|
|
35
|
+
mouthWidth: number;
|
|
36
|
+
/** 0 open eyes, 1 closed; applied on top of the eye openness, for blinking */
|
|
37
|
+
blink: number;
|
|
38
|
+
/** Eye openness: 0 shut, 1 normal, 1.6 wide (above about 1.2 the whites show) */
|
|
39
|
+
leftEye: number;
|
|
40
|
+
rightEye: number;
|
|
41
|
+
/** Eyebrow height: -1 lowered, 0 rest, 1 raised */
|
|
42
|
+
leftBrow: number;
|
|
43
|
+
rightBrow: number;
|
|
44
|
+
/** Eyebrow slant: -1 angry (inner ends down), 1 worried (inner ends up) */
|
|
45
|
+
browTilt: number;
|
|
46
|
+
/** Where the eyes look: -1..1 across (+ is the way the figure faces) and down (+) */
|
|
47
|
+
lookX: number;
|
|
48
|
+
lookY: number;
|
|
49
|
+
}
|
|
50
|
+
export declare const REST_POSE: StickPose;
|
|
51
|
+
/** A full pose from the fields that differ from rest. */
|
|
52
|
+
export declare function pose(changes: Partial<StickPose>): StickPose;
|
|
53
|
+
/** The face fields of a pose: what an expression sets. */
|
|
54
|
+
export type Expression = Pick<StickPose, 'mouth' | 'smile' | 'mouthWidth' | 'leftEye' | 'rightEye' | 'leftBrow' | 'rightBrow' | 'browTilt' | 'lookX' | 'lookY'>;
|
|
55
|
+
/**
|
|
56
|
+
* Ready-made faces. Each sets every face field, so applying one replaces the
|
|
57
|
+
* whole face, and any two blend. Combine with a body pose via {@link withExpression}.
|
|
58
|
+
*/
|
|
59
|
+
export declare const EXPRESSIONS: {
|
|
60
|
+
neutral: Expression;
|
|
61
|
+
happy: Expression;
|
|
62
|
+
joyful: Expression;
|
|
63
|
+
sad: Expression;
|
|
64
|
+
crying: Expression;
|
|
65
|
+
surprised: Expression;
|
|
66
|
+
shocked: Expression;
|
|
67
|
+
angry: Expression;
|
|
68
|
+
furious: Expression;
|
|
69
|
+
worried: Expression;
|
|
70
|
+
scared: Expression;
|
|
71
|
+
confused: Expression;
|
|
72
|
+
skeptical: Expression;
|
|
73
|
+
thinking: Expression;
|
|
74
|
+
sleepy: Expression;
|
|
75
|
+
disgusted: Expression;
|
|
76
|
+
smug: Expression;
|
|
77
|
+
wink: Expression;
|
|
78
|
+
};
|
|
79
|
+
export type ExpressionName = keyof typeof EXPRESSIONS;
|
|
80
|
+
/** `base` with its face replaced by an expression (a name, or face fields to change). */
|
|
81
|
+
export declare function withExpression(base: StickPose, expression: ExpressionName | Partial<Expression>): StickPose;
|
|
82
|
+
/** Ready-made poses. Blend between them, or override single joints. */
|
|
83
|
+
export declare const POSES: {
|
|
84
|
+
rest: StickPose;
|
|
85
|
+
wave: StickPose;
|
|
86
|
+
cheer: StickPose;
|
|
87
|
+
shrug: StickPose;
|
|
88
|
+
point: StickPose;
|
|
89
|
+
think: StickPose;
|
|
90
|
+
handsOnHips: StickPose;
|
|
91
|
+
sad: StickPose;
|
|
92
|
+
surprised: StickPose;
|
|
93
|
+
};
|
|
94
|
+
export type PoseName = keyof typeof POSES;
|
|
95
|
+
/** Linear blend: `t` 0 is `from`, 1 is `to`. */
|
|
96
|
+
export declare function blendPose(from: StickPose, to: StickPose, t: number): StickPose;
|
|
97
|
+
/**
|
|
98
|
+
* A walking stride at `phase` (in strides: 0 → 1 is one full cycle), built on
|
|
99
|
+
* `base`: the legs walk, hanging arms swing, and raised arms (a wave, a point)
|
|
100
|
+
* and the face keep `base`'s pose. `stride` scales the swing.
|
|
101
|
+
*
|
|
102
|
+
* Limb angles are measured outward from each side, so the same angle moves the
|
|
103
|
+
* left limb one way on screen and the right limb the other. Giving both hips the
|
|
104
|
+
* same angle therefore puts one foot forward (+x, the way the figure faces) and
|
|
105
|
+
* the other back, evenly about the vertical, which is what a stride looks like.
|
|
106
|
+
*/
|
|
107
|
+
export declare function walkPose(phase: number, base?: StickPose, stride?: number): StickPose;
|
|
108
|
+
/**
|
|
109
|
+
* Ground covered by one full walk cycle (two steps) for a figure `height` px
|
|
110
|
+
* tall: each step the foot sweeps from one side of the hip to the other.
|
|
111
|
+
* Set the walk phase to distance / strideLength so the feet stay planted.
|
|
112
|
+
*/
|
|
113
|
+
export declare function strideLength(height: number, stride?: number): number;
|
|
114
|
+
/** How open a talking mouth is at `time` ms: a deterministic chatter, 0..1. */
|
|
115
|
+
export declare function talkingMouth(time: number): number;
|
|
116
|
+
/** How the figure looks, apart from its pose. */
|
|
117
|
+
export interface StickStyle {
|
|
118
|
+
/** Feet to top of head, px (default 300) */
|
|
119
|
+
height?: number;
|
|
120
|
+
/** Line colour (default slate) */
|
|
121
|
+
color?: string;
|
|
122
|
+
/** Line width (default 2.5% of the height) */
|
|
123
|
+
lineWidth?: number;
|
|
124
|
+
/** Head fill; `none` leaves it see-through (default white) */
|
|
125
|
+
headFill?: string;
|
|
126
|
+
/** 1 faces right, -1 faces left: mirrors the figure and turns the eyes */
|
|
127
|
+
facing?: number;
|
|
128
|
+
/** Name tag drawn over the head */
|
|
129
|
+
label?: string;
|
|
130
|
+
/** Name tag font (default bold, 11% of the height, sans-serif) */
|
|
131
|
+
labelFont?: string;
|
|
132
|
+
}
|
|
133
|
+
/** Draw a figure with its feet at (0, 0). */
|
|
134
|
+
export declare function drawStickFigure(ctx: CanvasRenderingContext2D, figure: StickPose, style?: StickStyle): void;
|
|
135
|
+
/** Values a stick-figure target's tracks can animate, besides x/y/opacity/…. */
|
|
136
|
+
export interface StickFigureProps extends StickPose {
|
|
137
|
+
/** Walk cycle phase, in strides (animate it 0 → n for n strides) */
|
|
138
|
+
walk: number;
|
|
139
|
+
/** How much of the walk cycle is applied, 0..1 (0 standing) */
|
|
140
|
+
walking: number;
|
|
141
|
+
/** How much the mouth chatters, 0..1 */
|
|
142
|
+
talk: number;
|
|
143
|
+
}
|
|
144
|
+
export interface StickFigureTargetOptions {
|
|
145
|
+
/** Where the feet stand */
|
|
146
|
+
x: number;
|
|
147
|
+
y: number;
|
|
148
|
+
/** Starting pose (default rest) */
|
|
149
|
+
pose?: Partial<StickPose>;
|
|
150
|
+
style?: StickStyle;
|
|
151
|
+
}
|
|
152
|
+
/**
|
|
153
|
+
* A `custom` canvas target that draws a stick figure. Its props are the pose
|
|
154
|
+
* plus `walk`, `walking` and `talk`, so the timeline can pose, walk and voice
|
|
155
|
+
* it. `x`/`y` here are the feet; the target's own box sits above them.
|
|
156
|
+
*/
|
|
157
|
+
export declare function stickFigureTarget(options: StickFigureTargetOptions): CustomTarget;
|
|
158
|
+
export interface PoseKey {
|
|
159
|
+
time: number;
|
|
160
|
+
/** The pose here: a name, or joints to change from the previous key (default: no change) */
|
|
161
|
+
pose?: PoseName | Partial<StickPose>;
|
|
162
|
+
/** The face here, applied over the pose: a name, or face fields to change */
|
|
163
|
+
expression?: ExpressionName | Partial<Expression>;
|
|
164
|
+
/** Easing into this key */
|
|
165
|
+
easing?: EasingType;
|
|
166
|
+
}
|
|
167
|
+
/**
|
|
168
|
+
* Keyframe tracks that move `target` through a sequence of poses. Each key is
|
|
169
|
+
* a named pose or changes from the previous key (the first builds on rest),
|
|
170
|
+
* optionally with an expression over it.
|
|
171
|
+
* Only joints that leave rest in some key get a track, so the JSON stays
|
|
172
|
+
* small; the others keep the target's own pose.
|
|
173
|
+
*/
|
|
174
|
+
export declare function poseTracks(target: string, keys: PoseKey[]): Track[];
|
|
@@ -0,0 +1,80 @@
|
|
|
1
|
+
import type { TimelineMarker } from '../types';
|
|
2
|
+
/**
|
|
3
|
+
* Narration timing: lay spoken lines out on a timeline.
|
|
4
|
+
*
|
|
5
|
+
* A narrated video is timed by its voice-over. Each line is a recorded (or
|
|
6
|
+
* synthesised) clip of known length; scenes group lines and add a short lead
|
|
7
|
+
* before the first line, a gap between lines and a tail after the last. This
|
|
8
|
+
* module turns those clip lengths into absolute start/end times, so drawing,
|
|
9
|
+
* markers and captions all follow the audio. It is pure: same lines in, same
|
|
10
|
+
* times out.
|
|
11
|
+
*/
|
|
12
|
+
/** One spoken line. */
|
|
13
|
+
export interface NarrationLine {
|
|
14
|
+
/** The text shown as its caption */
|
|
15
|
+
text: string;
|
|
16
|
+
/** Length of the spoken clip, in milliseconds */
|
|
17
|
+
duration: number;
|
|
18
|
+
/** Marker id for the line (default `s{scene}-l{line}`, both 0-based) */
|
|
19
|
+
id?: string;
|
|
20
|
+
}
|
|
21
|
+
/** A scene: consecutive lines that share one picture. */
|
|
22
|
+
export interface NarrationScene {
|
|
23
|
+
/** Scene id (default `s{scene}`) */
|
|
24
|
+
id?: string;
|
|
25
|
+
lines: NarrationLine[];
|
|
26
|
+
/** Extra hold after this scene's last line, added to the default tail, in ms */
|
|
27
|
+
tail?: number;
|
|
28
|
+
}
|
|
29
|
+
/** Pauses around the lines, in milliseconds. */
|
|
30
|
+
export interface NarrationOptions {
|
|
31
|
+
/** Silence before a scene's first line (default 350) */
|
|
32
|
+
lead?: number;
|
|
33
|
+
/** Silence between lines in a scene (default 300) */
|
|
34
|
+
gap?: number;
|
|
35
|
+
/** Silence after a scene's last line (default 550) */
|
|
36
|
+
tail?: number;
|
|
37
|
+
}
|
|
38
|
+
/** A line placed on the timeline. Times are absolute milliseconds. */
|
|
39
|
+
export interface NarrationCue {
|
|
40
|
+
id: string;
|
|
41
|
+
/** Index of the scene the line belongs to */
|
|
42
|
+
scene: number;
|
|
43
|
+
/** Index of the line within its scene */
|
|
44
|
+
line: number;
|
|
45
|
+
start: number;
|
|
46
|
+
end: number;
|
|
47
|
+
text: string;
|
|
48
|
+
}
|
|
49
|
+
/** A scene placed on the timeline. */
|
|
50
|
+
export interface NarrationSceneTiming {
|
|
51
|
+
id: string;
|
|
52
|
+
/** Absolute start, in ms */
|
|
53
|
+
start: number;
|
|
54
|
+
/** Scene length including lead, gaps and tail, in ms */
|
|
55
|
+
duration: number;
|
|
56
|
+
cues: NarrationCue[];
|
|
57
|
+
}
|
|
58
|
+
/** The whole narration laid out. */
|
|
59
|
+
export interface NarrationPlan {
|
|
60
|
+
/** Total length, in ms */
|
|
61
|
+
duration: number;
|
|
62
|
+
scenes: NarrationSceneTiming[];
|
|
63
|
+
/** Every line in order */
|
|
64
|
+
cues: NarrationCue[];
|
|
65
|
+
}
|
|
66
|
+
/**
|
|
67
|
+
* Lay the scenes' lines out end to end.
|
|
68
|
+
*
|
|
69
|
+
* Within a scene: lead, line 0, gap, line 1, …, last line, tail. Scenes follow
|
|
70
|
+
* each other with no extra space. The narration audio must be assembled with
|
|
71
|
+
* the same pauses for it to line up (or built from the returned cue times).
|
|
72
|
+
*/
|
|
73
|
+
export declare function planNarration(scenes: NarrationScene[], options?: NarrationOptions): NarrationPlan;
|
|
74
|
+
/**
|
|
75
|
+
* One marker per line, at its start, labelled with its text. Players step
|
|
76
|
+
* through them and show the label as the caption.
|
|
77
|
+
*/
|
|
78
|
+
export declare function narrationMarkers(plan: NarrationPlan): TimelineMarker[];
|
|
79
|
+
/** The scene playing at `time` (the last one at or past the end). */
|
|
80
|
+
export declare function narrationSceneAt(plan: NarrationPlan, time: number): NarrationSceneTiming | undefined;
|
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
import type { TimelineDefinition } from '../types';
|
|
2
|
+
/**
|
|
3
|
+
* Caption files: SubRip (`.srt`) and WebVTT (`.vtt`).
|
|
4
|
+
*
|
|
5
|
+
* A cue is a span of time and its text. Cues come either from a narration plan
|
|
6
|
+
* (`planNarration(...).cues`, which are already cue-shaped) or from a
|
|
7
|
+
* timeline's markers via {@link captionCuesFromTimeline}. Pure string output;
|
|
8
|
+
* no DOM.
|
|
9
|
+
*/
|
|
10
|
+
/** One caption. Times are milliseconds from the start. */
|
|
11
|
+
export interface CaptionCue {
|
|
12
|
+
/** Optional name, e.g. a narration cue's `s0-l1`; used to name stills */
|
|
13
|
+
id?: string;
|
|
14
|
+
start: number;
|
|
15
|
+
end: number;
|
|
16
|
+
text: string;
|
|
17
|
+
}
|
|
18
|
+
/** SubRip text: numbered cues with `00:00:01,250 --> 00:00:03,000` times. */
|
|
19
|
+
export declare function toSRT(cues: CaptionCue[]): string;
|
|
20
|
+
/** WebVTT text: a `WEBVTT` header, then cues with `00:00:01.250` times. */
|
|
21
|
+
export declare function toWebVTT(cues: CaptionCue[]): string;
|
|
22
|
+
export interface TimelineCaptionOptions {
|
|
23
|
+
/** Caption language to read from `captions`; falls back to each marker's label */
|
|
24
|
+
language?: string;
|
|
25
|
+
}
|
|
26
|
+
/**
|
|
27
|
+
* Cues from a timeline's markers: each marker's caption (or label) runs from
|
|
28
|
+
* its time until the next marker, and the last one until the end of the
|
|
29
|
+
* timeline. Markers with no text are skipped but still end the previous cue.
|
|
30
|
+
*/
|
|
31
|
+
export declare function captionCuesFromTimeline(definition: TimelineDefinition, options?: TimelineCaptionOptions): CaptionCue[];
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The ffmpeg command line for encoding raw frames into an MP4.
|
|
3
|
+
*
|
|
4
|
+
* Frames arrive on stdin as raw RGBA at a fixed rate; an optional audio file
|
|
5
|
+
* is muxed in and the output stops at the shorter of the two streams. Kept
|
|
6
|
+
* separate from the process handling so it can be tested as plain data.
|
|
7
|
+
*/
|
|
8
|
+
export interface FfmpegOptions {
|
|
9
|
+
width: number;
|
|
10
|
+
height: number;
|
|
11
|
+
fps: number;
|
|
12
|
+
output: string;
|
|
13
|
+
/** Soundtrack file to mux in */
|
|
14
|
+
audio?: string;
|
|
15
|
+
/** x264 quality, 0 (lossless) to 51 (default 20) */
|
|
16
|
+
crf?: number;
|
|
17
|
+
/** x264 preset (default `medium`) */
|
|
18
|
+
preset?: string;
|
|
19
|
+
}
|
|
20
|
+
export declare function ffmpegArgs(options: FfmpegOptions): string[];
|
|
21
|
+
/** Decode any audio file ffmpeg reads to mono 32-bit float samples on stdout. */
|
|
22
|
+
export declare function ffmpegDecodeArgs(input: string, sampleRate: number): string[];
|
|
23
|
+
/** The error to report when ffmpeg could not be started. */
|
|
24
|
+
export declare function ffmpegStartError(ffmpeg: string, error: Error & {
|
|
25
|
+
code?: string;
|
|
26
|
+
}): Error;
|
|
27
|
+
/** The error to report when ffmpeg exited with a failure code. */
|
|
28
|
+
export declare function ffmpegExitError(code: number | null, stderr: string): Error;
|
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
import type { VideoScene } from './video-scene';
|
|
2
|
+
/**
|
|
3
|
+
* Draws a {@link VideoScene} at any time onto a 2D context.
|
|
4
|
+
*
|
|
5
|
+
* Needs no DOM and no Node API: the caller supplies the context (a browser
|
|
6
|
+
* canvas, an OffscreenCanvas, or a Node canvas library). Every frame is drawn
|
|
7
|
+
* from scratch at an explicit time, so rendering is deterministic and frames
|
|
8
|
+
* can be drawn in any order.
|
|
9
|
+
*/
|
|
10
|
+
export declare class FrameRenderer {
|
|
11
|
+
readonly scene: VideoScene;
|
|
12
|
+
readonly fps: number;
|
|
13
|
+
/** Length in ms */
|
|
14
|
+
readonly duration: number;
|
|
15
|
+
/** Output size is the scene size times this */
|
|
16
|
+
readonly scale: number;
|
|
17
|
+
private readonly timeline?;
|
|
18
|
+
private readonly adapter;
|
|
19
|
+
constructor(scene: VideoScene, options?: {
|
|
20
|
+
scale?: number;
|
|
21
|
+
});
|
|
22
|
+
/** Output width in pixels */
|
|
23
|
+
get width(): number;
|
|
24
|
+
/** Output height in pixels */
|
|
25
|
+
get height(): number;
|
|
26
|
+
/** Frames needed to cover the whole duration */
|
|
27
|
+
get frameCount(): number;
|
|
28
|
+
/** Time in ms of a frame */
|
|
29
|
+
frameTime(index: number): number;
|
|
30
|
+
/**
|
|
31
|
+
* Stills worth checking: the middle of each caption (the moment a line is
|
|
32
|
+
* being spoken), else the middle of each marker's step (from the marker to
|
|
33
|
+
* the next one, or the end), else the middle of the video.
|
|
34
|
+
*/
|
|
35
|
+
stillTimes(): Array<{
|
|
36
|
+
id: string;
|
|
37
|
+
time: number;
|
|
38
|
+
}>;
|
|
39
|
+
/** Clear the context and draw the scene at `time` ms. */
|
|
40
|
+
render(ctx: CanvasRenderingContext2D, time: number, index?: number): void;
|
|
41
|
+
/** Run scene code without letting its context changes leak into the rest. */
|
|
42
|
+
private drawIsolated;
|
|
43
|
+
}
|
|
44
|
+
/** Frames at 0, 1/fps, 2/fps, … needed to reach `duration` ms (at least one). */
|
|
45
|
+
export declare function frameCount(duration: number, fps: number): number;
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `@algorisys/tinyfly/headless`: render animations to video and stills
|
|
3
|
+
* outside the browser (Node + `@napi-rs/canvas` + ffmpeg).
|
|
4
|
+
*/
|
|
5
|
+
export * from './video-scene';
|
|
6
|
+
export * from './frame-renderer';
|
|
7
|
+
export * from './ffmpeg-args';
|
|
8
|
+
export * from './scene-captions';
|
|
9
|
+
export * from './node-video';
|
|
10
|
+
export * from './narration-audio';
|
|
11
|
+
export * from './node-audio';
|
|
12
|
+
export { toSRT, toWebVTT, captionCuesFromTimeline, type CaptionCue } from '../engine/export/captions';
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
import type { NarrationPlan } from '../engine/authoring/narration';
|
|
2
|
+
/**
|
|
3
|
+
* Narration audio as plain samples: place each line's clip at its cue time and
|
|
4
|
+
* encode the result as a WAV file.
|
|
5
|
+
*
|
|
6
|
+
* Pure (no Node, no DOM). Clips are mono float samples in [-1, 1] at one
|
|
7
|
+
* sample rate; silence fills the lead, gaps and tails. Placement rounds to the
|
|
8
|
+
* nearest sample, so the audio lines up with the picture to within one sample.
|
|
9
|
+
*/
|
|
10
|
+
/** Mono samples of the whole narration, `plan.duration` long. */
|
|
11
|
+
export declare function assembleNarration(plan: NarrationPlan, clips: Float32Array[], sampleRate: number): Float32Array;
|
|
12
|
+
/** A 16-bit PCM mono WAV file. Samples outside [-1, 1] are clipped. */
|
|
13
|
+
export declare function encodeWav(samples: Float32Array, sampleRate: number): Uint8Array;
|
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
import { type NarrationLine, type NarrationOptions, type NarrationPlan } from '../engine/authoring/narration';
|
|
2
|
+
/**
|
|
3
|
+
* Voice-over for a video: time the lines from their recorded clips and write
|
|
4
|
+
* the narration track.
|
|
5
|
+
*
|
|
6
|
+
* Each line names an audio file (any format ffmpeg reads). Its length comes
|
|
7
|
+
* from the decoded samples, so nobody types durations and the picture's timing
|
|
8
|
+
* matches the sound exactly. Needs ffmpeg on the PATH (or `options.ffmpeg`).
|
|
9
|
+
*/
|
|
10
|
+
/** A spoken line with its recording. */
|
|
11
|
+
export interface VoicedLine extends Omit<NarrationLine, 'duration'> {
|
|
12
|
+
/** Audio file of the line, relative to `baseDir` */
|
|
13
|
+
audio: string;
|
|
14
|
+
}
|
|
15
|
+
export interface VoicedScene {
|
|
16
|
+
id?: string;
|
|
17
|
+
lines: VoicedLine[];
|
|
18
|
+
/** Extra hold after this scene's last line, in ms */
|
|
19
|
+
tail?: number;
|
|
20
|
+
}
|
|
21
|
+
export interface VoiceNarrationOptions extends NarrationOptions {
|
|
22
|
+
/** WAV file to write, relative to `baseDir` */
|
|
23
|
+
output: string;
|
|
24
|
+
/** Directory relative paths resolve against (default: cwd) */
|
|
25
|
+
baseDir?: string;
|
|
26
|
+
/** Sample rate of the output (default 48000) */
|
|
27
|
+
sampleRate?: number;
|
|
28
|
+
/** ffmpeg executable (default `ffmpeg`) */
|
|
29
|
+
ffmpeg?: string;
|
|
30
|
+
}
|
|
31
|
+
export interface VoicedNarration {
|
|
32
|
+
/** Timing of every line, measured from the clips */
|
|
33
|
+
plan: NarrationPlan;
|
|
34
|
+
/** Absolute path of the written WAV; pass it as the scene's `audio` */
|
|
35
|
+
audio: string;
|
|
36
|
+
}
|
|
37
|
+
/**
|
|
38
|
+
* Decode every line's clip, lay the lines out with {@link planNarration} and
|
|
39
|
+
* write the whole narration as one WAV.
|
|
40
|
+
*/
|
|
41
|
+
export declare function voiceNarration(scenes: VoicedScene[], options: VoiceNarrationOptions): Promise<VoicedNarration>;
|
|
42
|
+
/** Decode an audio file to mono float samples with ffmpeg. */
|
|
43
|
+
export declare function decodeAudio(file: string, options?: {
|
|
44
|
+
sampleRate?: number;
|
|
45
|
+
ffmpeg?: string;
|
|
46
|
+
}): Promise<Float32Array>;
|
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
import type { VideoScene } from './video-scene';
|
|
2
|
+
/** Options shared by video and stills rendering. */
|
|
3
|
+
export interface HeadlessOptions {
|
|
4
|
+
/** Directory that relative `audio` and font paths resolve against (default: cwd) */
|
|
5
|
+
baseDir?: string;
|
|
6
|
+
/** Output size multiplier, e.g. 0.5 for a quick preview (default 1) */
|
|
7
|
+
scale?: number;
|
|
8
|
+
/** Font files to register before drawing, added to the scene's: `{ Poppins: 'fonts/Poppins-Bold.ttf' }` */
|
|
9
|
+
fonts?: Record<string, string>;
|
|
10
|
+
}
|
|
11
|
+
export interface RenderVideoOptions extends HeadlessOptions {
|
|
12
|
+
/** Output file (.mp4) */
|
|
13
|
+
output: string;
|
|
14
|
+
/** Soundtrack to mux in, overriding the scene's; `false` renders silent */
|
|
15
|
+
audio?: string | false;
|
|
16
|
+
/** Frames per second, overriding the scene's */
|
|
17
|
+
fps?: number;
|
|
18
|
+
/** x264 quality, 0–51 (default 20) */
|
|
19
|
+
crf?: number;
|
|
20
|
+
/** x264 preset (default `medium`) */
|
|
21
|
+
preset?: string;
|
|
22
|
+
/** ffmpeg executable (default `ffmpeg`) */
|
|
23
|
+
ffmpeg?: string;
|
|
24
|
+
/** Called after each frame */
|
|
25
|
+
onProgress?: (done: number, total: number) => void;
|
|
26
|
+
}
|
|
27
|
+
export interface RenderVideoResult {
|
|
28
|
+
output: string;
|
|
29
|
+
frames: number;
|
|
30
|
+
/** Length in ms */
|
|
31
|
+
duration: number;
|
|
32
|
+
}
|
|
33
|
+
/** Render every frame of the scene into an MP4. */
|
|
34
|
+
export declare function renderVideo(scene: VideoScene, options: RenderVideoOptions): Promise<RenderVideoResult>;
|
|
35
|
+
export interface RenderStillsOptions extends HeadlessOptions {
|
|
36
|
+
/** Directory to write PNGs into (created if missing) */
|
|
37
|
+
dir: string;
|
|
38
|
+
/** Times in ms to render, named by id (default: the middle of each marker's step) */
|
|
39
|
+
times?: Array<{
|
|
40
|
+
id: string;
|
|
41
|
+
time: number;
|
|
42
|
+
}>;
|
|
43
|
+
}
|
|
44
|
+
/**
|
|
45
|
+
* One PNG per marker step (or per given time), for checking layout without
|
|
46
|
+
* encoding a video. Returns the written file paths.
|
|
47
|
+
*/
|
|
48
|
+
export declare function renderStills(scene: VideoScene, options: RenderStillsOptions): Promise<string[]>;
|
|
@@ -0,0 +1,4 @@
|
|
|
1
|
+
import { type CaptionCue } from '../engine/export/captions';
|
|
2
|
+
import type { VideoScene } from './video-scene';
|
|
3
|
+
/** The scene's own captions, else cues from its timeline's markers, else none. */
|
|
4
|
+
export declare function sceneCaptions(scene: VideoScene, language?: string): CaptionCue[];
|
|
@@ -0,0 +1,57 @@
|
|
|
1
|
+
import type { AnimationState, TimelineDefinition } from '../engine/types';
|
|
2
|
+
import type { CaptionCue } from '../engine/export/captions';
|
|
3
|
+
import type { CanvasTarget } from '../adapters/canvas';
|
|
4
|
+
/**
|
|
5
|
+
* A video scene: everything needed to render an animation to frames without a
|
|
6
|
+
* browser.
|
|
7
|
+
*
|
|
8
|
+
* Two ways to draw, usable together:
|
|
9
|
+
* - **Declarative**: `timeline` animates `targets` (canvas targets, including
|
|
10
|
+
* `custom` ones whose draw function is code).
|
|
11
|
+
* - **Immediate**: `draw(ctx, frame)` paints the whole frame from the time,
|
|
12
|
+
* like a Cairo or Processing sketch. It runs after the targets; a
|
|
13
|
+
* `background` function runs before them.
|
|
14
|
+
*
|
|
15
|
+
* A scene is usually the default export of a module handed to `tinyfly video`.
|
|
16
|
+
*/
|
|
17
|
+
export interface VideoScene {
|
|
18
|
+
/** Frame size in pixels, before `scale` */
|
|
19
|
+
width: number;
|
|
20
|
+
height: number;
|
|
21
|
+
/** Frames per second (default 30) */
|
|
22
|
+
fps?: number;
|
|
23
|
+
/** Length in ms (default: the timeline's duration) */
|
|
24
|
+
duration?: number;
|
|
25
|
+
/** Animation data; its markers drive stills and captions */
|
|
26
|
+
timeline?: TimelineDefinition;
|
|
27
|
+
/** Canvas targets by id, drawn in insertion order; tracks address them by id */
|
|
28
|
+
targets?: Record<string, CanvasTarget>;
|
|
29
|
+
/**
|
|
30
|
+
* What goes under the targets: a colour (default white; `transparent` paints
|
|
31
|
+
* nothing) or a function that draws the backdrop each frame.
|
|
32
|
+
*/
|
|
33
|
+
background?: string | DrawFunction;
|
|
34
|
+
/** Immediate-mode drawing, called every frame after the targets */
|
|
35
|
+
draw?: DrawFunction;
|
|
36
|
+
/** Soundtrack to mux into the video, relative to the scene file */
|
|
37
|
+
audio?: string;
|
|
38
|
+
/** Font files to register before drawing, by family, relative to the scene file */
|
|
39
|
+
fonts?: Record<string, string>;
|
|
40
|
+
/** Captions to write alongside the video (default: from the timeline's markers) */
|
|
41
|
+
captions?: CaptionCue[];
|
|
42
|
+
}
|
|
43
|
+
/** Draws part of a frame. Context state is saved and restored around each call. */
|
|
44
|
+
export type DrawFunction = (ctx: CanvasRenderingContext2D, frame: FrameInfo) => void;
|
|
45
|
+
/** What the draw function knows about the frame being drawn. */
|
|
46
|
+
export interface FrameInfo {
|
|
47
|
+
/** 0-based frame number (0 for stills) */
|
|
48
|
+
index: number;
|
|
49
|
+
/** Time in ms */
|
|
50
|
+
time: number;
|
|
51
|
+
/** Timeline state at `time`, when the scene has a timeline */
|
|
52
|
+
state?: AnimationState;
|
|
53
|
+
/** Scene size in pixels (the logical size, before `scale`) */
|
|
54
|
+
width: number;
|
|
55
|
+
height: number;
|
|
56
|
+
}
|
|
57
|
+
export declare const DEFAULT_FPS = 30;
|