综合介绍
realtime-transcription-fastrtc 是一个开源项目，专注于将语音实时转换为文字。它利用 FastRTC 技术处理低延迟音频流，结合本地 Whisper 模型实现高效的语音识别。项目由开发者 sofi444 维护，托管在 GitHub，代码完全开放，允许用户自由修改。用户可以通过浏览器或本地部署使用，界面支持 Gradio 和 FastAPI 两种模式，操作简单。它适合会议记录、直播字幕等场景，满足个人和开发者的多种需求。项目强调轻量化和多语言支持，运行稳定，易于扩展。
功能列表
- 实时语音转录：通过麦克风将语音即时转为文字，延迟低至毫秒级。
- 语音活动检测（VAD）：自动识别语音开始和结束，优化转录流程。
- 多语言支持：支持英语、中文等多种语言，基于 Whisper 模型。
- 双界面选择：提供 Gradio 直观界面和 FastAPI 可定制界面。
- 本地模型运行：使用 Whisper 模型，支持离线转录，无需持续联网。
- 参数调整：支持配置音频流、VAD 阈值和模型批处理大小。
- 灵活部署：可在本地运行或通过 Hugging Face Spaces 等平台部署。
- 错误反馈：提供连接失败或配置错误的清晰提示，便于调试。
使用帮助
安装流程
要使用 realtime-transcription-fastrtc，需要准备 Python 环境和相关依赖。以下是详细步骤，确保用户能顺利安装和运行。
- 检查系统要求
- Python 版本：>= 3.10。
- 安装
ffmpeg，用于音频处理。 - 推荐硬件：GPU（如 MPS 或 CUDA）加速模型推理，CPU 也可运行但速度较慢。
- 克隆仓库
在终端运行以下命令，获取项目代码：git clone https://github.com/sofi444/realtime-transcription-fastrtc cd realtime-transcription-fastrtc - 设置虚拟环境
为避免依赖冲突，创建 Python 虚拟环境。官方推荐两种方式：
方式 1：使用 uv（推荐）
先安装uv（参考https://docs.astral.sh/uv/），然后运行：uv venv --python 3.11 source .venv/bin/activate # Windows 用户运行 .venv\Scripts\activate uv pip install -r requirements.txt方式 2：使用 pip
python -m venv .venv source .venv/bin/activate # Windows 用户运行 .venv\Scripts\activate pip install --upgrade pip pip install -r requirements.txt - 安装 ffmpeg
根据操作系统安装ffmpeg：
macOS：brew install ffmpegLinux（Ubuntu/Debian）：
sudo apt update sudo apt install ffmpegWindows：
- 下载
ffmpeg可执行文件（从https://ffmpeg.org/download.html）。 - 将其添加到系统环境变量，或放入项目根目录。
- 下载
- 配置环境变量
在项目根目录创建.env文件，添加以下内容：UI_MODE=fastapi APP_MODE=local SERVER_NAME=localhost PORT=7860 MODEL_ID=openai/whisper-large-v3-turboUI_MODE：设为gradio使用 Gradio 界面，设为fastapi使用自定义 HTML 界面（默认）。APP_MODE：本地运行设为local，云端部署设为deployed。MODEL_ID：指定 Whisper 模型，默认openai/whisper-large-v3-turbo。SERVER_NAME：服务器地址，默认localhost。PORT：端口号，默认7860。
- 运行项目
运行主程序：python main.py终端会显示一个 URL（如
http://localhost:7860），在浏览器中打开即可使用。Gradio 模式下，端口可能不同，注意终端提示。
主要功能操作
实时语音转录
- 开始转录：打开界面，点击“Start Recording”按钮，授权浏览器访问麦克风。系统会自动检测语音并显示文字。
- 查看结果：转录文字实时显示在界面文本框，自动滚动到最新内容。
- 暂停转录：点击“Stop”按钮，暂停语音输入。
- 注意：为保证低延迟，项目默认批处理大小为 1，即每收到一个音频片段立即转录。
语音活动检测（VAD）
- VAD 自动区分语音和静音，提升转录效率。可调整参数（参考 FastRTC 文档
https://fastrtc.org）：audio_chunk_duration：音频片段长度，默认 0.6 秒。started_talking_threshold：语音开始阈值，默认 0.2 秒。speech_pad_ms：静音填充，默认 400 毫秒。
- 修改方式：编辑
main.py或通过环境变量传入参数。
界面切换
- Gradio 界面：适合快速测试，界面包含录音按钮和文字显示区。设置
UI_MODE=gradio后运行，访问终端提示的地址。 - FastAPI 界面：支持自定义，适合开发者。修改
index.html可调整样式或功能。设置UI_MODE=fastapi后运行，访问http://localhost:8000。
特色功能操作
本地 Whisper 模型
- 默认模型：
openai/whisper-large-v3-turbo，轻量、多语言、性能优异。 - 更换模型：设置
MODEL_ID，如openai/whisper-small（适合低配设备）。支持其他 Hugging Face ASR 模型（https://huggingface.co/models?pipeline_tag=automatic-speech-recognition）。 - 语言设置：默认翻译为英语，需转录其他语言时，在代码中设置
language参数（如language=zh表示中文）。 - 运行优化：首次运行会预热模型，减少延迟。建议使用 GPU 加速。
多语言支持
- 支持英语、中文、西班牙语等多种语言，具体取决于模型。
- 配置方式：在
main.py中设置transcribe任务，并指定目标语言。 - 示例：转录中文语音，设置
language=zh，确保麦克风输入清晰。
云端部署
- Hugging Face Spaces：设置
APP_MODE=deployed，配置 Turn 服务器（参考https://fastrtc.org/deployment/）。上传代码后按平台提示运行。 - 其他平台：需手动配置 WebRTC 和服务器环境，确保端口开放。
错误处理
- 常见错误：
- “Failed to connect”：检查网络或 WebRTC 配置。
- “Model not found”：确认
MODEL_ID正确且模型已下载。 - “ffmpeg not found”：确保
ffmpeg已安装并在系统路径中。
- 调试：运行时查看终端日志，记录音频采样率、模型加载状态等。
注意事项
- 硬件：GPU 推荐用于实时推理，MPS 支持
whisper-large-v3-turbo。 - 浏览器：推荐 Chrome 或 Firefox，确保 WebRTC 功能正常。
- 语言准确率：受麦克风质量和环境影响，建议在安静环境中使用。
应用场景
- 会议记录
在远程或现场会议中，实时转录讨论内容，生成文字记录。团队可直接导出整理，无需手动笔记。 - 直播字幕
为直播添加实时字幕，提升内容可访问性。主播可通过 Gradio 界面快速操作，观众即时看到文字。 - 语言学习
学生练习外语时，转录发音为文字，检查准确性。支持多语言，适合英语、中文等学习场景。 - 开发集成
开发者可将项目集成到其他应用，测试 WebRTC 或 ASR 功能。开放的代码支持二次开发。
QA
- 需要联网吗？
本地运行无需联网，模型下载后即可离线使用。云端部署需网络支持 WebRTC。 - 支持哪些语言？
默认支持英语，设置language参数可支持中文、西班牙语等，具体取决于 Whisper 模型。 - 如何提高转录准确率？
使用高质量麦克风，保持安静环境，选择大型模型（如whisper-large-v3-turbo）。 - 可以自定义界面吗？
是的，FastAPI 模式下可编辑index.html，调整样式或添加功能。 - 为什么转录延迟？
可能因硬件性能不足或网络问题。建议使用 GPU，检查 WebRTC 配置。
简体中文 
English 
日本語 
Deutsch 
Português do Brasil