@algorisys/tinyfly 0.79.0 → 0.82.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.
@@ -0,0 +1,243 @@
1
+ import type { EasingType, Track } from '../engine/types';
2
+ import { type HandPose, type HandShapeName } from './hands/hand-rig';
3
+ import { type DanceFrame, type Dancer, type Expression, type ExpressionName, type StickPose } from './stick-figure';
4
+ /**
5
+ * Dancing for the stick figure, as plain data.
6
+ *
7
+ * A **move** is a short loop of poses keyed in beats (a disco point is two
8
+ * beats: arm up, arm down). A **style** is a stance, a groove (the bounce and
9
+ * sway every beat carries), its moves and a routine that strings them
10
+ * together. Everything is counted in beats, so the same dance plays at any
11
+ * tempo: `beat = time × bpm / 60000`.
12
+ *
13
+ * Every function here is pure: the same style and beat always give the same
14
+ * pose, so a dance scrubs, renders to video and syncs to music exactly.
15
+ */
16
+ /** Hands in a dance key: a shape name or a full hand pose, per side. */
17
+ export interface DanceHands {
18
+ left?: HandShapeName | MudraName | HandPose;
19
+ right?: HandShapeName | MudraName | HandPose;
20
+ }
21
+ export interface DanceKey {
22
+ /** When, in beats from the start of the move */
23
+ beat: number;
24
+ /** Joints that change from the previous key (the first key builds on the stance) */
25
+ pose?: Partial<StickPose>;
26
+ /** Start again from the stance before applying `pose`, instead of from the previous key */
27
+ reset?: boolean;
28
+ /** Hand shapes from this key on */
29
+ hands?: DanceHands;
30
+ /** Easing into this key (default: the move's, else ease-in-out) */
31
+ easing?: EasingType;
32
+ /** Parts of the feet that strike the floor at this key: the sounds of tap, a stamp */
33
+ taps?: TapName[];
34
+ }
35
+ /** Where a foot strikes the floor: its toe (the ball) or its heel. */
36
+ export type TapName = 'leftToe' | 'leftHeel' | 'rightToe' | 'rightHeel';
37
+ /** One strike of a foot, `beat` beats from the start of the dance. */
38
+ export interface DanceTap {
39
+ beat: number;
40
+ tap: TapName;
41
+ }
42
+ export interface DanceMove {
43
+ label: string;
44
+ /** Length of one loop, in beats */
45
+ beats: number;
46
+ /** Keys in beat order; after the last, the move eases back to the first */
47
+ keys: DanceKey[];
48
+ /** Easing between keys that do not name their own */
49
+ easing?: EasingType;
50
+ /**
51
+ * Ground covered in one loop, as a fraction of the figure's height, at a
52
+ * steady speed: positive toward +x (the way a side-on figure faces), negative
53
+ * the other way. A glide or a moonwalk travels; most moves stay on the spot.
54
+ * Mirrored front-on it travels the other way; side-on it keeps its direction.
55
+ */
56
+ travel?: number;
57
+ }
58
+ /**
59
+ * What every beat carries, whatever the move: a knee bounce (down on the beat
60
+ * for hip hop, up for a springy jazz feel) and a side-to-side sway.
61
+ */
62
+ export interface Groove {
63
+ /** Knee bend at the bottom of the bounce, degrees (0 none) */
64
+ bounce: number;
65
+ /** Where the bounce is lowest: on the beat (`down`, default) or between beats (`up`) */
66
+ accent?: 'down' | 'up';
67
+ /** Upper-body sway, degrees either side, over two beats */
68
+ sway?: number;
69
+ }
70
+ /** One step of a routine: a move, for how many beats, optionally mirrored. */
71
+ export interface RoutineStep {
72
+ move: string;
73
+ beats: number;
74
+ /** Dance it on the other side: left and right swap */
75
+ mirror?: boolean;
76
+ }
77
+ export interface DanceStyle {
78
+ label: string;
79
+ /** The tempo it is made for; any tempo plays it */
80
+ bpm: number;
81
+ /** Joints that differ from rest while dancing: the base every move builds on */
82
+ stance: Partial<StickPose>;
83
+ /** The face while dancing */
84
+ expression?: ExpressionName | Partial<Expression>;
85
+ /** Hand shapes before any key sets them (default relaxed) */
86
+ hands?: DanceHands;
87
+ groove: Groove;
88
+ moves: Record<string, DanceMove>;
89
+ /** The moves in order; it loops */
90
+ routine: RoutineStep[];
91
+ }
92
+ /**
93
+ * Hand gestures of Indian classical dance (hasta mudras), as cartoon-hand
94
+ * poses, palm toward the viewer. Use them by name in a key's `hands`.
95
+ */
96
+ export declare const MUDRAS: {
97
+ /** Flag: fingers together and straight, thumb bent in */
98
+ pataka: HandPose;
99
+ /** Pataka with the ring finger bent */
100
+ tripataka: HandPose;
101
+ /** Lotus in bloom: fingers fanned, each a little more curled than the last */
102
+ alapadma: HandPose;
103
+ /** Fist */
104
+ mushti: HandPose;
105
+ /** Fist, thumb up */
106
+ shikhara: HandPose;
107
+ /** Swan's beak: thumb and index touch, the others fanned */
108
+ hamsasya: HandPose;
109
+ /** Bracelet: thumb, index and middle meet, ring and little finger out */
110
+ katakamukha: HandPose;
111
+ };
112
+ export type MudraName = keyof typeof MUDRAS;
113
+ /**
114
+ * A pose danced on the other side. Front-on (`turn` below 0.5) left and right
115
+ * swap and leans and spins reverse, a mirror image. Side-on the figure still
116
+ * faces the same way: the other arm and leg do the same thing (swapped, and
117
+ * their angles negated, since forward is negative on the left), and leans and
118
+ * spins stay as they are.
119
+ */
120
+ export declare function mirrorPose(pose: StickPose): StickPose;
121
+ /** Bounce and sway at `beat`, on top of a pose. */
122
+ export declare function applyGroove(pose: StickPose, groove: Groove, beat: number): StickPose;
123
+ /** The stance a style dances from, with its face. */
124
+ export declare function danceStance(style: DanceStyle): StickPose;
125
+ export interface DanceOptions {
126
+ /** Dance one move on a loop instead of the style's routine */
127
+ move?: string;
128
+ /** Mirror it (with `move`) */
129
+ mirror?: boolean;
130
+ }
131
+ /**
132
+ * The figure dancing `style` at `beat` (beats from the start; it loops): the
133
+ * pose, with the groove, and the hand shapes. Moves blend into each other
134
+ * over half a beat.
135
+ */
136
+ export declare function danceFrame(style: DanceStyle | DanceStyleName, beat: number, options?: DanceOptions): DanceFrame;
137
+ /** Just the pose of {@link danceFrame}. */
138
+ export declare function dancePose(style: DanceStyle | DanceStyleName, beat: number, options?: DanceOptions): StickPose;
139
+ /** Length of a style's routine, in beats. */
140
+ export declare function routineBeats(style: DanceStyle | DanceStyleName): number;
141
+ /**
142
+ * The foot strikes between beat `from` (included) and `to` (not), in order:
143
+ * what a scene plays tap sounds or stamps on. Call it each frame with the
144
+ * previous frame's beat and this one's to get exactly the taps that just
145
+ * happened; it follows the routine (and its mirrored steps) as
146
+ * {@link danceFrame} does, looping it.
147
+ */
148
+ export declare function danceTaps(style: DanceStyle | DanceStyleName, from: number, to: number, options?: DanceOptions): DanceTap[];
149
+ /**
150
+ * How far the dance has carried the figure at `beat`, as a fraction of its
151
+ * height (multiply by the height in px for an `x` offset). Travelling moves go
152
+ * at a steady speed, so it is a straight line between step changes; the
153
+ * other moves hold it still. A routine that does not come back to where it
154
+ * started keeps going that way each time it loops.
155
+ */
156
+ export declare function danceTravel(style: DanceStyle | DanceStyleName, beat: number, options?: DanceOptions): number;
157
+ export interface DanceTravelOptions extends DanceOptions {
158
+ /** Tempo (default the style's) */
159
+ bpm?: number;
160
+ /** How many beats (default the routine, or one loop of the move) */
161
+ beats?: number;
162
+ /** When the dance starts, ms (default 0) */
163
+ start?: number;
164
+ /** The figure's height, px: travel is measured in heights */
165
+ height: number;
166
+ /** The `x` offset the figure starts from (default 0) */
167
+ x?: number;
168
+ /**
169
+ * Beats the dance blends in from standing and back out over, as
170
+ * {@link danceTracks}' `fade` (default 1, the same): the glide eases in and
171
+ * out with the pose. 0 travels at full speed from the first beat to the last.
172
+ */
173
+ fade?: number;
174
+ }
175
+ /**
176
+ * The ground a dance covers as an `x` track, to play beside
177
+ * {@link danceTracks} (or {@link bakeDanceTracks}, which adds it itself).
178
+ * Travel goes at a steady speed, so the keys are linear and only where the
179
+ * speed changes, plus a few while it eases in and out with the `fade`.
180
+ * Undefined when the dance stays on the spot.
181
+ */
182
+ export declare function danceTravelTrack(target: string, style: DanceStyle | DanceStyleName, options: DanceTravelOptions): Track | undefined;
183
+ /** Beats since `start` at `time` (both ms), at `bpm`. */
184
+ export declare function beatAt(time: number, bpm: number, start?: number): number;
185
+ /**
186
+ * A {@link Dancer} for `stickFigureTarget({ dance })`: the target's `beat`
187
+ * prop then plays the style (and `dancing` blends it in).
188
+ */
189
+ export declare function dancer(style: DanceStyle | DanceStyleName, options?: DanceOptions): Dancer;
190
+ export interface DanceTrackOptions {
191
+ /** Tempo (default the style's) */
192
+ bpm: number;
193
+ /** How many beats to dance */
194
+ beats: number;
195
+ /** When the dance starts, ms (default 0) */
196
+ start?: number;
197
+ /** Beats to blend in from standing and back out at the end (default 1) */
198
+ fade?: number;
199
+ }
200
+ /**
201
+ * Tracks that make a `stickFigureTarget({ dance })` dance: `beat` counts up
202
+ * at the tempo, and `dancing` blends in at the start and out at the end.
203
+ * Two small tracks, so the timeline JSON stays tiny.
204
+ */
205
+ export declare function danceTracks(target: string, options: DanceTrackOptions): Track[];
206
+ export interface DanceBakeOptions extends DanceOptions {
207
+ /** Bake the hand shapes too, as `hand.left.*` / `hand.right.*` tracks (default true) */
208
+ hands?: boolean;
209
+ bpm?: number;
210
+ /** How many beats to bake (default the routine, or the move's length) */
211
+ beats?: number;
212
+ /** When it starts, ms (default 0) */
213
+ start?: number;
214
+ /** Keyframes per beat (default 4) */
215
+ samplesPerBeat?: number;
216
+ /** The figure's height, px: with it a travelling dance (a glide, a moonwalk) moves it, as an `x` track */
217
+ height?: number;
218
+ /** The `x` offset it starts from (default 0) */
219
+ x?: number;
220
+ }
221
+ /**
222
+ * The dance as plain pose keyframes, for any stick-figure target and for
223
+ * timelines that must stand alone as JSON (no `dance` option needed). Only
224
+ * joints that move get a track. Hand shapes are baked as `hand.left.*` /
225
+ * `hand.right.*` tracks, which a target drawn with `style.hands` plays.
226
+ * With `height`, a dance that travels gets an `x` track too.
227
+ */
228
+ export declare function bakeDanceTracks(target: string, style: DanceStyle | DanceStyleName, options?: DanceBakeOptions): Track[];
229
+ /** Ready-made dance styles. Each is plain data: copy one and change it to make your own. */
230
+ export declare const DANCE_STYLES: {
231
+ disco: DanceStyle;
232
+ hipHop: DanceStyle;
233
+ breaking: DanceStyle;
234
+ jazz: DanceStyle;
235
+ kpop: DanceStyle;
236
+ bollywood: DanceStyle;
237
+ bhangra: DanceStyle;
238
+ bharatanatyam: DanceStyle;
239
+ charleston: DanceStyle;
240
+ tap: DanceStyle;
241
+ popping: DanceStyle;
242
+ };
243
+ export type DanceStyleName = keyof typeof DANCE_STYLES;
@@ -5,12 +5,15 @@
5
5
  * here.
