# tts-engine Specification

## Purpose
TBD - created by archiving change add-tts-voiceover-system. Update Purpose after archive.
## Requirements
### Requirement: Voice Synthesis
系統 SHALL 使用 edge-tts 引擎將文字轉換為語音檔案 (MP3 格式)。

#### Scenario: Successful voice generation
- **WHEN** 提供有效的文字內容與語言設定
- **THEN** 系統生成對應的 MP3 音檔

#### Scenario: Network error handling
- **WHEN** 網路連線中斷或逾時
- **THEN** 系統重試一次，若仍失敗則記錄錯誤並跳過

### Requirement: Voice Selection Support
系統 SHALL 支援使用者從 GUI 選擇的語音進行合成，並提供基於 Lang 欄位的預設映射。

#### Scenario: User selected voice
- **WHEN** 使用者從 GUI 選擇特定語音
- **THEN** 系統使用該語音合成所有講稿

#### Scenario: Default voice by Lang column
- **WHEN** 使用者未選擇語音且 Excel Lang 欄位為 "zh" 或 "zh-tw"
- **THEN** 系統使用 zh-TW-HsiaoChenNeural 語音

#### Scenario: Vietnamese default voice
- **WHEN** 使用者未選擇語音且 Excel Lang 欄位為 "vi"
- **THEN** 系統使用 vi-VN-HoaiMyNeural 語音

#### Scenario: English default voice
- **WHEN** 使用者未選擇語音且 Excel Lang 欄位為 "en"
- **THEN** 系統使用 en-US-JennyNeural 語音

#### Scenario: Unknown language fallback
- **WHEN** 使用者未選擇語音且 Lang 欄位為未知值或空白
- **THEN** 系統預設使用 zh-TW-HsiaoChenNeural 語音

### Requirement: Rate Limit Protection
系統 SHALL 在每次 TTS 請求之間加入延遲，防止 IP 被封鎖。

#### Scenario: Request throttling
- **WHEN** 連續發送多筆 TTS 請求
- **THEN** 系統在每筆請求間等待至少 0.5 秒

### Requirement: Batch Processing
系統 SHALL 支援批次處理多筆講稿，單筆失敗不中斷整體流程。

#### Scenario: Batch with failures
- **WHEN** 批次中有部分檔案生成失敗
- **THEN** 系統記錄失敗項目並繼續處理剩餘檔案

#### Scenario: All files successful
- **WHEN** 批次中所有檔案皆生成成功
- **THEN** 系統顯示完成通知並統計成功數量

### Requirement: Output File Management
系統 SHALL 將生成的音檔儲存至指定輸出路徑。

#### Scenario: Output directory creation
- **WHEN** 輸出路徑不存在
- **THEN** 系統自動建立該目錄

#### Scenario: File naming
- **WHEN** 生成音檔時
- **THEN** 檔名使用 Excel 中 Filename 欄位值加上 .mp3 副檔名

#### Scenario: File overwrite
- **WHEN** 輸出路徑已存在同名檔案
- **THEN** 系統覆蓋既有檔案