audio2srt-localgen
在本地从零生成并部署 Audio2SRT 项目 —— MLX Whisper 音频转录与翻译 Web GUI 工具。
与 audio2srt-deploy（需要从 Gitee 克隆）不同，本 Skill 将所有源代码模板内嵌，执行时直接在目标目录生成完整项目，无需任何网络访问即可获得源码。
触发条件
以下关键词或意图触发本 Skill：
| 触发词（中文） | 触发词（英文） |
|---|---|
| 本地生成audio2srt | generate Audio2SRT locally |
| 本地搭建转录工具 | create Audio2SRT project |
| 生成音频转录项目 | local deploy mlx whisper |
| 不用克隆部署audio2srt | setup whisper tool without git |
| 从零搭建音频转录 | build whisper GUI from scratch |
区分 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 许可证
生成顺序（按依赖关系）：
- 配置文件：
package.json,tsconfig.json,tsconfig.node.json,vite.config.ts,tailwind.config.js,postcss.config.js,index.html,.gitignore,LICENSE - 后端文件：
server/requirements.txt,server/transcribe_server.py - 前端类型和工具：
src/types/index.ts,src/utils/helpers.ts,src/index.css - 前端组件：
src/store/queueStore.ts,src/components/*.tsx,src/App.tsx,src/main.tsx - 启动脚本：
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。
模型来源
| 模型 | ModelScope ID | 本地路径 |
|---|---|---|
| Whisper 转录 | mlx-community/whisper-large-v3-turbo-4bit |
models/whisper-large-v3-turbo |
| Qwen 翻译 | mlx-community/Qwen2.5-3B-Instruct-4bit |
models/Qwen2.5-3B-Instruct-4bit |
模型总计约 4GB+，首次下载需 5~10 分钟。
服务端口
| 服务 | 端口 | URL |
|---|---|---|
| 前端 (Vite + React) | 3000 | http://localhost:3000 |
| 后端 (Python aiohttp) | 8765 | http://localhost:8765 |
故障排除
模型下载失败
确保 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