@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,214 @@
1
+ import type { Frame } from "./normalize.js";
2
+ import { FOOTAGE_FPS } from "./normalize.js";
3
+
4
+ /**
5
+ * Drawn transitions between two shots, the same frames in the draft (`draft.ts`) and the render's picture
6
+ * (`picture.ts`): both give the outgoing segment a tail that plays on under the incoming one, as a dissolve does, and
7
+ * blend the tail with the incoming head through `buildDrawnTransitionFilters`. Nothing is taken from outside the code:
8
+ * the paper's grain is ffmpeg's noise, its torn edge a sum of sines.
9
+ *
10
+ * - `whip`: the outgoing shot slides left faster and faster under a growing horizontal blur (8 frames), the incoming
11
+ * one slides in from the right still blurred, lands from 110 % and comes sharp (6 frames). No sound of its own.
12
+ * - `card`: the incoming shot appears in the middle as a small card (a quarter of the frame, tilted 3°, rounded
13
+ * corners) and grows over the outgoing one until it fills the frame, eased out.
14
+ * - `paper`: a paper grain settles over the outgoing shot (4 frames), then a torn edge opens from the middle onto the
15
+ * incoming one (8 frames).
16
+ *
17
+ * The `stutter` is not drawn here: it is a scale (the first `STUTTER_FRAMES` frames at the full frame, then the
18
+ * segment's tight framing), set where the other zooms are (`getSegmentScales`, the draft's zoom).
19
+ */
20
+
21
+ export const DRAWN_TRANSITIONS = ["whip", "card", "paper"] as const;
22
+
23
+ export type DrawnTransition = (typeof DRAWN_TRANSITIONS)[number];
24
+
25
+ /** Each drawn transition's length in frames at 30 fps (the reference reels, measured). */
26
+ export const DRAWN_TRANSITION_FRAMES: Readonly<Record<DrawnTransition, number>> = { whip: 14, card: 13, paper: 12 };
27
+
28
+ /** The whip's outgoing half; the rest of its frames are the incoming shot landing. */
29
+ export const WHIP_OUT_FRAMES = 8;
30
+
31
+ /** The paper's grain fade-in over the outgoing shot, before the tear opens. */
32
+ export const PAPER_FADE_FRAMES = 4;
33
+
34
+ /** How many frames a stutter shows the full frame before its tight framing. */
35
+ export const STUTTER_FRAMES = 5;
36
+
37
+ /** The stutter's tight framing when the segment sets no camera of its own. */
38
+ export const STUTTER_SCALE = 1.5;
39
+
40
+ /** How far the whip slides on each side, as a share of the frame's width. */
41
+ const WHIP_TRAVEL = 0.6;
42
+ /** The whip's horizontal blur on its outgoing frames, as a share of the frame's width (0: sharp). */
43
+ const WHIP_OUT_BLUR = [0, 0, 0, 0.002, 0.006, 0.014, 0.028, 0.05] as const;
44
+ /** The whip's blur on its incoming frames, falling to sharp. */
45
+ const WHIP_IN_BLUR = [0.042, 0.022, 0.01, 0.004, 0.0015, 0] as const;
46
+ /** The whip's landing zoom on the incoming shot. */
47
+ const WHIP_LANDING_SCALE = 1.1;
48
+
49
+ /** The card's first size (a share of the frame), tilt in radians (3°) and corner radius (a share of the width). */
50
+ const CARD_START_SCALE = 0.25;
51
+ const CARD_START_TILT = 0.0524;
52
+ const CARD_CORNER = 0.035;
53
+
54
+ /** The paper's colour, how strongly its grain multiplies the outgoing shot, how far the tear opens and its rim. */
55
+ const PAPER_COLOR = "0xEDE6D8";
56
+ const PAPER_STRENGTH = 0.55;
57
+ const PAPER_OPEN = 0.62;
58
+ const PAPER_RIM = 0.012;
59
+ /** The torn edge across the height: a sum of sines (amplitude as a share of the width, frequency, phase). */
60
+ const PAPER_TEAR: readonly (readonly [number, number, number])[] = [
61
+ [0.035, 31, 1.3],
62
+ [0.02, 83, 0.7],
63
+ [0.012, 197, 2.1],
64
+ [0.006, 421, 0.4],
65
+ ];
66
+ /** The paper's white at the torn rim (luma, limited range). */
67
+ const PAPER_RIM_LUMA = 232;
68
+
69
+ const r4 = (value: number): number => Math.round(value * 10000) / 10000 || 0;
70
+
71
+ /** Whether a transition is one of the drawn ones. */
72
+ export function isDrawnTransition(transition: string): transition is DrawnTransition {
73
+ return (DRAWN_TRANSITIONS as readonly string[]).includes(transition);
74
+ }
75
+
76
+ /** The frames the outgoing segment plays on under the incoming one: a fade's own or the film's, a drawn transition's own, else 0. */
77
+ export function getTransitionOverlapFrames(segment: { transition: string; fadeFrames?: number | undefined }, filmFadeFrames: number): number {
78
+ if (segment.transition === "fade") return segment.fadeFrames ?? filmFadeFrames;
79
+ return isDrawnTransition(segment.transition) ? DRAWN_TRANSITION_FRAMES[segment.transition] : 0;
80
+ }
81
+
82
+ export interface DrawnTransitionFiltersInput {
83
+ kind: DrawnTransition;
84
+ /** The outgoing tail's label: exactly the transition's frames, the frame's size, yuv420p at 30 fps. */
85
+ outgoing: string;
86
+ /** The incoming head's label, the same. */
87
+ incoming: string;
88
+ /** The label the blended frames go out on (as many frames, yuv420p, 30 fps). */
89
+ output: string;
90
+ frame: Frame;
91
+ /** A prefix for the graph's inner labels, unique in the graph. */
92
+ prefix: string;
93
+ }
94
+
95
+ /** The filter chains (to join with `;`) that blend an outgoing tail and an incoming head into the transition's frames. */
96
+ export function buildDrawnTransitionFilters(input: DrawnTransitionFiltersInput): string[] {
97
+ switch (input.kind) {
98
+ case "whip":
99
+ return buildWhipFilters(input);
100
+ case "card":
101
+ return buildCardFilters(input);
102
+ case "paper":
103
+ return buildPaperFilters(input);
104
+ }
105
+ }
106
+
107
+ /**
108
+ * The film's time base with every frame numbered on it, after a `trim`, a blend or a `concat`: each frame then has its
109
+ * place, so a `concat` lays the pieces end to end. (An `fps` filter here drops the last frame of a stream whose frames
110
+ * carry no duration, as `overlay`, `blend` and `interleave` leave them.)
111
+ */
112
+ export const FRAME_TIMING = `settb=1/${FOOTAGE_FPS},setpts=N`;
113
+
114
+ /** The closing filters every transition ends on: the film's pixel format, square pixels and frame rate. */
115
+ function closeStream(): string {
116
+ return `format=yuv420p,setsar=1,${FRAME_TIMING}`;
117
+ }
118
+
119
+ /** One `gblur` per frame of `sigmas` (shares of the width), horizontal only, on that frame alone; none for a sharp frame. */
120
+ function blurSteps(sigmas: readonly number[], width: number): string[] {
121
+ return sigmas.flatMap((share, frame) => (share > 0 ? [`gblur=sigma=${r4(share * width)}:sigmaV=0:enable='eq(n,${String(frame)})'`] : []));
122
+ }
123
+
124
+ function buildWhipFilters(input: DrawnTransitionFiltersInput): string[] {
125
+ const { width: w, height: h } = input.frame;
126
+ const p = input.prefix;
127
+ const inFrames = DRAWN_TRANSITION_FRAMES.whip - WHIP_OUT_FRAMES;
128
+ const last = WHIP_OUT_FRAMES - 1;
129
+ const land = inFrames - 1;
130
+ // The slide wraps the shot around (a strip of the shot beside itself), so the blur streaks never show an edge.
131
+ const out = [`hstack`, `crop=w=${w}:h=${h}:x='${w}*${WHIP_TRAVEL}*pow(n/${last},2)':y=0`, ...blurSteps(WHIP_OUT_BLUR, w), "setpts=PTS-STARTPTS", FRAME_TIMING];
132
+ const into = [
133
+ `hstack`,
134
+ `crop=w=${w}:h=${h}:x='${w}*(1-${WHIP_TRAVEL}*pow(1-(n+1)/${inFrames},2))':y=0`,
135
+ `zoompan=z='${WHIP_LANDING_SCALE}-${r4(WHIP_LANDING_SCALE - 1)}*(1-pow(1-on/${land},2))':x='(iw-iw/zoom)/2':y='(ih-ih/zoom)/2':d=1:s=${w}x${h}:fps=${FOOTAGE_FPS}`,
136
+ ...blurSteps(WHIP_IN_BLUR, w),
137
+ "setpts=PTS-STARTPTS",
138
+ FRAME_TIMING,
139
+ ];
140
+ return [
141
+ `[${input.outgoing}]trim=end_frame=${WHIP_OUT_FRAMES},setpts=PTS-STARTPTS,split[${p}o1][${p}o2]`,
142
+ `[${p}o1][${p}o2]${out.join(",")}[${p}out]`,
143
+ `[${input.incoming}]trim=start_frame=${WHIP_OUT_FRAMES}:end_frame=${DRAWN_TRANSITION_FRAMES.whip},setpts=PTS-STARTPTS,split[${p}i1][${p}i2]`,
144
+ `[${p}i1][${p}i2]${into.join(",")}[${p}in]`,
145
+ `[${p}out][${p}in]concat=n=2:v=1:a=0,${closeStream()}[${input.output}]`,
146
+ ];
147
+ }
148
+
149
+ /** The card's size, tilt and corner on frame `k` (0-based) of `frames`, eased out (`1 - (1 - t)^2`) to the full frame. */
150
+ export function getCardFrame(k: number, frames: number = DRAWN_TRANSITION_FRAMES.card): { scale: number; tilt: number; corner: number } {
151
+ const eased = 1 - (1 - (k + 1) / frames) ** 2;
152
+ return { scale: r4(CARD_START_SCALE + (1 - CARD_START_SCALE) * eased), tilt: r4(CARD_START_TILT * (1 - eased)), corner: r4(CARD_CORNER * (1 - eased)) };
153
+ }
154
+
155
+ /** An even size of at least 2 px, as yuv420p needs. */
156
+ function toEven(value: number): number {
157
+ return Math.max(2, 2 * Math.floor(value / 2));
158
+ }
159
+
160
+ function buildCardFilters(input: DrawnTransitionFiltersInput): string[] {
161
+ const { width: w, height: h } = input.frame;
162
+ const p = input.prefix;
163
+ const frames = DRAWN_TRANSITION_FRAMES.card;
164
+ // Each frame is its own chain at a fixed size: a size that changes mid-stream breaks `geq` and `rotate`.
165
+ const labels = Array.from({ length: frames }, (_, k) => `${p}c${String(k)}`);
166
+ const chains = labels.map((label, k) => {
167
+ const { scale, tilt, corner } = getCardFrame(k, frames);
168
+ const radius = r4(corner * w);
169
+ const chain = [`trim=start_frame=${String(k)}:end_frame=${String(k + 1)}`, `scale=${String(toEven(w * scale))}:${String(toEven(h * scale))}`];
170
+ if (radius >= 0.5) {
171
+ chain.push(`geq=lum='lum(X,Y)':cb='cb(X,Y)':cr='cr(X,Y)':a='255*lte(hypot(max(0,abs(X-W/2)-(W/2-${radius})),max(0,abs(Y-H/2)-(H/2-${radius}))),${radius})'`);
172
+ }
173
+ if (tilt > 0) chain.push(`rotate=${tilt}:c=black@0:ow=rotw(${tilt}):oh=roth(${tilt})`);
174
+ chain.push(`pad=${w}:${h}:(ow-iw)/2:(oh-ih)/2:color=black@0`, "setsar=1");
175
+ return `[${p}s${String(k)}]${chain.join(",")}[${label}]`;
176
+ });
177
+ return [
178
+ `[${input.incoming}]trim=end_frame=${frames},setpts=PTS-STARTPTS,format=yuva420p,split=${frames}${labels.map((_, k) => `[${p}s${String(k)}]`).join("")}`,
179
+ ...chains,
180
+ // One-frame chains keep their own times, so `interleave` lays them out in order (a `concat` of them drops frames).
181
+ `${labels.map((label) => `[${label}]`).join("")}interleave=nb_inputs=${frames}[${p}card]`,
182
+ `[${input.outgoing}]trim=end_frame=${frames},setpts=PTS-STARTPTS,format=yuv420p[${p}under]`,
183
+ `[${p}under][${p}card]overlay=0:0:format=auto,${closeStream()}[${input.output}]`,
184
+ ];
185
+ }
186
+
187
+ /** The paper's tear: a sum of sines along the height, as a share of the width (the `blend` expression's `Y` and `H`). */
188
+ function getTearExpression(): string {
189
+ return `(${PAPER_TEAR.map(([amplitude, frequency, phase]) => `${amplitude}*sin(Y/H*${frequency}+${phase})`).join("+")})`;
190
+ }
191
+
192
+ /** How far the tear has opened on frame `N` (the `blend` expression's frame), as a share of the width; closed during the grain's fade. */
193
+ function getOpenExpression(frames: number): string {
194
+ const opening = frames - PAPER_FADE_FRAMES;
195
+ return `if(lt(N,${PAPER_FADE_FRAMES}),-1,${PAPER_OPEN}*(0.5-0.5*cos(PI*(N-${PAPER_FADE_FRAMES}+1)/${opening})))`;
196
+ }
197
+
198
+ function buildPaperFilters(input: DrawnTransitionFiltersInput): string[] {
199
+ const { width: w, height: h } = input.frame;
200
+ const p = input.prefix;
201
+ const frames = DRAWN_TRANSITION_FRAMES.paper;
202
+ const strength = `min(1,(N+1)/${PAPER_FADE_FRAMES})*${PAPER_STRENGTH}`;
203
+ // Below 0 inside the tear (the incoming shot), up to the rim the torn paper's white, beyond it the papered shot.
204
+ const edge = `(abs(X/W-0.5)-(${getOpenExpression(frames)})-${getTearExpression()})`;
205
+ const tear = (rim: number): string => `'if(lt(${edge},0),A,if(lt(${edge},${PAPER_RIM}),${String(rim)},B))'`;
206
+ return [
207
+ // A static grain (no temporal noise) softened more along the height, as paper fibres run.
208
+ `color=c=${PAPER_COLOR}:s=${w}x${h}:r=${FOOTAGE_FPS},trim=end_frame=${frames},format=yuv420p,noise=c0s=28:c0f=a,gblur=sigma=${r4(Math.max(0.6, w / 900))}:sigmaV=${r4(Math.max(1.5, w / 360))}[${p}grain]`,
209
+ `[${input.outgoing}]trim=end_frame=${frames},setpts=PTS-STARTPTS,format=yuv420p[${p}under]`,
210
+ `[${input.incoming}]trim=end_frame=${frames},setpts=PTS-STARTPTS,format=yuv420p[${p}over]`,
211
+ `[${p}under][${p}grain]blend=c0_expr='A*(1-${strength})+A*B/255*${strength}':c1_expr='A*(1-${strength})+B*${strength}':c2_expr='A*(1-${strength})+B*${strength}'[${p}papered]`,
212
+ `[${p}over][${p}papered]blend=c0_expr=${tear(PAPER_RIM_LUMA)}:c1_expr=${tear(128)}:c2_expr=${tear(128)},${closeStream()}[${input.output}]`,
213
+ ];
214
+ }
@@ -1,7 +1,10 @@
1
1
  import { z } from "zod";
