181bc28d33
The Web Audio beep test was a spike for the WASM-TTS path (B), which was dropped in favour of guiding Android users to system Select-to-Speak (C). The plugin plays via speechSynthesis, not Web Audio, so the command tested an unused subsystem and only cluttered the palette. The TTS diagnostics command (speechSynthesis state + WebView version) stays as a genuine no-sound troubleshooter. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> |
||
|---|---|---|
| .github/workflows | ||
| docs | ||
| src | ||
| tests | ||
| .gitignore | ||
| .nvmrc | ||
| esbuild.config.mjs | ||
| eslint.config.mjs | ||
| LICENSE | ||
| manifest.json | ||
| package-lock.json | ||
| package.json | ||
| README.md | ||
| styles.css | ||
| tsconfig.json | ||
| tsconfig.test.json | ||
| versions.json | ||
Hans TW TTS
中文為主 · English below
給台灣使用者的 Obsidian 語音朗讀外掛:用各平台系統內建的中文語音把筆記唸出來,逐句反白跟讀。免費、離線、跨平台,介面全繁體中文。走瀏覽器內建 Web Speech API 與系統語音,不依賴任何外部伺服器。
中文
功能
- 一鍵朗讀目前筆記,或只朗讀選取的文字,或從游標處開始唸
- 資料夾連播:右鍵資料夾一次唸完整個資料夾,可設定讀完自動下一篇
- 發音字典:自訂破音字 / 專有名詞唸法(iPAS、臺、GPT…),全 Obsidian TTS 外掛獨家
- 獨立朗讀窗格逐句顯示筆記;唸到哪句那句就反白 + 自動捲到可視範圍
- 播放 / 暫停 / 繼續 / 停止 / 上一句 / 下一句;播放當下可調語速
- 點窗格裡任一句,從那句開始唸
- 設定:選語音(清單依品質排序,預設自動挑最佳)、調語速
- 全繁體中文介面
安裝
A. 官方社群外掛(審核通過後) 設定 → 社群外掛 → 瀏覽 → 搜「Hans TW TTS」→ 安裝 → 啟用。
B. BRAT(現在就能用,電腦與手機都可)
- 在社群外掛安裝 BRAT(Obsidian42 - BRAT)並啟用。
- 命令面板 →「BRAT: Add a beta plugin」。
- 貼上
hansai-art/obsidian-tw-tts,確認。 - 回社群外掛啟用「Hans TW TTS」。
C. 手動
到 最新 release 下載 main.js、manifest.json、styles.css,放進 <vault>/.obsidian/plugins/tw-read-aloud/,再啟用外掛。手機上 .obsidian 是隱藏資料夾,通常用 BRAT 較方便。
怎麼用
朗讀目前筆記(任選一種):
- 點左側工具列的喇叭圖示
- 點視窗底部狀態列的「🔊 朗讀」
- 命令面板(
Cmd/Ctrl + P)→「朗讀目前筆記」
其他:
- 選取一段文字 → 命令面板「朗讀選取文字」,只唸選取的
- 從游標處開始唸:命令面板「從游標處開始唸」,從游標所在的那句起讀
- 資料夾連播:檔案總管右鍵資料夾 →「朗讀此資料夾」,一篇接一篇連續唸(命令面板「朗讀目前資料夾」亦可)
- 右側會開朗讀窗格,逐句顯示;唸到的那句會反白;連播時頂端顯示篇名與進度(2/5)
- 控制列:上一句 / 播放暫停 / 停止 / 下一句
- 點窗格裡任一句 → 從那句開始唸
- 命令面板「停止朗讀」可隨時停
設定
設定 → 社群外掛 → Hans TW TTS:
- 語音:預設「自動(推薦最佳語音)」。下拉清單依品質排序,最上面是目前平台最推薦的(台灣中文優先),並標了地區(台灣/大陸/香港)。品質太差或重複的角色/機械音會自動壓到最後或隱藏。
- 語速:0.5(最慢)到 2.0(最快)。旁邊有回到預設(1.0x)與試聽兩顆按鈕。
- 播放當下也能調語速:朗讀窗格控制列有
− 1.0x +,點中間數字即回到 1.0x。 - 單篇讀完自動下一篇:開啟後,唸完一篇會自動接著唸同資料夾的下一篇。
- 資料夾連播含子資料夾:右鍵連播時是否也含子資料夾內的筆記(預設只該層)。
- 發音字典:一行一條「原文=唸法」(
#開頭為註解),校正破音字與專有名詞。例:iPAS=愛帕斯、臺=台。只改朗讀發音,畫面仍顯示原文。
平台支援
| 平台 | 支援 | 說明 |
|---|---|---|
| macOS | ✅ | 用系統內建中文語音 |
| Windows | ✅ | 需在系統安裝中文語音 |
| iPhone / iPad | ✅ | 用 iOS 內建中文語音 |
| Android | ❌ 外掛內不支援(改用系統朗讀) | Obsidian 的 Android WebView 未開放語音介面(Chromium 長年未修的 bug),所有外掛皆無法直接朗讀。改用系統「選取即朗讀」即可用台灣語音、免費、離線,見下方步驟 |
Android 為什麼不能在外掛內朗讀: 這不是本外掛的問題,而是 Obsidian 的 Android WebView 沒有把系統語音接進 Web Speech API(Chromium 開了十多年沒修的 bug,連 speechSynthesis 介面都不給)。所有 TTS 外掛在 Android 都一樣,純外掛無法碰到系統原生語音。
Android 建議做法(系統「選取即朗讀」,台灣語音、免費、離線):
- 裝台灣語音:系統設定搜尋「文字轉語音」→ 偏好引擎選 Google →「安裝語音資料」→「中文(台灣)」。
- 開啟朗讀:系統設定 →「協助工具 / 無障礙」→「選取即朗讀 / Select to Speak」→ 開啟。
- 使用:在 Obsidian 選取要唸的文字 → 點出現的「選取即朗讀」圖示 → 系統用台灣語音唸出來。
（各廠牌選單名稱略有不同;找不到時直接搜尋「文字轉語音」「選取即朗讀」。想要逐句反白、資料夾連播等外掛功能,請在電腦或 iPhone / iPad 使用。）
找不到中文語音怎麼辦
外掛偵測不到中文語音時,會在朗讀窗格內顯示「原因 + 解法」面板。請先到系統安裝中文語音:
- macOS:系統設定 → 輔助使用 → 朗讀內容 → 系統聲音,加入中文(台灣)
- Windows:設定 → 時間與語言 → 語音,新增中文語音
- iPhone / iPad:設定 → 輔助使用 → 朗讀內容 → 聲音 → 中文,下載語音
開發
- TypeScript + esbuild。
npm run dev監看建置,npm run build正式建置。 npm test跑單元測試(Node 內建測試 runner + tsx)。- 純邏輯(
sentence-splitter、tts-engine、voice-catalog、pronunciation、note-order、setting-defs、playback-error)與 Obsidian 解耦,可獨立測試。
授權
MIT。原創程式碼,不衍生自任何 AGPL 專案。
English
An Obsidian plugin (Traditional-Chinese first) that reads your notes aloud using your device's built-in Traditional Chinese system voice, with sentence-by-sentence highlight follow. Free, offline, cross-platform. It uses the Web Speech API and each platform's system voices, so it does not depend on any external server.
Features
- Read the current note aloud, or read only the selected text
- A dedicated reader pane shows the note sentence by sentence; the sentence being read is highlighted and auto-scrolled into view
- Play / Pause / Resume / Stop / Previous / Next sentence
- Click any sentence in the pane to start reading from there
- Settings: choose a voice (defaults to a Traditional Chinese voice) and adjust speed
- Traditional Chinese interface
Installation
A. Community Plugins (once approved): Settings → Community plugins → Browse → search "Hans TW TTS" → Install → Enable.
B. BRAT (works now, desktop and mobile): Install the BRAT plugin, then command palette → "BRAT: Add a beta plugin" → paste hansai-art/obsidian-tw-tts → enable "Hans TW TTS".
C. Manual: Download main.js, manifest.json, styles.css from the latest release into <vault>/.obsidian/plugins/tw-read-aloud/, then enable the plugin.
Usage
Read the current note via the ribbon speaker icon, the status-bar "🔊 朗讀" button, or the command "朗讀目前筆記". Select text and run "朗讀選取文字" to read only the selection, or "從游標處開始唸" to start from the sentence at your cursor. Right-click a folder → "朗讀此資料夾" to play every note in it back-to-back. The reader pane opens on the right, highlights each sentence as it is read (with the note title + position when playing a folder), and click any sentence to start from there. "停止朗讀" stops playback.
Settings let you pick a voice (quality-ranked, best first, Taiwan Chinese preferred, region-labelled; low-quality character voices sink or hide), adjust/reset/preview speed, toggle auto-advance to the next note in a folder, choose whether folder playback recurses into subfolders, and define a pronunciation dictionary (one 原文=唸法 rule per line) to fix how proper nouns and heteronyms are read — no other Obsidian TTS plugin has this. The reader pane also has a live speed control (− [1.0x] +).
Platform support
macOS ✅ · Windows ✅ · iPhone/iPad ✅ · Android ❌ not supported. Obsidian's Android WebView does not expose the Web Speech API (a known Chromium bug that blocks every offline TTS plugin). Use desktop/iOS, or Android's system Select to Speak (Settings → Accessibility) to read notes on Android.
License
MIT. Original code; not derived from any AGPL project.