@softure-ai/marketing-kit 0.14.0 → 0.16.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 (113) hide show
  1. package/CHANGELOG.md +95 -0
  2. package/README.md +136 -12
  3. package/dist/config/schema.d.ts +2 -1
  4. package/dist/config/schema.d.ts.map +1 -1
  5. package/dist/config/schema.js +7 -0
  6. package/dist/config/schema.js.map +1 -1
  7. package/dist/footage/clip-sound.d.ts +58 -0
  8. package/dist/footage/clip-sound.d.ts.map +1 -0
  9. package/dist/footage/clip-sound.js +103 -0
  10. package/dist/footage/clip-sound.js.map +1 -0
  11. package/dist/footage/declick.d.ts +1 -1
  12. package/dist/footage/declick.d.ts.map +1 -1
  13. package/dist/footage/declick.js +3 -4
  14. package/dist/footage/declick.js.map +1 -1
  15. package/dist/footage/draft.d.ts +19 -5
  16. package/dist/footage/draft.d.ts.map +1 -1
  17. package/dist/footage/draft.js +94 -24
  18. package/dist/footage/draft.js.map +1 -1
  19. package/dist/footage/elevenlabs.d.ts +5 -0
  20. package/dist/footage/elevenlabs.d.ts.map +1 -1
  21. package/dist/footage/elevenlabs.js +10 -3
  22. package/dist/footage/elevenlabs.js.map +1 -1
  23. package/dist/footage/failure.d.ts +53 -0
  24. package/dist/footage/failure.d.ts.map +1 -0
  25. package/dist/footage/failure.js +23 -0
  26. package/dist/footage/failure.js.map +1 -0
  27. package/dist/footage/fake.d.ts +10 -1
  28. package/dist/footage/fake.d.ts.map +1 -1
  29. package/dist/footage/fake.js +19 -4
  30. package/dist/footage/fake.js.map +1 -1
  31. package/dist/footage/film-mix.d.ts +5 -1
  32. package/dist/footage/film-mix.d.ts.map +1 -1
  33. package/dist/footage/film-mix.js +11 -2
  34. package/dist/footage/film-mix.js.map +1 -1
  35. package/dist/footage/hyperframes-capture.d.ts +30 -0
  36. package/dist/footage/hyperframes-capture.d.ts.map +1 -0
  37. package/dist/footage/hyperframes-capture.js +80 -0
  38. package/dist/footage/hyperframes-capture.js.map +1 -0
  39. package/dist/footage/isolate-ranges.d.ts +67 -5
  40. package/dist/footage/isolate-ranges.d.ts.map +1 -1
  41. package/dist/footage/isolate-ranges.js +92 -21
  42. package/dist/footage/isolate-ranges.js.map +1 -1
  43. package/dist/footage/loudness.d.ts +16 -2
  44. package/dist/footage/loudness.d.ts.map +1 -1
  45. package/dist/footage/loudness.js +10 -7
  46. package/dist/footage/loudness.js.map +1 -1
  47. package/dist/footage/paid.d.ts +14 -1
  48. package/dist/footage/paid.d.ts.map +1 -1
  49. package/dist/footage/paid.js +10 -4
  50. package/dist/footage/paid.js.map +1 -1
  51. package/dist/footage/pipeline.d.ts +10 -4
  52. package/dist/footage/pipeline.d.ts.map +1 -1
  53. package/dist/footage/pipeline.js +74 -64
  54. package/dist/footage/pipeline.js.map +1 -1
  55. package/dist/footage/providers.d.ts +5 -0
  56. package/dist/footage/providers.d.ts.map +1 -1
  57. package/dist/footage/providers.js.map +1 -1
  58. package/dist/footage/render.d.ts +1 -1
  59. package/dist/footage/render.d.ts.map +1 -1
  60. package/dist/footage/render.js +4 -3
  61. package/dist/footage/render.js.map +1 -1
  62. package/dist/footage/speech-ranges.d.ts +80 -14
  63. package/dist/footage/speech-ranges.d.ts.map +1 -1
  64. package/dist/footage/speech-ranges.js +146 -26
  65. package/dist/footage/speech-ranges.js.map +1 -1
  66. package/dist/index.d.ts +10 -6
  67. package/dist/index.d.ts.map +1 -1
  68. package/dist/index.js +9 -5
  69. package/dist/index.js.map +1 -1
  70. package/dist/og/index.d.ts +2 -0
  71. package/dist/og/index.d.ts.map +1 -1
  72. package/dist/og/index.js +2 -0
  73. package/dist/og/index.js.map +1 -1
  74. package/dist/og/photo-cover.d.ts +55 -0
  75. package/dist/og/photo-cover.d.ts.map +1 -0
  76. package/dist/og/photo-cover.js +215 -0
  77. package/dist/og/photo-cover.js.map +1 -0
  78. package/dist/og/photo.d.ts +51 -0
  79. package/dist/og/photo.d.ts.map +1 -0
  80. package/dist/og/photo.js +154 -0
  81. package/dist/og/photo.js.map +1 -0
  82. package/dist/voice/provider-failure.d.ts +41 -0
  83. package/dist/voice/provider-failure.d.ts.map +1 -0
  84. package/dist/voice/provider-failure.js +68 -0
  85. package/dist/voice/provider-failure.js.map +1 -0
  86. package/dist/voice/provider.d.ts +7 -1
  87. package/dist/voice/provider.d.ts.map +1 -1
  88. package/dist/voice/provider.js +1 -1
  89. package/dist/voice/provider.js.map +1 -1
  90. package/package.json +2 -1
  91. package/schema/marketing.schema.json +6 -0
  92. package/src/config/schema.ts +7 -0
  93. package/src/footage/clip-sound.ts +124 -0
  94. package/src/footage/declick.ts +3 -4
  95. package/src/footage/draft.ts +125 -24
  96. package/src/footage/elevenlabs.ts +11 -3
  97. package/src/footage/failure.ts +57 -0
  98. package/src/footage/fake.ts +28 -4
  99. package/src/footage/film-mix.ts +10 -2
  100. package/src/footage/hyperframes-capture.ts +100 -0
  101. package/src/footage/isolate-ranges.ts +158 -22
  102. package/src/footage/loudness.ts +17 -8
  103. package/src/footage/paid.ts +29 -4
  104. package/src/footage/pipeline.ts +85 -66
  105. package/src/footage/providers.ts +5 -0
  106. package/src/footage/render.ts +4 -3
  107. package/src/footage/speech-ranges.ts +197 -27
  108. package/src/index.ts +55 -1
  109. package/src/og/index.ts +23 -0
  110. package/src/og/photo-cover.ts +280 -0
  111. package/src/og/photo.ts +177 -0
  112. package/src/voice/provider-failure.ts +98 -0
  113. package/src/voice/provider.ts +7 -2
