---
description: "Agent 读视频：中层跑 scripts/video_read.py，给下载脚本的文件夹或一个视频文件，出关键帧（3 分钟以内按画面切换，更长的均匀撒点）、编号联系图、转写和 read.json；图文出编号拼图；底层只记 ffmpeg 抽帧、测画面切换、测音量、拼图的坑，转写见转录音频"
---

# 阅读视频

把视频变成 AI 能读的两样东西：一张关键帧联系图看画面，一份转写读声音。图文帖的图也拼成带编号的大图，一次看完。分两层：

- **中层**：跑 [`scripts/video_read.py`](../scripts/video_read.py)，一般用这个
- **底层**：抽帧、测音量、拼图的坑写在[本页末尾](#raw)，转写接口见[转录音频](transcribe.md)

## 中层：脚本 { #script }

```bash
python3 scripts/video_read.py <文件夹或视频文件>...
```

- **输入**：[解析分享链接](share-link/index.md)的平台脚本取下来的文件夹，读 `meta.json` 的 `parts`，结果写进同一个文件夹；也可以直接给视频文件，结果写进旁边的 `<文件名>_read/`。临时文件也写在这个文件夹里，不用系统的临时目录
- **要 ffmpeg 和 ffprobe**，转写要先载入 `MY_API_KEY`，见 [Agent 基础能力 · 用法](../index.md#usage)。其余只用 Python 标准库
- **输出**：
    - `keyframes/01.jpg`…：单帧，长边最多 1920，界面上的字、代码在这里读
    - `keyframes/contact_sheet_01.jpg`…：12 帧一张，格子左上角的序号就是单帧的序号；按行从左往右读，竖屏视频格子也是竖的
    - `keyframes.json`：每帧的编号（`KF-P01-03`）、分P、时间、在哪张联系图第几行第几列；按画面切换取的另有 `scene_score`
    - **怎么取帧**：3 分钟以内的视频按画面切换取，挑变化最大的，最多 24 帧，每帧取在下一个切换之前：短教程常把提示词、设置页闪几秒，还是一个字一个字打出来的，均匀撒点会漏掉，切换后马上取又只拍到一半。超过 6 秒没有切换的空档（录屏里慢慢滚动的对话）每 4 秒补一帧。更长的视频均匀撒 12 帧，每P至少一帧
    - `images_sheet_01.jpg`…：有图的帖子，12 张一张拼图，每张左上角标着在 `images/` 里的序号
    - `transcripts/p01.txt`、`.srt`、`.json`：转写，一句一行；`.json` 里有词级时间戳和说话人
    - `read.json`：每P的时长、尺寸、最大音量、字幕和转写字数，全片每分钟字数、花费、`warnings`
- **怎么读**：先看联系图和 `read.json`，再按需打开单帧和转写。转写会听错专有名词、平台名，拿画面上的字核对。`warnings` 里出现「little speech for the length」，是 3 分钟以上的视频每分钟不到 80 字，内容多半在 PPT、板书、界面演示里，只凭转写写不全，要看关键帧
- **参数**：`--transcribe auto` 是默认，只转没有字幕、有声音的P；`always` 有字幕也转，`never` 不转。`--mode scenes` 或 `uniform` 指定取帧方式，`--frames 36` 改帧数，超过 12 帧就多拼几张联系图；`--at 20,22.5` 在这几个时间点补帧，第 2P 写 `2@30`，补的帧照样进 `keyframes.json`，编号会重排；`--language zh` 指定语言；`--force` 重做取帧和拼图，不重新转写；`--retranscribe` 重新转写，再扣一次钱
- **花费**：转写约 0.1 美元一小时，`read.json` 的 `cost` 是各次返回的 `usage.cost` 加起来；抽帧、拼图不花钱。已有的输出不重做，重跑不扣钱
- **静音不送转写**：最大音量低于 -50 dB 的音轨会跳过，它照样计费，转回来也是空的。纯音乐会送，转出来是空的，`warnings` 会提示

## 底层：自己调 ffmpeg 时的坑 { #raw }

- **找画面切换**：`ffmpeg -i <视频> -an -vf "scale=320:-2,select='gt(scene,0.15)',metadata=print:file=-" -f null -`，stdout 里每个切换有 `pts_time` 和 `lavfi.scene_score`，缩小再算快得多，45 秒的竖屏 4 秒算完。提示词卡、换页这类整屏换掉的分数接近 1
- **`-ss` 放在 `-i` 前面**：放后面会从片头解码到每个时间点，50 分钟的课抽 12 帧要 21 分钟，放前面 1.6 秒，画面逐像素一样
- **先测有没有声音**：`ffmpeg -i <视频> -vn -af volumedetect -f null -`，看 stderr 里的 `max_volume`；静音是 -91 dB
- **尺寸不一的图别直接拼**：图片序列直接接 `tile`，碰到尺寸不同的图会悄悄截断，不报错。小红书一帖里图片尺寸常常混着，要先把每张缩放补边到同一格子大小，再拼
- **竖屏用竖格子**：短视频平台多是竖屏，按横屏格子拼会缩成一条
- **转写**：先抽成 16 kHz 单声道 32 kbps 的 mp3，长视频每 10 分钟切一块分别请求，接口和时间戳的坑见[转录音频](transcribe.md)