Originals/ViGent2
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 51 Wiki Activity
Files
71b45852bf85ed121c4cb4faee7abe03e50f6308
ViGent2/Docs/FRONTEND_README.md
Kevin Wong 71b45852bf 更新
2026-03-04 17:35:59 +08:00

10 KiB
Raw Blame History

ViGent2 Frontend

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

📌 文档定位

  • 本文档用于说明前端功能、运行方式与目录概览（面向使用与协作）。
  • 开发规范与实现约束请查看 Docs/FRONTEND_DEV.md。
  • 历史变更与里程碑请查看 Docs/DevLogs/ 与 Docs/TASK_COMPLETE.md。

✨ 核心功能

1. 视频生成 (/)

  • 一、文案提取与编辑: 文案输入/提取/翻译/保存；输入框右下角支持一键扩展到大编辑器。
  • 二、配音: 配音方式（EdgeTTS/声音克隆）+ 配音列表（生成/试听/管理）合并为一个板块。
  • 三、素材编辑: 视频素材（上传/选择/管理）+ 时间轴编辑（波形/色块/拖拽排序）合并为一个板块。
  • 四、标题与字幕: 片头标题/副标题/字幕样式配置；短暂显示/常驻显示；样式预览使用视频片头帧作为真实背景。
  • 五、背景音乐: 试听 + 搜索选择 + 选择持久化（无音量滑杆，生成时固定混音系数）。
  • 六、作品（右栏）: 作品列表 + 作品预览合并为一个板块。
  • 进度追踪: 实时显示视频生成进度 (10% -> 100%)。
  • 作品预览: 生成完成后直接播放下载（作品预览 + 历史作品）。
  • 下载直达: 首页作品下载与发布成功弹窗下载统一走同源下载接口（/api/videos/generated/{id}/download），避免新标签页在线播放。
  • 预览优化: 预览视频 metadata 预取，首帧加载更快。
  • 本地保存: 文案/标题/偏好由 useHomePersistence 统一持久化，刷新后恢复。
  • 历史文案: 手动保存/加载/删除历史文案，独立 localStorage 持久化。
  • 选择持久化: 首页/发布页作品选择均使用稳定 id 持久化；新视频生成后优先选中最新，后续用户手动选择持续持久化恢复。
  • 统一下拉交互: 首页/发布页业务选择器统一为 SelectPopover（支持自动上拉、已选定位、移动端 BottomSheet）；ScriptEditor 的“历史文案 / AI多语言”为产品例外，保留原轻量菜单。
  • AI 多语言翻译: 支持 9 种目标语言翻译文案 + 还原原文。

2. 全自动发布 (/publish)

  • 多平台管理: 统一管理抖音、微信视频号、B站、小红书账号状态。
  • 扫码登录:
    • 集成后端 Playwright 生成的 QR Code。
    • 实时检测扫码状态 (Wait/Success)。
    • Cookie 自动保存与状态同步。
  • 发布配置: 设置视频标题、标签、简介。
  • 作品选择: SelectPopover 下拉 + 搜索 + 预览弹窗（下拉内可连续预览，不强制收起）。
  • 选择持久化: 使用稳定 video.id 持久化选择，刷新保持；新视频生成自动选中最新。
  • 预览兼容: 签名 URL / 相对路径均可直接预览。
  • 发布方式: 仅支持 "立即发布"。
  • 发布成功清理弹窗: 全平台发布成功后触发 CleanupModal（展示成功平台、截图、下载备份、清理按钮），刷新/跳转后可恢复。
  • 清理失败兜底: 清理接口失败时弹窗不关闭且不清本地输入；连续失败达到阈值后可“暂不清理，继续使用”。
  • 清理范围: 仅清理输入内容字段（文案/标题/副标题/发布标题/标签），保留样式、字号、边距、模型等用户偏好。

3. 声音克隆

  • TTS 模式选择: EdgeTTS / 声音克隆切换，音色选择统一下拉（显示音色名 + 语言）。
  • 音色试听: EdgeTTS 音色列表支持一键试听，按音色 locale 自动选择对应语言的固定示例文案。
  • 参考音频管理: 上传/列表/重命名/删除参考音频，上传后自动 Whisper 转写 ref_text + 超 10s 自动截取。
  • 录音入口: 参考音频区域底部右侧提供“上传音频 / 录音”入口；录音采用弹窗流程（录制 -> 试听 -> 使用/弃用）。
  • 录音防误触: 录音中禁用遮罩关闭（避免误触中断）；未录音时可点空白关闭。
  • 重新识别: 旧参考音频可重新转写并截取 (RotateCw 按钮)。
  • 一键克隆: 选择参考音频后自动调用 CosyVoice 3.0 服务。
  • 语速控制: 声音克隆模式下支持 5 档语速 (0.8-1.2)，统一下拉，选择持久化。
  • 语气控制: 声音克隆模式下支持 4 种语气 (正常/欢快/低沉/严肃)，统一下拉，选择持久化。
  • 多语言支持: EdgeTTS 10 语言声音列表，声音克隆 language 透传。

