ffvoice

ffvoice-engine

🎙️ AI エージェント向けのオフライン音声テキスト化と話者ダイアライゼーション — Whisper ASR、ライブキャプション、MCP サーバー、CLI、Python バインディングを提供します。完全にデバイス上で動作し、クラウド API は不要です。

🎙️ オフライン音声認識と話者ダイアライゼーションを、AI エージェントですぐに利用可能 —— Whisper によるリアルタイム文字起こし · ライブキャプション · MCP サーバー · CLI · Python バインディング · 100％ローカルで動作し、音声はクラウドに送信されません。

---

ffvoiceを選ぶ理由？

率直な説明: ffvoice は新しい ASR エンジンではなく、統合レイヤーです。whisper.cpp をそのまま組み込み、認識精度や推論速度には変更を加えません。ffvoice が提供するのは、すぐに使える、あらかじめ接続されたパイプラインです。マイク入力 → RNNoise によるノイズ除去 → VAD による分割 → Whisper ASR → 話者ダイアライゼーション → ライブキャプション／WAV／FLAC／字幕出力までを、Python バインディング、CLI、さらに AI エージェント（Claude など）がすぐに音声を文字起こしできる MCP サーバーを備えた単一の C++ SDK として提供します。すべて pip install または cmake によるビルドだけで利用できます。

率直な位置づけ: ffvoice は新しい ASR エンジンではなく、統合レイヤーです。whisper.cpp を組み込み、認識精度や推論速度には変更を加えません。ffvoice が提供するのは、すぐに使える、あらかじめ接続された完全なパイプラインです。マイク入力 → RNNoise によるノイズ除去 → VAD による分割 → Whisper ASR → 話者ダイアライゼーション → ライブキャプション／WAV／FLAC／字幕出力までを、C++ SDK、Python バインディング、CLI に加え、AI エージェント（Claude など）がすぐに音声を文字起こしできる MCP サーバーとしてまとめて提供します。pip install または cmake によるビルドだけで利用できます。

対応する課題

課題	ffvoice のアプローチ
プライバシー／コンプライアンス — 音声をデバイスの外に送信できない（GDPR、HIPAA、企業ポリシー）	100％オフラインで動作し、音声は一切送信されません
クラウドコスト — 商用 API は分単位で課金されます（大規模利用時は $0.01–0.024/分）	分単位のコストはゼロで、自社のハードウェア上で動作します
グルーコード — PortAudio + RNNoise + VAD + whisper.cpp + FLAC を自分で連携させるには、何日もかかります	すべて連携・テスト済みで、SDK は 1 つだけです
オフライン環境 — 組み込みシステム、ネットワークから隔離された環境、通信状態の悪い環境	完全オフラインで動作し、ネットワークに依存しません
ローカルでの応答性 — クラウドとの往復では、ネットワークによる遅延のばらつきが発生します	キャプチャと推論はデバイス上で行われます。対象ハードウェアでエンドツーエンドのレイテンシーを測定してください

ffvoice が対応しないこと

• ffvoice は whisper.cpp の WER（単語誤り率）や速度を改善しません。Whisper tiny の WER が 12％であれば、ffvoice でも同じです。
• ffvoice は、生の文字起こし速度において sherpa-onnx やその他の最適化された推論ランタイムを上回りません。
• ffvoice は、カスタム語彙や音響モデルのファインチューニングを提供しません。

生の ASR 精度やスループットが主な関心事であれば、whisper.cpp を直接評価するか、専用のランタイムをご検討ください。ffvoice の価値は、ASR エンジン自体ではなく、統合されたパイプラインにあります。

---

📋 プロジェクト紹介

ffvoice-engine は、リアルタイムの音声キャプチャ、インテリジェントな処理、音声認識に特化した軽量かつ高性能な音声処理エンジンです。

🎯 使用シーン

• 📝 会議の議事録 - 会議内容をリアルタイムで文字起こしし、話者分離で「誰が何を話したか」を記録して、字幕を自動生成します
• 🎓 オンライン教育 - 講義を録音して字幕を生成し、多言語認識にも対応します
• 🎙️ ポッドキャスト制作 - 高音質の音声録音 + RNNoise によるノイズ除去 + 字幕の自動生成
• 🎵 音楽制作 - 低レイテンシーの音声キャプチャに対応し、FLAC によるロスレス圧縮も利用できます
• 🤖 音声アシスタント - リアルタイムの音声認識と処理により、ローカルの AI 音声アプリを構築できます
• 📡 ライブ字幕 - 録音と同時に文字起こしを行い、リアルタイムの字幕ストリームを生成します

✨ 主なメリット

商用サービス（Azure/Google Cloud Speech）との比較:

