egg/TTS
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
master
TTS/openspec/changes/archive/2025-12-27-add-tts-voiceover-system/design.md
beabigegg 33ea22f259 feat: 新增智慧簡報旁白生成系統 (Smart Slide Voiceover System) 
- 新增 Excel 輸入模組：解析 .xlsx 格式講稿檔案
- 新增 TTS 引擎模組：整合 edge-tts 調用 Azure Neural Voice
- 新增 PyQt6 圖形介面：檔案選擇、語音選擇、進度監控
- 新增執行緒模型：QThread + Asyncio 確保 UI 響應性
- 支援 10 種 Neural Voice (中文/越南/英文)
- 支援中英混雜、越英混雜發音

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2025-12-27 15:42:11 +08:00

3.4 KiB
Raw Permalink Blame History

Context

本專案為桌面端 TTS 工具，需整合 PyQt6 GUI 與 edge-tts 非同步網路請求。主要挑戰在於 PyQt 的 Event Loop 與 asyncio 的衝突處理，以及確保長時間批次任務不阻塞 UI。

目標使用者為企業內部簡報製作人員，技術背景有限，需要簡單直觀的操作流程。

Goals / Non-Goals

Goals:

  • 實現 Excel 到 MP3 的批次轉換
  • 支援中英/越英混合語音
  • 提供響應式 GUI 與進度回饋
  • 錯誤容忍，單檔失敗不中斷

Non-Goals:

  • 不支援即時語音預覽
  • 不實作語音編輯功能
  • 不處理影片嵌入

Decisions

架構模式: MVC + Producer-Consumer

  • 決定: 採用 MVC 分離關注點，Worker Thread 作為 Producer 生成任務結果
  • 原因: PyQt6 原生支援此模式，易於維護與測試

執行緒模型: QThread + Asyncio Event Loop

  • 決定: 在 Worker Thread 內建立獨立的 asyncio loop
  • 替代方案:
    • qasync 整合 - 額外依賴，維護風險
    • 純同步請求 - 效能差，阻塞嚴重
  • 選擇原因: 原生解法，無額外依賴，已驗證穩定

TTS 引擎: edge-tts

  • 決定: 使用 edge-tts Python 套件
  • 原因:
    • 免費調用 Azure Neural Voice
    • 無需 API Key
    • 語音品質達 SOTA 水準

語音選擇策略

  • 決定: 提供下拉選單讓使用者自選語音，每個選項標註雙語支援能力
  • 預設值: 維持原映射作為預設選項
  • 替代方案: 固定映射 - 簡化操作但缺乏彈性
  • 選擇原因: 使用者可能需要男聲或不同風格

可用語音清單 (含雙語支援標註)

語言 Voice ID 性別 雙語支援 說明
zh-TW zh-TW-HsiaoChenNeural 女 中英混雜 ✓ 知性專業 (預設)
zh-TW zh-TW-HsiaoYuNeural 女 中英混雜 ✓ 活潑年輕
zh-TW zh-TW-YunJheNeural 男 中英混雜 ✓ 成熟穩重
zh-CN zh-CN-XiaoxiaoNeural 女 中英混雜 ✓ 甜美親切
zh-CN zh-CN-YunyangNeural 男 中英混雜 ✓ 新聞播報風格
vi-VN vi-VN-HoaiMyNeural 女 越英混雜 ✓ 溫柔清晰 (預設)
vi-VN vi-VN-NamMinhNeural 男 越英混雜 ✓ 專業沉穩
en-US en-US-JennyNeural 女 純英文 標準美式 (預設)
en-US en-US-AriaNeural 女 純英文 自然對話
en-US en-US-GuyNeural 男 純英文 專業旁白

GUI 下拉選單分組

  • 中文語音 (適合中英混雜簡報)
  • 越南語音 (適合越英混雜簡報)
  • 英文語音 (適合純英文簡報)

Rate Limit 策略

  • 決定: 每筆請求間隔 0.5 秒
  • 原因: 防止 IP 被 Azure 封鎖，經測試此間隔穩定

Risks / Trade-offs

網路依賴風險

  • 風險: edge-tts 依賴網路連線，離線無法使用
  • 緩解: 明確標示網路需求，提供網路錯誤提示

API 變動風險

  • 風險: Microsoft 可能調整 Edge TTS API
  • 緩解: edge-tts 套件由社群維護，跟進更新

單執行緒序列化

  • 風險: 大量檔案時處理時間長
  • Trade-off: 選擇穩定性優先，避免並發導致 Rate Limit

Migration Plan

N/A - 全新專案，無既有系統需遷移

Resolved Questions

  • ✅ 是否需要支援自訂語音選擇？→ 是，提供下拉選單並標註雙語支援
  • ✅ 是否需要輸出格式選項？→ 否，固定 MP3 格式