组合效果 for YMM4 — 使用说明书

版本: 2.2.0 / 支持OS: Windows 10 / 11 (64bit) / 运行时: .NET 10.0

1. 概述

"组合效果"是一款在 YukkuriMovieMaker4（YMM4）上运行的视频效果插件。可将多个视频效果存放在单个"组合效果"项目中，进行分组、预设保存和调用管理。

主要特点：

将多个效果整合到一个项目中并按顺序应用
以命名预设的形式保存、调用和共享
通过标签管理多套效果配置并可即时切换（支持添加、删除、重命名）
通过全部、收藏、最近使用三种虚拟组进行整理
类 Git 的快照历史与分支管理
带 CRC32 校验的原子写入与 SHA-256 哈希多重冗余持久化
预设包文件（.ceprstpkg）的导出与导入
通过剪贴板进行复制、剪切和粘贴
支持正则表达式的多轴搜索
支持8种语言的UI（日语、英语、简体中文、繁体中文、韩语、西班牙语、阿拉伯语、印度尼西亚语）
宽度低于400px时自动切换为移动端布局的响应式UI

时间轴标签会显示当前效果数量和已应用预设名称，例如"组合效果应用中: 3个 [预设名称]"，便于直观把握内容。

不支持 AviUtl 输出（.exo）。

2. 运行环境

项目	要求
OS	Windows 10 / 11 (64bit)
YukkuriMovieMaker4	推荐使用最新版本
运行时	.NET 10.0
GPU	支持 Direct2D 的 GPU

3. 安装方法

从 GitHub 的 Releases 页面下载最新的 .ymme 文件。
确认 YMM4 未在运行。
双击下载的 .ymme 文件进行安装。
启动 YMM4，在时间轴上选择一个项目。
从添加视频效果中选择 "组合效果"。

安装后，属性面板中将显示预设管理面板和效果列表。

4. 快速入门

在时间轴上选择视频或图像等视频项目。
从添加视频效果中添加"组合效果"。
在属性面板下方的"活动效果"区域添加并设置所需效果。
在预设管理面板中点击"＋（添加）"按钮，输入名称并保存预设。
如需将相同配置应用到其他项目，选择预设后点击"✓（应用）"按钮。

5. 界面构成

属性面板从上到下依次显示以下区域。

5-1. 预设管理面板（PresetManagerControl）

预设管理的主操作区域，分为左右两列。

区域	说明
左列（组列表）	显示用户自定义组和虚拟组（全部、最近使用、收藏）。单击选中，双击重命名，拖放排序（虚拟组无法移动）。底部 + 按钮可添加组，- 按钮可删除组。
右列上方（搜索栏）	通过关键词筛选预设。点击右端图标可切换搜索目标。
右列中央（预设列表）	显示当前组的预设列表。每行显示★（收藏切换）、名称、效果数量、信息图标（悬停显示效果列表）。支持多选（Ctrl点击、Shift点击）。
右列下方（操作按钮）	从左到右依次为"添加（＋）"、"删除（－）"、"更新（↺）"、"应用（✓）"按钮。鼠标悬停时标签会展开动画。
底部调整大小手柄	拖动可调整面板高度。

5-2. 网格分割线

拖动左右列之间的边界线可调整组列的宽度，下次启动时将恢复该设置。

5-3. 移动端布局（宽度低于400px）

控件宽度低于400px时，组列表将自动隐藏，并显示汉堡菜单按钮（≡）。点击该按钮可以弹出组列表。

5-4. 效果标签管理（EffectTabManagerControl）

“活动效果”上方会显示标签栏。每个标签都保存独立的效果配置，切换标签后会立即反映当前选中标签的内容。

右侧＋按钮: “添加标签”
各标签的×按钮: “删除标签”（首个标签“新建”不可删除）
双击标签名: 重命名（按 Enter 或失去焦点确认，按 Esc 取消）
默认标签名: 第一个为“新建”，之后为“标签 2”“标签 3”……

5-5. 活动效果（VideoEffectSelector）

