# FlashCut **Repository Path**: otreee/FlashCut ## Basic Information - **Project Name**: FlashCut - **Description**: No description available - **Primary Language**: Python - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-09-06 - **Last Updated**: 2026-09-06 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # FlashCut FlashCut 是面向长视频快速过片的 Windows 桌面工具：高速浏览、在源时间轴上标记点式 HL， 再按 `HL - 前时长` 到 `HL + 后时长` 导出即时重放式片段。它不是非线性剪辑软件，不包含 多轨、波形、转场、调色或字幕编辑。 当前版本：**v0.5.0** ## 已实现功能 - 拖入单个视频或整个文件夹，也可从“文件”菜单打开。播放区上方有独立透明原生拖放层，不再依赖 `QVideoWidget` 是否转发拖放；无媒体时始终显示“拖动到此处松开即播放”。 - 每个源视频在独立缓存目录保存 `project.json`、`metadata.json`、`proxy.mkv` 和 `proxy_info.json`。缓存键使用规范化绝对路径，文件大小与纳秒修改时间用于失效检查。 - 再次打开时立即恢复 HL、备注、代理状态，以及可选的播放位置和倍速。 - 短于阈值的视频跳过代理；长视频默认使用 `-skip_frame nokey` 仅抽源 I 帧，也可在设置中改为均匀抽帧。I 帧模式的密度由 GOP 决定，设置中的抽帧密度会禁用。 - 打开文件夹后先并行探测文件，当前视频优先；之后使用有界提交队列，最终为文件夹内所有达到预加载阈值的视频生成代理，短片明确跳过。导出和新打开视频可抢占后台工作，被中断的文件会回到队列。 - 右上“HL 时间点 / 文件夹视频”选项卡显示原文件名提示、最多 32 字符显示名、时长、FPS 与代理状态，可双击切换视频。 - 代理可选原分辨率/指定分辨率、H.264/HEVC。NVIDIA 模式使用 NVDEC/CUVID 解码、CUDA 帧筛选/缩放和 NVENC 编码，像素数据不回传内存；抽 I 帧组合 `-discard:v nokey`、`-skip_frame nokey` 与 GPU 上的 `select=key`，避免 CUVID 单独忽略 `skip_frame`。可指定 GPU index 和显存解码 surface 池，并决定是否允许 CPU 回退。代理输入默认限制为 `2x`，可在设置中修改，以限制后台 NVDEC/NVENC 与磁盘占用。 - 当前视频正在创建代理时，播放区中央显示说明、实时进度、“取消”与“先使用原视频”。选择原视频后，代理仍在后台继续，播放倍速按当前分辨率的无代理上限约束；到达上限会在播放区显示 2 秒后平滑淡出的顶层半透明 HUD。 - LRU 风格滚动缓存只清理旧代理媒体，保留体积很小的 HL JSON；当前视频代理受保护。 - 低倍速使用原片，严格超过设置阈值后使用代理；支持单路和双路并行切换。双路模式在后台准备两个 `QMediaPlayer`，切换前用同一源时间对齐。 - 没有可用代理时严禁进入代理流；默认 >1080p/4K 原片限制为 4x，≤1080p 限制为 16x，两个上限均可在“设置 → 播放”修改，到达上限显示 2 秒 HUD。 - 打开视频后自动播放；倍速大于 2x 时直接禁用音轨，恰好 2x 仍播放声音。 - 可设置 1–240 fps 最大显示帧率。解码帧通过共享 `QVideoFrame` 限帧门送往渲染器，超出部分不进行 UI 呈现，不转换为 CPU 图像。 - 原片播放使用有界内存环形预读（默认 256 MB）预热 Windows 文件页缓存；4x 保持连续硬件播放并由后端丢弃过期帧，避免长 GOP 4K AV1 被高频随机 seek 拖慢；>4x 且仍使用原片时才启用稀疏 seek 抽样。实测或预估解码率超过显示预算时，后台 FFmpeg 代理任务会暂停；暂停满 10 秒后持续采样 NVIDIA Video Decode，最近 10 次平均占用 ≤60% 时以系统空闲优先级恢复代理，切入代理流后立即恢复正常生成优先级。 - 播放区左上角以 1 Hz 刷新小型 HUD，始终显示实测解码帧率与当前视频流（原视频/代理）；调试模式额外显示有效输入帧率、过去 10 秒平均预读码率和估算前方缓冲秒数。HUD 使用播放区坐标锚定的顶层工具窗，不会再被 Windows 原生视频层遮住。 - 所有播放区 HUD 使用 50% alpha 半透明背景和圆角外框。 - 自绘预览轴和总轴，不为每个标记创建控件。黄色 HL 书签位于轴上方，蓝色当前帧标签位于总轴下方；靠近播放位置的预览轴 HL 会按设定范围增长。预览轴保持当前帧指针居中，按住左键拖动的是下方时间尺，可用于暂停后的精确定位。预览轴每秒显示一条 1 px 短刻度、每 10 秒显示一条 2 px 长刻度；刻度只缓存可见窗口及前后各一个窗口，默认在 >4x 时隐藏，可在设置中提高到 8x（会增加高倍速重绘开销）。 - HL 标签的尖端始终指向时间轴，并在轴内保留 1 px 帧线；总轴下方的当前帧标签同样向上指向轴。总轴支持按住左键连续拖动定位。 - 点击轴上 HL 会严格先暂停、后跳转；同一源帧已有 HL 时不允许重复标记。 - 预览轴的中心始终表示当前源时间，播放与跳转时由时间窗口在其下方滚动。 - HL 添加、删除、位置调整、备注和专属导出时间支持撤回/重做。调整时只维护候选位置， “完成”后才写入项目；Esc 或调整中的 Ctrl+Z 放弃候选值。 - HL 备注停止输入后自动、原子保存。列表与底栏显示 `HL_HH:MM:SS.xx`；同一显示精度下的 重复标记仍由稳定 UUID 区分。 - 首次标记后在后台计算完整文件 `FC_MD5`。NTFS 上会写入不改动视频主数据的 `FC_MD5` 备用数据流，同时始终保存到项目 JSON。规范化 HLM v2 是 UTF-8 JSON 文本，固定使用 `.HLM` 后缀，包含原片绝对路径/尺寸/修改时间/媒体参数、FC_MD5、全部 HL、备注及专属导出区间。 - 可导出选中或全部 HL；多个 HL 的导出时间窗相交或首尾相接时，会先合并为一个无重复片段。快速方式使用 `-c copy`（边界受关键帧影响），精确方式重编码； NVENC 运行失败时自动回退 libx264。输出先写临时文件，再原子替换最终文件。 - CodecFoundry 集成只认 Windows 已注册应用，并从 App Paths/卸载信息中定位安装目录；除存在性外还会读取版本，当前 HLM v2 联动要求 CodecFoundry `>= 1.1.0`。 - 所有 ffprobe、代理、预加载、缓存清理和导出工作均在 Qt 后台线程池或子进程运行。 - 时间轴控制区与视频区严格同宽；右侧 HL/文件列表与导出设置整列延伸到窗口底部。 - 独立 GUI 设置窗口提供常规、代理/预加载、播放、导出和多快捷键配置，代理页可直接打开当前缓存文件夹；About 弹窗按 CPVC 的层次和暗色节奏重新设计。 - 个性化设置和 5 MB 轮转主日志统一保存在 `%APPDATA%\FlashCut`；旧 `%LOCALAPPDATA%` 设置会自动迁移一次。 - 代理使用按 1 秒簇及时刷盘的 Matroska 容器。生成被中断时保留 `proxy.partial.mkv` 和兼容性清单，下次从最后可读视频包续作并无重编码合并；写入中的 partial 不会交给播放器，避免播放器把暂时的 EOF/未完成索引误判为损坏。底栏实时显示编码 fps、编码倍速、暂停原因与预计剩余时间。 ## 运行要求 - Windows 10/11 - Python 3.10+ - PySide6 6.6+ - FFmpeg 与 ffprobe 位于 `PATH` - 可选：NVIDIA 显卡与可用的 `h264_nvenc` / `hevc_nvenc` - 可选：已通过安装包注册到 Windows 的 CodecFoundry 安装 Python 依赖： ```powershell python -m pip install -r requirements.txt ``` 启动： ```powershell python .\main.py ``` 也可以在 Windows 双击 `FlashCut.pyw`，或把一个视频/文件夹路径传给入口： ```powershell python .\main.py "D:\Videos\A.mp4" ``` 本机未安装 libmpv，因此当前播放适配器使用 PySide6 QtMultimedia。播放控制器与 UI 没有绑定代理生成实现，后续可以增加 libmpv 后端而不改变 HL、缓存或时间轴数据结构。 ## 默认操作 | 操作 | 默认快捷键 | | --- | --- | | 播放/暂停 | `Space` | | 标记 HL | `M` | | 删除 HL | `Delete` | | 加速 / 减速 / 还原 | `D` / `A` / `S` | | 上一个 / 下一个 HL | `Shift+Left` / `Shift+Right` | | 调整 HL | `Ctrl+M` | | 调整时逐帧移动 | `Left` / `Right` | | 完成 / 取消调整 | `Enter` / `Escape` | | 撤回 / 重做 | `Ctrl+Z` / `Ctrl+Y`、`Ctrl+Shift+Z` | | 导出选中 HL | `Ctrl+E` | 所有操作都可以在“设置 → 快捷键”中配置一个或多个按键。文本输入框获得焦点时，单键操作 不会误触发。 ## 绝对源时间与代理设计 FlashCut 的唯一权威时间域是原视频秒数。HL JSON 不保存 UI 像素、代理帧号或压缩后的 “播放时间”。CPU 均匀抽帧和仅 I 帧代理保留源 PTS；NVIDIA 均匀模式在 GPU 帧上做输出速率同步，避免为了 CPU `fps` 滤镜而下载 CUDA 帧。共同基础参数为： ```text -copyts -start_at_zero ... ``` 均匀模式用 `fps=N` 或 GPU 端 `-r N -fps_mode cfr` 选取代表帧；I 帧模式在解码端用 `-skip_frame nokey` 丢弃非关键帧，并同样保留可变间距。`proxy_info.json` 明确记录 `timestamp_mode: source_pts_video_only`。代理不包含音轨；I 帧模式在源结尾补一个视频时长哨兵帧，因此即使 最后一个 I 帧离文件结尾较远，播放器也会保持最后一张代表画面直到真正的源结尾。因此代理 播放器的位置可以直接解释为源时间；切换时流程为： 1. 从活动播放器读取源时间； 2. 暂停当前流； 3. 在目标流 seek 到相同毫秒值； 4. 设置相同倍速并恢复； 5. UI、HL 与导出继续使用源时间。 项目中的权威源时长始终来自原片 ffprobe，绝不由代理覆盖。 ## 缓存结构 ```text CacheRoot/ └── _/ ├── project.json ├── metadata.json ├── proxy.mkv ├── proxy.partial.mkv # 生成中或中断后存在；只用于续作 ├── proxy_resume.json # 部分文件兼容性清单 └── proxy_info.json ``` 当源大小或修改时间改变，代理会失效，播放位置归零；用户 HL 和备注会保留，避免静默丢失 人工工作。后台 worker 只发布原子的 metadata/proxy sidecar，不会用过期项目副本覆盖正在 编辑的 HL JSON。 ## CodecFoundry 联动 设置“输出处理”为“联动 CodecFoundry”后，FlashCut 不生成任何中间视频。它写出一份 HLM v2，随后运行： ```text "<注册的安装目录>/CodecFoundry.exe" --hlm <联动任务.HLM> ``` HLM 的 `processing` 段包含最低 CF 版本、原片处理模式、编码/容器/字幕/覆盖选项、输出目录， 以及每个任务的 HL id、精确 `start/end/duration` 和输出名。顶层 `highlights` 始终保留当前 原片的完整 HL 数据，即使本次只联动“导出选中”。CF 打开后，待处理列表直接显示这些 HL 视频任务，并由 CF 自己从同一原片执行定位、解码、裁切和最终编码。若应用未注册、版本过低、 可执行文件、GPU 或 CF 配置不可用，FC 会保留 HLM/HL 项目并显示可操作错误，不会退回代理素材导出。 ## 开发与验证 运行全部测试： ```powershell $env:QT_QPA_PLATFORM = "offscreen" python -m unittest discover -s tests -v ``` 测试覆盖时间码、HL 命令撤回/重做、源变更与缓存失效、sidecar 合并、LRU 清理、FFmpeg 命令、 GUI 构建，以及一个真实 FFmpeg 集成用例。集成用例生成 6 秒视频，确认 1 fps 稀疏代理仍保留 约 `0, 1, 2, 3, 4, 5` 秒的源 PTS，而不是压缩成 6 个连续高帧率画面。 ## 目录结构 ```text main.py 应用入口 FlashCut.pyw Windows 双击入口 flashcut/ about_dialog.py CPVC 风格 About 弹窗 main_window.py 主窗口、菜单和 HL 工作流 playback.py 原片/代理单路与双路播放控制 read_ahead.py 原片有界内存预读与磁盘/缓冲统计 timeline.py 自绘预览轴与总轴 models.py 源时间数据模型 commands.py 撤回/重做命令 storage.py 原子项目存储与 LRU 缓存 media.py ffprobe、代理与预加载 exporter.py 原片导出和 CodecFoundry 适配器 settings.py 设置模型与持久化 settings_dialog.py GUI 设置窗口 theme.py CodecFoundry 风格深色主题 tests/ 单元与 FFmpeg 集成测试 ``` ## Changelog ### v0.5.0 — 2026-08-15 - CodecFoundry 联动改为 HLM v2 清单交接；FC 不再预导出临时视频，CF 直接从原片完成全部 HL 裁切与编码。 - HLM v2 补齐原片路径、尺寸、修改时间、媒体参数、完整 HL 数据及可执行的 `processing.jobs`。 - 已注册 CF 检测增加应用版本读取和最低版本校验；当前联动门槛集中定义为 `1.1.0`，后续发布决策只需调整一处。 ### v0.4.1 — 2026-08-15 - 修复 AV1 CUVID 单独忽略 `-skip_frame nokey`、错误生成全帧 4K 代理的问题；以输入丢包和 CUDA `select=key` 双重约束保持全 GPU 管线，输出帧数严格等于源 I 帧数。 - 写入中的 MKV 只用于中断续作，不再交给播放器；完成校验后才原子发布 `proxy.mkv`，避免暂时 EOF/未完成索引引发黑屏和 `Read error at pos`。 - Windows 播放器延迟占用旧 `proxy.mkv` 时不再令重建失败；新代理可发布到带 generation 的 MKV，由 sidecar 原子切换，旧文件释放后再清理。 - 代理切换阈值改为严格超过后切换；4x 原片保持连续硬件播放，只有更高倍速才使用稀疏 seek。 - CodecFoundry 改为只从 Windows App Paths 或卸载注册信息定位安装目录中的 `CodecFoundry.exe`。 - 代理因原片解码压力暂停后监测 NVIDIA Video Decode；满 10 秒且最近 10 次平均值 ≤60% 时，以低优先级恢复同一 FFmpeg 进程。 ### v0.4.0 — 2026-08-15 - 新安装默认抽 I 帧代理，均匀抽帧密度会随模式禁用；代理改为可续作 MKV，并在底栏显示编码 fps、倍速与 ETA。 - 原片高速播放使用稀疏 seek 抽样；解码压力超过显示预算时暂停后台代理，压力解除后原进程继续。 - 设置与主日志统一迁移到 `%APPDATA%\FlashCut`，方便安装包和用户配置备份。 - 播放区增加独立顶层透明拖放窗口，直接覆盖 Windows 原生视频 HWND；无媒体时放置 HUD 始终可见。 - 没有代理时严禁切流，新增可配置的 >1080p/4K 4x 和 ≤1080p 16x 原片限速及达限 HUD。 - 单路切回原片改为完整卸载/重载媒体拓扑；媒体 Ready 后重新应用倍速，界面使用 Qt 实际接受的 `playbackRate`。 - 调试 HUD 增加当前原视频/代理流；播放区所有 HUD 统一为 50% alpha 圆角样式。 - 新增全文件 `FC_MD5` 身份、NTFS 非破坏性元数据内嵌与 `.HLM` 标记文件导出。完整 HL 仍保留在项目/HLM 双份数据中，避免仅依赖可在跨文件系统复制时丢失的 NTFS 元数据。 ### v0.3.1 — 2026-08-15 - 拖入整个窗口或原生视频播放区均可打开视频/文件夹，拖入时在播放区中央显示“拖动到此处松开即播放”。 - 解码/调试 HUD 改为锚定播放区的顶层透明工具窗，修复被原生视频层遮挡。 - 音频解码阈值改为严格大于 2x；代理改为纯视频文件，设置中增加“打开代理缓存文件夹”。 - 单路切换会校验播放器的实际 URL，双路切换会同步校验可见层，修复从高速代理还原后仍显示/播放代理的问题。 - 缓存代理在交给播放器前先用 ffprobe 验证；损坏、截断或上次强制关闭遗留的文件会连同 partial/sidecar 一起删除并自动重建。 ### v0.3.0 — 2026-08-15 - 打开视频改为自动播放；初版音轨高速禁用策略在 v0.3.1 精确调整为 >2x。 - 加入可配置最大显示帧率和共享 `QVideoFrame` 限帧门，避免高倍速把每个解码帧都交给渲染器。 - 加入原片有界内存预读，持续保留播放位置前方的文件块并预热 Windows 页缓存；原片高速播放时动态降低 FFmpeg 代理优先级。 - 加入 1 Hz 左上角 HUD；调试模式增加有效输入帧率、10 秒平均读取码率和前方缓冲估算。 - 总轴支持连续拖动；修正 HL/当前帧标签的指向，并在轴内增加 1 px 帧线。 - 轴上 HL 点击改为先暂停再跳转，新建 HL 按原始帧率对齐且拒绝同帧重复。 - About 恢复“技术宅照亮世界”，加入 Bilibili 作者链接和“探索更多免费好用的工具”GitHub 按钮。 ### v0.2.1 — 2026-08-15 - 当前视频代理生成期间，在播放区中央加入实时进度层。 - 加入“取消”和“先使用原视频”；取消只停止当前代理，不影响其他文件夹预载。 - 原视频临时播放时使用代理切换阈值作为倍速上限；超限时显示 2 秒圆角半透明提示 HUD。 - 缓存代理命中时不再启动多余代理任务，已知短片也不会闪现加载层。 ### v0.2.0 — 2026-08-15 - 加入“打开文件夹”、文件夹拖放和“HL 时间点 / 文件夹视频”并排选项卡。 - 文件列表加入 32 字符中间省略、时长、FPS 与实时代理状态，不显示编码和分辨率。 - 文件夹预载改为全量阈值扫描 + 有界提交队列；当前视频与导出优先，取消的后台项自动回队。 - 修复 Windows 原生视频组件吞掉拖放事件的问题。 - 重排主窗口：视频和时间轴左侧同宽，右侧整列延伸到底部，并增加标题高度。 - 抽 I 帧与均匀抽帧均支持 NVDEC/CUVID → CUDA 帧筛选/缩放 → NVENC 全 GPU 视频管线；抽 I 帧额外以输出包校验确保只保留源视频关键帧。 - 按 CPVC 参考重做 About 弹窗，并扩充 GUI/命令级自动测试。 ### v0.1.0 — 2026-08-15 - 建立模块化 PySide6 桌面应用、拖放打开、顶栏菜单和 CodecFoundry 风格主题。 - 加入 QtMultimedia 原片/代理播放、单路/双路切换和绝对源时间同步。 - 加入自绘双时间轴、HL 列表、附近标记强调、候选位置调整和帧级键盘微调。 - 加入 HL JSON、备注自动保存、专属导出窗口、撤回/重做和缓存快速恢复。 - 加入 I 帧/均匀抽帧代理、NVENC/CPU、阈值、同目录低优先级预载和 LRU 清理。 - 加入原片快速/精确导出、CodecFoundry CLI 联动、碰撞安全命名与后台进度。 - 加入完整 GUI 设置、可配置多快捷键、轮转日志及自动化测试。