ishenwei/atlas

Fork 0

Files

admin 44110a0ccf manifest.json里extract audio, transcribe audio 共用一条记录

2026-09-17 08:49:16 +08:00

23 KiB

Raw Blame History

SynthMind - 视频音频提取与转录工具

将视频文件转换为文字稿的自动化工具链，为后续 AI 内容分析与总结提供数据基础。

流水线：视频文件 → MP3 音频 → TXT 文字稿 → （后续 AI 分析）

功能特性

通用特性

✅ 支持单文件或递归扫描目录
✅ 完善的断点续传：中断后重新运行自动跳过已完成项
✅ JSON manifest 进度追踪，两个脚本共享同一文件
✅ 失败自动记录 + 重试机制（--retry-failed）
✅ 状态查询（--status）实时查看进度
✅ 完全支持含空格、中文的文件名
✅ 详细的时间戳日志

extract_audio.py 特性

使用 FFmpeg 提取音频：MP3 / 64kbps / 22050Hz / 单声道（语音场景优化，体积小）
支持视频切分模式：超大视频按时长切分为多段分别处理
支持多种输入格式：.mp4/.mkv/.avi/.mov/.flv/.wmv/.webm/.m4v

transcribe_audio.py 特性

基于 openai-whisper 命令行工具
支持 4 种模型：tiny / base / small / medium（详见 Whisper 模型选择）
多模型批量转录（--all-models）：一次运行对每个音频用 4 个模型分别转录，输出 <stem>.<model>.txt 便于精度对比
模型预下载（--preload-models）：一次性下载全部支持的模型到本地缓存
自定义输出后缀（--output-suffix）：便于同一模型多次转录（不同参数）不覆盖
支持指定语言（--language zh/en/...）或自动检测
支持音频切分转录：超长音频切分后逐段转录再合并
支持多种音频格式：.mp3/.m4a/.wav/.flac/.ogg/.aac
Manifest 嵌套 transcriptions：同一视频/音频记录里，多模型多参数结果按 <model>[:<suffix>] 为 subkey 共存，互不覆盖

环境要求

依赖	版本	用途
Python	3.8+	脚本运行
FFmpeg	4.0+	音视频处理（含 `ffprobe`）
openai-whisper	最新	音频转录

当前实测环境：Ubuntu 22.04 (WSL2) + Python 3.13 + FFmpeg 6.0 + Whisper 20250625

安装

1. 安装 FFmpeg

sudo apt update
sudo apt install -y ffmpeg
ffmpeg -version   # 验证

2. 安装 Whisper

pip install openai-whisper
whisper --help    # 验证

3. 预下载所有 Whisper 模型（推荐）

首次运行前，建议一次性下载所需的 4 个模型（共约 2.1GB）：

python3 transcribe_audio.py --preload-models

下载耗时参考（本机测试）：

tiny    (~75MB)  → 数秒
base    (~140MB) → 数秒
small   (~460MB) → 数十秒
medium  (~1.5GB) → 75s

模型会缓存到 ~/.cache/whisper/。

4. 下载脚本

将 extract_audio.py 和 transcribe_audio.py 放到同一目录即可，无需额外配置。

快速开始

场景 1：处理某目录下所有视频（简单流水线）

# Step 1: 提取音频（生成 .mp3）
python3 extract_audio.py /path/to/videos/

# Step 2: 转录文字（生成 .txt，默认 base 模型）
python3 transcribe_audio.py /path/to/videos/ --language zh

场景 2：对比 4 个模型的精度

# 一次运行，每个音频用 4 个模型都跑一遍
python3 transcribe_audio.py /path/to/audio/ --all-models --language zh

输出（每个 mp3 生成 4 个 txt）：

audio1.mp3
audio1.tiny.txt
audio1.base.txt
audio1.small.txt
audio1.medium.txt

场景 3：高精度转录（推荐配置）

python3 transcribe_audio.py /path/to/audio/ --model medium --language zh

脚本一：extract_audio.py

用法

python3 extract_audio.py <source> [选项]

参数说明

