设置

首次使用时，请阅读 references/whisper-models.md 和 references/troubleshooting.md。
确保已安装以下依赖项：ffmpeg、python3，以及所需的 Python 包（openai-whisper，deepgram-sdk 为可选）。

适用场景

• 用户发送语音备忘录 / 音频文件 / 视频文件，需进行转录。
• 需要同时归档原始音频与文字稿。
• 需要说话人识别功能（若使用支持说话人分离的 Deepgram）。
• 无需调用外部 API 的快速本地转录（Whisper）。

架构

所有持久化数据存储于 ~/voice-transcriber/ 目录下。目录结构如下：

~/voice-transcriber/
├── memory.md          # 提供方偏好、默认配置、历史记录
├── transcripts/       # 已保存的文字稿（txt、json、srt 格式）
├── audio/             # 已保存的原始音频文件
└── temp/              # 处理工作区（自动清理）

速查表

核心规则

1. 输入类型识别

转录前需完成以下判断：

• 本地文件路径 → 验证路径存在，并检查格式（mp3、wav、m4a、mp4 等）
• URL → 下载至 temp/ 目录后处理
• 语音备忘录 → 通常为单说话人、时长较短
• 会议 / 访谈录音 → 往往含多位说话人，建议启用说话人分离（diarization）

2. 根据上下文选择提供方

3. 长音频处理

文件大小超过 25 MB 或时长超过 2 小时：

1. 使用 ffmpeg 切分音频（参见 scripts/transcribe.py --split）
2. 逐段处理各音频片段
3. 合并各段文字稿，并保留正确的时间戳

4. 产物保存

转录成功后：

• 将文字稿保存至 ~/voice-transcriber/transcripts/，并采用有意义的文件名
• 如用户要求归档，将原始音频保存至 ~/voice-transcriber/audio/
• 在 memory.md 中更新本次操作的日期、文件名、提供方、音频时长等信息

5. 输出格式

默认输出纯文本（.txt），同时支持以下格式选项：

• .txt —— 清洁文本，不含时间戳
• .srt / .vtt —— 带时间轴的字幕格式
• .json —— 结构化数据：Deepgram 输出词级时间戳；Whisper 输出片段级时间戳

常见陷阱

• 假设单一提供方适用于所有场景 → Whisper 不支持说话人分离；Deepgram 需要 API 密钥。
• 直接上传超大文件 → 易触发超时错误。务必先切分。
• 忽略音频质量 → 噪声较大的音频可能需预处理（例如使用 ffmpeg 进行降噪）。
• 未确认语言类型 → Whisper 支持自动语言检测，但在混合语言内容中可能失效。
• 忘记保存原始音频 → 用户可能需要归档原始文件。

依赖要求

必需依赖：

• ffmpeg（用于音频格式转换与切分）
• python3 + pip
• Python 包：openai-whisper（本地 Whisper）、requests（若启用 Deepgram）

可选 API 密钥（仅 Deepgram 使用时需要）：

• DEEPGRAM_API_KEY —— 用于 Deepgram Nova‑3（支持说话人分离）

本地 Whisper 无需任何 API 密钥即可运行。

提供方速查

本地 Whisper（无需 API 密钥）

# 安装
pip install openai-whisper

# 基础转录（通过脚本）
python3 scripts/transcribe.py --file audio.wav --provider whisper --model base

# 输出格式：txt（默认）、srt、vtt、json
python3 scripts/transcribe.py --file audio.wav --provider whisper --model medium --format srt

模型性能由低到高依次为：tiny（最快）→ base → small → medium → large（最准确）。

Deepgram Nova‑3（需 API 密钥）

# 设置环境变量
export DEEPGRAM_API_KEY="your_key_here"

# 启用说话人分离的转录
python3 scripts/transcribe.py --file audio.wav --provider deepgram --diarize

# 输出带说话人标签的 JSON
python3 scripts/transcribe.py --file audio.wav --provider deepgram --format json

音频预处理

从视频中提取音频

ffmpeg -i video.mp4 -vn -acodec pcm_s16le -ar 16000 -ac 1 audio.wav

降噪处理

ffmpeg -i noisy.wav -af "afftdn=nf=-25" clean.wav

切分长音频（每段 10 分钟）

ffmpeg -i long.mp3 -f segment -segment_time 600 -c copy temp/chunk_%03d.mp3

安全与隐私

始终保留在本地的数据：

• 文字稿保存于 ~/voice-transcriber/transcripts/
• 原始音频保存于 ~/voice-transcriber/audio/
• 本地 Whisper 全程在设备端完成处理

若启用 Deepgram，则会离开本机的数据：

• 音频文件发送至 Deepgram API（api.deepgram.com）
• 返回的文字稿将在本地存储

本能力不会执行以下操作：

• 以明文形式存储 API 密钥（请使用环境变量）
• 未经确认自动上传文件
• 处理完成后在外部服务器上保留文件

外部端点

仅当用户显式选择 Deepgram 提供方时调用。本地 Whisper 不向任何外部服务发送数据。

记忆模板

请创建 ~/voice-transcriber/memory.md，内容结构如下：

# Voice Transcriber Memory

## Status
status: ongoing
version: 1.0.0
last: YYYY‑MM‑DD
integration: pending

## Context


## Notes


---
*Updated: YYYY‑MM‑DD*

相关能力

如用户确认，可通过 clawhub install 安装：

• speech-to-text-transcription —— 更广泛的音视频转录能力，支持更多提供方
• ffmpeg —— 高级音视频处理
• audio —— 通用音频操作

反馈

• 若本能力有用：clawhub star voice-transcriber
• 保持更新：clawhub sync