museav-cli 2.8.0 → 2.10.1

package/src/commands/slideshow.ts

@@ -0,0 +1,210 @@
+/** museav slideshow —— 一组图 + 文案 + 配乐 → 竖版短视频。
+ *  纯本地渲染、不上传任何图片；stdout 只出产物路径，进度与统计打 stderr。
+ *
+ *  版面来自排版模板：不给 --layout 用内置的（**完全免登录、不碰网络**），
+ *  给了就去中台 slideshow_layouts 拉。免登录这条路必须一直留着——
+ *  秒级出片、零成本是这个命令的立身之本，不能因为接了模板库就没了。 */
+import { readFile, readdir, stat } from 'node:fs/promises'
+import { extname, isAbsolute, join, resolve } from 'node:path'
+import { makeSlideshow, fileSize, type Layout } from '../local-slideshow.js'
+import { PRESETS, PRESET_LIGHT, PRESET_DARK } from '../slideshow-presets.js'
+import { loadConfig } from '../config.js'
+import { StudioClient } from '../client.js'
+
+const IMG_EXT = new Set(['.png', '.jpg', '.jpeg', '.webp'])
+
+function fmtBytes(n: number): string {
+  return n >= 1048576 ? `${(n / 1048576).toFixed(2)}MB` : `${(n / 1024).toFixed(1)}KB`
+}
+
+/** 入参可以是若干张图，也可以是一个目录（目录内按文件名排序，所以图片建议带序号前缀） */
+async function collectImages(paths: string[]): Promise<string[]> {
+  const out: string[] = []
+  for (const p of paths) {
+    const abs = isAbsolute(p) ? p : resolve(p)
+    let st
+    try {
+      st = await stat(abs)
+    } catch {
+      throw new Error(`路径不存在: ${p}`)
+    }
+    if (st.isDirectory()) {
+      const names = (await readdir(abs))
+        .filter((n) => !n.startsWith('.') && IMG_EXT.has(extname(n).toLowerCase()))
+        .sort((a, b) => a.localeCompare(b, 'zh-Hans-CN', { numeric: true }))
+      if (!names.length) throw new Error(`目录里没有图片: ${p}`)
+      out.push(...names.map((n) => join(abs, n)))
+    } else {
+      out.push(abs)
+    }
+  }
+  return out
+}
+
+/** 按需建 client：只有真要拉中台模板时才需要凭证，没有 --layout 就一路不碰网络 */
+function studioClient(): StudioClient {
+  const cfg = loadConfig()
+  if (!cfg.token && !cfg.apiKey) {
+    throw new Error('拉中台排版模板需要登录：museav login（或配 apiKey）。\n不想登录就别传 --layout，内置版式免登录可用')
+  }
+  return new StudioClient({ baseUrl: cfg.baseUrl, apiKey: cfg.apiKey, token: cfg.token })
+}
+
+async function loadLayout(opts: SlideshowCmdOpts): Promise<{ layout: Layout; label: string; client?: StudioClient }> {
+  if (opts.layoutFile) {
+    const raw = await readFile(opts.layoutFile, 'utf8').catch(() => {
+      throw new Error(`排版模板文件读不到: ${opts.layoutFile}`)
+    })
+    try {
+      return { layout: JSON.parse(raw) as Layout, label: `文件 ${opts.layoutFile}` }
+    } catch (e) {
+      throw new Error(`排版模板不是合法 JSON: ${(e as Error).message}`)
+    }
+  }
+
+  if (opts.layout) {
+    // 内置的同名模板优先命中，省一次网络往返；不在内置里才去中台拉
+    const builtin = PRESETS[opts.layout]
+    if (builtin) return { layout: builtin, label: `内置 ${opts.layout}` }
+    const client = studioClient()
+    const row = await client.slideshowLayout(opts.layout)
+    if (!row?.layout) throw new Error(`模板 ${opts.layout} 没有 layout 内容`)
+    return { layout: row.layout as Layout, label: `中台 ${row.name}（${row.slug}）`, client }
+  }
+
+  const dark = (opts.theme || 'light') === 'dark'
+  return { layout: dark ? PRESET_DARK : PRESET_LIGHT, label: dark ? '内置深色' : '内置默认' }
+}
+
+export interface SlideshowCmdOpts {
+  out?: string
+  title?: string
+  subtitle?: string
+  footer?: string
+  caption?: string[]
+  captions?: string
+  music?: string
+  sec?: string
+  size?: string
+  theme?: string
+  layout?: string
+  layoutFile?: string
+}
+
+export async function slideshowCmd(paths: string[], opts: SlideshowCmdOpts): Promise<void> {
+  const images = await collectImages(paths)
+
+  let captions = opts.caption?.length ? [...opts.caption] : []
+  if (opts.captions) {
+    const text = await readFile(opts.captions, 'utf8').catch(() => {
+      throw new Error(`文案文件读不到: ${opts.captions}`)
+    })
+    captions = text.split('\n').map((l) => l.trim()).filter(Boolean)
+  }
+  if (captions.length && captions.length < images.length) {
+    process.stderr.write(`⚠️  文案 ${captions.length} 条少于图片 ${images.length} 张，后面几张不带文字\n`)
+  }
+
+  const { layout, label, client } = await loadLayout(opts)
+
+  const sec = opts.sec ? Number(opts.sec) : undefined
+  if (opts.sec && (!Number.isFinite(sec) || (sec as number) <= 0)) throw new Error('--sec 必须是正数')
+
+  let width: number | undefined
+  let height: number | undefined
+  if (opts.size) {
+    const m = /^(\d+)[x×](\d+)$/i.exec(opts.size.trim())
+    if (!m) throw new Error('--size 格式是 宽x高，如 1080x1920')
+    width = Number(m[1])
+    height = Number(m[2])
+  }
+
+  const out = opts.out ? resolve(opts.out) : resolve('slideshow.mp4')
+  const effSec = sec ?? layout.seconds ?? 2.5
+  const w = width ?? layout.canvas.w
+  const h = height ?? layout.canvas.h
+  process.stderr.write(
+    `${images.length} 张 × ${effSec}s ≈ ${(images.length * effSec).toFixed(0)}s · ${w}×${h} · 版式：${label}` +
+    (opts.title ? ` · 「${opts.title}」` : '') +
+    (opts.music ? ' · 带配乐' : ' · 无配乐') + '\n',
+  )
+
+  // 贴图只在模板真的引用了 sticker:// 时才去拉，且整轮只拉一次清单
+  let stickerUrls: Map<string, string> | null = null
+  const resolveSticker = async (id: string): Promise<string | null> => {
+    if (!stickerUrls) {
+      const c = client ?? studioClient()
+      const rows = await c.stickers().catch(() => [])
+      stickerUrls = new Map(rows.filter((r: any) => r?.id && r?.url).map((r: any) => [r.id, r.url]))
+    }
+    return stickerUrls.get(id) ?? null
+  }
+
+  const start = Date.now()
+  const r = await makeSlideshow({
+    images, out, layout, width, height, seconds: sec,
+    title: opts.title, subtitle: opts.subtitle, footer: opts.footer,
+    captions: captions.length ? captions : undefined,
+    music: opts.music ? resolve(opts.music) : undefined,
+    resolveSticker,
+    onWarn: (m) => process.stderr.write(`⚠️  ${m}\n`),
+  })
+  process.stderr.write(
+    `✅ 视频生成完成（${r.pages} 页，${r.seconds.toFixed(1)}s，` +
+    `${fmtBytes(await fileSize(out))}，用时 ${((Date.now() - start) / 1000).toFixed(1)}s）\n`,
+  )
+  console.log(out)
+}
+
+/** museav slideshow-layouts —— 列出可用排版模板（内置 + 中台） */
+export async function slideshowLayoutsCmd(): Promise<void> {
+  process.stderr.write('内置版式（免登录可用）:\n')
+  for (const slug of Object.keys(PRESETS)) {
+    process.stderr.write(`  ${slug.padEnd(28)} ${PRESETS[slug].canvas.w}×${PRESETS[slug].canvas.h}\n`)
+  }
+
+  let rows: any[] = []
+  try {
+    rows = await studioClient().slideshowLayouts()
+  } catch (e) {
+    // 没登录不算错：内置版式已经列出来了，这条命令仍然有用
+    process.stderr.write(`\n（中台模板未列出：${(e as Error).message.split('\n')[0]}）\n`)
+    console.log(Object.keys(PRESETS).join('\n'))
+    return
+  }
+
+  if (rows.length) {
+    process.stderr.write(`\n中台模板（${rows.length} 个）:\n`)
+    for (const r of rows) {
+      const src = r.source === 'platform' ? '[平台]' : r.source === 'mine' ? '[租户]' : '[私有]'
+      const size = r.layout?.canvas ? `${r.layout.canvas.w}×${r.layout.canvas.h}` : ''
+      process.stderr.write(`  ${String(r.slug).padEnd(28)} ${String(r.name).padEnd(20)} ${size.padEnd(10)} ${src}\n`)
+    }
+  } else {
+    process.stderr.write('\n中台还没有模板。用 museav slideshow-layouts create 建一个。\n')
+  }
+  process.stderr.write('\n出片: museav slideshow ./图片目录 --layout <slug>\n')
+  console.log([...Object.keys(PRESETS), ...rows.map((r) => r.slug)].join('\n'))
+}
+
+/** museav slideshow-layouts create —— 从 JSON 文件建一个排版模板 */
+export async function createSlideshowLayoutCmd(file: string, opts: { name: string; slug: string; description?: string; category?: string }): Promise<void> {
+  const raw = await readFile(file, 'utf8').catch(() => {
+    throw new Error(`读不到文件: ${file}`)
+  })
+  let layout: unknown
+  try {
+    layout = JSON.parse(raw)
+  } catch (e) {
+    throw new Error(`不是合法 JSON: ${(e as Error).message}`)
+  }
+
+  const row = await studioClient().createSlideshowLayout({
+    name: opts.name, slug: opts.slug, layout,
+    description: opts.description, category: opts.category,
+  })
+  process.stderr.write(`✅ 排版模板已建：${row.name}（${row.slug}）\n`)
+  process.stderr.write(`归属：${row.visibility === 'private' ? '仅本人可见' : row.tenant_id ? '本租户共享' : '平台共享'}\n`)
+  process.stderr.write(`\n出片: museav slideshow ./图片目录 --layout ${row.slug}\n`)
+  console.log(row.id)
+}

