TAS — 文字與語音雙向處理 (Speakee API) 是做什麼的？

一個腳本搞定雙向處理：

文字 → 語音 (TTS)： 40+ 種語言、100+ 種語音、自訂語音 UID、長文字自動分段、多講者對話模式、ffmpeg 拼接、音訊品質檢查。
音訊 → 文字 (STT)： 將任何音訊/影片檔案轉錄為文字、逐字時間戳記，以及 SRT/WebVTT 字幕，自動對長錄音進行分段。

所有功能均由捆綁腳本完成 — 請勿重複實作且請勿安裝任何套件（無 Whisper、無 torch、無 faster-whisper、無 pip）：

<skill base dir>/scripts/tas.py

常見安裝位置： ~/.config/opencode/skills/tas/scripts/tas.py (opencode)、 ~/.claude/skills/tas/scripts/tas.py (Claude Code)，以及 ~/.agents/skills/tas/scripts/tas.py (使用 skills CLI，npx skills add)。此技能名稱為 tas — 使用名稱 tas 載入它，切勿使用 tts。

不可協商的規則（適用於每個請求）

使用捆綁腳本。 不要自行編寫 curl/python 程式碼片段來做 TTS 或 STT。
絕對不要安裝任何套件。 不要執行 pip install faster-whisper、pip install whisper、pip install torch，或下載任何模型。此腳本完全透過 Speakee API 搭配 Python 標準函式庫進行 STT — 無需本地模型、無需本地下載、無需 pip。
傳遞前務必驗證。 tts 和 conversation 會自動執行音訊 QA；QA: FAIL 必須修正，不可直接交付。
回報結果：最終路徑、時長、大小和 QA 狀態（TTS）；最終 SRT/VTT/文字路徑和字幕數量（STT）。
始終進行預檢查。 語言、模型和語音在發送任何請求前都會驗證；切勿使用猜測的語音。
保持快取開啟，除非使用者要求關閉。這可以讓重複執行變快，並能恢復失敗的對話。
切勿猜測語音名稱。 使用 voices / suggest 解析，或直接傳遞 UUID。
尊重免費 API：預設 --workers 4；遇到 HTTP 429 時降低並行數。
讓腳本自行正規化文字。 預設會移除 Markdown、網址、HTML 和表情符號；僅在使用者想要字面文字時使用 --raw。
切勿預先分割長文字。 腳本會以句子邊界自動分段和合併。
STT 時只要有已知語言就務必傳入 -l <code>。自動偵測不可靠（Whisper 會混淆孟加拉語/古吉拉特語）；正確的孟加拉語需要 -l bn。
當其他工具或腳本需要解析結果時，請使用 --json。

命令

命令	用途
`tts`	合成一段文字 (TTS)
`uid`	使用自訂語音 UID 進行合成 (`language=uid`)
`conversation`	多講者對話 → 一個拼接並驗證過的 MP3
`stt`	轉錄音訊/影片檔案 → 文字（可選 SRT/VTT）
`transcribe`	`stt` 的別名
`subtitle`	轉錄並生成 SRT 字幕
`verify`	對任何檔案執行音訊 QA
`voices -l <code>`	列出某語言的可用語音
`suggest -l <code>`	列出語音並標示推薦
`presets`	列出內建語音預設集
`languages`	列出支援的語言
`models`	列出模型（預設 `sonic-3.5`）
`cache-clear`	清除合成快取

工作流程 A — 文字轉語音 (TTS)

步驟 1 — 範圍界定

確定：語言（或讓自動偵測工作）、語氣（新聞 / 故事 / 助理 / 有聲書）、單一講者或對話、期望的輸出路徑，以及是否需要字幕（--srt）或中繼資料（--title/--artist）。

步驟 2 — 選擇語言和語音

python3 "$S" languages                 # 43 種語言代碼
python3 "$S" suggest -l bn             # 優先顯示推薦語音
python3 "$S" presets                   # 精選語音集

如果使用者有自訂語音 UID，請使用 uid 模式。否則優先選擇預設集或推薦語音。

步驟 3 — 合成

單一講者：

python3 "$S" tts "您的文字" -l bn -o out.mp3
python3 "$S" tts --text-file article.md -l en --preset news -o article.mp3

對話：

python3 "$S" conversation dialog.txt -l bn \
  --map "人=Nayem,AI=Pooja - Everyday Assistant" \
  --loudnorm --srt dialog.srt -o dialog.mp3

對於耗時或昂貴的執行，請先使用 --dry-run。

步驟 4 — 驗證

QA 會自動執行。要重新檢查任何檔案：

python3 "$S" verify out.mp3

檢查項目：解碼、時長、整合音量 (ebur128)、真實峰值/削波、以及開頭/結尾/內部靜音。退出碼 5 表示失敗。

步驟 5 — 交付

回報範例：

out.mp3 — 2.8s, 0.04 MB, QA PASS (-18.9 LUFS, peak -4.2 dBFS)

除非被要求，否則不要貼出原始 JSON。

步驟 6 — 重複使用

重複執行會命中快取 (~/.cache/speakee-tas)。使用 --force 重新生成，使用 cache-clear 清除。

工作流程 B — 語音轉文字 (STT)

當使用者有音訊或影片檔案並想要逐字稿、字幕或 SRT 時使用。請勿安裝 Whisper — 捆綁腳本會直接呼叫 Speakee /api/stt 端點。

步驟 1 — 確認檔案

python3 "$S" verify /path/to/audio.mp3   # 可選：確認其可解碼
ls -la /path/to/audio.mp3

步驟 2 — 選擇語言

