Hans TW TTS

中文為主 · English below

給繁中使用者的筆記跟讀與連播外掛：預設用各平台系統內建的中文語音免費、離線朗讀；桌面可切換免 Key 的 Edge CLI，或使用自己的 Azure Speech Key。支援逐句反白、游標起讀、資料夾連播、發音字典、不朗讀符號，以及 Callout／Highlightr 格式清理。只有主動選擇線上引擎時，朗讀文字才會送到 Microsoft。

---

中文

0.18.0：通勤播放、安全快取與繁中自然朗讀

• 支援續讀書籤、句級進度與跳轉、鍵盤控制，以及 Media Session 播放控制。
• Edge CLI 與 Azure 語音加入句級音訊快取；可清除快取，並可將單篇筆記匯出為 MP3。
• Azure Speech Key 改存於 Obsidian SecretStorage，不再寫入外掛的一般設定資料。
• 可選擇自然化朗讀數學式、表格與中英混排內容，或只朗讀標題與粗體重點。
• 支援匯入與匯出繁中朗讀規則 JSON，並提供繁中與英文介面。

0.15.0：自然朗讀體驗

• 空白行會形成可調整的段落停頓（預設 400 ms），標題與 Callout 自訂標題後有較長的標題停頓（預設 600 ms）；兩者皆可設為 0。
• Callout 內的一至六級標題、清單、任務、表格、程式碼、數學式與註腳，現在會先按原本的 Markdown 規則處理；#、> 與空白引用行不會送到語音引擎。
• 可選擇朗讀任務狀態，例如「未完成」「已完成」「進行中」「已取消」「已排程」；預設關閉，維持只讀任務文字。
• 可選擇是否朗讀 [!type]- 預設收合 Callout 的內文；關閉時仍保留自訂標題，展開型 [!type]+ 不受影響。
• 系統語音、Edge CLI 與 Azure 共用同一份朗讀節奏與安全過濾，避免純 Markdown 結構被送去合成而中斷。

功能

• 一鍵朗讀目前筆記,或只朗讀選取的文字,或從游標處開始唸
• 資料夾連播:右鍵資料夾一次唸完整個資料夾,可設定讀完自動下一篇
• 發音字典:自訂破音字 / 專有名詞唸法(iPAS、臺、GPT…);在目前查核的主流同類外掛中少見
• 不朗讀的符號:拿來當列點的符號(○ ● ※…)可以設成不唸,不會再被唸成「零」
• 獨立朗讀窗格逐句顯示筆記;唸到哪句那句就反白 + 自動捲到可視範圍
• 播放 / 暫停 / 繼續 / 停止 / 上一句 / 下一句;播放當下可調語速
• 點窗格裡任一句,從那句開始唸
• 設定:選系統已安裝的多國語音(預設自動挑最佳中文)、調語速與音高
• 全繁體中文介面

安裝

A. 官方社群外掛（推薦） 設定 → 社群外掛 → 瀏覽 → 搜「Hans TW TTS」→ 安裝 → 啟用。

B. BRAT(現在就能用,電腦與手機都可)

1. 在社群外掛安裝 BRAT(Obsidian42 - BRAT)並啟用。
2. 命令面板 →「BRAT: Add a beta plugin」。
3. 貼上 hansai-art/obsidian-tw-tts,確認。
4. 回社群外掛啟用「Hans TW TTS」。

C. 手動 到 最新 release 下載 main.js、manifest.json、styles.css,放進 <vault>/.obsidian/plugins/tw-read-aloud/,再啟用外掛。手機上 .obsidian 是隱藏資料夾,通常用 BRAT 較方便。

怎麼用

朗讀目前筆記(任選一種):

1. 點左側工具列的喇叭圖示
2. 點視窗底部狀態列的「🔊 朗讀」
3. 命令面板(Cmd/Ctrl + P)→「朗讀目前筆記」

其他:

