audio2srt-localgen

在本地從零生成並部署 Audio2SRT 專案 —— MLX Whisper 音訊轉錄與翻譯 Web GUI 工具。

與 audio2srt-deploy（需要從 Gitee 克隆）不同，本 Skill 將所有原始碼模板內嵌，執行時直接在目標目錄生成完整專案，無需任何網路訪問即可獲得原始碼。

觸發條件

以下關鍵詞或意圖觸發本 Skill：

區分 audio2srt-deploy vs audio2srt-localgen：

• 使用者提到"克隆""下載""Gitee" → 使用 audio2srt-deploy
• 使用者提到"本地生成""從零搭建""不用克隆""離線部署" → 使用本 Skill (audio2srt-localgen)
• 使用者只說"部署 audio2srt"且無已有專案 → 預設使用本 Skill（本地生成更可靠）

前置條件

• macOS 14.0+ with Apple Silicon (M1/M2/M3/M4)
• Python 3.10+ 已安裝
• Node.js 18+ 已安裝

執行流程

Step 1: 確認目標目錄

詢問使用者希望將專案生成到哪個目錄。預設值 ~/audio2srt。

如果目錄已存在且非空，詢問是否覆蓋（清空重建）或選擇其他目錄。

重要：不要在使用者的工作目錄或桌面下直接生成，建議使用 ~/audio2srt 或使用者明確指定的路徑。

Step 2: 生成專案檔案

按以下目錄結構，逐個使用 Write 工具生成所有檔案。所有檔案內容均來自本 Skill 的 references 目錄中的模板檔案。

目標目錄結構：

TARGET_DIR/
├── server/
│   ├── transcribe_server.py   # Python 後端（MLX Whisper + mlx-lm）
│   └── requirements.txt       # Python 依賴
├── src/
│   ├── components/
│   │   ├── DropZone.tsx       # 檔案拖拽上傳
│   │   ├── FileCard.tsx       # 任務卡片
│   │   ├── FileList.tsx       # 檔案列表
│   │   ├── Header.tsx         # 頂部欄
│   │   ├── ResultPanel.tsx    # 轉錄結果面板
│   │   ├── SrtTranslatePage.tsx # SRT 翻譯頁面
│   │   ├── StatsBar.tsx       # 統計面板
│   │   └── TranscriptionSettings.tsx # 轉錄引數設定
│   ├── store/
│   │   └── queueStore.ts      # Zustand 狀態管理
│   ├── types/
│   │   └── index.ts           # TypeScript 型別定義
│   ├── utils/
│   │   └── helpers.ts         # 工具函式和 API 客戶端
│   ├── App.tsx                # 應用主元件
│   ├── main.tsx               # 入口檔案
│   └── index.css              # 全域性樣式
├── models/                    # 模型目錄（gitignored，執行時下載）
├── start.sh                   # 一鍵啟動指令碼
├── package.json               # Node.js 依賴
├── index.html                 # HTML 入口
├── vite.config.ts             # Vite 配置
├── tsconfig.json              # TypeScript 配置
├── tsconfig.node.json         # TypeScript Node 配置
├── tailwind.config.js         # Tailwind CSS 配置
├── postcss.config.js          # PostCSS 配置
├── .gitignore                 # Git 忽略規則
└── LICENSE                    # MIT 許可證

生成順序（按依賴關係）：

1. 配置檔案：package.json, tsconfig.json, tsconfig.node.json, vite.config.ts, tailwind.config.js, postcss.config.js, index.html, .gitignore, LICENSE
2. 後端檔案：server/requirements.txt, server/transcribe_server.py
3. 前端型別和工具：src/types/index.ts, src/utils/helpers.ts, src/index.css
4. 前端元件：src/store/queueStore.ts, src/components/*.tsx, src/App.tsx, src/main.tsx
5. 啟動指令碼：start.sh

關鍵要求：

• 讀取 references/ 目錄下的模板檔案，使用 Write 工具逐個寫入目標路徑
• 寫入 start.sh 後必須執行 chmod +x 賦予執行許可權
• 確保 models/ 目錄存在（mkdir -p TARGET_DIR/models）

Step 3: 安裝 Python 依賴

cd TARGET_DIR
pip3 install -r server/requirements.txt

如果 pip 失敗：

• 嘗試 pip3 install --user -r server/requirements.txt
• 或建議使用虛擬環境：python3 -m venv venv && source venv/bin/activate && pip install -r server/requirements.txt

Step 4: 安裝 Node.js 依賴

cd TARGET_DIR
npm install

Step 5: 啟動服務

cd TARGET_DIR
./start.sh

start.sh 自動執行：

• 檢測 models/whisper-large-v3-turbo 和 models/Qwen2.5-3B-Instruct-4bit 是否存在
• 從 ModelScope 下載缺失模型（首次約需 5~10 分鐘，共約 4GB+）
• 啟動 Python 後端（埠 8765）
• 啟動 Vite 前端（埠 3000）

Step 6: 開啟應用

啟動成功後，開啟瀏覽器訪問 http://localhost:3000。

模型來源

模型總計約 4GB+，首次下載需 5~10 分鐘。

服務埠

故障排除

模型下載失敗

7w4.net小蔥技能站，你的AI助手技能庫。

確保 ModelScope CLI 可用：

pip3 install modelscope
python3 -m modelscope.cli.download --model mlx-community/whisper-large-v3-turbo-4bit --local_dir models/whisper-large-v3-turbo
python3 -m modelscope.cli.download --model mlx-community/Qwen2.5-3B-Instruct-4bit --local_dir models/Qwen2.5-3B-Instruct-4bit

埠被佔用

lsof -ti:3000 | xargs kill -9
lsof -ti:8765 | xargs kill -9

M4A/MP3 格式不被識別

工具通過 macOS afconvert 自動轉換。確保 Xcode Command Line Tools 已安裝。

npm install 失敗

刪除 node_modules 和 package-lock.json 後重試：

rm -rf node_modules package-lock.json
npm install

這個 Skill 質量中等偏上，文件編寫清晰詳細，觸發條件區分合理，程式碼結構專業。優點是提供了完整的前後端程式碼和自動化啟動指令碼，故障排除指南實用。不足是部分配置模板檔案缺失，可能影響部署完整性。對於需要本地離線生成 Audio2SRT 專案的使用者來說，這是一個可用但需要手動補充少量檔案的解決方案。