openclaw-asr

name	openclaw-asr
description	Local-first ASR: audio/video to MP3, Whisper/WhisperX transcription, .tty parsing, meeting notes and OpenClaw delivery. For 百炼/阿里云/云端/cloud ASR use huo15-openclaw-asr-bailian instead. Triggers: speech recognition, ASR, transcription, 录音转文字, 纪要, MP3, ffmpeg, Whisper, WhisperX, speaker diarization, 说话人分离, 本地转写, audio/video to text, .tty files.

OpenClaw 媒体转写与龙虾研判（本地优先）

本 skill 指导将音视频或 .tty 转为可用文本，生成原文与纪要，并以固定结构交给 OpenClaw（龙虾） 做类型与内容判断。

与 huo15-openclaw-asr-bailian 的分工（必读）

场景	使用哪个 skill
百炼 / 阿里云 / 云端 / 云转录 / Paraformer / DashScope / 不用本地 Whisper	优先加载 huo15-openclaw-asr-bailian（默认云端路线）
本地转写、隐私不上云、Whisper / WhisperX	本 skill（huo15-openclaw-asr）
.tty 终端录屏	本 skill（百炼 skill 不处理 .tty）

云端转写不要在本 skill 内对接百炼 API；统一交给 huo15-openclaw-asr-bailian。纪要模板、交付块、Word 落盘两边约定一致，百炼侧见该 skill 文档。

适用范围与触发

• 输入：mp3、wav、m4a、aac、flac、ogg、mp4、mkv、webm、mov 等常见音视频，或扩展名为 .tty 的文件。
• 输出：规范化文本（原文）、纪要、元数据与待龙虾判断字段。

总流程（决策树）

1. 识别输入类型

   • 扩展名为 .tty → 走 .tty 分支。
   • 其余音视频 → 走 音视频分支。

2. 取得原文

   • 原文：逐字/逐句转写（openai-whisper 默认 --model base）或从 .tty 提取的可读文本，尽量保留说话人切换线索（若模型支持说话人分离则标注 说话人 A/B）。

3. 转写质量判断（仅 Whisper 本地转写时必做）

   • 跑完 base 转写后，按 转写质量判断与模型升级建议 自检；问题多则提示用户改用 small / medium 重跑，通过前不写定稿纪要；问题少再进入下一步。
   • .tty 文本路径不做 Whisper 质检，直接进入纪要。

4. 生成纪要

   • 结构化摘要（见 纪要模板），严格基于已通过质检（或无需质检）的原文，不杜撰未出现的信息。

5. 交给龙虾判断

   • 使用 OpenClaw 交付块 输出；由龙虾结合项目策略做类型判定与后续动作（归档、跟进、敏感内容标记等）。

6. 可选：保存文件（下载文件夹）

   • Whisper 路径：质量判断为「可接受」并完成纪要、交付块之后；.tty 等路径：完成原文、纪要、交付块之后。询问用户是否保存，以及保存格式（Markdown 或 Word）；若同意，按 保存文件（下载文件夹） 写入。

---

音视频 → MP3 → 转写

1. 转为 MP3（统一中间格式）

优先使用 ffmpeg（需已安装并在 PATH 中）。

ffmpeg -y -i "INPUT" -vn -acodec libmp3lame -q:a 2 "OUTPUT.mp3"

• INPUT：任意 ffmpeg 可读音视频路径。
• -vn：去掉视频轨，只保留音频。
• 若 libmp3lame 不可用，可改用：-acodec aac -b:a 192k "OUTPUT.m4a"，并在后续转写步骤中改用该中间文件（仍按本 skill 的「原文 + 纪要 + 龙虾块」交付）。

2. 语音转文字（ASR）

按环境选择其一（默认优先本地，避免泄露）：

方式	说明
Whisper 系 CLI	如 whisper、faster-whisper 等，对 OUTPUT.mp3 跑转写，保存为 txt/srt/vtt。本 skill 默认。
WhisperX	在 Whisper 类转写之上做 词级对齐与可选 说话人分离（diarization）；见 WhisperX（说话人分离）。
百炼云端 ASR	不要在此实现。用户要云端/百炼/阿里云时 → huo15-openclaw-asr-bailian（Paraformer 等）。

openai-whisper：依赖与首次运行体积预期

