@baimingtao/lbs-agent 1.0.0

package/extensions/skills/builtin/creative/ascii-video/references/scenes.md

@@ -0,0 +1,741 @@
+# 场景系统与创意构图
+
+> **另见:** architecture.md · composition.md · effects.md · shaders.md
+
+## 场景设计哲学
+
+场景是叙事单元，而非特效演示。每个场景都需要：
+- 一个**概念** —— 视觉上正在发生什么？不是“等离子+圆环”，而是“从虚无中涌现”或“结晶化”
+- 一个**弧线** —— 它在其持续时间内如何变化？蓄势、衰减、变换、揭示？
+- 一个**角色** —— 它如何服务于更大的视频叙事？开场张力、能量顶峰、结局收尾？
+
+下文的设计模式提供了构图技巧。场景示例展示了它们在实践中不断增加的复杂度。协议部分涵盖了技术契约。
+
+优秀的场景设计始于概念，然后选择服务于该概念的特效和参数。设计模式部分展示了*如何*有意地构图图层。示例部分展示了每个复杂度级别的完整工作场景。协议部分涵盖了所有场景必须遵循的技术契约。
+
+---
+
+## 场景设计模式
+
+用于组合场景的高阶模式，让场景感觉是有意为之，而非随机的。这些模式使用现有的构建块（value fields、blend modes、shaders、feedback），但将它们以构图意图组织起来。
+
+## 图层层级
+
+每个场景都应具有带有不同角色的清晰视觉图层：
+
+| 图层 | Grid | 亮度 | 目的 |
+|-------|------|-----------|---------|
+| **Background** | xs 或 sm（密集） | 0.1–0.25 | 氛围，纹理。绝不喧宾夺主。 |
+| **Content** | md（均衡） | 0.4–0.8 | 主要视觉思想。承载场景的概念。 |
+| **Accent** | lg 或 sm（稀疏） | 0.5–1.0（稀疏覆盖） | 高光，标点，稀疏的亮点。 |
+
+背景设定情绪。内容层是场景*表达的主题*。点缀层在不喧宾夺主的前提下增加视觉趣味。
+
+```python
+def fx_example(r, f, t, S):
+    local = t
+    progress = min(local / 5.0, 1.0)
+
+    g_bg = r.get_grid("sm")
+    g_main = r.get_grid("md")
+    g_accent = r.get_grid("lg")
+
+    # --- Background: dim atmosphere ---
+    bg_val = vf_smooth_noise(g_bg, f, t * 0.3, S, octaves=2, bri=0.15)
+    # ... render bg to canvas
+
+    # --- Content: the main visual idea ---
+    content_val = vf_spiral(g_main, f, t, S, n_arms=n_arms, tightness=tightness)
+    # ... render content on top of canvas
+
+    # --- Accent: sparse highlights ---
+    accent_val = vf_noise_static(g_accent, f, t, S, density=0.05)
+    # ... render accent on top
+
+    return canvas
+```
+
+## 定向参数弧线
+
+在场景的持续时间内，参数应该*有明确的发展方向* —— 而不是使用 `sin(t * N)` 漫无目的地振荡。
+
+**反面教材：** `twist = 3.0 + 2.0 * math.sin(t * 0.6)` —— 来回摆动，让人感觉漫无目的。
+
+**正面教材：** `twist = 2.0 + progress * 5.0` —— 起始温和，结束强烈。场景在不断*蓄势*。
+
+使用 `progress = min(local / duration, 1.0)`（在场景内从 0→1）来驱动定向变化：
+
+| 模式 | 公式 | 感觉 |
+|---------|---------|------|
+| 线性斜坡 | `progress * range` | 稳定的积累 |
+| 缓出 | `1 - (1 - progress) ** 2` | 快速开始，平缓结束 |
+| 缓入 | `progress ** 2` | 缓慢开始，逐渐加速 |
+| 步进显示 | `np.clip((progress - 0.5) / 0.25, 0, 1)` | 在 50% 之前不可见，随后淡入 |
+| 蓄势 + 平稳期 | `min(1.0, progress * 1.5)` | 在 67% 达到顶峰，保持不变 |
+
+振荡对于*次要*参数（如饱和度微光、色调偏移）来说是可以的。但是场景的*决定性*参数应该具有明确的方向。
+
+### 定向弧线示例
+
+| 场景概念 | 参数 | 弧线 |
+|--------------|-----------|-----|
+| 涌现 | 圆环半径 | 0 → max (ease-out) |
+| 破碎 | Voronoi 单元数 | 8 → 38 (linear) |
+| 坠落 | 隧道速度 | 2.0 → 10.0 (linear) |
+| 曼陀罗 | 形状复杂度 | 圆环 → +多边形 → +星形 → +玫瑰形 (step reveals) |
+| 渐强 | 图层数量 | 1 → 7 (交错进入) |
+| 熵 | 几何可见度 | 1.0 → 0.0 (被消耗) |
+
+## 场景概念
+
+每个场景都应围绕一个*视觉理念*构建，而不是特效名称。
+
+**反面教材：** "fx_plasma_cascade" —— 以特效命名。没有概念。
+**正面教材：** "fx_emergence" —— 一个光点扩展成一个场。这个名字告诉你*发生了什么*。
+
+优秀的场景概念具有：
+1. 一个**视觉隐喻**（涌现、坠落、碰撞、熵）
+2. 一个**定向弧线**（事物从 A 变化到 B，而非振荡）
+3. **有明确动机的图层选择**（每个图层都服务于核心概念）
+4. **有明确动机的 feedback**（变换方向与隐喻相匹配）
+
+| 概念 | 隐喻 | Feedback 变换 | 原因 |
+|---------|----------|-------------------|-----|
+| 涌现 | 诞生，扩张 | zoom-out | 过去帧向外扩张 |
+| 坠落 | 掉落，加速 | zoom-in | 过去帧向中心冲来 |
+| 地狱 | 升起的火焰 | shift-up | 过去帧随火焰一同升起 |
+| 熵 | 衰变，消散 | none | 干净，无残影 —— 事物直接消失 |
+| 渐强 | 积累 | zoom + hue_shift | 一切都在复合和变化 |
+
+## 构图技巧
+
+### 反向旋转双系统
+
+同一个特效的两个实例以相反方向旋转，可产生视觉干涉：
+
+```python
+# Primary spiral (clockwise)
+s1_val = vf_spiral(g_main, f, t * 1.5, S, n_arms=n_arms_1, tightness=tightness_1)
+
+# Counter-rotating spiral (counter-clockwise via negative time)
+s2_val = vf_spiral(g_accent, f, -t * 1.2, S, n_arms=n_arms_2, tightness=tightness_2)
+
+# Screen blend creates bright interference at crossing points
+canvas = blend_canvas(canvas_with_s1, c2, "screen", 0.7)
+```
+
+适用于螺旋、漩涡、圆环。反向旋转创造了不断变化的干涉图样。
+
+### 波浪碰撞
+
+两个波前从相对的两侧汇聚，在碰撞点相遇：
+
+```python
+collision_phase = abs(progress - 0.5) * 2  # 1→0→1 (0 at collision)
+
+# Wave A approaches from left
+offset_a = (1 - progress) * g.cols * 0.4
+wave_a = np.sin((g.cc + offset_a) * 0.08 + t * 2) * 0.5 + 0.5
+
+# Wave B approaches from right
+offset_b = -(1 - progress) * g.cols * 0.4
+wave_b = np.sin((g.cc + offset_b) * 0.08 - t * 2) * 0.5 + 0.5
+
+# Interference peaks at collision
+combined = wave_a * 0.5 + wave_b * 0.5 + np.abs(wave_a - wave_b) * (1 - collision_phase) * 0.5
+```
+
+### 渐进式碎裂
+
+Voronoi 的单元数量随时间增加 —— 视觉上的破碎：
+
+```python
+n_pts = int(8 + progress * 30)  # 8 cells → 38 cells
+# Pre-generate enough points, slice to n_pts
+px = base_x[:n_pts] + np.sin(t * 0.3 + np.arange(n_pts) * 0.7) * (3 + progress * 3)
+```
+
+边缘辉光的宽度也可以随 progress 增加以强调裂纹。
+
+### 熵 / 消耗
+
+干净的几何图案被有机过程吞噬：
+
+```python
+# Geometry fades out
+geo_val = clean_pattern * max(0.05, 1.0 - progress * 0.9)
+
+# Organic process grows in
+rd_val = vf_reaction_diffusion(g, f, t, S) * min(1.0, progress * 1.5)
+
+# Render geometry first, organic on top — organic consumes geometry
+```
+
+### 交错图层进入（渐强）
+
+图层逐一登场，不断累积直至极度密集：
+
+```python
+def layer_strength(enter_t, ramp=1.5):
+    """0.0 until enter_t, ramps to 1.0 over ramp seconds."""
+    return max(0.0, min(1.0, (local - enter_t) / ramp))
+
+# Layer 1: always present
+s1 = layer_strength(0.0)
+# Layer 2: enters at 2s
+s2 = layer_strength(2.0)
+# Layer 3: enters at 4s
+s3 = layer_strength(4.0)
+# ... etc
+
+# Each layer uses a different effect, grid, palette, and blend mode
+# Screen blend between layers so they accumulate light
+```
+
+对于一个 15 秒的渐强场景，7 个图层每 2 秒进入一个效果很好。使用不同的 blend mode（大多数用 screen，能量用 add，最后的高光泛滥用 colordodge）。
+
+## 场景排序
+
+对于多场景的混剪或视频：
+- **在相邻场景之间变换情绪** —— 不要把两个平静的场景放在一起
+- **随机化顺序**，而不是按类型分组 —— 避免产生“特效演示”的感觉
+- **在最强场景处结束** —— 渐强或具有明确回报的事物
+- **以能量开场** —— 在前 2 秒抓住注意力
+
+---
+
+## 场景协议
+
+场景是顶层的创意单元。每个场景都是一个具有自身特效函数、shader 链、feedback 配置和 tone-mapping gamma 的时间受限片段。
+
+### Scene Protocol (v2)
+
+### 函数签名
+
+```python
+def fx_scene_name(r, f, t, S) -> canvas:
+    """
+    Args:
+        r: Renderer instance — access multiple grids via r.get_grid("sm")
+        f: dict of audio/video features, all values normalized to [0, 1]
+        t: time in seconds — local to scene (0.0 at scene start)
+        S: dict for persistent state (particles, rain columns, etc.)
+
+    Returns:
+        canvas: numpy uint8 array, shape (VH, VW, 3) — full pixel frame
+    """
+```
+
+**局部时间约定：** 无论场景在时间轴上出现在哪里，场景函数接收到的 `t` 都从场景第一帧的 `0.0` 开始。渲染循环在调用该函数之前会减去场景的起始时间：
+
+```python
+# In render_clip:
+t_local = fi / FPS - scene_start
+canvas = fx_fn(r, feat, t_local, S)
+```
+
+这使得场景可以在不修改代码的情况下重新排序。计算场景进度的方法如下：
+
+```python
+progress = min(t / scene_duration, 1.0)  # 0→1 over the scene
+```
+
+这取代了场景返回 `(chars, colors)` 元组的 v1 协议。v2 协议让场景完全掌控内部的多 grid 渲染和像素级合成。
+
+### Renderer 类
+
+```python
+class Renderer:
+    def __init__(self):
+        self.grids = {}   # lazy-initialized grid cache
+        self.g = None      # "active" grid (for backward compat)
+        self.S = {}        # persistent state dict
+
+    def get_grid(self, key):
+        """Get or create a GridLayer by size key."""
+        if key not in self.grids:
+            sizes = {"xs": 8, "sm": 10, "md": 16, "lg": 20, "xl": 24, "xxl": 40}
+            self.grids[key] = GridLayer(FONT_PATH, sizes[key])
+        return self.grids[key]
+
+    def set_grid(self, key):
+        """Set active grid (legacy). Prefer get_grid() for multi-grid scenes."""
+        self.g = self.get_grid(key)
+        return self.g
+```
+
+**与 v1 的主要区别**：场景调用 `r.get_grid("sm")`、`r.get_grid("lg")` 等来访问多个 grid。每个 grid 都是延迟初始化并缓存的。对于单 grid 场景，`set_grid()` 方法仍然有效。
+
+### 最小场景（单一 Grid）
+
+```python
+def fx_simple_rings(r, f, t, S):
+    """Single-grid scene: rings with distance-mapped hue."""
+    canvas = _render_vf(r, "md",
+        lambda g, f, t, S: vf_rings(g, f, t, S, n_base=8, spacing_base=3),
+        hf_distance(0.3, 0.02), PAL_STARS, f, t, S, sat=0.85)
+    return canvas
+```
+
+### 标准场景（两个 Grid + 混合）
+
+```python
+def fx_tunnel_ripple(r, f, t, S):
+    """Two-grid scene: tunnel depth exclusion-blended with ripple."""
+    canvas_a = _render_vf(r, "md",
+        lambda g, f, t, S: vf_tunnel(g, f, t, S, speed=5.0, complexity=10) * 1.3,
+        hf_distance(0.55, 0.02), PAL_GREEK, f, t, S, sat=0.7)
+
+    canvas_b = _render_vf(r, "sm",
+        lambda g, f, t, S: vf_ripple(g, f, t, S,
+            sources=[(0.3,0.3), (0.7,0.7), (0.5,0.2)], freq=0.5, damping=0.012) * 1.4,
+        hf_angle(0.1), PAL_STARS, f, t, S, sat=0.8)
+
+    return blend_canvas(canvas_a, canvas_b, "exclusion", 0.8)
+```
+
+### 复杂场景（三个 Grid + 条件触发 + 自定义渲染）
+
+```python
+def fx_rings_explosion(r, f, t, S):
+    """Three-grid scene with particles and conditional kaleidoscope."""
+    # Layer 1: rings
+    canvas_a = _render_vf(r, "sm",
+        lambda g, f, t, S: vf_rings(g, f, t, S, n_base=10, spacing_base=2) * 1.4,
+        lambda g, f, t, S: (g.angle / (2*np.pi) + t * 0.15) % 1.0,
+        PAL_STARS, f, t, S, sat=0.9)
+
+    # Layer 2: vortex on different grid
+    canvas_b = _render_vf(r, "md",
+        lambda g, f, t, S: vf_vortex(g, f, t, S, twist=6.0) * 1.2,
+        hf_time_cycle(0.15), PAL_BLOCKS, f, t, S, sat=0.8)
+
+    result = blend_canvas(canvas_b, canvas_a, "screen", 0.7)
+
+    # Layer 3: particles (custom rendering, not _render_vf)
+    g = r.get_grid("sm")
+    if "px" not in S:
+        S["px"], S["py"], S["vx"], S["vy"], S["life"], S["pch"] = (
+            [], [], [], [], [], [])
+    if f.get("beat", 0) > 0.5:
+        chars = list("\u2605\u2736\u2733\u2738\u2726\u2728*+")
+        for _ in range(int(80 + f.get("rms", 0.3) * 120)):
+            ang = random.uniform(0, 2 * math.pi)
+            sp = random.uniform(1, 10) * (0.5 + f.get("sub_r", 0.3) * 2)
+            S["px"].append(float(g.cols // 2))
+            S["py"].append(float(g.rows // 2))
+            S["vx"].append(math.cos(ang) * sp * 2.5)
+            S["vy"].append(math.sin(ang) * sp)
+            S["life"].append(1.0)
+            S["pch"].append(random.choice(chars))
+
+    # Update + draw particles
+    ch_p = np.full((g.rows, g.cols), " ", dtype="U1")
+    co_p = np.zeros((g.rows, g.cols, 3), dtype=np.uint8)
+    i = 0
+    while i < len(S["px"]):
+        S["px"][i] += S["vx"][i]; S["py"][i] += S["vy"][i]
+        S["vy"][i] += 0.03; S["life"][i] -= 0.02
+        if S["life"][i] <= 0:
+            for k in ("px","py","vx","vy","life","pch"): S[k].pop(i)
+        else:
+            pr, pc = int(S["py"][i]), int(S["px"][i])
+            if 0 <= pr < g.rows and 0 <= pc < g.cols:
+                ch_p[pr, pc] = S["pch"][i]
+                co_p[pr, pc] = hsv2rgb_scalar(
+                    0.08 + (1-S["life"][i])*0.15, 0.95, S["life"][i])
+            i += 1
+
+    canvas_p = g.render(ch_p, co_p)
+    result = blend_canvas(result, canvas_p, "add", 0.8)
+
+    # Conditional kaleidoscope on strong beats
+    if f.get("bdecay", 0) > 0.4:
+        result = sh_kaleidoscope(result.copy(), folds=6)
+
+    return result
+```
+
+### 带有自定义字符渲染的场景（Matrix Rain）
+
+当你需要超越 `_render_vf()` 提供范围的每单元格控制能力时：
+
+```python
+def fx_matrix_layered(r, f, t, S):
+    """Matrix rain blended with tunnel — two grids, screen blend."""
+    # Layer 1: Matrix rain (custom per-column rendering)
+    g = r.get_grid("md")
+    rows, cols = g.rows, g.cols
+    pal = PAL_KATA
+
+    if "ry" not in S or len(S["ry"]) != cols:
+        S["ry"] = np.random.uniform(-rows, rows, cols).astype(np.float32)
+        S["rsp"] = np.random.uniform(0.3, 2.0, cols).astype(np.float32)
+        S["rln"] = np.random.randint(8, 35, cols)
+        S["rch"] = np.random.randint(1, len(pal), (rows, cols))
+
+    speed = 0.6 + f.get("bass", 0.3) * 3
+    if f.get("beat", 0) > 0.5: speed *= 2.5
+    S["ry"] += S["rsp"] * speed
+
+    ch = np.full((rows, cols), " ", dtype="U1")
+    co = np.zeros((rows, cols, 3), dtype=np.uint8)
+    heads = S["ry"].astype(int)
+    for c in range(cols):
+        head = heads[c]
+        for i in range(S["rln"][c]):
+            row = head - i
+            if 0 <= row < rows:
+                fade = 1.0 - i / S["rln"][c]
+                ch[row, c] = pal[S["rch"][row, c] % len(pal)]
+                if i == 0:
+                    v = int(min(255, fade * 300))
+                    co[row, c] = (int(v*0.9), v, int(v*0.9))
+                else:
+                    v = int(fade * 240)
+                    co[row, c] = (int(v*0.1), v, int(v*0.4))
+    canvas_a = g.render(ch, co)
+
+    # Layer 2: Tunnel on sm grid for depth texture
+    canvas_b = _render_vf(r, "sm",
+        lambda g, f, t, S: vf_tunnel(g, f, t, S, speed=5.0, complexity=10),
+        hf_distance(0.3, 0.02), PAL_BLOCKS, f, t, S, sat=0.6)
+
+    return blend_canvas(canvas_a, canvas_b, "screen", 0.5)
+```
+
+---
+
+## 场景表
+
+场景表定义了时间线：何时播放哪个场景，及其相关配置。
+
+### 结构
+
+```python
+SCENES = [
+    {
+        "start": 0.0,           # start time in seconds
+        "end": 3.96,            # end time in seconds
+        "name": "starfield",    # identifier (used for clip filenames)
+        "grid": "sm",           # default grid (for render_clip setup)
+        "fx": fx_starfield,     # scene function reference (must be module-level)
+        "gamma": 0.75,          # tonemap gamma override (default 0.75)
+        "shaders": [            # shader chain (applied after tonemap + feedback)
+            ("bloom", {"thr": 120}),
+            ("vignette", {"s": 0.2}),
+            ("grain", {"amt": 8}),
+        ],
+        "feedback": None,       # feedback buffer config (None = disabled)
+        # "feedback": {"decay": 0.8, "blend": "screen", "opacity": 0.3,
+        #              "transform": "zoom", "transform_amt": 0.02, "hue_shift": 0.02},
+    },
+    {
+        "start": 3.96,
+        "end": 6.58,
+        "name": "matrix_layered",
+        "grid": "md",
+        "fx": fx_matrix_layered,
+        "shaders": [
+            ("crt", {"strength": 0.05}),
+            ("scanlines", {"intensity": 0.12}),
+            ("color_grade", {"tint": (0.7, 1.2, 0.7)}),
+            ("bloom", {"thr": 100}),
+        ],
+        "feedback": {"decay": 0.5, "blend": "add", "opacity": 0.2},
+    },
+    # ... more scenes ...
+]
+```
+
+### 节拍同步的场景剪辑
+
+从音频分析中得出剪辑点：
+
+```python
+# Get beat timestamps
+beats = [fi / FPS for fi in range(N_FRAMES) if features["beat"][fi] > 0.5]
+
+# Group beats into phrase boundaries (every 4-8 beats)
+cuts = [0.0]
+for i in range(0, len(beats), 4):  # cut every 4 beats
+    cuts.append(beats[i])
+cuts.append(DURATION)
+
+# Or use the music's structure: silence gaps, energy changes
+energy = features["rms"]
+# Find timestamps where energy drops significantly -> natural break points
+```
+
+### `render_clip()` —— 渲染循环
+
+此函数将单个场景渲染为一个片段文件：
+
+```python
+def render_clip(seg, features, clip_path):
+    r = Renderer()
+    r.set_grid(seg["grid"])
+    S = r.S
+    random.seed(hash(seg["id"]) + 42)  # deterministic per scene
+
+    # Build shader chain from config
+    chain = ShaderChain()
+    for shader_name, kwargs in seg.get("shaders", []):
+        chain.add(shader_name, **kwargs)
+
+    # Setup feedback buffer
+    fb = None
+    fb_cfg = seg.get("feedback", None)
+    if fb_cfg:
+        fb = FeedbackBuffer()
+
+    fx_fn = seg["fx"]
+
+    # Open ffmpeg pipe
+    cmd = ["ffmpeg", "-y", "-f", "rawvideo", "-pix_fmt", "rgb24",
+           "-s", f"{VW}x{VH}", "-r", str(FPS), "-i", "pipe:0",
+           "-c:v", "libx264", "-preset", "fast", "-crf", "20",
+           "-pix_fmt", "yuv420p", clip_path]
+    stderr_fh = open(clip_path.replace(".mp4", ".log"), "w")
+    pipe = subprocess.Popen(cmd, stdin=subprocess.PIPE,
+                            stdout=subprocess.DEVNULL, stderr=stderr_fh)
+
+    for fi in range(seg["frame_start"], seg["frame_end"]):
+        t = fi / FPS
+        feat = {k: float(features[k][fi]) for k in features}
+
+        # 1. Scene renders canvas
+        canvas = fx_fn(r, feat, t, S)
+
+        # 2. Tonemap normalizes brightness
+        canvas = tonemap(canvas, gamma=seg.get("gamma", 0.75))
+
+        # 3. Feedback adds temporal recursion
+        if fb and fb_cfg:
+            canvas = fb.apply(canvas, **{k: fb_cfg[k] for k in fb_cfg})
+
+        # 4. Shader chain adds post-processing
+        canvas = chain.apply(canvas, f=feat, t=t)
+
+        pipe.stdin.write(canvas.tobytes())
+
+    pipe.stdin.close(); pipe.wait(); stderr_fh.close()
+```
+
+### 从场景表构建片段
+
+```python
+segments = []
+for i, scene in enumerate(SCENES):
+    segments.append({
+        "id": f"s{i:02d}_{scene['name']}",
+        "name": scene["name"],
+        "grid": scene["grid"],
+        "fx": scene["fx"],
+        "shaders": scene.get("shaders", []),
+        "feedback": scene.get("feedback", None),
+        "gamma": scene.get("gamma", 0.75),
+        "frame_start": int(scene["start"] * FPS),
+        "frame_end": int(scene["end"] * FPS),
+    })
+```
+
+### 并行渲染
+
+场景是分发到进程池的独立单元：
+
+```python
+from concurrent.futures import ProcessPoolExecutor, as_completed
+
+with ProcessPoolExecutor(max_workers=N_WORKERS) as pool:
+    futures = {
+        pool.submit(render_clip, seg, features, clip_path): seg["id"]
+        for seg, clip_path in zip(segments, clip_paths)
+    }
+    for fut in as_completed(futures):
+        try:
+            fut.result()
+        except Exception as e:
+            log(f"ERROR {futures[fut]}: {e}")
+```
+
+**序列化限制**：`ProcessPoolExecutor` 通过 pickle 序列化参数。模块级函数可以被 pickle；lambda 和闭包则不行。所有的 `fx_*` 场景函数必须在模块级别定义，不能作为闭包或类方法。
+
+### 测试帧模式
+
+在特定时间戳渲染单帧，无需完整渲染即可验证视觉效果：
+
+```python
+if args.test_frame >= 0:
+    fi = min(int(args.test_frame * FPS), N_FRAMES - 1)
+    t = fi / FPS
+    feat = {k: float(features[k][fi]) for k in features}
+    scene = next(sc for sc in reversed(SCENES) if t >= sc["start"])
+    r = Renderer()
+    r.set_grid(scene["grid"])
+    canvas = scene["fx"](r, feat, t, r.S)
+    canvas = tonemap(canvas, gamma=scene.get("gamma", 0.75))
+    chain = ShaderChain()
+    for sn, kw in scene.get("shaders", []):
+        chain.add(sn, **kw)
+    canvas = chain.apply(canvas, f=feat, t=t)
+    Image.fromarray(canvas).save(f"test_{args.test_frame:.1f}s.png")
+    print(f"Mean brightness: {canvas.astype(float).mean():.1f}")
+```
+
+CLI: `python reel.py --test-frame 10.0`
+
+---
+
+## 场景设计清单
+
+对于每个场景：
+
+1. **选择 2-3 种 grid 尺寸** —— 不同的比例会产生干涉
+2. **为每个图层选择不同的 value field** —— 不要在每个 grid 上使用相同的特效
+3. **为每个图层选择不同的 hue field** —— 或者至少使用不同的色调偏移
+4. **为每个图层选择不同的调色板** —— 将 PAL_RUNE 与 PAL_BLOCKS 混合看起来与 PAL_RUNE 搭配 PAL_DENSE 截然不同
+5. **选择与能量相匹配的 blend mode** —— screen 适合明亮，difference 适合迷幻，exclusion 适合微妙
+6. **在节拍上添加条件特效** —— kaleidoscope, mirror, glitch
+7. **配置 feedback** 以获得拖尾/递归外观 —— 或者设为 None 以获得干净的切换
+8. **设置 gamma**（如果使用破坏性 shader，如 solarize, posterize）
+9. **在完全渲染前，使用 --test-frame 在场景中点进行测试**
+
+---
+
+## 场景示例
+
+复杂度不断增加、可直接复制粘贴的场景函数。每一个都是完整、可运行的 v2 场景函数，并返回像素画布。有关场景协议请参阅上面的场景协议部分，有关 blend mode 和 tonemap 请参阅 `composition.md`。
+
+---
+
+### 最小化 —— 单一 Grid，单一特效
+
+### 呼吸的等离子体
+
+一个 grid，一个 value field，一个 hue field。可能存在的最简单场景。
+
+```python
+def fx_breathing_plasma(r, f, t, S):
+    """Plasma field with time-cycling hue. Audio modulates brightness."""
+    canvas = _render_vf(r, "md",
+        lambda g, f, t, S: vf_plasma(g, f, t, S) * 1.3,
+        hf_time_cycle(0.08), PAL_DENSE, f, t, S, sat=0.8)
+    return canvas
+```
+
+### 反应扩散珊瑚
+
+单一 grid，基于模拟的 field。随时间有机演变。
+
+```python
+def fx_coral(r, f, t, S):
+    """Gray-Scott reaction-diffusion — coral branching pattern.
+    Slow-evolving, organic. Best for ambient/chill sections."""
+    canvas = _render_vf(r, "sm",
+        lambda g, f, t, S: vf_reaction_diffusion(g, f, t, S,
+            feed=0.037, kill=0.060, steps_per_frame=6, init_mode="center"),
+        hf_distance(0.55, 0.015), PAL_DOTS, f, t, S, sat=0.7)
+    return canvas
+```
+
+### SDF 几何体
+
+由 SDF 构成的几何形状。干净、精确、图像化。
+
+```python
+def fx_sdf_rings(r, f, t, S):
+    """Concentric SDF rings with smooth pulsing."""
+    def val_fn(g, f, t, S):
+        d1 = sdf_ring(g, radius=0.15 + f.get("bass", 0.3) * 0.05, thickness=0.015)
+        d2 = sdf_ring(g, radius=0.25 + f.get("mid", 0.3) * 0.05, thickness=0.012)
+        d3 = sdf_ring(g, radius=0.35 + f.get("hi", 0.3) * 0.04, thickness=0.010)
+        combined = sdf_smooth_union(sdf_smooth_union(d1, d2, 0.05), d3, 0.05)
+        return sdf_glow(combined, falloff=0.08) * (0.5 + f.get("rms", 0.3) * 0.8)
+    canvas = _render_vf(r, "md", val_fn, hf_angle(0.0), PAL_STARS, f, t, S, sat=0.85)
+    return canvas
+```
+
+---
+
+### 标准 —— 两个 Grid + 混合
+
+### 穿越噪声的隧道
+
+不同密度的两个 grid，使用 screen 混合。精细的噪声纹理透过粗糙的隧道字符显现出来。
+
+```python
+def fx_tunnel_noise(r, f, t, S):
+    """Tunnel depth on md grid + fBM noise on sm grid, screen blended."""
+    canvas_a = _render_vf(r, "md",
+        lambda g, f, t, S: vf_tunnel(g, f, t, S, speed=4.0, complexity=8) * 1.2,
+        hf_distance(0.5, 0.02), PAL_BLOCKS, f, t, S, sat=0.7)
+
+    canvas_b = _render_vf(r, "sm",
+        lambda g, f, t, S: vf_fbm(g, f, t, S, octaves=4, freq=0.05, speed=0.15) * 1.3,
+        hf_time_cycle(0.06), PAL_RUNE, f, t, S, sat=0.6)
+
+    return blend_canvas(canvas_a, canvas_b, "screen", 0.7)
+```
+
+### Voronoi 单元 + 螺旋覆盖
+
+Voronoi 单元边缘叠加螺旋臂图案。
+
+```python
+def fx_voronoi_spiral(r, f, t, S):
+    """Voronoi edge detection on md + logarithmic spiral on lg."""
+    canvas_a = _render_vf(r, "md",
+        lambda g, f, t, S: vf_voronoi(g, f, t, S,
+            n_cells=15, mode="edge", edge_width=2.0, speed=0.4),
+        hf_angle(0.2), PAL_CIRCUIT, f, t, S, sat=0.75)
+
+    canvas_b = _render_vf(r, "lg",
+        lambda g, f, t, S: vf_spiral(g, f, t, S, n_arms=4, tightness=3.0) * 1.2,
+        hf_distance(0.1, 0.03), PAL_BLOCKS, f, t, S, sat=0.9)
+
+    return blend_canvas(canvas_a, canvas_b, "exclusion", 0.6)
+```
+
+### 域扭曲的 fBM
+
+两层相同的 fBM，其中一层经过 domain-warp 处理，通过 difference 混合产生迷幻的有机纹理。
+
+```python
+def fx_organic_warp(r, f, t, S):
+    """Clean fBM vs domain-warped fBM, difference blended."""
+    canvas_a = _render_vf(r, "sm",
+        lambda g, f, t, S: vf_fbm(g, f, t, S, octaves=5, freq=0.04, speed=0.1),
+        hf_plasma(0.2), PAL_DENSE, f, t, S, sat=0.6)
+
+    canvas_b = _render_vf(r, "md",
+        lambda g, f, t, S: vf_domain_warp(g, f, t, S,
+            warp_strength=20.0, freq=0.05, speed=0.15),
+        hf_time_cycle(0.05), PAL_BRAILLE, f, t, S, sat=0.7)
+
+    return blend_canvas(canvas_a, canvas_b, "difference", 0.7)
+```
+
+---
+
+### 复杂 —— 三个 Grid + 条件触发 + Feedback
+
+### 迷幻大教堂
+
+包含节拍触发 kaleidoscope 和 feedback zoom tunnel 的三重 grid 构图。视觉上最复杂的图案。
+
+```python
+def fx_cathedral(r, f, t, S):
+    """Three-layer cathedral: interference + rings + noise, kaleidoscope on beat,
+    feedback zoom tunnel."""
+    # Layer 1: interference pattern on sm grid
+    canvas_a = _render_vf(r, "sm",
+        lambda g, f, t, S: vf_interference(g, f, t, S, n_waves=7) * 1.3,
+        hf_angle(0.0), PAL_MATH, f, t, S, sat=0.8)
+
+    # Layer 2: pulsing rings on md grid
+    canvas_b = _render_vf(r, "md",
+        lambda g, f, t, S: vf_rings(g, f, t, S, n_base=10, spacing_base=3) * 1.4,
+        hf_distance(0.3, 0.02), PAL_STARS, f, t, S, sat=0.9)
+
+    # Layer