package/src/index.ts

@@ -16,6 +16,7 @@ import { printWelcome } from './commands/welcome.js'
 import { gen } from './commands/gen.js'
 import { reverse } from './commands/reverse.js'
 import { compressCmd, removeBgCmd, upscaleCmd, removeWatermarkCmd } from './commands/img-tools.js'
+import { slideshowCmd, slideshowLayoutsCmd, createSlideshowLayoutCmd } from './commands/slideshow.js'
 import { projects, createProject, listAssets, addAsset, removeAsset, resolveWorkspace } from './commands/projects.js'
 import { imageToTemplate } from './commands/image-to-template.js'
 import { upload } from './commands/upload.js'
@@ -26,6 +27,7 @@ import { videoTemplates, createVideoTemplate } from './commands/video-templates.
 import { balance } from './commands/balance.js'
 import { jobs } from './commands/jobs.js'
 import { whoami } from './commands/whoami.js'
+import { feedback } from './commands/feedback.js'
 import { products } from './commands/products.js'
 import { assets } from './commands/assets.js'
 import { stickers, createSticker } from './commands/stickers.js'
@@ -210,6 +212,37 @@ program
   .option('--overwrite', '允许覆盖已存在的输出文件')
   .action(asyncRun((input: string, opts: any) => removeWatermarkCmd(input, opts)))
 