@@ -0,0 +1,280 @@
1
+ import { readFileSync } from "node:fs";
2
+
3
+ import { Resvg } from "@resvg/resvg-js";
4
+ import jpeg from "jpeg-js";
5
+ import satori from "satori";
6
+ import { z } from "zod";
7
+
8
+ import type { BrandColors } from "../config/colors.js";
9
+ import { h, type OgNode } from "./element.js";
10
+ import { pickWeight, toFontFamilyCss, type OgFonts } from "./fonts.js";
11
+ import { describeCharacter, findMissingGlyphs } from "./glyphs.js";
12
+ import { toOpaqueHex, withAlpha } from "./palette.js";
13
+ import { getCoverCrop, getOrientationMatrix, getOrientedSize, readPhotoInfo, type FocusPoint } from "./photo.js";
14
+ import { err, ok, type OgResult } from "./result.js";
15
+
16
+ /**
17
+ * A publish-ready cover for a vertical video from a photo the owner picks: the photo scaled to cover the frame and
18
+ * cropped around a focus point (EXIF orientation applied), and an optional short caption in the brand's display
19
+ * font, kept inside the lower half of the centre 4:5 band the platforms keep when they crop the cover for the profile
20
+ * grid. Satori
21
+ * lays the caption out, resvg draws the whole cover, `jpeg-js` encodes it: no network, no system fonts.
22
+ */
23
+
24
+ /** A Reels, Shorts and TikTok cover. */
25
+ export const PHOTO_COVER_SIZE: readonly [number, number] = [1080, 1920];
26
+
27
+ export const PHOTO_COVER_QUALITY = 90;
28
+
29
+ /** The longest caption accepted before layout; whether a shorter one fits is measured on the drawn caption. */
30
+ export const MAX_COVER_CAPTION_LENGTH = 80;
31
+
32
+ /** Sizes in this file are written for a 1080 px wide band and scaled with its width. */
33
+ const BAND_BASE_WIDTH = 1080;
34
+ const CAPTION_SIDE_PADDING = 80;
35
+ const CAPTION_BOTTOM_PADDING = 120;
36
+ /** A pixel whose alpha is above this counts as drawn when the caption is measured (the shadow's faint fringe does not). */
37
+ const DRAWN_ALPHA = 16;
38
+ /** The scrim's opacity at the band's lower edge and below it. */
39
+ const SCRIM_ALPHA = 0x8c;
40
+
41
+ /** The centre 4:5 band of a cover, in pixels. */
42
+ export interface CoverBand {
43
+ left: number;
44
+ top: number;
45
+ width: number;
46
+ height: number;
47
+ }
48
+
49
+ /** The widest 4:5 rectangle centred in a frame of `size`. */
50
+ export function getCoverBand(size: readonly [number, number]): CoverBand {
51
+ const [width, height] = size;
52
+ const bandWidth = Math.min(width, Math.floor((height * 4) / 5));
53
+ const bandHeight = Math.min(height, Math.round((bandWidth * 5) / 4));
54
+ return { left: Math.floor((width - bandWidth) / 2), top: Math.floor((height - bandHeight) / 2), width: bandWidth, height: bandHeight };
55
+ }
56
+
57
+ /** The caption size at a 1080 px band: shorter captions get bigger type. */
58
+ export function getCoverCaptionSize(caption: string): number {
59
+ if (caption.length <= 16) return 112;
60
+ if (caption.length <= 32) return 96;
61
+ return 80;
62
+ }
63
+
64
+ const coverOptionsSchema = z.object({
65
+ photo: z.union([z.string().min(1), z.instanceof(Buffer)]),
66
+ size: z.tuple([z.number().int().min(64).max(4096), z.number().int().min(64).max(4096)]).default([...PHOTO_COVER_SIZE] as [number, number]),
67
+ focus: z.object({ x: z.number().min(0).max(1), y: z.number().min(0).max(1) }).default({ x: 0.5, y: 0.5 }),
68
+ caption: z
69
+ .string()
70
+ .trim()
71
+ .min(1, "the caption is empty; leave it out for a cover without one")
72
+ .max(MAX_COVER_CAPTION_LENGTH, `the caption is longer than ${String(MAX_COVER_CAPTION_LENGTH)} characters`)
73
+ .optional(),
74
+ quality: z.number().int().min(1).max(100).default(PHOTO_COVER_QUALITY),
75
+ });
76
+
77
+ export interface PhotoCoverInput {
78
+ /** A JPEG or PNG: its path, or its bytes. */
79
+ photo: string | Buffer;
80
+ /** The cover's size; 1080×1920 by default. */
81
+ size?: readonly [number, number];
82
+ /** The point of the upright photo to keep in view, as fractions of its width and height; the centre by default. */
83
+ focus?: FocusPoint;
84
+ /** A short title (2 to 6 words fit best); none draws the cropped photo alone. */
85
+ caption?: string;
86
+ /** The text is the lighter of `foreground` and `background`; the scrim and the shadow the darker. */
87
+ colors: BrandColors;
88
+ /** The brand's fonts (`loadOgFonts`); the caption is set in the heading (display) family. */
89
+ fonts: OgFonts;
90
+ /** JPEG quality, 1-100; 90 by default. */
91
+ quality?: number;
92
+ /** Names the cover in errors, e.g. the video's id. */
93
+ id?: string;
94
+ }
95
+
96
+ export interface PhotoCover {
97
+ /** A baseline JPEG of exactly `width` × `height`, without an ICC profile (sRGB). */
98
+ jpeg: Buffer;
99
+ width: number;
100
+ height: number;
101
+ bytes: number;
102
+ }
103
+
104
+ function describeCover(id: string | undefined): string {
105
+ return id === undefined ? "Photo cover" : `Photo cover "${id}"`;
106
+ }
107
+
108
+ function readPhoto(photo: string | Buffer): OgResult<Buffer> {
109
+ if (typeof photo !== "string") return ok(photo);
110
+ try {
111
+ return ok(readFileSync(photo));
112
+ } catch (error) {
113
+ return err(`reading the photo ${photo}: ${(error as NodeJS.ErrnoException).code ?? String(error)}`);
114
+ }
115
+ }
116
+
117
+ /** Relative luminance (WCAG) of an opaque `#rrggbb`. */
118
+ function getLuminance(color: string): number {
119
+ const hex = toOpaqueHex(color);
120
+ const channel = (offset: number) => {
121
+ const value = Number.parseInt(hex.slice(offset, offset + 2), 16) / 255;
122
+ return value <= 0.039_28 ? value / 12.92 : ((value + 0.055) / 1.055) ** 2.4;
123
+ };
124
+ return 0.2126 * channel(1) + 0.7152 * channel(3) + 0.0722 * channel(5);
125
+ }
126
+
127
+ /** The brand's light and dark colour among its foreground and background. */
128
+ function getCoverInk(colors: BrandColors): { text: string; shade: string } {
129
+ const foreground = toOpaqueHex(colors.foreground);
130
+ const background = toOpaqueHex(colors.background);
131
+ return getLuminance(foreground) >= getLuminance(background) ? { text: foreground, shade: background } : { text: background, shade: foreground };
132
+ }
133
+
134
+ interface CaptionLayout {
135
+ size: readonly [number, number];
136
+ band: CoverBand;
137
+ caption: string;
138
+ fonts: OgFonts;
139
+ ink: { text: string; shade: string };
140
+ }
141
+
142
+ /** The caption alone on a transparent frame: centred, its foot above the band's lower edge. */
143
+ function buildCaptionTree(layout: CaptionLayout): OgNode {
144
+ const [width, height] = layout.size;
145
+ const { band, fonts, ink } = layout;
146
+ const scale = band.width / BAND_BASE_WIDTH;
147
+ const side = Math.round(CAPTION_SIDE_PADDING * scale);
148
+ const fontSize = Math.round(getCoverCaptionSize(layout.caption) * scale);
149
+ return h(
150
+ "div",
151
+ { style: { display: "flex", position: "relative", width, height } },
152
+ h(
153
+ "div",
154
+ {
155
+ style: {
156
+ position: "absolute",
157
+ display: "flex",
158
+ justifyContent: "center",
159
+ left: band.left + side,
160
+ width: band.width - 2 * side,
161
+ bottom: height - (band.top + band.height) + Math.round(CAPTION_BOTTOM_PADDING * scale),
162
+ fontFamily: toFontFamilyCss(fonts.heading),
163
+ fontSize,
164
+ fontWeight: pickWeight(fonts.heading.weights, 700),
165
+ lineHeight: 1.08,
166
+ textAlign: "center",
167
+ wordBreak: "break-word",
168
+ color: ink.text,
169
+ textShadow: `0px ${String(Math.round(4 * scale))}px ${String(Math.round(24 * scale))}px ${withAlpha(ink.shade, 0xb3)}`,
170
+ },
171
+ },
172
+ layout.caption,
173
+ ),
174
+ );
175
+ }
176
+
177
+ function checkCaptionGlyphs(tree: OgNode, fonts: OgFonts, caption: string): OgResult<null> {
178
+ const missing = findMissingGlyphs(tree, fonts.satoriFonts);
179
+ if (!missing.ok) return err(`reading ${missing.error}`);
180
+ const characters = missing.value.flatMap((entry) => entry.characters);
181
+ if (characters.length === 0) return ok(null);
182
+ return err(
183
+ `the caption ${JSON.stringify(caption)} has characters none of the loaded fonts can draw at its weight: ${characters.map(describeCharacter).join(", ")}. ` +
184
+ "Use font files that cover them.",
185
+ );
186
+ }
187
+
188
+ /** The rows of `pixels` (RGBA, `width` wide) that hold anything drawn, or null when nothing is. */
189
+ function findDrawnBox(pixels: Uint8Array, width: number, height: number): { top: number; bottom: number; left: number; right: number } | null {
190
+ let top = height;
191
+ let bottom = -1;
192
+ let left = width;
193
+ let right = -1;
194
+ for (let y = 0; y < height; y += 1) {
195
+ for (let x = 0; x < width; x += 1) {
196
+ if ((pixels[(y * width + x) * 4 + 3] ?? 0) <= DRAWN_ALPHA) continue;
197
+ top = Math.min(top, y);
198
+ bottom = Math.max(bottom, y);
199
+ left = Math.min(left, x);
200
+ right = Math.max(right, x);
201
+ }
202
+ }
203
+ return bottom < 0 ? null : { top, bottom, left, right };
204
+ }
205
+
206
+ /** The caption as SVG and the top of what it draws, or an error when it does not fit the band. */
207
+ async function layOutCaption(layout: CaptionLayout): Promise<OgResult<{ svg: string; top: number }>> {
208
+ const tree = buildCaptionTree(layout);
209
+ const glyphs = checkCaptionGlyphs(tree, layout.fonts, layout.caption);
210
+ if (!glyphs.ok) return glyphs;
211
+ const [width, height] = layout.size;
212
+ let svg: string;
213
+ try {
214
+ // Satori is typed for React elements; it reads only `type` and `props`, which `OgNode` has.
215
+ svg = await satori(tree as unknown as Parameters<typeof satori>[0], { width, height, fonts: layout.fonts.satoriFonts });
216
+ } catch (error) {
217
+ return err(`laying out the caption failed: ${error instanceof Error ? error.message : String(error)}`);
218
+ }
219
+ const pixels = new Resvg(svg, { fitTo: { mode: "original" }, font: { loadSystemFonts: false } }).render().pixels;
220
+ const box = findDrawnBox(pixels, width, height);
221
+ if (box === null) return err(`the caption ${JSON.stringify(layout.caption)} draws nothing`);
222
+ const { band } = layout;
223
+ // The caption keeps to the lower half of the band, so the photo's subject above it stays clear.
224
+ const isInside = box.top >= band.top + Math.floor(band.height / 2) && box.bottom < band.top + band.height && box.left >= band.left && box.right < band.left + band.width;
225
+ if (!isInside) {
226
+ return err(`the caption ${JSON.stringify(layout.caption)} does not fit the lower half of the centre 4:5 band (${String(band.width)}×${String(band.height)}); shorten it`);
227
+ }
228
+ return ok({ svg, top: box.top });
229
+ }
230
+
231
+ const toDataUri = (type: string, bytes: Buffer | string) => `data:${type};base64,${Buffer.from(bytes).toString("base64")}`;
232
+
233
+ /** Renders the cover: the photo cropped to `size` around the focus point, the caption (if any) over a soft scrim. */
234
+ export async function renderPhotoCover(input: PhotoCoverInput): Promise<OgResult<PhotoCover>> {
235
+ const name = describeCover(input.id);
236
+ const parsed = coverOptionsSchema.safeParse({ photo: input.photo, size: input.size, focus: input.focus, caption: input.caption, quality: input.quality });
237
+ if (!parsed.success) {
238
+ const lines = parsed.error.issues.map((issue) => ` ${issue.path.length > 0 ? issue.path.join(".") : "input"}: ${issue.message}`);
239
+ return err(`${name}: the input is not valid:\n${lines.join("\n")}`);
240
+ }
241
+ const options = parsed.data;
242
+ const bytes = readPhoto(options.photo);
243
+ if (!bytes.ok) return err(`${name}: ${bytes.error}.`);
244
+ const info = readPhotoInfo(bytes.value);
245
+ if (!info.ok) return err(`${name}: the photo${typeof options.photo === "string" ? ` ${options.photo}` : ""} cannot be used: ${info.error}.`);
246
+
247
+ const size = options.size;
248
+ const [width, height] = size;
249
+ const band = getCoverBand(size);
250
+ const ink = getCoverInk(input.colors);
251
+ const caption = options.caption === undefined ? null : await layOutCaption({ size, band, caption: options.caption, fonts: input.fonts, ink });
252
+ if (caption !== null && !caption.ok) return err(`${name}: ${caption.error}.`);
253
+
254
+ const crop = getCoverCrop(getOrientedSize(info.value), size, options.focus);
255
+ const matrix = getOrientationMatrix(info.value.orientation, info.value.width, info.value.height).join(" ");
256
+ const layers = [
257
+ `<rect width="${String(width)}" height="${String(height)}" fill="${ink.shade}"/>`,
258
+ `<image href="${toDataUri(`image/${info.value.format}`, bytes.value)}" width="${String(info.value.width)}" height="${String(info.value.height)}" preserveAspectRatio="none" ` +
259
+ `transform="translate(${String(crop.x)} ${String(crop.y)}) scale(${String(crop.scale)}) matrix(${matrix})"/>`,
260
+ ];
261
+ if (caption !== null) {
262
+ // The scrim fades in over a fifth of the band above the caption and holds from the band's lower edge down.
263
+ const bandBottom = band.top + band.height;
264
+ const start = Math.max(0, caption.value.top - Math.round(band.height / 5));
265
+ layers.push(
266
+ `<defs><linearGradient id="scrim" gradientUnits="userSpaceOnUse" x1="0" y1="${String(start)}" x2="0" y2="${String(bandBottom)}">` +
267
+ `<stop offset="0" stop-color="${ink.shade}" stop-opacity="0"/><stop offset="1" stop-color="${ink.shade}" stop-opacity="${(SCRIM_ALPHA / 255).toFixed(3)}"/></linearGradient></defs>`,
268
+ `<rect y="${String(start)}" width="${String(width)}" height="${String(height - start)}" fill="url(#scrim)"/>`,
269
+ `<image href="${toDataUri("image/svg+xml", caption.value.svg)}" width="${String(width)}" height="${String(height)}"/>`,
270
+ );
271
+ }
272
+ const svg = `<svg xmlns="http://www.w3.org/2000/svg" width="${String(width)}" height="${String(height)}" viewBox="0 0 ${String(width)} ${String(height)}">${layers.join("")}</svg>`;
273
+ try {
274
+ const image = new Resvg(svg, { fitTo: { mode: "original" }, font: { loadSystemFonts: false } }).render();
275
+ const encoded = jpeg.encode({ data: Buffer.from(image.pixels), width: image.width, height: image.height }, options.quality).data;
276
+ return ok({ jpeg: encoded, width: image.width, height: image.height, bytes: encoded.length });
277
+ } catch (error) {
278
+ return err(`${name}: drawing the cover failed: ${error instanceof Error ? error.message : String(error)}.`);
279
+ }
280
+ }
@@ -0,0 +1,177 @@
1
+ import { err, ok, type OgResult } from "./result.js";
2
+
3
+ /**
4
+ * What a photo's header says, read without decoding it: the format, the stored pixel size and the EXIF orientation.
5
+ * resvg draws a JPEG or PNG as stored and ignores EXIF orientation, so a cover applies the orientation itself
6
+ * (`getOrientationMatrix`).
7
+ */
8
+
9
+ export type PhotoFormat = "jpeg" | "png";
10
+
11
+ /** EXIF orientation 1-8: 1 is upright, 5-8 swap width and height. */
12
+ export type PhotoOrientation = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8;
13
+
14
+ export interface PhotoInfo {
15
+ format: PhotoFormat;
16
+ /** The stored size, before orientation. */
17
+ width: number;
18
+ height: number;
19
+ orientation: PhotoOrientation;
20
+ }
21
+
22
+ const PNG_SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
23
+ const EXIF_HEADER = Buffer.from("Exif\0\0", "latin1");
24
+ const ORIENTATION_TAG = 0x0112;
25
+ const SHORT_TYPE = 3;
26
+
27
+ function isOrientation(value: number): value is PhotoOrientation {
28
+ return Number.isInteger(value) && value >= 1 && value <= 8;
29
+ }
30
+
31
+ /** The orientation in a TIFF block (an EXIF payload after `Exif\0\0`, or a PNG `eXIf` chunk); 1 when absent. */
32
+ export function readTiffOrientation(tiff: Buffer): PhotoOrientation {
33
+ if (tiff.length < 8) return 1;
34
+ const order = tiff.toString("latin1", 0, 2);
35
+ if (order !== "II" && order !== "MM") return 1;
36
+ const isLittle = order === "II";
37
+ const u16 = (offset: number) => (isLittle ? tiff.readUInt16LE(offset) : tiff.readUInt16BE(offset));
38
+ const u32 = (offset: number) => (isLittle ? tiff.readUInt32LE(offset) : tiff.readUInt32BE(offset));
39
+ if (u16(2) !== 42) return 1;
40
+ const ifd = u32(4);
41
+ if (ifd + 2 > tiff.length) return 1;
42
+ const count = u16(ifd);
43
+ for (let index = 0; index < count; index += 1) {
44
+ const entry = ifd + 2 + index * 12;
45
+ if (entry + 12 > tiff.length) return 1;
46
+ if (u16(entry) !== ORIENTATION_TAG) continue;
47
+ if (u16(entry + 2) !== SHORT_TYPE) return 1;
48
+ const value = u16(entry + 8);
49
+ return isOrientation(value) ? value : 1;
50
+ }
51
+ return 1;
52
+ }
53
+
54
+ /** SOFn markers carry the frame size; C4 (DHT), C8 (JPG) and CC (DAC) share the range but are not frames. */
55
+ function isStartOfFrame(marker: number): boolean {
56
+ return marker >= 0xc0 && marker <= 0xcf && marker !== 0xc4 && marker !== 0xc8 && marker !== 0xcc;
57
+ }
58
+
59
+ function readJpegInfo(bytes: Buffer): OgResult<PhotoInfo> {
60
+ let orientation: PhotoOrientation = 1;
61
+ let offset = 2;
62
+ while (offset + 4 <= bytes.length) {
63
+ if (bytes[offset] !== 0xff) return err("the JPEG's markers are damaged");
64
+ const marker = bytes[offset + 1] ?? 0;
65
+ // Fill bytes and markers without a length (RSTn, TEM) carry no segment.
66
+ if (marker === 0xff) {
67
+ offset += 1;
68
+ continue;
69
+ }
70
+ if (marker === 0x01 || (marker >= 0xd0 && marker <= 0xd7)) {
71
+ offset += 2;
72
+ continue;
73
+ }
74
+ if (marker === 0xd9 || marker === 0xda) break;
75
+ const length = bytes.readUInt16BE(offset + 2);
76
+ const start = offset + 4;
77
+ const end = offset + 2 + length;
78
+ if (length < 2 || end > bytes.length) return err("the JPEG ends inside a segment");
79
+ if (marker === 0xe1 && bytes.subarray(start, start + EXIF_HEADER.length).equals(EXIF_HEADER)) {
80
+ orientation = readTiffOrientation(bytes.subarray(start + EXIF_HEADER.length, end));
81
+ }
82
+ if (isStartOfFrame(marker)) {
83
+ if (length < 7) return err("the JPEG's frame header is too short");
84
+ const height = bytes.readUInt16BE(start + 1);
85
+ const width = bytes.readUInt16BE(start + 3);
86
+ if (width === 0 || height === 0) return err("the JPEG has no pixel size");
87
+ return ok({ format: "jpeg", width, height, orientation });
88
+ }
89
+ offset = end;
90
+ }
91
+ return err("the JPEG has no frame header");
92
+ }
93
+
94
+ function readPngInfo(bytes: Buffer): OgResult<PhotoInfo> {
95
+ if (bytes.length < 33 || bytes.toString("latin1", 12, 16) !== "IHDR") return err("the PNG has no IHDR chunk");
96
+ const width = bytes.readUInt32BE(16);
97
+ const height = bytes.readUInt32BE(20);
98
+ if (width === 0 || height === 0) return err("the PNG has no pixel size");
99
+ let orientation: PhotoOrientation = 1;
100
+ let offset = 8;
101
+ while (offset + 8 <= bytes.length) {
102
+ const length = bytes.readUInt32BE(offset);
103
+ const type = bytes.toString("latin1", offset + 4, offset + 8);
104
+ const end = offset + 12 + length;
105
+ if (end > bytes.length) break;
106
+ if (type === "eXIf") orientation = readTiffOrientation(bytes.subarray(offset + 8, offset + 8 + length));
107
+ if (type === "IDAT" || type === "IEND") break;
108
+ offset = end;
109
+ }
110
+ return ok({ format: "png", width, height, orientation });
111
+ }
112
+
113
+ /** The format, stored size and orientation of a JPEG or PNG; anything else is an error naming what is wrong. */
114
+ export function readPhotoInfo(bytes: Buffer): OgResult<PhotoInfo> {
115
+ if (bytes.length >= 3 && bytes[0] === 0xff && bytes[1] === 0xd8 && bytes[2] === 0xff) return readJpegInfo(bytes);
116
+ if (bytes.subarray(0, PNG_SIGNATURE.length).equals(PNG_SIGNATURE)) return readPngInfo(bytes);
117
+ return err("it is neither a JPEG nor a PNG");
118
+ }
119
+
120
+ /** The size a viewer shows: orientations 5-8 turn the photo a quarter, swapping width and height. */
121
+ export function getOrientedSize(info: Pick<PhotoInfo, "width" | "height" | "orientation">): { width: number; height: number } {
122
+ return info.orientation >= 5 ? { width: info.height, height: info.width } : { width: info.width, height: info.height };
123
+ }
124
+
125
+ /**
126
+ * The SVG `matrix(a b c d e f)` that maps the stored pixels (`width` × `height`) onto the upright photo, so that
127
+ * `x' = a·x + c·y + e` and `y' = b·x + d·y + f`.
128
+ */
129
+ export function getOrientationMatrix(orientation: PhotoOrientation, width: number, height: number): readonly [number, number, number, number, number, number] {
130
+ switch (orientation) {
131
+ case 1:
132
+ return [1, 0, 0, 1, 0, 0];
133
+ case 2:
134
+ return [-1, 0, 0, 1, width, 0];
135
+ case 3:
136
+ return [-1, 0, 0, -1, width, height];
137
+ case 4:
138
+ return [1, 0, 0, -1, 0, height];
139
+ case 5:
140
+ return [0, 1, 1, 0, 0, 0];
141
+ case 6:
142
+ return [0, 1, -1, 0, height, 0];
143
+ case 7:
144
+ return [0, -1, -1, 0, height, width];
145
+ case 8:
146
+ return [0, -1, 1, 0, 0, width];
147
+ }
148
+ }
149
+
150
+ /** A point of the photo as fractions of its upright width and height, 0..1. */
151
+ export interface FocusPoint {
152
+ x: number;
153
+ y: number;
154
+ }
155
+
156
+ /** How the upright photo is scaled and shifted to cover the frame. */
157
+ export interface CoverCrop {
158
+ scale: number;
159
+ /** The scaled photo's offset from the frame's top-left corner, zero or negative. */
160
+ x: number;
161
+ y: number;
162
+ }
163
+
164
+ /**
165
+ * Scales the upright photo to cover `frame` and shifts it so the focus point sits as near the frame's centre as the
166
+ * photo allows: an edge of the photo never comes inside the frame.
167
+ */
168
+ export function getCoverCrop(photo: { width: number; height: number }, frame: readonly [number, number], focus: FocusPoint): CoverCrop {
169
+ const [width, height] = frame;
170
+ const scale = Math.max(width / photo.width, height / photo.height);
171
+ const place = (length: number, target: number, at: number) => {
172
+ const scaled = length * scale;
173
+ const offset = target / 2 - at * scaled;
174
+ return Math.min(0, Math.max(target - scaled, offset));
175
+ };
176
+ return { scale, x: place(photo.width, width, focus.x), y: place(photo.height, height, focus.y) };
177
+ }
@@ -0,0 +1,98 @@
1
+ /**
2
+ * Why a paid provider call failed, as values an app can log and act on (issue #1141). Every field is safe to log:
3
+ * no key, path, transcript or audio content. `message` is the provider's own message, truncated.
4
+ * - `refused`: the provider answered a 4xx other than 408 and 429 (a bad input, key or balance). Asking again fails
5
+ * the same way.
6
+ * - `rate_limited`: 429. `unavailable`: 5xx. `timeout`: 408 or the request timed out. `connection`: no answer.
7
+ */
8
+ export interface ProviderFailure {
9
+ kind: ProviderFailureKind;
10
+ /** The HTTP status; null when the provider never answered. */
11
+ status: number | null;
12
+ /** The provider's error code (e.g. `audio_too_short`); null when it gave none. */
13
+ code: string | null;
14
+ /** The provider's message, at most `PROVIDER_MESSAGE_LENGTH` characters; null when it gave none. */
15
+ message: string | null;
16
+ /** The provider's request id (header `request-id` or `x-request-id`, or the body's `request_id`). */
17
+ requestId: string | null;
18
+ /** True for 5xx, 408, 429, a timeout and a failed connection: asking again may succeed. */
19
+ isRetryable: boolean;
20
+ }
21
+
22
+ export type ProviderFailureKind = "refused" | "rate_limited" | "unavailable" | "timeout" | "connection";
23
+
24
+ export const PROVIDER_MESSAGE_LENGTH = 300;
25
+
26
+ const REQUEST_ID_HEADERS = ["request-id", "x-request-id"];
27
+
28
+ /** The kind of an HTTP status the provider answered (not 2xx). */
29
+ export function getProviderFailureKind(status: number): ProviderFailureKind {
30
+ if (status === 429) return "rate_limited";
31
+ if (status === 408) return "timeout";
32
+ if (status >= 500) return "unavailable";
33
+ return "refused";
34
+ }
35
+
36
+ const isRetryableKind = (kind: ProviderFailureKind): boolean => kind !== "refused";
37
+
38
+ const truncate = (text: string): string | null => {
39
+ const trimmed = text.trim();
40
+ return trimmed.length === 0 ? null : trimmed.slice(0, PROVIDER_MESSAGE_LENGTH);
41
+ };
42
+
43
+ const readString = (value: unknown): string | null => (typeof value === "string" && value.trim().length > 0 ? value.trim() : null);
44
+
45
+ interface ErrorBody {
46
+ code: string | null;
47
+ message: string | null;
48
+ requestId: string | null;
49
+ }
50
+
51
+ /** The provider's code, message and request id from an error body: `{ detail: { code | status, message, request_id } }`, `{ detail: "…" }` or text. */
52
+ export function readProviderErrorBody(text: string): ErrorBody {
53
+ let body: unknown;
54
+ try {
55
+ body = JSON.parse(text) as unknown;
56
+ } catch {
57
+ return { code: null, message: truncate(text), requestId: null };
58
+ }
59
+ const root = typeof body === "object" && body !== null ? (body as Record<string, unknown>) : {};
60
+ const detail = root.detail ?? root.error ?? root;
61
+ if (typeof detail === "string") return { code: null, message: truncate(detail), requestId: readString(root.request_id) };
62
+ const fields = typeof detail === "object" && detail !== null ? (detail as Record<string, unknown>) : {};
63
+ const message = readString(fields.message);
64
+ return {
65
+ code: readString(fields.code) ?? readString(fields.status) ?? readString(fields.type),
66
+ message: message === null ? null : truncate(message),
67
+ requestId: readString(fields.request_id) ?? readString(root.request_id),
68
+ };
69
+ }
70
+
71
+ /** The failure of a response that is not 2xx, from its status, headers and body text. */
72
+ export function getProviderFailure(response: Response, text: string): ProviderFailure {
73
+ const body = readProviderErrorBody(text);
74
+ const header = REQUEST_ID_HEADERS.map((name) => readString(response.headers.get(name))).find((value) => value !== null) ?? null;
75
+ const kind = getProviderFailureKind(response.status);
76
+ return { kind, status: response.status, code: body.code, message: body.message, requestId: header ?? body.requestId, isRetryable: isRetryableKind(kind) };
77
+ }
78
+
79
+ /** The failure of a request that got no answer: `timeout` when it timed out, `connection` otherwise. */
80
+ export function getConnectionFailure(error: unknown): ProviderFailure {
81
+ const kind: ProviderFailureKind = error instanceof Error && error.name === "TimeoutError" ? "timeout" : "connection";
82
+ return { kind, status: null, code: null, message: null, requestId: null, isRetryable: true };
83
+ }
84
+
85
+ /** A failure the kit decides before any request (e.g. a missing key): `refused`, with the kit's own code. */
86
+ export function getLocalRefusal(code: string): ProviderFailure {
87
+ return { kind: "refused", status: null, code, message: null, requestId: null, isRetryable: false };
88
+ }
89
+
90
+ /** The failure in one line for a log: kind, status, code, request id and message. */
91
+ export function describeProviderFailure(failure: ProviderFailure): string {
92
+ const parts: string[] = [failure.kind];
93
+ if (failure.status !== null) parts.push(String(failure.status));
94
+ if (failure.code !== null) parts.push(failure.code);
95
+ if (failure.requestId !== null) parts.push(`request ${failure.requestId}`);
96
+ const head = parts.join(", ");
97
+ return failure.message === null ? head : `${head}: ${failure.message}`;
98
+ }
@@ -1,3 +1,4 @@
1
+ import type { ProviderFailure } from "./provider-failure.js";
1
2
  import type { TimedWord } from "./voiceover.js";
