雅婷逐字稿管理系統

整合雅婷逐字稿 API 的檔案上傳與語音辨識管理系統，提供簡單易用的 Web 介面。

功能特色

• 檔案上傳管理：支援拖放上傳音檔到雅婷 API，自動記錄過期時間
• 辨識任務管理：配置辨識參數（模型、說話者數量、情緒分析）並執行語音辨識
• 即時狀態監控：自動輪詢辨識狀態，即時顯示進度
• 結果下載：支援純文字 (TXT) 和試算表 (CSV) 格式下載
• 詳細結果檢視：查看完整逐字稿，包含時間戳記、說話者、信心分數

技術架構

• 後端：FastAPI + SQLAlchemy + SQLite
• 前端：Vue.js 3 + Axios
• API：雅婷逐字稿 API

專案結構

stt_project/
├── backend/
│   ├── main.py              # FastAPI 主程式
│   ├── models.py            # SQLAlchemy 資料模型
│   ├── database.py          # 資料庫設定
│   ├── schemas.py           # Pydantic 資料驗證
│   ├── yating_client.py     # 雅婷 API 客戶端
│   └── requirements.txt     # Python 套件依賴
├── frontend/
│   ├── index.html           # Vue.js 前端頁面
│   ├── app.js               # Vue 應用程式邏輯
│   └── styles.css           # 樣式檔案
├── .env                     # 環境變數（需自行建立）
├── .env.example             # 環境變數範本
├── database.db              # SQLite 資料庫（自動產生）
└── README.md                # 說明文件

安裝步驟

1. 前置需求

• Python 3.8 或以上版本
• pip 套件管理工具
• 雅婷逐字稿 API Key（請至 雅婷開發者平台 申請）

2. 安裝依賴套件

cd backend
pip install -r requirements.txt

3. 設定環境變數

複製 .env.example 並重新命名為 .env：

cp .env.example .env

編輯 .env 檔案，填入您的雅婷 API Key：

YATING_API_KEY=your_actual_api_key_here

4. 啟動應用程式

在 backend 目錄下執行：

python main.py

或使用 uvicorn：

uvicorn main:app --host 0.0.0.0 --port 8000 --reload

5. 開啟瀏覽器

開啟瀏覽器並前往：

http://localhost:8000

使用說明

1. 上傳音檔

• 點擊「選擇檔案」按鈕或將音檔拖放到上傳區域
• 支援格式：MP3, WAV, MOV, MP4
• 上傳成功後，檔案會出現在「已上傳檔案」列表中
• 注意：所有檔案會在 24 小時後自動過期

2. 開始辨識

1. 在「已上傳檔案」列表中，點擊「開始辨識」按鈕
2. 設定辨識參數：
   • 辨識模型：選擇「中英文標準模型」或「中台語標準模型」
   • 說話者數量：選擇自動偵測或指定說話者人數 (1-10)
   • 情緒分析：勾選以啟用情緒分析功能
3. 點擊「開始辨識」提交任務

3. 監控狀態

• 辨識任務會自動出現在「辨識任務」列表中
• 系統每 5 秒自動更新任務狀態
• 狀態說明：
  • 等待中：任務已排隊，等待處理
  • 處理中：正在辨識中
  • 已完成：辨識完成，可下載結果
  • 錯誤：辨識失敗
  • 已過期：結果已過期（24 小時後）

4. 下載結果

辨識完成後，可以：

• 點擊「TXT」按鈕下載純文字逐字稿
• 點擊「CSV」按鈕下載試算表格式（包含時間戳記、說話者、信心分數等）
• 點擊「查看」按鈕在網頁上查看完整詳情

API 端點說明

檔案管理

• POST /api/upload - 上傳音檔
• GET /api/files - 列出所有已上傳檔案
• DELETE /api/files/{file_id} - 刪除檔案記錄

辨識任務

• POST /api/transcribe - 開始辨識任務
• GET /api/transcriptions - 列出所有辨識任務
• GET /api/transcriptions/{uid} - 取得特定任務詳情

結果下載

• GET /api/download/{uid}/txt - 下載純文字格式
• GET /api/download/{uid}/csv - 下載 CSV 格式

其他

• GET / - 根路徑（前端頁面）
• GET /health - 健康檢查

重要限制

根據雅婷逐字稿 API 的限制：

• 檔案過期時間：所有上傳的檔案和辨識結果會在 24 小時後過期
• 最大音檔長度：2 小時
• 最大並行辨識數：同時最多 3 個辨識任務
• 支援格式：MP3, WAV, MOV, MP4

故障排除

問題：無法啟動應用程式

確認是否已安裝所有依賴套件：

pip install -r requirements.txt

問題：上傳失敗或辨識失敗

檢查 .env 檔案中的 API Key 是否正確：

cat .env

問題：資料庫錯誤

刪除 database.db 檔案並重新啟動應用程式：

rm database.db
python main.py

問題：前端無法連接後端

確認後端服務是否正常運行，檢查終端機輸出是否有錯誤訊息。

開發說明

啟用開發模式

在開發模式下，修改程式碼後會自動重新載入：

uvicorn main:app --reload --host 0.0.0.0 --port 8000

資料庫管理

資料庫結構定義在 backend/models.py。

如需重設資料庫：

1. 刪除 database.db
2. 重新啟動應用程式（會自動建立新資料庫）

API 文件

啟動應用程式後，可以查看自動生成的 API 文件：

• Swagger UI：http://localhost:8000/docs
• ReDoc：http://localhost:8000/redoc

授權資訊

本專案僅供學習和開發使用。使用雅婷逐字稿 API 時，請遵守其服務條款。

相關連結

• 雅婷開發者平台
• 雅婷 API 文件
• FastAPI 官方文件
• Vue.js 官方文件

聯絡資訊

如有問題或建議，歡迎開 Issue 討論。