| name | media-transcribe |
| description | 通用本地音视频转录与时间戳工作流。把本地音视频文件（口播课、录屏、访谈、会议、播客、讲座、公开课）批量转成高精度文字 + 字级时间戳（SRT/JSON）+ 带时间戳的逐句转录稿，纯本地离线，支持 30+ 语种。当任务需要本地/批量/离线/高精度转录、字幕生成、口播稿整理、按时间戳定位剪辑点时使用。ChatCut 项目内的字幕请用 chatcut:transcription；已有转录只做口播去口误用 koubo-clean；口误识别审查稿用 AI剪口播。触发词：转录、转写、ASR、字幕、时间戳、音视频转文字、本地转写、会议记录、访谈转写、播客转写、口播稿、Qwen3-ASR。 |
本地音视频转录（media-transcribe）
把任意音视频一次性转成标准四件套：全文文本、字级时间戳（SRT/JSON）、带时间戳的逐句转录稿。全程本地运行，数据不出机器。
何时使用 / 何时不用（Agent 匹配决策）
使用：
- 用户给本地音视频文件，要求转成文字/字幕/口播稿/逐句稿
- 需要字级或句级时间戳来定位内容（“这句话在第几秒”）
- 批量转录多个文件、或需要离线/高精度中文转录
- 访谈/会议/播客/讲座的文稿与纪要整理
不用（交给相邻 skill）：
- ChatCut 项目内加字幕/开字幕/双语字幕 →
chatcut:transcription
- 已有转录，只要清理口误/叠字/重复 →
koubo-clean
- 只要口误识别与删除任务清单 →
AI剪口播
- 课程成片全流程（转录是其中一步） →
dou-ai-course-video（内部如需本地预转录再回到本 skill）
快速开始
# 0) 环境自检（Agent 调用前必跑；全 PASS 才继续）
python scripts\oral_pipeline.py --doctor
# 1) 转录：单文件 / 多文件 / 目录
python scripts\oral_pipeline.py a.mp4 b.mp3
python scripts\oral_pipeline.py --folder .\raw --out-dir .\transcripts
# 2) 验收
python scripts\oral_pipeline.py --search "关键词" --out-dir .\transcripts
参数
| 参数 | 默认 | 说明 |
|---|
--lang | Chinese | 语种，支持 English/Japanese/Korean/Cantonese 等 30+ |
--provider | DML | ONNX 编码器后端：DML / CUDA / CPU / TRT |
--no-ts | 关 | 关闭时间戳对齐（只要文本时提速） |
--n-ctx | 2048 | LLM 上下文 |
--chunk-size | 40 | 分片秒数（秒） |
--memory-num | 1 | 记忆历史分片数 |
--out-dir | 输入同目录 | 输出目录，建议显式指定避免覆盖 |
--search | - | 在逐句稿中定位短语并输出时间戳 |
--doctor | - | 环境自检，不转录 |
输出与验收标准
每个输入生成 4 个文件：
<名>.txt —— 全文（按标点换行）<名>.srt —— 字幕（按句切分）<名>.json —— 字级时间戳 [{text, start, end}]（秒）<名>_timed.md —— 逐句转录稿（每行 [MM:SS.mmm - MM:SS.mmm] 文本 + 纯文本区）
验收：4 个产物都存在且非空；json 时间戳项数 > 0（未 --no-ts 时）；_timed.md 每行格式正确；用 --search 抽查关键句能命中并给出时间戳。
下游处理（按需）
- 口播清理：按
koubo-clean 规范审校
- 课程成片：
dou-ai-course-video 模板
- 字幕进 ChatCut：
edit_captions
- 纪要整理：直接基于
_timed.md 的逐句稿
故障排查（分级）
| 现象 | 处理 |
|---|
--doctor 有 FAIL | 按提示修复：模型文件、DLL、依赖、ffmpeg |
初始化访问冲突 / llama_init_from_model 报错 | DLL 与项目版本不匹配，用作者 v0.1 包配套 DLL 整套替换 inference\bin |
| 转录结果 0 字 | 先 --doctor；音频是否为空；确认未传错误 --duration（内部固定 None） |
| provider 初始化失败 | --provider CPU --no-gpu 兜底，或确认 onnxruntime-directml |
| 长音频出现重复循环 | --temperature 0.5 或增大 --memory-num |
| 专有名词听错 | 属 ASR 常态（MCP→MZP、WorkBuddy→Work Buddy 等），按项目术语表统一（口播课见 koubo-clean 品牌词表） |
运行环境（环境变量配置，仓库不含本机路径）
- 引擎源码：
$env:QWEN3_ASR_ENGINE_DIR
- 模型目录：
$env:QWEN3_ASR_MODEL_DIR
- llama.cpp DLL：
$env:QWEN3_ASR_ENGINE_DIR\qwen_asr_gguf\inference\bin（作者 v0.1 包配套 Vulkan 版）
- 内核：HaujetZhao/Qwen3-ASR-GGUF（Qwen3-ASR-1.7B 文本 + Qwen3-ForceAligner-0.6B 字级时间戳）
配置方式（任选其一，优先级：命令行参数 > 系统环境变量 > .env）：
- 复制仓库根目录
.env.example 为 .env，填入本机路径（脚本启动时自动加载，不覆盖已有环境变量）
- 或设置系统/用户级环境变量
QWEN3_ASR_ENGINE_DIR、QWEN3_ASR_MODEL_DIR
- 或转录时传
--engine-dir <路径> --model-dir <路径>
常见坑
- 模型下载：GitHub release 直链需
--ssl-no-revoke --tlsv1.2；后台下载易断，用 $env:QWEN3_DOWNLOAD_WATCHER（在 .env 配置）监视器自动续传。
- chinese_itn：PyPI 无真包，引擎根目录的恒等 shim 生效中（数字规整暂不启用）。
- 输出覆盖：脚本直接覆盖同名输出，务必用
--out-dir 隔离。
