@softure-ai/marketing-kit 0.33.0 → 0.35.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 (93) hide show
  1. package/CHANGELOG.md +53 -0
  2. package/NOTICE +6 -0
  3. package/README.md +39 -0
  4. package/dist/config/schema.d.ts +8 -0
  5. package/dist/config/schema.d.ts.map +1 -1
  6. package/dist/config/schema.js +1 -1
  7. package/dist/config/schema.js.map +1 -1
  8. package/dist/footage/camera.d.ts +67 -0
  9. package/dist/footage/camera.d.ts.map +1 -0
  10. package/dist/footage/camera.js +89 -0
  11. package/dist/footage/camera.js.map +1 -0
  12. package/dist/footage/compose.d.ts +7 -1
  13. package/dist/footage/compose.d.ts.map +1 -1
  14. package/dist/footage/compose.js +45 -10
  15. package/dist/footage/compose.js.map +1 -1
  16. package/dist/footage/draft-overlays.d.ts +6 -0
  17. package/dist/footage/draft-overlays.d.ts.map +1 -1
  18. package/dist/footage/draft-overlays.js +194 -9
  19. package/dist/footage/draft-overlays.js.map +1 -1
  20. package/dist/footage/draft.d.ts +21 -2
  21. package/dist/footage/draft.d.ts.map +1 -1
  22. package/dist/footage/draft.js +70 -31
  23. package/dist/footage/draft.js.map +1 -1
  24. package/dist/footage/drawn-transitions.d.ts +63 -0
  25. package/dist/footage/drawn-transitions.d.ts.map +1 -0
  26. package/dist/footage/drawn-transitions.js +177 -0
  27. package/dist/footage/drawn-transitions.js.map +1 -0
  28. package/dist/footage/edl.d.ts +39 -0
  29. package/dist/footage/edl.d.ts.map +1 -1
  30. package/dist/footage/edl.js +48 -1
  31. package/dist/footage/edl.js.map +1 -1
  32. package/dist/footage/film.d.ts +4 -3
  33. package/dist/footage/film.d.ts.map +1 -1
  34. package/dist/footage/film.js +3 -2
  35. package/dist/footage/film.js.map +1 -1
  36. package/dist/footage/hand-font.d.ts +16 -0
  37. package/dist/footage/hand-font.d.ts.map +1 -0
  38. package/dist/footage/hand-font.js +43 -0
  39. package/dist/footage/hand-font.js.map +1 -0
  40. package/dist/footage/overlay-html.d.ts +1 -0
  41. package/dist/footage/overlay-html.d.ts.map +1 -1
  42. package/dist/footage/overlay-html.js +138 -9
  43. package/dist/footage/overlay-html.js.map +1 -1
  44. package/dist/footage/overlay-motion.d.ts +35 -0
  45. package/dist/footage/overlay-motion.d.ts.map +1 -1
  46. package/dist/footage/overlay-motion.js +45 -0
  47. package/dist/footage/overlay-motion.js.map +1 -1
  48. package/dist/footage/overlay-schema.d.ts +57 -8
  49. package/dist/footage/overlay-schema.d.ts.map +1 -1
  50. package/dist/footage/overlay-schema.js +87 -21
  51. package/dist/footage/overlay-schema.js.map +1 -1
  52. package/dist/footage/overlays.d.ts +127 -1
  53. package/dist/footage/overlays.d.ts.map +1 -1
  54. package/dist/footage/overlays.js +277 -12
  55. package/dist/footage/overlays.js.map +1 -1
  56. package/dist/footage/picture.d.ts +8 -2
  57. package/dist/footage/picture.d.ts.map +1 -1
  58. package/dist/footage/picture.js +41 -15
  59. package/dist/footage/picture.js.map +1 -1
  60. package/dist/footage/pipeline.d.ts.map +1 -1
  61. package/dist/footage/pipeline.js +7 -1
  62. package/dist/footage/pipeline.js.map +1 -1
  63. package/dist/footage/tools.d.ts +1 -1
  64. package/dist/footage/tools.d.ts.map +1 -1
  65. package/dist/footage/tools.js +1 -1
  66. package/dist/footage/tools.js.map +1 -1
  67. package/dist/index.d.ts +8 -5
  68. package/dist/index.d.ts.map +1 -1
  69. package/dist/index.js +8 -5
  70. package/dist/index.js.map +1 -1
  71. package/fonts/Caveat-SemiBold-Latin.ttf +0 -0
  72. package/fonts/LICENSE-Caveat.txt +93 -0
  73. package/fonts/README.md +14 -0
  74. package/package.json +1 -1
  75. package/schema/edl.schema.json +108 -13
  76. package/schema/marketing.schema.json +10 -2
  77. package/src/config/schema.ts +1 -1
  78. package/src/footage/camera.ts +129 -0
  79. package/src/footage/compose.ts +42 -11
  80. package/src/footage/draft-overlays.ts +223 -7
  81. package/src/footage/draft.ts +83 -32
  82. package/src/footage/drawn-transitions.ts +214 -0
  83. package/src/footage/edl.ts +45 -1
  84. package/src/footage/film.ts +3 -2
  85. package/src/footage/hand-font.ts +47 -0
  86. package/src/footage/overlay-html.ts +145 -8
  87. package/src/footage/overlay-motion.ts +49 -0
  88. package/src/footage/overlay-schema.ts +100 -23
  89. package/src/footage/overlays.ts +332 -15
  90. package/src/footage/picture.ts +48 -17
  91. package/src/footage/pipeline.ts +7 -1
  92. package/src/footage/tools.ts +1 -1
  93. package/src/index.ts +56 -0
