{"id":49857135,"url":"https://github.com/thc1006/breeze-asr-taigi","last_synced_at":"2026-05-14T20:33:48.609Z","repository":{"id":351839518,"uuid":"1212691888","full_name":"thc1006/breeze-asr-taigi","owner":"thc1006","description":"Taiwanese Hokkien (Taigi) speech-to-text transcriber - MediaTek Breeze-ASR-26 with faster-whisper, tuned for RTX 3050 4GB low-VRAM GPUs. Gradio UI, CLI, Docker, SRT/VTT/TXT/JSON.","archived":false,"fork":false,"pushed_at":"2026-05-06T21:20:25.000Z","size":167,"stargazers_count":7,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-06T22:35:11.696Z","etag":null,"topics":["asr","automatic-speech-recognition","breeze-asr","chinese-speech-recognition","ctranslate2","faster-whisper","gradio","hokkien","low-vram","mediatek","pytorch","rtx-3050","speech-recognition","speech-to-text","subtitle-generator","taigi","taiwanese","whisper"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/thc1006.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-16T16:25:23.000Z","updated_at":"2026-05-06T21:20:26.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/thc1006/breeze-asr-taigi","commit_stats":null,"previous_names":["thc1006/breeze-asr-taigi"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/thc1006/breeze-asr-taigi","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thc1006%2Fbreeze-asr-taigi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thc1006%2Fbreeze-asr-taigi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thc1006%2Fbreeze-asr-taigi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thc1006%2Fbreeze-asr-taigi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/thc1006","download_url":"https://codeload.github.com/thc1006/breeze-asr-taigi/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thc1006%2Fbreeze-asr-taigi/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33042253,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-13T13:14:54.681Z","status":"online","status_checked_at":"2026-05-14T02:00:06.663Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["asr","automatic-speech-recognition","breeze-asr","chinese-speech-recognition","ctranslate2","faster-whisper","gradio","hokkien","low-vram","mediatek","pytorch","rtx-3050","speech-recognition","speech-to-text","subtitle-generator","taigi","taiwanese","whisper"],"created_at":"2026-05-14T20:33:47.739Z","updated_at":"2026-05-14T20:33:48.598Z","avatar_url":"https://github.com/thc1006.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# taigi-asr\n\n**台灣台語語音轉錄器 / Taiwanese Hokkien ASR Transcriber**\n\n以 [MediaTek **Breeze-ASR-26**](https://huggingface.co/MediaTek-Research/Breeze-ASR-26) 為核心，專為 **NVIDIA RTX 3050 Laptop 4GB VRAM** 等低顯存環境最佳化，支援句級時間戳記、SRT/VTT/TXT/JSON 多格式輸出、Gradio Web UI、CLI、WSL2/Docker。\n\n---\n\n## 特色\n\n- **台語專用**：基於 Whisper-large-v2 微調，~10,000 小時台語資料（MediaTek 官方）。\n- **RTX 3050 4GB 可跑**：int8_float16 量化下峰值 VRAM 約 2.9 GB，留出安全空間。\n- **雙引擎自動路由**：依偵測 VRAM 自動選擇 Faster-Whisper (CTranslate2) 或 HuggingFace Pipeline。\n- **時間戳記對齊**：句級（預設）與可選逐字（`--word-timestamps`）。\n- **零摩擦 UI**：拖放音檔 -\u003e 點「開始轉錄」-\u003e 下載字幕檔。\n- **廣泛格式**：`m4a / mp3 / wav / mp4 / mov / mkv / flac / ogg / webm` 全部透過 ffmpeg。\n- **完整測試**：unit + smoke + integration（pytest），GitHub Actions CI Linux/Windows 多版本。\n- **Docker + WSL2 支援**：CUDA 12.1 runtime + GPU passthrough + 模型 cache volume。\n\n## 模型來源（固定，不替代）\n\n| 引擎 | HuggingFace Model ID |\n|---|---|\n| Faster-Whisper (CT2) | [`paulpengtw/faster-whisper-Breeze-ASR-26`](https://huggingface.co/paulpengtw/faster-whisper-Breeze-ASR-26) |\n| HuggingFace Pipeline | [`MediaTek-Research/Breeze-ASR-26`](https://huggingface.co/MediaTek-Research/Breeze-ASR-26) |\n\n---\n\n## 快速開始 / Quick Start\n\n### Windows (native + GPU)\n\n```batch\ngit clone https://github.com/thc1006/breeze-asr-taigi.git\ncd breeze-asr-taigi\ninstall.bat        REM 建 venv + 裝 CUDA 12.1 torch + 下載模型 (~2.9 GB)\nstart.bat          REM 啟動 Gradio UI + 自動開瀏覽器 http://127.0.0.1:7860\n```\n\n### Linux / WSL2 (native)\n\n```bash\ngit clone https://github.com/thc1006/breeze-asr-taigi.git\ncd breeze-asr-taigi\n./install.sh        # 建 venv + 裝 CUDA 12.1 torch + 下載模型\n./start.sh          # 啟動 Gradio UI\n```\n\n### Docker (WSL2 / Linux with NVIDIA Container Toolkit)\n\n```bash\n./install.sh --docker\n# 或手動：\ndocker compose up -d\n# 開啟 http://localhost:7860\n```\n\n---\n\n## CLI 用法\n\n```bash\n# 單檔\ntaigi-asr data/test.m4a --format srt --out out.srt\ntaigi-asr long_audio.mp3 --engine fw --beam-size 10 --word-timestamps\ntaigi-asr interview.wav --format json --out interview.json -v\n\n# 多檔批次（模型只載入一次，省 ~9 秒 / 檔）\ntaigi-asr a.mp3 b.m4a c.wav --format srt,txt\ntaigi-asr --input-dir music/ --format srt,json\ntaigi-asr clip1.mp3 --input-dir more_clips/ --format srt   # 兩種來源可混用\n```\n\nCLI 選項：\n| 參數 | 預設 | 說明 |\n|---|---|---|\n| `audio` | — | 一或多個音檔路徑（多檔時模型只 load 一次） |\n| `--input-dir` | — | 把目錄內所有支援副檔名的音檔加入批次（非遞迴） |\n| `--engine` | `auto` | `auto` / `fw` (faster-whisper) / `hf` (huggingface)；可用 `TAIGI_ASR_DEFAULT_ENGINE` 環境變數覆蓋 |\n| `--format` | `srt` | `srt` / `txt` / `vtt` / `json`，多格式以逗號串接（例：`srt,txt,json`）|\n| `--out` | 自動 | 輸出路徑（**只在單檔 + 單格式時生效**；其他情況輸出落在輸入旁） |\n| `--beam-size` | 5 | beam search 寬度（4GB GPU 建議 5-10）|\n| `--best-of` | 5 | 溫度採樣候選數 |\n| `--word-timestamps` | False | 逐字時間戳記（較慢）|\n| `-v` / `-vv` | WARN | 增加 log 詳細度 |\n\n`--input-dir` 自動撈的副檔名：`.mp3`, `.m4a`, `.wav`, `.flac`, `.ogg`, `.webm`, `.mp4`, `.mkv`, `.aac`, `.opus`, `.wma`。其他格式（如 `.aiff`）只要 ffmpeg 認得，仍可走 positional 直接傳。\n\n退出碼：\n| 代碼 | 含義 |\n|---|---|\n| `0` | 全部成功 |\n| `2` | 找不到輸入檔 / `--input-dir` 不存在 / 沒給任何輸入 |\n| `3` | 偵測到的 VRAM 不足以跑指定的 engine |\n| `4` | 模型 load 失敗，或所有檔案皆失敗（含「轉錄為空」也計入失敗）|\n| `6` | `--format` 指定了未知格式 |\n| `7` | 多檔批次中部分檔案失敗（其他成功）|\n\n## Python API\n\n```python\nfrom taigi_asr.audio import AudioConverter\nfrom taigi_asr.engines import build_engine\nfrom taigi_asr.formatters import to_srt\nfrom taigi_asr.router import EngineKind, EngineRouter, GPUProfiler\n\ninfo = GPUProfiler.detect()\nspec = EngineRouter.select(info)           # 自動路由\nwav, duration = AudioConverter.convert(\"audio.m4a\")\n\nengine = build_engine(spec)\nengine.load()\n\n# beam_size / best_of 只在 Faster-Whisper 引擎支援,\n# HuggingFace 引擎的 transcribe() 簽章只吃 word_timestamps,\n# 所以用 spec.kind 分流避免 TypeError。\nif spec.kind is EngineKind.FASTER_WHISPER:\n    segments = engine.transcribe(wav, beam_size=5)\nelse:\n    segments = engine.transcribe(wav)\n\nsrt = to_srt(segments)\nengine.unload()\n```\n\n或是要顯式鎖一個引擎時,直接建構 `FasterWhisperEngine`(不走 router):\n\n```python\nfrom taigi_asr.engines.faster_whisper import FasterWhisperEngine\n\nengine = FasterWhisperEngine(\n    device=\"cuda\", compute_type=\"int8_float16\", batch_size=4, beam_size=5\n)\nengine.load()\nsegments = engine.transcribe(\"audio.m4a\")\n```\n\n---\n\n## VRAM 決策表\n\n偵測到的 VRAM 會自動選擇配置；亦可用 `--engine` 強制覆蓋。\n\n| VRAM | 自動引擎 | compute_type | batch_size | 備註 |\n|---|---|---|---|---|\n| \u003e= 22 GB (A100/L4) | HuggingFace | float16 | 16 | 最高吞吐 |\n| \u003e= 14 GB (4070+) | HuggingFace | float16 | 8 | 預設快 |\n| \u003e= 10 GB (3080+) | HuggingFace | float16 | 4 | |\n| \u003e= 6 GB (RTX 4060/A2000) | HuggingFace | int8 (bitsandbytes) | 2 | Linux only |\n| \u003e= 3.5 GB (**RTX 3050 4GB**) | **Faster-Whisper** | **int8_float16** | **4** | **主力路徑** |\n| \u003c 3.5 GB | Faster-Whisper | int8_float16 | 2 | 緊湊配置 |\n| 無 CUDA | Faster-Whisper | int8 (CPU) | 1 | 純 CPU |\n\n---\n\n## 效能 (RTX 3050 Laptop 4GB)\n\n在 `int8_float16` + `beam_size=5` + `batch_size=4` 配置下的實測：\n\n| 測試音檔 | 長度 | Transcribe | Peak VRAM | xRT |\n|---|---|---|---|---|\n| `data/test.m4a` | 5.7 s | 1.9 s | ~2.0 GB | 2.93x |\n| `data/test.mp3` | 54 min | **5 min 26 s** | **2.03 GB** | **9.94x** |\n\n\u003e 長音檔 xRT 顯著優於短音檔，因為 Silero VAD 跳過 60-70% 的訪談靜音、且 batched 解碼並行化顯著。Model load (~6-9s) 一次性。\n\n更完整 benchmark 請見 [`docs/benchmarks.md`](docs/benchmarks.md)。\n\n---\n\n## 專案結構\n\n```\nsrc/taigi_asr/\n  segments.py         # TimestampedSegment dataclass\n  formatters.py       # to_txt / to_srt / to_vtt / to_json\n  audio.py            # AudioConverter (16 kHz mono)\n  router.py           # GPUProfiler + EngineRouter\n  engines/\n    base.py           # ASREngine Protocol\n    faster_whisper.py # FasterWhisperEngine (CT2)\n    huggingface.py    # HuggingFaceEngine (transformers)\n    fake.py           # FakeEngine (tests)\n  ui/\n    gradio_app.py     # Gradio Blocks\n    launcher.py       # python -m taigi_asr.ui.launcher\n  cli.py              # python -m taigi_asr.cli\ntests/\n  unit/               # unit tests (CPU-only, \u003c3s)\n  smoke/              # CLI + UI smoke tests\n  integration/        # Real model on test.m4a (marked slow)\n```\n\n---\n\n## 開發\n\n```bash\npip install -e \".[dev,hf]\"\npytest tests/unit tests/smoke       # 快速\npytest -m slow                       # integration (需 GPU + 模型)\nruff check . \u0026\u0026 ruff format --check .\npre-commit install\n```\n\n---\n\n## 疑難排解 / FAQ\n\n見 [`docs/faq.md`](docs/faq.md)：\n- CUDA not found / WSL2 GPU passthrough\n- OOM on 4GB\n- bitsandbytes Windows 失敗\n- torch.compile 錯誤\n- 音檔格式不支援\n\n---\n\n## 致謝\n\n- [MediaTek Research](https://huggingface.co/MediaTek-Research) - Breeze-ASR-26 官方模型\n- [SYSTRAN / faster-whisper](https://github.com/SYSTRAN/faster-whisper) - CTranslate2 推論框架\n- [paulpengtw](https://huggingface.co/paulpengtw) - CT2 預轉換模型\n- [OpenAI Whisper](https://github.com/openai/whisper) - 底層架構\n\n## License\n\nMIT. See [LICENSE](LICENSE). 模型授權請見各 HuggingFace 模型頁。\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthc1006%2Fbreeze-asr-taigi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthc1006%2Fbreeze-asr-taigi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthc1006%2Fbreeze-asr-taigi/lists"}