4. 配音前置 + 时间轴编排

  • 配音独立生成: 先生成配音 → 选中配音 → 再选素材 → 生成视频。
  • 配音管理面板: 生成/试听/改名/删除/选中，异步生成 + 进度轮询。
  • 时间轴编辑器: wavesurfer.js 音频波形 + 色块可视化素材分配，拖拽分割线调整各段时长。
  • 素材截取设置: ClipTrimmer 双手柄 range slider + HTML5 视频预览播放。
  • 拖拽排序: 时间轴色块支持 HTML5 Drag & Drop 调换素材顺序。
  • 自定义分配: 后端 custom_assignments 支持用户定义的素材分配方案（含 source_start/source_end 截取区间）。
  • 时间轴语义对齐: 超出音频时仅保留可见段并截齐末段，超出段不参与生成；不足音频时最后可见段自动循环补齐。
  • 画面比例控制: 时间轴顶部支持 9:16 / 16:9 输出比例选择，设置持久化并透传后端。

5. 字幕与标题

  • 片头标题: 可选输入，限制 15 字；支持”短暂显示 / 常驻显示”，默认短暂显示（4 秒）；常驻显示 时主标题与副标题都会全程显示。
  • 片头副标题: 可选输入，限制 20 字；显示在主标题下方，用于补充说明或悬念引导；独立样式配置（字体/字号/颜色/间距），可由 AI 同时生成；与标题共享显示模式设定；仅在视频画面中显示，不参与发布标题。
  • 标题同步: 首页片头标题修改会同步到发布信息标题。
  • 逐字高亮字幕: 卡拉OK效果，默认开启。
  • 自动对齐: 基于 faster-whisper 生成字级别时间戳。
  • 样式预设: 标题/字幕/副标题样式选择 + 预览 + 字号调节。
  • 默认样式: 标题 90px 站酷快乐体；字幕 60px 经典黄字 + DingTalkJinBuTi。
  • 样式持久化: 标题/字幕/副标题样式与字号刷新保留。

6. 背景音乐

  • 试听预览: 下拉列表内可直接试听。
  • 选择体验: 发布页同款搜索选择器，打开时自动定位到当前已选。
  • 混音控制: 当前前端不提供音量滑杆，生成时固定 bgm_volume=0.2，保持配音音量稳定。

7. 账户设置

  • 手机号登录: 11位中国手机号验证登录。
  • 账户下拉菜单: 显示手机号（中间四位脱敏）+ 有效期 + 修改密码 + 安全退出。
  • 修改密码: 弹窗输入当前密码与新密码，修改后强制重新登录。
  • 登录即时生效: 登录成功后 AuthContext 立即写入用户数据，无需刷新即显示手机号。

8. 付费开通会员 (/pay)

  • 支付宝电脑网站支付: 跳转支付宝官方收银台，支持扫码/账号登录/余额等多种支付方式。
  • 自动激活: 支付成功后异步回调自动激活会员（有效期 1 年），前端轮询检测支付结果。
  • 到期续费: 会员到期后登录自动跳转付费页续费，流程与首次开通一致。
  • 管理员激活: 管理员手动激活功能并存，两种方式互不影响。

9. 文案提取助手 (ScriptExtractionModal)

  • 多源提取: 支持文件拖拽上传与 URL 粘贴 (B站/抖音/TikTok)。
  • AI 智能改写: 集成 GLM-4.7-Flash，自动改写为口播文案。
  • 登录鉴权: 依赖后端受保护接口（/api/tools/extract-script），未登录会触发全局 401 跳转登录。
  • 自定义提示词: 可自定义改写提示词，留空使用默认；设置持久化到 localStorage。
  • 一键填入: 提取结果直接填充至视频生成输入框。
  • 智能交互: 实时进度展示，防误触设计。

🛠️ 技术栈

  • 框架: 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
│   ├── pay/               # 付费开通会员页
│   │   └── 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。

🎨 UI 说明（概览）

  • 业务选择器统一使用 SelectPopover（桌面 Popover / 移动端 BottomSheet）；ScriptEditor 的“历史文案 / AI多语言”保留原轻量菜单。
  • 业务弹窗统一使用 AppModal（统一遮罩、头部、关闭行为与滚动策略）。
  • 弹窗关闭策略：默认支持 ESC / X / 点击空白关闭；仅发布成功清理弹窗为强制流程（不允许空白关闭，也不显示 X）。
  • 视频预览弹窗层级高于下拉菜单；下拉内支持连续预览。
  • 页面同时适配桌面端与移动端；长列表统一隐藏滚动条。
  • 详细 UI 规范、持久化规范与交互约束请查看 Docs/FRONTEND_DEV.md。
Reference in New Issue View Git Blame Copy Permalink