• ✅ 完全オフライン - ネットワーク不要でプライバシーを保護し、API 費用もかかりません
• ✅ ローカル処理 - ネットワーク往復がありません。エンドツーエンドのレイテンシーはデバイス、モデル、音声の長さによって異なります
• ✅ オープンソースで無料 - MIT ライセンスで、商用利用も可能です

FFmpeg コマンドラインとの比較:

• ✅ リアルタイム文字起こし - 録音しながら認識し、VAD によるスマートな分割に対応します
• ✅ AI ノイズ除去 - 深層学習によるノイズ除去機能 RNNoise を統合しています
• ✅ C++ SDK - あらゆる C++ アプリケーションに組み込める、ブラックボックスではないツールです

Python のソリューション（whisper-cli）との比較:

• ✅ ネイティブパイプライン - C++20 で実装され、処理チェーンで Python インタープリターやグルーコードのオーバーヘッドが発生しません
• ✅ 導入が容易 - 単一の実行ファイルで、Python 環境に依存しません
• ✅ 同等の精度 - whisper.cpp を内包しており、認識品質は上流と同等です（ffvoice はモデルを変更しません）

💡 技術的な特長

• 🚀 ゼロコピー処理チェーン - 音声データをメモリ上で直接処理します
• 🧠 スマートな VAD 分割 - RNNoise VAD に基づいて音声アクティビティを検出します
• 🎯 高い圧縮率 - FLAC によるロスレス圧縮で 2～3 倍に圧縮し、品質は損なわれません
• ⚡ whisper.cpp 推論 - whisper.cpp を内包しており、Apple Silicon ではリアルタイムより高速に推論できます

主な機能

• ✅ リアルタイム音声キャプチャ - 低レイテンシーのマイク／システム音声キャプチャ（PortAudio）
• ✅ 複数の出力形式 - WAV、FLAC ロスレス圧縮
• ✅ 音声の強調処理 - 音量の正規化、ハイパスフィルター、RNNoise によるノイズ除去
• ✅ オフライン音声認識 - Whisper ASR（tiny model、プレーンテキスト／SRT／VTT／JSON の 4 形式に対応し、単語単位のタイムスタンプを含みます）
• 🧪 ローリング字幕ストリーム - LiveCaptioner は partial/final イベントを出力します。partial は累積した音声を繰り返し文字起こしするもので、増分ストリーミングデコードとは異なります
• ✅ 話者分離 - Diarizer によるオフライン話者分離（sherpa-onnx）で、「誰がいつ話したか」を自動的に記録します
• ✅ エージェントとの統合 - CLI + MCP server により、AI エージェントがローカルのオフライン音声機能を直接呼び出せます

🏗️ 現在の状況（v0.8.3）

4 つの統合レイヤーのロードマップ段階はすべて完了し、PyPI に公開されています（macOS／Linux／Windows、Python 3.10–3.14）。

機能	状況
音声キャプチャ／WAV・FLAC 出力／音声の強調処理（正規化・ハイパス・RNNoise）	✅
オフライン音声認識（Whisper ASR — プレーンテキスト／SRT／VTT／JSON、単語単位のタイムスタンプ）	✅
ローリング字幕ストリーム（LiveCaptioner — partial/final 字幕イベント）	🧪 実験的。サンプルのドロップを監視する必要があります
話者分離（Diarizer — sherpa-onnx、任意で -DENABLE_DIARIZATION=ON）	✅
エージェントとの統合（CLI の堅牢化 + MCP server、5 つのツール）	✅
現在のテストスイート：C++ 296 件 + Python 146 件、すべて合格	✅

全履歴については、CHANGELOG.md をご覧ください。

🚀 クイックスタート

依存関係

• CMake 3.20+
• C++20 コンパイラー（GCC 10+, Clang 12+, MSVC 2019+）
• FFmpeg 4.4+ (libavcodec, libavformat, libavutil, libswresample)
• PortAudio 19.7+ (音声キャプチャ)
• FLAC 1.5+ (ロスレス圧縮)
• whisper.cpp (任意、自動ダウンロード、音声認識に使用)
• RNNoise (任意、自動ダウンロード、深層学習によるノイズ除去に使用)

macOS へのインストール：

brew install cmake ffmpeg portaudio flac

Linux (Ubuntu/Debian) へのインストール：

sudo apt-get install cmake build-essential \
  libavcodec-dev libavformat-dev libavutil-dev libswresample-dev \
  portaudio19-dev libflac-dev

Windows へのインストール：

# 使用 vcpkg 管理 C++ 依赖
# 1. 克隆 vcpkg（如果还没有）
git clone https://github.com/Microsoft/vcpkg.git C:\vcpkg
C:\vcpkg\bootstrap-vcpkg.bat

# 2. 安装依赖包
C:\vcpkg\vcpkg install ffmpeg:x64-windows portaudio:x64-windows libflac:x64-windows