6
6
  */
7
7
  export * from './stick-figure';
8
+ export * from './dance';
9
+ export * from './acrobatics';
10
+ export { stickToHuman } from './stick-to-human';
8
11
  export * from '../adapters/canvas/sketch';
9
12
  export * from './erase';
10
13
  export * from '../adapters/canvas/polyline';
11
14
  export * from './hand';
12
15
  export * from './character';
13
- export { humanPlan, humanPose, humanFieldLabel, HUMAN_REST, HUMAN_POSES, HUMAN_EXPRESSIONS, type HumanBuild, type HumanPoseName } from './species/human';
16
+ export { humanPlan, humanPose, mirrorHumanPose, humanFieldLabel, HUMAN_REST, HUMAN_POSES, HUMAN_EXPRESSIONS, type HumanBuild, type HumanPoseName } from './species/human';
14
17
  export type { BodyPlan, ChainSpec, BoneSpec, BoneAngles, ContactSpec, HeadSpec, Pose as CharacterPose, Vec3 } from './rig/body-plan';
15
18
  export { createPen, ellipsePoints, type Pen, type Look, type PencilOptions, type PenOptions } from './look/pen';
16
19
  export { basicOutfit, type BasicOutfitOptions } from './wardrobe/basic-outfit';
@@ -11,7 +11,10 @@ import { type ExpressionName } from '../stick-figure';
11
11
  * - `arm.left.swing` (forward +), `arm.left.spread` (out +), `arm.left.elbow`