参数	简写	默认	说明
`source`	-	必填	视频文件路径或包含视频的目录
`--output`	`-o`	与源同目录	MP3 输出目录
`--manifest`	`-m`	source 目录下	manifest.json 路径
`--split-size`	-	不切分	视频时长超过此秒数则切分（单位：秒）
`--split-segment`	-	600	每个切分片段时长（单位：秒）
`--retry-failed`	-	false	重新处理上次失败的文件
`--status`	-	false	仅查看进度状态，不执行提取

使用示例

1. 处理目录下所有视频

python3 extract_audio.py /home/user/videos/

2. 处理单个视频

python3 extract_audio.py /home/user/videos/lesson1.mp4

3. 指定 MP3 输出目录

python3 extract_audio.py /home/user/videos/ -o /home/user/audio/

4. 超过 1 小时的视频自动切分为 10 分钟片段

python3 extract_audio.py /home/user/videos/ --split-size 3600 --split-segment 600

5. 查看进度

python3 extract_audio.py /home/user/videos/ --status

6. 重试失败的文件

python3 extract_audio.py /home/user/videos/ --retry-failed

输出规格（FFmpeg 参数）

-vn                去除视频轨道
-acodec libmp3lame MP3 编码
-ab 64k            比特率 64kbps
-ar 22050          采样率 22050Hz
-ac 1              单声道

场景优化：这套参数针对语音课程/讲座优化，体积约为原视频的 20%，同时保留清晰的人声。

脚本二：transcribe_audio.py

用法

python3 transcribe_audio.py <source> [选项]
python3 transcribe_audio.py --preload-models    # 仅下载模型（source 可省略）

参数说明

参数	简写	默认	说明
`source`	-	见备注	MP3 文件路径或包含音频的目录
`--output`	`-o`	与源同目录	TXT 输出目录
`--manifest`	`-m`	source 目录下	manifest.json 路径
`--model`	-	`base`	Whisper 模型：`tiny/base/small/medium`（4 选一）
`--language`	-	自动检测	语言代码。推荐 `zh`（中文）或 `en`（英文）
`--all-models`	-	false	每个音频用全部 4 个模型转录，输出 `<stem>.<model>.txt`
`--output-suffix`	-	空	输出 txt 附加后缀：`<stem><suffix>.txt`
`--split-size`	-	不切分	音频超过此秒数则切分（需要 ffmpeg）
`--split-segment`	-	1800	每个切分片段时长（单位：秒）
`--retry-failed`	-	false	重新处理上次失败的文件
`--status`	-	false	仅查看进度状态
`--preload-models`	-	false	预下载全部支持模型，无需 source

备注：--preload-models 或 --status 模式下可省略 source。

Whisper 模型选择

模型	参数量	磁盘	显存	CPU 转录 890s 音频	中文精度	语言输出
`tiny`	39M	~75MB	~1GB	47s	⭐⭐	繁体
`base`	74M	~140MB	~1GB	58s	⭐⭐⭐	简体
`small`	244M	~460MB	~2GB	93s	⭐⭐⭐⭐	简体
`medium`	769M	~1.5GB	~5GB	170s	⭐⭐⭐⭐⭐	简体 + 标点

实测数据来源：本项目测试报告（14 分 50 秒中文课程视频）推荐：日常速稿用 base，重要内容用 medium。

使用示例

1. 转录目录下所有 MP3（默认 base 模型）

python3 transcribe_audio.py /home/user/audio/

2. 中文课程使用 medium 模型（高精度）

python3 transcribe_audio.py /home/user/audio/ --model medium --language zh

3. 一次跑 4 个模型对比精度

python3 transcribe_audio.py /home/user/audio/ --all-models --language zh

4. 预下载模型（首次安装后一次性下载全部）

python3 transcribe_audio.py --preload-models

5. 自定义输出后缀（避免覆盖）

# 用 base 模型转录，输出为 <stem>_v1.txt
python3 transcribe_audio.py /home/user/audio/ --model base --output-suffix _v1

# 稍后再用 base + 不同参数转录，输出为 <stem>_v2.txt（不覆盖 v1）
python3 transcribe_audio.py /home/user/audio/ --model base --output-suffix _v2