YMM4 标准视频效果选择器会显示当前选中标签的效果。此处的添加、删除、排序、启用/禁用操作都会保存到该标签。

6. 组管理

预设可按组分类整理。组分为"实组"和"虚拟组"。

6-1. 添加组

点击组列表底部的"+"按钮。
在弹出的对话框中输入组名并点击"确定"。
新组将被添加到列表并自动选中。

6-2. 删除组

在组列表中选择要删除的组。
点击组列表底部的"-"按钮。
在确认对话框中点击"确定"，将删除该组及其所有预设。

注意："默认"组和虚拟组（全部、最近使用、收藏）无法删除。

6-3. 重命名组

可通过以下任一方式重命名：

双击组打开对话框，输入新名称。
右键点击组，从上下文菜单中选择"重命名"。

注意：虚拟组无法重命名。

6-4. 排序组

可通过拖放更改实组的顺序。虚拟组始终固定在列表顶部，无法移动。

7. 预设管理

7-1. 添加预设（保存）

在"活动效果"中设置要保存的效果。
在组列表中选择目标组（选择虚拟组时将保存到第一个实组）。
点击右列底部的"＋（添加）"按钮。
在对话框中输入预设名称并点击"确定"。
当前效果配置将作为预设保存并添加到列表中。

7-2. 删除预设

在列表中选择要删除的预设（支持 Ctrl 点击、Shift 点击多选）。
点击"－（删除）"按钮或右键选择"删除"。
在确认对话框中点击"确定"即可删除。

选择多个预设后执行删除，将一次性删除所有选中的预设。

7-3. 重命名预设

双击预设打开对话框，输入新名称。
右键点击并选择"重命名"。

7-4. 清空预设（清除内容）

删除预设中保存的所有效果，使预设为空。预设本身保留。

右键点击目标预设。
从上下文菜单中选择"清空预设"。
在确认对话框中点击"确定"。

7-5. 排序预设

在预设列表内可通过拖放更改顺序。查看虚拟组（全部、收藏、最近使用）时无法排序。

8. 虚拟组

虚拟组是始终显示在组列表顶部的特殊组，无法删除、重命名或排序。

组名	内容	排序
全部	显示所有实组中的所有预设。	按名称升序
最近使用	显示最近应用的预设，最多10条。	最新应用优先
收藏	显示已标星的预设。	按名称升序

在选择虚拟组的状态下添加或粘贴预设时，将保存到第一个实组中。

9. 应用预设

9-1. 应用单个预设

在列表中选择要应用的预设。
点击"✓（应用）"按钮或右键选择"应用"。
预设的效果配置将加载到时间轴上的项目中。

重复应用相同预设：如果尝试应用的预设内容与当前效果完全相同，将弹出确认对话框。点击"确定"将在当前效果后追加（叠加）。点击"取消"则中止操作。

9-2. 同时应用多个预设

使用 Ctrl 点击或 Shift 点击选择多个预设。
点击"✓（应用）"按钮。
所选多个预设的效果将按顺序合并后应用。

多选时不显示重复确认对话框。另外，选择2个以上预设时，不会更新"最近使用"列表，也不会记录预设 JSON。

9-3. 应用预设后的标签更新

应用单个预设后，时间轴标签将更新为"组合效果应用中: 3个 [预设名称]"的形式。即使手动修改效果，预设名称仍会保留显示。

10. 更新预设

用当前效果配置覆盖选中的预设。

在列表中选择要更新的预设。
修改"活动效果"中的效果。
确认"↺（更新）"按钮处于激活状态（仅在效果有变化时可用）。
点击"↺（更新）"按钮或右键选择"更新"。

更新按钮激活条件：仅当选中的预设与最近应用的预设相同，且当前效果配置与预设中保存的内容不同时才激活。修改效果参数后，将在50ms 防抖后自动判断。

11. 预设搜索

在搜索框中输入关键词，可实时筛选预设。

11-1. 切换搜索模式

点击搜索框右端的筛选图标可打开菜单，切换搜索目标。

