openclaw/skills/kb-whisper-diarization/SKILL.md

KB Whisper Diarization Skill

kb-whisper-diarization - 使用 Whisper + pyannote.audio 实现语音识别和说话者分离。

什么时候使用

当用户需要：

• 区分多个说话者（如访谈、对话）
• 获取带说话者标签的字幕
• 分析对话中谁说了什么

环境变量

在使用之前，必须检查环境变量是否已经设置。

变量名	用途	示例
WHISPER_CPP_PATH	whisper.cpp 安装路径	~/whisper.cpp
HF_TOKEN	HuggingFace Token	hf_xxx...

获取 HuggingFace Token（必需）

pyannote.audio 需要从 HuggingFace 下载模型，按以下步骤操作：

步骤 1: 注册/登录 HuggingFace

• 访问 https://huggingface.co
• 注册或登录账号

步骤 2: 申请模型访问权限 需要申请以下两个模型的访问权限（点击页面上的 "Access repository" 按钮）：

• https://huggingface.co/pyannote/speaker-diarization
• https://huggingface.co/pyannote/segmentation

⚠️ 申请后需要等待几分钟到几小时才能获得访问权限

步骤 3: 创建 Access Token

1. 访问 https://huggingface.co/settings/tokens
2. 点击 "New token"
3. 选择 "Read" 权限
4. 复制生成的 token（以 hf_ 开头）

步骤 4: 设置环境变量

# 添加到 ~/.kb_env 文件
echo 'export HF_TOKEN="hf_xxxxxxxxxxxxxxxxxxxxxx"' >> ~/.kb_env
source ~/.kb_env

# 验证
echo $HF_TOKEN

使用方法

# 基本用法（带说话者分离）
python whisper_diarization.py --input video.mp4

# 说话者分离
python whisper_diarization.py --input interview.mp4 --diarize

# 指定说话者数量
python whisper_diarization.py --input meeting.mp4 --diarize --num-speakers 2

# 指定语言
python whisper_diarization.py --input video.mp4 --language zh

命令参数

参数	说明	默认值
--input	输入音视频文件路径	必需
--output	输出目录	文件所在目录
--diarize	启用说话者分离	False
--num-speakers	估计说话者数量	None（自动检测）
--language	语言	自动检测
--model	Whisper 模型	base
--background	后台异步执行	False

模型选项

• Whisper 模型: tiny, base, small, medium, large
• 说话者分离: pyannote/speaker-diarization (需申请权限)

输出文件

对于输入 interview.mp4，将生成：

• interview.mp4.json - 完整结果（包含说话者标签）
• interview.mp4.txt - 纯文本
• interview.mp4.srt - 字幕格式（带说话者标签）

输出格式示例

JSON 格式

{
  "success": true,
  "input_file": "interview.mp4",
  "diarization": true,
  "speakers": ["SPEAKER_00", "SPEAKER_01"],
  "segments": [
    {
      "id": 0,
      "speaker": "SPEAKER_00",
      "start": 0.0,
      "end": 5.2,
      "text": "大家好，欢迎来到访谈节目"
    },
    {
      "id": 1,
      "speaker": "SPEAKER_01",
      "start": 5.2,
      "end": 10.8,
      "text": "谢谢邀请，我很荣幸"
    }
  ]
}

SRT 字幕格式

1
00:00:00,000 --> 00:00:05,200
[SPEAKER_00] 大家好，欢迎来到访谈节目

2
00:00:05,200 --> 00:00:10,800
[SPEAKER_01] 谢谢邀请，我很荣幸

安装

# 1. 安装依赖
pip install pyannote.audio torch

# 2. 设置 HuggingFace Token
export HF_TOKEN="hf_xxx..."

# 3. 首次运行会自动下载模型
python whisper_diarization.py --input test.mp4

注意事项

• 说话者分离需要申请权限: https://huggingface.co/pyannote/speaker-diarization
• 处理时间较长: 说话者分离会增加处理时间
• 对立体声效果更好: 多声道音频的分离效果更佳