转录视频

从本地视频文件中提取字幕文本。该技能优先检测视频中是否嵌入了字幕（速度更快、准确率更高），仅在未找到嵌入字幕时，才回退至基于 API 的语音识别方式。

步骤 1：确认视频文件

与用户确认视频文件路径。支持的格式包括：mp4、mkv、mov、avi、webm，以及 ffmpeg 可处理的任意格式。

步骤 2：检查嵌入式字幕

ffprobe -v quiet -select_streams s -show_entries stream=index,codec_name:stream_tags=language,title -of json ""

• 若存在字幕流 → 转至 步骤 3a（提取嵌入式字幕）
• 若不存在字幕流 → 转至 步骤 3b（API 转录）

步骤 3a：提取嵌入式字幕

若存在多个字幕轨道，优先选择与视频主语言匹配的轨道；若无法自动判断，请向用户询问应使用哪条轨道。

# 提取为 SRT 格式（0:s:0 表示第一条字幕流；如需其他流请相应调整索引）
ffmpeg -i "" -map 0:s:0 -c:s srt ".srt" -y

提取完成后，将 SRT 文件转换为纯净文本：

• 移除序号行
• 移除时间戳行（匹配格式：\d{2}:\d{2}:\d{2}）
• 移除类 HTML 标签（如 、 等）
• 合并所有非空行

将清洗后的纯文本转录内容保存为 .txt，置于视频文件所在目录。完成 —— 跳过步骤 3b。

步骤 3b：基于 API 的转录

使用内置的转录脚本。该脚本从 ~/.transcribe_video.env 中读取认证凭据。

前置条件检查

1. 验证环境变量文件是否存在：

   test -f ~/.transcribe_video.env && echo "OK" || echo "MISSING"
   

2. 若显示 MISSING，请告知用户创建 ~/.transcribe_video.env 文件，并填入以下内容：

   OPENAI_API_KEY=your-key-here
   # 可选的基础 URL：
   # OPENAI_API_BASE=https:///v1/
   # 可选的模型名称：
   # TRANSCRIBE_MODEL=gpt-4o-transcribe
   

   等待用户确认完成后再继续执行。

3. 验证依赖项是否已安装：

   python3 -c "from openai import OpenAI; from dotenv import load_dotenv; print('OK')" 2>&1
   

   若提示缺失模块，请运行：pip install openai python-dotenv

执行转录

python3 /scripts/transcribe.py ""

该脚本会先提取音频（WAV 格式，16kHz 单声道），再将其发送至 API 进行转录，并将结果保存为 .txt，置于视频文件所在目录。

步骤 4：报告结果

向用户说明以下信息：

• 转录文件的保存位置
• 总行数 / 大致字数
• 转录来源是嵌入式字幕还是 API 转录
• 展示前几行内容作为预览