搜索模式	搜索目标
预设名称（默认）	预设的名称
效果名称	预设中包含的所有效果标签（换行分隔的列表）
效果数量	预设中包含的效果数量。输入数字时优先完全匹配，不匹配则回退到字符串部分匹配
内部数据（JSON）	序列化后的效果配置原始 JSON 数据，可通过效果类型名或参数值进行搜索
所有	显示名称、效果名称或原始 JSON 中任意一项匹配的预设

11-2. 正则表达式搜索

所有搜索模式均支持正则表达式（不区分大小写）。

示例：^blur → 搜索名称以"blur"开头的预设
示例：color|shadow → 搜索名称包含"color"或"shadow"的预设
示例：[0-9]+ → 搜索名称中包含数字的预设

输入无效的正则表达式时，将回退为普通的部分匹配搜索（不区分大小写）。

12. 收藏

将常用预设标记为收藏，即可从"收藏"虚拟组快速访问。

12-1. 标记/取消收藏

点击预设列表每行左端的★按钮。

★变为黄色（金色）表示已收藏。
★变为灰色表示未收藏（已取消）。

更改将立即保存到预设文件中。

12-2. 查看收藏组

在组列表中选择"收藏"，将按名称顺序显示所有已标星的预设。在查看"收藏"组时取消某预设的收藏，该预设将立即从列表中消失。

13. 复制、剪切与粘贴

可通过剪贴板复制、剪切和粘贴预设。数据以与预设包相同的 JSON 格式写入剪贴板，也可在文本编辑器中查看和编辑内容。

13-1. 复制

选择要复制的预设（支持多选）。
右键点击并选择"复制"。

原始预设保持不变。

13-2. 剪切

选择要移动的预设（支持多选）。
右键点击并选择"剪切"。

将同时执行复制到剪贴板和删除原始预设的操作，不显示删除确认对话框。

13-3. 粘贴

在组列表中选择目标组。
右键点击预设列表的空白区域或任意预设，选择"粘贴"。

仅当剪贴板中包含有效的预设包 JSON 时才可执行。粘贴的预设将分配新的 GUID（与原始ID不同）。若选中了虚拟组，则会添加到第一个实组中。

13-4. 剪贴板数据格式

写入剪贴板的数据使用以下 JSON 格式：

{
  "FormatId": "CombinedEffect.PresetExchange",
  "Version": 1,
  "ExportedAtUtc": "2025-01-01T00:00:00+00:00",
  "Presets": [
    {
      "Id": "...",
      "Name": "预设名称",
      "IsFavorite": false,
      "SerializedTabs": "...",
      "SerializedEffects": "..."
    }
  ]
}

14. 预设的导出与导入

可将预设导出/导入为包文件（扩展名 .ceprstpkg），实现不同环境和用户之间的预设共享。

14-1. 导出（Export）

在列表中选择要导出的预设（支持 Ctrl 点击、Shift 点击多选）。
右键点击并选择"导出"。
文件保存对话框打开后，指定保存位置和文件名并保存。

选择单个预设时：以预设名称为默认文件名（文件名中不允许使用的字符将替换为 _）。
选择多个预设时：使用默认包名"组合效果_预设"作为初始值。

14-2. 导入（Import）

在组列表中选择要添加导入预设的目标组。
右键点击预设列表的空白区域，选择"导入"。
文件选择对话框打开后，选择 .ceprstpkg 文件（可同时选择多个文件）。
导入的预设将被添加到当前组中。

导入的预设将分配新的 GUID，不会与现有预设冲突。

14-3. 版本兼容性

包文件中记录了格式版本号，当前版本为 1。尝试导入超过支持版本的包时，将显示错误消息。

15. 快照历史与分支管理

每个预设都提供类 Git 的历史管理窗口。可将效果配置的变更历史保存为快照，并通过分支进行分叉管理。

15-1. 打开历史管理窗口

右键点击要管理历史的预设。
从上下文菜单中选择"历史管理"。
历史管理窗口打开（每个预设对应一个窗口）。

15-2. 历史管理窗口构成

