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 分钟。

服务端口

故障排除

模型下载失败

确保 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