6. 超长音频（>30 分钟）切分转录

python3 transcribe_audio.py /home/user/audio/ \
  --model medium --language zh \
  --split-size 1800 --split-segment 600

7. 查看进度（含每个模型的记录）

python3 transcribe_audio.py /home/user/audio/ --status

8. 重试失败的文件

python3 transcribe_audio.py /home/user/audio/ --retry-failed

多模型精度对比

实测样本

音频：SketchUp 软件优化设置课程（14 分 50 秒，中文普通话）
命令：python3 transcribe_audio.py <mp3> --all-models --language zh

精度对比（关键词识别）

关键词	原意	tiny	base	small	medium
SketchUp 中文名	草图大师	草毒大師 ❌	吵毒大师 ❌	草读大师 ❌	草毒大师 ❌
出厂设置	常规的设置	殘酷 ❌	残酷 ❌	常规 ✅	常规 ✅
行业	行业	含業 ❌	行业 ✅	行业 ✅	行业 ✅
轮廓线	轮廓线	能夠像 ❌	能扩限 ❌	轮廓线 ✅	轮廓线 ✅
场景	场景	殘景 ❌	场景 ✅	场景 ✅	场景 ✅
输出语言	简体中文	繁体 ⚠️	简体 ✅	简体 ✅	简体 ✅
标点符号	有	无 ❌	无 ❌	少量 ⚠️	有 ✅

各模型样例输出（首行）

原音频："大家好，这一节我们对草图大师来进行一个软件的一些优化设置方面的一些操作"

模型	输出	备注
tiny	大家好,這一節我們對草毒大師來進行一個軟件的一些優化設置方面的一些操作	繁体，专有名词错
base	大家好,这一节我们对吵毒大师来进行一个软件的一些优化设置方面的一些操作	简体，专有名词错
small	大家好,这一节我们对草读大师来进行一个软件的一些优化设置方面的一些操作	简体，专有名词接近
medium	大家好,这一节我们对草毒大师来进行一个软件的一些优化设置方面的一些操作	简体，专有名词接近，有逗号

结论

场景	推荐模型
快速内容概览、草稿	tiny 或 base（快，可接受）
日常转录、笔记	base 或 small（平衡）
正式转录、发布	medium（最好精度）
专有名词很多的领域	结合 `--initial_prompt` 或人工校对

提示：所有 whisper 模型对专有名词（品牌名、人名、技术术语）识别都容易出错。生产环境建议：

使用 medium 模型

通过 whisper --initial_prompt "本视频讨论 SketchUp / 草图大师" 提示 whisper（本脚本暂未透传此参数，可直接调 whisper CLI）

人工二次校对

Manifest 文件说明

两个脚本共享同一个 manifest.json（schema v2）。每个视频文件在 manifest 中只有一条记录，extract_audio.py 与 transcribe_audio.py 分别写入其中的 extraction 与 transcriptions 两个子对象，互不覆盖。

key 选择规则

Key	来源	场景
视频绝对路径（如 `/path/to/x.mp4`）	`extract_audio.py` 产生的记录	完整流水线（视频 → 音频 → 转录）
音频绝对路径（如 `/path/to/x.mp3`）	直接对 mp3 跑 `transcribe_audio.py`	独立音频转录（无对应视频）

反向查找：当 transcribe_audio.py 处理某个 mp3 时，会先扫描 manifest，如果发现某条视频记录的 extraction.audio_path 等于该 mp3 路径，就把转录结果并入该视频记录，而不是新建 key。

完整示例（v2）

