Llm Provider Whisper V1 Tool Free

SKILL.md

---
name: "llm-provider-whisper-v1-tool-free"
description: "Whisper v1稳定版本地转录工具,支持基础语音转文字与字幕生成,适合个人快速上手。"
license: Proprietary
allowed-tools: read exec
compatibility: "Requires LLM with tool-use capability"
metadata:
  displayName: "Whisper v1转录免费版"
  version: "1.0.0"
  summary: "Whisper v1稳定版本地转录工具,支持基础语音转文字与字幕生成,适合个人快速上手。"
  tags:
    - "创意设计"
    - "语音转文字"
    - "本地工具"
    - "字幕生成"
    - "Whisper v1"
  source: "SkillHub"
  converted_at: "2026-07-22T17:58:36"
---

# Whisper v1 语音转文字工具 - 免费版

## 概述

Whisper v1 语音转文字工具(免费版)基于 Whisper v1 稳定版本,提供简洁可靠的本地语音转文字能力。v1 版本接口固化、行为稳定,适合需要长期维护与脚本化的个人用户。

免费版聚焦核心转录能力,专业版(`llm-provider-whisper-v1-tool-pro`)在此基础上提供批量处理、模型管理、性能调优与服务化部署等高级能力。

## 核心能力

| 能力 | 免费版 | 说明 |
|:-----|:-------|:-----|
| 单文件转录 | 支持 | v1 稳定 CLI 接口 |
| 输出格式 | txt/srt/vtt/json | 覆盖常见字幕需求 |
| 翻译模式 | 支持 | 音频转英文文本 |
| 模型选择 | tiny/base/small | 轻量模型优先 |
| 自动语言检测 | 支持 | 省略 `--language` 自动识别 |
| 模型缓存 | 支持 | 首次下载后离线可用 |
| 批量处理 | 不支持 | 升级专业版 |
| 模型管理 | 不支持 | 升级专业版 |
| 性能调优 | 不支持 | 升级专业版 |

### 核心功能执行
用`input_params`参数进行配置。

**输入**: 用户提供核心功能执行所需的指令和必要参数。
**处理**: 按照skill规范执行核心功能执行操作,遵循单一意图原则。
**输出**: 返回核心功能执行的执行结果,包含操作状态和输出数据。
- 执行此能力时使用`input_params`参数,支持创建/查询/导出操作

### 参数配置与调用
用`config_options`参数进行配置。

**输入**: 用户提供参数配置与调用所需的指令和必要参数。
**处理**: 按照skill规范执行参数配置与调用操作,遵循单一意图原则。
**输出**: 返回参数配置与调用的执行结果,包含操作状态和输出数据。
- 执行此能力时使用`config_options`参数,支持修改/重置/导入操作

### 结果处理与输出
用`output_format`参数进行配置。

**输入**: 用户提供结果处理与输出所需的指令和必要参数。
**处理**: 按照skill规范执行结果处理与输出操作,遵循单一意图原则。
**输出**: 返回结果处理与输出的执行结果,包含操作状态和输出数据。
- 执行此能力时使用`output_format`参数,支持导出/保存/转换操作
**能力覆盖范围**：本skill的核心能力覆盖以下场景关键词：Whisper、稳定版本地转录工、支持基础语音转文、字与字幕生成、适合个人快速上手、稳定版本的本地语、音转文字工具、核心能力、稳定版、转录能力、接口简洁可靠、wav、等常见音频格式、等多种字幕格式、内置翻译模式、任意语言转英文、模型自动下载与本、地缓存等。这些关键词对应description中声明的使用场景,均已在上述能力点中提供对应的操作支持。

## 使用场景

### 场景一:个人播客转录

将播客录音转为文字稿,便于检索与归档。

```bash
# 转录为纯文本
whisper podcast_ep01.mp3 --model small --output_format txt --output_dir ./transcripts/

# 生成带时间戳的字幕
whisper podcast_ep01.mp3 --model small --output_format srt --output_dir ./subtitles/
```

### 场景二:学习视频字幕

为学习视频生成中文字幕。

```bash
# 提取音频
ffmpeg -i lecture.mp4 -vn -ar 16000 -ac 1 -c:a pcm_s16le lecture.wav

# 转录中文字幕
whisper lecture.wav --model small --language zh --output_format srt --output_dir ./subs/
```

### 场景三:多语言音频翻译

将外语音频翻译为英文便于阅读。

```bash
# 翻译模式(输出英文)
whisper french_interview.m4a --task translate --model base --output_format txt
```

## 不适用场景

以下场景Whisper v1转录免费版不适合处理：

- 专业医学法律翻译认证
- 同声传译
- 文学创作翻译

## 触发条件

需要文本翻译、多语言转换、本地化处理时使用。不适用于非本工具能力范围的需求。

## 快速开始

1. 阅读## 核心能力章节了解skill功能
2. 按## 依赖说明配置环境
3. 执行所需能力对应的命令
4. 参考## 错误处理章节处理异常
5. 查看## FAQ解答常见疑问

### 依赖详情

```bash
# pip 安装
pip install -U llm-provider-whisper

# 验证版本
whisper --help
```

### 2. 安装 FFmpeg

```bash
# macOS
brew install ffmpeg

# Ubuntu / Debian
sudo apt install ffmpeg

# Windows
scoop install ffmpeg
```

### 3. 首次转录

```bash
whisper audio.mp3 --model tiny --output_format txt --output_dir .
```

