scroll-world

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

scroll-world

滚动驱动世界着陆页

Produces a landing page where scroll drives a camera: it dives from outside a scene into its interior, then flies out and into the next scene, continuously, with no visible cuts. The visuals are AI-generated (Higgsfield); the page just scrubs pre-rendered video by scroll position. This is the same technique behind Apple's scroll-through product pages — the camera genuinely moves, scroll only drives time.

What you generate: N scene stills → N "dive-in" camera clips → N-1 "connector" clips that join consecutive scenes seamlessly → a portable scrub engine that plays the whole chain as one flight.

The one rule that makes or breaks it: seams must be frame-identical. Read The seamless chain before generating any connector. Getting this wrong is the single most common failure and produces a visible "pop" between scenes.

Do not assume a frontend framework. The scrub engine in

references/scrub-engine.js

is self-contained vanilla JS (it builds its own DOM + injects its own CSS into a container you give it), so it drops into plain HTML, Next.js, Vue, a Python-served page, anything. The value of this skill is the Higgsfield pipeline, the prompts, and the seam method — not the framework.

生成一个由滚动控制摄像机的着陆页：摄像机会从场景外部切入内部，然后飞出并进入下一个场景，全程连续无可见剪辑。视觉内容由AI生成（Higgsfield）；页面仅通过滚动位置控制预渲染视频的播放进度。这与Apple产品页的滚动浏览技术原理相同——摄像机真实移动，滚动仅控制时间轴。

生成内容包括：N张场景静帧 → N段“切入”摄像片段 → N-1段“衔接”片段（无缝连接连续场景） → 一个可移植的驱动引擎，将所有片段串联成完整的飞行体验。

决定成败的核心规则：场景衔接处必须帧完全一致。在生成任何衔接片段前，请先阅读无缝衔接链部分。这是最常见的失败原因，会导致场景间出现明显的“跳帧”。

不要预设前端框架。

references/scrub-engine.js

中的驱动引擎是独立的原生JS（它会构建自己的DOM并将CSS注入指定容器），因此可以直接嵌入纯HTML、Next.js、Vue、Python服务的页面等任何环境。该方案的价值在于Higgsfield工作流、提示词设计和无缝衔接方法——而非特定框架。

Step 0 — Bootstrap

步骤0 — 初始化

Higgsfield CLI. If
```
higgsfield
```
is not on
```
$PATH
```
, install per the
```
higgsfield-generate
```
skill. If
```
higgsfield workspace list
```
fails auth, ask the user to run
```
higgsfield auth login
```
(interactive OAuth — you cannot run it) and, if needed,
```
higgsfield workspace set <id>
```
. Confirm there are enough credits: a full run is roughly
```
N
```
image gens +
```
(2N-1)
```
video gens.
ffmpeg / ffprobe on
```
$PATH
```
(frame extraction + encoding).
An image tool for background knockout if you want floating scenes: PIL (
```
python3 -c "import PIL"
```
), or
```
cwebp
```
/
```
sips
```
. Optional — see Step 3.
Caveats: macOS ships bash 3.2 (no
```
declare -A
```
); don't use associative arrays in scripts. Higgsfield generations take 3–8 min each — always run them detached (background) and poll, never a foreground blocking call. Reference-by-job-UUID is rejected by media flags — pass local file paths to
```
--image/--start-image/--end-image
```
. Video models differ in accepted params (e.g. Kling has no
```
--resolution
```
) and in whether they support start/end-image conditioning at all — before batching, confirm the chosen model's schema with
```
higgsfield model get <job_type>
```
and see the Step 4 model table.

Higgsfield CLI。如果
```
higgsfield
```
不在
```
$PATH
```
中，请按照
```
higgsfield-generate
```
流程安装。如果
```
higgsfield workspace list
```
认证失败，请让用户运行
```
higgsfield auth login
```
（交互式OAuth——您无法代运行），必要时运行
```
higgsfield workspace set <id>
```
。确认有足够的 credits：完整流程大约需要
```
N
```
次图像生成 +
```
(2N-1)
```
次视频生成。
ffmpeg / ffprobe需在
```
$PATH
```
中（用于帧提取和编码）。
图像工具（可选，用于移除背景实现悬浮场景）：PIL（运行
```
python3 -c "import PIL"
```
验证），或
```
cwebp
```
/
```
sips
```
。详见步骤3。
注意事项：macOS自带bash 3.2（不支持
```
declare -A
```
）；脚本中不要使用关联数组。Higgsfield生成每次需要3–8分钟——始终后台运行并轮询状态，不要阻塞前台进程。通过作业UUID引用会被媒体标志拒绝——请向
```
--image/--start-image/--end-image
```
传递本地文件路径。不同视频模型接受的参数不同（例如Kling不支持
```
--resolution
```
），且并非所有模型都支持起始/结束帧条件控制——批量生成前，请通过
```
higgsfield model get <job_type>
```
确认所选模型的参数规范，并参考步骤4的模型表。

Step 1 — Interview the user

步骤1 — 用户调研

The subject is the user's to state — ask it as an open question in plain prose, never a fabricated multiple-choice. A made-up list of industries biases them and reads as you deciding their business for them; let them answer in their own words (their real business, a client's, or any idea). Reserve structured multiple-choice (

AskUserQuestion

in Claude Code; a plain either/or question elsewhere) for the genuinely enumerable, lower-stakes choices below — art direction and brand-kit approach — and even there, signal they can go their own way ("Other"). Ask only what you can't sensibly default. Cover:

Subject (ask openly, not multiple-choice) — "What should this world be about? Your business, a client's, or any idea — a word or a sentence is fine." Capture the industry/product + a one-line pitch (e.g. "a bubble tea company, from leaf to last sip"), and a brand name if they have one; otherwise you'll propose one below.
Brand kit — offer three paths, pick one:
- Import from a URL:
```
higgsfield marketing-studio brand-kits fetch --url <site> --wait
```
  (pulls name, colours, tone). Then read it back with
```
brand-kits list --json
```
  .
- The user hands you palette + name + tone directly.
- You propose a palette + name and let them approve. Capture 4–6 named hex values, a display name, and a tone word or two.
Art direction — default is "soft matte low-poly clay diorama, isometric, tilt-shift miniature, warm light." Offer alternatives (flat papercraft, glossy toy, claymation, neon night). Whatever is chosen becomes the shared style preamble reused verbatim in every scene prompt (this is what makes the world cohesive).
The journey (sections) — the ordered scenes the camera flies through. Propose a set derived from the subject's own value chain and let the user edit. 5–7 works well. Boba example: farms → pearl kitchen → flagship shop → delivery → community plaza → the hero product. Each section needs: a short subject description (what's IN the diorama), an eyebrow, a headline, one line of body, and 0–3 tag pills. The last section is usually the hero product + the CTA.
Mobile version (beta) — ALWAYS ask this; never silently generate both. Ask as a two-option choice (
```
AskUserQuestion
```
in Claude Code; a plain question elsewhere): "Want a mobile-optimized version too? Mobile support is in beta — the scroll-scrub mechanic is desktop-native; on phones you get lighter encodes and engine hardening, but portrait crops the 16:9 frame and low-end devices may still stutter." Options: "Desktop only" / "Desktop + mobile (beta)". The beta disclaimer must be stated to the user, not just implied. What the answer gates:
- Yes → produce the
```
-m.mp4
```
  mobile encodes (Step 6) and wire
```
clipMobile
```
  /
```
connectorsMobile
```
  (Step 7); run the full mobile QA (Step 8). If any scene's focal subject sits off-centre, offer the 9:16 hero-variant escape hatch (extra Higgsfield credits — say so).
