AI Video Ad Studio

本地优先的 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

CLI：用你自己的素材生成第一条视频

准备一个装有几条商品视频的文件夹，然后：

# 单条生成：指定素材目录、需求描述、音色、输出目录
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 等参数预设

Kaleidoscope-XinFang/ai-video-ad-studio

Star growth

README