更新 README.md，新增專案說明、快速開始、使用方式及注意事項；改善 app.py 中的錯誤處理；新增 .gitignore 檔案以排除不必要的檔案

.gitignore

@@ -0,0 +1,22 @@
+# Byte-compiled / cache
+__pycache__/
+**/__pycache__/
+*.py[cod]
+*.pyc
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# OS / editor
+.DS_Store
+*.swp
+*.swo
+
+# Python tooling
+.pytest_cache/
+.mypy_cache/
+
+# Local app artifacts
+data/history.json

README.md

@@ -1,4 +1,3 @@
----
 title: Taiwanese Tts
 emoji: 👁
 colorFrom: gray
@@ -11,3 +10,26 @@ short_description: 台語TTS
 ---
 
 Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+
+## 專案說明
+這是一個台語文字轉語音介面，使用 Gradio 建立。介面會呼叫外部 TTS API（`https://learn-language.tokyo/taigiTTS/taigi-text-to-speech`），將使用者輸入的台語文字轉成語音並播放，同時保留最近 50 筆歷史紀錄（儲存在 `data/history.json`）。在 Hugging Face Spaces 可設定持久儲存以保存歷史。
+
+## 快速開始
+1) 安裝套件：
+```
+pip install -r requirements.txt
+```
+2) 啟動介面：
+```
+python3 app.py
+```
+開啟終端顯示的網址（預設 7860）操作。
+
+## 使用方式
+- 輸入台語文字並選擇模型（目前預設 `model6`），點擊「產生語音」。
+- 轉換後可直接播放音檔；同時會顯示 API 回傳的狀態訊息、白話字（Tailo）與 IPA。
+- 下方歷史區域可重播任一紀錄或重新載入最新紀錄。最多保留 50 筆，超出會自動覆蓋最舊項目。
+
+## 注意事項
+- 介面直接呼叫外部 API，若 API 502/429 等錯誤會在 UI 顯示友善訊息，不會造成程式崩潰。
+- `data/history.json` 為本地紀錄檔，可視需要刪除或加入持久化設定。

app.py

@@ -66,9 +66,19 @@ def _history_table(entries: List[Dict]) -> List[Dict]:
 
 def fetch_tts(text: str, model: str) -> Tuple[str, Dict]:
     payload = {"text": text, "model": model}
-    response = requests.post(API_URL, json=payload, headers=API_HEADERS, timeout=60)
-    response.raise_for_status()
-    data = response.json()
+    try:
+        response = requests.post(API_URL, json=payload, headers=API_HEADERS, timeout=60)
+        response.raise_for_status()
+        data = response.json()
+    except requests.HTTPError as exc:
+        status = exc.response.status_code if exc.response is not None else "N/A"
+        detail = exc.response.text[:300] if exc.response is not None else str(exc)
+        raise gr.Error(f"TTS API 呼叫失敗 (HTTP {status}): {detail}")
+    except requests.RequestException as exc:
+        raise gr.Error(f"TTS API 連線失敗：{exc}")
+    except ValueError:
+        raise gr.Error("TTS API 回傳非 JSON 內容。")
+
     audio_url = data.get("converted_audio_url") or data.get("audio_url")
     if not audio_url:
         raise gr.Error("TTS API 回傳內容缺少音檔網址 (audio_url)。")
@@ -153,7 +163,7 @@ css = """
 }
 """
 
-with gr.Blocks(title="台語 TTS", css=css) as demo:
+with gr.Blocks(title="台語 TTS") as demo:
     gr.Markdown(
         textwrap.dedent(
             """
@@ -235,4 +245,4 @@ with gr.Blocks(title="台語 TTS", css=css) as demo:
     )
 
 if __name__ == "__main__":
-    demo.launch()
+    demo.launch(css=css)