• 選取一段文字 → 命令面板「朗讀選取文字」,只唸選取的
• 從游標處開始唸:命令面板「從游標處開始唸」,從游標所在的那句起讀
• 資料夾連播:檔案總管右鍵資料夾 →「朗讀此資料夾」,一篇接一篇連續唸(命令面板「朗讀目前資料夾」亦可)
• 右側會開朗讀窗格,逐句顯示;唸到的那句會反白;連播時頂端顯示篇名與進度(2/5)
• 控制列:上一句 / 播放暫停 / 停止 / 下一句
• 點窗格裡任一句 → 從那句開始唸
• 命令面板「停止朗讀」可隨時停

設定

設定 → 社群外掛 → Hans TW TTS:

• 語音:預設「自動(推薦最佳語音)」。下拉清單只保留中文與英文，台灣中文優先並依品質排序；避免中文知識庫出現難以選擇的多國語音清單。
• 音高:-10 到 +10 半音，0 為原始音高。想要較低沉男聲感可用 -7；外掛會換算為 Web Speech API 支援的音高倍率，實際音色仍取決於該系統語音。
• 試聽:設定頁最上方有同一行的試聽與停止試聽。切換系統中文／英文語音時會立即試聽；英文使用英文範例，中文使用中文範例。
• 雲端語音清單:Edge CLI 與 Azure Speech 都只列精選的台灣／大陸／香港中文 Neural 聲音，全部排在英文之前；方言、卡通與角色音不列入一般清單。
• 語速:0.5(最慢)到 2.0(最快)。旁邊有**回到預設(1.0x)**按鈕。
• 播放當下也能調語速:朗讀窗格控制列有 − 1.0x +,點中間數字即回到 1.0x。
• 單篇讀完自動下一篇:開啟後,唸完一篇會自動接著唸同資料夾的下一篇。
• 資料夾連播含子資料夾:右鍵連播時是否也含子資料夾內的筆記(預設只該層)。
• 發音字典:一行一條「原文=唸法」(# 開頭為註解),校正破音字與專有名詞。例:iPAS=愛帕斯、臺=台。只改朗讀發音,畫面仍顯示原文。
• 不朗讀的符號:一行填完、用空白分隔,例:○ ● ◎ ※。這些符號送去朗讀前會被刪掉(否則 ○ 會被唸成「零」),畫面仍顯示原文。整行只有這類符號時會被安靜跳過。若同一個符號在發音字典裡另有指定唸法,以發音字典為準。
• 內容朗讀:可分別開啟「朗讀獨立標籤列」「朗讀網址」「朗讀數學式」「朗讀任務狀態」，並控制是否朗讀預設收合的 Callout 內文。前三項與任務狀態預設關閉；折疊內容預設開啟以維持舊版行為。數學式開啟時只交付原始 MathJax／LaTeX，不會轉成自然語言。
• 自然停頓:段落停頓預設 400 ms，標題與 Callout 自訂標題停頓預設 600 ms；可各自調整為 0–1500 ms。筆記最後一句不會額外等待，資料夾連播可直接銜接下一篇。

Edge 線上語音（桌面版）

外掛預設仍使用系統語音（離線）、自動挑選最佳中文語音，音高預設為 0。如要使用 Edge CLI，可在設定把「朗讀引擎」切成 Edge CLI；它預設使用 zh-CN-XiaoxiaoNeural，不需要 Azure 帳號或 API Key。第一次使用前，請在電腦安裝 edge-tts，讓終端機可執行 edge-tts。

• macOS 終端機：python3 -m pip install --user edge-tts

• Windows PowerShell：py -m pip install --user edge-tts

• 安裝後重新啟用外掛，再到設定頁按「執行環境檢查」。外掛不會自行執行 pip 或要求系統管理員權限。

• Edge CLI 是透過 Microsoft Edge 線上服務合成，朗讀文字會傳送到該服務；可隨時切回系統語音（離線）。

• 可在「Edge 語音」欄位選擇已知 voice，例如 zh-CN-YunyangNeural；再將音高設為 -7，即可使用 Yunyang 的低沉音高作為一組可選範例，並非預設值。

• Edge CLI 僅支援桌面版 Obsidian；iPhone/iPad 會自動使用既有的系統語音。

疑難排解與安全診斷

設定 → Hans TW TTS →「疑難排解與環境檢查」：

1. 按「執行環境檢查」，外掛會依目前引擎檢查系統語音 API，或實際執行 Edge／Azure 合成與播放。
2. 查看顯示的 provider、voice、語速、音高、檢查階段與錯誤代碼。
3. 仍無法解決時，按「顯示安全診斷給 AI」，再按 Cmd/Ctrl+C 複製並貼給你使用的 AI 協助排錯。

安全診斷不包含筆記內容、Azure Key、Vault 名稱、完整私人路徑或 raw stderr。設定頁的「常見問題 Q&A」也提供 Edge CLI 安裝、錯誤語音、網路逾時與 Azure 設定的解法。

Android

Android 版固定切換為系統「隨選朗讀」模式。外掛會顯示啟用與操作指引，不會嘗試啟動 Edge CLI、Azure 或 Web Speech 播放。系統模式可免費朗讀、調整速度及在背景播放，但不提供外掛逐句反白、資料夾連播或 Yunyang。基於 Android 權限限制，外掛不能自行開啟無障礙服務，仍需使用者先在系統設定中啟用。

Callout 與 Highlightr

桌機與 iPhone／iPad 的朗讀文字會略過 Obsidian Callout 的 [!type]／摺疊符號，以及 Highlightr 寫入的 <mark>／<font> 顯示標籤與色碼，只保留自訂標題及可見內文。Callout 內的標題、清單、任務、表格、程式碼、數學式與註腳會套用與正文相同的 Markdown 清理；單獨用來換段的 > 只形成段落停頓，不會建立空語音。設定可略過 [!type]- 的收合內文，但仍朗讀其自訂標題。這項相容性限於筆記原始 Markdown 中的 Callout 與上述標籤，不代表支援所有第三方外掛或所有 HTML。

自動略過 Obsidian 語法

Hans TW TTS 在切句與交給任何語音引擎前，會先用同一套內容解析器清理筆記。預設會略過 Block ID（如 ^473eef）、%% comments %%、HTML comments、Footnotes、Embed syntax、fenced code blocks 與 Callout metadata；Markdown link／wikilink 則保留可見文字。朗讀窗格顯示的也是清理後內容，因此系統語音、Edge CLI、Azure、選取朗讀及游標起讀會保持一致。

獨立標籤列、直接出現的 http/https 網址與數學式可在「內容朗讀」設定中個別開啟。未知或無法確定的語法會保守保留，避免誤刪正文。

本外掛的內容清理功能適用於由 Hans TW TTS 自己處理朗讀的桌機與 iOS 路徑；Android 系統隨選朗讀由 Android 系統控制。

Azure Speech API（自己的 Key）

選擇「Azure Speech API（自己的 Key）」後，設定頁會顯示三個欄位：Azure Speech Key、Azure Region 與精選語音。這是 Microsoft 官方 API，不依賴本機 Python CLI；目前供桌機與 iPhone／iPad 使用。Android 版依產品策略固定切換為系統「隨選朗讀」。

• Key 存於 Obsidian SecretStorage，不會寫入外掛的一般設定資料；仍不可貼到筆記、截圖、Issue 或 Git。
• Key 與 Region 必須來自同一個 Azure Speech 資源，例如 Eastasia。
• Azure 免費額度、是否要求付款方式驗證、超額費用與可用額度依帳戶／地區而異；啟用前請在 Azure 設定 Budget／Cost Alert，勿假設無條件免費。
• 朗讀窗格仍會逐句產生、播放、反白並依序接續下一句；資料夾連播與發音字典同樣適用。

平台支援

平台	支援	說明
macOS	✅	用系統內建中文語音
Windows	✅	需在系統安裝中文語音
iPhone / iPad	✅	用 iOS 內建中文語音
Android	系統朗讀引導	外掛會引導啟用 Android「選取即朗讀」;不提供外掛逐句反白、資料夾連播或 Yunyang

Android 為什麼改用系統朗讀: Obsidian 的 Android WebView 沒有穩定提供本外掛採用的 Web Speech 路徑,桌面 Edge CLI 也無法在 Android 執行。因此 Hans TW TTS 會交由 Android 系統「選取即朗讀」處理。其他外掛若使用雲端服務或額外原生 App,可能採用不同路徑。

Android 建議做法(系統「選取即朗讀」,台灣語音、免費、離線):

1. 裝台灣語音:系統設定搜尋「文字轉語音」→ 偏好引擎選 Google →「安裝語音資料」→「中文(台灣)」。
2. 開啟朗讀:系統設定 →「協助工具 / 無障礙」→「選取即朗讀 / Select to Speak」→ 開啟。
3. 使用:在 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

A Traditional-Chinese-first read-aloud and folder-playback plugin. The default system voice is free and offline; desktop users can switch to the no-key Edge CLI, or use their own Azure Speech Key. It also supports sentence highlighting, cursor start, pronunciation rules, silent symbols, and Callout/Highlightr cleanup. Note text is sent to Microsoft only when an online provider is selected.

0.18.0 highlights

• Resume bookmarks, sentence-level progress and seeking, keyboard controls, and Media Session controls.
• Sentence audio caching for Edge CLI and Azure, cache cleanup, and single-note MP3 export.
• Azure Speech keys are stored in Obsidian SecretStorage rather than regular plugin settings.
• Optional natural reading for math, tables, and mixed Chinese-English content, plus a key-points-only mode.
• Import and export Traditional Chinese reading rules as JSON, with Traditional Chinese and English interfaces.

Features

• Read the current note, selected text, or start from the cursor
• Play every note in a folder back to back, with optional subfolder recursion and automatic next-note playback
• 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
• Use an offline system voice, desktop Edge CLI without an API key, or your own Azure Speech Key
• Chinese-first voice filtering and quality ordering, with speed and pitch controls
• Custom pronunciation rules and silent-symbol filtering across all three providers
• Callout and Highlightr markup cleanup
• Shared Markdown/Obsidian cleanup for block IDs, comments, footnotes, embeds and fenced code, with optional standalone-tag, bare-URL and raw-math reading
• Configurable paragraph and heading pauses shared by system, Edge and Azure playback
• Optional semantic task-state reading and optional skipping of default-collapsed Callout bodies
• Privacy-safe environment diagnostics that exclude note text, credentials, vault names, and full private paths
• Traditional Chinese interface

Installation

A. Community Plugins (recommended): 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 choose from Chinese and English system voices (quality-ranked Chinese voices come first), adjust/reset/preview speed and pitch, set paragraph and heading pauses from 0–1500 ms, optionally read semantic task states, optionally skip default-collapsed Callout bodies, toggle auto-advance to the next note, choose whether folder playback recurses into subfolders, define a pronunciation dictionary (one 原文=唸法 rule per line), and list silent symbols (for example ○ ● ◎ ※) that are removed before speaking. The same timing, pronunciation, symbol and structural-safety rules apply to system, Edge, and Azure providers. The reader pane also has a live speed control (− [1.0x] +).

Platform support

macOS ✅ · Windows ✅ · iPhone/iPad ✅. On Android, the plugin provides setup guidance for the system Select to Speak accessibility service instead of using the plugin reader. This Android handoff does not include sentence highlighting, folder playback, or Edge voices.

License

MIT. Original code; not derived from any AGPL project.