name: video-transcript-txt description: 将一个或多个本地视频转写为带每段开始和结束时间的整理版 TXT。当用户要求视频转文字、视频转写、提取视频文本或字幕、批量生成带时间戳 TXT、整理视频口述内容、统计视频处理耗时时使用。通过 uv、ffmpeg/ffprobe 和 openai-whisper 处理；中间文件写入系统临时目录并自动清理，永不删除源视频。 metadata: short-description: 视频转写为带起止时间的 TXT

视频转写为 TXT

将完整下载的本地视频转写为带逐段起止时间的纯文本文件。单视频生成一个 .txt；多视频时每个视频独立生成一个 .txt，并在全部完成后汇总总视频时长与实际处理总耗时。

输入与输出

• 输入：一个或多个本地视频文件的绝对路径。
• 默认输出：每个视频同目录下的 <视频文件名>_整理版.txt。
• 每段格式：［HH:MM:SS.mmm - HH:MM:SS.mmm］文本
• 输出已存在时默认停止；只有用户明确允许覆盖后才传 --force。
• 多视频完成后不生成额外汇总文件；只在回复中汇报汇总结果。

硬性规则

1. 不删除、不移动、不修改源视频。
2. 拒绝处理 .downloading、.part、.partial 等未完成下载文件。
3. 每个视频最终只保留一个 TXT；不得在视频目录生成或保留 WAV、JSON、SRT、VTT、TSV、原始 ASR TXT。
4. 所有 Whisper 中间输出必须进入系统临时目录，成功或失败都要清理。
5. 不编造说话人，不根据猜测强行修改人名、数字、剂量或专业术语。
6. 用户未指定语言时默认中文 zh；用户明确指定时使用其语言。
7. 运行前检查 uv、ffmpeg、ffprobe 是否可用。
8. 多视频并行必须限流；默认最多同时处理 2 个视频，资源充足且视频较短时最多 3 个。

单视频执行

uv run ~/.claude/skills/video-transcript-txt/scripts/video_transcript_txt.py \
  "/absolute/path/to/video.mp4"

指定输出：

uv run ~/.claude/skills/video-transcript-txt/scripts/video_transcript_txt.py \
  "/absolute/path/to/video.mp4" \
  --output "/absolute/path/to/result.txt"

用户已明确允许覆盖时：

uv run ~/.claude/skills/video-transcript-txt/scripts/video_transcript_txt.py \
  "/absolute/path/to/video.mp4" \
  --force

可选参数：

• --model：Whisper 模型，默认 small。
• --language：语言代码，默认 zh。
• --model-dir：模型缓存目录，默认 ~/.cache/whisper。
• --force：覆盖已存在的最终 TXT，仅在用户明确允许时使用。

单视频工作流

1. 校验输入文件、输出后缀和依赖工具。
2. 使用 ffprobe 获取视频时长。
3. 创建系统临时目录。
4. 用 uv run --with openai-whisper whisper 转写，所有格式输出到临时目录。
5. 读取临时 JSON 中的 segments。
6. 将有效分段按时间顺序写成唯一最终 TXT。
7. 原子替换最终输出并清理临时目录。
8. 汇报最终 TXT 绝对路径、有效段落数量、视频时长、单视频处理耗时。
9. 读取终端中的 SUMMARY_JSON: 行作为机器可读摘要。

多视频并行工作流

当用户提供多个视频时，由主 agent 统筹，多名子 agent 分批处理：

1. 主 agent 解析并列出全部视频绝对路径。
2. 主 agent 先做批量预检查：路径存在、普通文件、未命中未完成下载后缀、默认输出路径不冲突、输出不存在或已获覆盖授权。
3. 如果输出已存在且用户未授权覆盖，先询问用户选择：跳过已有输出、允许覆盖、或停止批处理。
4. 记录批处理开始时间。
5. 按并发上限分批派发子 agent：每个子 agent 只处理一个视频，只调用单视频脚本。
6. 环境不支持子 agent 或并行时，降级为串行处理；仍执行同样的汇总。
7. 单个视频失败不阻塞其他视频；失败原因进入最终汇总。
8. 所有视频完成后记录结束时间，计算实际处理总耗时。
9. 汇总成功数、失败数、每个 TXT 路径、每个视频时长、每个单视频处理耗时、总视频时长和实际处理总耗时。

子 agent 回传字段

每个子 agent 完成后必须回传：

• 源视频绝对路径。
• 输出 TXT 绝对路径。
• status：success 或 error。
• 失败原因；成功时为空。
• 视频时长秒数。
• 有效段落数。
• 单视频实际处理耗时秒数。
• 使用的模型和语言。

优先从脚本输出的 SUMMARY_JSON: 解析这些字段；解析失败时再从中文输出中提取，并说明摘要解析失败。

总时长汇报规范

用户说“总时长”但未明确含义时，默认同时汇报两类时长：

• 总视频时长：所有成功处理视频的媒体时长之和，来自 ffprobe。
• 实际处理总耗时：从主 agent 开始派发第一批任务到所有任务结束的墙钟时间。

多视频并行时，实际处理总耗时通常小于各单视频处理耗时之和；最终回复必须说明这一点。

汇总模板：

处理完成。

成功：3 个
失败：1 个

成功文件：
1. /path/a_整理版.txt
   视频时长：00:10:12.350
   处理耗时：00:03:05.120
   段落数：96

失败文件：
1. /path/c.mp4
   原因：输出已存在，未获覆盖授权

汇总：
总视频时长：00:40:00.330
实际处理总耗时：00:06:28.500
说明：因为多个视频并行处理，实际处理总耗时不是各单视频处理耗时的简单相加。

停机条件

出现以下情况时停止对应视频，不生成误导性结果：

• 输入不存在或不是普通文件。
• 输入是未完成下载文件。
• 输出不是 .txt。
• 输出已存在且未明确允许覆盖。
• uv、ffmpeg 或 ffprobe 不可用。
• Whisper 失败、JSON 缺失或没有有效文本段。

依赖缺失通常影响全部视频，应停止整批处理并提示用户修复环境。单个输入或单个转写失败只停止该视频，其余视频继续。

反例黑名单

不要做以下事情：

• 不要把多个视频路径一次性传给单视频脚本。
• 不要无限制启动 agent；默认并发 2，最多 3。
• 不要在未获明确授权时传 --force。
• 不要在视频目录留下 Whisper 中间文件或批量汇总 JSON/TXT。
• 不要把失败视频计入“成功处理的总视频时长”，除非回复中明确单独说明。
• 不要根据上下文猜测说话人、人名、数字、剂量或专业术语。
• 不要把“实际处理总耗时”说成“总视频时长”；两者必须分开标注。

这个视频转文字工具质量不错，文档写得清楚详细，脚本运行稳定可靠，能很好地保护源文件安全。使用起来比较简单，单个或多个视频都能处理。需要注意的是它依赖 ffmpeg 等外部工具，运行时需要等待转写过程，整体体验较好但对环境配置有一定要求。