ClawHub

火一五媒体转写·百炼云 ASR

Data & APIs

默认优先使用的云端转写 skill：百炼 Paraformer/Fun-ASR；本地文件经 OpenClaw 已有 enhance_share_file 插件生成 https://keepermac.huo15.com 公网 URL 后提交百炼。 触发：百炼、阿里云转写、云端 ASR、云转录、Paraformer、DashScope。本地 Whisper 请用 huo15-openclaw-asr。

Install

openclaw skills install huo15-openclaw-asr-bailian

OpenClaw 媒体转写 · 百炼云 ASR（默认云端路线）

定位：凡用户需要云端转写、或明确说 百炼 / 阿里云 / 不用本地 Whisper 时，优先加载并执行本 skill，不要在本仓库的 huo15-openclaw-asr 里自行对接百炼 API。
本地隐私转写（Whisper / WhisperX / .tty）→ 使用 huo15-openclaw-asr。

本 skill 与 huo15-openclaw-asr 共用纪要模板、OpenClaw 交付块结构、保存 Markdown/Word（office-doc）流程；差异仅在 ASR 引擎固定为百炼。

官方文档：百炼 · 录音文件识别（Paraformer / Fun-ASR） · Python SDK

默认策略

场景使用 skill
云端 / 百炼 / 阿里云 ASR本 skill（默认）
本地、不上云、Whisper、.ttyhuo15-openclaw-asr
用户未说明先问：本地还是云端；若倾向云端 → 本 skill

上云前必须确认：用户同意音频通过公网 URL 提交至阿里云百炼处理。

百炼 URL 约束与 OpenClaw 公网分享（必读）

百炼录音文件识别只接受 HTTP/HTTPS 的音频 URL，不支持本地路径直传、Base64 或二进制流（见百炼文档）。

在 OpenClaw 工作区中，标准链路为：

本地音视频文件 → enhance_share_file（已有插件）→ 公网 URL → 百炼 API
项说明
公网域名https://keepermac.huo15.com（bot 对外 base URL；分享链接形如 https://keepermac.huo15.com/plugins/enhance-share/<token>-<filename>）
工具enhance_share_file（OpenClaw 已安装，来自 enhance 插件；不要在本 skill 内实现或要求用户新写该插件）
agent 动作对本地待转写文件调用已有工具 enhance_share_file，从返回的 structuredContent.url 取真实公网 URL，再传给 transcribe_bailian.py --file-url 或等效百炼 SDK
严禁手写、拼接、猜测 share URL（缺 token 会 404）；与 huo15-markdown-export / enhance 规则一致

调用示例（概念）：

enhance_share_file({
  "filePath": "<本地音视频绝对路径>",
  "label": "<展示名，如 会议录音>",
  "expireHours": 24
})
→ structuredContent.url = "https://keepermac.huo15.com/plugins/enhance-share/<token>-meeting.mp4"

若用户已提供可公网访问的 URL，可跳过 enhance_share_file；若工具不可用或失败，如实告知用户并降级（勿伪造 URL）。

百炼支持的音视频格式（不必先转 MP3）

百炼录音文件识别支持多种音视频格式（不限 MP3），见官方说明：

aac、amr、avi、flac、flv、m4a、mkv、mov、mp3、mp4、mpeg、ogg、opus、wav、webm、wma、wmv

  • mp4 / mkv / mov 等视频可直接提交（服务端处理音轨），默认无需本地先抽音频再转 MP3。
  • 单文件：≤ 2GB、≤ 12 小时；启用说话人分离时建议 ≤ 2 小时。
  • 格式变种众多，不保证每一种都能识别成功；若失败再考虑 可选本地转码。

总流程（决策树）

  1. 确认引擎：本 skill 固定 asr_engine: bailian_paraformer（默认模型 paraformer-v2）。

  2. 识别输入

    • .tty → 转交 huo15-openclaw-asr 的 .tty 分支（百炼不做终端录屏解析）。
    • 音视频 → 继续本流程。

  3. 是否本地转码（默认：否）

    • 默认：源文件扩展名属于格式列表 → 不跑 ffmpeg，直接进入步骤 4。
    • 仅在下述情况再本地转码（见 可选本地转码）：格式不在列表、百炼返回失败/无识别结果、需说话人分离但为多声道、或用户要求压缩体积。
    • 不要为「百炼只认 MP3」而习惯性转码。

  4. 获得公网 URL（必做）

    • OpenClaw 标准路径：对步骤 2/3 得到的本地文件调用 enhance_share_file，使用返回的 structuredContent.url（域名 https://keepermac.huo15.com）。详见 百炼 URL 约束与 OpenClaw 公网分享。
    • 若用户已提供合法公网 URL，可跳过分享步骤。
    • 勿在 skill、脚本或对话中写入 DASHSCOPE_API_KEY；勿自行实现 enhance 插件。

  5. 调用百炼转写
    使用本目录脚本（推荐）：

    pip install dashscope
