本地优先的 AI 短视频广告生成器 —— 一个素材文件夹 + 一句中文需求，自动产出带配音、逐句字幕、竖屏 9:16 的成品带货短视频，支持一次批量生成多条创意变体。
适用于任意带货 / 种草 / 测评类短视频生成。100% 本地运行：素材、数据库、渲染产物全部留在本机，不上传云端。
- 🗂️ 素材导入与分析 — 拖拽 / 文件夹导入 6 种视频格式；自动探测元数据、自适应抽帧、生成 3×2 接触表缩略图、规则引擎打叙事角色标签
- ✍️ AI 文案 — MiniMax 大模型按一句自然语言需求撰写"钩子—正文—CTA"口播文案，含防泄漏校验与双次重试
- 🔊 AI 配音 — 62 个中文音色（普通话 / 粤语），语速音调可调，TTS 同时产出 MP3 与逐句毫秒级时间戳（SRT）
- 🎬 AI 镜头规划 — 大模型逐句推荐镜头 + 确定性引擎计算入点，每个镜头附推荐理由
- 🎞️ AI 动态剪辑 — 5 种剪辑策略预设；LLM 在"只许改创意、不许动旁白与素材"的围栏内生成剪辑计划，硬校验器防注入防越权，渲染前人工确认
- 📤 渲染与质检 — FFmpeg 归一化 → HyperFrames HTML 时间线渲染（lint / validate / inspect / render 四道工序）→ ffprobe 流校验 + 帧快照质检 → 应用内播放
- 🔍 全链路可观测 — 管线日志实时流式进 UI；每次 AI 调用写 JSONL 审计日志；每次渲染落盘校验与渲染报告
┌─────────────────────────── Electron 42（contextIsolation + preload IPC）──────────────────────────┐
│ 渲染层 React 19 + TS strict + Tailwind 4 + Radix UI │
│ 素材页 ｜ 混剪方案页 ｜ 动态剪辑页 ｜ 设置页（工具链体检） │
│ ▲ IPC 契约（window.studio，22 个方法） │
│ 主进程 20 个领域服务（分层：分析 / 规划 / 生成 / 渲染 / 持久化 / 诊断） │
│ SQLite（node:sqlite · WAL · 12+ 表 · 自动迁移） 每项目独立工作区 │
└──────────────────────────────────────────────────────────────────────────────────────────────────┘
│ │ │ │
FFmpeg/ffprobe MiniMax CLI HyperFrames 子进程编排
探测/抽帧/归一化 LLM 文案+镜头+导演 HTML 时间线渲染 日志流式回传
TTS(MP3+SRT) (GSAP · 1080×1920)
生成管线（四阶段）：素材分析 → 混剪方案（文案 → TTS → 镜头规划）→ AI 动态剪辑（safeTimeline + 受约束 RenderPlan + 硬校验）→ 渲染质检
混合 AI 架构：LLM 提议（创意）→ 确定性引擎裁决（时间轴安全）→ 硬校验器兜底（白名单 / 注入拒绝 / 越权检测）→ 人工确认门（渲染前勾选清单）
| 依赖 | 说明 |
|---|---|
| Node.js ≥ 22 | 含原生 node:sqlite 模块 |
| FFmpeg / ffprobe | 加入 PATH（素材探测、抽帧、归一化、质检） |
MiniMax CLI（mmx） |
并配置环境变量 MINIMAX_API_KEY（LLM 文案与 TTS 配音） |
| npx | 随 Node 提供，首次渲染会自动拉取 hyperframes 渲染器 |
密钥只通过环境变量配置，不要写入任何文件。Windows 下设置方式：
# 永久写入用户环境变量（配置后重开终端/应用生效）
setx MINIMAX_API_KEY "<你的key>"
# 或仅当前会话临时生效
$env:MINIMAX_API_KEY = "<你的key>"应用内「设置 → 工具链体检」会检测该环境变量是否就绪。
cd ai-video-ad-studio
npm install
# 桌面应用（推荐入口）
npm run dev准备一个装有几条商品视频的文件夹，然后：
# 单条生成：指定素材目录、需求描述、音色、输出目录
npm run generate -- --input "C:\path\to\你的素材" --prompt "用这批素材做一条带货短视频，突出卖点，女声配音" --out "C:\path\to\输出目录"
# 批量生成
npm run generate:batch -- --input "C:\path\to\你的素材" --prompt "..." --out "..."
# 仅做素材分析（探测元数据 + 抽帧 + 打标，不生成视频）
npm run analyze -- --input "C:\path\to\你的素材" --output "..."输出目录中会包含成片 final.mp4、逐句时间戳、镜头计划与渲染报告。
| 命令 | 作用 |
|---|---|
npm run dev |
启动 Electron 桌面应用 |
npm run generate |
CLI 单条生成（--input/--prompt/--voice/--out） |
npm run generate:batch |
CLI 批量生成 |
npm run analyze |
CLI 素材分析 |
npm run test |
单测 + 媒体测试 + 组件测试 |
npm run test:electron-ui |
Playwright E2E：界面批量生成并用 ffprobe 校验成片（需完整环境） |
npm run check:syntax |
TypeScript 类型检查 |
ai-video-ad-studio/
├── src/
│ ├── main/ # Electron 主进程（IPC、子进程编排、工具链体检）
│ ├── preload/ # IPC 桥（contextIsolation）
│ ├── renderer/ # React 界面（4 个页面 + 组件 + hooks）
│ ├── services/ # 20 个领域服务（生成/渲染/分析/诊断…）
│ ├── core/ # SQLite 数据库与项目工作区
│ ├── cli/ # 命令行管线（generate / generate:batch / analyze）
│ └── shared/ # 领域模型与 IPC 契约
└── tests/ # 单测 + 媒体测试 + 组件测试 + Electron E2E
- 素材打标当前为规则引擎 + 媒体元数据；视觉大模型理解与 Whisper 语音转写为规划项
- 仅在 Windows 环境验证；需从源码运行（无安装包）
- 单批最多 5 条方案，每方案的多版本动态剪辑需逐条确认渲染
- 目标平台（抖音/快手/小红书/视频号）差异目前体现为时长、画幅、CTA 等参数预设
本项目未附带开源许可证，保留所有权利。未经授权请勿复制或二次分发。