面板	说明
左侧（分支列表）	列出该预设的所有分支。点击选中，所选分支的快照历史将显示在中央。在底部文本框输入分支名称后点击"新建分支"可添加新分支。
中央（快照列表）	从选中分支的 HEAD 向上显示快照列表。每行显示提交图标（当前 HEAD 为实心）、标签、消息、日期时间、差异摘要和ID。右键可打开上下文菜单。在底部输入消息后点击"保存新快照"按钮可保存当前配置。底部的"恢复到此"按钮可回退到选中的快照。
右侧（差异显示）	显示选中快照与当前效果配置的差异。新增用绿色、删除用红色、修改用黄色进行颜色标记。效果数量的增减及各属性修改前后的值以 Consolas 字体显示。

15-3. 创建快照

打开历史管理窗口。
在中央面板底部的文本框中输入变更内容的消息。
点击"保存新快照"按钮。
当前预设的效果配置将作为快照保存，所选分支的 HEAD 将更新。

15-4. 回退到快照（Revert）

在列表中选择要回退的快照。
点击"恢复到此"按钮。
预设和时间轴上的项目（组合效果）的效果配置将恢复到所选快照的状态。

15-5. 创建分支

在左侧面板底部的文本框中输入新的分支名称。
点击"新建分支"按钮。
将以当前选中的快照（或当前分支 HEAD）为起点创建新分支。

15-6. 上下文菜单操作

右键点击快照可显示上下文菜单。

操作	说明
合并到当前	将选中快照的效果追加到当前效果末尾。
保留更改 (Soft)	将当前分支的 HEAD 移动到选中快照，不改变时间轴上的效果。
放弃更改 (Hard)	同时执行保留更改 (Soft) 和快照回退 (Revert)。
管理标签	打开快照的标签管理窗口。

15-7. 差异摘要说明

快照列表的"更改"列中显示差异摘要。

"已添加 (+N)"：快照比当前效果多 N 个
"已删除 (N)"：快照比当前效果少 N 个
"已修改"：效果数量相同，但参数已更改
（空白）：与当前效果配置内容相同

15-8. 历史数据保存位置

历史数据保存在插件目录下的 History/ 文件夹中。每个预设创建一个子文件夹，分支信息保存为 branches.json，各快照保存为 {ID}.json。

16. 标签管理

可为快照添加多个标签进行整理。标签在快照列表中以绿色显示。

16-1. 添加标签

右键点击要添加标签的快照。
从上下文菜单中选择"管理标签"。
标签管理窗口打开。
在顶部文本框中输入标签名称并点击"添加"按钮。

不允许添加重复的标签名称。

16-2. 删除标签

打开标签管理窗口。
点击要删除标签行的"删除"按钮。

17. 批量删除效果

可批量删除"组合效果"中已禁用（取消勾选）的效果。

右键点击预设列表的空白区域。
从上下文菜单中选择"清除" → "删除未选中的效果"。
在确认对话框中点击"确定"。
当前所有禁用的效果将被删除。

已启用的效果不会被删除。如果没有禁用的效果，则不会执行任何操作。

18. 响应式 UI 与布局调整

18-1. 调整面板高度

拖动预设管理面板底端的调整大小手柄（双线）可调整面板高度。最小高度为200px。松开拖动时保存设置，下次启动时恢复。

18-2. 调整组列宽度

拖动组列表与预设列表之间的边界线（网格分割线）可调整组列宽度。最小宽度为120px，最大宽度为400px，拖动完成时保存设置。

18-3. 移动端布局

控件宽度低于400px时将发生以下变化：

组列表面板隐藏。
网格分割线隐藏。
搜索栏左侧显示汉堡菜单按钮（≡）。
点击该按钮以弹出框打开组列表，选择组后弹出框关闭。

控件宽度恢复至400px或以上时，将自动切换回桌面布局。

19. 数据保存与安全持久化

所有预设数据、组配置和历史数据均保存为 JSON 文件。通过以下多重冗余化和完整性验证机制，防止单一故障导致数据丢失。

19-1. 原子写入

文件写入按以下步骤进行：

写入临时文件（.tmp）。
使用 File.Replace 将临时文件与主文件替换，并将旧文件移动到备份（.bak）。
即使写入过程中崩溃，主文件或备份文件中必有一个处于有效状态。

