---
slug: "llm-provider-whisper-tool-free"
name: "llm-provider-whisper-tool-free"
version: "1.0.0"
displayName: "Whisper语音转文字免费版"
summary: "本地Whisper CLI语音转文字工具,支持常见音频格式转录与翻译,无需API Key,适合个人使用。"
license: "Proprietary"
edition: "free"
description: |-
  基于 Whisper CLI 的本地语音转文字工具(免费版)。核心能力:
  - 本地音频转文字(transcription),无需 API Key
  - 支持 mp3 / m4a / wav / flac 等常见格式
  - 多种输出格式:txt / srt / vtt / json
  - 内置翻译模式(音频转英文)
  - 模型自动下载与缓存

  适用场景:
  - 个人播客/会议录音转文字
  - 视频字幕生成
  - 学习笔记与采访整理
  - 离线环境下的语音转写

  差异化:
  - 免费版聚焦单文件转录核心能力
  - 完全本...
tags:
  - 创意设计
  - 语音转文字
  - 本地工具
  - 字幕生成
  - Whisper
  - 工具
  - 效率
  - 自动化
  - 创意
  - 图像
  - 知识
  - 文档
  - 开发
  - whisper
  - ffmpeg
  - small
  - install
  - output_format
tools:
  - read
  - exec
  - write
homepage: ""
category: "Automation"
---
# Whisper 语音转文字工具 - 免费版

## 概述

Whisper 语音转文字工具(免费版)基于 llm-provider 开源的 Whisper 模型,提供完全本地化的语音转文字能力。无需 API Key、无需联网(首次下载模型后),适合个人用户处理播客录音、会议纪要、视频字幕等场景.
免费版聚焦单文件转录的核心能力,专业版(`llm-provider-whisper-tool-pro`)在此基础上提供批量处理、多模型管理、GPU 加速与自定义词典等高级能力.
## 核心能力

| 能力 | 免费版 | 说明 |
|---|---|---|
| 单文件转录 | 支持 | mp3/m4a/wav/flac 等 |
| 输出格式 | txt/srt/vtt/json | 满足常见字幕需求 |
| 翻译模式 | 支持 | 音频转英文文本 |
| 模型选择 | tiny/base/small | 轻量模型优先 |
| 自动下载模型 | 支持 | 首次使用自动拉取 |
| 批量处理 | 不支持 | 升级专业版 |
| GPU 加速 | 不支持 | 升级专业版 |
| 自定义词典 | 不支持 | 升级专业版 |
| 说话人分离 | 不支持 | 升级专业版 |

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

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

### 结果处理与输出
用`output_format`参数进行配置.
**输入**: 用户提供结果处理与输出所需的指令和必要参数.
**处理**: 解析结果处理与输出的输入参数,完成核心逻辑,返回结构化响应.
**输出**: 返回结果处理与输出的响应数据,包含状态码、结果和日志.
- 执行此能力时使用`output_format`参数,支持导出/保存/转换操作
**能力覆盖范围**：本skill的核心能力覆盖以下场景关键词：Whisper、CLI、语音转文字工具、支持常见音频格式、转录与翻译、API、Key、适合个人使用、的本地语音转文字、核心能力、本地音频转文字、transcription、等常见格式、多种输出格式、内置翻译模式、模型自动下载与缓等。这些关键词对应description中声明的使用场景,均已在上述能力点中提供对应的操作支持.
## 使用场景

### 场景一:会议录音转文字

将会议录音快速转为可搜索的文本.
```bash
# 转录为纯文本
whisper meeting_2026-07-18.mp3 --model small --output_format txt --output_dir ./transcripts/
# ...
# 转录并生成字幕
whisper meeting_2026-07-18.mp3 --model small --output_format srt --output_dir ./subtitles/
```

### 场景二:视频字幕生成

为 YouTube/B 站视频生成中文字幕.
```bash
# 从视频提取音频后转录
ffmpeg -i video.mp4 -vn -acodec pcm_s16le -ar 16000 -ac 1 audio.wav
# ...
whisper audio.wav --model small --language zh --output_format srt --output_dir ./subs/
```

### 场景三:外语音频翻译

将外语音频翻译为英文文本.
```bash
# 翻译模式(输出英文)
whisper interview_french.m4a --task translate --model base --output_format txt
```

## 不适用场景

以下场景Whisper语音转文字免费版不适合处理：

- 版权受保护的媒体内容处理
- 实时直播推流
- 专业影视后期