# 自動偵測（不可靠 — Whisper 會混淆孟加拉語/古吉拉特語）：
python3 "$S" stt audio.mp3

# 已知語言時，請務必優先使用明確指定：
python3 "$S" stt audio.mp3 -l bn

重要： 傳入 -l <code> 以指定正確的書寫系統。孟加拉語請使用 -l bn；對孟加拉語音訊，自動偵測會回傳古吉拉特語。低置信度 (< 0.5) 的警告表示偵測到的語言可能錯誤。

步驟 3 — 轉錄 + 生成字幕

# 在輸入檔案旁生成 SRT + VTT，並儲存逐字稿：
python3 "$S" stt audio.mp3 -l bn \
  --srt --srt-path audio.srt --vtt --vtt-path audio.vtt \
  -o audio.txt

# 簡寫：僅生成 SRT（subtitle 命令）：
python3 "$S" subtitle audio.mp3 -l bn -o audio.srt

# 機器可讀 JSON（供其他工具使用）：
python3 "$S" stt audio.mp3 -l bn --json -o result.json

# 長錄音：自動分段約 120 秒；強制較小分段或一次上傳：
python3 "$S" stt audio.mp3 -l bn --chunk-seconds 60
python3 "$S" stt audio.mp3 -l bn --no-chunk     # 僅適用於小於 ~3.5 MB 的檔案

步驟 4 — 交付

回報範例：

audio.srt — 111 個字幕 (8.05 分鐘, 孟加拉語)
audio.txt — 逐字稿已儲存

STT 標記：--srt, --srt-path, --vtt, --vtt-path, --no-word-timestamps (更快，時間戳為估計值), --chunk-seconds, --no-chunk, --workers, --max-chars, --max-line-seconds。

對話模式 (TTS)

腳本格式，每行一個回合：

表演開始。                <- 無 "講者：" 前綴 -> 旁白語音
人：兄弟，2+2 等於多少？
AI：已收到您的提問。

講者標籤是 : 前的簡短符記（≤16 個字元，無空格）。
沒有 講者： 前綴的行由旁白/評論者使用。旁白透過特殊鍵 narrator 對映，因此第三個獨立語音是 --map "narrator=VoiceC,人=VoiceA,AI=VoiceB"。
--map "speaker=voice" 接受語音名稱（模糊）或 UUID。
如果沒有 --map，會自動分配不同的語音。
語音必須不同。 如果兩個講者解析到同一個語音，腳本會印出 WARNING；請將每個講者對映到不同的語音。始終為 AI 和人類分配不同的語音（如果存在評論者/旁白行，則為旁白分配第三個語音）。
--silence 0.35 回合之間的間隔；--loudnorm 將音量正規化至 −16 LUFS。
--manifest FILE 記錄每個片段；--srt FILE 寫入字幕。
--no-stitch 保留獨立片段檔案而不是一個 MP3。
--workers 控制並行請求（預設 4）。

常用選項

標記	預設值	說明
`-l, --language`	自動偵測	ISO 代碼或 `uid`
`-m, --model`	`sonic-3.5`	`sonic-3.5` / `sonic-3` / `sonic-turbo` / `sonic-2`
`-v, --voice_id`	預設	語音名稱或 UUID
`-o, --out`	自動	輸出檔案/目錄 (`--no-stitch`)
`-s, --speed`	`1.2`	0.5–2.0
`--preset`	—	`news`, `story`, `assistant`, `audiobook`
`--chunk-limit`	`1200`	每次請求的字元數
`--retries`	`4`	指數退避重試次數
`--workers`	`4`	並行請求數
`--no-cache` / `--force`	關閉	繞過快取 / 重新生成
`--no-verify`	關閉	跳過自動 QA（不建議）
`--dry-run`	關閉	印出計劃，不發送請求
`--json`	關閉	機器可讀輸出

STT 選項

標記	預設值	說明
`-l, --language`	`auto`	ISO 代碼（孟加拉語使用 `bn`）
`--chunk-seconds`	`120`	每次上傳的音訊秒數
`--no-chunk`	關閉	一次請求（最大 ~3.5 MB）
`--workers`	`2`	並行上傳數
`--srt` / `--srt-path`	關閉	寫入 SRT
`--vtt` / `--vtt-path`	關閉	寫入 WebVTT
`--no-word-timestamps`	關閉	更快；字幕時間為估計值
`--max-chars`	`42`	每則字幕的最大字元數
`--max-line-seconds`	`6.0`	每則字幕的最大秒數
`--timeout` / `--retries`	`300` / `3`	每請求超時 / 重試次數

快取與安全性

片段會根據內容雜湊值快取在 ~/.cache/speakee-tas；重複執行和重試會自動繼續。
暫存拼接檔案始終會被移除；--no-cache 的暫存目錄在退出時清理。
回應會經過驗證（Content-Type: audio/* + MP3 標頭），因此錯誤 JSON 永遠不會被儲存為音訊。
HTTP 429 會遵循 Retry-After；5xx/逾時會以指數退避重試；永久性 4xx 會立即失敗並顯示伺服器訊息。
STT 完全在 Python 標準函式庫中進行處理 — 無需網路安裝、無需模型下載、無需 pip。
退出碼：0 成功，1 錯誤，2 使用方式，3 驗證，4 網路/API，5 音訊 QA 失敗。

參考檔案

references/api.md — 端點、負載、驗證、重試、快取。
references/voices.md — 語言/語音目錄、UID 模式、預設集。
references/troubleshooting.md — 症狀、修正、常見失敗模式。
assets/presets.json — 精選語音預設集（可編輯以加入自己的設定）。

TAS — 文字與語音雙向處理 (Speakee API)