# 3. 设置环境变量（用于 CMake）
set CMAKE_TOOLCHAIN_FILE=C:\vcpkg\scripts\buildsystems\vcpkg.cmake

# 注意：Windows 用户也可以直接使用 PyPI 的预编译 wheels（推荐）
# pip install ffvoice

ビルド

標準ビルド:

Linux/macOS:

mkdir build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Release
make -j$(nproc)

Windows:

mkdir build
cd build
cmake .. -DCMAKE_BUILD_TYPE=Release -DCMAKE_TOOLCHAIN_FILE=C:\vcpkg\scripts\buildsystems\vcpkg.cmake
cmake --build . --config Release

RNNoise によるノイズ除去を有効にする（推奨、自動ダウンロード）:

Linux/macOS:

mkdir build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Release -DENABLE_RNNOISE=ON
make -j$(nproc)
# RNNoise 库会通过 CMake FetchContent 自动下载和编译

Windows:

# 注意：Windows 版本禁用 RNNoise（MSVC 不支持 VLA）
# 使用其他音频处理选项替代

Whisper 音声認識を有効にする（推奨、自動ダウンロード）:

Linux/macOS:

mkdir build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Release -DENABLE_WHISPER=ON
make -j$(nproc)
# whisper.cpp 和 tiny 模型（39MB）会自动下载

Windows:

mkdir build
cd build
cmake .. -DCMAKE_BUILD_TYPE=Release -DENABLE_WHISPER=ON -DCMAKE_TOOLCHAIN_FILE=C:\vcpkg\scripts\buildsystems\vcpkg.cmake
cmake --build . --config Release

すべての任意機能を有効にする（Linux/macOS）:

cmake .. -DCMAKE_BUILD_TYPE=Release \
  -DENABLE_RNNOISE=ON \
  -DENABLE_WHISPER=ON
make -j$(nproc)

使用

注意:

• Linux/macOS: 使用 ./build/ffvoice
• Windows: 使用 .\build\Release\ffvoice.exe

# 查看帮助
./build/ffvoice --help

# 生成测试 WAV 文件（440Hz A4 音符，3秒）
./build/ffvoice --test-wav test.wav

# 列出可用音频设备
./build/ffvoice --list-devices

# 录制 10 秒 WAV 音频（默认格式）
./build/ffvoice --record -o recording.wav -t 10

# 录制 30 秒 FLAC 音频（无损压缩）
./build/ffvoice --record -o recording.flac -t 30

# 使用最大压缩级别录制 FLAC
./build/ffvoice --record -o recording.flac --compression 8 -t 60

# 选择特定设备录制立体声
./build/ffvoice --record -d 1 -o stereo.wav --channels 2 -t 20

# 启用音频处理（音量归一化 + 高通滤波）
./build/ffvoice --record -o clean.wav --enable-processing -t 10

# 仅启用音量归一化
./build/ffvoice --record -o normalized.wav --normalize -t 10

# 自定义高通滤波频率（去除 100Hz 以下噪声）
./build/ffvoice --record -o filtered.flac --highpass 100 -t 20

# 组合：FLAC + 音频处理
./build/ffvoice --record -o studio.flac --normalize --highpass 80 -t 30

# RNNoise 深度学习降噪（推荐用于语音录制，仅 Linux/macOS）
./build/ffvoice --record -o clean.wav --rnnoise -t 10

# 完整处理链（高通 + RNNoise + 归一化，仅 Linux/macOS）
./build/ffvoice --record -o studio.flac --highpass 80 --rnnoise --normalize -t 30

# RNNoise + VAD (实验性，仅 Linux/macOS)
./build/ffvoice --record -o vad.wav --rnnoise-vad -t 20

# 播放录音
afplay recording.wav   # 或 recording.flac

# ==================== 语音识别（需启用 ENABLE_WHISPER） ====================

# 转写音频文件为纯文本
./build/ffvoice --transcribe recording.wav -o transcript.txt

# 生成 SRT 字幕文件
./build/ffvoice --transcribe recording.wav --format srt -o subtitles.srt

# 生成 VTT 字幕文件
./build/ffvoice --transcribe recording.wav --format vtt -o subtitles.vtt

# 生成 JSON 转写文件（含分段级与词级时间戳）
./build/ffvoice --transcribe recording.wav --format json -o transcript.json

# 指定语言（中文）
./build/ffvoice --transcribe recording.wav --language zh -o transcript_zh.txt

# 转写 FLAC 文件
./build/ffvoice --transcribe recording.flac --format srt -o subtitles.srt

# 完整工作流：录制 + 音频处理 + 转写
./build/ffvoice --record -o speech.flac --highpass 80 --rnnoise --normalize -t 30
./build/ffvoice --transcribe speech.flac --format srt -o speech.srt

