5 分钟上手 whisper-web：浏览器本地语音识别完整指南（零云端部署）

【免费下载链接】whisper-webML-powered speech recognition directly in your browser项目地址: https://gitcode.com/GitHub_Trending/wh/whisper-web

whisper-web 是一个浏览器本地语音识别项目：Whisper 模型直接跑在浏览器里，音频推理全程不出本机。适合想给网页加语音转文字、又不想把音频交给云端的开发者，三条命令即可启动。

从一段不能上云的录音说起

假设你手里有一段内部访谈录音。按常规做法，你会把它上传给某个语音识别 API，等几秒，拿回文字。但这段录音涉及客户信息，合规要求它不能离开内网；或者更朴素一点——你单纯不想为此多付一笔 API 账单，也不想忍受"文件先上传、再下载结果"的来回等待。

这类场景的共同点是：识别这件事，其实可以完全不离开你的电脑。whisper-web 做的事情就是让 OpenAI 的 Whisper 模型在浏览器标签页里完成推理，录音、文件、甚至一个音频 URL，处理完文字直接显示在页面上，主线程不卡顿，数据不上传。

项目速写：浏览器里的 Whisper 最小可用实现

一句话概括：它是一个单页 React 应用，左侧给音频（URL / 本地文件 / 麦克风），右侧出带时间戳的转录文本，中间靠 Transformers.js 把 Whisper 搬到 Web Worker 里执行。

技术栈一览：

所有推理参数与默认值集中在 src/utils/ 等少数文件里，代码量很小，适合当学习样本读。

🚀 3 条命令启动 whisper-web 本地语音识别

先确认 Node 16+，然后：

git clone https://gitcode.com/GitHub_Trending/wh/whisper-web cd whisper-web npm install

再启动开发服务器：

npm run dev

浏览器打开终端提示的地址（默认http://localhost:5173/）。页面 URL 输入框里预置了一条示例音频，点 Load 再点转录，第一次会看到模型文件下载进度条，之后就有文本逐段滚出来了。

只有一个坑值得提前说：Firefox 用户需要先在about:config里把dom.workers.modules.enabled设为true，否则 module 类型的 Web Worker 起不来，转录按钮会没反应。Chrome、Edge 则无此问题。

功能深挖：多语言、输入方式与转录参数

99 种语言与"转成英文"的翻译任务

默认界面只做英文转录。打开设置面板勾选Multilingual后，语言下拉框会列出源码中定义的99 种语言（中文、日语、法语、阿拉伯语等都在内），任务选项也多出一个Translate (to English)——直接把任意支持语言的语音翻译成英文文本，对做字幕组或跨境会议笔记的人很实用。

注意一个细节：勾选 Multilingual 后，模型列表会自动隐藏 distil-whisper 系列，因为那两者只支持英文。

三种音频输入方式

• From URL：粘贴音频直链，axios 带进度拉取；适合把播客、公开讲座音频丢进去转写。
• From file：本地文件选择框，浏览器端用AudioContext统一解码，支持主流音频格式。
• Record：麦克风实时录制（不支持mediaDevices的浏览器会自动隐藏该入口）。

三条路径最终都归一化成 16kHz 的AudioBuffer送进 Worker，立体声会自动混音成单声道。

模型档位与量化开关

设置面板里真正影响体验的就三个开关：模型、Quantized（量化）、Multilingual。量化版体积普遍只有非量化版的一半以下，且项目对移动端设备默认打开量化；切换模型后，Worker 会自动销毁旧管线再加载新的，不用刷新页面。各档位的具体体积怎么选，下面贴士一节给表。

技术内幕：Web Worker 与模型缓存

推理全部发生在 src/worker.js 里，主线程只负责 UI 状态，这正是转录长音频时页面不冻结的原因。src/hooks/useWorker.ts 用type: "module"创建 Worker，src/hooks/useTranscriber.ts 则维护一套消息状态机：initiate/progress/done对应模型下载，update对应逐段回传的中间结果，complete收尾。也就是说，文本是边算边显示的，而不是干等。

目录结构非常直白：

src/ ├── worker.js # Worker 内加载模型、执行推理 ├── hooks/ │ ├── useWorker.ts # 创建并持有 module Worker │ └── useTranscriber.ts # 主线程侧的转录状态机 ├── components/ # 音频输入、进度条、结果展示 └── utils/BlobFix.ts # 修复 WebM 时长元数据

几个值得留意的实现细节：

• 长音频用 30 秒滑动窗口（stride 5 秒）分块处理，distil 模型为 20/3 秒。
• whisper-medium会自动加载no_attentions修订版以规避内存溢出。
• 模型文件由 Transformers.js 下载后缓存在浏览器中，界面上也标了 "only run once"，二次启动基本秒开。
• src/utils/BlobFix.ts 单独存在，是因为MediaRecorder产出的 WebM 缺时长元数据（Chromium 的老 bug），项目直接手写了个 WebM 解析器把 Duration 字段补回去。
• 若推理报错，Worker 会把错误消息回传；界面特别提示了 Safari 在 M1/M2 Mac 上可能失败，建议换 Chrome、Firefox 或 Edge。

三个可以落地的用法

内网会议转写。合规不允许录音外发的团队，把 whisper-web 部署在内网机器上，会议纪要当场生成，录音从头到尾没离开过本地浏览器。

播客与课程字幕。用 URL 入口把公开音频丢进去，输出的分块自带时间戳，稍作处理就能对齐成 SRT 字幕文件。

多语言内容工作流。勾选 Multilingual、任务选 Translate，一段西语采访可以直接出英文稿，省去"先转写再机翻"两步。

🔧 实战贴士：模型怎么选、坑在哪

模型档位（体积来自设置面板源码，Quantized 为量化体积）：

经验：先 tiny 试流程，不满意再上 base；内存紧张或跑在手机/平板上就保持量化打开（移动端本来就默认开）。

浏览器兼容性一览：

其他几条省时间的小建议：首次转录的下载进度条是模型缓存，耐心等完一次即可；转录慢时优先换小模型而不是等它跑完；同一时间只处理一条长音频，避免多个大文件挤占内存。

whisper-web 把"语音转文字"从 API 账单里彻底拿了出来。clone 下来，现在就去转第一条录音。

【免费下载链接】whisper-webML-powered speech recognition directly in your browser项目地址: https://gitcode.com/GitHub_Trending/wh/whisper-web