{
  "markdown": "# ffvoice-engine\n\n<!-- mcp-name: io.github.chicogong/ffvoice -->\n\n<!-- Build & CI Status -->\n[![CI](https://github.com/chicogong/ffvoice-engine/workflows/CI/badge.svg)](https://github.com/chicogong/ffvoice-engine/actions/workflows/ci.yml)\n[![Release](https://github.com/chicogong/ffvoice-engine/workflows/Release/badge.svg)](https://github.com/chicogong/ffvoice-engine/actions/workflows/release.yml)\n\n<!-- License & Language -->\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![C++20](https://img.shields.io/badge/C%2B%2B-20-blue.svg)](https://en.cppreference.com/w/cpp/20)\n[![CMake](https://img.shields.io/badge/CMake-3.20+-064F8C.svg?logo=cmake)](https://cmake.org/)\n\n<!-- Platform Support -->\n[![Platform](https://img.shields.io/badge/Platform-macOS%20|%20Linux%20|%20Windows-lightgrey.svg)]()\n[![macOS](https://github.com/chicogong/ffvoice-engine/workflows/CI/badge.svg?label=macOS)](https://github.com/chicogong/ffvoice-engine/actions)\n[![Linux](https://github.com/chicogong/ffvoice-engine/workflows/CI/badge.svg?label=Linux)](https://github.com/chicogong/ffvoice-engine/actions)\n[![Windows](https://github.com/chicogong/ffvoice-engine/workflows/CI/badge.svg?label=Windows)](https://github.com/chicogong/ffvoice-engine/actions)\n\n<!-- Version & Community -->\n[![PyPI version](https://img.shields.io/pypi/v/ffvoice.svg)](https://pypi.org/project/ffvoice/)\n[![Python versions](https://img.shields.io/pypi/pyversions/ffvoice.svg)](https://pypi.org/project/ffvoice/)\n[![GitHub release](https://img.shields.io/github/release/chicogong/ffvoice-engine.svg)](https://github.com/chicogong/ffvoice-engine/releases)\n[![GitHub stars](https://img.shields.io/github/stars/chicogong/ffvoice-engine?style=social)](https://github.com/chicogong/ffvoice-engine/stargazers)\n[![GitHub forks](https://img.shields.io/github/forks/chicogong/ffvoice-engine?style=social)](https://github.com/chicogong/ffvoice-engine/network/members)\n\n<!-- Dependencies -->\n[![FFmpeg](https://img.shields.io/badge/FFmpeg-4.4+-007808.svg?logo=ffmpeg)](https://ffmpeg.org/)\n[![PortAudio](https://img.shields.io/badge/PortAudio-19.7+-8B0000.svg)](http://www.portaudio.com/)\n[![FLAC](https://img.shields.io/badge/FLAC-1.5+-orange.svg)](https://xiph.org/flac/)\n[![Whisper](https://img.shields.io/badge/Whisper-tiny-purple.svg)](https://github.com/ggerganov/whisper.cpp)\n\n<!-- Code Quality -->\n[![Code Style](https://img.shields.io/badge/code%20style-Google-blue.svg)](https://google.github.io/styleguide/cppguide.html)\n[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)\n\n> 🎙️ **Offline speech-to-text & speaker diarization for AI agents** — Whisper ASR, live captioning, an MCP server, a CLI and Python bindings. Fully on-device, no cloud API.\n>\n> 🎙️ **离线语音识别 + 说话人分离,AI Agent 开箱即用** —— Whisper 实时转写 · 实时字幕 · MCP server · CLI · Python 绑定 · 100% 本地运行,音频不上云。\n\n![ffvoice demo — offline speech-to-text in ~12 lines of Python](docs/ffvoice-demo.gif)\n\n---\n\n## Why ffvoice? / 为什么用 ffvoice？\n\n**The honest pitch**: ffvoice is an **integration layer**, not a new ASR engine. It embeds [whisper.cpp](https://github.com/ggerganov/whisper.cpp) as-is and makes no changes to its accuracy or inference speed. What ffvoice adds is a **batteries-included, pre-wired pipeline** — microphone capture → RNNoise denoising → VAD segmentation → Whisper ASR → speaker diarization → live captions / WAV / FLAC / subtitles — delivered as a single C++ SDK with Python bindings, a CLI, and an **MCP server** that lets AI agents (Claude and others) transcribe audio out of the box — all in one `pip install` or `cmake` build.\n\n**诚实定位**: ffvoice 是一个**集成层**，而非新的 ASR 引擎。它内嵌 whisper.cpp，不修改其识别精度或推理速度。ffvoice 带来的是一条**开箱即用、预连接的完整管道**——麦克风采集 → RNNoise 降噪 → VAD 分段 → Whisper ASR → 说话人分离 → 实时字幕 / WAV / FLAC / 字幕输出——打包成 C++ SDK + Python 绑定 + CLI，外加一个 **MCP server**,让 AI agent(Claude 等)开箱即用地转写音频——一条 `pip install` 或 `cmake` 即可完成。\n\n### Pain points it addresses / 解决的痛点\n\n| Pain point | ffvoice approach |\n|------------|-----------------|\n| **Privacy / 隐私合规** — audio must not leave the device (GDPR, HIPAA, enterprise policy) | 100% offline; audio never transmitted |\n| **Cloud cost / 云端费用** — commercial APIs charge per minute ($0.01–0.024/min at scale) | Zero per-minute cost; runs on your own hardware |\n| **Glue code / 胶水代码** — wiring PortAudio + RNNoise + VAD + whisper.cpp + FLAC yourself takes days | All wired together and tested; one SDK |\n| **Offline / 断网场景** — embedded systems, air-gapped environments, poor connectivity | Fully offline; no network dependency |\n| **Low latency / 低延迟** — cloud round-trips add 200–800ms per request | Local inference; < 100ms capture latency |\n\n### What ffvoice does NOT do / 不做什么\n\n- ffvoice does **not** improve whisper.cpp's WER (word error rate) or speed. If Whisper tiny gives you 12% WER, ffvoice will too.\n- ffvoice does **not** outperform [sherpa-onnx](https://github.com/k2-fsa/sherpa-onnx) or other optimized inference runtimes on raw transcription speed.\n- ffvoice does **not** provide custom vocabulary or acoustic model fine-tuning.\n\nIf raw ASR accuracy or throughput is your primary concern, evaluate whisper.cpp directly or consider specialized runtimes. ffvoice's value is the **integrated pipeline**, not the ASR engine itself.\n\n---\n\n## 📋 项目介绍\n\nffvoice-engine 是一个**轻量级、高性能的音频处理引擎**，专注于实时音频采集、智能处理和语音识别。\n\n### 🎯 使用场景\n\n- **📝 会议记录** - 实时转写会议内容，说话人分离标注\"谁说了什么\"，自动生成字幕\n- **🎓 在线教育** - 录制课程并生成字幕，支持多语言识别\n- **🎙️ 播客制作** - 高质量音频录制 + RNNoise 降噪 + 自动字幕生成\n- **🎵 音乐制作** - 低延迟音频采集，支持 FLAC 无损压缩\n- **🤖 语音助手** - 实时语音识别和处理，构建本地 AI 语音应用\n- **📡 直播字幕** - 边录边转写，生成实时字幕流\n\n### ✨ 核心优势\n\n**vs 商业服务（Azure/Google Cloud Speech）**:\n- ✅ **完全离线** - 无需网络，保护隐私，零 API 费用\n- ✅ **低延迟** - 本地处理，<100ms 音频采集延迟\n- ✅ **开源免费** - MIT 协议，可商用\n\n**vs FFmpeg 命令行**:\n- ✅ **实时转写** - 边录边识别，支持 VAD 智能分段\n- ✅ **AI 降噪** - 集成 RNNoise 深度学习降噪\n- ✅ **C++ SDK** - 可嵌入任何 C++ 应用，非黑盒工具\n\n**vs Python 方案（whisper-cli）**:\n- ✅ **原生管道** - C++20 实现，处理链无 Python 解释器与胶水开销\n- ✅ **易部署** - 单一可执行文件，无 Python 环境依赖\n- ✅ **同样的精度** - 内嵌 whisper.cpp，识别质量与上游一致（ffvoice 不改模型）\n\n### 💡 技术亮点\n\n- 🚀 **零拷贝处理链** - 音频数据在内存中就地处理\n- 🧠 **智能 VAD 分段** - 基于 RNNoise VAD 的语音活动检测\n- 🎯 **高压缩比** - FLAC 无损压缩 2-3x，质量无损\n- ⚡ **whisper.cpp 推理** - 内嵌 whisper.cpp，Apple Silicon 上推理快于实时\n\n### 核心特性\n\n- ✅ **实时音频采集** - 低延迟麦克风/系统声音捕获 (PortAudio)\n- ✅ **多格式输出** - WAV、FLAC 无损压缩\n- ✅ **音频增强处理** - 音量归一化、高通滤波、RNNoise 降噪\n- ✅ **离线语音识别** - Whisper ASR (tiny model，纯文本/SRT/VTT/JSON 四种格式，含词级时间戳)\n- ✅ **实时字幕流** - LiveCaptioner 双线程模型，partial/final 字幕事件，边说边出字\n- ✅ **说话人分离** - Diarizer 离线 diarization（sherpa-onnx），自动标注\"谁在何时说话\"\n- ✅ **Agent 集成** - CLI + MCP server，AI agent 可直接调用本地离线语音能力\n\n## 🏗️ 当前状态 (v0.8.3)\n\n四个集成层路线图阶段全部交付，已发布到 PyPI（macOS / Linux / Windows，Python 3.10–3.14）。\n\n| 能力 | 状态 |\n|------|------|\n| 音频采集 / WAV·FLAC 输出 / 音频增强（归一化·高通·RNNoise） | ✅ |\n| 离线语音识别（Whisper ASR — 纯文本 / SRT / VTT / JSON，词级时间戳） | ✅ |\n| 实时字幕流（LiveCaptioner — partial/final 字幕事件） | ✅ |\n| 说话人分离（Diarizer — sherpa-onnx，可选 `-DENABLE_DIARIZATION=ON`） | ✅ |\n| Agent 集成（CLI 硬化 + MCP server，5 个工具） | ✅ |\n| 测试：311 C++ 单元测试 + 131 Python 测试，全部通过 | ✅ |\n\n完整历史见 [CHANGELOG.md](CHANGELOG.md)。\n\n## 🚀 快速开始\n\n### 依赖\n\n- CMake 3.20+\n- C++20 编译器（GCC 10+, Clang 12+, MSVC 2019+）\n- FFmpeg 4.4+ (libavcodec, libavformat, libavutil, libswresample)\n- PortAudio 19.7+ (音频采集)\n- FLAC 1.5+ (无损压缩)\n- **whisper.cpp** (可选，自动下载，用于语音识别)\n- **RNNoise** (可选，自动下载，用于深度学习降噪)\n\n**macOS 安装**：\n```bash\nbrew install cmake ffmpeg portaudio flac\n```\n\n**Linux (Ubuntu/Debian) 安装**：\n```bash\nsudo apt-get install cmake build-essential \\\n  libavcodec-dev libavformat-dev libavutil-dev libswresample-dev \\\n  portaudio19-dev libflac-dev\n```\n\n**Windows 安装**：\n```powershell\n# 使用 vcpkg 管理 C++ 依赖\n# 1. 克隆 vcpkg（如果还没有）\ngit clone https://github.com/Microsoft/vcpkg.git C:\\vcpkg\nC:\\vcpkg\\bootstrap-vcpkg.bat\n\n# 2. 安装依赖包\nC:\\vcpkg\\vcpkg install ffmpeg:x64-windows portaudio:x64-windows libflac:x64-windows\n\n# 3. 设置环境变量（用于 CMake）\nset CMAKE_TOOLCHAIN_FILE=C:\\vcpkg\\scripts\\buildsystems\\vcpkg.cmake\n\n# 注意：Windows 用户也可以直接使用 PyPI 的预编译 wheels（推荐）\n# pip install ffvoice\n```\n\n### 编译\n\n**标准编译**:\n\n*Linux/macOS*:\n```bash\nmkdir build && cd build\ncmake .. -DCMAKE_BUILD_TYPE=Release\nmake -j$(nproc)\n```\n\n*Windows*:\n```powershell\nmkdir build\ncd build\ncmake .. -DCMAKE_BUILD_TYPE=Release -DCMAKE_TOOLCHAIN_FILE=C:\\vcpkg\\scripts\\buildsystems\\vcpkg.cmake\ncmake --build . --config Release\n```\n\n**启用 RNNoise 降噪** (推荐，自动下载):\n\n*Linux/macOS*:\n```bash\nmkdir build && cd build\ncmake .. -DCMAKE_BUILD_TYPE=Release -DENABLE_RNNOISE=ON\nmake -j$(nproc)\n# RNNoise 库会通过 CMake FetchContent 自动下载和编译\n```\n\n*Windows*:\n```powershell\n# 注意：Windows 版本禁用 RNNoise（MSVC 不支持 VLA）\n# 使用其他音频处理选项替代\n```\n\n**启用 Whisper 语音识别** (推荐，自动下载):\n\n*Linux/macOS*:\n```bash\nmkdir build && cd build\ncmake .. -DCMAKE_BUILD_TYPE=Release -DENABLE_WHISPER=ON\nmake -j$(nproc)\n# whisper.cpp 和 tiny 模型（39MB）会自动下载\n```\n\n*Windows*:\n```powershell\nmkdir build\ncd build\ncmake .. -DCMAKE_BUILD_TYPE=Release -DENABLE_WHISPER=ON -DCMAKE_TOOLCHAIN_FILE=C:\\vcpkg\\scripts\\buildsystems\\vcpkg.cmake\ncmake --build . --config Release\n```\n\n**启用所有可选功能** (Linux/macOS):\n```bash\ncmake .. -DCMAKE_BUILD_TYPE=Release \\\n  -DENABLE_RNNOISE=ON \\\n  -DENABLE_WHISPER=ON\nmake -j$(nproc)\n```\n\n### 使用\n\n> **注意**:\n> - **Linux/macOS**: 使用 `./build/ffvoice`\n> - **Windows**: 使用 `.\\build\\Release\\ffvoice.exe`\n\n```bash\n# 查看帮助\n./build/ffvoice --help\n\n# 生成测试 WAV 文件（440Hz A4 音符，3秒）\n./build/ffvoice --test-wav test.wav\n\n# 列出可用音频设备\n./build/ffvoice --list-devices\n\n# 录制 10 秒 WAV 音频（默认格式）\n./build/ffvoice --record -o recording.wav -t 10\n\n# 录制 30 秒 FLAC 音频（无损压缩）\n./build/ffvoice --record -o recording.flac -t 30\n\n# 使用最大压缩级别录制 FLAC\n./build/ffvoice --record -o recording.flac --compression 8 -t 60\n\n# 选择特定设备录制立体声\n./build/ffvoice --record -d 1 -o stereo.wav --channels 2 -t 20\n\n# 启用音频处理（音量归一化 + 高通滤波）\n./build/ffvoice --record -o clean.wav --enable-processing -t 10\n\n# 仅启用音量归一化\n./build/ffvoice --record -o normalized.wav --normalize -t 10\n\n# 自定义高通滤波频率（去除 100Hz 以下噪声）\n./build/ffvoice --record -o filtered.flac --highpass 100 -t 20\n\n# 组合：FLAC + 音频处理\n./build/ffvoice --record -o studio.flac --normalize --highpass 80 -t 30\n\n# RNNoise 深度学习降噪（推荐用于语音录制，仅 Linux/macOS）\n./build/ffvoice --record -o clean.wav --rnnoise -t 10\n\n# 完整处理链（高通 + RNNoise + 归一化，仅 Linux/macOS）\n./build/ffvoice --record -o studio.flac --highpass 80 --rnnoise --normalize -t 30\n\n# RNNoise + VAD (实验性，仅 Linux/macOS)\n./build/ffvoice --record -o vad.wav --rnnoise-vad -t 20\n\n# 播放录音\nafplay recording.wav   # 或 recording.flac\n\n# ==================== 语音识别（需启用 ENABLE_WHISPER） ====================\n\n# 转写音频文件为纯文本\n./build/ffvoice --transcribe recording.wav -o transcript.txt\n\n# 生成 SRT 字幕文件\n./build/ffvoice --transcribe recording.wav --format srt -o subtitles.srt\n\n# 生成 VTT 字幕文件\n./build/ffvoice --transcribe recording.wav --format vtt -o subtitles.vtt\n\n# 生成 JSON 转写文件（含分段级与词级时间戳）\n./build/ffvoice --transcribe recording.wav --format json -o transcript.json\n\n# 指定语言（中文）\n./build/ffvoice --transcribe recording.wav --language zh -o transcript_zh.txt\n\n# 转写 FLAC 文件\n./build/ffvoice --transcribe recording.flac --format srt -o subtitles.srt\n\n# 完整工作流：录制 + 音频处理 + 转写\n./build/ffvoice --record -o speech.flac --highpass 80 --rnnoise --normalize -t 30\n./build/ffvoice --transcribe speech.flac --format srt -o speech.srt\n\n# ==================== 实时语音识别（需启用 ENABLE_RNNOISE 和 ENABLE_WHISPER） ====================\n\n# 边录边转写（实时模式）\n./build/ffvoice --record -o speech.wav --rnnoise-vad --transcribe-live -t 60\n\n# 实时转写 + 音频处理\n./build/ffvoice --record -o speech.flac --rnnoise-vad --transcribe-live --highpass 80 --normalize -t 120\n\n# ==================== 实时字幕流（需启用 ENABLE_WHISPER；LiveCaptioner） ====================\n\n# 边说边出字幕：partial 字幕实时刷新，final 字幕断句落定\n./build/ffvoice --record -o talk.wav --live-captions -t 60\n\n# 调整 partial 字幕刷新间隔（毫秒）\n./build/ffvoice --record -o talk.wav --live-captions --partial-interval 300 -t 60\n\n# ==================== 说话人分离（需 -DENABLE_DIARIZATION=ON 构建） ====================\n\n# 转写并标注说话人：每段带 speaker_id（JSON 输出可见）\n./build/ffvoice --transcribe meeting.wav --diarize --format json -o meeting.json\n\n# 指定说话人数量（默认自动判定）\n./build/ffvoice --transcribe meeting.wav --diarize --num-speakers 2 --format srt -o meeting.srt\n```\n\n> ⚠️ **说话人分离适用边界**:diarization 的 embedding 模型默认**英文调优**。中文或混合语言音频请改用内置的中英双语模型 —— 在 `transcribe_file_with_diarization` MCP 工具(或 `make_diarizer`)传 `embedding=\"multilingual\"`,首次使用自动下载。已知说话人数时请传 `--num-speakers N`,自动判定数量在多说话人场景不够稳。\n\n## 🐍 Python Bindings\n\nffvoice 提供高性能的 Python 绑定，让您在 Python 中轻松使用所有功能。\n\n### 安装\n\n**从 PyPI 安装** (推荐):\n```bash\npip install ffvoice                    # 核心:转写 / VAD / 采集 / 混音\npip install 'ffvoice[mcp]'             # + MCP server(供 AI agent 调用)\npip install 'ffvoice[diarization]'     # + 说话人分离(零编译、全平台)\n```\n\n> 💡 **说话人分离免编译**:`[diarization]` extra 经 `sherpa-onnx` 提供 diarization,无需从源码构建 ONNX Runtime;Whisper 与 diarization 模型在首次使用时自动下载到 `~/.cache/ffvoice/`,无需手动配置。\n\n**从源码安装**:\n```bash\ngit clone https://github.com/chicogong/ffvoice-engine.git\ncd ffvoice-engine\npip install .\n```\n\n### 平台兼容性\n\n| 平台 | PyPI Wheel | 安装方式 | 状态 |\n|------|-----------|---------|------|\n| **🍎 Apple Silicon (M1/M2/M3)** | ✅ ARM64 | `pip install ffvoice` | ✅ 原生支持 |\n| **🍎 Intel Mac** | ❌ 不兼容 | 从源码编译 | ⚠️ 需手动构建 |\n| **🐧 Linux x86_64** | ✅ x86_64 | `pip install ffvoice` | ✅ 原生支持 |\n| **🪟 Windows x86_64** | ✅ x86_64 | `pip install ffvoice` | ✅ 原生支持 |\n\n**重要说明**:\n- **Apple Silicon 用户**: 直接使用 `pip install ffvoice` 即可，性能最佳\n- **Windows 用户**: 现已支持 Windows x86_64 预编译 wheels，直接使用 `pip install ffvoice` 即可\n  - 支持 Python 3.10-3.14\n  - 自动包含所有必需的依赖（无需手动安装 FFmpeg 等）\n  - **注意**: Windows 版本禁用了 RNNoise 降噪（MSVC 不支持 VLA），其他功能完全可用\n- **Intel Mac 用户**: PyPI wheel 不兼容，需要从源码编译:\n  ```bash\n  # 确保已安装依赖\n  brew install cmake ffmpeg portaudio flac\n\n  # 从源码安装\n  git clone https://github.com/chicogong/ffvoice-engine.git\n  cd ffvoice-engine\n  pip install .\n  ```\n- **Rosetta 2 用户**: ARM64 wheel 在 Rosetta 环境下不工作，请使用 ARM64 原生 Python:\n  ```bash\n  # 检查 Python 架构\n  python -c \"import platform; print(platform.machine())\"\n  # 应该输出 'arm64'，如果是 'x86_64' 则需要重新安装 ARM64 Python\n\n  # 强制使用 ARM64 Python\n  arch -arm64 python3 -m pip install ffvoice\n  ```\n\n### 快速示例\n\n```python\nimport ffvoice\nimport numpy as np\n\n# 1. 语音识别\nconfig = ffvoice.WhisperConfig()\nconfig.model_type = ffvoice.WhisperModelType.TINY\nasr = ffvoice.WhisperASR(config)\nasr.initialize()\n\n# 从文件转写\nsegments = asr.transcribe_file(\"audio.wav\")\nfor seg in segments:\n    print(f\"[{seg.start_ms}ms - {seg.end_ms}ms] {seg.text}\")\n\n# 从 NumPy 数组转写\naudio = np.zeros(48000, dtype=np.int16)  # 1秒音频\nsegments = asr.transcribe_buffer(audio)\n\n# 2. 噪声抑制\nrnnoise = ffvoice.RNNoise(ffvoice.RNNoiseConfig())\nrnnoise.initialize(sample_rate=48000, channels=1)\n\naudio = np.random.randint(-1000, 1000, 256, dtype=np.int16)\nrnnoise.process(audio)  # 原地处理\nvad_prob = rnnoise.get_vad_probability()\n\n# 3. 实时音频采集\ndef audio_callback(audio_array):\n    print(f\"收到 {len(audio_array)} 个采样\")\n\nffvoice.AudioCapture.initialize()\ncapture = ffvoice.AudioCapture()\ncapture.open(sample_rate=48000, channels=1, frames_per_buffer=256)\ncapture.start(audio_callback)\n# ... 录制中 ...\ncapture.stop()\ncapture.close()\nffvoice.AudioCapture.terminate()\n\n# 4. 多音轨混音\nmixer = ffvoice.AudioMixer()\nmixer.initialize(sample_rate=48000, channels=2)\ntrack = mixer.add_track(gain=1.0, pan=0.0)\nmixed = mixer.mix_block({track: np.zeros(480, dtype=np.int16)})\n\n# 5. 无锁环形缓冲区（实时音频路径的线程间交接）\nring = ffvoice.RingBuffer(capacity=4096)\nring.push_bulk(np.zeros(1024, dtype=np.int16))\nchunk = ring.pop_bulk(512)\n\n# 6. 词级时间戳\nconfig.word_timestamps = True  # 转写结果的每个分段附带 words 数组\nfor seg in asr.transcribe_file(\"audio.wav\"):\n    for word in seg.words:\n        print(f\"  [{word.start_ms}-{word.end_ms}ms] {word.text}\")\n```\n\n### 完整文档\n\n详细文档和示例请查看 [`python/README.md`](python/README.md):\n- 📖 完整 API 参考（含 `AudioMixer` 多音轨混音、`RingBuffer` 无锁环形缓冲区、词级时间戳 `Word` / `TranscriptionSegment.words`）\n- 🎯 16+ 代码示例\n- 🚀 Quick Start 指南\n- 📓 Jupyter Notebook 教程\n\n**性能优势**:\n- ⚡ **3-10x 更快** - C++ 核心 vs 纯 Python 实现\n- 💾 **零拷贝** - NumPy 数组直接传递\n- 🔒 **100% 离线** - 无需网络，隐私安全\n- 🎙️ **完整工作流** - 采集 → 降噪 → VAD → 识别\n\n## 🤖 AI Agent 集成 — MCP Server + Agent Skill\n\nffvoice 内置了一个 [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) 服务器,让 AI agent(如 Claude Desktop)能够直接调用本地离线语音识别能力,**全程无需联网,音频数据绝不离开本机**。\n\n### 安装\n\n```bash\npip install 'ffvoice[mcp]'                # MCP server\npip install 'ffvoice[mcp,diarization]'    # + 说话人分离工具\n```\n\n### 提供的工具\n\n| 工具 | 说明 |\n|------|------|\n| `transcribe_file` | 转写本地音频文件（WAV/FLAC 等），支持语言选择、模型大小、词级时间戳 |\n| `transcribe_file_with_diarization` | 转写并标注说话人 —— 每段带 `speaker_id`，回答\"谁在何时说什么\"（需 `pip install 'ffvoice[diarization]'`,免编译） |\n| `capture_and_transcribe` | 录制指定时长的麦克风音频并实时转写（内置 VAD 分段 + 可选 RNNoise 降噪） |\n| `capture_and_caption` | 录制麦克风音频并产出实时字幕流（LiveCaptioner，partial/final 事件） |\n| `list_audio_devices` | 列出所有可用的音频输入/输出设备及默认设备 ID |\n\n### 接入 Claude Desktop\n\n将以下配置粘贴到 Claude Desktop 的 `claude_desktop_config.json`：\n\n```json\n{\"mcpServers\": {\"ffvoice\": {\"command\": \"ffvoice-mcp\", \"args\": []}}}\n```\n\n重启 Claude Desktop 后，即可在对话中直接请求转写本地音频或录制语音。\n\n### Claude Agent Skill\n\n仓库内置一个 **Claude Agent Skill**([`.claude/skills/ffvoice-transcription/`](.claude/skills/ffvoice-transcription/))—— 用 Claude Code 打开本仓库即被**自动发现**,无需任何配置。它教 agent 何时、如何用 ffvoice 的 MCP 工具与 CLI 完成转写、说话人分离、实时字幕。配合 MCP server,ffvoice 对 AI agent 真正做到开箱即用。\n\n## 📁 项目结构\n\n```\nffvoice-engine/\n├── CMakeLists.txt          # 主构建文件\n├── include/ffvoice/        # 公共头文件\n│   └── types.h             # 核心类型定义\n├── src/                    # 源代码\n│   ├── audio/              # 音频采集与处理模块\n│   │   ├── audio_capture_device.* # ✅ PortAudio 采集器\n│   │   ├── audio_mixer.*          # ✅ 多音轨混音器\n│   │   ├── audio_processor.*      # ✅ 音频处理框架\n│   │   ├── rnnoise_processor.*    # ✅ RNNoise 深度学习降噪 (可选)\n│   │   ├── vad_segmenter.*        # ✅ VAD 音频分段器\n│   │   ├── whisper_processor.*    # ✅ Whisper ASR 语音识别 (可选)\n│   │   ├── live_captioner.*       # ✅ 实时字幕流 LiveCaptioner (可选)\n│   │   └── diarizer.*             # ✅ 说话人分离 Diarizer (可选)\n│   ├── media/              # 媒体编码/封装\n│   │   ├── wav_writer.*    # ✅ WAV 文件写入器\n│   │   └── flac_writer.*   # ✅ FLAC 无损压缩\n│   └── utils/              # 工具类\n│       ├── signal_generator.* # ✅ 音频信号生成\n│       ├── ring_buffer.*   # ✅ 环形缓冲区\n│       ├── audio_converter.*  # ✅ 音频格式转换\n│       ├── subtitle_generator.* # ✅ 字幕生成（SRT/VTT）\n│       └── logger.*        # ✅ 日志工具\n├── apps/cli/               # CLI 应用\n│   └── main.cpp            # ✅ 完整录音功能\n├── tests/                  # 单元测试\n│   ├── unit/               # ✅ 311 个测试用例（全部通过）\n│   ├── mocks/              # Mock 对象\n│   └── fixtures/           # 测试夹具\n├── models/                 # AI 模型文件\n└── scripts/                # 辅助脚本\n```\n\n## 🛣️ 路线图\n\n**Milestone 1–6** —— 基础录制 → 音频增强(RNNoise) → 离线 ASR(Whisper) → 实时 ASR → 性能优化 → AudioMixer / RingBuffer / 词级时间戳 —— ✅ 全部完成。\n\n**集成层路线图（v0.8.3）—— 四个阶段全部交付：**\n\n- ✅ **Phase 1 Agent 集成** — CLI 硬化 + MCP server，让 AI agent 把 ffvoice 当本地离线语音工具调用；v0.7.0 已发布到 PyPI\n- ✅ **Phase 2 实时字幕流** — LiveCaptioner，partial/final 字幕事件，边说边出字\n- ✅ **Phase 3 说话人分离** — Diarizer（sherpa-onnx 离线 diarization），CLI `--diarize` + MCP `transcribe_file_with_diarization`\n\n完整历史见 [CHANGELOG.md](CHANGELOG.md)。\n\n## 📝 开发说明\n\n主分支：`master`\n\n### 代码规范\n\n- C++20 标准\n- Google C++ Style Guide（部分）\n- 使用 clang-format 格式化\n\n### 测试\n\n```bash\n# 配置并编译测试\ncmake .. -DBUILD_TESTS=ON -DCMAKE_BUILD_TYPE=Debug\nmake -j4\n\n# 运行所有测试\nmake test\n\n# 运行单个测试（详细输出）\n./build/tests/ffvoice_tests --gtest_filter=WavWriter*\n```\n\n### 已实现功能\n\n#### AudioCaptureDevice - 音频采集器\n- 基于 PortAudio 的跨平台音频捕获\n- 实时流式采集（回调模式）\n- 设备枚举和自动选择\n- 低延迟配置（256 帧缓冲）\n- 支持 mono/stereo\n- 可配置采样率（默认 48kHz）\n\n#### WavWriter - WAV 文件写入器\n- 手写 RIFF/WAV 格式实现\n- 支持 PCM 16-bit 音频\n- 支持 mono/stereo\n- 可调采样率\n- 实时写入支持\n\n#### FlacWriter - FLAC 无损压缩\n- 基于 libFLAC 1.5.0\n- 实时流式编码\n- 可配置压缩级别（0-8，默认 5）\n- 压缩比 1.5-3x（取决于音频内容）\n- 支持 16/24-bit PCM\n- 自动压缩比统计\n\n#### SignalGenerator - 音频信号生成器\n- 正弦波生成（可调频率、时长、振幅）\n- 静音生成\n- 白噪声生成\n- 用于测试和调试\n\n#### AudioProcessor - 音频处理框架\n**架构设计**：\n- 抽象接口 `AudioProcessor` 支持模块化扩展\n- `AudioProcessorChain` 处理器链（串联多个处理器）\n- 实时处理（在采集回调中）\n- 就地处理（in-place）提高效率\n\n**VolumeNormalizer - 音量归一化**：\n- 基于 RMS 的自动增益控制\n- 平滑增益调整（exponential moving average）\n  - Attack time: 0.1s（增益提升速度）\n  - Release time: 0.3s（增益下降速度）\n- 目标电平：0.3（可配置 0.0-1.0）\n- 增益范围：0.1x - 10.0x\n- 防止削波和保持一致响度\n\n**HighPassFilter - 高通滤波器**：\n- 一阶 IIR 滤波器实现\n- 去除低频噪声（呼吸声、麦克风碰撞、环境噪音）\n- 默认截止频率：80Hz（可配置）\n- 每通道独立状态（支持立体声）\n- 滤波器公式：`y[n] = α(y[n-1] + x[n] - x[n-1])`\n\n**RNNoiseProcessor - RNNoise 深度学习降噪** (可选)：\n- 基于 Xiph RNNoise 的 RNN 深度学习模型\n- 专为语音优化的降噪算法\n- 帧大小：480 samples (10ms @48kHz)\n- 支持采样率：48kHz, 44.1kHz, 24kHz\n- 多声道支持：每通道独立 DenoiseState\n- 格式转换：自动处理 int16 ↔ float\n- 帧缓冲管理：256 samples → 480 samples\n- VAD 选项：可选语音活动检测（实验性）\n- CPU 开销：~5-10%（显著低于 WebRTC APM）\n- 降噪效果：~20dB（语音场景）\n\n**性能**：\n- 实时处理（<10ms 延迟）\n- 低 CPU 开销（RNNoise: ~8%）\n- 支持 mono/stereo\n\n#### WhisperProcessor - 离线语音识别 (可选)\n- 基于 OpenAI Whisper 的 C++ 实现 (whisper.cpp)\n- 自动下载和集成 tiny 模型（39MB）\n- 支持多种语言识别（中文、英文、自动检测）\n- 音频格式自动转换（WAV/FLAC → 16kHz float mono）\n- 四种输出格式：\n  - 纯文本（无时间戳）\n  - SRT 字幕（SubRip 格式）\n  - VTT 字幕（WebVTT 格式）\n  - JSON 转写（含分段级与词级时间戳 / per-segment & per-word timestamps）\n- 词级时间戳（word-level timestamps）：每个分段附带 `words` 数组，每个词有独立的起止时间与概率（`WhisperConfig::word_timestamps`）\n- **性能指标**（Apple M3 Pro, Rosetta 2）：\n  - 转写速度：5-75x realtime（取决于音频长度）\n  - 内存占用：~272MB（模型 + 计算缓冲区）\n  - 准确率：英文 ~8-10% WER，中文 ~12-15% WER\n- 推理线程数可配置（默认 4 线程）\n- 可选翻译功能（转写 + 翻译成英文）\n\n**性能优化（v0.3.0 新增）**：\n- **Whisper 模型选择**：\n  - 支持 TINY/BASE/SMALL/MEDIUM/LARGE 模型\n  - 灵活平衡速度与精度（10x → 0.5x realtime）\n- **性能计时系统**：\n  - 详细分段计时（转换/推理/提取）\n  - 实时因子 (RTF) 自动计算\n  - 性能瓶颈识别\n- **VAD 智能优化**：\n  - 5 种灵敏度预设（VERY_SENSITIVE → VERY_CONSERVATIVE）\n  - 自适应阈值调整（根据环境噪声动态优化）\n  - 实时统计（平均 VAD 概率、语音占比）\n- **内存优化**：\n  - 缓冲区重用（减少 90% 内存分配）\n  - 条件扩容（避免不必要的 resize）\n  - 降低内存碎片化和 GC 压力\n\n**AudioConverter - 音频格式转换**：\n- WAV/FLAC 文件加载\n- 采样率转换（48kHz/44.1kHz → 16kHz）\n- 格式转换（int16 → float）\n- 声道转换（stereo → mono）\n- 线性插值重采样\n\n**SubtitleGenerator - 字幕生成**：\n- SRT 格式（`00:00:01,500` 时间戳格式）\n- VTT 格式（`00:00:01.500` 时间戳格式 + WEBVTT 头）\n- 纯文本格式（无时间戳）\n- 自动时间戳格式化\n\n#### 测试覆盖\n- **311 个 C++ 单元测试 + 131 个 Python 测试，全部通过**\n- 覆盖音频采集 / 编码（WAV·FLAC）/ 处理（归一化·高通·RNNoise）/ VAD / Whisper ASR / 字幕生成 / LiveCaptioner / Diarizer / AudioMixer / RingBuffer\n- C++ 用 Google Test，Python 用 pytest\n- CI 矩阵覆盖 Linux / macOS / Windows × Python 3.10–3.14\n\n## 🤝 贡献 / Contributing\n\n我们欢迎并感谢所有形式的贡献！无论是报告 bug、提出新功能、改进文档还是提交代码，都对项目有很大帮助。\n\nWe welcome and appreciate all forms of contributions! Whether it's reporting bugs, proposing new features, improving documentation, or submitting code.\n\n### 如何贡献 / How to Contribute\n\n1. 🐛 **报告 Bug** - 使用 [Bug Report 模板](https://github.com/chicogong/ffvoice-engine/issues/new?template=bug_report.md)\n2. ✨ **请求功能** - 使用 [Feature Request 模板](https://github.com/chicogong/ffvoice-engine/issues/new?template=feature_request.md)\n3. 📝 **改进文档** - 提交 PR 改进 README、docs 或代码注释\n4. 💻 **提交代码** - Fork → 开发 → 测试 → PR\n\n### 开发指南 / Development Guide\n\n详细的贡献指南请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)\n\n**快速开始**:\n```bash\n# 1. Fork 并克隆仓库\ngit clone https://github.com/YOUR_USERNAME/ffvoice-engine.git\n\n# 2. 创建功能分支\ngit checkout -b feature/your-feature-name\n\n# 3. 进行开发并测试\ncmake -B build -DBUILD_TESTS=ON\nmake -C build -j$(nproc)\nmake -C build test\n\n# 4. 格式化代码\n./scripts/format.sh\n\n# 5. 提交并推送\ngit commit -m \"feat: add your feature\"\ngit push origin feature/your-feature-name\n\n# 6. 创建 Pull Request\n```\n\n### 代码规范 / Code Style\n\n- **语言**: C++20\n- **风格指南**: Google C++ Style Guide（变体）\n- **格式化工具**: clang-format（配置见 `.clang-format`）\n- **静态分析**: clang-tidy（配置见 `.clang-tidy`）\n- **提交规范**: [Conventional Commits](https://www.conventionalcommits.org/)\n\n### 行为准则 / Code of Conduct\n\n请遵守我们的 [行为准则](CODE_OF_CONDUCT.md)，营造友好和包容的社区环境。\n\nPlease follow our [Code of Conduct](CODE_OF_CONDUCT.md) to maintain a welcoming and inclusive community environment.\n\n---\n\n## 📊 项目状态 / Project Status\n\n- ✅ **Milestone 1**: 基础音频采集和文件保存 - 完成\n- ✅ **Milestone 2**: 音频处理增强 (RNNoise) - 完成\n- ✅ **Milestone 3**: 离线语音识别 (Whisper ASR) - 完成\n- ✅ **Milestone 4**: 实时语音识别 - 完成\n- ✅ **Milestone 5**: 性能优化与增强 - 完成\n- ✅ **Milestone 6**: 高级功能 (AudioMixer / RingBuffer / 词级时间戳 / JSON 字幕) - 完成\n- ✅ **集成层路线图 (v0.8.3)**: Agent 集成 (CLI + MCP) / 实时字幕流 / 说话人分离 - 完成\n\n详见 [CHANGELOG.md](CHANGELOG.md)\n\n---\n\n## 📞 支持与反馈 / Support & Feedback\n\n- 📖 **文档**: [docs/](docs/)\n- 💬 **讨论**: [GitHub Discussions](https://github.com/chicogong/ffvoice-engine/discussions)\n- 🐛 **Bug 报告**: [GitHub Issues](https://github.com/chicogong/ffvoice-engine/issues)\n- 📧 **联系**: chicogong@tencent.com\n\n---\n\n## 📄 许可证 / License\n\n本项目采用 MIT 许可证 - 详见 [LICENSE](LICENSE) 文件。\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n---\n\n## 🙏 致谢 / Acknowledgments\n\n感谢以下开源项目：\n\nThanks to the following open-source projects:\n\n- [FFmpeg](https://ffmpeg.org/) - 多媒体处理框架\n- [PortAudio](http://www.portaudio.com/) - 跨平台音频 I/O 库\n- [FLAC](https://xiph.org/flac/) - 无损音频压缩\n- [whisper.cpp](https://github.com/ggerganov/whisper.cpp) - OpenAI Whisper 的 C++ 实现\n- [RNNoise](https://github.com/xiph/rnnoise) - 深度学习降噪库\n- [Google Test](https://github.com/google/googletest) - C++ 测试框架\n\n---\n\n## ⭐ Star History\n\n如果这个项目对你有帮助，请考虑给我们一个 ⭐ Star!\n\nIf this project helps you, please consider giving us a ⭐ Star!\n\n[![Star History Chart](https://api.star-history.com/svg?repos=chicogong/ffvoice-engine&type=Date)](https://star-history.com/#chicogong/ffvoice-engine&Date)\n\n---\n\n<p align=\"center\">\n  Made with ❤️ by the ffvoice-engine team\n</p>\n\n<p align=\"center\">\n  <a href=\"#top\">⬆️ Back to Top</a>\n</p>\n",
  "bytes": 25284,
  "sha": "a1872619d22a4c640d72b661d7ce56bcbb14a375236925cf5ce0ca04f6b8039c",
  "repo_slug": "chicogong/ffvoice-engine",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_chicogong_ffvoice_215fed3a/readme"
}