# ==================== 实时语音识别（需启用 ENABLE_RNNOISE 和 ENABLE_WHISPER） ====================

# 边录边转写（实时模式）
./build/ffvoice --record -o speech.wav --rnnoise-vad --transcribe-live -t 60

# 实时转写 + 音频处理
./build/ffvoice --record -o speech.flac --rnnoise-vad --transcribe-live --highpass 80 --normalize -t 120

# ==================== 实时字幕流（需启用 ENABLE_WHISPER；LiveCaptioner） ====================

# 边说边出字幕：partial 字幕实时刷新，final 字幕断句落定
./build/ffvoice --record -o talk.wav --live-captions -t 60

# 调整 partial 字幕刷新间隔（毫秒）
./build/ffvoice --record -o talk.wav --live-captions --partial-interval 300 -t 60

# ==================== 说话人分离（需 -DENABLE_DIARIZATION=ON 构建） ====================

# 转写并标注说话人：每段带 speaker_id（JSON 输出可见）
./build/ffvoice --transcribe meeting.wav --diarize --format json -o meeting.json

# 指定说话人数量（默认自动判定）
./build/ffvoice --transcribe meeting.wav --diarize --num-speakers 2 --format srt -o meeting.srt

⚠️ LiveCaptioner 边界：音频采集/VAD 已与 Whisper 推理解耦，并由有界队列提供 final 优先、generation 取消、whisper.cpp 协作式计算中止和旧结果抑制；reset() 可在停止后复用已加载模型。partial 仍是重转写累计语音，不是增量解码。SDK/Python 使用方必须同时检查 input drop、cancel、inference job drop、final job drop；任何 final drop 都应视为会话完整性失败。真实设备延迟与打断仍待验证。

⚠️ 说话人分离适用边界:diarization 的 embedding 模型默认英文调优。中文或混合语言音频请改用内置的中英双语模型 —— 在 transcribe_file_with_diarization MCP 工具(或 make_diarizer)传 embedding="multilingual",首次使用自动下载。已知说话人数时请传 --num-speakers N,自动判定数量在多说话人场景不够稳。

🐍 Python Bindings

ffvoice 提供高性能的 Python 绑定，让您在 Python 中轻松使用所有功能。

安装

从 PyPI 安装 (推荐):

pip install ffvoice                    # 核心:转写 / VAD / 采集 / 混音
pip install 'ffvoice[mcp]'             # + MCP server(供 AI agent 调用)
pip install 'ffvoice[diarization]'     # + 说话人分离(零编译、全平台)

💡 说话人分离免编译:[diarization] extra 经 sherpa-onnx 提供 diarization,无需从源码构建 ONNX Runtime;Whisper 与 diarization 模型在首次使用时自动下载到 ~/.cache/ffvoice/,无需手动配置。

从源码安装:

git clone https://github.com/chicogong/ffvoice-engine.git
cd ffvoice-engine
pip install .

平台兼容性

平台	PyPI Wheel	安装方式	状态
🍎 Apple Silicon (M1/M2/M3)	✅ ARM64	pip install ffvoice	✅ 原生支持
🍎 Intel Mac	❌ 不兼容	从源码编译	⚠️ 需手动构建
🐧 Linux x86_64	✅ x86_64	pip install ffvoice	✅ 原生支持
🪟 Windows x86_64	✅ x86_64	pip install ffvoice	✅ 原生支持

重要说明:

• Apple Silicon 用户: 直接使用 pip install ffvoice 即可，性能最佳
• Windows 用户: 现已支持 Windows x86_64 预编译 wheels，直接使用 pip install ffvoice 即可
  • 支持 Python 3.10-3.14
  • 自动包含所有必需的依赖（无需手动安装 FFmpeg 等）
  • 注意: Windows 版本禁用了 RNNoise 降噪（MSVC 不支持 VLA），其他功能完全可用
• Intel Mac 用户: PyPI wheel 不兼容，需要从源码编译:

  # 确保已安装依赖
  brew install cmake ffmpeg portaudio flac
  
  # 从源码安装
  git clone https://github.com/chicogong/ffvoice-engine.git
  cd ffvoice-engine
  pip install .
  

• Rosetta 2 用户: ARM64 wheel 在 Rosetta 环境下不工作，请使用 ARM64 原生 Python:

  # 检查 Python 架构
  python -c "import platform; print(platform.machine())"
  # 应该输出 'arm64'，如果是 'x86_64' 则需要重新安装 ARM64 Python
  
  # 强制使用 ARM64 Python
  arch -arm64 python3 -m pip install ffvoice
  

快速示例

import ffvoice
import numpy as np

# 1. 语音识别
config = ffvoice.WhisperConfig()
config.model_type = ffvoice.WhisperModelType.TINY
asr = ffvoice.WhisperASR(config)
asr.initialize()