• pip install openai-whisper 会安装 PyTorch 等依赖，磁盘占用常见为数百 MB 量级，CUDA 版可达约 1GB+（随平台与是否 GPU 版变化）；Whisper 包本身相对较小。
• 首次执行转写时还会按 --model 单独下载权重：本 skill 默认 base（体积常见为 约百 MB 量级，以官方缓存为准）；tiny 约 72MB 级；turbo 约 1.5GB 量级，下载与加载都更重，弱配置上易 OOM 或极慢。

Windows：Whisper CLI 与中文控制台（GBK 崩溃）

在中文区域设置的 Windows 上，直接运行 whisper --help 或转写时，Python 可能用 GBK 写 stdout，触发 UnicodeEncodeError: 'gbk' codec ...。在同一 PowerShell 会话内先设置再调用 Whisper：

$env:PYTHONIOENCODING = "utf-8"
whisper --help

转写示例（会话内已设好 PYTHONIOENCODING）；默认模型为 base：

whisper "OUTPUT.mp3" --model base --language Chinese

Whisper 模型选择（默认 base，再按质量升降级）

• 默认：openai-whisper CLI 使用 --model base 做首次转写，再进入 转写质量判断与模型升级建议。
• tiny：约 72MB 级，仅当磁盘/内存极紧、或用户明确要求「先快速试跑」时使用；默认流程不以 tiny 为首选。
• turbo：权重大（约 1.5GB），下载与全量加载占用高，易 OOM；仅当机器资源充足且对准确率/速度有更高诉求时再考虑。

WhisperX（说话人分离）

当用户需要 分说话人 的原文（如会议多角色），可选用 WhisperX（Python 库，非 openai-whisper 自带 CLI）。

安装

pip install whisperx

仍依赖 PyTorch 等，整体磁盘与首次下载体积与 Whisper 路线同量级，且对齐 / diarization 会再拉取额外权重。

中文对齐（ZH）

• 使用 whisperx.load_align_model(language_code="zh", ...) 时，会自动下载中文 forced alignment 所用模型（首次需联网与足够磁盘）；无需手动另选「ZH 对齐包」路径，但要在 notes_for_openclaw 中注明是否已首次拉取成功。

Diarization（说话人分离）与 HuggingFace

• 默认：许多 diarization 管线依赖 HuggingFace 已登录（如 huggingface-cli login 或环境变量 HF_TOKEN），否则无法拉取门控模型。
• 不想登录 HF 时：部分场景可尝试将 use_auth_token=False 传给 API（或通过环境变量/封装参数，以当前 WhisperX 版本文档为准）。注意：部分模型在无 token 时不可用或行为异常，若采用此方式，须在交付备注中写明「未使用 HF 门控模型 / 可能降级」。
• 使用 pyannote/speaker-diarization-3.1（或同类 pyannote 门控模型）：必须先在 HuggingFace 网站对该模型访问条款点击同意，再在本地配置 token 后下载权重；否则拉取会失败。

启用 WhisperX 且带 diarization 时，原文中应显式标注说话人分段（如 SPEAKER_00 / 说话人 A 等与用户对齐的命名）；后续仍执行 转写质量判断与模型升级建议（针对合并可读文本与分段合理性），再走纪要、交付块与可选落盘。

---

转写质量判断与模型升级建议

在 openai-whisper 默认 base 模型产出原文后，agent 必须对照下列质量指标做一次快速审查（结合音频时长与领域常识，不必过度纠结单次口误）。若已按建议改用 small / medium 重跑，则对最后一次转写结果重复本审查。

指标	说明（出现则计为问题）
错译 / 同音错字成片	专有名词、数字、单位、人名地名等明显不合理或与音频常识不符
乱码与异常符号	不可读片段、大量无意义符号、编码异常痕迹
无意义重复	同一短语/句子异常堆叠，疑似解码或切片错误
句意断裂	大量不成句碎片、缺主谓宾导致无法理解叙述脉络
语言/段落错配	明显中英混排错误、段落顺序颠倒、长时间静音被填成幻觉句（若可判断）

分支：

• 问题偏多（多项明显、或严重影响可读性）：不要直接进入纪要定稿与落盘询问；向用户说明命中了哪些指标，并明确建议用更大模型 重跑转写，优先顺序 small → medium（资源允许再考虑 large / turbo）。重跑后再次做本表自检。
• 问题偏少（偶发错字、整体可读）：视为通过，进入 纪要、OpenClaw 交付块，以及 保存文件（下载文件夹） 的询问流程。