{
  "version": 2,
  "files": {
    "/path/to/lesson1.mp4": {
      "extraction": {
        "extracted": true,
        "audio_path": "/path/to/lesson1.mp3",
        "split_segments": [],
        "error": null,
        "updated_at": "2026-08-23T10:30:00"
      },
      "transcriptions": {
        "tiny": {
          "transcribed": true,
          "txt_path": "/path/to/lesson1.tiny.txt",
          "split_segments": [],
          "model": "tiny",
          "language": "zh",
          "output_suffix": null,
          "error": null,
          "updated_at": "2026-08-23T10:35:00"
        },
        "medium": {
          "transcribed": true,
          "txt_path": "/path/to/lesson1.medium.txt",
          "split_segments": [],
          "model": "medium",
          "language": "zh",
          "output_suffix": null,
          "error": null,
          "updated_at": "2026-08-23T10:50:00"
        },
        "base:_v1": {
          "transcribed": true,
          "txt_path": "/path/to/lesson1_v1.txt",
          "split_segments": [],
          "model": "base",
          "language": null,
          "output_suffix": "_v1",
          "error": null,
          "updated_at": "2026-08-23T11:00:00"
        }
      }
    },
    "/path/to/standalone.mp3": {
      "extraction": null,
      "transcriptions": {
        "medium": {
          "transcribed": true,
          "txt_path": "/path/to/standalone.medium.txt",
          "split_segments": [],
          "model": "medium",
          "language": "en",
          "output_suffix": null,
          "error": null,
          "updated_at": "2026-08-23T11:15:00"
        }
      }
    }
  }
}

字段说明

顶层每条记录

extraction - extract_audio.py 的产物；null 表示没有走过提取（例如直接对 mp3 跑转录）
transcriptions - transcribe_audio.py 的产物；以 <model> 或 <model>:<suffix> 为 subkey，允许同一音频用多种模型/参数并存

extraction 字段

extracted - 是否已提取音频（布尔）；false + 有 error 表示上次失败
audio_path - 生成的 MP3 路径（切分模式下为第一个片段）
split_segments - 切分片段列表（非切分模式为空 []）
error - 失败时的错误信息，成功为 null
updated_at - 最后更新时间（ISO 8601）

transcriptions.<subkey> 字段

transcribed - 是否已转录（布尔）
txt_path - 生成的 TXT 路径
split_segments - 切分片段列表
model - 使用的 whisper 模型（tiny/base/small/medium）
language - 使用的语言代码（zh/en/...）或 null（自动检测）
output_suffix - 输出后缀（默认 null）
error - 失败错误信息
updated_at - 最后更新时间

断点续传逻辑

脚本判断是否需要处理某文件时，同时校验：

manifest 中标记为已完成（extraction.extracted=true 或 transcriptions.<sk>.transcribed=true）
目标文件实际存在且非空

任一条件不满足则重新处理（例如手动删除了 mp3 后重跑，会重新提取）。

多模型模式：每个 (音频 × 模型 × 后缀) 组合独立跟踪，对应 transcriptions 里独立的 subkey。已完成的组合被跳过，未完成的继续。

从旧版 (v1) 升级

老版本使用扁平 schema：视频记录 key = 视频路径；转录记录 key = transcribe:<model>[:<suffix>]:<音频路径>。这些散落的记录在 v2 里会被合并到同一条视频记录里。

升级方式：脚本首次加载旧 manifest 时会打印警告并以空 v2 schema 重新开始（旧数据将被下次保存覆盖）。如果你想保留旧记录，运行升级前先手动备份 manifest.json。所有已提取的 mp3 和已转录的 txt 会在下次运行时被识别为"存在但 manifest 无记录"→ 重新处理并写入新 schema。

高级用法

1. 完整流水线脚本

#!/bin/bash
VIDEO_DIR="/path/to/videos"

echo "=== Step 0: 预下载模型（仅首次）==="
python3 transcribe_audio.py --preload-models

echo "=== Step 1: 提取音频 ==="
python3 extract_audio.py "$VIDEO_DIR" --split-size 3600 --split-segment 600

echo "=== Step 2: 转录文字（medium 模型高精度）==="
python3 transcribe_audio.py "$VIDEO_DIR" \
  --model medium --language zh \
  --split-size 1800 --split-segment 600

echo "=== Step 3: 查看最终状态 ==="
python3 extract_audio.py "$VIDEO_DIR" --status
python3 transcribe_audio.py "$VIDEO_DIR" --status

2. 多模型对比工作流

# 1) 提取音频
python3 extract_audio.py /videos/

# 2) 一次跑 4 个模型（此步骤会跑 4x 时长，请预留时间）
python3 transcribe_audio.py /videos/ --all-models --language zh

