@softure-ai/marketing-kit 0.15.0 → 0.17.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 (108) hide show
  1. package/CHANGELOG.md +91 -0
  2. package/README.md +138 -16
  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 +92 -22
  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 +12 -1
  24. package/dist/footage/failure.d.ts.map +1 -1
  25. package/dist/footage/failure.js +10 -1
  26. package/dist/footage/failure.js.map +1 -1
  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/hyperframes-capture.d.ts +30 -0
  32. package/dist/footage/hyperframes-capture.d.ts.map +1 -0
  33. package/dist/footage/hyperframes-capture.js +80 -0
  34. package/dist/footage/hyperframes-capture.js.map +1 -0
  35. package/dist/footage/isolate-ranges.d.ts +34 -6
  36. package/dist/footage/isolate-ranges.d.ts.map +1 -1
  37. package/dist/footage/isolate-ranges.js +90 -23
  38. package/dist/footage/isolate-ranges.js.map +1 -1
  39. package/dist/footage/loudness.d.ts +16 -2
  40. package/dist/footage/loudness.d.ts.map +1 -1
  41. package/dist/footage/loudness.js +10 -7
  42. package/dist/footage/loudness.js.map +1 -1
  43. package/dist/footage/paid.d.ts +12 -2
  44. package/dist/footage/paid.d.ts.map +1 -1
  45. package/dist/footage/paid.js +8 -3
  46. package/dist/footage/paid.js.map +1 -1
  47. package/dist/footage/pipeline.d.ts +14 -2
  48. package/dist/footage/pipeline.d.ts.map +1 -1
  49. package/dist/footage/pipeline.js +55 -46
  50. package/dist/footage/pipeline.js.map +1 -1
  51. package/dist/footage/providers.d.ts +5 -0
  52. package/dist/footage/providers.d.ts.map +1 -1
  53. package/dist/footage/providers.js.map +1 -1
  54. package/dist/footage/render.d.ts +1 -1
  55. package/dist/footage/render.d.ts.map +1 -1
  56. package/dist/footage/render.js +4 -3
  57. package/dist/footage/render.js.map +1 -1
  58. package/dist/footage/speech-ranges.d.ts +79 -11
  59. package/dist/footage/speech-ranges.d.ts.map +1 -1
  60. package/dist/footage/speech-ranges.js +137 -17
  61. package/dist/footage/speech-ranges.js.map +1 -1
  62. package/dist/index.d.ts +9 -6
  63. package/dist/index.d.ts.map +1 -1
  64. package/dist/index.js +8 -5
  65. package/dist/index.js.map +1 -1
  66. package/dist/og/index.d.ts +2 -0
  67. package/dist/og/index.d.ts.map +1 -1
  68. package/dist/og/index.js +2 -0
  69. package/dist/og/index.js.map +1 -1
  70. package/dist/og/photo-cover.d.ts +74 -0
  71. package/dist/og/photo-cover.d.ts.map +1 -0
  72. package/dist/og/photo-cover.js +357 -0
  73. package/dist/og/photo-cover.js.map +1 -0
  74. package/dist/og/photo.d.ts +51 -0
  75. package/dist/og/photo.d.ts.map +1 -0
  76. package/dist/og/photo.js +154 -0
  77. package/dist/og/photo.js.map +1 -0
  78. package/dist/voice/provider-failure.d.ts +41 -0
  79. package/dist/voice/provider-failure.d.ts.map +1 -0
  80. package/dist/voice/provider-failure.js +68 -0
  81. package/dist/voice/provider-failure.js.map +1 -0
  82. package/dist/voice/provider.d.ts +7 -1
  83. package/dist/voice/provider.d.ts.map +1 -1
  84. package/dist/voice/provider.js +1 -1
  85. package/dist/voice/provider.js.map +1 -1
  86. package/package.json +2 -1
  87. package/schema/marketing.schema.json +6 -0
  88. package/src/config/schema.ts +7 -0
  89. package/src/footage/clip-sound.ts +124 -0
  90. package/src/footage/declick.ts +3 -4
  91. package/src/footage/draft.ts +123 -22
  92. package/src/footage/elevenlabs.ts +11 -3
  93. package/src/footage/failure.ts +14 -1
  94. package/src/footage/fake.ts +28 -4
  95. package/src/footage/hyperframes-capture.ts +100 -0
  96. package/src/footage/isolate-ranges.ts +124 -29
  97. package/src/footage/loudness.ts +17 -8
  98. package/src/footage/paid.ts +25 -3
  99. package/src/footage/pipeline.ts +68 -47
  100. package/src/footage/providers.ts +5 -0
  101. package/src/footage/render.ts +4 -3
  102. package/src/footage/speech-ranges.ts +184 -19
  103. package/src/index.ts +49 -1
  104. package/src/og/index.ts +28 -0
  105. package/src/og/photo-cover.ts +442 -0
  106. package/src/og/photo.ts +177 -0
  107. package/src/voice/provider-failure.ts +98 -0
  108. package/src/voice/provider.ts +7 -2
