@softure-ai/marketing-kit 0.44.0 → 0.45.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@softure-ai/marketing-kit",
3
- "version": "0.44.0",
3
+ "version": "0.45.1",
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",
@@ -67,20 +67,73 @@ export interface ClipSound {
67
67
  file: string;
68
68
  gainDb: number;
69
69
  preGain: SpeechPreGain;
70
+ /** Whether the clip's sound lived in one channel only and was folded onto both (issue #1385). */
71
+ channels: ChannelBalance;
70
72
  }
71
73
 
74
+ /**
75
+ * How a clip's sound sits in its channels (issue #1385): `balanced` (stereo with sound in both, mono, silence, or no
76
+ * sound at all), or `one_sided`, a stereo clip whose `live` channel carries the sound and whose other channel is dead,
77
+ * as a wireless lavalier receiver in stereo mode records one transmitter. Levels are RMS in dBFS.
78
+ */
79
+ export type ChannelBalance = { kind: "balanced" } | { kind: "one_sided"; live: "left" | "right"; liveRmsDb: number; deadRmsDb: number };
80
+
81
+ /**
82
+ * When a stereo clip counts as one-sided: its quieter channel is under `deadCeilingDb` RMS and at least `minGapDb`
83
+ * under the louder one. A dead channel measures about -115 dBFS; a phone's real stereo stays within a few dB.
84
+ */
85
+ export const ONE_SIDED_CHANNEL = { deadCeilingDb: -70, minGapDb: 30 } as const;
86
+
87
+ const BALANCED: ChannelBalance = { kind: "balanced" };
88
+
72
89
  const toFormat = `aformat=sample_rates=${String(FOOTAGE_SAMPLE_RATE)}:channel_layouts=stereo`;
73
90
 
91
+ /** The per-channel RMS pass over the trimmed clip's sound, as the source has it (no format change); writes nothing. */
92
+ export function buildChannelMeasureArgs(input: ClipSoundInput): string[] {
93
+ const { seek, length } = getTrimArgs(input);
94
+ return ["-hide_banner", "-nostats", ...seek, "-i", input.source, ...length, "-map", "0:a:0", "-vn", "-af", "astats=measure_overall=none:measure_perchannel=RMS_level", "-f", "null", "-"];
95
+ }
96
+
97
+ /** Each channel's RMS level in dBFS, in channel order, from `astats`' log; `-inf` (digital silence) is `-Infinity`. */
98
+ export function readChannelRmsDb(stderr: string): number[] {
99
+ return [...stderr.matchAll(/RMS level dB: (-?inf|-?\d+(?:\.\d+)?)/g)].map((match) => (match[1]?.endsWith("inf") === true ? -Infinity : Number(match[1])));
100
+ }
101
+
102
+ /** The balance of a clip's channels from their RMS levels (`readChannelRmsDb`); only two channels can be one-sided. */
103
+ export function getChannelBalance(rmsDb: readonly number[]): ChannelBalance {
104
+ const [left, right] = rmsDb;
105
+ if (rmsDb.length !== 2 || left === undefined || right === undefined) return BALANCED;
106
+ const [live, liveRmsDb, deadRmsDb] = left >= right ? (["left", left, right] as const) : (["right", right, left] as const);
107
+ if (!Number.isFinite(liveRmsDb) || deadRmsDb >= ONE_SIDED_CHANNEL.deadCeilingDb || liveRmsDb - deadRmsDb < ONE_SIDED_CHANNEL.minGapDb) return BALANCED;
108
+ return { kind: "one_sided", live, liveRmsDb, deadRmsDb };
109
+ }
110
+
111
+ /** The filter (with its trailing comma) that copies a one-sided clip's live channel onto both; empty when balanced. */
112
+ export function getChannelFoldFilter(balance: ChannelBalance): string {
113
+ if (balance.kind === "balanced") return "";
114
+ const channel = balance.live === "left" ? "c0" : "c1";
115
+ return `pan=stereo|c0=${channel}|c1=${channel},`;
116
+ }
117
+
118
+ /** The log line for a clip whose sound was folded onto both channels; null for a balanced one. */
119
+ export function describeChannelFold(clipId: string, balance: ChannelBalance): string | null {
120
+ if (balance.kind === "balanced") return null;
121
+ const dead = balance.live === "left" ? "right" : "left";
122
+ const level = (db: number): string => (Number.isFinite(db) ? `${String(Math.round(db * 10) / 10)} dBFS` : "silent");
123
+ return `clip sound: clip ${clipId} has sound only in its ${balance.live} channel (${level(balance.liveRmsDb)} RMS, ${dead} ${level(balance.deadRmsDb)}); the ${balance.live} channel is played on both.`;
124
+ }
125
+
74
126
  /** The seek and the length of the trimmed clip, as `buildNormalizeArgs` reads its source. */
