ViGent2/Docs/FRONTEND_README.md

ViGent2 Frontend

ViGent2 的前端界面，采用 Next.js 16 + TailwindCSS 构建。

✨ 核心功能

1. 视频生成 (/)

• 素材管理: 拖拽上传人物视频，实时预览。
• 素材重命名: 支持在列表中直接重命名素材。
• 文案配音: 集成 EdgeTTS，支持多音色选择 (云溪 / 晓晓)。
• AI 标题/标签: 一键生成视频标题与标签 (Day 14)。
• 标题/字幕样式: 样式选择 + 预览 + 字号调节 (Day 16)。
• 背景音乐: 试听 + 音量控制 + 选择持久化 (Day 16)。
• 交互优化: 选择项持久化、列表内定位、刷新回顶部 (Day 16)。
• 预览一致性: 标题/字幕预览按素材分辨率缩放，效果更接近成片 (Day 17)。
• 进度追踪: 实时显示视频生成进度 (10% -> 100%)。
• 作品预览: 生成完成后直接播放下载（作品预览 + 历史作品）。
• 预览优化: 预览视频 metadata 预取，首帧加载更快。
• 本地保存: 文案/标题/偏好由 useHomePersistence 统一持久化，刷新后恢复 (Day 14/17)。
• 历史文案: 手动保存/加载/删除历史文案，独立 localStorage 持久化 (Day 23)。
• 选择持久化: 首页/发布页作品选择均使用稳定 id 持久化，刷新保持用户选择；新视频生成后自动选中最新 (Day 21)。
• AI 多语言翻译: 支持 9 种目标语言翻译文案 + 还原原文 (Day 22)。

2. 全自动发布 (/publish) [Day 7 新增]

• 多平台管理: 统一管理抖音、微信视频号、B站、小红书账号状态。
• 扫码登录:
  • 集成后端 Playwright 生成的 QR Code。
  • 实时检测扫码状态 (Wait/Success)。
  • Cookie 自动保存与状态同步。
• 发布配置: 设置视频标题、标签、简介。
• 作品选择: 卡片列表 + 搜索 + 预览弹窗。
• 选择持久化: 使用稳定 video.id 持久化选择，刷新保持；新视频生成自动选中最新 (Day 21)。
• 预览兼容: 签名 URL / 相对路径均可直接预览。
• 发布方式: 仅支持 "立即发布"。

3. 声音克隆 [Day 13 新增]

• TTS 模式选择: EdgeTTS (预设音色) / 声音克隆 (自定义音色) 切换。
• 参考音频管理: 上传/列表/删除参考音频 (3-20秒 WAV)。
• 一键克隆: 选择参考音频后自动调用 Qwen3-TTS 服务。
• 多语言支持: EdgeTTS 10 语言声音列表，声音克隆 language 透传 (Day 22)。

4. 配音前置 + 时间轴编排 [Day 23 新增]

• 配音独立生成: 先生成配音 → 选中配音 → 再选素材 → 生成视频。
• 配音管理面板: 生成/试听/改名/删除/选中，异步生成 + 进度轮询。
• 时间轴编辑器: wavesurfer.js 音频波形 + 色块可视化素材分配，拖拽分割线调整各段时长。
• 素材截取设置: ClipTrimmer 双手柄 range slider + HTML5 视频预览播放。
• 拖拽排序: 时间轴色块支持 HTML5 Drag & Drop 调换素材顺序。
• 自定义分配: 后端 custom_assignments 支持用户定义的素材分配方案。

5. 字幕与标题 [Day 13 新增]

• 片头标题: 可选输入，限制 15 字，视频开头显示 3 秒淡入淡出标题。
• 标题同步: 首页片头标题修改会同步到发布信息标题。
• 逐字高亮字幕: 卡拉OK效果，默认开启，可关闭。
• 自动对齐: 基于 faster-whisper 生成字级别时间戳。
• 样式预设: 标题/字幕样式选择 + 预览 + 字号调节 (Day 16)。
• 默认样式: 标题 90px 站酷快乐体；字幕 60px 经典黄字 + DingTalkJinBuTi (Day 17)。
• 样式持久化: 标题/字幕样式与字号刷新保留 (Day 17)。

6. 背景音乐 [Day 16 新增]

• 试听预览: 点击试听即选中，音量滑块实时生效。
• 混音控制: 仅影响 BGM，配音保持原音量。

7. 账户设置 [Day 15 新增]

• 手机号登录: 11位中国手机号验证登录。
• 账户下拉菜单: 显示有效期 + 修改密码 + 安全退出。
• 修改密码: 弹窗输入当前密码与新密码，修改后强制重新登录。

8. 文案提取助手 (ScriptExtractionModal) [Day 15 新增]

• 多源提取: 支持文件拖拽上传与 URL 粘贴 (B站/抖音/TikTok)。
• AI 洗稿: 集成 GLM-4.7-Flash，自动改写为口播文案。
• 一键填入: 提取结果直接填充至视频生成输入框。
• 智能交互: 实时进度展示，防误触设计。

🛠️ 技术栈

• 框架: Next.js 16 (App Router)
• 样式: TailwindCSS
• 图标: Lucide React
• 组件: 自定义现代化组件 (Glassmorphism 风格)
• 音频波形: wavesurfer.js (时间轴编辑器)
• API: Axios 实例 @/shared/api/axios (对接后端 FastAPI :8006)

🚀 开发指南

安装依赖

npm install

启动开发服务器

默认运行在 3002 端口 (通过 package.json 配置):

npm run dev
# 访问: http://localhost:3002

目录结构

src/
├── app/                   # 页面入口 (轻量)
│   ├── page.tsx           # 视频生成主页
│   ├── publish/           # 发布管理页
│   │   └── page.tsx
│   └── layout.tsx         # 全局布局 (导航栏)
├── features/
│   ├── home/
│   │   ├── model/          # Home 业务逻辑 (hooks)
│   │   └── ui/             # Home UI 组件
│   └── publish/
│       ├── model/          # Publish 业务逻辑 (hooks)
│       └── ui/             # Publish UI 组件
├── shared/
│   ├── api/                # API 实例
│   ├── hooks/              # 通用 hooks
│   └── lib/                # 工具函数
└── components/             # 跨页面复用 UI

🔌 后端对接

• Base URL: http://localhost:8006 (SSR) / 相对路径 (Client)
• URL 统一工具: @/shared/lib/media 提供 resolveMediaUrl / resolveAssetUrl
• 代理配置: Next.js Rewrites (如需) 或直接 CORS。

🎨 设计规范

• 主色调: 深紫/黑色系 (Dark Mode)
• 交互: 悬停微动画 (Hover Effects)
• 响应式: 适配桌面端大屏操作