package/src/index.ts CHANGED
@@ -84,6 +84,17 @@ export {
84
84
  type TtsRequest,
85
85
  } from "./voice/voiceover.js";
86
86
  export type { TtsEstimate, TtsInput, TtsProvider, TtsRecording, TtsResult } from "./voice/provider.js";
87
+ export {
88
+ describeProviderFailure,
89
+ getConnectionFailure,
90
+ getLocalRefusal,
91
+ getProviderFailure,
92
+ getProviderFailureKind,
93
+ readProviderErrorBody,
94
+ PROVIDER_MESSAGE_LENGTH,
95
+ type ProviderFailure,
96
+ type ProviderFailureKind,
97
+ } from "./voice/provider-failure.js";
87
98
  export { ELEVENLABS_API_KEY_ENV, ELEVENLABS_PROVIDER_ID, createElevenLabsProvider, type ElevenLabsOptions } from "./voice/elevenlabs.js";
88
99
  export { createFakeTtsProvider, type FakeTtsOptions, type FakeTtsProvider } from "./voice/fake.js";
89
100
  export { createTtsProvider, type CreateTtsProviderOptions, type TtsProviderId } from "./voice/providers.js";
@@ -152,15 +163,21 @@ export {
152
163
  countOgSlides,
153
164
  getDefaultOgSize,
154
165
  OG_TEMPLATE_IDS,
166
+ PHOTO_COVER_LAYOUTS,
155
167
  getOgPalette,
156
168
  loadOgFonts,
157
169
  renderConfiguredOgImage,
158
170
  renderOgImage,
171
+ renderPhotoCover,
159
172
  type ConfiguredOgImageOptions,
160
173
  type OgBrand,
161
174
  type OgImageInput,
162
175
  type OgResult,
163
176
  type OgTemplateId,
177
+ type PhotoCover,
178
+ type PhotoCoverInput,
179
+ type PhotoCoverLayout,
180
+ type PhotoCoverTone,
164
181
  } from "./og/index.js";
165
182
  export { buildPosts, postsMarkdown, type PlatformPost, type PostsInput } from "./posts/posts.js";
166
183
  export { createActionScene, getLocator, runAction, type LocatorSource } from "./record/actions.js";
@@ -293,6 +310,7 @@ export {
293
310
  type SttTranscript,
294
311
  } from "./footage/providers.js";