+program
+  .command('slideshow <图片或目录...>')
+  .description('本地图集转竖版短视频（sharp + ffmpeg，免登录）：默认 1080×1920 / 30fps / H.264，可加标题、逐张文案与配乐。需要本机有 ffmpeg')
+  .option('--out <path>', '输出 mp4（默认当前目录 slideshow.mp4）')
+  .option('--title <text>', '顶部主标题（大字）')
+  .option('--subtitle <text>', '顶部副标题（小字）')
+  .option('--caption <text>', '单页文案，可重复传，按顺序对应每张图', (v: string, acc: string[]) => [...acc, v], [] as string[])
+  .option('--captions <file>', '文案文件（每行一条，按顺序对应每张图），与 --caption 二选一')
+  .option('--footer <text>', '底部引导语')
+  .option('--music <file>', '配乐音频。自动裁到视频长度并加首尾淡入淡出（不会中途硬切断）')
+  .option('--sec <n>', '每张停留秒数，默认取模板的（内置模板 2.5）')
+  .option('--size <WxH>', '画面尺寸，默认取模板画布（内置模板 1080x1920）；与模板不同则整体等比缩放')
+  .option('--theme <name>', 'light（默认）/ dark。只影响内置版式，给了 --layout 就以模板为准')
+  .option('--layout <slug>', '排版模板 slug：内置的直接用，其余去中台拉（需登录）。清单见 museav slideshow-layouts')
+  .option('--layout-file <path>', '直接用本地 JSON 排版模板（调模板时用，免登录）')
+  .action(asyncRun((paths: string[], opts: any) => slideshowCmd(paths, opts)))
+
+const slideshowLayoutsCommand = program
+  .command('slideshow-layouts')
+  .description('查排版模板：内置版式（免登录）+ 中台模板（平台共享 / 本租户 / 本人私有）。配合 slideshow --layout 使用')
+  .action(asyncRun(() => slideshowLayoutsCmd()))
+
+slideshowLayoutsCommand
+  .command('create <layout.json>')
+  .description('从 JSON 文件新建排版模板——归属由身份自动决定：租户 Key 建的归本租户，个人账号建的仅本人可见。结构校验在服务端做')
+  .requiredOption('--name <名称>', '模板中文名')
+  .requiredOption('--slug <slug>', '对外调用标识（小写字母/数字/连字符，全局唯一）')
+  .option('--description <text>', '模板说明')
+  .option('--category <name>', '分类，默认「其他」')
+  .action(asyncRun((file: string, opts: any) => createSlideshowLayoutCmd(file, opts)))
+
 // 工作区（项目）与项目素材库：平台 → 账户 → 工作区三层归属，素材挂工作区
 const projectsCmd = program
   .command('projects')