# 3) 查看所有结果
python3 transcribe_audio.py /videos/ --status

# 4) 对比不同模型输出（例如用 diff）
diff /videos/lesson1.base.txt /videos/lesson1.medium.txt

3. 独立分离 MP3 与 TXT 输出

python3 extract_audio.py /videos/     -o /audios/
python3 transcribe_audio.py /audios/  -o /transcripts/ --model medium

4. 自定义 manifest 位置（多套并行）

python3 extract_audio.py /videos/ -m /var/run/task1_manifest.json
python3 extract_audio.py /videos2/ -m /var/run/task2_manifest.json

5. 同一模型不同参数的多轮转录

# 第一版：自动检测语言
python3 transcribe_audio.py audio.mp3 --model base --output-suffix _auto

# 第二版：强制中文
python3 transcribe_audio.py audio.mp3 --model base --language zh --output-suffix _zh

# 两个 txt 独立保存，manifest 各自记录
ls audio_*.txt
# audio_auto.txt  audio_zh.txt

故障排查

FFmpeg 相关

症状	原因	解决
未找到 ffmpeg 命令	未安装	`sudo apt install ffmpeg`
视频时长为 0	ffprobe 无法解析	检查视频是否损坏 `ffprobe <file>`
切分片段为空	编码不兼容 codec copy	手动尝试 `ffmpeg -i in.mp4 -c copy out.mp4`

Whisper 相关

症状	原因	解决
未找到 whisper 命令	未安装	`pip install openai-whisper`
首次转录卡住	正在下载模型	提前用 `--preload-models` 一次下完
CUDA out of memory	显存不足	使用更小模型；whisper 自动 fallback 到 CPU
转录内容为繁体	tiny 模型对中文倾向输出繁体	使用 `base` 及以上模型
专有名词识别错	模型未训练过	使用 `medium`；未来可支持 `--initial-prompt`

Manifest 相关

症状	解决
想强制重跑所有文件	删除 `manifest.json`
想强制重跑某个文件	编辑 manifest 或删除对应 `.mp3/.txt` 文件
想重跑失败的文件	加 `--retry-failed` 参数
想同一音频用同模型换参数再跑一次	用 `--output-suffix` 区分

文件名相关

中文文件名：完全支持
空格文件名：完全支持（内部用 subprocess 参数列表，非 shell 拼接）
特殊字符（如 &、|）：应可正常处理，遇到问题请提 issue

测试报告

测试环境

OS: Ubuntu 22.04 (WSL2 on Windows)
Python: 3.13
FFmpeg: 6.0
Whisper: 20250625 (全部 4 个模型)

测试用例

测试视频：03-SU软件的优化设置.mp4

时长：890 秒（14 分 50 秒）
大小：37 MB
视频：H.264 1280x720
音频：AAC 44.1kHz 立体声
语言：中文（普通话）
内容：SketchUp 软件优化设置教学

提取音频 & 通用功能测试

#	测试项	结果	耗时	备注
1	基本音频提取	✅	4s	输出 6.9MB MP3 (22050Hz mono 64kbps)
2	断点续传（重跑跳过）	✅	<1s	manifest 校验通过
3	`--status` 状态查看	✅	<1s	正确显示 1/1 完成
4	视频切分模式（500s 阈值）	✅	4s	3 片段完美衔接（修复 pipe:0 bug）
5	失败重试 + 含空格文件名	✅	-	失败记录、跳过、`--retry-failed` 均正常
6	端到端流水线（视频→MP3→TXT）	✅	54s	从零开始生成完整产物

转录 & 多模型功能测试

#	测试项	结果	耗时	备注
7	`--preload-models` 预下载 4 模型	✅	~120s	共 2.1GB，缓存到 `~/.cache/whisper/`
8	单模型转录（tiny + zh）	✅	47s	输出 9KB TXT
9	单模型转录（base + zh）	✅	58s	输出 9KB TXT
10	单模型转录（small + zh）	✅	93s	输出 9KB TXT
11	单模型转录（medium + zh）	✅	170s	输出 9KB TXT，有标点符号
12	`--all-models` 4 模型一次跑	✅	368s	生成 4 个独立 txt
13	多模型 manifest 记录	✅	-	4 条独立 key，互不覆盖
14	多模型 `--status` 展示	✅	<1s	每个模型独立行显示
15	断点续传（重跑跳过）	✅	<1s	4/4 全部跳过
16	`--output-suffix` 自定义后缀	✅	46s	`_custom` 生成独立 key + 独立 txt
17	音频切分转录	✅	59s	3 片段并转录后合并成完整 TXT
18	manifest 共享验证	✅	-	提取+转录记录并存互不干扰

