# Tingwu Asr

> 使用阿里云通义听悟进行云端音频/视频转录。本技能应在用户需要云端语音转文字、长音频转录、本地 FunASR 不可用或需要更高精度时使用。不适用于无网络环境或需要完全离线的场景。

- Skill: `cat-xierluo/tingwu-asr` (Agent Skill, multi-file: 20 files)
- Install (CLI): `npx skillmds@latest add cat-xierluo/tingwu-asr`
- Raw SKILL.md: https://api.skillmd.com/api/skills/cat-xierluo/tingwu-asr/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: MIT
- Author: cat-xierluo (https://skillmd.com/u/cat-xierluo)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/cat-xierluo/tingwu-asr

---


# 通义听悟云端转录 (tingwu-asr)

通过逆向封装通义听悟网页端内部 REST API，实现云端音频/视频文件转录，输出与 `funasr-transcribe` 兼容的 Markdown 格式。

## 功能

- 上传本地音频/视频文件到阿里云 OSS
- 云端转录，支持说话人分离（单人/2人/多人）
- 支持中文、英文、日文、粤语、中英文混合
- 输出 funasr-transcribe 兼容的 Markdown，可直接用 `summary.py` 注入 AI 总结

## 依赖

- Python 3.8+
- `requests` (必须) — HTTP 请求
- `oss2` (必须) — 阿里云 OSS SDK（STS 直传）
- `playwright` (登录时) — 内置登录脚本 `login_pw.py` 使用（`pip3 install playwright && playwright install chromium`）

安装:
```bash
pip3 install -r skills/tingwu-asr/config/requirements.txt
```

## 首次使用：登录（首选：内置 Playwright 脚本）

**方式一（推荐）**：skill 内置 `login_pw.py`，一条命令完成"开浏览器 → 自动填凭证 → 等
登录 → cookie 落盘"：

```bash
python3 skills/tingwu-asr/scripts/login_pw.py
```

- 凭证从 `config/.env` 读取（从 `config/.env.example` 复制填写）
- 浏览器以可见窗口打开；若出现滑块/验证码，人工在窗口内完成即可，脚本自动轮询等待
- 脚本通过 `context.cookies()` 取 cookie（含 HttpOnly 的 `login_aliyunid_ticket`），
  **直接写入** `config/cookies.json`，cookie 值不经过 stdout/对话记录
- 完成后可用 `check_auth.py` 验证登录态

**方式二（备用）**：Agent 用 MCP Playwright 浏览器工具手工流程：

1. 用 MCP Playwright 打开 `https://tingwu.aliyun.com/home`
2. 如果跳转到登录页，用账号密码或扫码登录
3. 登录成功后，将提取的 cookie 保存到文件（注意 `document.cookie` 拿不到 HttpOnly
   cookie，仅作兜底）：
   ```bash
   python3 skills/tingwu-asr/scripts/login.py --save-cookies '{"cna":"xxx",...}'
   ```

账号密码可预配置在 `config/.env` 文件中（从 `config/.env.example` 复制）。

## 每日签到（领取免费额度）

每天登录听悟网页可领取 2 小时免费转录额度。Agent 签到流程：

1. 运行内置登录脚本（会打开 `https://tingwu.aliyun.com/home` 触发每日额度并保存 Cookie）：
   ```bash
   python3 skills/tingwu-asr/scripts/login_pw.py
   ```
2. 运行检查脚本确认状态：
   ```bash
   python3 skills/tingwu-asr/scripts/daily_checkin.py
   ```

可在 OpenClaw 中配置定时任务，让 Agent 每天自动执行此流程。

## Agent 工作流

当用户要求转录音频/视频文件时，执行以下步骤：

### 1. 检查登录状态

```bash
python3 skills/tingwu-asr/scripts/check_auth.py
```

如果返回"无效"，先运行 `login.py`。

### 2. 执行转录

```bash
# 直接给链接(自动 yt-dlp 下载,默认多人分离):小宇宙/YouTube/B站等
python3 skills/tingwu-asr/scripts/transcribe.py "https://www.xiaoyuzhoufm.com/episode/xxx"

# 单文件转录(默认多人分离)
python3 skills/tingwu-asr/scripts/transcribe.py /path/to/audio.mp3 --lang cn

# 多文件并行转录（自动保存到文件所在目录 + archive 目录）
python3 skills/tingwu-asr/scripts/transcribe.py /path/to/audio1.mp3 /path/to/audio2.mp3 /path/to/video.mp4

# 批量转录目录下所有文件（并行）
python3 skills/tingwu-asr/scripts/transcribe.py /path/to/media_folder/ --batch

# 指定并行数（默认3）
python3 skills/tingwu-asr/scripts/transcribe.py /path/to/audio1.mp3 /path/to/audio2.mp3 --parallel 5
```

参数说明:
- `paths` 音频/视频文件路径**或链接**（http(s) 开头自动用 yt-dlp 下载到临时目录；支持小宇宙/YouTube/B站等；支持多个混用）
- `--lang cn` 语言: cn(中文,默认) / en(英文) / ja(日文) / cant(粤语) / cn_en(中英混合)
- `--speakers` 说话人分离: 2=区分发言人(**默认**,实测唯一有效值,分 2 人) / 0=不区分 / 1=单人。**注:3 与 4 实测均无效(不分离),原"4=多人"为误注**
- `--batch` 批量转录目录下所有文件
- `--parallel N` 并行转录的最大文件数 (默认: 3)
- `--force` 强制重新上传，即使该文件已有转录结果（默认会跳过已转录的文件）
- `-o output.md` 指定输出路径（单文件模式）
- `--no-archive` 不保存归档
- `--no-lab` 不获取智能分析（关键词/议程/重点等）
- `--ppt` 下载 PPT 幻灯片图片并嵌入 Markdown（仅视频有效）

**关于「给链接转写」与说话人分离（重要设计取舍）**：传入链接时，skill 走「yt-dlp 下载 → 本地上传」路径，以保证说话人分离生效。听悟网页端的「播客链接转写」(底层 net_source 网络源通道)虽能省本地带宽，但实测其「区分发言人」选项不生效（提交时 roleSplitNum 被强制为 0，不做分离）。此外经实测，听悟 roleSplitNum **仅 `2` 为有效分离值（分 2 人）**，`0/1/3/4` 均不分离（原 skill 注释"4=多人"为误注，已更正）。故 skill 默认 `--speakers 2` 走本地上传通道，换取可靠的 2 人分离，代价是下载+上传的带宽。如只需纯文字稿不在乎分离，可自行调用听悟网页端播客链接转写。

### 3. 输出说明

转录结果会同时保存到两个位置：
1. **源文件所在目录**：例如 `/path/to/audio.mp3` → `/path/to/audio.md`
2. **archive 归档目录**：`archive/YYYYMMDD_HHMMSS_audio/audio.md`

这样做的好处是：
- 源文件目录方便直接访问
- archive 目录便于集中管理和备份

**PPT 幻灯片**: 视频文件会自动提取 PPT 幻灯片，图片保存在 `{文件名}_slides/` 子目录中（每个文件独立目录，避免同目录下多视频冲突）。

### 3. 生成 AI 总结（复用 funasr-transcribe）

转录完成后，复用 funasr-transcribe 的 summary 模块:
```bash
python3 skills/funasr-transcribe/scripts/summary.py inject transcript.md summary.json
python3 skills/funasr-transcribe/scripts/summary.py verify transcript.md
```

## 文件结构

```
skills/tingwu-asr/
  SKILL.md              ← 本文件
  scripts/
    tingwu.py           ← 核心 API 客户端
    transcribe.py       ← CLI 入口
    format_output.py    ← 听悟 JSON → Markdown 转换
    login.py            ← Cookie 保存工具
    daily_checkin.py    ← 额度检查 + 记录
    check_auth.py       ← 认证检查
  config/
    .env                ← 账号密码凭证（gitignore，不提交）
    .env.example        ← 账号密码模板
    cookies.json        ← 登录 Cookie（gitignore，不提交）
    cookie.example.json ← Cookie 文件模板
    quota_history.jsonl ← 额度变更记录（gitignore，不提交）
    requirements.txt    ← Python 依赖
  references/           ← API 文档和决策记录
  archive/              ← 转录结果归档
```

## 异步转录模式（推荐用于长视频）

对于 1 小时以上的长视频，转录可能需要 20-30 分钟。使用异步模式上传后立即返回，后台自动轮询。

### 1. 异步提交

```bash
python3 skills/tingwu-asr/scripts/transcribe.py /path/to/video.mp4 --async --speakers 2
```

上传完成后立即返回任务 ID，任务信息保存到 `config/pending_tasks.json`。

### 2. 后台监控（Claude Code 增强模式）

提交后，用 `Bash` 工具的 `run_in_background` 启动后台监控：

```
command: "python3 skills/tingwu-asr/scripts/poll_tasks.py --monitor --timeout 3600 --interval 120"
run_in_background: true
timeout: 600000
```

**注意**：`timeout` 必须设为 `600000`（10 分钟），否则默认 2 分钟会超时。

监控完成后会自动收到通知，此时展示转录结果路径给用户。

### 3. 手动查询

```bash
# 检查所有待处理任务的状态
python3 skills/tingwu-asr/scripts/poll_tasks.py

# 阻塞式监控
python3 skills/tingwu-asr/scripts/poll_tasks.py --monitor
```

## 注意事项

- Cookie 会过期，过期后需重新运行 `login.py`
- 网页端免费额度有限，大文件或高频使用可能触发风控
- 支持格式: mp3/wav/m4a/wma/aac/ogg/amr/flac/aiff/mp4/wmv/mov/mkv/webm/avi 等
- 音频最大 500M，视频最大 6G，单文件最长 6 小时