@@ -0,0 +1,93 @@
1
+ Copyright 2014 The Caveat Project Authors (https://github.com/googlefonts/caveat)
2
+
3
+ This Font Software is licensed under the SIL Open Font License, Version 1.1.
4
+ This license is copied below, and is also available with a FAQ at:
5
+ http://scripts.sil.org/OFL
6
+
7
+
8
+ -----------------------------------------------------------
9
+ SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
10
+ -----------------------------------------------------------
11
+
12
+ PREAMBLE
13
+ The goals of the Open Font License (OFL) are to stimulate worldwide
14
+ development of collaborative font projects, to support the font creation
15
+ efforts of academic and linguistic communities, and to provide a free and
16
+ open framework in which fonts may be shared and improved in partnership
17
+ with others.
18
+
19
+ The OFL allows the licensed fonts to be used, studied, modified and
20
+ redistributed freely as long as they are not sold by themselves. The
21
+ fonts, including any derivative works, can be bundled, embedded,
22
+ redistributed and/or sold with any software provided that any reserved
23
+ names are not used by derivative works. The fonts and derivatives,
24
+ however, cannot be released under any other type of license. The
25
+ requirement for fonts to remain under this license does not apply
26
+ to any document created using the fonts or their derivatives.
27
+
28
+ DEFINITIONS
29
+ "Font Software" refers to the set of files released by the Copyright
30
+ Holder(s) under this license and clearly marked as such. This may
31
+ include source files, build scripts and documentation.
32
+
33
+ "Reserved Font Name" refers to any names specified as such after the
34
+ copyright statement(s).
35
+
36
+ "Original Version" refers to the collection of Font Software components as
37
+ distributed by the Copyright Holder(s).
38
+
39
+ "Modified Version" refers to any derivative made by adding to, deleting,
40
+ or substituting -- in part or in whole -- any of the components of the
41
+ Original Version, by changing formats or by porting the Font Software to a
42
+ new environment.
43
+
44
+ "Author" refers to any designer, engineer, programmer, technical
45
+ writer or other person who contributed to the Font Software.
46
+
47
+ PERMISSION & CONDITIONS
48
+ Permission is hereby granted, free of charge, to any person obtaining
49
+ a copy of the Font Software, to use, study, copy, merge, embed, modify,
50
+ redistribute, and sell modified and unmodified copies of the Font
51
+ Software, subject to the following conditions:
52
+
53
+ 1) Neither the Font Software nor any of its individual components,
54
+ in Original or Modified Versions, may be sold by itself.
55
+
56
+ 2) Original or Modified Versions of the Font Software may be bundled,
57
+ redistributed and/or sold with any software, provided that each copy
58
+ contains the above copyright notice and this license. These can be
59
+ included either as stand-alone text files, human-readable headers or
60
+ in the appropriate machine-readable metadata fields within text or
61
+ binary files as long as those fields can be easily viewed by the user.
62
+
63
+ 3) No Modified Version of the Font Software may use the Reserved Font
64
+ Name(s) unless explicit written permission is granted by the corresponding
65
+ Copyright Holder. This restriction only applies to the primary font name as
66
+ presented to the users.
67
+
68
+ 4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
69
+ Software shall not be used to promote, endorse or advertise any
70
+ Modified Version, except to acknowledge the contribution(s) of the
71
+ Copyright Holder(s) and the Author(s) or with their explicit written
72
+ permission.
73
+
74
+ 5) The Font Software, modified or unmodified, in part or in whole,
75
+ must be distributed entirely under this license, and must not be
76
+ distributed under any other license. The requirement for fonts to
77
+ remain under this license does not apply to any document created
78
+ using the Font Software.
79
+
80
+ TERMINATION
81
+ This license becomes null and void if any of the above conditions are
82
+ not met.
83
+
84
+ DISCLAIMER
85
+ THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
86
+ EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
87
+ MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
88
+ OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
89
+ COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
90
+ INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
91
+ DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
92
+ FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
93
+ OTHER DEALINGS IN THE FONT SOFTWARE.
package/fonts/README.md CHANGED
@@ -10,3 +10,17 @@ pyftsubset DejaVuSans-Bold.ttf --unicodes="U+0020-007E,U+00A0-017F,U+2010-2027,U
10
10
  ```
11
11
 
12
12
  Licence: [LICENSE-DejaVu.txt](LICENSE-DejaVu.txt) (the Bitstream Vera licence; DejaVu changes are in the public domain).
13
+
14
+ `Caveat-SemiBold-Latin.ttf` is the kit's handwriting (`HAND_FONT`): a note card and an end word are written in it. It
15
+ is [Caveat](https://github.com/googlefonts/caveat) as a static SemiBold instance (weight 600 of the variable font,
16
+ named back to family `Caveat`, style `Regular`) subset to the same characters as the caption font, with its contextual
17
+ alternates kept:
18
+
19
+ ```bash
20
+ fonttools varLib.instancer Caveat[wght].ttf wght=600 --output Caveat-SemiBold.ttf
21
+ # then set name IDs 1, 2, 4 and 6 to Caveat / Regular / Caveat / Caveat-Regular
22
+ pyftsubset Caveat-SemiBold.ttf --unicodes="U+0020-007E,U+00A0-017F,U+2010-2027,U+2030-203A,U+20AC,U+2122" \
23
+ --layout-features='kern,liga,calt' --output-file=Caveat-SemiBold-Latin.ttf
24
+ ```
25
+
26
+ Licence: [LICENSE-Caveat.txt](LICENSE-Caveat.txt) (SIL Open Font License 1.1).
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@softure-ai/marketing-kit",
3
- "version": "0.33.0",
3
+ "version": "0.35.0",
4
4
  "description": "SOFTURE AI marketing kit: a CLI that turns a project's real app into a vertical film (cached voiceover, frame-by-frame recording, HTML composition, hyperframes render) plus per-platform post copy and OG images.",
5
5
  "license": "MIT",
6
6
  "type": "module",
@@ -44,9 +44,13 @@
44
44
  "cut",
45
45
  "fade",
46
46
  "zoom",
47
- "whoosh"
47
+ "whoosh",
48
+ "whip",
49
+ "card",
50
+ "paper",
51
+ "stutter"
48
52
  ],
49
- "description": "How the segment starts: cut, fade (a cross-fade from the segment before), zoom (a punch-in) or whoosh."
53
+ "description": "How the segment starts: cut, fade (a cross-fade from the segment before), zoom (a punch-in), whoosh, whip (a whip pan with motion blur, 14 frames), card (the shot grows from a small card, 13 frames), paper (a torn-paper wipe, 12 frames) or stutter (5 frames wide, then tight)."
50
54
  },
51
55
  "motion": {
52
56
  "type": "string",
@@ -56,6 +60,73 @@
56
60
  ],
57
61
  "description": "kenburns: a slow zoom over the segment; none: still."
58
62
  },
63
+ "camera": {
64
+ "type": "object",
65
+ "properties": {
66
+ "from": {
67
+ "type": "number",
68
+ "minimum": 1,
69
+ "maximum": 1.6,
70
+ "description": "The scale the segment starts at: 1 is the full frame, up to 1.6."
71
+ },
72
+ "to": {
73
+ "type": "number",
74
+ "minimum": 1,
75
+ "maximum": 1.6,
76
+ "description": "The scale it ends at; equal to from: a still framing."
77
+ },
78
+ "ease": {
79
+ "type": "string",
80
+ "enum": [
81
+ "linear",
82
+ "out"
83
+ ],
84
+ "description": "linear: one steady speed; out: slows down to its end."
85
+ },
86
+ "seconds": {
87
+ "description": "How long the move takes from the segment's start, then the picture holds; absent: the whole segment.",
88
+ "type": "number",
89
+ "exclusiveMinimum": 0,
90
+ "maximum": 120
91
+ },
92
+ "anchor": {
93
+ "description": "The point the zoom keeps still, such as the face's centre; absent: 50 % across, 42 % down.",
94
+ "type": "object",
95
+ "properties": {
96
+ "x": {
97
+ "type": "number",
98
+ "minimum": 0,
99
+ "maximum": 1,
100
+ "description": "Across the frame, 0 (left) to 1 (right)."
101
+ },
102
+ "y": {
103
+ "type": "number",
104
+ "minimum": 0,
105
+ "maximum": 1,
106
+ "description": "Down the frame, 0 (top) to 1 (bottom)."
107
+ }
108
+ },
109
+ "required": [
110
+ "x",
111
+ "y"
112
+ ],
113
+ "additionalProperties": false
114
+ }
115
+ },
116
+ "required": [
117
+ "from",
118
+ "to",
119
+ "ease"
120
+ ],
121
+ "additionalProperties": false,
122
+ "description": "The segment's framing and a slow move over it (a push-in, a pull-out, a settle); drawn alike by the draft and the render."
123
+ },
124
+ "fadeFrames": {
125
+ "description": "A fade cut's own length in frames at 30 fps (1-30); absent: the film's fadeFrames. Only on a fade.",
126
+ "type": "integer",
127
+ "minimum": 1,
128
+ "maximum": 30
129
+ },
59
130
  "audio": {
60
131
  "description": "Sound from another clip or span: a J- or L-cut, or b-roll over speech. Without it, the segment plays its own sound.",
61
132
  "type": "object",
@@ -140,9 +211,11 @@
140
211
  "search_bar",
141
212
  "place_card",
142
213
  "counter",
143
- "date_stamp"
214
+ "date_stamp",
215
+ "note",
216
+ "end_word"
144
217
  ],
145
- "description": "punch_in (an emphasis zoom on a word), keyword, lower_third, list, arrow, highlight, hook_title, search_bar, place_card, counter or date_stamp."
218
+ "description": "punch_in (an emphasis zoom on a word), keyword, lower_third, list, arrow, highlight, hook_title, search_bar, place_card, counter, date_stamp, note or end_word."
146
219
  },
147
220
  "at_word": {
148
221
  "description": "The transcript word the overlay starts on (its start after the cut); give this or at.",
@@ -172,12 +245,12 @@
172
245
  },
173
246
  "duration": {
174
247
  "type": "number",
175
- "minimum": 1,
248
+ "minimum": 0.5,
176
249
  "maximum": 180,
177
- "description": "Seconds on screen (1-8; a hook_title up to 180)."
250
+ "description": "Seconds on screen (1-8; a hook_title up to 180; an end_word 0.5-2)."
178
251
  },
179
252
  "text": {
180
- "description": "The text: keyword (up to 24 characters), lower_third (40), hook_title (64, one or two lines), search_bar (40), place_card title (28) or date_stamp (24).",
253
+ "description": "The text: keyword (up to 24 characters), lower_third (40), hook_title (64, one or two lines), search_bar (40), place_card title (28), date_stamp (24), note (72) or end_word (16, one line).",
181
254
  "type": "string",
182
255
  "minLength": 1
183
256
  },
@@ -303,7 +376,7 @@
303
376
  ]
304
377
  },
305
378
  "side": {
306
- "description": "The side a keyword, lower third, list or date stamp sits on.",
379
+ "description": "The side a keyword, lower third, list, date stamp or note sits on.",
307
380
  "type": "string",
308
381
  "enum": [
309
382
  "left",
@@ -311,7 +384,7 @@
311
384
  ]
312
385
  },
313
386
  "position": {
314
- "description": "top, middle or bottom of the room above the captions: keyword, search_bar, place_card, counter (any), lower_third (top or bottom), list (top or middle).",
387
+ "description": "top, middle or bottom of the room above the captions: keyword, search_bar, place_card, counter (any), lower_third (top or bottom), list and note (top or middle).",
315
388
  "type": "string",
316
389
  "enum": [
317
390
  "top",
@@ -320,7 +393,7 @@
320
393
  ]
321
394
  },
322
395
  "entrance": {
323
- "description": "fade, slide, type (text typed in letter by letter), none, pop (92 % to 100 %, no overshoot), rise (up from 5 % of the height), blur (blurred to sharp) or wipe (card revealed from the left in the accent, then the text); without it the kind's own. Never a bounce.",
396
+ "description": "fade, slide, type (text typed in letter by letter), none, pop (92 % to 100 %, no overshoot), rise (up from 5 % of the height), blur (blurred to sharp), wipe (card revealed from the left in the accent, then the text) or drop (hook_title, keyword, end_word: letters fall into place one by one, never below their line); without it the kind's own. Never a bounce.",
324
397
  "type": "string",
325
398
  "enum": [
326
399
  "fade",
@@ -330,7 +403,8 @@
330
403
  "pop",
331
404
  "rise",
332
405
  "blur",
333
- "wipe"
406
+ "wipe",
407
+ "drop"
334
408
  ]
335
409
  },
336
410
  "exit": {
@@ -391,11 +465,12 @@
391
465
  ]
392
466
  },
393
467
  "align": {
394
- "description": "center (the default) or left: how a hook_title's or a place_card's lines sit in their card.",
468
+ "description": "center (the default) or left: how a hook_title's or a place_card's lines sit in their card; left, center or right: where a keyword's card sits across its room (in place of side).",
395
469
  "type": "string",
396
470
  "enum": [
471
+ "left",
397
472
  "center",
398
- "left"
473
+ "right"
399
474
  ]
400
475
  },
401
476
  "subtitle_size": {
@@ -438,6 +513,26 @@
438
513
  "underline": {
439
514
  "description": "A keyword only: an accent bar drawn under the word after it enters.",
440
515
  "type": "boolean"
516
+ },
517
+ "backdrop": {
518
+ "description": "A hook_title or keyword only: card (the default) or highlight (each line on its own tight box in the card colour; typed in, the box grows with the letters).",
519
+ "type": "string",
520
+ "enum": [
521
+ "card",
522
+ "highlight"
523
+ ]
524
+ },
525
+ "note_style": {
526
+ "description": "A note only: card (the default: a tilted paper card, handwritten words appearing as they are said) or strip (a torn paper strip that grows in, then types its text in capitals).",
527
+ "type": "string",
528
+ "enum": [
529
+ "card",
530
+ "strip"
531
+ ]
532
+ },
533
+ "tick": {
534
+ "description": "A note only: a hand-drawn tick after its last word.",
535
+ "type": "boolean"
441
536
  }
442
537
  },
443
538
  "additionalProperties": false
@@ -2777,18 +2777,26 @@
2777
2777
  "fade",
2778
2778
  "zoom",
2779
2779
  "whoosh",
2780
+ "whip",
2781
+ "card",
2782
+ "paper",
2783
+ "stutter",
2780
2784
  "auto"
2781
2785
  ]
2782
2786
  },
2783
2787
  "clip": {
2784
2788
  "default": "cut",
2785
- "description": "A cut from one clip to the next: cut (the default), fade, zoom or whoosh.",
2789
+ "description": "A cut from one clip to the next: cut (the default), fade, zoom, whoosh, whip, card, paper or stutter.",
2786
2790
  "type": "string",
2787
2791
  "enum": [
2788
2792
  "cut",
2789
2793
  "fade",
2790
2794
  "zoom",
2791
- "whoosh"
2795
+ "whoosh",
2796
+ "whip",
2797
+ "card",
2798
+ "paper",
2799
+ "stutter"
2792
2800
  ]
2793
2801
  },
2794
2802
  "autoThreshold": {
@@ -546,7 +546,7 @@ const footageSchema = z
546
546
  .describe(
547
547
  "A cut inside one talking clip: cut (the default), fade, zoom (a punch-in), whoosh, or auto (zoom when the frames on both sides look alike, fade when the camera moved; measured when the cut is built).",
548
548
  ),
549
- clip: z.enum(CUT_TRANSITIONS).default("cut").describe("A cut from one clip to the next: cut (the default), fade, zoom or whoosh."),
549
+ clip: z.enum(CUT_TRANSITIONS).default("cut").describe("A cut from one clip to the next: cut (the default), fade, zoom, whoosh, whip, card, paper or stutter."),
550
550
  autoThreshold: z
551
551
  .number()
552
552
  .min(0)
@@ -0,0 +1,129 @@
1
+ import { z } from "zod";
2
+
3
+ import { FOOTAGE_FPS } from "./normalize.js";
4
+
5
+ /**
6
+ * A segment's camera: the framing it is shown at and a slow move over it, drawn alike by the draft (ffmpeg `zoompan`
7
+ * about the anchor) and the render (a GSAP scale tween with the anchor as `transform-origin`). Captions and overlays
8
+ * are drawn over the moved picture, so a move never moves them.
9
+ *
10
+ * - A still framing: `from` equal to `to` (1 is the full frame, 1.5 a tight crop).
11
+ * - A push-in: `from` below `to`; a pull-out or a settle: `from` above `to`.
12
+ * - `ease`: `linear` keeps one speed (a slow drift); `out` slows down to its end (`power1.out`, `1 - (1 - t)^2`).
13
+ * - `seconds`: how long the move takes from the segment's start, then the picture holds; absent: the whole segment.
14
+ * - `anchor`: the point of the frame the zoom keeps still (fractions of the frame; a face's centre keeps the face in
15
+ * the picture); absent: the kit's zoom origin (`CAMERA_ORIGIN`). The crop never leaves the source frame.
16
+ */
17
+ export interface EdlCamera {
18
+ from: number;
19
+ to: number;
20
+ ease: CameraEase;
21
+ seconds?: number;
22
+ anchor?: CameraAnchor;
23
+ }
24
+
25
+ export const CAMERA_EASES = ["linear", "out"] as const;
26
+
27
+ export type CameraEase = (typeof CAMERA_EASES)[number];
28
+
29
+ export interface CameraAnchor {
30
+ x: number;
31
+ y: number;
32
+ }
33
+
34
+ /** The point a zoom keeps still when it names none: the composition's `transform-origin: 50% 42%`. */
35
+ export const CAMERA_ORIGIN: CameraAnchor = { x: 0.5, y: 0.42 };
36
+
37
+ /** The tightest framing a camera may take: past it a 1080x1920 source shows its pixels. */
38
+ export const MAX_CAMERA_SCALE = 1.6;
39
+
40
+ const scaleSchema = z.number().min(1).max(MAX_CAMERA_SCALE);
41
+
42
+ export const cameraSchema = z
43
+ .strictObject({
44
+ from: scaleSchema.describe(`The scale the segment starts at: 1 is the full frame, up to ${String(MAX_CAMERA_SCALE)}.`),
45
+ to: scaleSchema.describe("The scale it ends at; equal to from: a still framing."),
46
+ ease: z.enum(CAMERA_EASES).describe("linear: one steady speed; out: slows down to its end."),
47
+ seconds: z.number().positive().max(120).optional().describe("How long the move takes from the segment's start, then the picture holds; absent: the whole segment."),
48
+ anchor: z
49
+ .strictObject({
50
+ x: z.number().min(0).max(1).describe("Across the frame, 0 (left) to 1 (right)."),
51
+ y: z.number().min(0).max(1).describe("Down the frame, 0 (top) to 1 (bottom)."),
52
+ })
53
+ .optional()
54
+ .describe("The point the zoom keeps still, such as the face's centre; absent: 50 % across, 42 % down."),
55
+ })
56
+ .describe("The segment's framing and a slow move over it (a push-in, a pull-out, a settle); drawn alike by the draft and the render.");
57
+
58
+ const r4 = (value: number): number => Math.round(value * 10000) / 10000 || 0;
59
+
60
+ /** The point a camera keeps still. */
61
+ export function getCameraOrigin(camera: Pick<EdlCamera, "anchor"> | undefined): CameraAnchor {
62
+ return camera?.anchor ?? CAMERA_ORIGIN;
63
+ }
64
+
65
+ /** Whether a camera changes its scale over the segment (a still framing does not). */
66
+ export function isCameraMoving(camera: EdlCamera | undefined): boolean {
67
+ return camera !== undefined && camera.from !== camera.to;
68
+ }
69
+
70
+ /** The frames a camera's move takes: its `seconds` (or the segment's length), at most the segment's frames, at least one. */
71
+ export function getCameraMoveFrames(camera: EdlCamera, segmentSeconds: number): number {
72
+ const segmentFrames = Math.max(1, Math.round(segmentSeconds * FOOTAGE_FPS));
73
+ return Math.max(1, Math.min(segmentFrames, Math.round((camera.seconds ?? segmentSeconds) * FOOTAGE_FPS)));
74
+ }
75
+
76
+ /** The camera's move in seconds, as the render's tween plays it (`getCameraMoveFrames` in film frames). */
77
+ export function getCameraMoveSeconds(camera: EdlCamera, segmentSeconds: number): number {
78
+ return Math.round((getCameraMoveFrames(camera, segmentSeconds) / FOOTAGE_FPS) * 1000) / 1000;
79
+ }
80
+
81
+ /** The GSAP ease of a camera's move: `none` for `linear`, `power1.out` (`1 - (1 - t)^2`) for `out`. */
82
+ export function getCameraGsapEase(ease: CameraEase): string {
83
+ return ease === "linear" ? "none" : "power1.out";
84
+ }
85
+
86
+ /** The camera's scale as an ffmpeg expression of the segment's frame number `variable`, as the render's tween eases it. */
87
+ export function getCameraScaleExpression(camera: EdlCamera, frames: number, variable = "on"): string {
88
+ if (!isCameraMoving(camera)) return String(camera.from);
89
+ const progress = `min(${variable}/${String(frames)},1)`;
90
+ const eased = camera.ease === "linear" ? progress : `(1-pow(1-${progress},2))`;
91
+ return `${String(camera.from)}+(${String(r4(camera.to - camera.from))})*${eased}`;
92
+ }
93
+
94
+ /** The camera's scale `frame` frames into its segment, as the draft's expression and the render's tween give it. */
95
+ export function getCameraScaleAt(camera: EdlCamera, frames: number, frame: number): number {
96
+ const t = Math.min(Math.max(frame / frames, 0), 1);
97
+ const eased = camera.ease === "linear" ? t : 1 - (1 - t) ** 2;
98
+ return r4(camera.from + (camera.to - camera.from) * eased);
99
+ }
100
+
101
+ /** The anchor as a CSS `transform-origin`. */
102
+ export function toTransformOrigin(anchor: CameraAnchor): string {
103
+ return `${String(r4(anchor.x * 100))}% ${String(r4(anchor.y * 100))}%`;
104
+ }
105
+
106
+ /** Whether a camera shows the full frame, still: drawn as no camera at all. */
107
+ function isFullFrame(camera: EdlCamera | undefined): boolean {
108
+ return camera === undefined || (camera.from === 1 && camera.to === 1);
109
+ }
110
+
111
+ /**
112
+ * Whether two cameras show the same framing: both the full frame, still (absent, or `from` and `to` 1), or the same
113
+ * scales, ease, length and anchor.
114
+ */
115
+ export function isSameCamera(a: EdlCamera | undefined, b: EdlCamera | undefined): boolean {
116
+ if (isFullFrame(a) && isFullFrame(b)) return true;
117
+ if (a === undefined || b === undefined) return false;
118
+ const [pa, pb] = [getCameraOrigin(a), getCameraOrigin(b)];
119
+ return a.from === b.from && a.to === b.to && a.ease === b.ease && a.seconds === b.seconds && pa.x === pb.x && pa.y === pb.y;
120
+ }
121
+
122
+ /** A camera in a few words, for `diffEdl` ("push 1 → 1.15 linear"). */
123
+ export function describeCamera(camera: EdlCamera | undefined): string {
124
+ if (camera === undefined) return "none";
125
+ const kind = camera.from === camera.to ? "framing" : camera.from < camera.to ? "push" : "pull";
126
+ const scales = camera.from === camera.to ? String(camera.from) : `${String(camera.from)} → ${String(camera.to)} ${camera.ease}`;
127
+ const anchor = camera.anchor === undefined ? "" : ` at ${String(r4(camera.anchor.x))},${String(r4(camera.anchor.y))}`;
128
+ return `${kind} ${scales}${camera.seconds === undefined ? "" : ` over ${String(camera.seconds)} s`}${anchor}`;
129
+ }
@@ -6,7 +6,9 @@ import { CAPTION_LINE_HEIGHT, getCaptionPillCss, getCaptionPositionCss, type Cap
6
6
  import type { TimedWord } from "../voice/voiceover.js";
7
7
  import { CAPTION_HIGHLIGHT_BOX_PADDING_EM, CAPTION_HIGHLIGHT_BOX_RADIUS, CAPTION_HIGHLIGHT_SECONDS, CAPTION_UNDERLINE_EM, getCaptionEntranceTween, getCaptionHighlight } from "./caption-highlight.js";
8
8
  import { CAPTION_SAFE_ZONES, getCaptionChunkLayouts, getCaptionSpans, getFootageCaptionChunks, isSameCaptionPlace, type CaptionSpan } from "./captions.js";
9
- import { getEdlDuration, getSegmentStarts, type Edl } from "./edl.js";
9
+ import { getCameraGsapEase, getCameraMoveSeconds, getCameraOrigin, isCameraMoving, toTransformOrigin } from "./camera.js";
10
+ import { STUTTER_FRAMES, STUTTER_SCALE } from "./drawn-transitions.js";
11
+ import { getEdlDuration, getSegmentStarts, type Edl, type EdlSegment } from "./edl.js";
10
12
  import {
11
13
  CAPTION_MIN_FONT_SCALE,
12
14
  DEFAULT_EDIT,
@@ -30,7 +32,8 @@ const r3 = (value: number): number => Math.round(value * 1000) / 1000 || 0;
30
32
  * The HyperFrames composition of a footage film (the same 0.8.85 contract as `composeFilm`): one `<video>` clip per
31
33
  * EDL segment over the normalized clip with its media start, the transitions (`fade` cross-fades from the segment
32
34
  * before over `fadeFrames`, `zoom` punches in by `zoomPercent` on alternate jump cuts, eased over `zoomEaseFrames`, `whoosh` plays the whoosh
33
- * sound), a slow zoom on `kenburns` segments, the captions (plain phrases, or the word-highlight pill), the end card
35
+ * sound, `stutter` holds the full frame for `STUTTER_FRAMES` and then its tight framing; the drawn `whip`, `card` and
36
+ * `paper` are in the picture, and the per-segment videos without one play them as plain cuts), a slow zoom on `kenburns` segments, the captions (plain phrases, or the word-highlight pill), the end card
34
37
  * over the cut's last frame (the full card, or the short logo card; its whoosh only with `isEndCardWhoosh`), the cut
35
38
  * speech track and the ducked music.
36
39
  */
@@ -93,16 +96,29 @@ export function getFootageFilmSeconds(film: Pick<FootageFilm, "endCard">, edl: E
93
96
  return r3(getEdlDuration(edl) + getEndCardSeconds(film.endCard));
94
97
  }
95
98
 
96
- /** The picture scale each segment starts at: `zoom` cuts alternate between punched in (`zoomPercent`) and back out. */
99
+ /**
100
+ * The picture scale each segment starts at: `zoom` cuts alternate between punched in (`zoomPercent`) and back out; a
101
+ * segment with a `camera` starts at its camera's `from`; a `stutter` holds its camera's framing or `STUTTER_SCALE`
102
+ * once its wide frames are over.
103
+ */
97
104
  export function getSegmentScales(edl: Edl, zoomPercent = DEFAULT_EDIT.zoomPercent): number[] {
98
105
  const scales: number[] = [];
99
106
  edl.segments.forEach((segment, index) => {
100
107
  const previous = scales[index - 1] ?? 1;
101
- scales.push(segment.transition === "zoom" && index > 0 ? (previous === 1 ? zoomPercent / 100 : 1) : 1);
108
+ if (segment.camera !== undefined) scales.push(segment.camera.from);
109
+ else if (segment.transition === "stutter") scales.push(STUTTER_SCALE);
110
+ else scales.push(segment.transition === "zoom" && index > 0 ? (previous === 1 ? zoomPercent / 100 : 1) : 1);
102
111
  });
103
112
  return scales;
104
113
  }
105
114
 
115
+ /** The frames a segment's cut cross-fades over: its own `fadeFrames` or the film's on a `fade` after the first segment, else 0. */
116
+ export function getSegmentFadeFrames(edl: Pick<Edl, "segments">, index: number, edit: Pick<FootageEdit, "fadeFrames">): number {
117
+ const segment: EdlSegment | undefined = edl.segments[index];
118
+ if (segment === undefined || index === 0 || segment.transition !== "fade") return 0;
119
+ return segment.fadeFrames ?? edit.fadeFrames;
120
+ }
121
+
106
122
  /**
107
123
  * The frames each segment's zoom eases over (`zoomEaseFrames`, at most the segment's own frames): a `zoom` cut after
108
124
  * the first segment that changes the scale and is not `kenburns` (its slow zoom owns the scale); 0 for every other.
@@ -110,7 +126,7 @@ export function getSegmentScales(edl: Edl, zoomPercent = DEFAULT_EDIT.zoomPercen
110
126
  export function getSegmentZoomEases(edl: Edl, edit: Pick<FootageEdit, "zoomPercent" | "zoomEaseFrames">): number[] {
111
127
  const scales = getSegmentScales(edl, edit.zoomPercent);
112
128
  return edl.segments.map((segment, index) => {
113
- const isEased = edit.zoomEaseFrames > 0 && index > 0 && segment.transition === "zoom" && segment.motion !== "kenburns" && scales[index - 1] !== scales[index];
129
+ const isEased = edit.zoomEaseFrames > 0 && index > 0 && segment.transition === "zoom" && segment.motion !== "kenburns" && segment.camera === undefined && scales[index - 1] !== scales[index];
114
130
  return isEased ? Math.max(1, Math.min(edit.zoomEaseFrames, Math.floor((segment.end - segment.start) * FOOTAGE_FPS))) : 0;
115
131
  });
116
132
  }
@@ -156,7 +172,10 @@ export function composeFootage(input: FootageComposeInput): string {
156
172
  const edit = getFootageEdit(film);
157
173
  const scales = getSegmentScales(edl, edit.zoomPercent);
158
174
  const eases = getSegmentZoomEases(edl, edit);
159
- const fadeSeconds = r3(edit.fadeFrames / FOOTAGE_FPS);
175
+ const fadeSecondsAt = (index: number): number => r3(getSegmentFadeFrames(edl, index, edit) / FOOTAGE_FPS);
176
+ // A film with a camera anchors its zooms per segment; one without keeps the stylesheet's origin (and its markup).
177
+ const hasCamera = edl.segments.some((segment) => segment.camera !== undefined);
178
+ const originOf = (segment: EdlSegment): string => toTransformOrigin(getCameraOrigin(segment.camera));
160
179
  const kenBurnsScale = 1 + (edit.kenBurnsPercent > 0 ? edit.kenBurnsPercent : HAND_KEN_BURNS_PERCENT) / 100;
161
180
 
162
181
  const picture = assets.picture;
@@ -165,12 +184,12 @@ export function composeFootage(input: FootageComposeInput): string {
165
184
  ? edl.segments.map((segment, index) => {
166
185
  const src = assets.clips[segment.clip];
167
186
  if (src === undefined) throw new Error(`The EDL names clip "${segment.clip}", which the film has no file for.`);
168
- const next = edl.segments[index + 1];
169
- const tail = next?.transition === "fade" ? fadeSeconds : 0;
187
+ const tail = fadeSecondsAt(index + 1);
170
188
  const start = starts[index] as number;
171
189
  const duration = r3(segment.end - segment.start + tail);
172
190
  const scale = scales[index] as number;
173
- const style = scale === 1 ? "" : ` style="transform:scale(${scale})"`;
191
+ const origin = segment.camera === undefined ? "" : `;transform-origin:${originOf(segment)}`;
192
+ const style = scale === 1 && origin === "" ? "" : ` style="transform:scale(${scale})${origin}"`;
174
193
  return `<video id="seg${index}" class="clip shot" src="${escapeHtml(src)}" data-start="${start}" data-media-start="${segment.start}" data-duration="${duration}"${style} muted playsinline></video>`;
175
194
  })
176
195
  : [`<video id="picture" class="clip shot" src="${escapeHtml(picture)}" data-start="0" data-media-start="0" data-duration="${cutEnd}" muted playsinline></video>`];
@@ -181,9 +200,21 @@ export function composeFootage(input: FootageComposeInput): string {
181
200
  const scale = scales[index] as number;
182
201
  const target = picture === undefined ? `#seg${index}` : "#picture";
