@algorisys/tinyfly 0.101.0 → 0.102.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (48) hide show
  1. package/README.md +5 -5
  2. package/bin/tinyfly.mjs +9 -3
  3. package/docs/editor-guide.md +1 -1
  4. package/docs/examples.md +1 -1
  5. package/docs/getting-started.md +1 -1
  6. package/docs/gsap-compat.md +1 -1
  7. package/docs/llm-guide.md +8 -2
  8. package/docs/maps.md +2 -2
  9. package/docs/scene-3d.md +117 -5
  10. package/docs/teaching.md +1 -1
  11. package/docs/video-rendering.md +44 -1
  12. package/lib/addons/adapters.js +168 -123
  13. package/lib/addons/characters.js +4663 -4566
  14. package/lib/addons/scene-3d-webgl.js +30 -30
  15. package/lib/addons/scene-3d.js +650 -341
  16. package/lib/browser/tinyfly-scene-3d-webgl.iife.js +2 -2
  17. package/lib/browser/tinyfly-scene-3d.iife.js +2 -2
  18. package/lib/browser/tinyfly.iife.js +13 -13
  19. package/lib/browser/tinyfly.js +4105 -3973
  20. package/lib/browser/tinyfly.umd.js +13 -13
  21. package/lib/engine/tinyfly-engine.js +1207 -1172
  22. package/lib/engine/tinyfly-engine.umd.cjs +2 -2
  23. package/lib/headless/headless.js +150 -6
  24. package/lib/types/adapters/canvas/framing.d.ts +27 -0
  25. package/lib/types/adapters/canvas/index.d.ts +1 -0
  26. package/lib/types/characters/character-script-3d.d.ts +21 -1
  27. package/lib/types/characters/index.d.ts +2 -1
  28. package/lib/types/characters/staging-3d.d.ts +56 -0
  29. package/lib/types/engine/authoring/framing.d.ts +48 -0
  30. package/lib/types/engine/authoring/index.d.ts +1 -0
  31. package/lib/types/headless/audio-mix.d.ts +40 -0
  32. package/lib/types/headless/ffmpeg-args.d.ts +2 -0
  33. package/lib/types/headless/frame-renderer.d.ts +7 -1
  34. package/lib/types/headless/index.d.ts +1 -0
  35. package/lib/types/headless/node-audio.d.ts +19 -0
  36. package/lib/types/headless/node-video.d.ts +2 -0
  37. package/lib/types/headless/video-scene.d.ts +12 -0
  38. package/lib/types/scene-3d/index.d.ts +3 -0
  39. package/lib/types/scene-3d/lighting.d.ts +58 -0
  40. package/lib/types/scene-3d/resolve-scene.d.ts +5 -1
  41. package/lib/types/scene-3d/scene-3d-adapter.d.ts +2 -0
  42. package/lib/types/scene-3d/scene-types.d.ts +14 -2
  43. package/lib/types/scene-3d/shots.d.ts +162 -0
  44. package/lib/types/scene-3d/software-renderer.d.ts +40 -0
  45. package/llms-full.txt +177 -16
  46. package/llms.txt +29 -29
  47. package/package.json +1 -1
  48. package/skills/tinyfly/SKILL.md +4 -1
@@ -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;
@@ -9,3 +9,4 @@ export * from './spring-follow';
9
9
  export * from './periodic';
10
10
  export * from './curve';
11
11
  export * from './beat-loop';
12
+ export * from './framing';
@@ -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
- /** Clear the context and draw the scene at `time` ms. */
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?: string;
111
+ background?: Scene3D['background'];
108
112
  fog?: Scene3D['fog'];
109
113
  camera: ResolvedCamera;
110
114
  lights: ResolvedLight[];
