把 .wav 送進去，拿回含 start / end / text 的 JSON 轉寫結果。 Provider 可替換，CPU CI 也能跑完整流程。

安裝  ·  執行  ·  輸出格式  ·  換 Provider  ·  授權

---

安裝

python -m venv .venv
. .venv/bin/activate          # Windows: .venv\Scripts\activate
pip install -e .[dev]

---

執行

# 產生示範音檔（合成靜音，不含真實語料）
python scripts/generate_demo_wav.py

# 執行轉寫
whisper-run transcribe --input ./out/demo.wav --lang zh --provider mock --output ./out/demo.json

# 驗證輸出格式
whisper-run validate --input ./out/demo.json

---

輸出格式

{
  "language": "zh",
  "segments": [
    { "start": 0.0, "end": 1.0, "text": "[zh] demo" }
  ]
}

---

Python API

from whisper_starter.pipeline import transcribe_file
from whisper_starter.providers.mock_provider import MockProvider

result = transcribe_file(audio_path="out/demo.wav", language="zh", provider=MockProvider())
print(result)

---

換成自己的推論後端

MockProvider 用於測試，不需要 GPU。換成實際推論後端時，繼承 WhisperProvider 協定即可：

from whisper_starter.providers.faster_whisper_provider import FasterWhisperProvider

provider = FasterWhisperProvider(model_name="small")
result = transcribe_file(audio_path="audio.wav", language="zh", provider=provider)

faster-whisper 需自行安裝：pip install faster-whisper

---

適合這些情境

• 需要讓轉寫後端可替換，而不是寫死在流程裡
• 想在 CPU CI 跑完整轉寫測試，不依賴 GPU 環境
• 需要一個有測試覆蓋的轉寫輸出基線

---

不包含

• 真實語料與客戶詞庫
• 模型選型策略、後處理規則、任何 Prompt 資產

詳見 docs/threat-model.md。

---

開發

pytest -q

---

授權

本專案採 MIT License 授權，永久免費、可商業使用、可修改、可散佈。

權利	說明
✅ 免費使用	個人、商業、學術皆可，不收費
✅ 可修改	可依需求自由調整原始碼
✅ 可散佈	可重新散佈原始或修改版本
✅ 可商業使用	可用於商業產品中
ℹ️ 保留聲明	散佈時需保留原始版權與授權聲明

版權所有 © 2026 eGroupAI 益群健康資訊

---

維護者

本 repo 由 eGroupAI 益群健康資訊 維護，作為公司開源貢獻的一部分。

項目	資訊
官網	https://www.egroupai.com/zh-TW
聯絡信箱	service@egroupai.com
GitHub 組織	github.com/eGroupAI

如有問題或建議，歡迎透過 GitHub Issues 或上述信箱與我們聯絡。