19-2. CRC32 校验

写入时计算文件内容的 CRC32 校验和并附加到文件末尾。读取时进行校验，不匹配时尝试从备份文件恢复。

19-3. SHA-256 哈希多重冗余

预设数据和组注册表保存在以下两个位置：

主存储：插件目录下的 presets/ 文件夹
备份存储：user/backup/CombinedEffect/ 文件夹

启动时将两者内容与 CombinedEffectSettings 中记录的 SHA-256 哈希值和时间戳进行比对，检测到不一致时，自动用正确数据修复（愈合）。

19-4. 防抖写入

连续的变更操作经过300ms防抖（删除操作为100ms）后统一写入，从而降低 I/O 负载。

19-5. 日志记录

操作日志和错误日志保存在 user/log/CombinedEffect/ 下。

日志文件超过 512 KB 时创建新文件。
超过31天的日志文件将自动删除（每小时检查一次）。

20. 从旧版本迁移

如果以下路径存在旧版本数据文件，首次启动时将自动执行迁移。

%AppData%\YukkuriMovieMaker4\user\plugins\CombinedEffect\presets.json

迁移完成后，旧文件将重命名为 presets.json.migrated。迁移失败时旧文件不会被删除。

迁移对象：

旧格式的组列表（相当于虚拟组"全部"和"收藏"的组将被排除）
各组中的预设（名称、收藏状态、效果配置）

21. 文件与文件夹结构

路径（相对于插件目录）	内容
`presets/`	主预设数据保存文件夹
`presets/groups.json`	组配置（组名和所属预设ID列表）
`presets/{GUID}.json`	各预设数据（名称、收藏、效果配置JSON）
`presets/recent_ids.json`	最近使用预设ID列表（最多10条）
`presets/UISettings.json`	UI设置（面板高度、组列宽度）
`History/`	快照历史数据保存文件夹
`History/{预设GUID}/branches.json`	该预设的分支列表
`History/{预设GUID}/{快照GUID}.json`	各快照数据
`user/backup/CombinedEffect/`	备份存储（相对于YMM4安装目录）
`user/log/CombinedEffect/`	日志文件保存文件夹（相对于YMM4安装目录）

预设数据同时保存在主存储和备份存储中。丢失其中一方仍可从另一方恢复，但两者均丢失则无法恢复数据。

22. 多语言支持

整个UI将根据 YMM4 的语言设置自动切换，无需额外配置。

语言代码	语言
ja-jp	日语
en-us	英语
zh-cn	简体中文
zh-tw	繁体中文
ko-kr	韩语
es-es	西班牙语
ar-sa	阿拉伯语
id-id	印度尼西亚语

23. 参数说明

参数名	类型	默认值	可动画化	说明
活动效果（Effects）	ImmutableList<IVideoEffect>	（空）	否	要管理的视频效果列表。使用 YMM4 标准效果选择器添加、删除、排序和启用/禁用效果。按从上到下的顺序进行流水线处理，禁用的效果将被跳过。
EffectTabsJson	String（JSON格式）	（空字符串）	否	保存效果标签状态（当前选中标签ID、标签名称、各标签的效果JSON）的内部属性。在添加/删除/重命名/切换标签时自动更新。
SelectedPresetJson	String（JSON格式）	（空字符串）	否	保存当前已应用预设信息的内部属性。应用预设时自动设置，不推荐直接编辑。用于时间轴标签显示。
PresetManagerVisible	bool	true	否	控制预设管理面板显示的内部标志，不包含在JSON序列化中（[JsonIgnore]）。

标签显示格式

状态	显示格式	示例
未应用预设	{效果名} 应用中: {N}个	组合效果应用中: 3个
已应用预设	{效果名} 应用中: {N}个 [{预设名}]	组合效果应用中: 3个 [效果A套装]

24. 操作速查表

标签操作

操作	方法	限制与补充
添加标签	标签栏右侧“＋”按钮	新标签以空效果配置创建
删除标签	标签上的“×”按钮	首个标签“新建”不可删除
重命名标签	双击标签后编辑	Enter/失去焦点确认，Esc取消
切换标签	点击标签	选中标签的效果会反映到“活动效果”

