any-video-to-text

---
name: any-video-to-text
description: 把视频链接或本地录音转成文字稿，全程在本机跑，不花钱、不上传。支持 B站/YouTube/抖音/微博/知乎/小红书/西瓜等 1700+ 视频站点，也支持本地会议录音、播客、课程录屏。自动适配机器：苹果自研芯片走 mlx-whisper，Windows/Linux/英特尔 Mac 走 faster-whisper，有英伟达显卡自动用显卡。可挂领域词表修正专业术语的同音字错误。Use when the user says 视频转文字、转成文字稿、把这条视频转了、B站转文字、抖音转写、录音转文字、会议录音整理、播客转文字稿、长视频抓重点、这个视频太长帮我转一下, 或发来一个视频链接/音频文件想要文字稿。
version: 1.0.0
license: MIT
metadata:
  openclaw:
    emoji: "🎙️"
    requires:
      bins:
        - ffmpeg
        - python3
      anyBins:
        - yt-dlp
    install:
      - kind: brew
        formula: ffmpeg
        bins: [ffmpeg]
      - kind: brew
        formula: yt-dlp
        bins: [yt-dlp]
---

<!--
本 skill 不需要任何 API Key、Token 或环境变量：模型在本机跑，音频不出本机。
frontmatter 里没有 requires.env / primaryEnv，就是因为确实一个都不需要。
-->


# any-video-to-text

视频链接或本地音视频 → **文字稿（纯文本 + 时间戳两版）**。

不调用任何云端接口，不需要密钥，不花钱，音频不出本机。

## 能转什么

**网上的**：B站（含收藏夹、合集、番剧）、YouTube、抖音、微博、知乎、小红书、西瓜视频、TikTok…… 底层用 yt-dlp，支持 1700 多个站点。

> 快手目前不支持。

**本机的**：会议录音、访谈、播客、课程录屏。`.mp3 .wav .m4a .aac .flac .ogg .opus / .mp4 .mov .mkv .avi .webm .flv` 都行。

这条是很多人真正需要的：**内部会议录音不能传给第三方接口**，本地跑就没这个顾虑。

## 装

```bash
pip install faster-whisper
brew install yt-dlp ffmpeg          # Windows 用 winget/scoop，或到官网下载
```

苹果自研芯片（M 系列）的 Mac 再装一个，会快很多：

```bash
pip install mlx-whisper
```

首次运行会自动下载模型（1～3 GB，看你选哪个），之后离线可用。

## 用

```bash
# 视频链接
python3 scripts/transcribe.py "https://www.bilibili.com/video/BVxxxxx"

# 本地录音
python3 scripts/transcribe.py ~/Desktop/周会录音.m4a

# 批量：清单文件里每行一个链接或路径
python3 scripts/transcribe.py --file links.txt

# 换更准的模型 / 换输出目录 / 关掉词表
python3 scripts/transcribe.py URL --model large
python3 scripts/transcribe.py URL --out ~/Documents/文字稿
python3 scripts/transcribe.py URL --prompt-file none

# 外语视频（默认按中文转，转英文/日文内容必须加这个）
python3 scripts/transcribe.py URL --lang auto
python3 scripts/transcribe.py URL --lang en
```

> 默认 `--lang zh`。**转 YouTube 上的英文内容记得改**，否则模型会硬按中文听，出来是乱码。

产物是一份 Markdown，默认落在 `./transcripts/`，含元信息、纯文字稿、时间戳稿。

## 模型怎么选

| `--model` | 实际模型 | 什么时候用 |
|---|---|---|
| `turbo`（默认） | large-v3-turbo | 日常够用，比 large 快好几倍 |
| `large` | large-v3 | 中文口音重、术语密、要引用原话 |
| `medium` / `small` | medium / small | 老机器、没有独立显卡、只要个大意 |

turbo 是 large-v3 的蒸馏版，参数量小一半多。**大部分场景听不出差别，赶时间就用它；要抠字眼就换 `large`。**

## 机器适配

脚本自己探测，一般不用管：

| 你的机器 | 走哪个后端 | 速度感受 |
|---|---|---|
| 苹果 M 系列芯片 | mlx-whisper（GPU） | 最快，40 分钟视频约 6 分钟 |
| Windows / Linux + 英伟达显卡 | faster-whisper（CUDA） | 快 |
| 英特尔芯片 Mac | faster-whisper（CPU） | 明显慢，建议用 `--model medium` |
| Windows / Linux 无独显 | faster-whisper（CPU） | 明显慢，建议用 `--model medium` |

想强制指定：`--backend mlx` 或 `--backend fw`。

## 复读过滤

片头音乐、静音段、纯背景噪音会让模型开始复读，吐出「谢谢大家 谢谢大家 谢谢大家…」
或者「字幕由XX提供」这类根本没人说过的话——这是 Whisper 的老毛病。

脚本会自动识别并滤掉这类片段，跑完告诉你滤了几段。正常的短句（「好的」「嗯，对」）不受影响。

## 领域词表

转专业内容时同音字错得离谱——「夏普比率」听成「下铺比率」。往模型里喂一段本领域词汇能明显改善。

自带 `prompts/finance.txt`（投资/量化）。换成你自己的：

```bash
python3 scripts/transcribe.py URL --prompt-file prompts/medical.txt
```

怎么写见 `prompts/README.md`。

## 给 Agent 的行为约定

1. 拿到链接或文件路径，直接跑 `scripts/transcribe.py`。
2. 跑完**读一遍文字稿，在对话里给用户补一段摘要 + 3-5 条核心要点**。要具体，不要堆词。
3. **产物只留在输出目录，不要自动写进用户的笔记库/知识库。** 用户明确说"这条存到 XX"时才另外写卡片。
4. 转写有错字是正常的，用户要引用原话时提醒他核对一下。

## 已知限制

- 快手不支持。
- 部分站点遇到风控需要登录态：给 yt-dlp 加 `--cookies-from-browser chrome`。
- 生僻词、人名、机构简称仍可能错，词表只降低概率不能根治。
- 默认按中文转写，外语内容要显式加 `--lang`。
- 复读过滤是启发式的，极端情况下可能误伤正常的重复强调句。
- 中英混说的内容，英文部分识别质量不如纯中文，把英文词写进词表能改善。

## 出处

底座参考了 ClawHub 上的 `douyin-video-to-txt`。本版本的改动：多后端自动适配、支持本地文件、可替换的领域词表、模型可选、输出目录可配置。