ai-agent-book 精选快照（<2MB 代码与文档，来自 github.com/bojieli/ai-agent-book）

chapter5/video-edit/blender_editor.py

@@ -0,0 +1,210 @@
+"""
+Blender Python API（bpy）剪辑执行层 —— 实验 5-6 的核心。
+
+书中方案强调"代码生成"：Proposer Agent 不去点 GUI，而是**生成一段调用
+Blender Python API 的脚本**，每个编辑操作（导入 / 裁剪 / 字幕 / 变速 / 渲染）
+对应一个清晰的函数调用，再用 `blender --background --python edit.py` 无头执行。
+
+本模块两个出口：
+  generate_bpy_script(source, plan, out_video) -> str
+      纯字符串生成，**不依赖 bpy**，任何机器都能产出这段脚本（体现代码生成能力，
+      可人工核对，或拷到装了 Blender 的机器上执行）。
+  render_with_blender(source, plan, out_video, script_path) -> str
+      若本机 `blender` 可执行，写出脚本并无头渲染产出成片；否则抛错由调用方回退。
+
+裁剪基于 Blender 视频序列编辑器（VSE）：new_movie / new_sound 导入素材，
+frame_offset_start + frame_final_duration 完成裁剪，TEXT / SPEED 特效条叠加，
+FFMPEG(H.264+AAC) 容器渲染。API 面向 Blender 3.x / 4.x。
+"""
+import os
+import shutil
+import subprocess
+
+
+def blender_available() -> bool:
+    """本机是否有 blender 可执行文件（决定 backend=auto 时走 Blender 还是 ffmpeg）。"""
+    return shutil.which("blender") is not None
+
+
+# 生成的 bpy 脚本模板。占位符全部通过 repr() 注入，保证是合法的 Python 字面量。
+_BPY_TEMPLATE = '''"""
+本文件由 blender_editor.generate_bpy_script() 自动生成（实验 5-6）。
+执行：blender --background --python edit.py
+它把一条剪辑计划翻译成 Blender 视频序列编辑器（VSE）的 API 调用序列。
+"""
+import os
+import bpy
+
+SRC = {src}
+OUT = {out}
+FPS = {fps}
+START = {start}       # 目标片段起点（秒）
+END = {end}           # 目标片段终点（秒）
+SUBTITLE = {subtitle} # None 或字幕文本
+SLOWMO = {slowmo}     # None 或放慢倍率（factor>1 表示放慢 factor 倍）
+
+scene = bpy.context.scene
+scene.render.fps = FPS
+scene.render.fps_base = 1.0
+
+# 清掉可能存在的旧序列，保证幂等
+if scene.sequence_editor:
+    bpy.ops.sequencer.select_all(action='SELECT')
+    bpy.ops.sequencer.delete()
+se = scene.sequence_editor_create()
+
+start_frame = int(round(START * FPS))
+dur_frames = max(1, int(round((END - START) * FPS)))
+
+# 1) 导入影片 + 音轨（new_sound 在无音轨素材上会抛 RuntimeError，忽略即可）
+# frame_offset_start trims the strip's visible left edge as well as advancing
+# into the source.  Start the raw strip earlier by the same amount so the
+# trimmed clip's final visible start remains at output frame 1.
+movie = se.sequences.new_movie(
+    name="clip", filepath=SRC, channel=1, frame_start=1 - start_frame
+)
+try:
+    sound = se.sequences.new_sound(
+        name="audio", filepath=SRC, channel=2, frame_start=1 - start_frame
+    )
+except RuntimeError:
+    sound = None
+
+# 2) 裁剪 [START, END]：偏移掉片头，再固定成片时长
+for strip in (movie, sound):
+    if strip is None:
+        continue
+    strip.frame_offset_start = start_frame
+    strip.frame_final_duration = dur_frames
+
+top_channel = 3
+
+# 3) 慢动作：SPEED 特效条（MULTIPLY 模式，speed_factor = 1/倍率）
+if SLOWMO:
+    speed = se.sequences.new_effect(
+        name="slowmo", type='SPEED', channel=top_channel,
+        frame_start=1, frame_end=1 + dur_frames, seq1=movie,
+    )
+    speed.use_default_fade = False
+    speed.speed_control = 'MULTIPLY'
+    speed.speed_factor = 1.0 / SLOWMO
+    top_channel += 1
+    # 放慢后成片总帧数按倍率拉长
+    render_dur = int(round(dur_frames * SLOWMO))
+    movie.frame_final_duration = render_dur
+else:
+    render_dur = dur_frames
+
+# 4) 字幕：TEXT 特效条，底部居中带半透明底框
+if SUBTITLE:
+    txt = se.sequences.new_effect(
+        name="subtitle", type='TEXT', channel=top_channel,
+        frame_start=1, frame_end=1 + render_dur,
+    )
+    txt.text = SUBTITLE
+    txt.font_size = 100
+    txt.location = (0.5, 0.12)
+    txt.align_x = 'CENTER'
+    txt.align_y = 'BOTTOM'
+    txt.use_box = True
+    txt.box_color = (0.0, 0.0, 0.0, 0.6)
+
+# 5) 渲染范围 + 输出为 mp4(H.264+AAC)
+scene.frame_start = 1
+scene.frame_end = render_dur
+
+r = scene.render
+r.image_settings.file_format = 'FFMPEG'
+r.ffmpeg.format = 'MPEG4'
+r.ffmpeg.codec = 'H264'
+r.ffmpeg.audio_codec = 'AAC'
+r.filepath = OUT
+os.makedirs(os.path.dirname(OUT) or ".", exist_ok=True)
+
+bpy.ops.render.render(animation=True)
+print("BLENDER_RENDER_DONE", OUT)
+'''
+
+
+def _plan_fields(plan: dict):
+    """从剪辑计划里抽出 bpy 脚本需要的字段。"""
+    start, end = float(plan["start"]), float(plan["end"])
+    if end <= start:
+        raise ValueError(f"剪辑区间非法：start={start} >= end={end}")
+    effects = plan.get("effects", []) or []
+    subtitle = None
+    slowmo = None
+    for eff in effects:
+        etype = eff.get("type")
+        if etype == "subtitle":
+            subtitle = eff.get("text", "")
+        elif etype == "slowmo":
+            # Skip null factor like non-positive.
+            raw = eff.get("factor", 2.0)
+            if raw is None:
+                continue
+            factor = float(raw)
+            if factor <= 0:
+                continue
+            slowmo = factor
+    return start, end, subtitle, slowmo
+
+
+def generate_bpy_script(source: str, plan: dict, out_video: str, fps: int = 30) -> str:
+    """把剪辑计划渲染成一段可执行的 Blender Python(bpy) 脚本文本（不依赖 bpy）。"""
+    start, end, subtitle, slowmo = _plan_fields(plan)
+    return _BPY_TEMPLATE.format(
+        src=repr(os.path.abspath(source)),
+        out=repr(os.path.abspath(out_video)),
+        fps=int(fps),
+        start=repr(start),
+        end=repr(end),
+        subtitle=repr(subtitle),
+        slowmo=repr(slowmo),
+    )
+
+
+def write_bpy_script(source: str, plan: dict, out_video: str,
+                     script_path: str, fps: int = 30) -> str:
+    """生成 bpy 脚本并落盘（无论用哪个后端都会产出，作为代码生成产物）。"""
+    script = generate_bpy_script(source, plan, out_video, fps=fps)
+    os.makedirs(os.path.dirname(script_path) or ".", exist_ok=True)
+    with open(script_path, "w") as f:
+        f.write(script)
+    return script_path
+
+
+def render_with_blender(source: str, plan: dict, out_video: str,
+                        script_path: str, fps: int = 30) -> str:
+    """写出 bpy 脚本并用 `blender --background --python` 无头执行，产出成片。"""
+    if not blender_available():
+        raise RuntimeError(
+            "指定用 Blender 后端，但未找到 blender 可执行文件。\n"
+            "  安装后确保 `blender --version` 可用：https://www.blender.org/download/\n"
+            "  或改用 --backend ffmpeg。"
+        )
+    write_bpy_script(source, plan, out_video, script_path, fps=fps)
+    os.makedirs(os.path.dirname(out_video) or ".", exist_ok=True)
+    proc = subprocess.run(
+        ["blender", "--background", "--python", script_path],
+        capture_output=True, text=True,
+    )
+    if proc.returncode != 0 or not os.path.exists(out_video):
+        tail = "\n".join(proc.stderr.strip().splitlines()[-12:])
+        raise RuntimeError(
+            f"Blender 渲染失败（exit={proc.returncode}）：\n{tail}\n"
+            f"  可人工检查生成的脚本：{script_path}"
+        )
+    return out_video
+
+
+if __name__ == "__main__":
+    # 零依赖自检：打印一段"含裁剪 + 字幕"的示例 bpy 脚本（可 py_compile 校验其语法）。
+    demo_plan = {
+        "start": 16.0,
+        "end": 28.0,
+        "effects": [{"type": "subtitle", "text": "SURFING"}],
+    }
+    print("# blender available:", blender_available())
+    print("# ---- generated edit.py ----")
+    print(generate_bpy_script("output/source.mp4", demo_plan, "output/final.mp4"))