1实现原理 · 为什么它能做到
唯一铁律：没有两张照片可以用同一种运动，且这种差异必须是由索引播种的确定性伪随机。
skills/photo-slideshow/SKILL.md
**No two slides may move the same way.** The instant-giveaway of an amateur slideshow is every photo doing the identical slow zoom-in. Vary direction, zoom in vs. out, and start scale per photo — but make it **deterministic** (seeded by index), so re-renders are identical and a frame-based renderer stays stable.
「变化」解决观感，「确定性」解决帧渲染器可能乱序渲染。
播种机制是 mulberry32 + 索引播种：同一张照片永远同一运动，相邻照片不同。
skills/photo-slideshow/references/ken-burns.md
`mulberry32` is a tiny, fast, well-distributed 32-bit PRNG. Seed it with the photo index so photo 0 always gets the same move, but adjacent photos differ.
reference 给出 8 种运动词表与「回滚重复」保险。
Ken Burns 只动 transform，且起始 scale ≥1.05，保证平移不露白边。
skills/photo-slideshow/SKILL.md
Always start scale ≥ `1.05` so a pan never exposes an empty edge.
KB 说明动 width/height 会触发布局、卡顿甚至闪烁。
混合比例照片用 blurred-pad（模糊底 + contain 前景原图），绝不拉伸。
skills/photo-slideshow/references/aspect-and-layout.md
Blurred-pad wins for mixed folders: it fills the frame, never crops the subject, and the soft blur reads as intentional depth rather than empty bars.
另有像素判据：长宽比差异 <15% 用 cover，否则 blurred-pad。
配乐先行：离线测一次 beat 烘进 props，绝不在渲染时逐帧做音频分析。
skills/photo-slideshow/references/timing-and-audio.md
The rule: **lock the music first, derive slide boundaries from it.** Detect beats once, offline, and bake them into props — audio analysis per frame is non-deterministic and slow.
换片取每 2 或 4 拍，并提供 BPM 网格退路。
文件夹 → manifest：自然排序、EXIF 拍摄时间、文件名提取 caption，全部派生自数据。
skills/photo-slideshow/references/templating-folder.md
// natural sort so photo2 < photo10 (default lexical sort breaks this)
并说明不用文件 mtime：拷贝后不可靠。
图片必须加载门控（staticFile + delayRender/continueRender），否则某帧会空白弹出。
skills/photo-slideshow/SKILL.md
- Photos loaded via `staticFile()`, gated with `delayRender`/`continueRender` so each image (and any caption font) is present before its frame renders — otherwise a slide pops in blank.
该要求在 reference 实现中并未照做（见 second_pass）。
验证环重点是「每张照片是否真的加载并正确重构图」，而不是画面美感。
skills/photo-slideshow/SKILL.md
A slideshow ingests a whole folder of user photos — the verify pass is mostly *did every photo actually load and reframe without distortion*.
多相册批量时先验一个代表文件夹。
转场只选一种（默认 0.4–0.6s 交叉溶解），且要重叠而不是硬切，除非切在拍点。
skills/photo-slideshow/SKILL.md
Pick **one** transition and keep it consistent — mixing wipes, spins and cubes screams "template."
reference 用 TransitionSeries + fade()，15 帧（0.5s@30fps）。
2核心能力
01播种式多样化 Ken Burns（运动词表 + mulberry32 + 主题锚点）
02主题感知锚点（按人脸/焦点设 transform-origin，避免把人摇出画面）
03三种适配策略与自动判据（blurred-pad / cover / contain）
04beat-synced 换片（librosa 离线测拍 + 每 2/4 拍换片 + 落点动态）
05无音频分析的 BPM 网格退路（60/bpm × beatsPerSlide × fps）
06数据驱动 Slideshow（照片+节拍+音乐全为 props，时序由数据推导）
07纯 FFmpeg 退路（zoompan 逐张 + xfade 串联 + 合成音轨）
08多比例安全区（16:9 / 9:16 / 1:1，一次构图多次渲染）
3外部依赖
| Kind | Dependency / Endpoint |
|---|---|
| package | remotion（frame/interpolate/Easing/Img/Audio/Sequence） |
| package | @remotion/transitions（TransitionSeries + fade） |
| package | sharp + exifr（读图像尺寸与 EXIF DateTimeOriginal） |
| package | librosa + soundfile（pip 安装；离线测 beat 与 onset） |
| cli | ffmpeg（blurred-pad、zoompan、xfade 与仓库共享 contact-sheet.sh） |
| network | iart.ai（reference 尾部推广链接，具 utm 参数；仅读者点击才请求） |
4管控建议与判定依据
建议配套管控措施
面向 Agent
分级或逐次授权，建议在沙箱运行
面向管理者
审批流程、可回滚、全程审计
判定依据（文件路径与关键语句摘要）
- scripts/: 执行本地脚本或命令: skill 目录内无自带脚本；SKILL.md/reference 指示 agent 执行 `node scripts/build-manifest.
- 网络端点: 声明外部网络访问: 执行期无业务 API 调用；照片与音乐来自用户本地文件。
- 本地工作目录: 文件读写与工件输出: 在用户工程内写 `photos.json`/`props.json`、`beats.json`、`out/<name>.mp4`、`out/*.gif
审计说明： 。触发项是分级范式「依赖第三方插件、镜像、远程包」，且是本批 9 个 skill 中依赖面最宽的一个：remotion 与 @remotion/transitions（npm）、sharp 与 exifr（npm，manifest 构建）、librosa 与 soundfile（pip），外加 ffmpeg/ffprobe；均需从公共仓库获取执行。同仓 `remotion-video` 已按同口径判橙，此处与之一致。**明确不成立的项**：无 process.env / API key / token / cookie / 钥匙串读取（token 扫描零实质命中）；不把照片与音乐上传任何外部服务（解析与渲染全在本地，素材不出网）；无 TLS 降级、无 `--no-verify`、无沙箱关闭、无反自动化绕过。触发条件：仅在构建 manifest、测拍与渲染视频时发生。
5第二遍独立确认
- [discrepancy] 图片加载门控口径是否实现一致 — SKILL.md 要求 staticFile() + delayRender/continueRender 门控，但 templating-folder.md 的 Slideshow 直接把 manifest 里的文件系统路径（join(dir, f)）交给 Img/KenBurnsImage，既未用 staticFile 也无 delayRender——照抄 reference 会拿不到 Remotion public/ 之外的资源，且仍可能出现空白帧。
- [discrepancy] 被引用的「打包脚本」是否真的存在 — reference 以 `scripts/build-manifest.mjs` 文件名给出源码、SKILL.md 也写 `node scripts/build-manifest.mjs ./photos`，但仓库根 scripts/ 只有 seek-shot.sh / contact-sheet.sh / probe-mp4.sh，没有 build-manifest.mjs；`python beats.py` 同理（脚本内联在文档里）。使用前必须自行落盘。
- [ok] 起始 scale 与运动确定性口径 — SKILL.md 的 start scale ≥ 1.05、seeded by index 与 ken-burns.md 的 `const base = 1.05;`、`mulberry32(index * 2654435761)` 完全一致。
- [ok] 适配策略与判据是否自洽 — aspect-and-layout.md 的三策略表与 fitStrategy 阈值（<0.15 → cover）一致；SKILL.md 的 never stretch 与 blurred-pad 默认选择一致。
- [ok] 换片节奏的量化声明 — timing-and-audio.md 的每张 3–6s、低于约 2.5s 会显仓促、每 2/4 拍换片，与 SKILL.md 的 photos hold ≥1 musical unit, not every beat 一致。
- [unlocatable] 隐私面：照片元数据是否被提示处理 — manifest 读取 EXIF DateTimeOriginal 并把日期上屏，但全文未讨论照片 GPS/相机信息的处理与输出视频的元数据策略；源码内定位不到任何隐私处理声明，记 unlocatable（能力缺口，不作为档位依据）。
6结论
适合： 把一整个相册文件夹变成成片的场景：婚礼/旅行/年度回顾/纪念视频，混合竖横照片、需要 Ken Burns 动感、音乐节拍换片与日期字幕，且要有可复用的模板化管线。
不适合： 只需单张图片做静态卡片；需要旁白叙事驱动时长（用 presentation-video）；不愿处理依赖安装与脚本落盘的环境。
Install Agent-Ready
① Verified Mirror 2026-09-28
Option A · Direct DownloadDownload photo-slideshow.tar.gz
sha256:
Option B · Copy Guide for Agent58ffd9961bdf764e…agent 读 JSON 指南后会自动从本站下载安装，无需更多说明。
② Upstream GitHub
GitHub Repo ↗
Pinned to commit 2bd0dd19c9.