# 视频节点交互 ## 导入与放置 - 右侧元素条点击「视频」先打开文件选择器，选中视频后再点击画布放置。取消选择或按 Esc 取消放置不会创建空节点。 - 支持将视频文件拖入画布，落在拖放位置；画布获得焦点后，Ctrl+V 可粘贴剪贴板提供的视频文件，放在当前视口中心。剪贴板必须实际提供文件，仅复制文件路径文字或网页链接不等于复制视频文件。 - 支持 MP4 / WebM / MOV / MKV，单文件上限 48MB（与现有播放器一致），能否解码取决于浏览器的编码支持。上传前读取尺寸、时长和首帧封面，上传使用 1MB 分块。 - 画布须先保存到工作区。文件完整上传后才创建带封面的原视频节点，保持原始宽高比并进入当前图层，可正常撤销。读取/上传失败不创建节点，切换画布或页面时取消导入并清理临时媒体。 验证：`node tools/check-video-import.mjs`，已纳入 `npm test`。 ## 视频复刻：自主设置画质、帧率和范围 导入普通视频后，选中视频，悬停或点击悬浮工具条的「绘制复刻」展开设置。设置范围、帧率、采样尺寸、碎片数量、画风、颜色数及背景选项，再加入绘制队列。前台自动保存当前素材并向宿主提交任务；无需额外确认保存。角落统一显示图片绘制、视频绘制、抽帧与当前画布的视频导出任务。 任务列表默认隐藏，点击右侧工具栏底部的任务按钮展开；面板顶部可再次隐藏，显示偏好保存在本机。按钮上的数字表示进行中的任务数量，隐藏列表不会暂停或取消任务。 - 范围可选完整视频或指定起止秒数，结束时间留空表示到视频结尾。到达源视频末尾时自动截短，输出时长以帧数 / 帧率计，误差不超过一帧。 - 帧率由用户输入任意正数，支持 25、29.97、30、60 fps 等。浏览器不可靠提供源帧率，因此不提供未经验证的「原帧率」选项；高于源帧率可能产生重复画面。 - 采样画质可选长边 480/887/1440px、原始尺寸或自定义长边，小视频不放大。视频复刻不再沿用图片内部 887px 长边封顶；碎片档位仍按采样密度区分画风。 - 移除 30 秒、360 帧和 640px 的固定任务限制，开始前显示预计帧数及采样尺寸。分辨率、帧率和时长越高，计算量、存储占用和导出体积通常越大。单帧处理仍须在 1600 万像素、16384px 长边以内，超出会明确报错。 - 宿主 FFmpeg 顺序抽帧，直接将 RGBA 像素交给常驻 Worker 池，最多 4 帧并行，并根据帧尺寸限制在途内存。无需网页 seek、Canvas、PNG 编码或逐帧上传。仅复用像素完全一致的相邻帧，调色板复用仍经过亮色、色差和周期刷新检查；不启用近似整帧复用。图片和 AI 的逐图/逐帧矢量化计算也使用共享 Worker 池。 - 计算完成后自动将结果加入原画布的原页面。提交时重新读取最新文档，校验稳定页面 ID、来源内容、节点与图层锁定状态；任务 ID 防止重复加入。源被更换、页面被删或文件被其他编辑器修改时保留产物，并显示“等待加入画布”。 - 切换画布、对话、关闭画布标签、刷新或关闭网页不会取消已接收的任务；DSH 宿主进程须继续运行。结果计算不等待网页应用回执，后续任务可继续。统一任务面板支持进行中/需处理/已结束/全部筛选、上下排序、暂停后续任务、逐帧暂停续绘、重试、重新开始、打开原页面、回放图片绘制和单项撤销生成。 - 宿主重启后原任务记录、参数、产物和连续帧检查点仍在工作区 `.drawai-cache/drawing-tasks/`。未完成项标记中断，用户选择继续后验证素材、算法版本和帧摘要；不一致时必须重新开始。每 500ms 或 30 帧写一次检查点，暂停、正常结束和可处理的失败会刷新检查点；进程突然退出可能重算最后未提交的少量帧。 - 生成撤销只删除该任务产生且未被后续编辑的节点；已连接新连线或已编辑的结果会拒绝撤销。后台补丁同步进当前视图及本地撤销历史；未知外部版本冲突保留本地编辑。媒体清理扫描全部页面，并保护任务输入及保留中的输出；移除任务记录不会删除已加入画布的节点。 - 完成后可在预览窗口播放、逐帧检查，并通过悬浮工具条「导出 → 导出 SVG 视频」导出 `.svgvideo.zip`（播放清单、SVG 帧、封面及片段音频来源）；不是单文件动态 SVG。 - 碎片数量支持低/中/高，内部自动匹配每帧 60,000/120,000/248,000 字符预算，单帧文件格式上限 250,000 字符。复用图片的碎片画风，必要时自动简化；完成信息会提示发生细节降低的帧数。不做跨帧颜色或轮廓稳定。 - 队列最多保留 16 个未完成绘制任务，缓存素材总预算 256MiB、单素材 64MiB，单任务最多 100 万帧。取消可保留已提交帧供重试；“重新开始”使用原始素材快照创建新任务。已成功任务释放输入快照；普通已结束历史保留最近 64 项，交付冲突的产物保留至用户处理或移除。清除旧记录不删除已加入画布的节点。 验证：`node tools/check-video-trace.mjs`，已纳入 `npm test`。 ## 播放与导出 - 单击节点选中；点击节点中央播放按钮时也会选中该节点。 - 鼠标悬停视频节点时，中央显示播放或暂停按钮，底部显示进度条（类似常见视频站点）；移出后一并收起。加载中或出错时中央按钮仍常显以便重试。 - 选中原视频后显示「绘制复刻 / 预览 / 抽帧 / 导出」悬浮条，复用其他节点的图标在上、文字在下的布局、尺寸、主题色与悬停底色。SVG 视频显示「预览 / 抽帧 / 导出」，不显示不适用的绘制复刻。 - 绘制和导出复用图片绘制的悬停卡片组件，优先在工具条上方展开，空间不足时调整到视口内。移出后延迟关闭，移入浮窗取消关闭；输入参数时保持打开。点击外部或按 Escape 关闭。切换画布/页面会取消正在进行的视频复刻。 - 「抽帧」把当前画面放到原视频右侧（同尺寸、同图层，可撤销）。未播放时会先加载并停在当前进度。源视频导出当前解码画面的 PNG；SVG 视频直接使用当前帧的 SVG，不再栅格化，避免色块之间出现白缝。选区悬浮条不展示播放、停止、逐帧、进度、循环及适配控件，也不再提供设置封面。节点表面悬停条只负责进度与播放/暂停；完整控制（停止、逐帧、循环、适配、静音）在「预览」窗口操作。 - 图片和视频默认无外框，不提供不适用的描边工具，也不显示文字标签。 - 暂停保留当前位置，再次播放继续；停止回到开头。播放结束后再次播放从头开始。 - SVG 帧序列支持上一帧、下一帧；普通视频禁用逐帧按钮。 - 默认等比适配，可切换裁切填满或拉伸。此设置只影响本次预览。 - 双击节点或点击“放大”打开预览，按 Escape 或点击关闭返回画布，保持播放位置。 - 「导出」菜单按媒体类型筛选：原视频提供导出源视频、MP4 和 GIF；SVG 视频提供导出 SVG 视频包、MP4、WebM 和 GIF。 - MP4 源视频直接导出原文件，保留画质与音频；其他源视频由宿主离线转码。SVG 帧由宿主独立 Worker 使用 resvg 逐张渲染为白底 PNG，再交给 FFmpeg 离线合成；浏览器不再解码、渲染或上传导出帧。按序号处理全部 SVG 帧，以原帧率生成固定间隔时间戳，不依赖页面播放时钟。30fps 的 300 帧输出为 10 秒；处理慢时延长导出耗时，不跳过中间帧。 - MP4 使用 H.264 / AAC、WebM 使用 VP9 / Opus。SVG 视频音频按原片段起点截取，短音频补静音至画面时长。导出采用媒体尺寸，奇数宽高补齐到偶数以适配编码器，不受画布节点缩放影响。 - GIF 导出默认白底、无限循环、无音频。支持原视频及 SVG 复刻视频，保留媒体原始尺寸（奇数宽高也无需补齐）；SVG 结果按复刻范围逐帧输出。先扫描生成统一的最多 256 色调色板，再通过抖动量化编码，避免各帧独立调色板带来的颜色跳变；两遍处理复用磁盘帧，不把整段原始视频缓存在内存中。GIF 延时以 1/100 秒记录，30fps 等帧率由相邻帧的延时取整来近似，不能像 MP4 一样精确记录每个时间戳。SVG 视频导出 GIF 不依赖原片段音频文件。 - 发起请求后，宿主自行完成渲染、编码与保存，无需网页持续轮询或发出结束指令。切换浏览器标签、画布、对话，最小化窗口或刷新网页均不取消导出。回到原画布可通过“后台导出”卡片恢复查看进度；完成文件以 `<画布名>-<媒体ID>-<任务ID>.<格式>` 自动保存到画布文件旁，可另外点击“下载文件”保存到浏览器下载目录。 - 任务记录按会话和画布隔离，最多同时运行 4 个任务，保留至多 16 条完成/失败历史。运行项可取消，完成项可移除记录；移除记录不删除已导出的文件。渲染与编码成功、失败或取消后清理临时 PNG 和源视频副本。宿主和插件仍需运行：宿主退出或插件重载会停止未完成任务；已保存的文件继续保留，任务记录暂不跨宿主重启保存。 - 导出缓存使用画布所在目录的 `.drawai-cache/video-exports/`，不依赖 Windows 系统临时目录的子进程写权限。开始导出前由 FFmpeg 实际试写输出路径并检查编码器，失败时立即显示目录及原因；底部状态支持选中文字复制，也可点击「复制提示」复制完整信息。 - 离线编码需要宿主可运行 FFmpeg：安装到 `PATH`，或启动 DSH 前设置 `DRAWAI_FFMPEG_PATH` 为 FFmpeg 可执行文件的绝对路径。本源码开发目录也识别 `_local/bin/ffmpeg.exe`（Windows）或 `_local/bin/ffmpeg`；发布包不包含该二进制。缺少 FFmpeg 时明确报错，不退回会掉帧的实时录制方式。源 MP4 直接导出及 SVG 视频包导出不依赖 FFmpeg。 - 宿主 SVG 渲染依赖 `@resvg/resvg-js`，已列入插件运行依赖，更新安装插件时一并安装。常规图形、路径、渐变、镂空与文本由宿主渲染，字体和浏览器的细节可能略有差异；不支持 `foreignObject`，也不读取 SVG 引用的外部网络资源或本地文件。图片须内嵌为 PNG/JPEG/GIF/WebP data URI，内部渐变等 `#id` 引用可正常使用。 - MP4 / WebM / GIF 编码默认使用白色底板，透明区域合成为白色；画面已有的背景色保持原样。直接导出源视频和 SVG 视频包保留原始内容。 - 加载、缺失和错误提示显示在节点内，可重试加载。 - 同一画布一次播放一个视频；切换播放对象时暂停旧视频并保留其进度。切换到其他画布或隐藏浏览器页面时暂停。 播放进度、循环、适配和预览状态均不写入 `.drawio`，也不进入撤销历史。视频封面在导入或复刻完成时生成。 播放器实现位于 `src/video-player.js`，由构建器内联至客户端 bundle。SVG 使用累计时间定位帧、最多四路并发加载帧；长序列按播放/跳转位置预取，最多保留 48 帧 SVG 内容，不等待全片加载。媒体事件和逐帧更新由播放器子组件订阅，不更新整张画布的 React 状态。节点删除、媒体类型切换、文件切换和卸载时清理加载状态、动画任务及 Blob URL。 验证：`node tools/check-video-player.mjs`，也已纳入 `npm test`。 播放默认开启声音，预览控制栏可静音。复刻结果保存原视频副本及片段起点，音频跟随播放、暂停、跳转和循环；SVG 视频包携带音频来源，WebM 导出混入对应片段音频。旧复刻包若没有保存音频来源，需重新复刻。