@@ -398,6 +431,13 @@ program
   .description('查当前登录账户 + 租户归属（仅个人 login 可用，apiKey 调用会报错）')
   .action(withClient((client: StudioClient) => whoami(client)))
 
+program
+  .command('feedback [content]')
+  .description('提 bug / 需求（不带内容则交互式输入）；--list 看我的反馈记录。个人账户可提，租户 apiKey 会被服务端拒')
+  .option('--type <type>', '反馈类型：bug / 需求（默认 bug）')
+  .option('--list', '列出我的反馈记录')
+  .action(withLazyClient((getClient: () => StudioClient, content: string | undefined, opts: any) => feedback(getClient, content || '', opts)))
+
 program
   .command('config')
   .description('配置中台地址和 apiKey（存到 ~/.museav.json）')

package/src/local-slideshow.ts

@@ -0,0 +1,299 @@
+/**
+ * 本地图集转竖版短视频 —— slideshow 的核心实现。
+ * 一组图 + 每张的文字说明 + 配乐 → mp4，适合发朋友圈 / 视频号 / 小红书。
+ *
+ * 版面由**排版模板（图层 DSL）**描述，不再写死在代码里。内置一套默认模板（免登录可用），
+ * `--layout <slug>` 可以拉中台 `slideshow_layouts` 里的模板 —— 模板结构的真源在中台的
+ * `shared/slideshow-layout.js`。
+ *
+ * ## 这里刻意不校验模板
+ *
+ * 校验只在中台写入时做。本模块是消费方：遇到不认识的层类型**跳过该层并提示升级 CLI**，
+ * 而不是报错中断。老版本 CLI 碰上新层类型应该少画一个图层，不是彻底出不了片。
+ * 两侧都校验的话，老 CLI 会把新写的合法模板判为非法，那才是真坏掉。
+ *
+ * 渲染走 sharp 渲染 SVG（中文靠系统字体），合成走 ffmpeg 的 concat demuxer ——
+ * 不引入 canvas 那种要编译的重依赖。
+ *
+ * 三个实测踩出来的点，写在这里免得下次重踩：
+ *
+ * 1. 图片必须显式放大。小图（如 240×240 的表情）直接贴到 1080 宽的画布上只占两成宽，
+ *    画面空得离谱。要按目标尺寸等比 resize，而不是「不超过某上限」那种只缩不放的逻辑。
+ *    贴纸类素材还要先裁掉四周透明留白（slot 层的 trim），否则放大的是留白、主体照样小。
+ * 2. 配乐不能直接 -shortest。配乐通常比视频长几倍，硬切会在中途断掉。
+ *    要 atrim 裁到视频时长 + 首尾 afade。
+ * 3. concat demuxer 的最后一张要再列一次，否则它的 duration 被忽略，末页一闪而过。
+ */
+import { mkdtemp, writeFile, rm, stat } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { spawn } from 'node:child_process'
+
+/** 图层类型。与中台 shared/slideshow-layout.js 的 LAYER_TYPES 对应。 */
+export type LayerType = 'rect' | 'ellipse' | 'text' | 'slot' | 'image'
+
+export interface Layer {
+  type: LayerType | string
+  fill?: string
+  opacity?: number
+  // rect / slot / image
+  box?: [number, number, number, number]
+  radius?: number
+  fit?: 'contain' | 'cover'
+  trim?: boolean
+  src?: string
+  // ellipse
+  cx?: number; cy?: number; rx?: number; ry?: number
+  // text
+  bind?: string | null
+  text?: string
+  x?: number; y?: number
+  size?: number
+  weight?: number
+  align?: 'left' | 'center' | 'right'
+  maxWidth?: number
+  minSize?: number
+}
+
+export interface Layout {
+  version?: number
+  canvas: { w: number; h: number; bg?: string }
+  seconds?: number
+  layers: Layer[]
+}
+
+/** 渲染时填进模板的内容。caption / image 逐页变化，其余全局固定。 */
+export interface PageContent {
+  title?: string
+  subtitle?: string
+  caption?: string
+  footer?: string
+  image: string
+}
+
+export interface SlideshowOpts {
+  images: string[]
+  out: string
+  layout: Layout
+  captions?: string[]
+  title?: string
+  subtitle?: string
+  footer?: string
+  music?: string
+  seconds?: number
+  /** 目标尺寸。与模板 canvas 不同时整个版面按比例缩放 */
+  width?: number
+  height?: number
+  /** 解析 sticker://<id> → 图片 URL/本地路径。不传则跳过这类图层 */
+  resolveSticker?: (id: string) => Promise<string | null>
+  onWarn?: (msg: string) => void
+}
+
+const FONT = 'Hiragino Sans GB, PingFang SC, Microsoft YaHei, Noto Sans CJK SC, sans-serif'
+
+function esc(s: string): string {
+  return s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;').replace(/'/g, '&apos;')
+}
+
+/** 中文按全宽算、ASCII 按半宽算，估出一行文字的像素宽，用来收敛字号 */
+function textWidth(s: string, size: number): number {
+  let w = 0
+  for (const ch of s) w += /[一-鿿　-〿＀-￯]/.test(ch) ? size : size * 0.55
+  return w
+}
+
+function fitSize(text: string, max: number, start: number, min: number): number {
+  let size = start
+  while (size > min && textWidth(text, size) > max) size -= 2
+  return size
+}
+
+/** 取 text 层这一页该显示的文字：有 bind 就取绑定值，否则用固定 text */
+function resolveText(layer: Layer, content: PageContent): string {
+  if (!layer.bind) return layer.text ?? ''
+  const v = (content as unknown as Record<string, unknown>)[layer.bind]
+  return typeof v === 'string' ? v : ''
+}
+
+/**
+ * 把一页渲染成 SVG（不含图片 —— 图片走 sharp composite，SVG 里嵌 base64 会让文件爆大）。
+ * 返回 SVG 字符串 + 需要 composite 的图片层。
+ */
+function buildPage(layout: Layout, content: PageContent, scale: number, onWarn?: (m: string) => void) {
+  const W = Math.round(layout.canvas.w * scale)
+  const H = Math.round(layout.canvas.h * scale)
+  const s = (n: number) => n * scale
+  const parts: string[] = [`<rect width="${W}" height="${H}" fill="${layout.canvas.bg ?? '#ffffff'}"/>`]
+  const images: { layer: Layer; box: [number, number, number, number] }[] = []
+  const unknown = new Set<string>()
+
+  for (const layer of layout.layers) {
+    const op = layer.opacity !== undefined ? ` opacity="${layer.opacity}"` : ''
+
+    if (layer.type === 'rect' && layer.box) {
+      const [x, y, w, h] = layer.box
+      const r = layer.radius ? ` rx="${s(layer.radius)}"` : ''
+      parts.push(`<rect x="${s(x)}" y="${s(y)}" width="${s(w)}" height="${s(h)}"${r} fill="${layer.fill ?? '#000000'}"${op}/>`)
+    } else if (layer.type === 'ellipse') {
+      parts.push(`<ellipse cx="${s(layer.cx ?? 0)}" cy="${s(layer.cy ?? 0)}" rx="${s(layer.rx ?? 0)}" ry="${s(layer.ry ?? 0)}" fill="${layer.fill ?? '#000000'}"${op}/>`)
+    } else if (layer.type === 'text') {
+      const txt = resolveText(layer, content)
+      // 绑定值为空就整层不画（比如没给 --subtitle），而不是画一行空白占位
+      if (!txt) continue
+      const base = s(layer.size ?? 40)
+      const min = s(layer.minSize ?? Math.max(12, (layer.size ?? 40) * 0.5))
+      const max = (layer.maxWidth ?? 0.86) * W
+      const size = fitSize(txt, max, base, min)
+      const anchor = layer.align === 'left' ? 'start' : layer.align === 'right' ? 'end' : 'middle'
+      const weight = layer.weight ? ` font-weight="${layer.weight}"` : ''
+      parts.push(
+        `<text x="${s(layer.x ?? 0)}" y="${s(layer.y ?? 0)}" font-family="${FONT}" font-size="${size}"${weight} fill="${layer.fill ?? '#000000'}" text-anchor="${anchor}"${op}>${esc(txt)}</text>`,
+      )
+    } else if ((layer.type === 'slot' || layer.type === 'image') && layer.box) {
+      const [x, y, w, h] = layer.box
+      images.push({ layer, box: [s(x), s(y), s(w), s(h)] })
+    } else {
+      // 不认识的层类型：跳过，不中断。老 CLI 碰上新层类型该少画一层，不是出不了片。
+      unknown.add(String(layer.type))
+    }
+  }
+
+  if (unknown.size && onWarn) {
+    onWarn(`模板里有本版本不认识的图层类型（${[...unknown].join(', ')}），已跳过。升级试试：npm i -g museav-cli`)
+  }
+  return { svg: `<svg width="${W}" height="${H}" xmlns="http://www.w3.org/2000/svg">${parts.join('')}</svg>`, W, H, images }
+}
+
+function run(cmd: string, args: string[]): Promise<{ code: number; err: string }> {
+  return new Promise((resolve) => {
+    const p = spawn(cmd, args)
+    let err = ''
+    p.stderr.on('data', (d) => { err += d.toString() })
+    p.on('error', (e) => resolve({ code: 1, err: String(e) }))
+    p.on('close', (code) => resolve({ code: code ?? 1, err }))
+  })
+}
+
+async function hasFfmpeg(): Promise<boolean> {
+  const { code } = await run('ffmpeg', ['-version'])
+  return code === 0
+}
+
+export async function makeSlideshow(opts: SlideshowOpts): Promise<{ out: string; pages: number; seconds: number }> {
+  if (!opts.images.length) throw new Error('没有输入图片')
+  if (!(await hasFfmpeg())) throw new Error('需要 ffmpeg（brew install ffmpeg）')
+
+  const sharpMod = await import('sharp').catch(() => null)
+  if (!sharpMod) throw new Error('sharp 不可用。重装 CLI 即可补上：npm install -g museav-cli')
+  const sharp = (sharpMod as any).default ?? sharpMod
+
+  const layout = opts.layout
+  // 目标尺寸与模板 canvas 不同就整体等比缩放。取较小的比例，保证画面不被裁掉。
+  const targetW = opts.width ?? layout.canvas.w
+  const targetH = opts.height ?? layout.canvas.h
+  const scale = Math.min(targetW / layout.canvas.w, targetH / layout.canvas.h)
+  const sec = opts.seconds ?? layout.seconds ?? 2.5
+  const work = await mkdtemp(join(tmpdir(), 'museav-slideshow-'))
+
+  // sticker:// 引用逐个解析一次就够，同一个贴图在每页都用得上
+  const stickerCache = new Map<string, string | null>()
+  let warned = false
+  const warn = (m: string) => { if (!warned) { warned = true; opts.onWarn?.(m) } }
+
+  try {
+    const pages: string[] = []
+    for (let i = 0; i < opts.images.length; i++) {
+      const content: PageContent = {
+        title: opts.title,
+        subtitle: opts.subtitle,
+        caption: opts.captions?.[i],
+        footer: opts.footer,
+        image: opts.images[i],
+      }
+      const { svg, images } = buildPage(layout, content, scale, warn)
+      const composites: { input: Buffer; top: number; left: number }[] = []
+
+      for (const { layer, box } of images) {
+        const [bx, by, bw, bh] = box
+        let src: string | null = null
+
+        if (layer.type === 'slot') {
+          src = content.image
+        } else if (layer.src?.startsWith('sticker://')) {
+          const id = layer.src.slice('sticker://'.length)
+          if (!stickerCache.has(id)) stickerCache.set(id, opts.resolveSticker ? await opts.resolveSticker(id) : null)
+          src = stickerCache.get(id) ?? null
+          if (!src) { warn(`模板引用的贴图 ${id} 取不到，已跳过该图层`); continue }
+        } else {
+          src = layer.src ?? null
+        }
+        if (!src) continue
+
+        let pipe = sharp(src.startsWith('http') ? Buffer.from(await (await fetch(src)).arrayBuffer()) : src)
+        // 贴纸类素材四周常有大片透明留白，直接放大等于把留白也放大、主体显小。
+        // 只对带 alpha 的图做 —— 对不透明照片 trim 会去裁纯色边框，那不是这里想要的。
+        if (layer.trim && (await pipe.metadata()).hasAlpha) {
+          const buf = await pipe.toBuffer()
+          pipe = sharp(buf).trim({ background: { r: 0, g: 0, b: 0, alpha: 0 }, threshold: 8 })
+        }
+        // 显式放大：fit inside + withoutEnlargement:false，小图必须撑满槽位。
+        //
+        // 注意 box 的语义是**矩形框 + contain**（同 CSS object-fit），不是「正方形边长」。
+        // 2.9.0 那版把主图区当成正方形（resize(ART, ART)），对高瘦的图会受高度限制而偏小：
+        // 219×229 的图在 518×701 的框里，旧算法出 495×518，新算法出 518×542（大 4.6%）。
+        // 换成框语义是刻意的——框多大图就能占多大，这才符合直觉，也是主图偏小那个老问题的根治。
+        const art = await pipe
+          .resize(Math.round(bw), Math.round(bh), {
+            fit: layer.fit === 'cover' ? 'cover' : 'inside',
+            withoutEnlargement: false,
+            background: { r: 0, g: 0, b: 0, alpha: 0 },
+          })
+          .png()
+          .toBuffer({ resolveWithObject: true })
+        // 在槽位内居中
+        composites.push({
+          input: art.data,
+          top: Math.max(0, Math.round(by + (bh - art.info.height) / 2)),
+          left: Math.max(0, Math.round(bx + (bw - art.info.width) / 2)),
+        })
+      }
+
+      const page = join(work, `p${String(i).padStart(3, '0')}.png`)
+      await sharp(Buffer.from(svg)).composite(composites).png().toFile(page)
+      pages.push(page)
+    }
+
+    // concat demuxer：末页要重复列一次，否则它的 duration 会被忽略
+    const listLines: string[] = []
+    for (const p of pages) listLines.push(`file '${p}'`, `duration ${sec}`)
+    listLines.push(`file '${pages[pages.length - 1]}'`)
+    const listFile = join(work, 'list.txt')
+    await writeFile(listFile, listLines.join('\n') + '\n', 'utf8')
+
+    const total = pages.length * sec
+    const args = ['-y', '-v', 'error', '-f', 'concat', '-safe', '0', '-i', listFile]
+    if (opts.music) args.push('-i', opts.music)
+    args.push('-c:v', 'libx264', '-r', '30', '-pix_fmt', 'yuv420p', '-preset', 'medium', '-crf', '22')
+    if (opts.music) {
+      const fadeOut = Math.max(0, total - 1.5)
+      args.push('-af', `atrim=0:${total},afade=t=in:st=0:d=1,afade=t=out:st=${fadeOut}:d=1.5`,
+        '-c:a', 'aac', '-b:a', '128k', '-shortest')
+    }
+    args.push(opts.out)
+
+    const { code, err } = await run('ffmpeg', args)
+    if (code !== 0) throw new Error(`ffmpeg 失败：${err.trim().slice(0, 400)}`)
+    return { out: opts.out, pages: pages.length, seconds: total }
+  } finally {
+    await rm(work, { recursive: true, force: true }).catch(() => {})
+  }
+}
+
+export async function fileSize(p: string): Promise<number> {
+  try {
+    return (await stat(p)).size
+  } catch {
+    return 0
+  }
+}

