---
slug: "llm-provider-whisper-v1-tool-free"
name: "llm-provider-whisper-v1-tool-free"
version: "1.0.0"
displayName: "Whisper v1转录免费版"
summary: "Whisper v1稳定版本地转录工具,支持基础语音转文字与字幕生成,适合个人快速上手。。基于 Whisper v1 稳定版本的本地语音转文字工具(免费版)。核心能力: - v1 稳定版 C"
license: "Proprietary"
edition: "free"
description: |-
  基于 Whisper v1 稳定版本的本地语音转文字工具(免费版)。核心能力:
  - v1 稳定版 CLI 转录能力,接口简洁可靠
  - 支持 mp3 / m4a / wav 等常见音频格式
  - 输出 txt / srt / vtt 等多种字幕格式
  - 内置翻译模式(任意语言转英文)
  - 模型自动下载与本地缓存

  适用场景:
  - 个人播客录音转文字
  - 视频字幕快速生成
  - 会议录音整理为文字稿
  - 学习与采访内容转录

  差异化:
  - 基于 v1 稳定版,API 接口固化,适合长期维护
  - 完全本地运...
tags:
  - 创意设计
  - 语音转文字
  - 本地工具
  - 字幕生成
  - Whisper v1
  - 工具
  - 效率
  - 自动化
  - 知识
  - 文档
  - 创意
  - 图像
  - 写作
  - whisper
  - model
  - small
  - output_format
  - ffmpeg
tools:
  - read
  - exec
  - write
homepage: ""
category: "Automation"
---
# 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`参数进行配置.
**输入**: 用户提供核心功能执行所需的指令和必要参数.
**处理**: 解析核心功能执行的输入参数,完成核心逻辑,返回结构化响应.
**输出**: 返回核心功能执行的响应数据,包含状态码、结果和日志.
- 执行此能力时使用`input_params`参数,支持创建/查询/导出操作

### 参数配置与调用
用`config_options`参数进行配置.
**输入**: 用户提供参数配置与调用所需的指令和必要参数.
**处理**: 解析参数配置与调用的输入参数,完成核心逻辑,返回结构化响应.
**输出**: 返回参数配置与调用的响应数据,包含状态码、结果和日志.
- 执行此能力时使用`config_options`参数,支持修改/重置/导入操作

### 结果处理与输出
用`output_format`参数进行配置.
**输入**: 用户提供结果处理与输出所需的指令和必要参数.
**处理**: 解析结果处理与输出的输入参数,完成核心逻辑,返回结构化响应.
**输出**: 返回结果处理与输出的响应数据,包含状态码、结果和日志.
- 执行此能力时使用`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 完全本地运行,**基础LLM由Agent平台提供**
- 模型首次使用时自动下载,后续离线可用
- 不依赖 llm-provider API 或其他云服务

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

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

## 已知限制

- 本地运行，不支持多设备同步