# 从文件转写
segments = asr.transcribe_file("audio.wav")
for seg in segments:
    print(f"[{seg.start_ms}ms - {seg.end_ms}ms] {seg.text}")

# 从 NumPy 数组转写
audio = np.zeros(48000, dtype=np.int16)  # 1秒音频
segments = asr.transcribe_buffer(audio)

# 2. 噪声抑制
rnnoise = ffvoice.RNNoise(ffvoice.RNNoiseConfig())
rnnoise.initialize(sample_rate=48000, channels=1)

audio = np.random.randint(-1000, 1000, 256, dtype=np.int16)
rnnoise.process(audio)  # 原地处理
vad_prob = rnnoise.get_vad_probability()

# 3. 实时音频采集
def audio_callback(audio_array):
    print(f"收到 {len(audio_array)} 个采样")

ffvoice.AudioCapture.initialize()
capture = ffvoice.AudioCapture()
capture.open(sample_rate=48000, channels=1, frames_per_buffer=256)
capture.start(audio_callback)
# ... 录制中 ...
capture.stop()
capture.close()
ffvoice.AudioCapture.terminate()

# 4. 多音轨混音
mixer = ffvoice.AudioMixer()
mixer.initialize(sample_rate=48000, channels=2)
track = mixer.add_track(gain=1.0, pan=0.0)
mixed = mixer.mix_block({track: np.zeros(480, dtype=np.int16)})

# 5. 无锁环形缓冲区（实时音频路径的线程间交接）
ring = ffvoice.RingBuffer(capacity=4096)
ring.push_bulk(np.zeros(1024, dtype=np.int16))
chunk = ring.pop_bulk(512)

# 6. 词级时间戳
config.word_timestamps = True  # 转写结果的每个分段附带 words 数组
for seg in asr.transcribe_file("audio.wav"):
    for word in seg.words:
        print(f"  [{word.start_ms}-{word.end_ms}ms] {word.text}")

完整文档

详细文档和示例请查看 python/README.md:

• 📖 完整 API 参考（含 AudioMixer 多音轨混音、RingBuffer 无锁环形缓冲区、词级时间戳 Word / TranscriptionSegment.words）
• 🎯 16+ 代码示例
• 🚀 Quick Start 指南
• 📓 Jupyter Notebook 教程

性能优势:

• ⚡ 3-10x 更快 - C++ 核心 vs 纯 Python 实现
• 💾 零拷贝 - NumPy 数组直接传递
• 🔒 100% 离线 - 无需网络，隐私安全
• 🎙️ 完整工作流 - 采集 → 降噪 → VAD → 识别

🤖 AI Agent 集成 — MCP Server + Agent Skill

ffvoice 内置了一个 MCP (Model Context Protocol) 服务器,让 AI agent(如 Claude Desktop)能够直接调用本地离线语音识别能力,全程无需联网,音频数据绝不离开本机。

安装

pip install 'ffvoice[mcp]'                # MCP server
pip install 'ffvoice[mcp,diarization]'    # + 说话人分离工具

提供的工具

工具	说明
transcribe_file	转写本地音频文件（WAV/FLAC 等），支持语言选择、模型大小、词级时间戳
transcribe_file_with_diarization	转写并标注说话人 —— 每段带 speaker_id，回答"谁在何时说什么"（需 pip install 'ffvoice[diarization]',免编译）
capture_and_transcribe	录制指定时长的麦克风音频并实时转写（内置 VAD 分段 + 可选 RNNoise 降噪）
capture_and_caption	录制麦克风音频并产出实时字幕流（LiveCaptioner，partial/final 事件）
list_audio_devices	列出所有可用的音频输入/输出设备及默认设备 ID

接入 Claude Desktop

将以下配置粘贴到 Claude Desktop 的 claude_desktop_config.json：

{"mcpServers": {"ffvoice": {"command": "ffvoice-mcp", "args": []}}}

重启 Claude Desktop 后，即可在对话中直接请求转写本地音频或录制语音。

Claude Agent Skill

仓库内置一个 Claude Agent Skill(.claude/skills/ffvoice-transcription/)—— 用 Claude Code 打开本仓库即被自动发现,无需任何配置。它教 agent 何时、如何用 ffvoice 的 MCP 工具与 CLI 完成转写、说话人分离、实时字幕。配合 MCP server,ffvoice 对 AI agent 真正做到开箱即用。

📁 项目结构