- No → skip the mobile encodes and wiring entirely. The engine's phone hardening (seek-coalescing, iOS priming, safe-area CSS) is always on regardless — that's not a "mobile version," it's just the page not breaking when a phone visits — so a desktop-only build still degrades gracefully.

Video model is not an interview question — default

seedance_2_0

silently. If the user names a preference, honor it only if it can frame-lock seams (Step 4 roster:

seedance_2_0

kling3_0

seedance_2_0_mini

). This skill only ships seamless output, so a model that can't frame-lock is declined with a one-line why, not substituted in — use a roster model instead.

Keep the scroll mechanic fixed (continuous fly-through) — that's the point of the skill. See

references/prompts.md

for the intake checklist and copy structure.

主题由用户指定——以开放式问题询问，不要使用预设的选择题。虚构的行业列表会引导用户，显得您替他们决定业务方向；让用户用自己的语言回答（他们的真实业务、客户业务或任何想法）。仅在真正可枚举、低风险的选项中使用结构化选择题（Claude Code中的

AskUserQuestion

；其他场景用简单的二选一问题）——比如艺术风格和品牌套件方案，即使如此也要提供“其他”选项。只询问无法合理预设的内容，需覆盖：

主题（开放式提问，非选择题）——“这个世界应该围绕什么主题？您的业务、客户业务或任何想法——一个词或一句话即可。”记录行业/产品+一句宣传语（例如“一家奶茶公司，从茶叶到最后一口”），以及品牌名称（如果用户提供）；否则后续将自行提议。
品牌套件——提供三种方案，选择其一：
- 从URL导入：
```
higgsfield marketing-studio brand-kits fetch --url <site> --wait
```
  （提取名称、颜色、风格）。然后通过
```
brand-kits list --json
```
  查看结果。
- 用户直接提供调色板+名称+风格描述。
- 您提议调色板+名称，让用户确认。需记录4–6个带名称的十六进制颜色值、显示名称和1-2个风格关键词。
艺术风格——默认风格为“柔和哑光低多边形黏土立体模型，等距视角，移轴微缩效果，暖光”。提供替代选项（扁平纸艺、光泽玩具、黏土动画、霓虹夜景）。无论选择哪种风格，都将作为风格前缀在所有场景提示词中重复使用（这是保证世界连贯性的关键）。
旅程（板块）——摄像机飞越的有序场景。根据用户的价值链提议一组场景，让用户编辑。5–7个场景效果最佳。奶茶示例：茶园 → 珍珠制作间 → 旗舰店 → 配送 → 社区广场 → 主打产品。每个板块需要：简短的场景描述（立体模型中的内容）、副标题、主标题、一行正文和0–3个标签。最后一个板块通常是主打产品+CTA。
移动端版本（测试版）——务必询问，不要默认生成两个版本。以二选一问题询问（Claude Code中的
```
AskUserQuestion
```
；其他场景用简单问题）： *“是否需要同时生成移动端优化版本？移动端支持处于测试版——滚动驱动机制为桌面原生；在手机上会使用更轻量的编码和引擎加固，但竖屏会裁剪16:9画面，低端设备仍可能出现卡顿。”*选项：“仅桌面端” / “桌面端+移动端（测试版）”。必须向用户说明测试版免责声明，不能仅暗示。回答决定：
- 是 → 生成
```
-m.mp4
```
  移动端编码（步骤6）并配置
```
clipMobile
```
  /
```
connectorsMobile
```
  （步骤7）；完成完整的移动端QA（步骤8）。如果某个场景的核心主体偏离中心，可提供9:16英雄变体方案（需额外Higgsfield credits——请说明）。
- 否 → 完全跳过移动端编码和配置。引擎的手机加固功能（请求合并、iOS预加载、安全区域CSS）始终开启——这不是“移动端版本”，只是确保页面在手机访问时不会崩溃——因此仅桌面端构建仍能优雅降级。

视频模型不纳入调研问题——默认使用

seedance_2_0

，无需告知用户。如果用户指定偏好，仅当该模型支持帧锁定衔接时才遵循（步骤4的可用模型：

seedance_2_0

、

kling3_0

、

seedance_2_0_mini

）。该方案仅交付无缝输出，因此不支持帧锁定的模型会被拒绝并说明原因，不会替代使用——请选择可用模型。

保持滚动机制固定为连续飞行——这是该方案的核心。详见

references/prompts.md

中的调研清单和文案结构。

Step 2 — Generate the scene stills

步骤2 — 生成场景静帧

One image per section, all sharing the same style preamble for cohesion. Default model gpt_image_2
(crisp, great at isometric illustration; returns a solid/white background which is perfect for floating diorama "islands"). Use

nano_banana_2