12
12
  * (forearm forward +), `arm.left.bend` (forearm out +), and the same for `.right`
13
13
  * - `leg.left.swing` (forward +), `leg.left.spread` (out +), `leg.left.knee`
14
- * (shin back +), `leg.left.ankle` (toes up +), and the same for `.right`
14
+ * (shin back +), `leg.left.ankle` (toes up +), `leg.left.toeOut` (the foot
15
+ * turned out from its natural angle +, in −), `leg.left.rotate` (the whole
16
+ * leg turned out at the hip +: at 90 a bent knee points sideways, as in a
17
+ * turned-out plié), and the same for `.right`
15
18
  * - `stretch` (1 normal), `lift` (fraction of height above the ground), `roll` (whole-figure roll, degrees)
16
19
  * - the face: `mouth`, `smile`, `mouthWidth`, `blink`, `eye.left`, `eye.right`,
17
20
  * `brow.left`, `brow.right`, `browTilt`, `lookX`, `lookY` (as the v1 stick figure)
@@ -29,6 +32,14 @@ export interface HumanBuild {
29
32
  export declare const HUMAN_REST: Pose;
30
33
  /** A full human pose from the fields that differ from rest. */
31
34
  export declare function humanPose(changes?: Pose): Pose;
35
+ /**
36
+ * The mirror image of a pose, as if seen in a mirror beside the picture: the
37
+ * left limbs, eye, brow and hand take the right's values and the other way
38
+ * round, and the body turns, tips and rolls the other way (`turn` 1, facing
39
+ * screen-right, becomes -1, facing screen-left). Fields of other body plans
40
+ * pass through.
41
+ */
42
+ export declare function mirrorHumanPose(pose: Pose): Pose;
32
43
  /**
33
44
  * Ready-made human poses. Several rest on something other than the feet (a
34
45
  * knee, the hands, the back): the figure is set down on whatever is lowest.
@@ -2,6 +2,7 @@ import type { CustomTarget } from '../adapters/canvas';
2
2
  import type { FrameInfo } from '../headless/video-scene';
3
3
  import type { EasingType, Track } from '../engine/types';
4
4
  import { type Point, type SketchPen, type SketchStyle } from '../adapters/canvas/sketch';
5
+ import { type HandPose } from './hands/hand-rig';
5
6
  /**
6
7
  * A stick-figure rig: a pose is a handful of numbers, so poses blend, walk
7
8
  * cycles are functions of a phase, and every joint can be a timeline track.
@@ -29,6 +30,26 @@ export interface StickPose {
29
30
  /** Knee bend: positive swings the shin back toward the centre */
30
31
  leftKnee: number;
31
32
  rightKnee: number;
33
+ /**
34
+ * Wrist bend, degrees, added to the forearm's angle like the elbow is to the
35
+ * upper arm's. It turns `handAngle` (props, cartoon hands) and the hands
36
+ * drawn by `style.hands`; a dot hand looks the same at any angle.
37
+ */
38
+ leftWrist: number;
39
+ rightWrist: number;
40
+ /**
41
+ * Ankle, degrees: positive points the toe down (onto tiptoe, which lifts the
42
+ * body), negative flexes it up onto the heel. Not drawn in the classic look.
43
+ */
44
+ leftAnkle: number;
45
+ rightAnkle: number;
46
+ /**
47
+ * Foot turn-out seen from the front: 0 the natural splay, positive turns the
48
+ * toes further out (1 fully sideways), negative turns them in. Swivelling
49
+ * feet (the twist, a Charleston) animate this.
50
+ */
51
+ leftFootOut: number;
52
+ rightFootOut: number;
32
53
  /** 0 closed, 1 wide open */
33
54
  mouth: number;
34
55
  /** -1 frown, 0 flat, 1 smile; with an open mouth, sets a grin (+) or a wail (-) */
@@ -66,6 +87,14 @@ export interface StickPose {
66
87
  * 0.25 on, the lower foot rests on the ground.
67
88
  */
68
89
  sit: number;
90
+ /**
91
+ * The whole body turned about the hips, degrees: positive rolls forward (the
92
+ * way the figure faces, a front flip), negative backward. Seen front-on
93
+ * (`turn` 0) it is a cartwheel. 360 is a full turn.
94
+ */
95
+ spin: number;
96
+ /** Lift off the ground, as a fraction of the height: the arc of a jump or a flip */
97
+ rise: number;
69
98
  }
70
99
  export declare const REST_POSE: StickPose;
71
100
  /** A full pose from the fields that differ from rest. */
@@ -113,6 +142,8 @@ export declare const POSES: {
113
142
  crouch: StickPose;
114
143
  sit: StickPose;
115
144
  jump: StickPose;
145
+ sideSplit: StickPose;
146
+ frontSplit: StickPose;
116
147
  };
117
148
  export type PoseName = keyof typeof POSES;
118
149
  /** Linear blend: `t` 0 is `from`, 1 is `to`. */
@@ -178,6 +209,25 @@ export interface StickStyle {
178
209
  classic?: boolean;
179
210
  /** Drawing hooks that put costumes, hair and props inside the figure's z-order */
180
211
  layers?: FigureLayers;
212
+ /**
213
+ * Cartoon hands in place of the round dot hands (not in the classic look):
214
+ * posed hands with fingers, pointing along the forearm turned by the wrist.
215
+ */
216
+ hands?: StickHands;
217
+ }
218
+ /** Cartoon hands for a stick figure: a {@link HandPose} per hand, and how they look. */
219
+ export interface StickHands {
220
+ /** Hand poses (default relaxed): see `HAND_SHAPES` */
221
+ left?: HandPose;
222
+ right?: HandPose;
223
+ /** Skin fill (default the head fill, or a warm tan when the head is see-through) */
224
+ skin?: string;
225
+ /** Wrist to fingertip, as a fraction of the figure's height (default 0.075) */
226
+ size?: number;
227
+ /** `5` (default) or `4`: a thumb and three, the classic cartoon glove */
228
+ fingers?: 4 | 5;
229
+ /** 1 a natural hand (default); 1.5 a fat cartoon glove */
230
+ plump?: number;
181
231
  }
182
232
  export type StickSide = 'left' | 'right';
183
233
  /**
@@ -259,7 +309,10 @@ export interface StickJoints {
259
309
  /** Where the arms start: one point when `shoulderWidth` is 0 */
260
310
  shoulders: Record<StickSide, Point>;
261
311
  elbows: Record<StickSide, Point>;
312
+ /** The wrists: where the forearms end and the hands begin */
262
313
  hands: Record<StickSide, Point>;
314
+ /** Where each hand reaches to past its wrist, turned by the wrist bend */
315
+ fingertips: Record<StickSide, Point>;
263
316
  knees: Record<StickSide, Point>;
264
317
  feet: Record<StickSide, Point>;
265
318
  /** Tips of the feet, pointing the way the figure faces (the ankles, in the classic look) */
@@ -268,7 +321,10 @@ export interface StickJoints {
268
321
  feetY: number;
269
322
  /** Which feet are on the ground: within 1% of the height of the lower foot */
270
323
  grounded: Record<StickSide, boolean>;
271
- /** Direction the hand points (the forearm, along its curve for rubber hose), radians: for holding props */
324
+ /**
325
+ * Direction the hand points, radians: the forearm (along its curve for rubber
326
+ * hose) turned by the wrist bend. For holding props.
327
+ */
272
328
  handAngle: Record<StickSide, number>;
273
329
  /** Each limb as the polyline that is stroked (rubber-hose curves included), for sleeves and trousers */
274
330
  limbs: {
@@ -318,12 +374,31 @@ export interface StickFigureProps extends StickPose {
318
374
  talk: number;
319
375
  /** Limbs from jointed (0) to rubber hose (1); starts at the style's `rubber` */
320
376
  rubber: number;
377
+ /** Beats into the target's dance (animate it 0 → n at the tempo); see `danceTracks` */
378
+ beat?: number;
379
+ /** How much of the dance is applied, 0..1 (0 standing) */
380
+ dancing?: number;
321
381
  }
382
+ /** A dancer's pose at one moment, and its hand shapes when it has them. */
383
+ export interface DanceFrame {
384
+ pose: StickPose;
385
+ hands?: {
386
+ left?: HandPose;
387
+ right?: HandPose;
388
+ };
389
+ }
390
+ /** Gives the pose at a beat: what `stickFigureTarget({ dance })` plays (see `dancer()`). */
391
+ export type Dancer = (beat: number) => DanceFrame;
322
392
  /**
323
- * The pose a stick-figure target draws at `time` ms: its props with the walk
324
- * cycle (by `walking`) and the chatter of `talk` folded in.
393
+ * What a stick-figure target draws at `time` ms: its props with the walk
394
+ * cycle (by `walking`), a dance (by `dancing`) and the chatter of `talk`
395
+ * folded in, and the dance's hand shapes.
325
396
  */
326
- export declare function resolveStickPose(props: StickFigureProps, time: number): StickPose;
397
+ export declare function resolveStickFrame(props: StickFigureProps, time: number, dance?: Dancer): DanceFrame;
398
+ /** The pose of {@link resolveStickFrame}. */
399
+ export declare function resolveStickPose(props: StickFigureProps, time: number, dance?: Dancer): StickPose;
400
+ /** Prop names for a hand's pose fields on a stick-figure target: `hand.left.index.curl`, … */
401
+ export declare const handProp: (side: StickSide, field: string) => string;
327
402
  export interface StickFigureTargetOptions {
328
403
  /** Where the feet stand */
329
404
  x: number;
@@ -331,11 +406,18 @@ export interface StickFigureTargetOptions {
331
406
  /** Starting pose (default rest) */
332
407
  pose?: Partial<StickPose>;
333
408
  style?: StickStyle;
409
+ /**
410
+ * A dance to play: its `beat` prop counts beats and `dancing` blends it in
411
+ * (see `dancer()` and `danceTracks()`). Its hand shapes show when the style has `hands`.
412
+ */
413
+ dance?: Dancer;
334
414
  }
335
415
  /** A `custom` target made by {@link stickFigureTarget}. */
336
416
  export interface StickFigureTarget extends CustomTarget {
337
417
  /** The style it draws with, so {@link stickFigureAt} can find its joints */
338
418
  readonly figureStyle: StickStyle;
419
+ /** The dance it plays, if any */
420
+ readonly figureDance?: Dancer;
339
421
  }
340
422
  /**
341
423
  * A `custom` canvas target that draws a stick figure. Its props are the pose
@@ -0,0 +1,27 @@
1
+ import type { Pose } from './rig/body-plan';
2
+ import type { DanceFrame, StickPose } from './stick-figure';
3
+ /**
4
+ * The stick figure's poses on a v2 human character, so dances and flips
5
+ * written for the stick figure play on characters too (and in the editor).
6
+ *
7
+ * The stick figure is drawn in one plane: seen front-on (`turn` 0) a limb's
8
+ * angle spreads it sideways; in profile (`turn` 1) the same angle swings it
9
+ * forward or back. A v2 character's limbs are 3D, so each stick angle is split
10
+ * by the turn into a sideways `spread` and a forward `swing`, and the
11
+ * character is turned the same way. Sides swap: the stick figure's right is
12
+ * on screen-right, which is a v2 character's left when it faces the viewer.
13
+ *
14
+ * Elbows split the same way. Legs use the hip rotation instead: front-on, a
15
+ * stick leg lies in the picture plane, which is a v2 leg turned out 90° at the
16
+ * hip (`leg.*.rotate`), so its swing and knee bend sideways, and a plié's
17
+ * knees point out over the toes as they do on the stick figure. Side-on the
18
+ * leg is not turned and swings forward and back. Foot turn-out becomes
19
+ * `toeOut`. `sit` has no v2 field and is left out.
20
+ *
21
+ * With `hands` (a dance frame's hand shapes), the result also carries the
22
+ * `hand.<side>.*` fields that a character with `hands: 'cartoon'` draws: the
23
+ * shapes, turned to match how the stick figure shows them, rolled by the
24
+ * stick figure's wrist bends. Without, wrists are left out (dot hands look
25
+ * the same at any angle).
26
+ */
27
+ export declare function stickToHuman(stick: StickPose, hands?: DanceFrame['hands']): Pose;
@@ -0,0 +1,64 @@
1
+ /**
2
+ * Beats: a steady pulse laid over the timeline, so motion can land on the
3
+ * music. A grid is a tempo, where its first beat falls, and how many beats a
4
+ * bar has; everything else (which beat a moment is on, the nearest beat, the
5
+ * beats in a range) follows from it. Pure functions, no audio or DOM.
6
+ *
7
+ * `detectTempo` finds a grid in audio samples: the tempo and where the beats
8
+ * fall. It is deterministic (the same samples always give the same grid), so
9
+ * it runs anywhere: the editor decodes a clip and passes its samples in, a
10
+ * Node script passes samples from `decodeAudio`.
11
+ */
12
+ export interface BeatGrid {
13
+ /** Beats per minute */
14
+ bpm: number;
15
+ /** Timeline time of a beat (ms); the grid runs forward and back from it */
16
+ offset: number;
17
+ /** Beats in a bar (default 4): the grid's stronger lines */
18
+ beatsPerBar?: number;
19
+ }
20
+ /** Milliseconds between beats. */
21
+ export declare const beatLength: (grid: BeatGrid) => number;
22
+ /** Timeline time (ms) of beat `n` (0 is the beat at `offset`; it may be negative or fractional). */
23
+ export declare function beatTime(grid: BeatGrid, n: number): number;
24
+ /** Which beat `time` is on, counted from `offset` (fractional between beats). */
25
+ export declare function beatAtTime(grid: BeatGrid, time: number): number;
26
+ /** The beat nearest `time`, ms. */
27
+ export declare function nearestBeat(grid: BeatGrid, time: number): number;
28
+ /** The first beat at or after `time`, ms. */
29
+ export declare function nextBeat(grid: BeatGrid, time: number): number;
30
+ /** Every beat from `from` to `to` (ms, inclusive), and whether it starts a bar. */
31
+ export declare function beatsBetween(grid: BeatGrid, from: number, to: number): Array<{
32
+ time: number;
33
+ bar: boolean;
34
+ n: number;
35
+ }>;
36
+ export interface TempoOptions {
37
+ /** Slowest and fastest tempos to consider (default 70–180 bpm) */
38
+ minBpm?: number;
39
+ maxBpm?: number;
40
+ /** Analyse at most this many seconds from the start (default 60) */
41
+ maxSeconds?: number;
42
+ }
43
+ export interface DetectedTempo {
44
+ bpm: number;
45
+ /** Where the first beat falls, ms from the start of the audio */
46
+ offset: number;
47
+ /** How clearly the audio pulses, 0..1: low means the guess is shaky */
48
+ confidence: number;
49
+ }
50
+ /**
51
+ * Find the tempo of audio, and where its beats fall.
52
+ *
53
+ * 1. Onset strength: the audio's loudness in 10 ms frames, log-compressed;
54
+ * where it rises (a drum hit, a strum) is a likely beat.
55
+ * 2. Tempo: the onset strength compared with itself shifted by each beat
56
+ * length in range (autocorrelation). The best match is the beat; a gentle
57
+ * preference for tempos near 120 settles half- and double-time doubts.
58
+ * 3. Tempo and phase: of the grids close to that tempo, and every position
59
+ * each could take, the one whose beats land on the most onset strength
60
+ * across the whole clip.
61
+ *
62
+ * `samples` are mono; mix channels down first.
63
+ */
64
+ export declare function detectTempo(samples: Float32Array, sampleRate: number, options?: TempoOptions): DetectedTempo;
@@ -2,3 +2,4 @@ export * from './random';
2
2
  export * from './resolve-values';
3
3
  export * from './custom-ease';
4
4
  export * from './narration';
5
+ export * from './beats';
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@algorisys/tinyfly",
3
- "version": "0.79.0",
3
+ "version": "0.82.0",
4
4
  "type": "module",
5
5
  "description": "Lightweight, API-driven animation engine and editor. The engine is framework-agnostic and runs in browsers, Web Workers, and Node.",
6
6
  "license": "MIT",