package/src/slideshow-presets.ts

@@ -0,0 +1,42 @@
+/**
+ * 内置排版模板。不联网、不登录也能出片 —— 这是 slideshow 最重要的属性，
+ * 接中台模板库之后也必须保住。
+ *
+ * `sticker-pink-mint` 与中台 slideshow_layouts 里平台预置的同名模板**是同一份 DSL**
+ * （见 supabase/migrations/20260828120000_slideshow_layouts.sql）。存两份是刻意的：
+ * 中台那份是给人看、给人改的起点，这份是断网兜底。两份必须一致，改动时同步。
+ *
+ * 想要别的版面不要在这里加 —— 去中台建模板（museav slideshow-layouts create），
+ * 那才是排版体系的落点。这里只留「默认」和「深色默认」两套兜底。
+ */
+import type { Layout } from './local-slideshow.js'
+
+export const PRESET_LIGHT: Layout = {
+  version: 1,
+  canvas: { w: 1080, h: 1920, bg: '#ffffff' },
+  seconds: 2.5,
+  layers: [
+    { type: 'ellipse', cx: 190, cy: -131, rx: 510, ry: 430, fill: '#ffd6e2' },
+    { type: 'ellipse', cx: 1110, cy: 1901, rx: 291, ry: 280, fill: '#baebe2' },
+    { type: 'text', bind: 'title', x: 540, y: 394, size: 84, weight: 600, fill: '#2b2d31', align: 'center', maxWidth: 0.86, minSize: 36 },
+    { type: 'text', bind: 'subtitle', x: 540, y: 495, size: 44, fill: '#8c929b', align: 'center' },
+    { type: 'slot', bind: 'image', box: [281, 660, 518, 701], fit: 'contain', trim: true },
+    { type: 'text', bind: 'caption', x: 540, y: 1578, size: 72, weight: 600, fill: '#2b2d31', align: 'center', maxWidth: 0.86, minSize: 28 },
+    { type: 'text', bind: 'footer', x: 540, y: 1776, size: 33, fill: '#8c929b', align: 'center' },
+  ],
+}
+
+export const PRESET_DARK: Layout = {
+  ...PRESET_LIGHT,
+  canvas: { w: 1080, h: 1920, bg: '#16181c' },
+  layers: PRESET_LIGHT.layers.map((l) => {
+    if (l.type === 'ellipse') return { ...l, fill: l.fill === '#ffd6e2' ? '#3a2b33' : '#22383a' }
+    if (l.type === 'text') return { ...l, fill: l.fill === '#2b2d31' ? '#e9ebef' : '#8b929c' }
+    return l
+  }),
+}
+
+export const PRESETS: Record<string, Layout> = {
+  'sticker-pink-mint': PRESET_LIGHT,
+  'sticker-pink-mint-dark': PRESET_DARK,
+}