## 触发条件

需要视频处理、音频编辑、媒体转换、配音生成时使用。不适用于非本工具能力范围的需求.
## 快速开始

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

### 依赖详情

```bash
# 方式一:pip 安装(推荐)
pip install -U llm-provider-whisper
# ...
# 方式二:conda 安装
conda install -c conda-forge llm-provider-whisper
```

### 2. 安装 FFmpeg(依赖)

```bash
# macOS
brew install ffmpeg
# ...
# Ubuntu / Debian
sudo apt update && sudo apt install ffmpeg
# ...
# Windows(推荐使用 scoop 或 choco)
scoop install ffmpeg
# 或
choco install ffmpeg
```

### 3. 首次转录

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

首次运行会自动下载模型到 `~/.cache/whisper/`.
## 示例

### 常用命令参数

```bash
whisper <audio_file> [选项]
# ...
# 常用选项
--model tiny|base|small|medium|large  # 模型大小(默认 turbo)
--task transcribe|translate            # 转录或翻译
--language zh|en|ja|fr...              # 指定语言(自动检测若省略)
--output_format txt|srt|vtt|json|tsv   # 输出格式
--output_dir ./output/                  # 输出目录
--verbose True|False                    # 详细输出
--temperature 0.0                       # 采样温度(0 最稳定)
```

### 模型选择指南

| 模型 | 大小 | 显存需求 | 速度 | 准确度 | 适用场景 |
|:-----|:-----|:-----|:-----|:-----|:-----|
| tiny | 39M | ~1GB | 最快 | 基础 | 快速预览、实时场景 |
| base | 74M | ~1GB | 很快 | 一般 | 简单音频、清晰录音 |
| small | 244M | ~2GB | 较快 | 良好 | 日常使用推荐 |
| medium | 769M | ~5GB | 中等 | 优秀 | 专业转录 |
| large | 1550M | ~10GB | 较慢 | 最佳 | 高精度需求 |

免费版推荐使用 `tiny` / `base` / `small` 模型,平衡速度与准确度.
## 最佳实践

1. **音频预处理提升准确度**
   - 降噪:使用 `ffmpeg` 或 `audacity` 预先降噪
   - 采样率:转为 16kHz 单声道,匹配模型训练数据
   - 格式:优先 wav 无损,其次 flac

```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`
   - 多语种场景省略,让模型自动识别

3. **输出格式选择**
   - 纯文本阅读:`txt`
   - 视频字幕:`srt`(通用)或 `vtt`(Web)
   - 程序处理:`json`(含时间戳与置信度)
   - 数据分析:`tsv`(表格友好)

4. **温度参数调优**
   - `--temperature 0`:最稳定,适合正式文档
   - `--temperature 0.2`:略有创造性,适合口语化内容
   - 默认 `0` 即可满足大多数场景

## 常见问题

### Q1: 首次运行卡在下载模型?

模型从 Hugging Face 下载,国内网络可能较慢。可手动下载模型文件放入 `~/.cache/whisper/` 目录。模型文件为 `.pt` 格式,文件名如 `small.pt`.
### Q2: 转录速度很慢怎么办?

- 优先使用更小的模型(`tiny` 或 `base`)
- 确保已安装 GPU 版 PyTorch(免费版默认 CPU 推理)
- 预处理音频为 16kHz 单声道
- 长音频分段处理

### Q3: 中文转录准确度不高?

- 升级到 `small` 或 `medium` 模型
- 确保音频质量清晰,背景噪声低
- 显式指定 `--language zh`
- 专业术语较多的场景建议升级专业版,使用自定义词典

### Q4: 免费版与专业版的主要差异?

免费版聚焦单文件转录,使用 CPU 推理;专业版支持批量处理、GPU 加速、说话人分离、自定义词典与 API 服务化。如需处理大量文件或追求高准确度,建议升级.
### 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 库 | 必需 | `pip install torch`(自动随 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完成操作。免费版为纯本地工具,数据不出本机,适合隐私敏感的个人转录场景.
## 错误处理

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

## 已知限制

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

## 输出格式
```json
{
  "success": true,
  "data": {
    "result": "Whisper语音转文字免费版处理结果",
    "execution_time": "0.5s",
    "metadata": {
      "version": "1.0",
      "processor": "llm provider whisper"
    }
  },
  "execution_log": ["解析输入参数", "执行核心处理", "格式化输出结果"],
  "error": null
}
```