Files
xhgit 35c676cf96 chore: 版本升级到 0.1.3
- package.json / package-lock.json 版本号 0.1.2 → 0.1.3
- 界面底部版本号与 README 同步,补充 0.1.3 变更说明
2026-11-14 14:35:31 +08:00

97 lines
8.2 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 轻映 AI · Windows 视频剪辑工作台
轻映 AI(Qingying AI)是一款面向 Windows 的本地优先 AI 辅助视频剪辑工作台,支持本地与云端模型接入、自然语言辅助剪辑、时间轴编辑、GPU 加速导出及成片抽帧检查。
项目围绕“提供素材、描述创意、审核方案、完成剪辑”的流程,将模型辅助分析与可编辑时间轴结合。用户可以检查、修改和撤销 AI 提出的剪辑操作,使用 CPU、GPU 或 CPU+GPU 处理模式完成视频输出。
采用 Electron、React、TypeScript、SQLite 和 FFmpeg 构建。当前为 **0.1.3 开发预览版**:基础媒体导入、工程保存、剪辑与导出流程已可运行,素材理解、通用自动卡点及高级剪辑能力仍在完善。0.1.3 优化了 AI 剪辑助手:模型返回容错与失败自动重试、按评分选材的规划提示词、AI 操作净化层(越界截断、重叠平移)、按参数组接只选已分析素材并轮转保多样性、对话历史压缩注入、未分析素材拦截、视觉测试容错与按素材指纹的分析缓存(跨项目复用,无需重复分析)。完整实现范围和未完成项见 [验收说明](docs/ACCEPTANCE.md)。欢迎提交问题、建议和代码贡献。
## 开源许可
本项目原创代码采用 [GNU GPL v3.0](LICENSE)(`GPL-3.0-only`)。第三方组件保留各自许可证,见 [第三方声明](docs/THIRD_PARTY_NOTICES.md)。模型权重、用户素材、测试用影视视频和导出成片不属于本仓库的许可范围,也不随源码提交。
发布含 FFmpeg 的安装包时,还需提供与所分发二进制对应的源码及构建资料;本仓库中的上游链接和许可证文本不代表该分发工作已经完成。
## 安装和启动
本地构建后的安装程序:`release/Qingying-AI-Setup-0.1.3.exe`(源码仓库不包含安装包)。运行安装器,选择安装位置后启动「轻映 AI」。普通用户不需要 Node.js、Python、Rust 或系统 FFmpeg。也可直接运行 `release/win-unpacked/轻映 AI.exe`。
## 一条实际可用的创作流程
1. 拖入视频、照片和音频,或使用「导入素材」/ 文件夹按钮;导入在后台执行,可在「任务」中取消。
2. 双击素材或拖到对应时间轴。选中素材可技术分析(镜头、时间采样帧;音频为静音/响度分析)。无模型时可用「按参数组接」提出剪辑方案,确认后建立时间轴。
3. 在「模型 → 本地模型」启动已有 Ollama,或下载并安装官方运行时;输入模型标签下载。已有服务不会被擅自停止。下载代理与本地服务请求分别处理,本地请求直连。
4. 「云端与端点」选择 Ollama / OpenAI-Compatible / Anthropic / Gemini 协议,填写 Base URL 和 Model ID。API Key 用 Windows DPAPI 加密。获取模型列表,运行文本及视觉测试,再在「任务分配」选择视觉和规划账户。
5. 选中素材「AI 分析」;分析输出包含真实模型描述、带时间戳的片段和评分理由。当前是场景切分后的多帧分析,不包含光流或专用目标跟踪。自然语言搜索框右侧 ✧ 根据分析结果检索片段。
6. 在剪辑助手输入创意,选择风格和目标秒数。AI 读取素材摘要与当前时间轴,返回操作;审核后点击「应用到时间轴」。方案若已过时会被拒绝,修改可撤销。
7. 拖动片段或两侧边缘;在「属性」修改源入出点、时间轴位置、速度、音量、倒放、留边/裁切、调色和缩放/平移关键帧。可添加字幕并改字、颜色、字号。
8. 点击「生成合成预览」查看多轨音频、效果和倒放的最终结果,再「导出视频」。支持 MP4 / MOV / MKV / WebM;处理引擎可选 CPU / GPU / CPU+GPU;GPU 模式使用硬件解码与编码,不静默回退;CPU+GPU 模式允许最终编码失败回退。
9. 保存 `.qycut` 工程。项目保存素材引用、分析、时间轴、对话和撤销记录;命名项目自动写入工程,并保留 `.bak` 上一版本。未命名项目启动时恢复最近自动恢复文件。素材丢失可重新定位;设置中可复制整理素材以便迁移。
## 快捷键
| 按键 | 操作 |
| --- | --- |
| Ctrl+S | 保存工程 |
| Ctrl+Z / Ctrl+Shift+Z | 撤销 / 重做 |
| S | 在播放头分割选中片段 |
| Delete | 删除片段 |
| Ctrl+C / Ctrl+V | 复制片段 / 在播放头粘贴 |
| Space | 播放 / 暂停 |
| Ctrl+Enter | 提交 AI 规划 |
视频轨道当前为顺序单画面,允许空隙,拒绝重叠。音频片段可混合;字幕独立。关键帧目前仅缩放/平移,效果通过合成预览确认。源片段预览不是完整多轨实时合成。
## 云端协议和隐私
本版实现四个适配器,不把 AWS SigV4、Vertex OAuth、Azure 专有认证等当作通用 OpenAI 请求。其他提供 OpenAI 兼容协议的服务可填自定义端点,能力须实测。本版尚未实测任何付费云端账户。
远程请求默认禁止。允许文字授权后,规划发送指令、素材名称、分析摘要与时间轴;允许帧授权后,视觉分析发送抽取 JPEG。原始视频不上传。无隐式云端回退。自定义远程端点要求 HTTPS;本机 localhost 支持 HTTP。局域网 HTTP 端点尚不支持。
本地模型首次下载需要网络。Ollama 独立服务可能有自己的远程模型功能,使用时应选择实际本地模型标签。请求日志保留最近 200 条元数据,不含请求正文与密钥;费用以服务商账单为准。GPU 选项控制视频引擎,Ollama 推理由运行时管理;本机实测视觉模型全部加载到 RTX 5080 显存。
## 开发、测试与打包
开发环境:Windows x64,Node.js 24 LTS,npm 11。无需 Python。推荐先启用 Clash 系统代理或配置 HTTPS_PROXY 解决开发依赖的 GitHub 下载连接问题。
```powershell
npm ci
npm run build
npm start
npm test
npm run test:desktop
npm run test:batch
npm run test:ai
npm run dist
```
`test:desktop` 启动真实 Electron,自动选择测试素材进行导入、编辑、保存、预览、导出。须先运行 `npm test` 生成其输入。`test:batch` 生成 30 个合成视频并真实渲染 45 秒视频;不是 30 个现实场景的语义验收。`test:ai` 需要已运行的 Ollama 以及实际本地视觉模型,具体见验收报告。
单独调试 UI:终端一 `npm run dev`;终端二设置 `$env:QY_DEV_URL='1'` 后 `npx electron .`。不要用普通浏览器代替桌面启动,浏览器无桌面 IPC。
镜像仅为开发依赖下载选项,源码及二进制许可证见 [第三方组件](docs/THIRD_PARTY_NOTICES.md)。开发环境下载失败可设置:
```powershell
$env:HTTPS_PROXY='http://127.0.0.1:7890'
$env:HTTP_PROXY='http://127.0.0.1:7890'
$env:NO_PROXY='127.0.0.1,localhost'
# 可选,在官方 GitHub 路线不可用时:
$env:ELECTRON_MIRROR='https://npmmirror.com/mirrors/electron/'
$env:FFMPEG_BINARIES_URL='https://cdn.npmmirror.com/binaries/ffmpeg-static'
npm ci
```
打包文件全部使用应用资源或用户数据目录;不会依赖开发机器上的绝对路径。数据库和缓存保存在 Electron userData(默认 `%APPDATA%/qingying-ai-cut`)。测试通过 `QY_TEST_USERDATA` 使用隔离目录。`--smoke-test` 用于自动冒烟检查并退出。
模块边界见 [ARCHITECTURE.md](docs/ARCHITECTURE.md)。Windows 干净机器、Windows 10、高 DPI 多屏以及无 GPU 的最终验收尚需独立环境执行。
## 导出抽帧复核
导出完成后进入「任务 → 查看抽帧」。每行对应一个时间轴片段,依次是成片的起帧、中帧、尾帧;相邻行的尾/起帧可核对切点。旁边的 `.frames-*` 文件夹保存检查页、单帧和源时间映射 JSON。工具仅提供真实抽帧证据,不自动保证模型描述和剧情正确。
本次测试最终使用 `output/无职转生_30秒_修订版/` 的视频。初版已因错误选片和一帧偏移撤回,详见 `docs/FRAME_REVIEW.md`。
## 测试素材
基础集成测试使用 FFmpeg 生成的合成素材,不需要影视文件。测试中 GPU 专项及桌面导出验收使用 NVIDIA 硬件;运行完整测试套件需要可用的 NVENC/CUDA 驱动。`scripts/*user*` 等人工剪辑复现脚本依赖未公开的本地测试素材,不能直接作为通用自动剪辑入口。