已修复 Bug

BUG-01：切分模式下 MP3 为空文件（148 字节）

原因：使用 cat <file> | ffmpeg -i pipe:0 时，MP4 的 moov atom 位于文件末尾需要 seek，pipe 不支持 seek 导致 ffmpeg 静默失败
修复：改用 ffmpeg -i <file> 直接读取本地文件，同时增加输出文件非空校验（> 1KB）
验证：切分后 3 个片段合计 890.4s ≈ 原视频 890.2s

BUG-02：--output-suffix 被 manifest 误跳过

原因：初版 manifest key 只含 model + path，未含 output_suffix，导致同一模型换 suffix 后被判定为已完成
修复：key 结构改为 transcribe:<model>[:<suffix>]:<path>，suffix 参与 key 判定
验证：同一 tiny 模型，无 suffix 和 _custom suffix 生成独立 manifest 条目和独立 txt

性能参考（本次测试环境，CPU 转录）

阶段	输入	输出	耗时	吞吐
音频提取	37MB / 890s 视频	6.9MB MP3	4s	223x realtime
转录（tiny）	6.9MB / 890s 音频	9KB TXT	47s	19x realtime
转录（base）	6.9MB / 890s 音频	9KB TXT	58s	15x realtime
转录（small）	6.9MB / 890s 音频	9KB TXT	93s	9.6x realtime
转录（medium）	6.9MB / 890s 音频	9KB TXT	170s	5.2x realtime
多模型一次跑（4 model）	6.9MB / 890s 音频	4 个 9KB TXT	368s	-

上述数据为 CPU 转录性能。GPU 转录速度可提升 5-10x。

项目路线图

Phase 1: 音频提取（extract_audio.py）
Phase 2: 音频转录（transcribe_audio.py）
- 单模型转录
- 多模型批量对比（--all-models）
- 模型预下载（--preload-models）
- 输出后缀自定义（--output-suffix）
- 语言指定（--language zh/en）
Phase 3: 内容归纳整理（summarize.py）- 待定
- AI 分析文字内容 + 视频内容
- 生成脑图、结构化文档

23 KiB Raw Blame History Unescape Escape

SynthMind - 视频音频提取与转录工具

目录

功能特性

通用特性

extract_audio.py 特性

transcribe_audio.py 特性

环境要求

安装

1. 安装 FFmpeg

2. 安装 Whisper

3. 预下载所有 Whisper 模型（推荐）

4. 下载脚本

快速开始

场景 1：处理某目录下所有视频（简单流水线）

场景 2：对比 4 个模型的精度

场景 3：高精度转录（推荐配置）

脚本一：extract_audio.py

用法

参数说明

使用示例

输出规格（FFmpeg 参数）

脚本二：transcribe_audio.py

用法

参数说明

Whisper 模型选择

使用示例

多模型精度对比

实测样本

精度对比（关键词识别）

各模型样例输出（首行）

结论

Manifest 文件说明

key 选择规则

完整示例（v2）

字段说明

断点续传逻辑

从旧版 (v1) 升级

高级用法

1. 完整流水线脚本

2. 多模型对比工作流

3. 独立分离 MP3 与 TXT 输出

4. 自定义 manifest 位置（多套并行）

5. 同一模型不同参数的多轮转录

故障排查

FFmpeg 相关

Whisper 相关

Manifest 相关

文件名相关

测试报告

测试环境

测试用例

提取音频 & 通用功能测试

转录 & 多模型功能测试

已修复 Bug

性能参考（本次测试环境，CPU 转录）

项目路线图

相关脚本

23 KiB

Raw Blame History