only if the brief is character/cartoon-heavy (note:

nano_banana_2

is a CLI alias — it resolves to

nano_banana_pro

; it won't appear under that name in

higgsfield model list

Prompt shape (full templates in

references/prompts.md

<STYLE PREAMBLE, identical every time>. On a plain solid <bg> background with a soft
contact shadow. <PALETTE hexes>. No text, no letters, no logos, centered, 3:2.
Subject: <what is in THIS diorama>.

Run all N concurrently, detached. Command per scene:

higgsfield generate create gpt_image_2 --prompt "$(cat scene_i.txt)" --aspect_ratio 3:2 --resolution 2k --quality high --wait --wait-timeout 15m --json > scene_i.json 2>scene_i.err

Result URL is
```
.[]0.result_url
```
in the
```
--wait --json
```
output.
```
curl
```
it down.
A generation may fail transiently (HTTP 503) — re-roll that one individually; don't restart the batch.
Review the stills before continuing. They must read as one cohesive world (same angle, palette, light). If one is off-style, regenerate it, optionally passing an approved scene as
```
--image
```
to lock style.

See

references/pipeline.md

for the exact batch script.

每个板块对应一张图像，所有图像使用相同的风格前缀以保证连贯性。默认模型为**

gpt_image_2

**（画面清晰，擅长等距插画；返回纯色/白色背景，非常适合悬浮立体模型“岛屿”）。仅当需求以角色/卡通为主时使用

nano_banana_2

（注意：

nano_banana_2

是CLI别名——实际指向

nano_banana_pro

；在

higgsfield model list

中不会显示该别名）。

提示词格式（完整模板见

references/prompts.md

）：

<STYLE PREAMBLE, identical every time>. On a plain solid <bg> background with a soft
contact shadow. <PALETTE hexes>. No text, no letters, no logos, centered, 3:2.
Subject: <what is in THIS diorama>.

同时运行所有N个生成任务，后台执行。每个场景的命令：

higgsfield generate create gpt_image_2 --prompt "$(cat scene_i.txt)" --aspect_ratio 3:2 --resolution 2k --quality high --wait --wait-timeout 15m --json > scene_i.json 2>scene_i.err

结果URL在
```
--wait --json
```
输出的
```
.[]0.result_url
```
中。使用
```
curl
```
下载。
生成可能临时失败（HTTP 503）——单独重新生成该场景；不要重启整个批次。
继续前先检查静帧。它们必须呈现为一个连贯的世界（相同视角、调色板、光线）。如果某张静帧风格不符，重新生成，可选择传递一张已通过的场景作为
```
--image
```
来锁定风格。

详见

references/pipeline.md

中的精确批量脚本。

Step 3 — (Optional) Float the scenes

步骤3 — （可选）实现悬浮场景

If you want the dioramas to float over an atmospheric background instead of sitting in a solid box, knock out the flat background to transparency with

references/knockout.py

(border-connected flood fill — preserves interior colour that matches the bg, e.g. cream walls). Then encode to webp. If you'd rather keep it simple, just make the page background the same colour as the scene background and skip this.

These stills double as video posters and lazy-load fallbacks, so keep them.

如果希望立体模型悬浮在氛围感背景上而非纯色框中，使用

references/knockout.py

移除纯色背景实现透明（边界连接的泛洪填充——保留与背景颜色匹配的内部颜色，例如奶油色墙壁）。然后编码为webp格式。如果想简化操作，只需将页面背景设置为与场景背景相同的颜色，跳过此步骤。

这些静帧同时作为视频海报和懒加载占位图，请保留。

Step 4 — Camera architecture (pick one — this makes or breaks the feel)

步骤4 — 摄像机架构（二选一——决定体验质感）

How the camera moves between scenes is the single biggest quality lever. Two shapes; pick by aesthetic.

场景间的摄像机移动方式是影响品质的最大因素。两种架构；根据美学选择。

Video model — pick ONE for the whole chain

视频模型——全程使用同一模型

This skill only ships seamless output, so the only usable models are ones that can frame-lock a seam: every chained clip must accept

--start-image

, and connectors also need

--end-image

. That capability — not preference — is the selection rule. Check any model with

higgsfield model get <job_type>

and skip anything whose media inputs are reference-only (no start/end image): it can only condition a generation, not continue a shot, so it physically can't hold a seam. Schemas below were confirmed against the CLI:

Model	start/end image	Notes
`seedance_2_0` (default)	✓ / ✓	Full chain (legs + connectors). `--mode std --resolution 1080p` . Its NSFW filter is the touchy one (see Gotchas).
`kling3_0`	✓ / ✓	Full chain — tested: `--mode std --sound off --duration 5` with start+end images accepted, seams frame-lock cleanly. No `--resolution` param (don't pass one; `--mode std` returns 720p native — encode what ffprobe reports, never upscale). Sound defaults on → `--sound off` . `--duration` default 5, try 10 for legs. Different content filter than Seedance — the sanctioned NSFW fallback.
`seedance_2_0_mini`	✓ / ✓	Cheap draft tier that keeps frame-locking (720p). The previz tier: run the whole chain here first, then re-render final legs on the full model — still seamless, so it translates directly.

Those three are the roster — all do both architectures. (

kling3_0_turbo

also frame-locks via

--start-image

, but has no

--end-image

, so it's architecture-A-only and can't make connectors; it also takes a different flag set — no

--mode

, has

--resolution

— so it doesn't drop into the pipeline as-is. It's not in the default roster; only reach for it, and wire it by hand, if architecture A's sequential render time is a proven bottleneck and you've benchmarked it as actually faster.)

Rules:

One model for all chained clips. Each renderer has its own motion/color/grain character; mixing models mid-chain keeps position continuity (frames still hand off) but the render-character shift reads as a subtle pop. The one sanctioned exception is the NSFW fallback for a single stubborn clip (Gotchas) — a slight character shift on one 5s connector beats a missing connector.
Default to
```
seedance_2_0
```
; honor a user's stated preference only if the model qualifies (frame-locking). If it doesn't, say so and use a supported model — never ship a non-seamless build to satisfy a model request.
The pipeline scripts take the model as
```
$VMODEL
```
with per-model flags already cased out (
```
references/pipeline.md
```
).

该方案仅交付无缝输出，因此仅可使用支持帧锁定衔接的模型：每个串联片段必须接受

--start-image

，衔接片段还需支持

--end-image

。选择规则是该能力——而非偏好。通过

higgsfield model get <job_type>

检查模型，跳过任何媒体输入仅支持参考的模型（无起始/结束帧）：这类模型只能为生成提供条件，无法延续镜头，因此无法保持衔接。以下参数规范已通过CLI验证：

模型	起始/结束帧支持	说明
`seedance_2_0` （默认）	✓ / ✓	完整链（场景片段+衔接片段）。参数 `--mode std --resolution 1080p` 。其NSFW过滤器较为敏感（见注意事项）。
`kling3_0`	✓ / ✓	完整链——已测试： `--mode std --sound off --duration 5` 支持起始+结束帧，衔接处帧锁定清晰。无 `--resolution` 参数（不要传递； `--mode std` 返回原生720p——按ffprobe报告的分辨率编码，不要 upscale）。声音默认开启 → 需添加 `--sound off` 。默认 `--duration` 为5，场景片段可尝试设为10。内容过滤器与Seedance不同——是NSFW场景的备选方案。
`seedance_2_0_mini`	✓ / ✓	低成本草稿版本，仍支持帧锁定（720p）。预演版本：先使用该模型生成完整链，再用完整模型重新渲染最终场景片段——仍保持无缝，可直接转换。

以上三个为可用模型——均支持两种架构。（

kling3_0_turbo

也通过

--start-image

支持帧锁定，但无

--end-image

，因此仅支持架构A，无法生成衔接片段；且参数集不同——无

--mode

，有

--resolution

——无法直接融入工作流。不在默认可用列表中；仅当架构A的顺序渲染时间被证实为瓶颈，且经测试确实更快时，才手动使用该模型。）

规则：

所有串联片段使用同一模型。每个渲染器有自己的运动/色彩/颗粒特征；中途切换模型虽能保持位置连续性（帧仍可衔接），但渲染特征的变化会导致细微的跳帧。唯一允许的例外是单个顽固片段的NSFW备选方案（见注意事项）——5秒衔接片段的轻微特征变化比缺失衔接片段更好。
默认使用
```
seedance_2_0
```
；仅当用户指定的模型符合要求（支持帧锁定）时才遵循。如果不符合，说明原因并使用支持的模型——绝不因满足模型请求而交付非无缝构建。
工作流脚本通过
```
$VMODEL
```
指定模型，并已按模型区分参数（
```
references/pipeline.md
```
）。

A) Continuous forward take — RECOMMENDED for grounded / realistic / walkthrough

A) 连续向前镜头——推荐用于写实/沉浸式/漫游场景

One camera that only ever glides forward, first scene through last, as a single take. Generate the legs sequentially: leg 0 from scene-0's still (glide forward into it); then each leg's

--start-image

= the previous leg's ACTUAL last frame (extract with ffmpeg), prompt "continue gliding smoothly FORWARD into [scene i], never pulling back" (or an expressive mid-leg move under the motion-handoff contract — see Camera grammar below), and no
--end-image
— an end-image of a wide establishing shot forces the camera to pull back, which is the #1 cause of stutter. Extract each leg's last frame to feed the next. Result: every seam is frame-identical and the camera never reverses. There are no connectors (skip Step 5) — the legs ARE the journey. Wire each leg as a section clip with

connectors: []

and a small

crossfade

(~0.08). Even without an

--end-image

the legs still arrive at distinct rooms (the prompt steers the content). Cost: strictly sequential (can't parallelize) and slower; interiors trip the NSFW filter, so build in re-rolls (3 attempts/leg).

一台摄像机始终向前滑动，从第一个场景到最后一个场景，作为单个镜头。顺序生成场景片段：片段0从场景0的静帧开始（向前滑入）；然后每个片段的

--start-image

= 前一个片段的实际最后一帧（用ffmpeg提取），提示词为*“继续平稳向前滑入[场景i]，不要后退”*（或在运动衔接规则下使用富有表现力的镜头内移动——见摄像机语法），且不使用
--end-image
——宽景建立镜头的结束帧会迫使摄像机后退，这是卡顿的首要原因。提取每个片段的最后一帧用于下一个片段。结果：每个衔接处帧完全一致且摄像机从不后退。无衔接片段（跳过步骤5）——场景片段即为完整旅程。将每个片段配置为板块剪辑，

connectors: []

并添加小幅度

crossfade

（约0.08）。即使不使用

--end-image

，片段仍会到达不同场景（提示词引导内容）。成本：严格顺序执行（无法并行）且速度较慢；室内场景容易触发NSFW过滤器，因此需预留重新生成的次数（每个片段最多3次尝试）。

B) Dive-in + aerial connector — only for diorama / miniature / god's-eye worlds

B) 切入+空中衔接——仅适用于立体模型/微缩/上帝视角世界