@@ -49,6 +49,8 @@ export declare function drawScene3D(ctx: CanvasRenderingContext2D, scene: Loaded
49
49
  time?: number;
50
50
  /** A looping video's period (a frame's `period`): trails wrap at it */
51
51
  period?: number;
52
+ /** Draw through a software depth buffer (shapes that cut through each other draw right; hard edges) instead of back to front */
53
+ depthBuffer?: boolean;
52
54
  valuesAt?: (time: number) => SceneValues;
53
55
  stateAt?: (time: number) => {
54
56
  values: SceneValues;
@@ -19,8 +19,10 @@ export interface Scene3D {
19
19
  /** In order: parents before children; array order breaks depth ties */
20
20
  objects: Object3D[];
21
21
  materials?: Record<string, Material3D>;
22
- /** Background colour, or 'transparent' (default) */
23
- background?: string;
22
+ /** Background colour, or 'transparent' (default), or a sky: a vertical gradient from `top` to `bottom` */
23
+ background?: string | SkyGradient;
24
+ /** The ground's height, metres, where blob shadows lie (default 0) */
25
+ ground?: number;
24
26
  /** Fog from `near` to `far` metres from the camera, toward `color` (outlines fade with it too) */
25
27
  fog?: {
26
28
  color: string;
@@ -67,6 +69,16 @@ export interface MeshObject extends ObjectBase {
67
69
  geometry: Geometry3D;
68
70
  /** A key of `materials` */
69
71
  material: string;
72
+ /** A soft blob shadow on the ground under it (default none): `true`, or its opacity and a ground height of its own */
73
+ shadow?: boolean | {
74
+ opacity?: number;
75
+ ground?: number;
76
+ };
77
+ }
78
+ /** A sky as a vertical gradient: `top` at the top of the frame to `bottom` at the bottom. */
79
+ export interface SkyGradient {
80
+ top: string;
81
+ bottom: string;
70
82
  }
71
83
  interface CameraBase extends ObjectBase {
72
84
  kind: 'camera';
@@ -0,0 +1,162 @@
1
+ import type { Track } from '../engine/types';
2
+ import type { EasingType } from '../engine/types';
3
+ import type { SceneValues } from './resolve-scene';
4
+ /**
5
+ * Shots and cameras for a film made from a 3D scene: a shot list as data,
6
+ * cuts and transitions that any frame can be asked about, camera moves as
7
+ * presets that write ordinary tracks, and a seeded handheld shake. Nothing
8
+ * here renders: the tracks join the timeline, and `transitionAt` tells a
9
+ * frame which two cameras to draw and how to blend them.
10
+ *
11
+ * const shots: Shot[] = [
12
+ * { id: 'wide', start: 0, end: 4000, camera: 'wide' },
13
+ * { id: 'close', start: 4000, end: 7000, camera: 'close', transition: { kind: 'crossfade', duration: 600 } },
14
+ * ]
15
+ * const tracks = [...shotTracks(shots, 'stage'), ...cameraMoveTracks({ scene: 'stage', camera: 'wide', start: 0, end: 4000,
16
+ * from: { target: [0, 1, 0], yaw: 20, pitch: 15, distance: 9 }, to: { yaw: 60, distance: 6 } })]
17
+ */
18
+ export type Vec3 = [number, number, number];
19
+ export interface ShotTransition {
20
+ /** How the shot comes in: a hard cut (the default), a crossfade from the shot before, a dip to black, or a wipe */
21
+ kind: 'cut' | 'crossfade' | 'dipToBlack' | 'wipe';
22
+ /** ms, from the shot's start */
23
+ duration: number;
24
+ /** A wipe's direction (default `left`: the new shot sweeps in from the left) */
25
+ direction?: 'left' | 'right' | 'up' | 'down';
26
+ /** A dip's colour (default black) */
27
+ color?: string;
28
+ }
29
+ export interface Shot {
30
+ id: string;
31
+ /** ms */
32
+ start: number;
33
+ end: number;
34
+ /** The camera's object id */
35
+ camera: string;
36
+ /** A caption for the storyboard and the stills */
37
+ label?: string;
38
+ transition?: ShotTransition;
39
+ }
40
+ /** The shot playing at a time (the last one that has started), or undefined before the first. */
41
+ export declare function shotAt(shots: ReadonlyArray<Shot>, time: number): Shot | undefined;
42
+ /** Problems with a shot list, as sentences; empty when fine. */
43
+ export declare function checkShots(shots: ReadonlyArray<Shot>): string[];
44
+ /**
45
+ * The cut track: `activeCamera` on the scene, one keyframe per shot (a cut
46
+ * is one keyframe; a transition still cuts at the shot's start and blends
47
+ * the shot before over it, see `transitionAt`).
48
+ */
49
+ export declare function shotTracks(shots: ReadonlyArray<Shot>, sceneId: string): Track[];
50
+ /** One marker per shot, for the timeline's `config.markers` (stills and captions step through them). */
51
+ export declare function shotMarkers(shots: ReadonlyArray<Shot>): Array<{
52
+ id: string;
53
+ time: number;
54
+ label: string;
55
+ }>;
56
+ export interface ActiveTransition {
57
+ kind: ShotTransition['kind'];
58
+ /** 0 at the shot's start to 1 when the transition is over */
59
+ progress: number;
60
+ /** The shot going out and the shot coming in */
61
+ from: Shot;
62
+ to: Shot;
63
+ direction: NonNullable<ShotTransition['direction']>;
64
+ color: string;
65
+ }
66
+ /** The transition under way at a time, if one is: which two shots, and how far along. */
67
+ export declare function transitionAt(shots: ReadonlyArray<Shot>, time: number): ActiveTransition | undefined;
68
+ /**
69
+ * Shots cut on the beat: each shot's start (but the first's) moved to the
70
+ * nearest beat of a grid (`detectTempo` on the music, or `{ bpm, offset }`),
71
+ * ends following; transitions keep their lengths. Nothing moves more than
72
+ * half a beat.
73
+ */
74
+ export declare function snapShotsToBeats(shots: ReadonlyArray<Shot>, grid: {
75
+ bpm: number;
76
+ offset: number;
77
+ }): Shot[];
78
+ /** The scene's values with another camera active: to draw the shot going out during a transition. */
79
+ export declare function withActiveCamera(values: SceneValues | undefined, sceneId: string, cameraId: string): SceneValues;
80
+ /** Where a camera is and looks, as an orbit round a target (or a fixed position), with its field of view. */
81
+ export interface CameraPose {
82
+ /** What it orbits and looks at (default the origin) */
83
+ target?: Vec3;
84
+ /** Degrees round the target (0 is in front, +z) */
85
+ yaw?: number;
86
+ /** Degrees up from level */
87
+ pitch?: number;
88
+ /** Metres from the target */
89
+ distance?: number;
90
+ /** A fixed position instead of the orbit (a pan or tilt turns the camera where it stands) */
91
+ position?: Vec3;
92
+ /** Where it looks (default the target) */
93
+ lookAt?: Vec3;
94
+ /** Vertical field of view, degrees (a zoom changes it) */
95
+ fov?: number;
96
+ }
97
+ export interface CameraMoveOptions {
98
+ scene: string;
99
+ camera: string;
100
+ /** ms */
101
+ start: number;
102
+ end: number;
103
+ /** Where the move starts and ends: `to` fills in from `from` */
104
+ from: CameraPose;
105
+ to: Partial<CameraPose>;
106
+ /** Easing over the move (default `ease-in-out`) */
107
+ easing?: EasingType;
108
+ /** Key spacing, ms (default 33): the path between keys is a straight line */
109
+ every?: number;
110
+ }
111
+ /** A camera pose at a point of a move, `t` 0..1 (eased already). */
112
+ export declare function cameraPoseAt(from: CameraPose, to: Partial<CameraPose>, t: number): {
113
+ position: Vec3;
114
+ lookAt: Vec3;
115
+ fov?: number;
116
+ };
117
+ /**
118
+ * A camera move as tracks on the camera (`position`, `lookAt`, and `fov`
119
+ * when it zooms): an orbit (change `yaw`), a dolly (`distance`), a crane
120
+ * (`pitch` and `distance`), a pan or tilt (`position` fixed, `lookAt`
121
+ * moving), a zoom (`fov`), or any mix, eased over the move.
122
+ */
123
+ export declare function cameraMoveTracks(options: CameraMoveOptions): Track[];
124
+ export interface CameraFollowOptions {
125
+ scene: string;
126
+ camera: string;
127
+ start: number;
128
+ end: number;
129
+ /** Where the subject is at a time (its position in the scene) */
130
+ subjectAt: (time: number) => Vec3;
131
+ /** The camera's place relative to the subject, metres (default behind and above: [0, 2, 6]) */
132
+ offset?: Vec3;
133
+ /** How far the camera lags behind the subject's motion, ms (default 0) */
134
+ lag?: number;
135
+ every?: number;
136
+ }
137
+ /** Tracks that keep a camera on a moving subject: its position an offset from the subject, looking at it. */
138
+ export declare function cameraFollowTracks(options: CameraFollowOptions): Track[];
139
+ export interface HandheldOptions {
140
+ scene: string;
141
+ camera: string;
142
+ start: number;
143
+ end: number;
144
+ /** How far the camera drifts, metres (default 0.04), and how far its aim wanders, metres at the subject (default 0.08) */
145
+ amount?: number;
146
+ aim?: number;
147
+ /** How quickly it wanders (default 1.2 wobbles a second) */
148
+ rate?: number;
149
+ seed?: number | string;
150
+ /** The camera's rest, when no move's tracks are given: its authored position and where it looks */
151
+ base?: {
152
+ position: Vec3;
153
+ lookAt: Vec3;
154
+ };
155
+ every?: number;
156
+ }
157
+ /**
158
+ * A deterministic handheld shake: seeded, smooth, and added onto a move's
159
+ * `position` and `lookAt` tracks (or a still camera's `base`). The same
160
+ * seed always shakes the same way.
161
+ */
162
+ export declare function cameraHandheldTracks(tracks: ReadonlyArray<Track>, options: HandheldOptions): Track[];
@@ -0,0 +1,40 @@
1
+ import type { ResolvedScene3D } from './resolve-scene';
2
+ import type { Renderer3D } from './canvas-2d-renderer';
3
+ /**
4
+ * A software depth buffer for the Canvas 2D path: every triangle is
5
+ * rasterised into a pixel buffer with a depth per pixel, so shapes that cut
6
+ * through each other, huge floors and long meshes draw right with no `layer`
7
+ * needed, in Node as well as on a page. Each triangle keeps its one shaded
8
+ * colour (and its fog), edges are hard (no anti-aliasing), and the ink is
9
+ * drawn into the same buffer with a depth test, so an outline never shows
10
+ * through what is in front of it. Deterministic: the same frame gives the
11
+ * same bytes anywhere.
12
+ *
13
+ * Layers keep their meaning: a lower layer is drawn first and a higher one
14
+ * paints over it whatever the depths (the depth buffer is cleared between
15
+ * layers). Objects drawn whole with the canvas API (characters in their pen
16
+ * looks, lines, trails) go on top of the meshes, as on the WebGL2 renderer's
17
+ * overlay; solid characters are meshes and sort by depth.
18
+ */
19
+ export interface RasterImage {
20
+ width: number;
21
+ height: number;
22
+ /** RGBA bytes, row by row */
23
+ data: Uint8ClampedArray;
24
+ /** The nearest depth drawn at each pixel, metres; Infinity where nothing was */
25
+ depth: Float32Array;
26
+ }
27
+ export interface RasterOptions {
28
+ /** Start from these pixels instead of the background (what was on the canvas under a transparent scene) */
29
+ under?: Uint8ClampedArray;
30
+ }
31
+ /** Rasterise a resolved frame's triangles and ink into a pixel buffer with a depth per pixel. */
32
+ export declare function rasterizeResolvedScene(frame: ResolvedScene3D, options?: RasterOptions): RasterImage;
33
+ /** Draw a resolved frame on `ctx` through the depth buffer, then its drawables on top. */
34
+ export declare function drawResolvedSceneWithDepth(ctx: CanvasRenderingContext2D, frame: ResolvedScene3D): void;
35
+ /** The depth-buffered renderer, for the adapter: `new Scene3DAdapter(new SoftwareRenderer(ctx), …)`. */
36
+ export declare class SoftwareRenderer implements Renderer3D {
37
+ private readonly ctx;
38
+ constructor(ctx: CanvasRenderingContext2D);
39
+ render(frame: ResolvedScene3D): void;
40
+ }