组操作

操作	方法	限制
添加组	组列表底部"+"按钮	无
删除组	组列表底部"-"按钮	默认组和虚拟组不可删除
重命名组	双击，或右键→"重命名"	虚拟组不可重命名
排序组	拖放	虚拟组不可移动

预设操作

操作	方法	限制与补充
添加预设	"＋（添加）"按钮	选择虚拟组时保存到第一个实组
删除预设	"－（删除）"按钮，或右键→"删除"	有确认对话框，支持多选
重命名预设	双击，或右键→"重命名"	无
排序预设	拖放	查看虚拟组时不可排序
应用预设	"✓（应用）"按钮，或右键→"应用"	内容相同时有确认对话框
更新预设	"↺（更新）"按钮，或右键→"更新"	仅在效果有变化时可用
清空预设	右键→"清空预设"	有确认对话框，仅在效果数量≥1时可用
切换收藏	点击★按钮	无
复制	右键→"复制"	支持多选
剪切	右键→"剪切"	无确认对话框，支持多选
粘贴	右键→"粘贴"	需要剪贴板中有有效的JSON
导出	右键→"导出"	支持多选，.ceprstpkg格式
导入	空白处右键→"导入"	可同时选择多个文件
删除未选中效果	空白处右键→"清除"→"删除未选中的效果"	有确认对话框
打开历史管理	右键→"历史管理"	每个预设对应一个窗口

历史管理操作

操作	方法	说明
保存快照	输入消息→"保存新快照"按钮	消息为空时不可用
回退到快照	选择快照→"恢复到此"按钮	同时应用于预设和时间轴
创建分支	输入分支名→"新建分支"按钮	分支名为空时不可用
合并	右键快照→"合并到当前"	效果追加到当前末尾
保留更改（Soft Reset）	右键快照→"保留更改 (Soft)"	仅移动HEAD，不更改效果
放弃更改（Hard Reset）	右键快照→"放弃更改 (Hard)"	同时执行Soft Reset + Revert
管理标签	右键快照→"管理标签"	打开标签管理窗口

25. 注意事项

不支持 AviUtl 格式（.exo）输出。
不推荐在"组合效果"中嵌套另一个"组合效果"。
"全部"、"收藏"、"最近使用"虚拟组无法删除、重命名或排序。
"默认"组无法删除。
在选择虚拟组的状态下添加或粘贴预设，将保存到第一个实组中。
导入包文件时，将分配与原始 GUID 不同的新ID，因此导入的预设不继承快照历史。
剪切操作无需确认对话框即可删除预设。操作后无法立即撤销，请谨慎使用。
单个预设应用时会恢复已保存的标签结构（包含当前选中标签）。同时应用多个预设，或对同一预设执行重复叠加应用时，仅合并各预设选中标签的效果，并重建为单一“新建”标签。
预设数据保存在主存储和备份存储两处。删除其中一个文件夹仍可能恢复数据，但两者均删除将导致预设永久丢失。
历史数据保存在 History/ 文件夹中，删除此文件夹将丢失所有历史记录。
快照历史会无限增长。如有过多不必要的历史记录，可手动删除 History/{预设GUID}/ 文件夹中不需要的 .json 文件（请勿删除 branches.json）。
预设效果配置中仅保存 YMM4 插件系统支持的效果，不支持的效果在加载时可能会被跳过。
由于防抖写入机制，变更操作后实际写入文件最多有300ms延迟。若立即强制退出 YMM4，最后一次操作可能不会被保存。

26. 免责声明与许可证

本插件基于 MIT 许可证发布。

本软件按"原样"提供，不作任何明示或默示的保证，包括但不限于适销性、特定用途适用性和非侵权性保证。

作者对因使用或无法使用本插件而造成的任何损失概不负责。使用本软件须自行承担风险。

作者: routersys / 许可证: MIT License / 仓库: https://github.com/routersys/YMM4-CombinedEffect

文档结束。