2
2
 
3
3
  import type { TimedWord } from "../voice/voiceover.js";
4
+ import { cameraSchema, describeCamera, isSameCamera, type EdlCamera } from "./camera.js";
4
5
  import { overlaySchema, type EdlOverlay } from "./overlay-schema.js";
6
+ import { DRAWN_TRANSITION_FRAMES, isDrawnTransition, STUTTER_FRAMES } from "./drawn-transitions.js";
7
+ import { FOOTAGE_FPS } from "./normalize.js";
5
8
  import { CUT_TRANSITIONS, type ClipRole, type CutOptions, type CutTransition, type FootageTransitions } from "./film.js";
6
9
  import { splitFilmSentences, type Sentence } from "./sentences.js";
7
10
  import { isFiller } from "./words.js";
@@ -59,6 +62,10 @@ export interface EdlSegment {
59
62
  transition: CutTransition;
60
63
  /** `kenburns`: a slow zoom over a segment without speech. */
61
64
  motion: SegmentMotion;
65
+ /** The segment's framing and a slow move over it (`camera.ts`); absent: the film's own zoom (cuts, Ken Burns). */
66
+ camera?: EdlCamera;
67
+ /** A `fade` cut's own length in frames at 30 fps (1-30); absent: the film's `fadeFrames`. */
68
+ fadeFrames?: number;
62
69
  audio?: EdlAudio;
63
70
  /** Moves the caption box for the captions that start in this segment; absent: the film's box. */
64
71
  caption?: EdlCaption;
@@ -77,13 +84,17 @@ export interface Edl {
77
84
  captionRanges?: EdlCaptionRange[];
78
85
  }
79
86
 
87
+ /** The shortest and the longest a segment's own `fadeFrames` may be. */
88
+ export const MIN_FADE_FRAMES = 1;
89
+ export const MAX_FADE_FRAMES = 30;
90
+
80
91
  const SEGMENT_ID_PATTERN = /^[A-Za-z0-9._-]+$/;
81
92
 
82
93
  const segmentFields = {
83
94
  clip: z.string().min(1).describe("The clip's id: the picture, and the sound unless audio says otherwise."),
84
95
  start: z.number().min(0).describe("Seconds in the trimmed clip where the segment starts."),
85
96
  end: z.number().positive().describe("Seconds in the trimmed clip where the segment ends."),
86
- transition: z.enum(CUT_TRANSITIONS).describe("How the segment starts: cut, fade (a cross-fade from the segment before), zoom (a punch-in) or whoosh."),
97
+ transition: z.enum(CUT_TRANSITIONS).describe("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)."),
87
98
  motion: z.enum(SEGMENT_MOTIONS).describe("kenburns: a slow zoom over the segment; none: still."),
88
99
  };
89
100
 
@@ -96,6 +107,8 @@ export const edlSchema = z
96
107
  z.strictObject({
97
108
  id: z.string().regex(SEGMENT_ID_PATTERN, "letters, digits, dot, dash or underscore").describe("The segment's id, unique in the cut: s<n> for a sentence, r<n> for b-roll."),
98
109
  ...segmentFields,
110
+ camera: cameraSchema.optional(),
111
+ fadeFrames: z.number().int().min(MIN_FADE_FRAMES).max(MAX_FADE_FRAMES).optional().describe("A fade cut's own length in frames at 30 fps (1-30); absent: the film's fadeFrames. Only on a fade."),
99
112
  audio: z
100
113
  .strictObject({
101
114
  clip: z.string().min(1).describe("The clip the sound comes from."),
@@ -305,6 +318,7 @@ export function validateEdl(edl: Edl, clips: Pick<EdlClip, "id" | "duration">[],
305
318
  checkSpan(at, segment);
306
319
  if (segment.end - segment.start < MIN_SEGMENT_SECONDS) problems.push(`${at}: shorter than ${MIN_SEGMENT_SECONDS} s (start ${segment.start}, end ${segment.end})`);
307
320
  if (captionBounds !== undefined) problems.push(...findCaptionProblems(`${at}.caption`, segment.caption, captionBounds));
321
+ problems.push(...findCameraProblems(at, segment));
308
322
  const { audio } = segment;
309
323
  if (audio === undefined) return;
310
324
  checkSpan(`${at}.audio`, audio);
@@ -316,6 +330,34 @@ export function validateEdl(edl: Edl, clips: Pick<EdlClip, "id" | "duration">[],
316
330
  return problems;
317
331
  }
318
332
 
333
+ /** A camera beside the film's own zoom (a Ken Burns zoom, a zoom cut), which owns the scale too, and a fade length on another cut. */
334
+ function findCameraProblems(at: string, segment: EdlSegment): string[] {
335
+ const problems: string[] = [];
336
+ if (segment.fadeFrames !== undefined && segment.transition !== "fade") problems.push(`${at}.fadeFrames: only a fade cut has a length; this segment starts on a ${segment.transition}`);
337
+ problems.push(...findTransitionProblems(at, segment));
338
+ if (segment.camera === undefined) return problems;
339
+ if (segment.motion === "kenburns") problems.push(`${at}.camera: the segment has a Ken Burns zoom, which owns the picture's scale; set motion to none or drop the camera`);
340
+ if (segment.transition === "zoom") problems.push(`${at}.camera: the segment starts on a zoom cut, which owns the picture's scale; start it on a cut or a fade`);
341
+ return problems;
342
+ }
343
+
344
+ /**
345
+ * A drawn transition on a segment shorter than its frames (its head is the transition), and a stutter beside a zoom of
346
+ * its own: a moving camera or a Ken Burns zoom (the stutter holds one tight framing after its wide frames).
347
+ */
348
+ function findTransitionProblems(at: string, segment: EdlSegment): string[] {
349
+ const problems: string[] = [];
350
+ const frames = Math.round((segment.end - segment.start) * FOOTAGE_FPS);
351
+ if (isDrawnTransition(segment.transition) && frames <= DRAWN_TRANSITION_FRAMES[segment.transition]) {
352
+ problems.push(`${at}.transition: a ${segment.transition} takes ${String(DRAWN_TRANSITION_FRAMES[segment.transition])} frames, longer than the segment (${String(frames)} frames)`);
353
+ }
354
+ if (segment.transition !== "stutter") return problems;
355
+ if (frames <= STUTTER_FRAMES) problems.push(`${at}.transition: a stutter shows ${String(STUTTER_FRAMES)} wide frames first, longer than the segment (${String(frames)} frames)`);
356
+ if (segment.motion === "kenburns") problems.push(`${at}.transition: a stutter holds one tight framing; the segment's Ken Burns zoom would move it`);
357
+ if (segment.camera !== undefined && segment.camera.from !== segment.camera.to) problems.push(`${at}.transition: a stutter holds one tight framing; the segment's camera moves`);
358
+ return problems;
359
+ }
360
+
319
361
  /** Caption ranges that are empty, run past the cut, overlap one another or (with `captionBounds`) leave the frame. */
320
362
  function findCaptionRangeProblems(edl: Edl, captionBounds: EdlCaptionBounds | undefined): string[] {
321
363
  const problems: string[] = [];
@@ -419,6 +461,8 @@ export function diffEdl(before: Edl, after: Edl): string[] {
419
461
  if (a.clip !== b.clip || a.start !== b.start || a.end !== b.end) lines.push(`${id}: ${a.clip} ${formatSpan(a)} → ${b.clip} ${formatSpan(b)}`);
420
462
  if (a.transition !== b.transition) lines.push(`${id}: ${a.transition} → ${b.transition}`);
421
463
  if (a.motion !== b.motion) lines.push(`${id}: motion ${a.motion} → ${b.motion}`);
464
+ if (!isSameCamera(a.camera, b.camera)) lines.push(`${id}: camera ${describeCamera(a.camera)} → ${describeCamera(b.camera)}`);
465
+ if (a.fadeFrames !== b.fadeFrames) lines.push(`${id}: fade ${a.fadeFrames === undefined ? "default" : `${String(a.fadeFrames)} frames`} → ${b.fadeFrames === undefined ? "default" : `${String(b.fadeFrames)} frames`}`);
422
466
  }
423
467
  for (const segment of after.segments) {
424
468
  const previous = old.get(segment.id);
@@ -23,9 +23,10 @@ export type ClipFit = (typeof CLIP_FITS)[number];
23
23
 
24
24
  /**
25
25
  * How a segment of the cut starts: `cut` (hard), `fade` (a short cross-fade from the previous segment), `zoom` (a
26
- * punch-in that hides a jump cut inside one talking clip) or `whoosh` (a hard cut with the whoosh sound).
26
+ * punch-in that hides a jump cut inside one talking clip), `whoosh` (a hard cut with the whoosh sound), the drawn
27
+ * transitions `whip`, `card` and `paper` (`drawn-transitions.ts`) or `stutter` (five frames wide, then tight).
27
28
  */
28
- export const CUT_TRANSITIONS = ["cut", "fade", "zoom", "whoosh"] as const;
29
+ export const CUT_TRANSITIONS = ["cut", "fade", "zoom", "whoosh", "whip", "card", "paper", "stutter"] as const;
29
30
 
30
31
  export type CutTransition = (typeof CUT_TRANSITIONS)[number];
31
32
 
@@ -0,0 +1,47 @@
1
+ import { readFileSync } from "node:fs";
2
+ import { fileURLToPath } from "node:url";
3
+
4
+ import { readFontTables, readUint16 } from "../og/font-tables.js";
5
+ import { createDraftTextMeasure, type DraftTextMeasure } from "./draft-text-width.js";
6
+
7
+ /**
8
+ * The kit's handwriting: Caveat (SIL Open Font License 1.1, `fonts/LICENSE-Caveat.txt`), a static SemiBold instance
9
+ * subset to Latin with every Polish letter. A note card and an end word are written in it in both paths: the draft
10
+ * copies the file into its fonts folder (libass finds it by `family`), the render copies it to `asset` with its
11
+ * `@font-face`.
12
+ */
13
+ export const HAND_FONT = {
14
+ family: "Caveat",
15
+ file: fileURLToPath(new URL("../../fonts/Caveat-SemiBold-Latin.ttf", import.meta.url)),
16
+ asset: "assets/fonts/hand.ttf",
17
+ } as const;
18
+
19
+ /** Room left round a measured handwritten line: kerning and Caveat's contextual letters are not read. */
20
+ const HAND_WIDTH_SLACK = 1.04;
21
+
22
+ let handMetrics: { measure: DraftTextMeasure; toEm: number } | undefined;
23
+
24
+ /** The hand font's measure in CSS pixels and its libass-size-to-em ratio, read once from the kit's own file. */
25
+ function getHandMetrics(): { measure: DraftTextMeasure; toEm: number } {
26
+ if (handMetrics !== undefined) return handMetrics;
27
+ const font = readFileSync(HAND_FONT.file);
28
+ const tables = readFontTables(font);
29
+ const libass = createDraftTextMeasure(font);
30
+ const head = tables.ok ? tables.value.get("head") : undefined;
31
+ const os2 = tables.ok ? tables.value.get("OS/2") : undefined;
32
+ if (libass === null || head === undefined || os2 === undefined) throw new Error(`the kit's hand font ${HAND_FONT.file} cannot be read`);
33
+ // `createDraftTextMeasure` measures as libass sizes a font (by usWinAscent + usWinDescent); a browser sizes it by the em.
34
+ const toEm = (readUint16(os2, 74) + readUint16(os2, 76)) / readUint16(head, 18);
35
+ handMetrics = { measure: (text, fontSize) => Math.ceil(libass(text, fontSize * toEm) * HAND_WIDTH_SLACK), toEm };
36
+ return handMetrics;
37
+ }
38
+
39
+ /** How wide `text` is written in the hand font at `fontSize` px in the render. */
40
+ export function measureHandText(text: string, fontSize: number): number {
41
+ return getHandMetrics().measure(text, fontSize);
42
+ }
43
+
44
+ /** The draft's `\fs` for the hand font at the render's `fontSize`: libass sizes a font by its ascent and descent, so the letters match the render's. */
45
+ export function getHandFontAssSize(fontSize: number): number {
46
+ return Math.round(fontSize * getHandMetrics().toEm);
47
+ }