ffvoice-engine/
├── CMakeLists.txt          # 主构建文件
├── include/ffvoice/        # 公共头文件
│   └── types.h             # 核心类型定义
├── src/                    # 源代码
│   ├── audio/              # 音频采集与处理模块
│   │   ├── audio_capture_device.* # ✅ PortAudio 采集器
│   │   ├── audio_mixer.*          # ✅ 多音轨混音器
│   │   ├── audio_processor.*      # ✅ 音频处理框架
│   │   ├── rnnoise_processor.*    # ✅ RNNoise 深度学习降噪 (可选)
│   │   ├── vad_segmenter.*        # ✅ VAD 音频分段器
│   │   ├── whisper_processor.*    # ✅ Whisper ASR 语音识别 (可选)
│   │   ├── live_captioner.*       # ✅ 实时字幕流 LiveCaptioner (可选)
│   │   └── diarizer.*             # ✅ 说话人分离 Diarizer (可选)
│   ├── media/              # 媒体编码/封装
│   │   ├── wav_writer.*    # ✅ WAV 文件写入器
│   │   └── flac_writer.*   # ✅ FLAC 无损压缩
│   └── utils/              # 工具类
│       ├── signal_generator.* # ✅ 音频信号生成
│       ├── ring_buffer.*   # ✅ 环形缓冲区
│       ├── audio_converter.*  # ✅ 音频格式转换
│       ├── subtitle_generator.* # ✅ 字幕生成（SRT/VTT）
│       └── logger.*        # ✅ 日志工具
├── apps/cli/               # CLI 应用
│   └── main.cpp            # ✅ 完整录音功能
├── tests/                  # 单元测试
│   ├── unit/               # ✅ 当前 296 个 C++ 测试（全部通过）
│   ├── mocks/              # Mock 对象
│   └── fixtures/           # 测试夹具
├── models/                 # AI 模型文件
└── scripts/                # 辅助脚本

🛣️ 路线图

Milestone 1–6 —— 基础录制 → 音频增强(RNNoise) → 离线 ASR(Whisper) → 实时 ASR → 性能优化 → AudioMixer / RingBuffer / 词级时间戳 —— ✅ 全部完成。

集成层路线图（v0.8.3）：

• ✅ Phase 1 Agent 集成 — CLI 硬化 + MCP server，让 AI agent 把 ffvoice 当本地离线语音工具调用；v0.7.0 已发布到 PyPI
• 🧪 Phase 2 滚动字幕流 — LiveCaptioner 已有 partial/final 事件；真正低延迟对话接入仍需异步推理、取消与积压观测
• ✅ Phase 3 说话人分离 — Diarizer（sherpa-onnx 离线 diarization），CLI --diarize + MCP transcribe_file_with_diarization

下一阶段：面向 Open Voice Agent 的稳定输入层

• ✅ v0.8.4 正确性与可观测性 — 采样率一致性、mono 合同、丢样计数、类型桩。
• 🧪 v0.9 对话流式核心 — 已完成采集/VAD 与 Whisper 解耦、有界任务队列、final 优先、generation 取消、会话 reset，以及 backlog/drop/queue-wait/final-latency 指标；尚缺 whisper.cpp 在途计算中止与真实设备端点验证。
• v1.0 采用门槛 — 真实设备语料上的 WER、RTF、端点延迟、丢样基线；验证 wheel 矩阵；由 Open Voice Agent 通过稳定 provider 合同消费。

完整历史见 CHANGELOG.md。

📝 开发说明

主分支：master

コード規約

• C++20 標準
• Google C++ Style Guide（一部）
• clang-format でフォーマット

テスト

# 配置并编译测试
cmake .. -DBUILD_TESTS=ON -DCMAKE_BUILD_TYPE=Debug
make -j4

# 运行所有测试
make test

# 运行单个测试（详细输出）
./build/tests/ffvoice_tests --gtest_filter=WavWriter*

実装済み機能

AudioCaptureDevice - 音声キャプチャ

• PortAudio に基づくクロスプラットフォームの音声キャプチャ
• リアルタイムストリーミングキャプチャ（コールバックモード）
• デバイスの列挙と自動選択
• 低遅延設定（256 フレームバッファー）
• モノラル／ステレオに対応
• サンプリングレートを設定可能（デフォルトは 48kHz）

WavWriter - WAV ファイル書き込み

• RIFF/WAV 形式を手動で実装
• PCM 16-bit 音声に対応
• モノラル／ステレオに対応
• サンプリングレートを調整可能
• リアルタイム書き込みに対応

FlacWriter - FLAC 可逆圧縮

• libFLAC 1.5.0 に基づく
• リアルタイムストリーミングエンコード
• 圧縮レベルを設定可能（0-8、デフォルトは 5）
• 圧縮率 1.5-3x（音声の内容によって異なります）
• 16/24-bit PCM に対応
• 圧縮率を自動集計

SignalGenerator - 音声信号生成器

• 正弦波の生成（周波数、長さ、振幅を調整可能）
• 無音の生成
• ホワイトノイズの生成
• テストとデバッグに使用