2
3
 
3
4
  /** What a provider speaks: the text in one voice, model and language. */
@@ -26,7 +27,11 @@ export interface TtsEstimate {
26
27
  unit: string;
27
28
  }
28
29
 
29
- export type TtsResult<T> = { ok: true; value: T } | { ok: false; error: string };
30
+ /**
31
+ * A provider's answer. A failure carries `error`, the sentence for logs, and, when the provider answered (or the kit
32
+ * refused before asking), `providerFailure`: what an app logs and reads to decide whether to ask again (#1141).
33
+ */
34
+ export type TtsResult<T> = { ok: true; value: T } | { ok: false; error: string; providerFailure?: ProviderFailure };
30
35
 
31
36
  /**
32
37
  * A text-to-speech service. `estimate` is free and needs no credentials; `synthesize` may spend
@@ -39,4 +44,4 @@ export interface TtsProvider {
39
44
  }
40
45
 
41
46
  export const ok = <T>(value: T): TtsResult<T> => ({ ok: true, value });
42
- export const err = <T>(error: string): TtsResult<T> => ({ ok: false, error });
47
+ export const err = <T>(error: string, providerFailure?: ProviderFailure): TtsResult<T> => (providerFailure === undefined ? { ok: false, error } : { ok: false, error, providerFailure });