75
127
  function getTrimArgs(input: ClipSoundInput): { seek: string[]; length: string[] } {
76
128
  return { seek: input.clip.trim.start > 0 ? ["-ss", String(input.clip.trim.start)] : [], length: ["-t", input.duration.toFixed(3)] };
77
129
  }
78
130
 
79
131
  /** The measuring pass over the trimmed clip's sound, after the same format change the extraction makes; writes nothing. */
80
- export function buildClipSoundMeasureArgs(input: ClipSoundInput): string[] {
132
+ export function buildClipSoundMeasureArgs(input: ClipSoundInput & { balance?: ChannelBalance }): string[] {
81
133
  const { seek, length } = getTrimArgs(input);
134
+ const fold = getChannelFoldFilter(input.balance ?? BALANCED);
82
135
  const measure = `loudnorm=I=${String(SPEECH_PRE_GAIN.target)}:TP=${String(SPEECH_PRE_GAIN.peakCeiling)}:LRA=${String(MEASURE_RANGE)}:print_format=json`;
83
- return ["-hide_banner", "-nostats", ...seek, "-i", input.source, ...length, "-map", "0:a:0", "-vn", "-af", `${toFormat},${measure}`, "-f", "null", "-"];
136
+ return ["-hide_banner", "-nostats", ...seek, "-i", input.source, ...length, "-map", "0:a:0", "-vn", "-af", `${fold}${toFormat},${measure}`, "-f", "null", "-"];
84
137
  }
85
138
 
86
139
  /**
@@ -133,11 +186,11 @@ export function describeSpeechPreGain(clipId: string, sound: Pick<ClipSound, "ga
133
186
  * The trimmed clip's sound, gained by `gainDb`, as a 48 kHz stereo WAV (24-bit PCM, or 32-bit float with
134
187
  * `peaks: "float"`); silence as long as the clip when it has none.
135
188
  */
136
- export function buildClipSoundArgs(input: ClipSoundInput & { gainDb: number; output: string; peaks?: SpeechPeaks }): string[] {
189
+ export function buildClipSoundArgs(input: ClipSoundInput & { gainDb: number; output: string; peaks?: SpeechPeaks; balance?: ChannelBalance }): string[] {
137
190
  const codec = ["-ar", String(FOOTAGE_SAMPLE_RATE), "-ac", "2", "-c:a", input.peaks === "float" ? "pcm_f32le" : "pcm_s24le", input.output];
138
191
  const { seek, length } = getTrimArgs(input);
139
192
  if (!input.probe.hasAudio) return ["-v", "error", "-y", "-f", "lavfi", "-i", `anullsrc=r=${String(FOOTAGE_SAMPLE_RATE)}:cl=stereo`, ...length, ...codec];
140
- return ["-v", "error", "-y", ...seek, "-i", input.source, ...length, "-map", "0:a:0", "-vn", "-af", `${toFormat},volume=${String(input.gainDb)}dB`, ...codec];
193
+ return ["-v", "error", "-y", ...seek, "-i", input.source, ...length, "-map", "0:a:0", "-vn", "-af", `${getChannelFoldFilter(input.balance ?? BALANCED)}${toFormat},volume=${String(input.gainDb)}dB`, ...codec];
141
194
  }
142
195
 
143
196
  /** Where a clip's sound goes in the build folder. */
@@ -146,13 +199,25 @@ export function getClipSoundPath(buildDir: string, clipId: string): string {
146
199
  }
147
200
 
148
201
  /** Measures one clip's sound; null when the clip has none. Throws naming the clip when ffmpeg fails. */
149
- async function measureClipSound(input: ClipSoundInput, signal: AbortSignal | undefined): Promise<LoudnessMeasurement | null> {
150
- if (!input.probe.hasAudio) return null;
151
- const step = `Measuring the sound of clip ${input.clip.id}`;
152
- const measured = await runProcess({ command: "ffmpeg", args: buildClipSoundMeasureArgs(input), ...(signal === undefined ? {} : { signal }) });
202
+ /** Runs one ffmpeg measuring pass and answers its log; throws naming `step` when ffmpeg does not start or fails. */
203
+ async function runMeasure(step: string, args: string[], signal: AbortSignal | undefined): Promise<string> {
204
+ const measured = await runProcess({ command: "ffmpeg", args, ...(signal === undefined ? {} : { signal }) });
153
205
  if (measured.kind === "not-started") throw new Error(`${step}: ffmpeg did not start (${measured.error}).`);
154
206
  if (measured.code !== 0) throw new Error(`${step}: ffmpeg ended with code ${String(measured.code)}: ${measured.stderr.trim().split("\n").slice(-3).join(" | ")}.`);
155
- const measurement = readLoudnessMeasurement(measured.stderr);
207
+ return measured.stderr;
208
+ }
209
+
210
+ /** How one clip's sound sits in its channels (issue #1385); `balanced` for a clip without sound. Throws naming the clip when ffmpeg fails. */
211
+ async function measureClipChannels(input: ClipSoundInput, signal: AbortSignal | undefined): Promise<ChannelBalance> {
212
+ if (!input.probe.hasAudio) return BALANCED;
213
+ const stderr = await runMeasure(`Measuring the channels of clip ${input.clip.id}`, buildChannelMeasureArgs(input), signal);
214
+ return getChannelBalance(readChannelRmsDb(stderr));
215
+ }
216
+
217
+ async function measureClipSound(input: ClipSoundInput & { balance: ChannelBalance }, signal: AbortSignal | undefined): Promise<LoudnessMeasurement | null> {
218
+ if (!input.probe.hasAudio) return null;
219
+ const step = `Measuring the sound of clip ${input.clip.id}`;
220
+ const measurement = readLoudnessMeasurement(await runMeasure(step, buildClipSoundMeasureArgs(input), signal));
156
221
  if (measurement === null) throw new Error(`${step}: ffmpeg printed no loudnorm measurement for ${input.source}.`);
157
222
  return measurement;
158
223
  }
@@ -161,8 +226,9 @@ async function measureClipSound(input: ClipSoundInput, signal: AbortSignal | und
161
226
  * Every clip's lossless, pre-gained sound under `<buildDir>/audio/<id>.wav`, by clip id. A talking clip is gained by its
162
227
  * own measurement (`getPreGainDb`); any other clip by the mean of the talking clips' gains (0 dB without one), so a
163
228
  * b-roll's own sound under the speech keeps its relation to it. Each answers its `preGain` (issue #1181), and `log` gets
164
- * a line for every clip the peak ceiling held under the target (or, with `peaks: "float"`, whose peaks pass it).
165
- * Throws naming the clip when ffmpeg fails.
229
+ * a line for every clip the peak ceiling held under the target (or, with `peaks: "float"`, whose peaks pass it). A clip
230
+ * whose sound lives in one channel only is folded onto both before it is measured and extracted (issue #1385), with a
231
+ * log line. Throws naming the clip when ffmpeg fails.
166
232
  */
167
233
  export async function prepareClipSounds(
168
234
  clips: readonly ClipSoundInput[],
@@ -170,10 +236,13 @@ export async function prepareClipSounds(
170
236
  ): Promise<Record<string, ClipSound>> {
171
237
  const { signal } = options;
172
238
  const peaks = options.peaks ?? "ceiling";
239
+ const balances = new Map<string, ChannelBalance>();
240
+ for (const clip of clips) balances.set(clip.clip.id, await measureClipChannels(clip, signal));
173
241
  const measured = new Map<string, { gainDb: number; preGain: SpeechPreGain }>();
174
242
  for (const clip of clips) {
175
243
  if (clip.clip.role !== "talk") continue;
176
- measured.set(clip.clip.id, getSpeechPreGain(await measureClipSound(clip, signal), { peaks }));
244
+ const balance = balances.get(clip.clip.id) ?? BALANCED;
245
+ measured.set(clip.clip.id, getSpeechPreGain(await measureClipSound({ ...clip, balance }, signal), { peaks }));
177
246
  }
178
247
  const talking = [...measured.values()].map((entry) => entry.gainDb);
179
248
  const sharedGain = talking.length === 0 ? 0 : Math.round((talking.reduce((sum, gain) => sum + gain, 0) / talking.length) * 100) / 100 || 0;
@@ -183,11 +252,11 @@ export async function prepareClipSounds(
183
252
  const { gainDb, preGain } = measured.get(clip.clip.id) ?? shared;
184
253
  const output = getClipSoundPath(options.buildDir, clip.clip.id);
185
254
  mkdirSync(dirname(output), { recursive: true });
186
- await runFfmpeg(`Extracting the sound of clip ${clip.clip.id}`, buildClipSoundArgs({ ...clip, gainDb, output, peaks }), { ...(signal === undefined ? {} : { signal }), output });
187
- const sound: ClipSound = { file: output, gainDb, preGain };
255
+ const channels = balances.get(clip.clip.id) ?? BALANCED;
256
+ await runFfmpeg(`Extracting the sound of clip ${clip.clip.id}`, buildClipSoundArgs({ ...clip, gainDb, output, peaks, balance: channels }), { ...(signal === undefined ? {} : { signal }), output });
257
+ const sound: ClipSound = { file: output, gainDb, preGain, channels };
188
258
  sounds[clip.clip.id] = sound;
189
- const line = describeSpeechPreGain(clip.clip.id, sound);
190
- if (line !== null) options.log?.(line);
259
+ for (const line of [describeChannelFold(clip.clip.id, channels), describeSpeechPreGain(clip.clip.id, sound)]) if (line !== null) options.log?.(line);
191
260
  }
192
261
  return sounds;
193
262
  }
@@ -2,7 +2,7 @@ import { FOOTAGE_FPS } from "./normalize.js";
2
2
  import { getCornerRadiusPx, type BrandStyle, type CornerRadius } from "./brand-style.js";
3
3
  import { getDraftBoxEvents } from "./draft-boxes.js";
4
4
  import { toAssColor } from "./draft-color.js";
5
- import { DEFAULT_CONTENT_AREA, getSpacingWidth, toDraftAssSize, toDraftSpacing, wrapDraftLine, type DraftFont } from "./draft-text-width.js";
5
+ import { DEFAULT_CONTENT_AREA, getDraftLineShift, getDraftMiddleShift, getSpacingWidth, toDraftAssSize, toDraftSpacing, wrapDraftLine, type DraftFont } from "./draft-text-width.js";
6
6
  import { HAND_FONT, getHandFontAssSize } from "./hand-font.js";
7
7
  import { getCounterValueAt, getOverlayColors, getPlaceCardTimes, getTypingStep, getTypingTimes, type OverlayColors } from "./overlay-html.js";
8
8
  import {
@@ -205,6 +205,13 @@ interface DraftContext {
205
205
  layout?: OverlayTextMeasure;
206
206
  /** The content area (ascent, descent in ems) of the font of `role`, as a browser sizes an inline box. */
207
207
  contentArea: (role: DraftFontRole) => { ascentEm: number; descentEm: number };
208
+ /**
209
+ * How far a line of `role` placed by its top moves so its baseline stands where the render's does in a line box of
210
+ * `lineHeightEm` (`getDraftLineShift`), in px; 0 without the draft's fonts (as before).
211
+ */
212
+ lineShift: (role: DraftFontRole, cssPx: number, lineHeightEm: number) => number;
213
+ /** The same for a line placed by its middle (`getDraftMiddleShift`); 0 without the draft's fonts. */
214
+ middleShift: (role: DraftFontRole, cssPx: number) => number;
208
215
  }
209
216
 
210
217
  /**
@@ -653,7 +660,7 @@ function getLaidOutSideTextEvents(overlay: Extract<ResolvedOverlay, { kind: "key
653
660
  const isTyped = overlay.entrance !== null && overlay.entrance !== "drop" && overlay.typing !== null;
654
661
  let typedBefore = 0;
655
662
  const lines = layout.lines.flatMap((line, index) => {
656
- const pos = { x: layout.textX, y: layout.textTop + index * lineHeight };
663
+ const pos = { x: layout.textX, y: layout.textTop + index * lineHeight + context.lineShift(role, fontSize, OVERLAY_LINE_HEIGHT) };
657
664
  const lineStart = overlay.typing === null ? span.start : span.start + typedBefore / overlay.typing;
658
665
  const count = [...line].length;
659
666
  const steps =
@@ -726,8 +733,9 @@ function getListEvents(overlay: Extract<ResolvedOverlay, { kind: "list" }>, cont
726
733
  const name = overlay.entrance === null || overlay.entrance === "type" ? "fade" : overlay.entrance;
727
734
  const textTags = getTextTags(overlay, colors, context, OVERLAY_FONT_ROLES.list);
728
735
  const lines = getSideTextLines(overlay);
729
- const write = (pos: OverlayPoint, align: number, steps: TextStep[], motion: DraftMotion, clip = "") =>
730
- getTextEvents({ layer: 4, style: "OverlayPlain", pos, tags: `\\an${align}\\fs${context.toAssSize(OVERLAY_FONT_ROLES.list, fontSize)}${context.spacing(OVERLAY_LETTER_SPACING_EM.card, fontSize)}${textTags}${clip}`, steps, motion });
736
+ const shift = context.lineShift(OVERLAY_FONT_ROLES.list, fontSize, OVERLAY_LINE_HEIGHT);
737
+ const write = (at: OverlayPoint, align: number, steps: TextStep[], motion: DraftMotion, clip = "") =>
738
+ getTextEvents({ layer: 4, style: "OverlayPlain", pos: { x: at.x, y: at.y + shift }, tags: `\\an${align}\\fs${context.toAssSize(OVERLAY_FONT_ROLES.list, fontSize)}${context.spacing(OVERLAY_LETTER_SPACING_EM.card, fontSize)}${textTags}${clip}`, steps, motion });
731
739
  if (overlay.chips !== undefined) {
732
740
  const covered = getChipCoveredTimes(overlay);
733
741
  return overlay.chips.flatMap((_chip, index) => {
@@ -912,8 +920,10 @@ function getCardEvents(overlay: CardOverlay, context: DraftContext): string[] {
912
920
  // The render spaces a title's heading lines tighter than the rest of a card's text, and a search query not at all.
913
921
  const spacingFor = (role: OverlayFontRole): number =>
914
922
  overlay.kind === "search_bar" ? 0 : role !== "heading" ? OVERLAY_LETTER_SPACING_EM.card : overlay.kind === "hook_title" ? OVERLAY_LETTER_SPACING_EM.hookTitle : overlay.kind === "place_card" ? OVERLAY_LETTER_SPACING_EM.placeTitle : OVERLAY_LETTER_SPACING_EM.card;
915
- const text = (pos: OverlayPoint, align: number, size: number, role: OverlayFontRole, steps: TextStep[], own: DraftMotion = motion) =>
916
- getTextEvents({ layer: 4, style: "OverlayPlain", pos, tags: `\\an${align}\\fs${context.toAssSize(role, r0(size))}${context.spacing(spacingFor(role), r0(size))}${tagsFor(role)}`, steps, motion: own });
923
+ // Every card line is set by its top in the render's line box (a title's heading lines in theirs, the rest in `OVERLAY_LINE_HEIGHT`).
924
+ const lineBoxFor = (role: OverlayFontRole): number => (role === "heading" && overlay.kind === "place_card" ? OVERLAY_TITLE_LINE_HEIGHT : OVERLAY_LINE_HEIGHT);
925
+ const text = (at: OverlayPoint, align: number, size: number, role: OverlayFontRole, steps: TextStep[], own: DraftMotion = motion) =>
926
+ getTextEvents({ layer: 4, style: "OverlayPlain", pos: { x: at.x, y: at.y + (align >= 7 ? context.lineShift(role, r0(size), lineBoxFor(role)) : align >= 4 ? context.middleShift(role, r0(size)) : 0) }, tags: `\\an${align}\\fs${context.toAssSize(role, r0(size))}${context.spacing(spacingFor(role), r0(size))}${tagsFor(role)}`, steps, motion: own });
917
927
  const plain = { ...motion, name: "none" as const, entrance: { kind: "none" as const } };
918
928
  if (overlay.kind === "hook_title" || overlay.kind === "place_card") {
919
929
  // The text block sits in the card's middle; centred lines on its axis, left ones from its left edge (RV-131).
@@ -1119,7 +1129,8 @@ function getNoteEvents(overlay: Extract<ResolvedOverlay, { kind: "note" }>, cont
1119
1129
  const assSize = isStrip ? context.toAssSize("heading", overlay.fontSize) : getHandFontAssSize(overlay.fontSize);
1120
1130
  const tags = `\\an7\\fs${assSize}${isStrip ? context.spacing(OVERLAY_LETTER_SPACING_EM.strip, overlay.fontSize) : ""}${font}\\1c${toTagColor(colors.ink)}${turn}`;
1121
1131
  getNoteWordsByLine(overlay).forEach((words, index) => {
1122
- const pos = { x: textBox.left, y: textBox.top + index * lineHeight };
1132
+ // A strip's heading font stands on the render's baseline; the hand font is sized to its own letters (`getHandFontAssSize`).
1133
+ const pos = { x: textBox.left, y: textBox.top + index * lineHeight + (isStrip ? context.lineShift("heading", overlay.fontSize, NOTE_LINE_HEIGHT) : 0) };
1123
1134
  const line = overlay.lines[index] as string;
1124
1135
  const span = { start: overlay.start, end: overlay.end };
1125
1136
  if (isStrip) {
@@ -1192,6 +1203,8 @@ export function buildDraftOverlayEvents(
1192
1203
  measure: (role, text, cssPx, spacingEm) => (drawn === undefined ? estimateTextWidth(text, cssPx) : drawn[role].measure(text, cssPx) + getSpacingWidth(text, spacingEm, cssPx)),
1193
1204
  spacing: (spacingEm, cssPx) => (drawn === undefined || spacingEm === 0 ? "" : `\\fsp${String(toDraftSpacing(spacingEm, cssPx))}`),
1194
1205
  contentArea: (role) => drawn?.[role].contentArea ?? DEFAULT_CONTENT_AREA,
1206
+ lineShift: (role, cssPx, lineHeightEm) => (drawn === undefined ? 0 : getDraftLineShift(drawn[role], cssPx, lineHeightEm)),
1207
+ middleShift: (role, cssPx) => (drawn === undefined ? 0 : getDraftMiddleShift(drawn[role], cssPx)),
1195
1208
  ...(options.style === undefined ? {} : { style: options.style }),
1196
1209
  ...(drawn === undefined ? {} : { layout: (role: OverlayFontRole, text: string, cssPx: number, spacingEm: number) => drawn[role].measure(text, cssPx) + getSpacingWidth(text, spacingEm, cssPx) }),
1197
1210
  };
@@ -13,6 +13,10 @@ export type DraftTextMeasure = (text: string, fontSize: number) => number;
13
13
  interface Metrics {
14
14
  /** The font's units per libass font size: `usWinAscent + usWinDescent`. */
15
15
  unitsPerSize: number;
16
+ /** How far below a line's top libass sets its baseline, in font units: `usWinAscent` (else the `hhea` ascender). */
17
+ drawnAscent: number;
18
+ /** How far above a line's foot libass sets its baseline, in font units: `usWinDescent` (else the `hhea` descender). */
19
+ drawnDescent: number;
16
20
  /** The font's units per em (`head`), what a browser sizes it by; 0 when the font has no `head`. */
17
21
  unitsPerEm: number;
18
22
  advances: (glyph: number) => number;
@@ -39,12 +43,15 @@ function readMetrics(font: Buffer): Metrics | null {
39
43
  const os2 = tables.value.get("OS/2");
40
44
  const winSum = os2 === undefined ? 0 : readUint16(os2, 74) + readUint16(os2, 76);
41
45
  const unitsPerSize = winSum > 0 ? winSum : readInt16(hhea, 4) - readInt16(hhea, 6);
46
+ const isWin = winSum > 0 && os2 !== undefined;
47
+ const drawnAscent = isWin ? readUint16(os2, 74) : readInt16(hhea, 4);
48
+ const drawnDescent = isWin ? readUint16(os2, 76) : -readInt16(hhea, 6);
42
49
  const count = readUint16(hhea, 34);
43
50
  if (unitsPerSize <= 0 || count === 0 || hmtx.length < count * 4) return null;
44
51
  const head = tables.value.get("head");
45
52
  const unitsPerEm = head === undefined ? 0 : readUint16(head, 18);
46
53
  // Glyphs past `numberOfHMetrics` share the last advance (OpenType `hmtx`).
47
- return { unitsPerSize, unitsPerEm, advances: (glyph) => readUint16(hmtx, Math.min(glyph, count - 1) * 4), ...readContentArea(hhea, os2) };
54
+ return { unitsPerSize, drawnAscent, drawnDescent, unitsPerEm, advances: (glyph) => readUint16(hmtx, Math.min(glyph, count - 1) * 4), ...readContentArea(hhea, os2) };
48
55
  }
49
56
 
50
57
  /**
@@ -86,6 +93,14 @@ export interface DraftFont {
86
93
  * elsewhere, which then takes `DEFAULT_CONTENT_AREA`.
87
94
  */
88
95
  contentArea?: { ascentEm: number; descentEm: number };
96
+ /**
97
+ * How far below a line's top libass sets the baseline, in ems: `usWinAscent / unitsPerEm`. A browser sets it at the
98
+ * half-leading plus the content area's ascent, so a line placed by its top is moved by the difference
99
+ * (`getDraftLineShift`); absent for a font made elsewhere, which is not moved.
100
+ */
101
+ drawnAscentEm?: number;
102
+ /** How far above a line's foot libass sets the baseline, in ems: `usWinDescent / unitsPerEm`; absent with `drawnAscentEm`. */
103
+ drawnDescentEm?: number;
89
104
  }
90
105
 
91
106
  /** The content area a font without its own is given, in ems: a common sans serif's. */
@@ -96,6 +111,31 @@ export function toDraftAssSize(cssPx: number, assScale: number): number {
96
111
  return Math.round(cssPx * assScale * 100) / 100;
97
112
  }
98
113
 
114
+ /**
115
+ * How far to move a line of `font` drawn by its top (`\\an7`, `\\an8`, `\\an9`) so its baseline stands where the
116
+ * render's does in a line box of `lineHeightEm` at `cssPx`, in px (negative: up). libass sets the baseline
117
+ * `drawnAscentEm` below the top; a browser half the leading plus the content area's ascent. 0 for a font without its
118
+ * metrics (as before).
119
+ */
120
+ export function getDraftLineShift(font: Pick<DraftFont, "contentArea" | "drawnAscentEm">, cssPx: number, lineHeightEm: number): number {
121
+ if (font.drawnAscentEm === undefined || font.contentArea === undefined) return 0;
122
+ const { ascentEm, descentEm } = font.contentArea;
123
+ const browserBaseline = (lineHeightEm - ascentEm - descentEm) / 2 + ascentEm;
124
+ return Math.round((browserBaseline - font.drawnAscentEm) * cssPx * 100) / 100;
125
+ }
126
+
127
+ /**
128
+ * How far to move a line of `font` drawn by its middle (`\\an4`, `\\an5`, `\\an6`) so its baseline stands where a
129
+ * browser's does in a line box centred on the same point, in px (negative: up): a browser's baseline stands half the
130
+ * content area's ascent less its descent below the middle, libass's half the win ascent less the win descent. 0 for a
131
+ * font without its metrics (as before).
132
+ */
133
+ export function getDraftMiddleShift(font: Pick<DraftFont, "contentArea" | "drawnAscentEm" | "drawnDescentEm">, cssPx: number): number {
134
+ if (font.drawnAscentEm === undefined || font.drawnDescentEm === undefined || font.contentArea === undefined) return 0;
135
+ const { ascentEm, descentEm } = font.contentArea;
136
+ return Math.round(((ascentEm - descentEm - (font.drawnAscentEm - font.drawnDescentEm)) / 2) * cssPx * 100) / 100;
137
+ }
138
+
99
139
  /** The ASS letter spacing (`\\fsp`, `Spacing`, in the frame's px) of the render's `letter-spacing` of `spacingEm` at `cssPx`, to 0.01. */
100
140
  export function toDraftSpacing(spacingEm: number, cssPx: number): number {
101
141
  return Math.round(spacingEm * cssPx * 100) / 100;
@@ -128,6 +168,8 @@ export function createDraftFont(source: { family: string; file: string }, data:
128
168
  file: source.file,
129
169
  assScale: metrics.unitsPerSize / unitsPerEm,
130
170
  contentArea: { ascentEm: metrics.ascent / unitsPerEm, descentEm: metrics.descent / unitsPerEm },
171
+ drawnAscentEm: metrics.drawnAscent / unitsPerEm,
172
+ drawnDescentEm: metrics.drawnDescent / unitsPerEm,
131
173
  measure: (text, fontSize) => {
132
174
  let units = 0;
133
175
  for (const character of text) units += metrics.advances(map.getGlyph(character.codePointAt(0) ?? 0));
@@ -25,7 +25,7 @@ import { resolveEdlOverlays, type OverlayFontRole, type OverlayTextMeasure, type
25
25
  import { chooseFootageDraftFont } from "./draft-font.js";
26
26
  import { getEdlDuration, getSegmentStarts, remapWords, type Edl } from "./edl.js";
27
27
  import { declickSpeech, describeDeclick, type DeclickReport } from "./declick.js";
28
- import { CAPTION_RIBBON, getDeclickLevel, getFootageEdit, type FootageFilm } from "./film.js";
28
+ import { CAPTION_MIN_FONT_SCALE, CAPTION_RIBBON, getDeclickLevel, getFootageEdit, type FootageFilm } from "./film.js";
29
29
  import { buildFilmMixArgs } from "./film-mix.js";
30
30
  import { DEFAULT_LOUDNESS, formatDb, getLoudnessVerdict, measureLoudness, normalizeLoudness, type MixLoudnessTarget } from "./loudness.js";
31
31
  import { duckingKeyframes, getDuckingOptions } from "./music.js";
@@ -167,7 +167,7 @@ function toAssText(text: string): string {
167
167
  export type FootageDraftCaptionColors = Pick<BrandColors, "captionBackground" | "captionText" | "captionHighlight" | "captionHighlightBox" | "captionHighlightText">;
168
168
 
169
169
  export interface FootageDraftCaptionsInput {
170
- film: Pick<FootageFilm, "captions" | "captionStyle" | "captionHighlightStyle" | "captionRibbonTilt"> & CaptionWordsFilm;
170
+ film: Pick<FootageFilm, "captions" | "captionStyle" | "captionHighlightStyle" | "captionRibbonTilt" | "captionMaxLines"> & CaptionWordsFilm;
171
171
  edl: Edl;
172
172
  /** The film's words in film time (`remapWords`). */
173
173
  words: TimedWord[];
@@ -339,6 +339,19 @@ function getDrawnPill(input: DrawnPillInput): DrawnPill {
339
339
  return { breaks, events: getDraftBoxEvents({ layer: 0, at, styleName: "CaptionShape", box, radius, color: input.colors.background, accent: input.colors.accent, style, scale }), words };
340
340
  }
341
341
 
342
+ /**
343
+ * A caption chunk's place at the size the render's fit script gives it (`getCaptionFitScript`): with `maxLines`, the
344
+ * font shrinks in 1 px steps while its words (each kept whole, as the render's inline blocks are) take more lines of
345
+ * `width` than that, down to `minFontSize`; without, the place as it is.
346
+ */
347
+ export function fitDraftCaptionPlace(input: { words: readonly string[]; place: CaptionLayout; width: number; maxLines: number | undefined; minFontSize: number; measure: DraftTextMeasure }): CaptionLayout {
348
+ const { maxLines } = input;
349
+ if (maxLines === undefined || input.words.length === 0) return input.place;
350
+ let size = input.place.fontSize;
351
+ while (wrapDraftLine(input.words, input.width, size, input.measure).length > maxLines && size > input.minFontSize) size -= 1;
352
+ return size === input.place.fontSize ? input.place : { ...input.place, fontSize: size };
353
+ }
354
+
342
355
  interface RibbonInput {
343
356
  text: string;
344
357
  span: { start: number; end: number };
@@ -456,7 +469,7 @@ export function buildFootageDraftCaptions(input: FootageDraftCaptionsInput): str
456
469
  const toStyle = (name: string, place: CaptionLayout): string => [
457
470
  name,
458
471
  family,
459
- styleSize,
472
+ place.fontSize === caption.fontSize ? styleSize : toDraftAssSize(place.fontSize, lineScale),
460
473
  look.primary,
461
474
  look.primary,
462
475
  look.outlineColor,
@@ -467,7 +480,7 @@ export function buildFootageDraftCaptions(input: FootageDraftCaptionsInput): str
467
480
  0,
468
481
  100,
469
482
  100,
470
- spacing,
483
+ place.fontSize === caption.fontSize || fonts === undefined ? spacing : toDraftSpacing(isRibbon ? CAPTION_RIBBON_LETTER_SPACING_EM : CAPTION_LETTER_SPACING_EM, place.fontSize),
471
484
  0,
472
485
  look.borderStyle,
473
486
  look.outline,
@@ -482,10 +495,19 @@ export function buildFootageDraftCaptions(input: FootageDraftCaptionsInput): str
482
495
  // A chunk in a segment's own box gets a style of that box (Caption2, Caption3, ...); the film's box stays `Caption`.
483
496
  const styles = [toStyle("Caption", caption)];
484
497
  const moved: CaptionLayout[] = [];
485
- const places = getCaptionChunkLayouts(chunks, input.edl, caption);
498
+ // Each chunk at the size the render's fit gives it (`captionMaxLines`): a smaller one takes a style of its own.
499
+ const fitWidth = (place: CaptionLayout) => frame.width - place.left - place.right - (isHighlight && input.style !== undefined ? 2 * getStylePadding(CAPTION_PILL_PADDING, input.style.padding).x : 0);
500
+ const fitMeasure = fonts === undefined ? (input.measure ?? ((line: string, size: number) => estimateTextWidth(line, size))) : withLetterSpacing(fonts.body.measure, CAPTION_LETTER_SPACING_EM);
501
+ const minFontSize = Math.round(caption.fontSize * CAPTION_MIN_FONT_SCALE);
502
+ const places = getCaptionChunkLayouts(chunks, input.edl, caption).map((place, index) =>
503
+ isRibbon
504
+ ? place
505
+ : fitDraftCaptionPlace({ words: (chunks[index]?.words ?? []).map((word) => word.text.replace(/\u00a0/g, " ")), place, width: fitWidth(place), maxLines: input.film.captionMaxLines, minFontSize, measure: fitMeasure }),
506
+ );
507
+ const isSameStyle = (a: CaptionLayout, b: CaptionLayout) => isSameCaptionPlace(a, b) && a.fontSize === b.fontSize;
486
508
  const styleNames = places.map((place) => {
487
- if (isSameCaptionPlace(place, caption)) return "Caption";
488
- let index = moved.findIndex((other) => isSameCaptionPlace(other, place));
509
+ if (isSameStyle(place, caption)) return "Caption";
510
+ let index = moved.findIndex((other) => isSameStyle(other, place));
489
511
  if (index === -1) {
490
512
  index = moved.push(place) - 1;
491
513
  styles.push(toStyle(`Caption${index + 2}`, place));
@@ -148,7 +148,8 @@ export interface FootageFilm {
148
148
  captionPreset?: CaptionPreset;
149
149
  /**
150
150
  * The most lines a caption card may take: the render shrinks a longer card's font (to at most
151
- * `CAPTION_MIN_FONT_SCALE` of the box's size) until it fits. Absent: no limit. The draft keeps its font size.
151
+ * `CAPTION_MIN_FONT_SCALE` of the box's size) until it fits. Absent: no limit. The draft fits each chunk the same
152
+ * way (`fitDraftCaptionPlace`).
152
153
  */
153
154
  captionMaxLines?: number;
154
155
  /**
package/src/index.ts CHANGED
@@ -161,6 +161,8 @@ export {
161
161
  DEFAULT_CONTENT_AREA,
162
162
  createDraftFont,
163
163
  createDraftTextMeasure,
164
+ getDraftLineShift,
165
+ getDraftMiddleShift,
164
166
  getSpacingWidth,
165
167
  toDraftAssSize,
166
168
  toDraftSpacing,
@@ -717,6 +719,7 @@ export {
717
719
  FOOTAGE_DRAFT_OVERLAY_COLORS,
718
720
  FOOTAGE_DRAFT_FONT,
719
721
  FOOTAGE_DRAFT_WIDTH,
722
+ fitDraftCaptionPlace,
720
723
  loadFootageDraftFonts,
721
724
  createOverlayTextMeasure,
722
725
  type FootageDraftFonts,
@@ -758,15 +761,22 @@ export {
758
761
  type PicturePieceArgsInput,
759
762
  } from "./footage/picture.js";
760
763
  export {
764
+ ONE_SIDED_CHANNEL,
761
765
  SPEECH_PRE_GAIN,
766
+ buildChannelMeasureArgs,
762
767
  buildClipSoundArgs,
763
768
  buildClipSoundMeasureArgs,
769
+ describeChannelFold,
770
+ getChannelBalance,
771
+ getChannelFoldFilter,
772
+ readChannelRmsDb,
764
773
  getAudioCodecArgs,
765
774
  getClipSoundPath,
766
775
  describeSpeechPreGain,
767
776
  getPreGainDb,
768
777
  getSpeechPreGain,
769
778
  prepareClipSounds,
779
+ type ChannelBalance,
770
780
  type ClipSound,
771
781
  type ClipSoundInput,
772
782
  type MeasuredPreGain,