首次运行自动下载模型到 `~/.cache/whisper/`。

## 示例

### v1 标准命令模板

```bash
# 标准转录
whisper <input> --model <model> --task transcribe --language <lang> --output_format <fmt> --output_dir <dir>

# 翻译模式
whisper <input> --model <model> --task translate --output_format <fmt> --output_dir <dir>
```

### 模型选择建议

| 模型 | 参数量 | 适用场景 | 免费版推荐 |
|:-----|:-------|:---------|:-----------|
| tiny | 39M | 快速预览、实时场景 | 推荐 |
| base | 74M | 清晰录音、简单内容 | 推荐 |
| small | 244M | 日常使用、中文转录 | 推荐 |
| medium | 769M | 专业转录、高准确度 | 可用(较慢) |
| large | 1550M | 最高精度需求 | 可用(很慢) |

免费版推荐 `tiny` / `base` / `small`,平衡速度与准确度。更高精度需求建议升级专业版启用 GPU 加速。

### 输出格式说明

| 格式 | 用途 | 特点 |
|:-----|:-----|:-----|
| txt | 纯文本阅读 | 无时间戳,最简洁 |
| srt | 视频字幕 | 通用字幕格式,带时间戳 |
| vtt | Web 字幕 | HTML5 视频兼容 |
| json | 程序处理 | 含完整时间戳与置信度 |
| tsv | 数据分析 | 表格格式,便于 Excel |

## 最佳实践

1. **音频预处理**
   - 转为 16kHz 单声道,匹配模型训练数据
   - 降噪可显著提升准确度
   - 长音频分段处理,避免内存溢出

```bash
# 标准预处理
ffmpeg -i input.mp3 -ar 16000 -ac 1 -c:a pcm_s16le normalized.wav
whisper normalized.wav --model small --language zh
```

2. **语言指定策略**
   - 已知语言时显式指定 `--language`,跳过检测加速
   - 中文:`--language zh`
   - 英文:`--language en`
   - 多语种:省略,自动检测

3. **v1 稳定性优势**
   - v1 版本 CLI 接口固化,脚本可长期复用
   - 模型行为一致,升级不破坏现有流程
   - 适合集成到自动化脚本与 CI/CD 流水线

4. **成本控制**
   - 免费版完全本地运行,零 API 成本
   - 模型下载一次,永久离线使用
   - 无调用次数限制

## 常见问题

### Q1: v1 版本与其他 Whisper 版本有何不同?

v1 是稳定版本,CLI 接口与模型行为经过充分验证,适合长期维护的生产脚本。后续版本可能引入新特性,但 v1 保证向后兼容。

### Q2: 模型下载缓慢怎么办?

模型托管在 Hugging Face,可手动下载 `.pt` 文件放入 `~/.cache/whisper/`。文件名格式如 `small.pt`、`base.pt`。

### Q3: 转录准确度不理想?

- 升级到更大的模型(`small` 或 `medium`)
- 预处理音频:降噪、标准化采样率
- 显式指定 `--language`
- 专业术语多的场景建议升级专业版,使用 `initial_prompt` 自定义词典

### Q4: 免费版与专业版的区别?

免费版聚焦单文件转录,CPU 推理;专业版支持批量处理、GPU 加速、模型管理与服务化部署。如需高吞吐或自动化,建议升级。

### Q5: 是否支持实时转录?

免费版仅支持文件级离线转录。实时流式转录属于专业版特性。

## 依赖说明

### 运行环境
- **Agent 平台**: 支持SKILL.md的任意AI Agent(ai-assistant Code / Cursor / Codex / Gemini CLI等)
- **操作系统**: Windows / macOS / Linux
- **Python**: 3.9 及以上
- **硬件**: CPU 即可运行(GPU 可选加速)

### 第三方依赖

| 依赖项 | 类型 | 是否必需 | 获取方式 |
|:-------|:-----|:---------|:---------|
| llm-provider-whisper | Python 库 | 必需 | `pip install -U llm-provider-whisper` |
| ffmpeg | 系统工具 | 必需 | `brew install ffmpeg` / `apt install ffmpeg` |
| PyTorch | Python 库 | 必需 | 随 whisper 自动安装 |
| Python 3.9+ | 运行时 | 必需 | `python.org` 下载 |
| LLM API | API | 必需 | 由Agent内置LLM提供 |

### API Key 配置
- 本 Skill 完全本地运行,**无需任何 API Key**
- 模型首次使用时自动下载,后续离线可用
- 不依赖 llm-provider API 或其他云服务

### 可用性分类
- **分类**: MD+EXEC(纯Markdown指令,部分功能需exec命令行执行)
- **说明**: 基于Markdown的AI Skill,通过自然语言指令驱动Agent完成操作。免费版基于 v1 稳定版本,接口固化,适合长期维护的个人转录场景。

## 错误处理


| 错误场景 | 原因 | 处理方式 |
|---------|------|---------|
| 配置错误 | 参数缺失或格式错误 | 检查依赖说明中的配置要求 |
| 运行时错误 | 运行环境不满足 | 确认运行环境符合依赖说明 |
| 网络错误 | 连接超时或不可达 | 执行ping命令测试网络连通性,检查防火墙和代理设置连接后执行ping命令测试网络连通性,检查防火墙和代理设置连接后重新执行命令，参考国内替代方案 |

## 已知限制

- 需要API Key，无Key环境无法使用
- 本地运行，不支持多设备同步