AudioProcessor - 音声処理フレームワーク

アーキテクチャ設計：

• 抽象インターフェース AudioProcessor によるモジュール型の拡張
• AudioProcessorChain プロセッサーチェーン（複数のプロセッサーを連結）
• リアルタイム処理（キャプチャコールバック内で実行）
• インプレース処理により効率を向上

VolumeNormalizer - 音量正規化：

• RMS ベースの自動ゲイン制御
• ゲインを滑らかに調整（指数移動平均）
  • Attack time：0.1s（ゲイン上昇速度）
  • Release time：0.3s（ゲイン下降速度）
• 目標レベル：0.3（0.0-1.0 の範囲で設定可能）
• ゲイン範囲：0.1x - 10.0x
• クリッピングを防止し、一貫したラウドネスを維持

HighPassFilter - ハイパスフィルター：

• 1 次 IIR フィルターを実装
• 低周波ノイズを除去（呼吸音、マイクへの衝撃、環境ノイズ）
• デフォルトのカットオフ周波数：80Hz（設定可能）
• チャンネルごとに独立した状態（ステレオに対応）
• フィルターの式：y[n] = α(y[n-1] + x[n] - x[n-1])

RNNoiseProcessor - RNNoise ディープラーニングノイズ抑制（オプション）：

• Xiph RNNoise の RNN ディープラーニングモデルに基づく
• 音声向けに最適化されたノイズ抑制アルゴリズム
• フレームサイズ：480 samples (10ms @48kHz)
• 対応サンプリングレート：48kHz, 44.1kHz, 24kHz
• マルチチャンネル対応：チャンネルごとに独立した DenoiseState
• 形式変換：int16 ↔ float を自動処理
• フレームバッファー管理：256 samples → 480 samples
• VAD オプション：音声活動検出を選択可能（実験的）
• CPU 負荷：~5-10%（WebRTC APM より大幅に低い）
• ノイズ抑制効果：~20dB（音声シーン）

パフォーマンス：

• リアルタイム処理（遅延 <10ms）
• CPU 負荷が低い（RNNoise：~8%）
• モノラル／ステレオに対応

WhisperProcessor - オフライン音声認識（オプション）

• OpenAI Whisper の C++ 実装（whisper.cpp）に基づく
• tiny モデル（39MB）を自動ダウンロードして統合
• 複数の言語の認識に対応（中国語、英語、自動検出）
• 音声形式を自動変換（WAV/FLAC → 16kHz float mono）
• 4 種類の出力形式：
  • プレーンテキスト（タイムスタンプなし）
  • SRT 字幕（SubRip 形式）
  • VTT 字幕（WebVTT 形式）
  • JSON 文字起こし（セグメント単位および単語単位のタイムスタンプを含む）
• 単語単位のタイムスタンプ：各セグメントに words 配列が付属し、各単語に個別の開始・終了時間と確率があります（WhisperConfig::word_timestamps）
• パフォーマンス指標（Apple M3 Pro, Rosetta 2）：
  • 文字起こし速度：リアルタイムの 5-75 倍（音声の長さによって異なります）
  • メモリー使用量：~272MB（モデル + 計算バッファー）
  • 精度：英語 ~8-10% WER、中国語 ~12-15% WER
• 推論スレッド数を設定可能（デフォルトは 4 スレッド）
• 翻訳機能を選択可能（文字起こし + 英語への翻訳）

パフォーマンス最適化（v0.3.0 で追加）：

• Whisper モデルの選択：
  • TINY/BASE/SMALL/MEDIUM/LARGE モデルに対応
  • 速度と精度のバランスを柔軟に調整（リアルタイムの 10 倍 → 0.5 倍）
• パフォーマンス計測システム：
  • 詳細なセグメント別計測（変換／推論／抽出）
  • リアルタイム係数（RTF）を自動計算
  • パフォーマンスのボトルネックを特定
• VAD によるインテリジェントな最適化：
  • 5 種類の感度プリセット（VERY_SENSITIVE → VERY_CONSERVATIVE）
  • 適応型しきい値調整（環境ノイズに応じて動的に最適化）
  • リアルタイム統計（平均 VAD 確率、音声比率）
• メモリー最適化：
  • バッファーの再利用（メモリー割り当てを 90% 削減）
  • 条件付き拡張（不要な resize を回避）
  • メモリーの断片化と GC の負荷を軽減

AudioConverter - 音声形式変換：

• WAV/FLAC ファイルの読み込み
• サンプリングレート変換（48kHz/44.1kHz → 16kHz）
• 形式変換（int16 → float）
• チャンネル変換（stereo → mono）
• 線形補間によるリサンプリング

SubtitleGenerator - 字幕生成：