183
202
  // One video carries every segment: each one sets the zoom it starts at (a fade is already in the picture).
184
- if (picture !== undefined) tweens.push(`tl.set("#picture", { scale: ${scale} }, ${start});`);
203
+ const isStutter = segment.transition === "stutter";
204
+ // A stutter shows the full frame first, then cuts to its framing.
205
+ const opening = isStutter ? 1 : scale;
206
+ if (picture !== undefined) tweens.push(hasCamera ? `tl.set("#picture", { scale: ${opening}, transformOrigin: "${originOf(segment)}" }, ${start});` : `tl.set("#picture", { scale: ${opening} }, ${start});`);
207
+ if (isStutter) {
208
+ if (picture === undefined) tweens.push(`tl.set("${target}", { scale: 1 }, ${start});`);
209
+ tweens.push(`tl.set("${target}", { scale: ${scale} }, ${r3(start + STUTTER_FRAMES / FOOTAGE_FPS)});`);
210
+ }
185
211
  if (picture === undefined && segment.transition === "fade" && index > 0) {
186
- tweens.push(`tl.fromTo("${target}", { opacity: 0 }, { opacity: 1, duration: ${fadeSeconds}, ease: "none", immediateRender: false }, ${start});`);
212
+ tweens.push(`tl.fromTo("${target}", { opacity: 0 }, { opacity: 1, duration: ${fadeSecondsAt(index)}, ease: "none", immediateRender: false }, ${start});`);
213
+ }
214
+ const { camera } = segment;
215
+ if (camera !== undefined && isCameraMoving(camera)) {
216
+ const seconds = getCameraMoveSeconds(camera, segment.end - segment.start);
217
+ tweens.push(`tl.fromTo("${target}", { scale: ${camera.from} }, { scale: ${camera.to}, duration: ${seconds}, ease: "${getCameraGsapEase(camera.ease)}", immediateRender: false }, ${start});`);
187
218
  }
188
219
  const ease = eases[index] as number;
189
220
  if (ease > 0) {