A "dive into each scene" clip + a connector that pulls up and out and flies over to the next scene (Step 5). The pull-out reverses camera direction at every seam (forward dive → backward pull-out). In a miniature/diorama world that reads as an intentional "zoom out to the map, fly to the next island"; in a grounded first-person walkthrough it reads as a jarring rewind/stutter. Use B only for the map-like aesthetic. When in doubt, use A.

每个场景对应一段“切入”片段 + 一段衔接片段（向上飞出并飞往下一个场景，步骤5）。衔接片段在每个衔接处反转摄像机方向（向前切入 → 向后飞出）。在微缩/立体模型世界中，这会呈现为有意的“缩小到地图，飞往下一个岛屿”；在写实第一人称漫游场景中，这会显得突兀的倒带/卡顿。仅在地图类美学场景中使用B。不确定时选择A。

Camera grammar — the move should fit the concept (A is NOT "forward only")

摄像机语法——移动方式需符合概念（A并非“仅向前”）

"Forward only" is the seam rule, not the leg rule. The physics of the chain:

Position continuity at a seam comes from the frame handoff (next leg starts from the previous leg's actual last frame).
Velocity continuity at a seam means the camera must never reverse across a seam — that's the rewind stutter.
Inside a single leg the camera is free. One leg is one continuous render — there is no seam to break mid-leg, so orbits, crane-ups, lateral tracking, even a push-in that eases back out are all safe within the clip. Reversals are only fatal across seams.

So give each leg an expressive move chosen from the scene's own logic, under a motion handoff contract: every leg ends by settling into a slow, steady forward drift toward the next destination (final ~1 s), and every leg begins by continuing that same drift. Keep both clauses in the prompts verbatim (templates in

references/prompts.md

Pick the grammar from the concept:

Concept / tone	Mid-leg move
Product / luxury retail	slow half-orbit around the hero object, then continue past it
Real estate / hospitality	steadicam glide through doorways; gentle crane-up in atria
Industrial / process / logistics	low lateral track alongside the line, foreground parallax
Travel / outdoors / campus	drone-style rise-and-reveal, then a descending swoop
Food / craft / detail-driven	push in close to the craft moment, ease back, carry on
Playful miniature (arch. B)	dives + aerial hops — the connector IS the grammar

Honest costs: expressive mid-leg moves raise re-roll odds — the model can end a fancy move in a state that isn't a clean forward drift. Mitigations: keep the final-second settle clause verbatim; eyeball each leg's last frame before chaining the next (it should look like a frame from a gentle forward glide — if not, re-roll before wasting the next leg); budget ~1 extra re-roll per expressive leg. A plain forward glide stays the zero-risk default — use it for legs where the scene itself is the show.

Two related pacing knobs live in the engine (Step 7): per-section

scroll

(more scroll distance = longer dwell in that scene) and

linger

(the camera settles mid-scene exactly while the copy peaks, then picks up speed toward the seam). Prefer expressive motion in the clip and restraint in the scrub mapping — they compound.

And remember scroll is a scrubber: visitors can scroll up, so every move also plays in reverse. That's free and expected — no extra work — but it's another reason seam velocity must be consistent in both directions (a seam that reads fine forward reads as a stutter backward too if velocity flips).

For B, one camera flight per scene: starts high/outside, descends into the interior, structure opens. Model: the chain model you picked above (default seedance_2_0
),

--start-image = the scene still

Use the solid-background still (not the knocked-out transparent one) as the start image, so the video has a full frame.
Prompt: "Single continuous cinematic camera move, no cuts. Begin high and far looking at the whole <scene> from outside … descend and fly inside toward <focal point> … the roof/walls gently open to reveal the interior. <style>, smooth graceful slow motion. No text." (Template in
```
references/prompts.md
```
.)
Params (seedance):
```
--mode std --resolution 1080p --aspect_ratio 16:9 --duration 8
```
. For Kling: drop
```
--resolution
```
(no such param), add
```
--sound off
```
,
```
--duration 10
```
. Do not pass
```
--generate-audio
```
(it errors on seedance; audio is wasted anyway — you'll mute).
Run concurrently, detached, then download each
```
.result_url
```
. Re-roll individual failures. Keep the raw 1080p sources — you need their frames next.

“仅向前”是衔接处的规则，而非片段内的规则。链的物理逻辑：

衔接处的位置连续性来自帧传递（下一个片段从前一个片段的实际最后一帧开始）。
衔接处的速度连续性意味着摄像机在衔接处绝不能反向移动——这会导致倒带卡顿。
单个片段内摄像机可自由移动。一个片段是连续渲染的——片段内无衔接处可破坏，因此轨道移动、升降、横向跟踪，甚至先推进后拉远都在片段内是安全的。仅在衔接处反向移动是致命的。

因此，根据场景逻辑为每个片段选择富有表现力的移动方式，遵循运动衔接规则：每个片段最后约1秒以缓慢稳定的向前漂移结束，朝向下一个目的地；每个片段开始时延续该漂移。在提示词中严格保留这两个条款（模板见

references/prompts.md

）。

根据概念选择语法：

概念/风格	片段内移动方式
产品/奢侈品零售	围绕主打产品缓慢半环绕，然后继续向前
房地产/酒店	稳定摄像机滑过门口；中庭内缓慢上升
工业/流程/物流	沿生产线低空横向跟踪，前景视差效果
旅游/户外/校园	无人机式上升展示，然后俯冲下降
食品/手工艺/细节导向	推进至手工艺细节，缓慢拉远，继续向前
趣味微缩（架构B）	切入+空中跳跃——衔接片段即为语法

真实成本：富有表现力的片段内移动会增加重新生成的概率——模型可能在完成复杂移动后无法处于清晰的向前漂移状态。缓解措施：严格保留最后一秒的漂移条款；在串联下一个片段前检查每个片段的最后一帧（应呈现为缓慢向前漂移的帧——否则在浪费下一个片段前重新生成）；为每个富有表现力的片段预留约1次额外的重新生成次数。纯向前滑动是零风险的默认选项——在场景本身足够突出时使用。

引擎中有两个相关的节奏控制参数（步骤7）：每个板块的

scroll

（滚动距离越长，在该场景的停留时间越长）和

linger

（摄像机在文案最突出时停留在场景中间，然后加速向衔接处移动）。优先在片段中使用富有表现力的运动，在滚动映射中保持克制——两者会相互增强效果。

请记住滚动是双向的：访客可以向上滚动，因此所有移动也会反向播放。这是默认行为，无需额外工作——但这也是衔接处速度必须在两个方向一致的另一个原因（如果速度反转，向前播放时衔接正常，反向播放时仍会卡顿）。

对于架构B，每个场景对应一段摄像机飞行：从高处/外部开始，下降进入内部，场景结构展开。模型：您选择的链模型（默认**

seedance_2_0

**），

--start-image = 场景静帧

。

使用纯色背景静帧（而非移除背景的透明静帧）作为起始图像，确保视频画面完整。
提示词：“单个连续电影级摄像机移动，无剪辑。从高处远处俯瞰整个<场景>……下降并飞入内部朝向<焦点>……屋顶/墙壁缓缓打开以展示内部。<风格>，流畅优雅的慢动作。无文字。”（模板见
```
references/prompts.md
```
）。
参数（seedance）：
```
--mode std --resolution 1080p --aspect_ratio 16:9 --duration 8
```
。对于Kling：移除
```
--resolution
```
（无此参数），添加
```
--sound off
```
，
```
--duration 10
```
。不要传递
--generate-audio
（seedance会报错；音频无用——您会静音）。
后台并行运行，然后下载每个
```
.result_url
```
。单独重新生成失败的任务。保留原始1080p源文件——下一步需要提取帧。

Step 5 — Connectors (architecture B only)

步骤5 — 衔接片段（仅适用于架构B）

Skip this whole step for architecture A — the forward take has no connectors; its legs already chain seamlessly. This step applies to B (diorama/miniature), and note the reversal caveat from Step 4.

The connector clips are what make the world feel connected instead of cut. A connector flies from the end of scene i out and into the start of scene i+1. Both of its endpoints must be the ACTUAL RENDERED FRAMES of the neighbouring clips — never the original diorama still.

Why: every Higgsfield generation renders slightly differently. If a connector ends on a fresh render of "the kitchen diorama," but the next dive clip starts on its own different render of that same diorama, the two won't match and you get a pop at the seam. The fix is to hand off the exact pixels:

For each connector between dive_i and dive_{i+1}:
  start-image = the LAST frame extracted from dive_i's rendered video
  end-image   = the FIRST frame extracted from dive_{i+1}'s rendered video

Now every seam is frame-identical on both sides:

dive_i.end == connector.start

and

connector.end == dive_{i+1}.start

Extract the boundary frames from the rendered dives (not the stills):

bash

ffmpeg -sseof -0.15 -i dive_i.mp4   -frames:v 1 -q:v 2 dive_i_last.png    # interior of i
ffmpeg -ss 0      -i dive_{i+1}.mp4 -frames:v 1 -q:v 2 dive_next_first.png # establishing of i+1

Generate the connector (

--duration 5

is plenty). Connectors need

--end-image

, so the model must accept it — any roster model does (

seedance_2_0

seedance_2_0_mini

kling3_0

bash

higgsfield generate create "$VMODEL" \
  --prompt "$(cat connector_i.txt)" \
  --start-image dive_i_last.png --end-image dive_next_first.png \
  $VOPTS --aspect_ratio 16:9 --duration 5 --wait --json

架构A跳过此步骤——向前镜头无衔接片段；其场景片段已无缝串联。此步骤适用于B（立体模型/微缩），并注意步骤4中的反转警告。

衔接片段是让世界感觉连贯而非割裂的关键。衔接片段从场景i的结尾飞出并进入场景i+1的开头。其两个端点必须是相邻片段的实际渲染帧——绝不能是原始立体模型静帧。

原因：每个Higgsfield生成的渲染略有不同。如果衔接片段结束于“厨房立体模型”的新渲染，但下一个切入片段开始于同一立体模型的不同渲染，两者无法匹配，衔接处会出现跳帧。解决方案是传递精确的像素：

对于切入片段dive_i和dive_{i+1}之间的每个衔接片段：
  start-image = 从dive_i渲染视频中提取的最后一帧
  end-image   = 从dive_{i+1}渲染视频中提取的第一帧

现在每个衔接处的两侧帧完全一致：

dive_i.end == connector.start

且

connector.end == dive_{i+1}.start

。

从渲染的切入片段中提取边界帧（而非静帧）：

bash

ffmpeg -sseof -0.15 -i dive_i.mp4   -frames:v 1 -q:v 2 dive_i_last.png    # 场景i的内部
ffmpeg -ss 0      -i dive_{i+1}.mp4 -frames:v 1 -q:v 2 dive_next_first.png # 场景i+1的远景

生成衔接片段（

--duration 5

足够）。衔接片段需要

--end-image

，因此模型必须支持——所有可用模型均支持（

seedance_2_0

、

seedance_2_0_mini

、

kling3_0

）：

bash

higgsfield generate create "$VMODEL" \
  --prompt "$(cat connector_i.txt)" \
  --start-image dive_i_last.png --end-image dive_next_first.png \
  $VOPTS --aspect_ratio 16:9 --duration 5 --wait --json

seedance: VOPTS="--mode std --resolution 1080p"; kling3_0: VOPTS="--mode std --sound off"


Connector prompt: "Single continuous camera move, no cuts. Pull up and back out of
<scene i>, rise into the sky, glide across the connected miniature world, and arrive
above <scene i+1>, beginning to descend toward it. Seamless flowing aerial transition.
<style>. No text." (Template in `references/prompts.md`.)

Insurance: Seedance lands *close* to the end-image but not always pixel-perfect, so the
engine still applies a **short crossfade** (a few frames) at each seam. Frame-matched
endpoints + a small crossfade = no visible cut. Never skip the actual-frame handoff and
rely on the crossfade alone; a big content jump can't be hidden by a crossfade.

---


衔接片段提示词：“单个连续摄像机移动，无剪辑。从<场景i>向上向后飞出，升至空中，滑过相连的微缩世界，到达<场景i+1>上方，开始下降。无缝流畅的空中过渡。<风格>。无文字。”（模板见`references/prompts.md`）。

保险措施：Seedance生成的结尾帧与目标结束帧接近但并非始终像素完美，因此引擎仍会在每个衔接处应用**短交叉淡入淡出**（几帧）。帧匹配的端点+小幅度交叉淡入淡出=无可见剪辑。绝不要跳过实际帧传递仅依赖交叉淡入淡出；内容的大幅跳跃无法被交叉淡入淡出掩盖。

---

Step 6 — Encode for smooth scrubbing

步骤6 — 编码以实现流畅滚动

Scrubbing = setting

video.currentTime

from scroll. Two things matter, and they are often gotten wrong:

Seekability, not keyframe density, is what makes scrubbing work. Many static hosts (and
```
python -m http.server
```
) don't serve HTTP byte-range requests, which pins
```
video.seekable
```
to
```
[0,0]
```
and clamps every seek to frame 0 — the video looks frozen. The robust fix is to fetch each clip as a
Blob
and play it from an in-memory object URL (blobs are always fully seekable). The engine does this. Because of it, you do not need all-intra video.
Don't shrink quality to get smooth seeks. Encode at the native resolution (1080p from Seedance — don't downscale),
```
crf ~20
```
, a small GOP (
```
-g 8
```
) rather than all-intra (all-intra bloats an 8s clip to ~25 MB; GOP 8 is ~8 MB and scrubs fine via blob). Strip audio, add faststart, and a light
```
unsharp
```
counters video softness:

bash

ffmpeg -i src.mp4 -an -vf "unsharp=5:5:0.8:5:5:0.0" \
  -c:v libx264 -preset slow -crf 20 -pix_fmt yuv420p \
  -g 8 -keyint_min 8 -sc_threshold 0 -movflags +faststart out.mp4

Encode all 2N-1 clips (dives + connectors) with the same settings for uniform quality.

Mobile encodes (beta — only if the user opted in at Step 1.5). Phone video decoders seek far slower than a laptop's, and seek cost scales with GOP length, so the 1080p

-g 8

master that scrubs smoothly on desktop can stutter on a phone. Produce a lighter

-m.mp4

sibling for every clip — 720p,
-g 4
(more keyframes = cheaper seeks), crf 23 — and wire them as

clipMobile

connectorsMobile

(Step 7). The engine serves them automatically on phones and falls back to the desktop clip when absent. The exact

encm()

script is in

references/pipeline.md

§6. If the user chose desktop-only, skip this — the engine still hardens phone scrubbing regardless (seek-coalescing, iOS priming), so the page degrades gracefully rather than breaking.

滚动控制 = 通过滚动位置设置

video.currentTime

。两点至关重要，且常被误解：

可寻址性，而非关键帧密度，是实现流畅滚动的关键。许多静态主机（和
```
python -m http.server
```
）不支持HTTP字节范围请求，导致
```
video.seekable
```
为
```
[0,0]
```
，所有寻址操作都会被限制在第0帧——视频看起来像冻结了。可靠的解决方案是将每个片段作为
Blob
获取，并从内存对象URL播放（Blob始终完全可寻址）。引擎已实现此功能。因此，您无需全帧内编码视频。
不要为了流畅寻址而降低画质。以原生分辨率编码（Seedance的1080p——不要缩小），
```
crf ~20
```
，使用小GOP（
```
-g 8
```
）而非全帧内编码（全帧内编码会将8秒片段膨胀至~25 MB；GOP 8约为8 MB，通过Blob可流畅滚动）。移除音频，添加faststart，轻微的
```
unsharp
```
滤镜可抵消视频模糊：

bash

ffmpeg -i src.mp4 -an -vf "unsharp=5:5:0.8:5:5:0.0" \
  -c:v libx264 -preset slow -crf 20 -pix_fmt yuv420p \
  -g 8 -keyint_min 8 -sc_threshold 0 -movflags +faststart out.mp4

使用相同设置编码所有2N-1个片段（切入片段+衔接片段）以保证画质统一。

移动端编码（测试版——仅当用户在步骤1.5中选择时）。手机视频解码器的寻址速度远慢于笔记本电脑，且寻址成本随GOP长度增加而增加，因此在桌面端流畅滚动的1080p

-g 8

主文件在手机上可能卡顿。为每个片段生成一个更轻量的

-m.mp4

版本——720p，
-g 4
（更多关键帧=更低寻址成本），crf 23——并配置为

clipMobile

connectorsMobile

（步骤7）。引擎会自动在手机上提供这些版本，在缺少时回退到桌面端片段。精确的

encm()

脚本见

references/pipeline.md

第6节。如果用户选择仅桌面端，跳过此步骤——引擎仍会启用手机滚动加固（请求合并、iOS预加载），因此页面会优雅降级而非崩溃。

Step 7 — Assemble the page

步骤7 — 组装页面

Copy

references/scrub-engine.js

(and, if you want a fully standalone page, the tiny

references/index-template.html

) into the user's project — or adapt into their framework. It's config-driven and self-contained:

mountScrollWorld(document.getElementById('world'), {
  brand: { name: 'Pearl & Co.' },
  diveScroll: 1.3, connScroll: 0.9,          // viewport-heights of scroll per clip
  sections: [
    { id:'farm', label:'The Farms', still:'assets/farm.webp',
      clip:'assets/vid/farm.mp4', clipMobile:'assets/vid/farm-m.mp4',   // mobile beta only
      scroll: 1.6, linger: 0.45,   // optional pacing: longer dwell + camera settles mid-scene
      accent:'#8FB98A', eyebrow:'From leaf to last sip', title:'It starts in the hills.',
      body:'…', tags:['Single-origin','Hand-picked'] },
    // …one per section; last may carry a `cta`
  ],
  connectors:       ['assets/vid/conn1.mp4','assets/vid/conn2.mp4',   /* … length = sections-1 */],
  connectorsMobile: ['assets/vid/conn1-m.mp4','assets/vid/conn2-m.mp4' /* … same length; mobile beta only */],
});

The engine handles: the ordered dive/connector chain, scroll→currentTime with rAF smoothing, blob loading, lazy prefetch of nearby clips, frame-matched crossfades, pinned per-section copy (first section greets on landing, last holds its CTA), a route rail,

prefers-reduced-motion

, and mobile. Pacing per section:

scroll

overrides

diveScroll

for that scene (more scroll = longer dwell) and

linger

(0–1, keep ≤ 0.6) remaps time so the camera settles mid-scene — exactly while the copy peaks — then speeds up toward the seam; seam frames are untouched (f(0)=0, f(1)=1). Give the hero and finale scenes a higher

scroll

+ some

linger

; keep transit scenes brisk. Theme it with CSS variables (

--accent

--sw-bg

--sw-ink

, …) — the visual identity comes from the generated clips, so the chrome stays quiet. See the header of

scrub-engine.js

for the full config + CSS vars.

On phones the engine adapts automatically (coarse pointer or ≤860px): it serves

clipMobile

connectorsMobile

when present, coalesces seeks (never queues a new

currentTime

while the decoder is still seeking — this is what stops a fast flick from freezing the clip), keeps the still as a poster until the clip paints its first frame and primes each video on first touch (fixes iOS's blank-until-played video), drops the drifting particles, ignores URL-bar-only resizes (no scroll jump), and uses safe-area insets so copy clears the notch/home indicator. All of this hardening is on by default — no config needed. The

clipMobile

connectorsMobile

encodes are the opt-in mobile beta part (Step 1.5): only wire them when the user asked for the mobile version.

For non-JS backends (Python/Rails/etc.): serve the assets and drop the engine

<script>

into the rendered HTML; nothing about it is framework-specific.

将

references/scrub-engine.js

（如果需要完全独立的页面，还需 tiny的

references/index-template.html

）复制到用户项目中——或适配到他们的框架中。它由配置驱动且独立：

mountScrollWorld(document.getElementById('world'), {
  brand: { name: 'Pearl & Co.' },
  diveScroll: 1.3, connScroll: 0.9,          // 每个片段对应的视口滚动高度
  sections: [
    { id:'farm', label:'The Farms', still:'assets/farm.webp',
      clip:'assets/vid/farm.mp4', clipMobile:'assets/vid/farm-m.mp4',   // 仅移动端测试版
      scroll: 1.6, linger: 0.45,   // 可选节奏：更长停留时间 + 摄像机停留在场景中间
      accent:'#8FB98A', eyebrow:'From leaf to last sip', title:'It starts in the hills.',
      body:'…', tags:['Single-origin','Hand-picked'] },
    // …每个板块对应一个；最后一个可包含`cta`
  ],
  connectors:       ['assets/vid/conn1.mp4','assets/vid/conn2.mp4',   /* … 长度 = 板块数-1 */],
  connectorsMobile: ['assets/vid/conn1-m.mp4','assets/vid/conn2-m.mp4' /* … 长度相同；仅移动端测试版 */],
});

引擎处理：有序的切入/衔接片段链、通过rAF平滑实现滚动→currentTime、Blob加载、附近片段的懒预加载、帧匹配的交叉淡入淡出、固定的每个板块文案（第一个板块在着陆时显示，最后一个板块保留CTA）、导航轨道、

prefers-reduced-motion

适配和移动端适配。每个板块的节奏：

scroll

覆盖该场景的

diveScroll

（滚动距离越长，停留时间越长），

linger

（0–1，保持≤0.6）重新映射时间，使摄像机停留在场景中间——正好在文案最突出时——然后加速向衔接处移动；衔接帧不受影响（f(0)=0, f(1)=1）。为主打场景和结尾场景设置更高的

scroll

+ 一些

linger

；过渡场景保持快速。使用CSS变量（

--accent

、

--sw-bg

、

--sw-ink

等）设置主题——视觉标识来自生成的片段，因此界面元素保持简洁。详见

scrub-engine.js

头部的完整配置+CSS变量。

引擎在手机上自动适配（粗糙指针或≤860px）：当存在

clipMobile

connectorsMobile

时提供这些版本，合并请求（解码器仍在寻址时绝不排队新的

currentTime

——这可防止快速滑动导致片段冻结），在片段渲染第一帧前保留静帧作为海报，并在首次触摸时预加载每个视频（修复iOS视频未播放时空白的问题），移除漂移粒子，忽略仅URL栏变化的resize（无滚动跳跃），并使用安全区域内边距确保文案避开刘海/主屏幕指示器。所有这些加固功能默认开启——无需配置。

clipMobile

connectorsMobile

编码是可选的移动端测试版部分（步骤1.5）：仅当用户要求移动端版本时才配置。

对于非JS后端（Python/Rails等）：提供资源并将引擎

<script>

嵌入渲染后的HTML；它与框架无关。

Step 8 — QA the seams (don't skip)

步骤8 — 衔接处QA（不要跳过）

Drive the page in a headless browser and verify frame continuity at the seams, which is the thing most likely to be wrong:

Screenshot at scroll positions just before and just after each seam. The two frames must be near-identical (the dive's last frame == the connector's first frame). If they pop, you used the diorama still instead of the actual rendered frame (redo Step 5), or the crossfade band is too short.
Check the console for errors, confirm
```
video.seekable.end(0) > 0
```
(blob working), and that
```
currentTime
```
tracks scroll across each clip's band.
Mobile — full checklist only if the user opted into the mobile beta (Step 1.5). For a desktop-only build, just sanity-check a phone viewport once: page loads, still posters show, nothing overlaps — the engine's hardening covers graceful degradation. For the beta (do this on a real phone or an emulated one, portrait + landscape):
- Emulate a phone viewport with CPU throttled 4–6× and scroll fast — the clip should track without freezing (the seek-coalescing +
```
-m.mp4
```
  encodes are what make this hold).
- Confirm the first scene shows immediately (its still is the poster) and the video takes over the instant you scroll — no blank/black scene (the iOS priming fix). Test iOS Safari specifically; it's the one that goes blank if this regresses.
- Verify the
```
-m.mp4
```
  variant is actually served on mobile (Network panel), and the heavy 1080p master on desktop.
- Slowly scroll so the URL bar collapses — the page must not jump (height-only resizes are ignored on touch). Rotate the device — layout should recompose cleanly.
- Portrait crops a 16:9 clip to its centre; confirm the focal subject still reads. If a hero scene's subject sits off-centre and gets cut, recompose it (prompts.md) or generate a 9:16 variant for that scene.
Check reduced-motion (should fall back to the stills, no video, no particles).

在无头浏览器中测试页面，验证衔接处的帧连续性——这是最可能出错的地方：

在每个衔接处前后的滚动位置截图。两帧必须几乎完全一致（切入片段的最后一帧 == 衔接片段的第一帧）。如果出现跳帧，说明您使用了立体模型静帧而非实际渲染帧（重新执行步骤5），或交叉淡入淡出区间太短。
检查控制台是否有错误，确认
```
video.seekable.end(0) > 0
```
（Blob正常工作），且
```
currentTime
```
在每个片段的滚动区间内跟踪滚动位置。
移动端——仅当用户选择移动端测试版（步骤1.5）时才完成完整检查清单。对于仅桌面端构建，只需 sanity-check一次手机视口：页面加载，静帧海报显示，无重叠内容——引擎的加固功能可保证优雅降级。对于测试版（在真实手机或模拟器上测试，竖屏+横屏）：
- 模拟手机视口**CPU节流4–6×**并快速滚动——片段应能跟踪滚动而不冻结（请求合并+
```
-m.mp4
```
  编码是实现此效果的关键）。
- 确认第一个场景立即显示（其静帧为海报），滚动时视频立即接管——无空白/黑屏场景（iOS预加载修复）。专门测试iOS Safari；如果此功能失效，它会出现空白。
- 验证移动端实际提供
```
-m.mp4
```
  版本（网络面板），桌面端提供1080p主文件。
- 缓慢滚动使URL栏收起——页面不得跳跃（触摸时忽略仅高度变化的resize）。旋转设备——布局应重新组合干净。
- 竖屏会裁剪16:9片段的中心；确认核心主体仍清晰可见。如果主打场景的主体偏离中心被裁剪，重新构思（prompts.md）或为该场景生成9:16变体。
检查减少动画模式（应回退到静帧，无视频，无粒子）。

Gotchas (hard-won)

注意事项（经验总结）

Seam pop → connector endpoints were the diorama stills, not the neighbouring clips' actual frames. Always extract real frames (Step 5).
Seam stutter / camera "jumps backward" → even with frame-matched seams, if the camera velocity reverses (forward dive, then a connector that pulls back out) it reads as a rewind. This is inherent to architecture B. For any grounded walkthrough use architecture A (one continuous forward take — legs chained from actual last frames, no pull-back, no
```
--end-image
```
); see Step 4.
Frozen video / stuck at frame 0 →
```
seekable=[0,0]
```
; the host isn't serving byte ranges. Use blob URLs (engine does).
Huge files → you used all-intra. Use
```
-g 8
```
+ blob instead.
Soft / low quality → you downscaled or over-compressed. Encode native 1080p, crf ≤ 20, add
```
unsharp
```
. Video is inherently softer than the stills — keep the stills as the lite fallback for max fidelity.
Concurrent gens 503 / "not_enough_credits" race → transient when many launch at once; re-roll the individual failure, it's not really out of credits (verify with
```
higgsfield workspace list
```
).
NSFW false-positives (Seedance
status "nsfw"
) → the video content filter flags perfectly innocuous clips, especially bedroom, pool, spa/wellness contexts and trigger words like "bed", "pool", "waterfall", "wine", "swim". It's partly the prompt wording and partly the reference frames. Fixes, in order: (1) re-roll — it's often non-deterministic and passes on the 2nd–3rd try; (2) strip trigger words and add "empty, unoccupied, no people, no figures, architectural, tasteful"; (3) regenerate just that clip on kling3_0
with the same start/end frames — a different provider's filter often passes what Seedance blocks. Expect a slight render-character shift on that one clip (each model has its own grain/motion feel); for a 5s connector behind a crossfade that usually beats option (4): set the connector slot to
```
null
```
— the engine crossfades that seam directly (optional connectors), so the page still completes. Budget extra credits/time for these re-rolls on interiors/real-estate content.
Dark / custom theme → the engine wraps its default tokens in
```
@layer sw
```
, so a page-level
```
:root
```
/
```
.sw-root { --sw-bg; --sw-ink; --sw-accent; --sw-font-* }
```
block wins cleanly (no specificity hacks).
```
--sw-ink
```
is your primary text/heading colour; the accent fills the primary button and active nav. For a dark theme, set
```
--sw-bg
```
dark and
```
--sw-ink
```
light — the copy scrim and title shadow follow
```
--sw-bg
```
automatically.
Phone scrub stutters / freezes on a fast flick → the 1080p master is too heavy for a phone decoder and seeks pile up. Ship the
```
-m.mp4
```
mobile encodes (720p,
```
-g 4
```
) and wire
```
clipMobile
```
/
```
connectorsMobile
```
(Step 6/7). The engine already coalesces seeks; the lighter encode is the other half. Still choppy on a low-end device? Tighten GOP (
```
-g 2
```
/ all-intra).
Blank / black scene on iOS (desktop was fine) → an iOS Safari quirk: a muted video that was never played won't paint a seeked frame. The engine fixes this by keeping the still as a poster until the clip paints and priming each video on first touch — so don't hide the still on
```
loadedmetadata
```
or strip the
```
playsinline
```
/
```
muted
```
attributes if you adapt the engine into a framework.
Page jumps while scrolling on mobile → something is re-running layout on the URL-bar show/hide
```
resize
```
. The engine ignores height-only resizes on touch; if you ported it, gate your resize handler on a width change (keep the
```
orientationchange
```
path for rotation).
Copy hidden behind the URL bar / notch on mobile → use the engine's safe-area-aware bottom offset (
```
env(safe-area-inset-bottom)
```
+
```
dvh
```
); make sure the page's
```
<meta viewport>
```
includes
```
viewport-fit=cover
```
(the template does).
Portrait crops the scene → a 16:9 clip on a tall phone shows only its centre. Keep each scene's focal subject centred with a little headroom (prompts.md), or generate a 9:16 hero for the scenes that matter most. The engine centre-crops (
```
object-fit:cover
```
); it can't un-crop a widescreen composition.
--generate-audio
errors on seedance → omit it; mute in HTML and
```
-an
```
on encode.
Kling rejects your flags →
```
kling3_0
```
has no
--resolution
param (don't pass one; encode at whatever native res ffprobe reports) and sound defaults on — pass
```
--sound off
```
. Duration default is 5; legs/dives want 10.
Seam pop only where you "saved credits" → you swapped models mid-chain, or used a start-image-only model where a connector needs an
```
--end-image
```
. One model for the whole chain; the only cheap tier is
```
seedance_2_0_mini
```
, which keeps frame-locking so it stays seamless. (Any model with reference-only inputs can't hold a seam at all — Step 4.)
White-box scenes →
```
gpt_image_2
```
returns a solid bg; either match the page bg to it or knock it out (Step 3).
bash 3.2 on macOS → no associative arrays in scripts.

衔接处跳帧 → 衔接片段端点使用了立体模型静帧，而非相邻片段的实际帧。始终提取真实帧（步骤5）。
衔接处卡顿 / 摄像机“向后跳跃” → 即使帧匹配，如果摄像机速度反转（向前切入，然后衔接片段向后飞出），仍会呈现为倒带。这是架构B的固有问题。任何写实漫游场景使用架构A（单个连续向前镜头——场景片段通过实际最后一帧串联，无后退，无
```
--end-image
```
）；详见步骤4。
视频冻结 / 停留在第0帧 →
```
seekable=[0,0]
```
；主机不支持字节范围请求。使用Blob URL（引擎已实现）。
文件过大 → 使用了全帧内编码。使用
```
-g 8
```
+ Blob替代。
画面模糊 / 低画质 → 缩小分辨率或过度压缩。以原生1080p编码，crf ≤20，添加
```
unsharp
```
滤镜。视频本质上比静帧模糊——保留静帧作为轻量占位图以保证最高保真度。
并发生成出现503 / "not_enough_credits"竞争 → 同时启动多个任务时的临时错误；单独重新生成失败的任务，并非真的缺少credits（通过
```
higgsfield workspace list
```
验证）。
NSFW误判（Seedance状态为"nsfw"） → 视频内容过滤器标记完全无害的片段，尤其是卧室、泳池、水疗/养生场景和触发词如“bed”、“pool”、“waterfall”、“wine”、“swim”。部分原因是提示词措辞，部分原因是参考帧。修复顺序：(1) 重新生成——通常是非确定性的，第2–3次尝试可能通过；(2) 移除触发词并添加“empty, unoccupied, no people, no figures, architectural, tasteful”；(3) 使用**
```
kling3_0
```
**重新生成该片段，使用相同的起始/结束帧——不同提供商的过滤器通常会通过Seedance阻止的内容。该片段会出现轻微的渲染特征变化（每个模型有自己的颗粒/运动风格）；对于5秒的衔接片段，在交叉淡入淡出下，这通常比选项(4)更好：将衔接片段插槽设为
```
null
```
——引擎会直接交叉淡入淡出该衔接处（可选衔接片段），因此页面仍能完成。为室内/房地产内容预留额外的credits/时间用于重新生成。
深色/自定义主题 → 引擎将默认令牌包裹在
```
@layer sw
```
中，因此页面级的
```
:root
```
/
```
.sw-root { --sw-bg; --sw-ink; --sw-accent; --sw-font-* }
```
块会优先生效（无需特异性 hack）。
```
--sw-ink
```
是您的主要文字/标题颜色；accent填充主按钮和活动导航。对于深色主题，设置
```
--sw-bg
```
为深色，
```
--sw-ink
```
为浅色——文案遮罩和标题阴影会自动跟随
```
--sw-bg
```
。
手机滚动卡顿 / 快速滑动时冻结 → 1080p主文件对手机解码器来说过重，请求堆积。交付
```
-m.mp4
```
移动端编码（720p，
```
-g 4
```
）并配置
```
clipMobile
```
/
```
connectorsMobile
```
（步骤6/7）。引擎已合并请求；更轻量的编码是另一关键。低端设备仍卡顿？缩小GOP（
```
-g 2
```
/ 全帧内编码）。
iOS上出现空白/黑屏（桌面端正常） → iOS Safari的怪癖：从未播放过的静音视频不会渲染寻址帧。引擎通过保留静帧作为海报直到片段渲染，并在首次触摸时预加载每个视频来修复此问题——因此如果您将引擎适配到框架中，不要在
```
loadedmetadata
```
时隐藏静帧，或移除
```
playsinline
```
/
```
muted
```
属性。
移动端滚动时页面跳跃 → URL栏显示/隐藏的
```
resize
```
事件触发了布局重计算。引擎在触摸时忽略仅高度变化的resize；如果您移植了引擎，请在宽度变化时触发resize处理程序（保留
```
orientationchange
```
路径用于旋转）。
移动端文案被URL栏/刘海遮挡 → 使用引擎的安全区域感知底部偏移（
```
env(safe-area-inset-bottom)
```
+
```
dvh
```
）；确保页面的
```
<meta viewport>
```
包含
```
viewport-fit=cover
```
（模板已包含）。
竖屏裁剪场景 → 16:9片段在长屏手机上仅显示中心。保持每个场景的核心主体居中并留有少量顶部空间（prompts.md），或为最重要的场景生成9:16英雄变体。引擎居中裁剪（
```
object-fit:cover
```
）；无法还原宽屏构图。
seedance上
--generate-audio
报错 → 省略该参数；在HTML中静音并在编码时添加
```
-an
```
。
Kling拒绝您的参数 →
```
kling3_0
```
无
--resolution
参数（不要传递；按ffprobe报告的原生分辨率编码），且声音默认开启——需添加
```
--sound off
```
。默认
```
--duration
```
为5；场景片段/切入片段设为10。
仅在“节省credits”的地方出现衔接处跳帧 → 中途切换了模型，或在需要
```
--end-image
```
的衔接片段中使用了仅支持起始帧的模型。全程使用同一模型；唯一的低成本版本是
```
seedance_2_0_mini
```
，它仍支持帧锁定，因此保持无缝。（任何仅支持参考输入的模型完全无法保持衔接——步骤4。）
白框场景 →
```
gpt_image_2
```
返回纯色背景；将页面背景设置为相同颜色或移除背景（步骤3）。
macOS上的bash 3.2 → 脚本中不支持关联数组。

References

参考资源

```
references/prompts.md
```
— the intake checklist, style-preamble pattern, and every prompt template (scene still, dive, connector) with fill-in slots.
```
references/pipeline.md
```
— copy-paste batch scripts for the whole run (generate → extract frames → connectors → encode → mobile encode), bash-3.2-safe.
```
references/scrub-engine.js
```
— the portable, config-driven scrub engine (builds DOM + injects CSS; blob-seek, lazy load, seam crossfade, copy, route rail, reduced-motion, and phone hardening: mobile encodes, seek-coalescing, iOS priming, safe-area, no-jump resize).
```
references/index-template.html
```
— a minimal standalone page that mounts the engine.
```
references/knockout.py
```
— border-connected background knockout for floating scenes.

```
references/prompts.md
```
— 调研清单、风格前缀模式和所有提示词模板（场景静帧、切入片段、衔接片段），包含填充插槽。
```
references/pipeline.md
```
— 完整流程的复制粘贴批量脚本（生成 → 提取帧 → 衔接片段 → 编码 → 移动端编码），兼容bash 3.2。
```
references/scrub-engine.js
```
— 可移植、配置驱动的滚动引擎（构建DOM + 注入CSS；Blob寻址、懒加载、衔接处交叉淡入淡出、文案、导航轨道、减少动画模式和手机加固：移动端编码、请求合并、iOS预加载、安全区域、无跳跃resize）。
```
references/index-template.html
```
— 挂载引擎的最小独立页面。
```
references/knockout.py
```
— 用于悬浮场景的边界连接背景移除工具。