295
312
  export {
313
+ ELEVENLABS_ISOLATION_MIN_SECONDS,
296
314
  ELEVENLABS_MUSIC_MODEL,
297
315
  ELEVENLABS_STT_MODEL,
298
316
  createElevenLabsFootageProviders,
@@ -309,6 +327,7 @@ export {
309
327
  createFakeMusicProvider,
310
328
  createFakeSttProvider,
311
329
  makePlaceholderTranscript,
330
+ type FakeIsolationOptions,
312
331
  type FakeIsolationProvider,
313
332
  type FakeMusicProvider,
314
333
  type FakeSttOptions,
@@ -419,6 +438,18 @@ export {
419
438
  type PicturePieceArgsInput,
420
439
  } from "./footage/picture.js";
421
440
  export {
441
+ SPEECH_PRE_GAIN,
442
+ buildClipSoundArgs,
443
+ buildClipSoundMeasureArgs,
444
+ getAudioCodecArgs,
445
+ getClipSoundPath,
446
+ getPreGainDb,
447
+ prepareClipSounds,
448
+ type ClipSound,
449
+ type ClipSoundInput,
450
+ } from "./footage/clip-sound.js";
451
+ export {
452
+ AUDIO_BITRATE_RANGE_KBPS,
422
453
  DEFAULT_LOUDNESS,
423
454
  buildLoudnessArgs,
424
455
  buildLoudnessMeasureArgs,
@@ -503,17 +534,26 @@ export {
503
534
  export {
504
535
  DEFAULT_SPEECH_RANGE_FADE_MS,
505
536
  DEFAULT_SPEECH_RANGE_MARGIN,
537
+ DEFAULT_SPEECH_RANGE_MERGE_GAP,
538
+ DEFAULT_SPEECH_RANGE_MIN_PAD,
506
539
  buildRangeAudioArgs,
507
540
  buildRangeLayArgs,
541
+ buildRangeMeasureArgs,
542
+ formatSpeechRangeGain,
543
+ getRangeInputGainDb,
508
544
  getSpeechRangeCache,
509
545
  getSpeechRangeFades,
546
+ getSpeechRangeGainPath,
510
547
  getSpeechRangeWindows,
511
548
  planSpeechRanges,
549
+ readSpeechRangeGain,
512
550
  type LaidRange,
551
+ type PlanSpeechRangesOptions,
513
552
  type SpeechRange,
514
553
  type SpeechRangeCacheResolver,
515
554
  type SpeechRangeClip,
516
555
  type SpeechRangeFade,
556
+ type SpeechRangeSkip,
517
557
  type SpeechRangeWindow,
518
558
  } from "./footage/speech-ranges.js";
519
559
  export {
@@ -526,6 +566,14 @@ export {
526
566
  type SpeechRangeOutcome,
527
567
  type SpeechRangeRetry,
528
568
  } from "./footage/isolate-ranges.js";
569
+ export {
570
+ HYPERFRAMES_CAPTURE_STAGES,
571
+ readHyperframesCapture,
572
+ type HyperframesCapture,
573
+ type HyperframesCapturePath,
574
+ type HyperframesCaptureStage,
575
+ type HyperframesGpuMode,
576
+ } from "./footage/hyperframes-capture.js";
529
577
  export { RENDER_MIN_FREE_BYTES, findLowDiskProblems, getFreeBytes, getRenderTempDir, type FreeBytesReader } from "./footage/disk.js";
530
578
  export { DRAFT_FILTERS, REQUIRED_DECODERS, REQUIRED_FILTERS, checkFootageTools, findBrowserProblem, readFfmpegListing, type FootageToolsOptions } from "./footage/tools.js";
531
579
  export {
@@ -559,7 +607,7 @@ export {
559
607
  type RenderedFootage,
560
608
  type TranscribeOutcome,
561
609
  } from "./footage/pipeline.js";
562
- export { isRetryableFootageFailure, type FootageError, type FootageFailure, type FootageFailureKind } from "./footage/failure.js";
610
+ export { getProviderFootageFailure, isRetryableFootageFailure, type FootageError, type FootageFailure, type FootageFailureKind } from "./footage/failure.js";
563
611
  export {
564
612
  formatMessage,
565
613
  getMarketingMessages,
package/src/og/index.ts CHANGED
@@ -18,6 +18,34 @@ export {
18
18
  type OgBrand,
19
19
  type OgImageInput,
20
20
  } from "./render.js";
21
+ export {
22
+ MAX_COVER_CAPTION_LENGTH,
23
+ MAX_COVER_KICKER_LENGTH,
24
+ MAX_COVER_PILL_LENGTH,
25
+ PHOTO_COVER_LAYOUTS,
26
+ PHOTO_COVER_QUALITY,
27
+ PHOTO_COVER_SIZE,
28
+ getCoverBand,
29
+ getCoverCaptionSize,
30
+ renderPhotoCover,
31
+ type CoverBand,
32
+ type PhotoCover,
33
+ type PhotoCoverInput,
34
+ type PhotoCoverLayout,
35
+ type PhotoCoverTone,
36
+ } from "./photo-cover.js";
37
+ export {
38
+ getCoverCrop,
39
+ getOrientationMatrix,
40
+ getOrientedSize,
41
+ readPhotoInfo,
42
+ readTiffOrientation,
43
+ type CoverCrop,
44
+ type FocusPoint,
45
+ type PhotoFormat,
46
+ type PhotoInfo,
47
+ type PhotoOrientation,
48
+ } from "./photo.js";
21
49
  export { OG_TEMPLATE_IDS, OG_TEMPLATES, isOgTemplateId, type OgTemplateId } from "./templates/index.js";
22
50
  export { PORTRAIT_BASE, getLayoutScale, type OgLayout, type OgTemplateContext } from "./templates/context.js";
23
51
  export {
@@ -0,0 +1,442 @@
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 optional text in the brand's display font laid out by
19
+ * one of `PHOTO_COVER_LAYOUTS`, kept inside the centre 4:5 band the platforms keep when they crop the cover for the
20
+ * profile grid. Satori lays the text out, resvg draws the whole cover, `jpeg-js` encodes it: no network, no system
21
+ * 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
+ /** The longest kicker (the small line above the title in `kicker-title`). */
33
+ export const MAX_COVER_KICKER_LENGTH = 40;
34
+
35
+ /** The longest label of the `pill` layout (the caption set in a rounded box). */
36
+ export const MAX_COVER_PILL_LENGTH = 32;
37
+
38
+ /**
39
+ * Where the cover's text goes. `photo`: no text. `title-bottom`, `title-center`, `title-top`: the caption in the lower
40
+ * half, the middle third or the upper half of the band. `kicker-title`: a small kicker line above the caption, in the
41
+ * lower half. `pill`: the caption as a short label in a rounded box, in the lower half.
42
+ */
43
+ export const PHOTO_COVER_LAYOUTS = ["photo", "title-bottom", "title-center", "title-top", "kicker-title", "pill"] as const;
44
+
45
+ export type PhotoCoverLayout = (typeof PHOTO_COVER_LAYOUTS)[number];
46
+
47
+ /** `light`: light text over a dark scrim. `dark`: dark text over a light scrim. */
48
+ export type PhotoCoverTone = "light" | "dark";
49
+
50
+ /** Sizes in this file are written for a 1080 px wide band and scaled with its width. */
51
+ const BAND_BASE_WIDTH = 1080;
52
+ const CAPTION_SIDE_PADDING = 80;
53
+ const CAPTION_BOTTOM_PADDING = 120;
54
+ const CAPTION_TOP_PADDING = 120;
55
+ const KICKER_SIZE = 44;
56
+ const KICKER_GAP = 20;
57
+ const PILL_SIZE = 56;
58
+ const PILL_PADDING: readonly [number, number] = [22, 48];
59
+ /** The pill box's opacity: the box is the pill's scrim. */
60
+ const PILL_ALPHA = 0xd9;
61
+ /** A pixel whose alpha is above this counts as drawn when the caption is measured (the shadow's faint fringe does not). */
62
+ const DRAWN_ALPHA = 16;
63
+ /** The scrim's opacity at the band's lower edge and below it. */
64
+ const SCRIM_ALPHA = 0x8c;
65
+
66
+ /** The centre 4:5 band of a cover, in pixels. */
67
+ export interface CoverBand {
68
+ left: number;
69
+ top: number;
70
+ width: number;
71
+ height: number;
72
+ }
73
+
74
+ /** The widest 4:5 rectangle centred in a frame of `size`. */
75
+ export function getCoverBand(size: readonly [number, number]): CoverBand {
76
+ const [width, height] = size;
77
+ const bandWidth = Math.min(width, Math.floor((height * 4) / 5));
78
+ const bandHeight = Math.min(height, Math.round((bandWidth * 5) / 4));
79
+ return { left: Math.floor((width - bandWidth) / 2), top: Math.floor((height - bandHeight) / 2), width: bandWidth, height: bandHeight };
80
+ }
81
+
82
+ /** The caption size at a 1080 px band: shorter captions get bigger type. */
83
+ export function getCoverCaptionSize(caption: string): number {
84
+ if (caption.length <= 16) return 112;
85
+ if (caption.length <= 32) return 96;
86
+ return 80;
87
+ }
88
+
89
+ const coverOptionsSchema = z.object({
90
+ photo: z.union([z.string().min(1), z.instanceof(Buffer)]),
91
+ size: z.tuple([z.number().int().min(64).max(4096), z.number().int().min(64).max(4096)]).default([...PHOTO_COVER_SIZE] as [number, number]),
92
+ focus: z.object({ x: z.number().min(0).max(1), y: z.number().min(0).max(1) }).default({ x: 0.5, y: 0.5 }),
93
+ layout: z.enum(PHOTO_COVER_LAYOUTS).optional(),
94
+ caption: z
95
+ .string()
96
+ .trim()
97
+ .min(1, "the caption is empty; leave it out for a cover without one")
98
+ .max(MAX_COVER_CAPTION_LENGTH, `the caption is longer than ${String(MAX_COVER_CAPTION_LENGTH)} characters`)
99
+ .optional(),
100
+ kicker: z
101
+ .string()
102
+ .trim()
103
+ .min(1, "the kicker is empty")
104
+ .max(MAX_COVER_KICKER_LENGTH, `the kicker is longer than ${String(MAX_COVER_KICKER_LENGTH)} characters`)
105
+ .optional(),
106
+ tone: z.enum(["light", "dark"]).optional(),
107
+ quality: z.number().int().min(1).max(100).default(PHOTO_COVER_QUALITY),
108
+ });
109
+
110
+ export interface PhotoCoverInput {
111
+ /** A JPEG or PNG: its path, or its bytes. */
112
+ photo: string | Buffer;
113
+ /** The cover's size; 1080×1920 by default. */
114
+ size?: readonly [number, number];
115
+ /** The point of the upright photo to keep in view, as fractions of its width and height; the centre by default. */
116
+ focus?: FocusPoint;
117
+ /** Where the text goes (`PHOTO_COVER_LAYOUTS`); `title-bottom` with a caption and `photo` without one by default. */
118
+ layout?: PhotoCoverLayout;
119
+ /** The title (2 to 6 words fit best), or the `pill` label; required by every layout but `photo`, refused by it. */
120
+ caption?: string;
121
+ /** The small line above the title; required by `kicker-title` and refused by the other layouts. */
122
+ kicker?: string;
123
+ /** `light` text over a dark scrim, or `dark` text over a light one; `light` by default. */
124
+ tone?: PhotoCoverTone;
125
+ /** The light colour is the lighter of `foreground` and `background`, the dark colour the darker. */
126
+ colors: BrandColors;
127
+ /** The brand's fonts (`loadOgFonts`); the text is set in the heading (display) family. */
128
+ fonts: OgFonts;
129
+ /** JPEG quality, 1-100; 90 by default. */
130
+ quality?: number;
131
+ /** Names the cover in errors, e.g. the video's id. */
132
+ id?: string;
133
+ }
134
+
135
+ export interface PhotoCover {
136
+ /** A baseline JPEG of exactly `width` × `height`, without an ICC profile (sRGB). */
137
+ jpeg: Buffer;
138
+ width: number;
139
+ height: number;
140
+ bytes: number;
141
+ }
142
+
143
+ /** The text a cover draws, by layout. */
144
+ type CoverText =
145
+ | { layout: "title-bottom" | "title-center" | "title-top"; caption: string }
146
+ | { layout: "kicker-title"; caption: string; kicker: string }
147
+ | { layout: "pill"; caption: string };
148
+
149
+ type CoverRegion = "lower half" | "upper half" | "middle third";
150
+
151
+ /** The part of the band each text layout keeps to. */
152
+ const LAYOUT_REGIONS: Record<CoverText["layout"], CoverRegion> = {
153
+ "title-bottom": "lower half",
154
+ "title-center": "middle third",
155
+ "title-top": "upper half",
156
+ "kicker-title": "lower half",
157
+ pill: "lower half",
158
+ };
159
+
160
+ /** The rows of `region` in the band: `top` included, `bottom` excluded. */
161
+ function getRegionRows(band: CoverBand, region: CoverRegion): { top: number; bottom: number } {
162
+ const bandBottom = band.top + band.height;
163
+ if (region === "lower half") return { top: band.top + Math.floor(band.height / 2), bottom: bandBottom };
164
+ if (region === "upper half") return { top: band.top, bottom: band.top + Math.floor(band.height / 2) };
165
+ return { top: band.top + Math.floor(band.height / 3), bottom: band.top + Math.floor((2 * band.height) / 3) };
166
+ }
167
+
168
+ /** The text the options ask for, or an error when the layout and the texts do not go together. */
169
+ function resolveCoverText(options: { layout?: PhotoCoverLayout | undefined; caption?: string | undefined; kicker?: string | undefined }): OgResult<CoverText | null> {
170
+ const { caption, kicker } = options;
171
+ const layout = options.layout ?? (caption === undefined ? "photo" : "title-bottom");
172
+ if (kicker !== undefined && layout !== "kicker-title") return err(`the kicker is drawn only by the layout "kicker-title", not "${layout}"; leave it out`);
173
+ if (layout === "photo") return caption === undefined ? ok(null) : err('the layout "photo" draws no text; leave the caption out or pick a text layout');
174
+ if (caption === undefined) return err(`the layout "${layout}" needs a caption`);
175
+ if (layout === "kicker-title") return kicker === undefined ? err('the layout "kicker-title" needs a kicker') : ok({ layout, caption, kicker });
176
+ if (layout === "pill" && caption.length > MAX_COVER_PILL_LENGTH) {
177
+ return err(`the pill label ${JSON.stringify(caption)} is longer than ${String(MAX_COVER_PILL_LENGTH)} characters`);
178
+ }
179
+ return ok({ layout, caption });
180
+ }
181
+
182
+ function describeCover(id: string | undefined): string {
183
+ return id === undefined ? "Photo cover" : `Photo cover "${id}"`;
184
+ }
185
+
186
+ function readPhoto(photo: string | Buffer): OgResult<Buffer> {
187
+ if (typeof photo !== "string") return ok(photo);
188
+ try {
189
+ return ok(readFileSync(photo));
190
+ } catch (error) {
191
+ return err(`reading the photo ${photo}: ${(error as NodeJS.ErrnoException).code ?? String(error)}`);
192
+ }
193
+ }
194
+
195
+ /** Relative luminance (WCAG) of an opaque `#rrggbb`. */
196
+ function getLuminance(color: string): number {
197
+ const hex = toOpaqueHex(color);
198
+ const channel = (offset: number) => {
199
+ const value = Number.parseInt(hex.slice(offset, offset + 2), 16) / 255;
200
+ return value <= 0.039_28 ? value / 12.92 : ((value + 0.055) / 1.055) ** 2.4;
201
+ };
202
+ return 0.2126 * channel(1) + 0.7152 * channel(3) + 0.0722 * channel(5);
203
+ }
204
+
205
+ /** The text colour and the scrim (and shadow) colour: the brand's light and dark colour, swapped for a `dark` tone. */
206
+ function getCoverInk(colors: BrandColors, tone: PhotoCoverTone): { text: string; shade: string } {
207
+ const foreground = toOpaqueHex(colors.foreground);
208
+ const background = toOpaqueHex(colors.background);
209
+ const [light, dark] = getLuminance(foreground) >= getLuminance(background) ? [foreground, background] : [background, foreground];
210
+ return tone === "light" ? { text: light, shade: dark } : { text: dark, shade: light };
211
+ }
212
+
213
+ interface TextLayout {
214
+ size: readonly [number, number];
215
+ band: CoverBand;
216
+ text: CoverText;
217
+ fonts: OgFonts;
218
+ ink: { text: string; shade: string };
219
+ }
220
+
221
+ /** Where the text block sits: its foot above the band's lower edge, its head below the band's top, or centred in the middle third. */
222
+ function getBlockPlacement(layout: TextLayout, scale: number): Record<string, number | string> {
223
+ const [, height] = layout.size;
224
+ const { band } = layout;
225
+ const region = LAYOUT_REGIONS[layout.text.layout];
226
+ if (region === "lower half") return { bottom: height - (band.top + band.height) + Math.round(CAPTION_BOTTOM_PADDING * scale) };
227
+ if (region === "upper half") return { top: band.top + Math.round(CAPTION_TOP_PADDING * scale) };
228
+ const rows = getRegionRows(band, region);
229
+ return { top: rows.top, height: rows.bottom - rows.top, justifyContent: "center" };
230
+ }
231
+
232
+ /** The text alone on a transparent frame, laid out by its layout and centred across the band. */
233
+ function buildTextTree(layout: TextLayout): OgNode {
234
+ const [width, height] = layout.size;
235
+ const { band, fonts, ink, text } = layout;
236
+ const scale = band.width / BAND_BASE_WIDTH;
237
+ const side = Math.round(CAPTION_SIDE_PADDING * scale);
238
+ const font = { fontFamily: toFontFamilyCss(fonts.heading), fontWeight: pickWeight(fonts.heading.weights, 700) };
239
+ const shadow = `0px ${String(Math.round(4 * scale))}px ${String(Math.round(24 * scale))}px ${withAlpha(ink.shade, 0xb3)}`;
240
+ const line = (content: string, style: Record<string, number | string>) =>
241
+ h("div", { style: { display: "flex", justifyContent: "center", width: "100%", textAlign: "center", wordBreak: "break-word", color: ink.text, ...font, ...style } }, content);
242
+ const children =
243
+ text.layout === "pill"
244
+ ? [
245
+ h(
246
+ "div",
247
+ {
248
+ style: {
249
+ display: "flex",
250
+ maxWidth: "100%",
251
+ padding: `${String(Math.round(PILL_PADDING[0] * scale))}px ${String(Math.round(PILL_PADDING[1] * scale))}px`,
252
+ borderRadius: Math.round(PILL_SIZE * scale),
253
+ backgroundColor: withAlpha(ink.shade, PILL_ALPHA),
254
+ textAlign: "center",
255
+ wordBreak: "break-word",
256
+ color: ink.text,
257
+ fontSize: Math.round(PILL_SIZE * scale),
258
+ lineHeight: 1.15,
259
+ ...font,
260
+ },
261
+ },
262
+ text.caption,
263
+ ),
264
+ ]
265
+ : [
266
+ ...(text.layout === "kicker-title"
267
+ ? [line(text.kicker, { fontSize: Math.round(KICKER_SIZE * scale), lineHeight: 1.2, letterSpacing: Math.round(3 * scale), marginBottom: Math.round(KICKER_GAP * scale), textShadow: shadow })]
268
+ : []),
269
+ line(text.caption, { fontSize: Math.round(getCoverCaptionSize(text.caption) * scale), lineHeight: 1.08, textShadow: shadow }),
270
+ ];
271
+ return h(
272
+ "div",
273
+ { style: { display: "flex", position: "relative", width, height } },
274
+ h(
275
+ "div",
276
+ {
277
+ style: {
278
+ position: "absolute",
279
+ display: "flex",
280
+ flexDirection: "column",
281
+ alignItems: "center",
282
+ left: band.left + side,
283
+ width: band.width - 2 * side,
284
+ ...getBlockPlacement(layout, scale),
285
+ },
286
+ },
287
+ ...children,
288
+ ),
289
+ );
290
+ }
291
+
292
+ /** How errors name the cover's text, e.g. `the kicker "New" and the caption "Lisbon"`. */
293
+ function describeText(text: CoverText): { name: string; isPlural: boolean } {
294
+ if (text.layout === "pill") return { name: `the pill label ${JSON.stringify(text.caption)}`, isPlural: false };
295
+ if (text.layout === "kicker-title") return { name: `the kicker ${JSON.stringify(text.kicker)} and the caption ${JSON.stringify(text.caption)}`, isPlural: true };
296
+ return { name: `the caption ${JSON.stringify(text.caption)}`, isPlural: false };
297
+ }
298
+
299
+ function checkTextGlyphs(tree: OgNode, fonts: OgFonts, text: CoverText): OgResult<null> {
300
+ const missing = findMissingGlyphs(tree, fonts.satoriFonts);
301
+ if (!missing.ok) return err(`reading ${missing.error}`);
302
+ const sentences = missing.value
303
+ .filter((entry) => entry.characters.length > 0)
304
+ .map((entry) => {
305
+ const role = text.layout === "pill" ? "pill label" : text.layout === "kicker-title" && entry.text === text.kicker ? "kicker" : "caption";
306
+ return `the ${role} ${JSON.stringify(entry.text)} has characters none of the loaded fonts can draw at its weight: ${entry.characters.map(describeCharacter).join(", ")}`;
307
+ });
308
+ if (sentences.length === 0) return ok(null);
309
+ return err(`${sentences.join("; ")}. Use font files that cover them`);
310
+ }
311
+
312
+ /** The rows of `pixels` (RGBA, `width` wide) that hold anything drawn, or null when nothing is. */
313
+ function findDrawnBox(pixels: Uint8Array, width: number, height: number): { top: number; bottom: number; left: number; right: number } | null {
314
+ let top = height;
315
+ let bottom = -1;
316
+ let left = width;
317
+ let right = -1;
318
+ for (let y = 0; y < height; y += 1) {
319
+ for (let x = 0; x < width; x += 1) {
320
+ if ((pixels[(y * width + x) * 4 + 3] ?? 0) <= DRAWN_ALPHA) continue;
321
+ top = Math.min(top, y);
322
+ bottom = Math.max(bottom, y);
323
+ left = Math.min(left, x);
324
+ right = Math.max(right, x);
325
+ }
326
+ }
327
+ return bottom < 0 ? null : { top, bottom, left, right };
328
+ }
329
+
330
+ /** The text as SVG and the rows it draws, or an error when it does not fit its part of the band. */
331
+ async function layOutText(layout: TextLayout): Promise<OgResult<{ svg: string; top: number; bottom: number }>> {
332
+ const tree = buildTextTree(layout);
333
+ const glyphs = checkTextGlyphs(tree, layout.fonts, layout.text);
334
+ if (!glyphs.ok) return glyphs;
335
+ const [width, height] = layout.size;
336
+ let svg: string;
337
+ try {
338
+ // Satori is typed for React elements; it reads only `type` and `props`, which `OgNode` has.
339
+ svg = await satori(tree as unknown as Parameters<typeof satori>[0], { width, height, fonts: layout.fonts.satoriFonts });
340
+ } catch (error) {
341
+ return err(`laying out the text failed: ${error instanceof Error ? error.message : String(error)}`);
342
+ }
343
+ const pixels = new Resvg(svg, { fitTo: { mode: "original" }, font: { loadSystemFonts: false } }).render().pixels;
344
+ const box = findDrawnBox(pixels, width, height);
345
+ const { name, isPlural } = describeText(layout.text);
346
+ if (box === null) return err(`${name} ${isPlural ? "draw" : "draws"} nothing`);
347
+ const { band } = layout;
348
+ // The text keeps to the part of the band its layout names, so the photo's subject elsewhere stays clear.
349
+ const region = LAYOUT_REGIONS[layout.text.layout];
350
+ const rows = getRegionRows(band, region);
351
+ const isInside = box.top >= rows.top && box.bottom < rows.bottom && box.left >= band.left && box.right < band.left + band.width;
352
+ if (!isInside) {
353
+ return err(`${name} ${isPlural ? "do" : "does"} not fit the ${region} of the centre 4:5 band (${String(band.width)}×${String(band.height)}); shorten ${isPlural ? "them" : "it"}`);
354
+ }
355
+ return ok({ svg, top: box.top, bottom: box.bottom });
356
+ }
357
+
358
+ /** The scrim behind the text, as SVG: a gradient of the shade that follows the text's position; none for a pill (its box is its scrim). */
359
+ function buildScrim(input: { size: readonly [number, number]; band: CoverBand; layout: CoverText["layout"]; text: { top: number; bottom: number }; shade: string }): string {
360
+ const [width, height] = input.size;
361
+ const { band, shade } = input;
362
+ const region = LAYOUT_REGIONS[input.layout];
363
+ if (input.layout === "pill") return "";
364
+ const fade = Math.round(band.height / 5);
365
+ const alpha = (SCRIM_ALPHA / 255).toFixed(3);
366
+ const stop = (offset: number, opacity: string) => `<stop offset="${offset.toFixed(4)}" stop-color="${shade}" stop-opacity="${opacity}"/>`;
367
+ const gradient = (y1: number, y2: number, stops: string) =>
368
+ `<defs><linearGradient id="scrim" gradientUnits="userSpaceOnUse" x1="0" y1="${String(y1)}" x2="0" y2="${String(y2)}">${stops}</linearGradient></defs>`;
369
+ const rect = (top: number, bottom: number) => `<rect y="${String(top)}" width="${String(width)}" height="${String(bottom - top)}" fill="url(#scrim)"/>`;
370
+ if (region === "lower half") {
371
+ // Fades in over a fifth of the band above the text and holds from the band's lower edge down.
372
+ const start = Math.max(0, input.text.top - fade);
373
+ return gradient(start, band.top + band.height, stop(0, "0") + stop(1, alpha)) + rect(start, height);
374
+ }
375
+ if (region === "upper half") {
376
+ // Holds from the frame's top to the band's top and fades out over a fifth of the band below the text.
377
+ const end = Math.min(height, input.text.bottom + fade);
378
+ return gradient(band.top, end, stop(0, alpha) + stop(1, "0")) + rect(0, end);
379
+ }
380
+ // Fades in above the text, holds behind it and fades out below it.
381
+ const start = Math.max(0, input.text.top - fade);
382
+ const end = Math.min(height, input.text.bottom + fade);
383
+ const span = Math.max(1, end - start);
384
+ return gradient(start, end, stop(0, "0") + stop((input.text.top - start) / span, alpha) + stop((input.text.bottom - start) / span, alpha) + stop(1, "0")) + rect(start, end);
385
+ }
386
+
387
+ const toDataUri = (type: string, bytes: Buffer | string) => `data:${type};base64,${Buffer.from(bytes).toString("base64")}`;
388
+
389
+ /** Renders the cover: the photo cropped to `size` around the focus point, the layout's text (if any) over a soft scrim. */
390
+ export async function renderPhotoCover(input: PhotoCoverInput): Promise<OgResult<PhotoCover>> {
391
+ const name = describeCover(input.id);
392
+ const parsed = coverOptionsSchema.safeParse({
393
+ photo: input.photo,
394
+ size: input.size,
395
+ focus: input.focus,
396
+ layout: input.layout,
397
+ caption: input.caption,
398
+ kicker: input.kicker,
399
+ tone: input.tone,
400
+ quality: input.quality,
401
+ });
402
+ if (!parsed.success) {
403
+ const lines = parsed.error.issues.map((issue) => ` ${issue.path.length > 0 ? issue.path.join(".") : "input"}: ${issue.message}`);
404
+ return err(`${name}: the input is not valid:\n${lines.join("\n")}`);
405
+ }
406
+ const options = parsed.data;
407
+ const text = resolveCoverText(options);
408
+ if (!text.ok) return err(`${name}: ${text.error}.`);
409
+ const bytes = readPhoto(options.photo);
410
+ if (!bytes.ok) return err(`${name}: ${bytes.error}.`);
411
+ const info = readPhotoInfo(bytes.value);
412
+ if (!info.ok) return err(`${name}: the photo${typeof options.photo === "string" ? ` ${options.photo}` : ""} cannot be used: ${info.error}.`);
413
+
414
+ const size = options.size;
415
+ const [width, height] = size;
416
+ const band = getCoverBand(size);
417
+ const ink = getCoverInk(input.colors, options.tone ?? "light");
418
+ const drawn = text.value === null ? null : await layOutText({ size, band, text: text.value, fonts: input.fonts, ink });
419
+ if (drawn !== null && !drawn.ok) return err(`${name}: ${drawn.error}.`);
420
+
421
+ const crop = getCoverCrop(getOrientedSize(info.value), size, options.focus);
422
+ const matrix = getOrientationMatrix(info.value.orientation, info.value.width, info.value.height).join(" ");
423
+ const layers = [
424
+ `<rect width="${String(width)}" height="${String(height)}" fill="${ink.shade}"/>`,
425
+ `<image href="${toDataUri(`image/${info.value.format}`, bytes.value)}" width="${String(info.value.width)}" height="${String(info.value.height)}" preserveAspectRatio="none" ` +
426
+ `transform="translate(${String(crop.x)} ${String(crop.y)}) scale(${String(crop.scale)}) matrix(${matrix})"/>`,
427
+ ];
428
+ if (drawn !== null && text.value !== null) {
429
+ layers.push(
430
+ buildScrim({ size, band, layout: text.value.layout, text: drawn.value, shade: ink.shade }),
431
+ `<image href="${toDataUri("image/svg+xml", drawn.value.svg)}" width="${String(width)}" height="${String(height)}"/>`,
432
+ );
433
+ }
434
+ 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>`;
435
+ try {
436
+ const image = new Resvg(svg, { fitTo: { mode: "original" }, font: { loadSystemFonts: false } }).render();
437
+ const encoded = jpeg.encode({ data: Buffer.from(image.pixels), width: image.width, height: image.height }, options.quality).data;
438
+ return ok({ jpeg: encoded, width: image.width, height: image.height, bytes: encoded.length });
439
+ } catch (error) {
440
+ return err(`${name}: drawing the cover failed: ${error instanceof Error ? error.message : String(error)}.`);
441
+ }
442
+ }