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

chapter5/video-edit/ffmpeg_utils.py

@@ -0,0 +1,103 @@
+"""
+ffmpeg / ffprobe 薄封装：所有对外部进程的调用都集中在这里，统一做错误检查。
+
+设计要点：
+  - run() 捕获非零退出码并抛出带 stderr 的清晰异常（而非让 traceback 泄漏）；
+  - 提供 probe_duration / probe_streams，供 Reviewer 与验证环节读取成片信息；
+  - extract_frame 把某一时间点抽成一张 PNG（缩放到 512 宽以节省 Vision token）。
+"""
+import json
+import os
+import shutil
+import subprocess
+
+# macOS 自带字体；换平台时改这里即可（Linux 常见 DejaVuSans.ttf）。
+FONT_CANDIDATES = [
+    "/System/Library/Fonts/Supplemental/Arial.ttf",
+    "/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf",
+    "/Library/Fonts/Arial.ttf",
+]
+
+
+def find_font() -> str:
+    for p in FONT_CANDIDATES:
+        if os.path.exists(p):
+            return p
+    return ""  # drawtext 会退化为默认字体
+
+
+def ensure_ffmpeg():
+    """启动前自检：ffmpeg / ffprobe 是否可用，给出清晰中文报错。"""
+    for tool in ("ffmpeg", "ffprobe"):
+        if shutil.which(tool) is None:
+            raise RuntimeError(
+                f"未找到 {tool}，本项目用 ffmpeg 完成实际剪辑。\n"
+                f"  macOS: brew install ffmpeg\n"
+                f"  Ubuntu: sudo apt install ffmpeg"
+            )
+
+
+def run(cmd, desc="ffmpeg 命令"):
+    """执行命令，失败时抛出带 stderr 尾部的异常。"""
+    proc = subprocess.run(cmd, capture_output=True, text=True)
+    if proc.returncode != 0:
+        tail = "\n".join(proc.stderr.strip().splitlines()[-8:])
+        raise RuntimeError(f"{desc} 执行失败（exit={proc.returncode}）：\n{tail}")
+    return proc
+
+
+def probe_duration(path: str) -> float:
+    """返回视频时长（秒）。文件缺少时长元数据时 ffprobe 输出 N/A，给出清晰报错。"""
+    proc = run(
+        ["ffprobe", "-v", "error", "-show_entries", "format=duration",
+         "-of", "default=noprint_wrappers=1:nokey=1", path],
+        desc="ffprobe 读取时长",
+    )
+    out = proc.stdout.strip()
+    if not out or out == "N/A":
+        raise RuntimeError(f"ffprobe 无法读取时长（文件缺少时长元数据或不是音视频文件）：{path}")
+    return float(out)
+
+
+def probe_streams(path: str) -> dict:
+    """返回 ffprobe 的 JSON（format + streams），用于打印成片信息。"""
+    proc = run(
+        ["ffprobe", "-v", "error", "-show_format", "-show_streams",
+         "-of", "json", path],
+        desc="ffprobe 读取流信息",
+    )
+    return json.loads(proc.stdout)
+
+
+def format_probe(path: str) -> str:
+    """把成片信息格式化成一行行的人类可读文本（用于验证输出）。"""
+    info = probe_streams(path)
+    fmt = info.get("format", {})
+    lines = [
+        f"  文件: {os.path.basename(path)}",
+        f"  时长: {float(fmt.get('duration', 0)):.2f}s",
+        f"  容器: {fmt.get('format_name', '?')}",
+        f"  大小: {int(fmt.get('size', 0)) / 1024:.1f} KB",
+    ]
+    for s in info.get("streams", []):
+        if s.get("codec_type") == "video":
+            lines.append(
+                f"  视频流: {s.get('codec_name')} {s.get('width')}x{s.get('height')} "
+                f"@ {s.get('r_frame_rate')} fps"
+            )
+        elif s.get("codec_type") == "audio":
+            lines.append(
+                f"  音频流: {s.get('codec_name')} {s.get('sample_rate')}Hz "
+                f"{s.get('channels')}ch"
+            )
+    return "\n".join(lines)
+
+
+def extract_frame(video: str, t: float, out_png: str, width: int = 512):
+    """抽取 t 秒处的一帧，缩放到 width 宽存为 PNG。"""
+    run(
+        ["ffmpeg", "-y", "-ss", f"{t:.3f}", "-i", video,
+         "-frames:v", "1", "-vf", f"scale={width}:-1", out_png],
+        desc=f"抽帧 t={t:.1f}s",
+    )
+    return out_png