.tty 纯文本路径不适用 Whisper 模型升级；若文本来自终端抽取且噪声大，在 notes_for_openclaw 中说明即可。

---

转写要求：

• 语言：若未知，先自动检测或让用户确认（中文/英文/混合）。
• 输出一份连续可读原文（可附带时间戳文件作附录，但「原文」字段本身以可读文本为主）。

3. 纪要

在取得原文、且 Whisper 路径已通过 转写质量判断与模型升级建议（或 .tty 等无需 Whisper 质检）之后，由当前 agent 基于原文生成纪要（不得编造未出现的信息）。模板见下节。

---

.tty（终端录屏 / 会话日志）

.tty 并非单一国际标准格式，可能是纯文本、script/typescript 文本、或 ttyrec 类二进制。按顺序处理：

1. 探测

   • 运行 file（Linux/macOS）或读取文件头若干字节判断是否为文本。
   • 若整文件为可读 UTF-8/ASCII → 直接作为「原文」基础，必要时去掉 ANSI 转义（可用 sed/脚本剥离 \x1b[...m）。

2. script 会话

   • 若内容含 Script started on / Script done on 等典型标记，可保留命令与输出；纪要中总结执行了哪些命令、关键输出、错误信息。

3. 二进制 ttyrec

   • 若判定为 ttyrec 类：使用 ttyplay / termplay / ttyrec 配套工具，或小型解析脚本将帧解码为文本流，再整理为原文。
   • 若无工具：至少用 strings 提取可打印片段，并在交付块中 诚实标注「部分为 strings 抽取，可能不完整」。

4. 纪要

   与音视频相同：基于提取出的文本生成纪要，并进入 OpenClaw 交付块。

---

纪要模板

## 纪要

### 主题（一句话）
[用一句话概括]

### 要点
- [要点 1]
- [要点 2]

### 行动项（若有）
- [ ] 负责人/角色未明则写「待确认」— [事项] — 截止时间未明则写「待定」

### 风险与待澄清
- [若有]

---

类型候选（供龙虾判断，非最终定案）

agent 可根据内容给出 1–3 个候选类型 与简短理由；最终类型以龙虾判断为准。

示例维度（可按项目扩展）：

代码	含义（示例）
meeting	会议/讨论
interview	访谈/面试
lecture	课程/演讲
support	客服/技术支持
terminal_session	终端操作/排障录屏
personal	个人备忘/闲聊
other	其他（需在理由中说明）

---

OpenClaw（龙虾）交付块

完成转写与纪要后，必须附加以下结构化块（便于龙虾解析与路由）：

---OPENCLAW_ASR_DELIVERY---
version: 1
source_kind: audio_video | tty
source_path: "<原始文件路径或用户提供的标识>"
intermediate_mp3: "<若适用，MP3 路径；tty 则填 null>"
language_guess: "<如 zh | en | mixed | unknown>"
type_candidates:
  - code: "<meeting|interview|...>"
    confidence: <0.0-1.0>
    reason: "<一句理由>"
verbatim_text: |
  <原文全文，或说明见附件路径>
summary_markdown: |
  <纪要全文，使用上文「纪要模板」>
notes_for_openclaw: |
  <给龙虾的备注：不确定性、敏感提示、需人工复核的点等>
---END_OPENCLAW_ASR_DELIVERY---

说明：

• verbatim_text 过长时，可写 见: <path>，但需在 notes_for_openclaw 说明编码与换行是否保留。
• 龙虾的职责：在此块之上做最终类型、优先级、是否入库/触发自动化等判断；本 skill 不替代龙虾策略。

---

保存文件（下载文件夹）

在已完成原文 + 纪要 + 交付块的组装后：Whisper 路径须已通过 转写质量判断与模型升级建议；.tty 等路径无 Whisper 质检要求。随后：

1. 询问用户：是否需要将本次结果保存到本地（默认不擅自写入）。
2. 若用户同意，再询问保存格式：Markdown 还是 Word。
3. 保存到当前系统用户的 「下载」 目录：
   • Windows：%USERPROFILE%\Downloads（资源管理器中显示为「下载」）。
   • macOS：~/Downloads。
   • Linux：常见为 ~/Downloads（若不存在可先创建或改用用户指定路径并说明）。

---

选项 A：保存为 Markdown

文件命名（避免文件名非法字符，不要使用冒号）：

ASR_转写_YYYY-MM-DD_HHmmss.md

示例：ASR_转写_2026-05-07_143052.md。日期与时间取保存时刻的本地时间。

文件内容须按顺序包含以下三部分（可用二级标题分隔）：

1. 原文（完整转写正文，或与用户约定的附件引用方式及路径说明）。
2. 纪要（使用 纪要模板）。
3. OpenClaw 交付块（完整一段 ---OPENCLAW_ASR_DELIVERY--- … ---END_OPENCLAW_ASR_DELIVERY---，与对话中交付给龙虾的块一致）。

---

选项 B：保存为 Word（仅纪要）

使用 huo15-openclaw-office-doc 技能（位于 skills/huo15-openclaw-office-doc/）将纪要部分生成为格式规范的 。docx 文件。

依赖安装（如未安装）：

pip install python-docx reportlab pygments

如果系统有多个 Python 版本（如 MSYS2 Python 与官方 Python 并存），请确认 pip 安装的目标 Python 与执行脚本的 Python 保持一致。可通过 python -c "import sys; print(sys.executable)" 确认。

文件命名：

ASR_纪要_YYYY-MM-DD_HHmmss.docx

示例：ASR_纪要_2026-05-07_143052.docx。

操作步骤：

1. 将纪要全文写入一个临时 Markdown 文件（如 $env:TEMP\meeting_summary_<timestamp>.md）。注意：内容为执行本 skill 时已生成的 summary_markdown 字段，不含交付块。
2. 调用 office-doc 的 create-word-doc.py 生成 Word：

python <workspace>/skills/huo15-openclaw-office-doc/scripts/create-word-doc.py `
  --output "<下载目录>\ASR_纪要_YYYY-MM-DD_HHmmss.docx" `
  --title "会议纪要 - YYYY-MM-DD" `
  --content @"<临时 markdown 文件路径>" `
  --doc-format 会议纪要 `
  --company-name "会议纪要" `
  --no-title-block

<workspace> 为本 skill 所在 OpenClaw 工作区根目录（即 ~/.openclaw/workspace-hanser）。因本机环境 python 指向 MSYS2 的 Python，需要显式使用官方 Python 路径：D:\Users\Grunray\AppData\Local\Programs\Python\Python313\python.exe（可通过 python -c "import sys; print(sys.executable)" 确认正确的路径）。

参数说明：

参数	值	说明
--output	下载目录下的 。docx 路径	输出文件
--title	会议纪要 - YYYY-MM-DD	文档标题
--content @<path>	@ 开头表示读取文件	纪要正文（Markdown 格式）
--doc-format 会议纪要	指定为会议纪要规范	自动匹配页眉/正文样式
--company-name 会议纪要	占位公司名	避免因缺公司信息报错
--no-title-block	不额外渲染标题块	标题已在正文中

3. 清理：删除临时 Markdown 文件。
4. 告知用户文件已生成。

注意：当前使用占位公司名「会议纪要」，header 区域可能显示占位名称。如希望定制公司信息，可使用 --company-name "<公司名>" 和 --logo-path "<LOGO路径>"，或参照 office-doc 技能的本地公司信息工作流配置持久化信息。

---

自检清单

• 音视频已尽量统一为 MP3（或等价单音频轨）再转写。
• 在 Windows 用 openai-whisper CLI 时，已设置 PYTHONIOENCODING=utf-8（或等价方式），避免 GBK 编码崩溃。
• openai-whisper 默认已用 base 转写，并已按质量指标完成判断；问题多时已建议 small / medium 重跑。
• 若使用 WhisperX 做 diarization：已说明 HF 登录 / 协议同意 / use_auth_token=False 尝试 等实际情况，且原文已带说话人分段标注。
• .tty 已按文本 / script / ttyrec 路径处理，不确定处已标注。
• 纪要严格来源于原文或终端输出。
• 已输出 OPENCLAW_ASR_DELIVERY 块供龙虾判断。
• （Whisper 路径在质量可接受后，或 .tty 等路径在完成交付块后）已询问是否保存，以及保存格式（Markdown 或 Word）。
  • Markdown：已写入 下载 文件夹，文件名为 ASR_转写_YYYY-MM-DD_HHmmss.md，含 原文 + 纪要 + 交付块。
  • Word：已使用 huo15-openclaw-office-doc 技能的 create-word-doc.py 生成 。docx 文件到 下载 文件夹（仅含纪要部分）。

---

附加资源

• 标准操作（SOP）：docs/SOP.md
• 终端 ANSI 剥离与轻量 .tty 辅助：见 scripts/README.md