# 环境变量 DASHSCOPE_API_KEY 已设置
python scripts/transcribe_bailian.py --file-url "https://keepermac.huo15.com/plugins/enhance-share/..." -o verbatim.txt

    可选参数：

    • --model paraformer-v2（默认；方言/嘈杂场景可改 fun-asr，见百炼文档选型）
    • --diarization：说话人分离（仅单声道；多声道需先 ffmpeg -ac 1 混成单声道，不必强行转成 MP3）
    • --language-hints zh en（仅 paraformer-v2 等支持的模型）

  6. 结果检查（不做 Whisper 模型升级）

    • 任务状态须为 SUCCEEDED；原文非空。
    • 若明显乱码、大段空结果 → 提示用户换模型（如 fun-asr）或检查 URL/格式，不要编造纪要。

  7. 生成纪要 + OpenClaw 交付块
    严格基于原文；模板与 YAML 字段与 huo15-openclaw-asr 一致，但交付块须标明云端来源（见下节）。

  8. 可选落盘
    与 huo15-openclaw-asr 相同：询问后保存 Markdown（原文+纪要+交付块）或 Word（仅纪要，调用 huo15-openclaw-office-doc）。

可选本地转码（ffmpeg）

仅在需要时使用；百炼路线默认跳过本节。

情况建议
扩展名不在百炼支持列表转为 mp3 或 wav 等支持格式后，再 enhance_share_file 分享
百炼任务失败或识别结果为空先查 share URL 是否有效、百炼能否拉取；仍失败可试转码或换 fun-asr
--diarization 且源文件为多声道ffmpeg -i INPUT -ac 1 OUTPUT.wav（或其它支持格式），不必 MP3
减小上传体积可 ffmpeg 压成 mp3/aac 后再 enhance_share_file

转 MP3 可复用 huo15-openclaw-asr 脚本（仅当选择转 MP3 时）：

  • Windows：../huo15-openclaw-asr/scripts/transcode_mp3.ps1
  • Unix：../huo15-openclaw-asr/scripts/transcode_mp3.sh

凭证与环境

变量说明
DASHSCOPE_API_KEY百炼 API Key（配置到环境变量，禁止硬编码）

任务为异步：提交后排队，通常数分钟内完成；结果 JSON 的下载链接 24 小时有效（以官方说明为准）。

OpenClaw（龙虾）交付块

在 huo15-openclaw-asr 交付块基础上增加/固定下列字段：

---OPENCLAW_ASR_DELIVERY---
version: 1
asr_engine: bailian_paraformer
bailian_model: "<paraformer-v2 | fun-asr | ...>"
source_kind: audio_video
source_path: "<原始文件路径或标识>"
file_url: "<enhance_share_file 返回的 structuredContent.url，或用户提供的公网 URL>"
share_via: "enhance_share_file | user_provided_url"
local_transcode: "<none | 说明：如 ffmpeg 混单声道 wav；默认 none 表示直传原文件>"
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---

纪要模板、类型候选表：见 huo15-openclaw-asr · 纪要模板。

保存 Word（纪要）

与 huo15-openclaw-asr 相同：调用 huo15-openclaw-office-doc 的 create-word-doc.py，--doc-format 会议纪要。详见 选项 B：保存为 Word。

与 huo15-openclaw-asr 的分工小结

能力本 skillhuo15-openclaw-asr
百炼 Paraformer / Fun-ASR✔ 默认不实现，仅指向本 skill
公网 URL（enhance_share_file）✔ 标准✘
Whisper / WhisperX✘✔ 默认
.tty 终端日志✘✔
纪要 / 交付块 / 落盘✔（复用约定）✔

自检清单

  • 已确认用户同意云端转写。
  • 已配置 DASHSCOPE_API_KEY（未泄露到仓库或对话）。
  • 已通过 enhance_share_file 取得公网 URL（https://keepermac.huo15.com/...），或用户已提供合法 URL；未手写/拼接 share 链接。
  • 音频 URL 已提交百炼；默认未做不必要的本地转码。
  • 若曾本地转码：已在 local_transcode / notes_for_openclaw 中说明原因（格式、分轨、压缩等）。
  • 已用 transcribe_bailian.py 或等效 SDK 调用，任务 SUCCEEDED，原文非空。
  • 若启用说话人分离：音频为单声道。
  • 纪要严格来源于原文；已输出带 asr_engine: bailian_paraformer 的交付块。
  • 若保存 Word：已走 huo15-openclaw-office-doc。

附加资源

More in Data & APIs