# Audio Universal

> 语音转文字工具，将音频文件转录为文本。原生 transcription 端点优先，失败自动降级为 chat completions（适配非标准语音识别模型）。支持多语言和时间戳。

- Skill: `kesepain-ke/audio-universal` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add kesepain-ke/audio-universal`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kesepain-ke/audio-universal/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: kesepain-ke (https://skillmd.com/u/kesepain-ke)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/kesepain-ke/audio-universal

---


# 语音转文字 (Audio Universal)

将音频文件转录为带可选时间戳的文本。支持多种语言和引导词。

## 插件路径

`plugins/audio_universal/`

## 工作方式

1. **原生 transcription 端点** → `client.audio.transcriptions.create()`（whisper-1 等标准模型）
2. 失败时自动降级为 **chat completions** → 音频 base64 编码后作为多模态消息发送给专用模型

## 模型优先级

`audio_transcription_model`（config.json 专用配置）> `"whisper-1"`（默认）

配置后优先使用专用模型；不配则使用 whisper-1 走原生端点。

## 注册工具

| 工具名 | 描述 |
|--------|------|
| `audio_transcribe` | 将音频文件转录为文本，支持语言指定、引导词和时间戳 |

## 参数

| 参数 | 类型 | 必需 | 默认值 | 说明 |
|------|------|------|--------|------|
| `audio` | string | 是 | — | 音频文件路径（本地文件） |
| `language` | string | 否 | 自动检测 | 语言代码（如 `zh`、`en`、`ja`）。由智能体自行传入合适的语言代码，留空自动检测 |
| `prompt` | string | 否 | — | 引导词，帮助适应特定风格或上下文词汇 |
| `timestamp_granularity` | string (enum) | 否 | `"segment"` | `none`=纯文本、`segment`=段落级时间戳、`word`=单词级时间戳 |

## 结果说明

- 成功：返回转录文本（纯文本或带时间戳格式，取决于 `timestamp_granularity`）
- 失败：返回 `ERROR:` 前缀的错误信息
- 能力不支持：提示需要切换 provider 或配置 `capabilities_override: ["audio_transcription"]`

## 支持的服务商

- **OpenAI 官方** — 原生 transcription 端点（whisper-1）
- **OpenRouter / 其他兼容厂商** — 配 `audio_transcription_model` 后通过 chat 降级调用
- **不支持时** — 可通过 `capabilities_override: ["audio_transcription"]` 显式开启

## 典型场景

- 会议录音转文字
- 语音消息转录
- 播客/采访转写
- 外语音频翻译前预处理

## 常见规范

- 已知语种时明确传入 `language` 参数可提升转录准确率，留空则自动检测
- `prompt` 引导词对专有名词、人名、技术术语的识别效果显著
- 音频文件需存在于本地文件系统

## 常见处理办法

- **转录结果不理想**：尝试传入 `prompt` 引导词，包含关键术语的正确写法
- **文件不存在报错**：检查路径是否正确，确认文件已上传到 `users/<user>/history/file/`
- **能力不支持**：检查 provider 配置，确认 `audio_transcription_model` 已设置

## 常见教训

- `timestamp_granularity` 选择 `word` 时输出可能非常庞大，仅在实际需要词级时间戳时使用
- chat 降级路径使用 `input_audio` 多模态格式发送音频，部分非标准模型可能不兼容
- provider 上下文缺失时工具直接报错，需重新进入会话