- package.json / package-lock.json 版本号 0.1.2 → 0.1.3 - 界面底部版本号与 README 同步,补充 0.1.3 变更说明
97 lines
8.2 KiB
Markdown
97 lines
8.2 KiB
Markdown
# 轻映 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*` 等人工剪辑复现脚本依赖未公开的本地测试素材,不能直接作为通用自动剪辑入口。
|