• SRT 形式（00:00:01,500 タイムスタンプ形式）
• VTT 形式（00:00:01.500 タイムスタンプ形式 + WEBVTT ヘッダー）
• プレーンテキスト形式（タイムスタンプなし）
• タイムスタンプを自動フォーマット

テストカバレッジ

• 現在、C++ の単体テスト 296 件と Python のテスト 146 件がすべて成功
• 音声キャプチャ／エンコード（WAV・FLAC）／処理（正規化・ハイパス・RNNoise）／VAD／Whisper ASR／字幕生成／LiveCaptioner／Diarizer／AudioMixer／RingBuffer をカバー
• C++ では Google Test、Python では pytest を使用
• CI マトリックスは Linux／macOS／Windows × Python 3.10–3.14 をカバー

🤝 貢献

あらゆる形での貢献を歓迎し、感謝しています！バグの報告、新機能の提案、ドキュメントの改善、コードの提出など、どのような貢献もプロジェクトにとって大きな助けになります。

バグの報告、新機能の提案、ドキュメントの改善、コードの提出など、あらゆる形での貢献を歓迎し、感謝しています。

貢献方法

1. 🐛 バグを報告 - バグ報告テンプレートを使用
2. ✨ 機能をリクエスト - 機能リクエストテンプレートを使用
3. 📝 ドキュメントを改善 - PR を提出して README、docs、またはコードコメントを改善
4. 💻 コードを提出 - Fork → 開発 → テスト → PR

開発ガイド

詳しい貢献ガイドについては、CONTRIBUTING.mdを参照してください。

クイックスタート：

# 1. Fork 并克隆仓库
git clone https://github.com/YOUR_USERNAME/ffvoice-engine.git

# 2. 创建功能分支
git checkout -b feature/your-feature-name

# 3. 进行开发并测试
cmake -B build -DBUILD_TESTS=ON
make -C build -j$(nproc)
make -C build test

# 4. 格式化代码
./scripts/format.sh

# 5. 提交并推送
git commit -m "feat: add your feature"
git push origin feature/your-feature-name

# 6. 创建 Pull Request

コードスタイル

• 言語：C++20
• スタイルガイド：Google C++ Style Guide（派生版）
• フォーマットツール：clang-format（設定は .clang-format を参照）
• 静的解析：clang-tidy（設定は .clang-tidy を参照）
• コミット規約：Conventional Commits

行動規範 / 行動規範

行動規範を遵守し、誰もが歓迎され、包摂されるコミュニティ環境を維持してください。

行動規範を遵守し、誰もが歓迎され、包摂されるコミュニティ環境を維持してください。

---

📊 プロジェクトの状況 / プロジェクトの状況

• ✅ Milestone 1: 基本的な音声の取得とファイル保存 - 完了
• ✅ Milestone 2: 音声処理の強化（RNNoise） - 完了
• ✅ Milestone 3: オフライン音声認識（Whisper ASR） - 完了
• ✅ Milestone 4: リアルタイム音声認識 - 完了
• ✅ Milestone 5: パフォーマンスの最適化と強化 - 完了
• ✅ Milestone 6: 高度な機能（AudioMixer / RingBuffer / 単語レベルのタイムスタンプ / JSON 字幕） - 完了
• ✅ 統合レイヤーのロードマップ（v0.8.3）: エージェント統合（CLI + MCP）/ リアルタイム字幕ストリーム / 話者分離 - 完了

詳細は CHANGELOG.md をご覧ください。

---

📞 サポートとフィードバック / サポートとフィードバック

• 📖 ドキュメント: docs/
• 💬 ディスカッション: GitHub Discussions
• 🐛 バグ報告: GitHub Issues
• 📧 お問い合わせ: [email protected]

---

📄 ライセンス / ライセンス

本プロジェクトは MIT ライセンスを採用しています。詳細は LICENSE ファイルをご覧ください。

本プロジェクトは MIT ライセンスのもとでライセンスされています。詳細は LICENSE ファイルをご覧ください。

---

🙏 謝辞 / 謝辞

以下のオープンソースプロジェクトに感謝します。

以下のオープンソースプロジェクトに感謝します。

• FFmpeg - マルチメディア処理フレームワーク
• PortAudio - クロスプラットフォームのオーディオ I/O ライブラリ
• FLAC - ロスレス音声圧縮
• whisper.cpp - OpenAI Whisper の C++ 実装
• RNNoise - ディープラーニングによるノイズ低減ライブラリ
• Google Test - C++ テストフレームワーク

---

⭐ Star History

このプロジェクトがお役に立ちましたら、ぜひ ⭐ Star をお願いします！

このプロジェクトがお役に立ちましたら、ぜひ ⭐ Star をお願いします！

---

ffvoice-engine チームが ❤️ を込めて作成

⬆️ トップに戻る