trx 转录技能

trx 转录技能 是做什么的？

通过 Whisper 转录来自 URL 或本地文件的媒体，清理音频，并返回适合 AI 工作流的 JSON 数据。

概述

trx (转录) 技能允许 AI 代理将音频或视频文件中的语音转录为文本。它使用 Whisper 模型进行语音识别，并在转录前对音频进行预处理（如降噪）以获得更佳效果。输出是结构化的 JSON，包含时间戳、置信度分数以及可选的说话人识别信息，便于直接集成到 AI 工作流中。

平台支持

• Claude Code
• Cursor
• Codex
• 其他通过 shell 命令支持的 AI 代理平台

要求

• 安装 ffmpeg (用于音频提取和转换)
• 安装 openai-whisper Python 包 (建议使用 pip install openai-whisper)
• 对于本地文件，代理需有读取权限
• 对于 URL，代理需有网络访问权限

使用

从 URL 转录

# 转录远程文件
trx https://example.com/audio.mp3

从本地文件转录

# 转录本地文件
trx /path/to/meeting-recording.mp4

选项

• --model：选择 Whisper 模型大小 (tiny, base, small, medium, large)。默认: base。
• --language：指定音频语言代码（例如 en, zh）。默认: 自动检测。
• --speakers：启用简单说话人识别 (实验性)。
• --no-clean：跳过音频清理步骤。
• --output：指定输出 JSON 文件路径；默认为标准输出。

输出格式

转录结果以 JSON 形式返回，结构如下：

{
  "source": "source.mp3",
  "duration_seconds": 120.5,
  "language": "en",
  "segments": [
    {
      "start": 0.0,
      "end": 2.5,
      "text": "Hello, and welcome to this meeting.",
      "confidence": 0.98,
      "speaker": null
    },
    {
      "start": 2.5,
      "end": 6.0,
      "text": "Today we are discussing the new project.",
      "confidence": 0.95,
      "speaker": null
    }
  ],
  "full_text": "Hello, and welcome to this meeting. Today we are discussing the new project."
}

工作原理

1. 技能接收媒体文件的 URL 或本地路径。
2. 使用 ffmpeg 提取音频并转换为 16kHz WAV 格式。
3. 对音频进行降噪和音量归一化 (除非指定 --no-clean)。
4. 使用 Whisper 模型进行转录。
5. 将结果格式化为 JSON 并输出。

环境变量

• WHISPER_MODEL_DIR：Whisper 模型的缓存目录。默认为 ~/.cache/whisper。
• FFMPEG_PATH：ffmpeg 可执行文件的路径。默认为系统 PATH 中搜索。

故障排除

• 错误: ffmpeg not found：请安装 ffmpeg (sudo apt install ffmpeg 或 brew install ffmpeg)。
• 错误: Out of memory：尝试使用更小的模型 (--model tiny 或 --model base)。
• 转录质量差：确保音频清晰，尝试使用 large 模型，或手动指定语言 (--language zh)。
• URL 下载失败：检查 URL 的可访问性以及代理的网络设置。

许可证

MIT