MMnode/skills/easy-media-multitrack-workflow/references/multitrack-schema.md
Z User 46617b71b8 fix: snap the half-res first pass onto the even-latent grid
Multi-segment projects crashed on the first continuation segment with
RuntimeError: shape '[1, 24, 1, 1, 8, 2, 15, 2]' is invalid for input of
size 12240 (patchify_video). The hidden half-resolution first pass
declared its size with plain integer halving, so a 1920x1080 editor
sampled at 960x540 - and a latent encoded from 540px carries an odd
17-row count. Odd latents sample fine, but when the segment tail comes
back as motion-context keyframes on the next segment, the model's
patchify_video (2x2 latent patches) cannot reshape them.

The first pass now snaps onto the nearest 64px grid (h3_even_latent_size)
so every latent in the pipeline keeps even row/column counts:

- 1920x1080 editor samples at 960x512 (was 960x540 -> 17 rows)
- 1344x768 samples at 704x384 (672 had odd latent columns)
- 3840x2160 is unchanged at 1920x1088 - the size the VAE already rounds
  up to, so the 4K-editor trick behaves identically

Outputs and second-pass dimensions are unchanged; only continuation
segments that previously crashed now run. Also updates the stale
single-task expansion test, which still expected pre-half-res-trick
conditioning dimensions (editor size instead of the sampled size).
2026-10-15 02:05:48 +00:00

19 KiB
Raw Blame History

MultiTrack 数据与编排规则

本参考用于创建或调整 easy multiTrackEditor 的 TRACK_DATA。当前项目的前端类型定义位于 frontend/src/types/multitrack.ts,实际执行逻辑位于 nodes/basic.py。

动态分辨率

resolution 是 easy multiTrackEditor 的 DynamicCombo widget。它不属于 TRACK_DATA;修改时必须按所选模式重建对应的子 widget,并同步工作流已有的 widgets_values_named。使用 patch_workflow.py 的 editor.resolution 写入,不要手工假设数组下标。

需求 resolution 标签 必需子字段
输出固定预设尺寸 如 1344 x 768 (16:9) 可选 resize_method,默认 stretch
明确自定义宽高 width x height (custom) width、height,可选 resize_method
跟随首个视频比例 width x height (auto) 可选 resize_method
固定短边或长边 width x height (shortest) / width x height (longest) resize_to_pixel,可选 resize_method
按比例和总像素预算 width x height (megapixels) aspect_ratio、megapixels

选择顺序:用户给出精确宽高时用已有 fixed preset,若没有对应预设则用 custom;只给横竖屏或画幅比例与质量/像素预算时用 megapixels;要求保持源视频比例时用 auto;要求“短边/长边为 N”时用 shortest/longest。用户没有表达分辨率意图时保留当前设置。模型 format 的默认尺寸只是参考,不能覆盖用户明确要求。

自然语言中的 MP 与比例

把不区分大小写的 mp、Mpx、megapixel(s) 或“百万像素”视为 megapixels 单位。0.9mp、1 MP、0.8 megapixels 等表达直接选择 megapixels 模式,并原样提取数值。同句中的比例映射为 DynamicCombo 的完整 aspect_ratio 值:

用户比例 aspect_ratio
1:1 1:1 (Square)
2:3 2:3 (Portrait Photo)
3:2 3:2 (Photo)
3:4 3:4 (Portrait Standard)
4:3 4:3 (Standard)
9:16 9:16 (Portrait Widescreen)
16:9 16:9 (Widescreen)
21:9 21:9 (Ultrawide)

例如“生成 16:9 0.9mp 大小的视频”无需追问,直接规范化为:

{
  "resolution": "width x height (megapixels)",
  "aspect_ratio": "16:9 (Widescreen)",
  "megapixels": 0.9
}

MP 数值不得换算为宽高或四舍五入。若只有 MP:当前已经是 megapixels 模式则保留其 aspect_ratio;否则可根据明确的横屏/竖屏语义选择 16:9/9:16,仍无法确定时询问。精确宽高、比例与 MP 互相矛盾时也应询问。

custom 示例:

{
  "resolution": "width x height (custom)",
  "width": 1024,
  "height": 576,
  "resize_method": "crop"
}

可用 resize_method 为 stretch、resize、pad、pad (white)、pad_edge、pad_edge_pixel、crop、pillarbox_blur。需要保留完整画面时优先 pad/resize,需要铺满画布且允许裁边时选 crop;不要在用户未提出时擅自改变已有 resize method。

时间语义

  • start_frame 包含,end_frame 不包含;片段帧数为 end_frame - start_frame。
  • 秒转帧使用 round(seconds * frame_rate),每个片段至少 1 帧。
  • 同一轨道中的片段按 start_frame 排序且不得重叠;允许间隙。不同同类轨道可独立编排。
  • 有片段时,total_length 应为所有轨道最大 end_frame。无片段时可保留编辑器当前默认长度。
  • 修改 FPS 时,应按时间比例重映射所有片段边界、origin_start_frame 和 task marker,而不是只改 frame_rate。

顶层对象

{
  "muted": false,
  "volume_db": 0,
  "task_markers": [],
  "task_overview": false,
  "tracks": [],
  "total_length": 240,
  "frame_rate": 24
}

轨道 type 为 task、video、audio 或 subtitle。保留现有未知字段,以兼容新版本。

通用轨道与片段

{
  "id": "uuid",
  "name": "Video 0",
  "type": "video",
  "color": "var(--primary)",
  "muted": false,
  "solo": false,
  "volume_db": 0,
  "locked": false,
  "segments": [
    {
      "id": "uuid",
      "start_frame": 0,
      "end_frame": 120,
      "color": "var(--primary)",
      "content": {}
    }
  ]
}

新建轨道时优先使用项目已有颜色 token:task 为 var(--multitrack-task-bg),video 为 var(--primary)。保留现有轨道自己的颜色。

任务片段

{
  "media_type": "none",
  "task_mode": "ref",
  "continuity_mode": "shot",
  "ref_image_size": "match",
  "images": [],
  "user_prompt": "用户提示词",
  "system_prompt": "",
  "user_prompt_variant": "a",
  "user_prompt_b": "",
  "muted": false,
  "volume_db": 0
}
  • task_mode: default、l2v、ref、edit。
  • continuity_mode: shot(独立镜头)、context(普通上下文衔接)或 context_swap(上下文主体替换)。
  • ref_image_size: match 或 max。
  • images 最多 9 张,顺序决定 Picture 引用顺序。
  • 编辑已有任务时保留未要求改变的 system_prompt、prompt variant、连续性和参考图策略。
  • 若当前 variant 为 b,应修改 user_prompt_b;否则修改 user_prompt。不要无意切换 variant。

任务参考图:

{
  "id": "uuid",
  "source_type": "input",
  "file_path": "codex/session-123/reference.png",
  "file_name": "reference.png"
}

source_type 可为 input、output、local、url 或 slot。字段必须与来源匹配:input/output 用 file_path,local 用 local_path,url 用 url,slot 用 slot_name。不要把本机绝对路径标成 input。

上下文分段需要反复使用同一张参考图时,可在图片项上设置 "shared_reference": true。该图片会成为公用图片,自动排在每个任务片段的私有图片之前;公用和私有图片合计仍不得超过 9 张。不要为了共享而在每个任务中手工复制相同图片。

上下文主体替换模式

context_swap 是“上下文主体替换”衔接模式:沿用前一段的场景和运动上下文,同时允许模型根据参考视频替换主体、人物、物体或局部区域。用户提供视频作为主体替换、人物替换、物体替换、服装/脸部等局部替换参考时,按以下规则编排:

  • 将本次范围内所有 task segment 的 content.continuity_mode 设为 context_swap;不要只修改第二段或后续片段。首段虽然没有前序生成上下文,也保持同一模式,以便项目元数据和后续重生成一致。
  • 参考视频放在 video track,并覆盖全部目标 task segment 的时间范围。若它还需要跨任务作为模型参考,在视频片段 content 上设置 shared_reference: true。
  • 在该 video track 设置轨道级 audio_locked: true,让源视频时间驱动生成;同时只把其他 video track 的 audio_locked 显式设为 false。若要替换原声,可另锁定一条 audio track,后者会优先作为音频来源。仅沿用视频原声时,锁定前确认视频包含可用音轨并覆盖全部目标 task segment。
  • 用户明确指定片段长度或边界时以用户要求为准。否则按连续 10 秒拆分 task segment:每段帧数为 round(10 * frame_rate),最后一段使用参考视频的剩余帧,不补齐、不丢弃余数,也不创建空末段。参考视频本身可保留为覆盖完整范围的单个 video segment,无需为每个 task segment 重复复制。
  • 用户明确要求去掉、替换或不保留参考视频原声时,不自动锁定该 video track,并按用户指定的音频方案处理。

视频与音频片段

{
  "media_type": "video",
  "source_type": "input",
  "file_path": "codex/session-123/clip.mp4",
  "file_name": "clip.mp4",
  "duration": 5.0,
  "muted": false,
  "volume_db": 0,
  "speed": 1
}

音频把 media_type 改为 audio。素材原始时长可用 ffprobe 获取;时间线时长按用户目标、裁切和速度决定。若用户要求素材与任务片段对齐,应复用相同的 [start_frame, end_frame),不要仅依靠相近秒数。

音频锁定决策

audio_locked 是 audio/video 轨道级字段。锁定 audio track 会沿用其音频;锁定 video track 会让生成画面遵循视频轨道时间线,并在没有锁定 audio track 时沿用视频原声。两种锁可以同时存在;此时 audio track 优先作为 audio_lock 的音频来源,video track 仍负责画面时间线。它与轨道的 locked 不同:locked 只禁止时间线编辑,不能代替 audio_locked。

{
  "id": "music-track",
  "name": "Master Song",
  "type": "audio",
  "audio_locked": true,
  "muted": false,
  "segments": [
    {
      "id": "song-segment",
      "start_frame": 0,
      "end_frame": 240,
      "content": {
        "media_type": "audio",
        "source_type": "input",
        "file_path": "codex/mv/song.wav",
        "file_name": "song.wav"
      }
    }
  ]
}

同一个 TrackData 最多可有一条 audio_locked: true 的 audio track 和一条 audio_locked: true 的 video track。切换同类型锁定来源时,应把该类型的其他轨道显式设为 false,不要清除另一种类型的锁。不要把 audio_locked 写进媒体片段的 content;旧版片段级字段仅用于兼容迁移。

根据上下文按以下顺序判断:

  1. 用户提供视频用于主体或局部替换且未要求移除/替换原声时,锁定该 video track。
  2. 用户明确指定“锁定”“主音轨”“沿用原声”“不要重生成音频”时,使用其指定的 audio/video 轨。
  3. MV、音乐视频、歌词视频、卡点视频、舞蹈视频、按歌曲节拍或完整歌曲时长生成画面时,将歌曲/配乐主轨锁定。
  4. 旁白、播客或对白是视频时长与镜头节奏的唯一基准时,也可锁定该旁白主轨。
  5. 普通背景音乐、环境声、音效、角色参考音频或临时占位音频不自动视为主锁定音轨,除非用户语义表明它负责驱动生成。
  6. 已有一条锁定媒体轨且用户未要求更换时,优先保留;但仍要检查它是否与本次要生成的任务片段范围相交。

有多条音轨时先利用名称、文件名、素材时长、轨道内容和用户描述消歧。例如 Master Song、完整歌曲 通常优先于 SFX、环境声。如果仍有两条或更多合理候选,停止生成补丁并询问用户,至少列出每个候选的轨道 ID、名称、文件名和时间范围。不得按轨道顺序、第一条音轨或最长时长擅自决定。

锁定前还要检查:

  • 锁定轨至少包含一个与轨道类型一致的媒体片段:audio track 对应 media_type: "audio",video track 对应 media_type: "video";锁定视频原声时还要确认源视频确实包含音轨。
  • 锁定媒体片段应与本次每个目标 task segment 的 [start_frame, end_frame) 相交;不相交时,先调整时间线或询问用户。
  • 作为主音频使用时通常保持 muted: false。不要为了“锁定”而修改无关的 solo、音量或轨道编辑锁状态。
  • 如果上下文明确不需要保留任何原音频,应确保所有 audio/video track 的 audio_locked 为 false。

公用媒体

shared_reference 是任务图片项以及音频/视频片段 content 中的布尔字段。当多个上下文任务分段需要使用同一张图片、同一段音频或同一段视频作为参考时,将对应媒体设置为公用媒体;它不要求在时间线上与每个任务片段重叠。

{
  "id": "shared-audio-segment",
  "start_frame": 0,
  "end_frame": 120,
  "content": {
    "media_type": "audio",
    "source_type": "input",
    "file_path": "codex/voice/reference.wav",
    "file_name": "reference.wav",
    "shared_reference": true
  }
}

决策规则:

  • 用户说“设为公用媒体”“所有上下文分段都参考这张图/这段音频/这个视频”或表达相同语义时,标记其指定媒体;不要只因文件名相同就自动共享。
  • 任务图片的标记写在 content.images[] 项上,可以有多张公用图片;它们会排在每个任务的私有图片之前,公用和私有图片总数仍最多为 9。
  • 音频/视频的标记写在对应媒体片段 content 上,同一音频轨或视频轨最多一个;切换时把该轨其他片段显式设为 false。
  • 公用音频从源文件开头使用,最多 15 秒;公用视频使用该源视频作为各任务的参考视频。
  • 公用媒体是跨任务参考,不等于时间线原声复用。不要仅因为音频设为公用就同时设置 audio_locked;只有用户还要求原样保留音频并用它驱动时间线时,才分别评估 audio_locked。
  • 若用户既要某段音频/视频作为公用参考,又要它按普通时间线语义输出,应使用独立轨道或片段表达两个角色,并在交付摘要中说明。
  • speaker_reference 是旧版音频参考字段,只用于读取和迁移旧工作流;新建或更新工作流统一写 shared_reference。
  • 多个候选无法消歧时,列出媒体项或片段 ID、轨道名称、文件名、时长或帧范围,请用户指定;不要按第一项或最长片段选择。

自动编排决策

  • 用户给出明确镜头/片段长度时优先采用;否则按素材时长或提示词中的时间信息推导,并说明推导。
  • 主体或局部视频替换模式在用户未指定片段长度时,固定按 10 秒连续拆分 task segment,最后一段使用剩余时长。
  • “每段 N 秒”意味着连续片段 [0,N*fps)、[N*fps,2N*fps)……;不要在边界额外加 1 帧。
  • 将提示词放入对应 task segment;参考图放入该 task segment 的 images;主视频和音频放入各自 media track。
  • 对主体替换视频、MV 或其他主音频驱动项目,在完成时间线编排后锁定唯一的 audio/video 轨,并复核它覆盖目标任务范围。
  • 默认保留轨道间空隙。只有用户要求紧凑排列时才消除间隙并顺移后续片段。
  • 调整已有片段时尽量保留 segment ID;新建片段、轨道、图片项才生成新 UUID。

MultiTrack Project 参数

  • segment_start_number 为从 1 开始的任务片段编号;执行逻辑使用 segment_start_number - 1 转换为内部索引。
  • segment_count = -1 表示从起始索引处理到末尾;非负数限制本次任务片段数量。
  • project_save: new 或 override。在 override 且 count 为 -1 时,执行逻辑会删除起始索引之后的已保存片段再生成;修改前向用户清楚说明。
  • sampling_mode: single 或 dual;sampling_plan 必须是当前节点可用预设。不要仅凭另一份流程中的值假设当前环境支持。
  • context_frames(默认 "22",可选 "5" / "22" / "39" / "56")控制 Context / Context Swap 续接片段从上一段拷贝为延续上下文的视频帧数;取值必须落在 H3 时间潜空间网格(17k+5 帧)上,与 Moxie 上下文采样节点的选项一致。数值越大运动衔接越平滑,但每个续接片段会多生成等量帧(实际生成长度为 任务长度 + context_frames + 12,其中 12 帧为网格尾帧,解码后裁掉)。
  • Moxie MultiTrack Project(MoxieProject)同样暴露同一个 context_frames 下拉,位于 steps 与 seed 之间;该节点的其余采样设置仍保持隐藏(euler + beta sigmas 由 steps 推导)。
  • Moxie MultiTrack Project Slow(MoxieProjectSlow)是 Moxie 变体:参数与 Moxie MultiTrack Project 完全一致,但用潜空间放大替代 RTX VSR——隐藏的半分辨率一采之后,用 models/latent_upscale_models/ 下选定的潜空间放大模型把潜空间升到最终(编辑器)尺寸,再以 2 步 euler、0.33 denoise 的隐藏二采精修;片段按项目分辨率保存,Video Combine 的 RTX 还原会直接跳过。该节点在 audio_vae 之后新增 upscale_model 下拉(默认 minimax_h3_latent_upscaler_3d_fp16.safetensors,列出 models/latent_upscale_models/ 全部检查点);选 None 会直接报错,因为该节点始终走潜空间放大。旧工作流没有该控件时自动回落到默认检查点。二采默认启用自动空间分块(tile_count=0 表示按可用显存自动选择分块数、放得下则完全不分块),因此 1920x1080 输出在 12GB 显存及 AMD/Intel GPU 上也可运行;upscale_model 旁新增 tiling 开关(Boolean,默认 on)可整体关闭分块——关闭时引擎向二采注入 {"enabled_tiling":"false","tile_count":0},二采改走普通 SamplerCustomAdvanced 一体化采样;旧工作流没有该开关时保持分块开启。分块实现只用 ComfyUI 的设备无关显存接口,不含 CUDA 专属代码(AMD/Intel 机器上 Loader 的注意力后端应选 pytorch_attention,INT8 注意力仅支持 Nvidia/AMD)。
  • 编辑器分辨率是一采尺寸;dual 不会反算缩小一采。二采宽高分别为 round(编辑器尺寸 * upscale_by / 32) * 32,采用 Python round 就近对齐,恰好居中时取偶数,不是固定向上对齐。
  • 隐藏的半分辨率一采(单采样与 Moxie 变体)会对齐到偶数潜空间网格:先按 0.5 缩放,再取最近的 64px 整数倍(h3_even_latent_size)。原因:H3 视频 patch 覆盖 2x2 潜空间格子(32px 潜空间网格),非 64px 倍数的尺寸编码出的潜空间行/列数为奇数(如 540px → 17 行),采样本身可行,但作为下一片段的 Motion Context keyframes 回流时 patchify_video 无法 reshape,报 shape '[1, 24, 1, 1, 8, 2, 15, 2]' is invalid for input of size 12240。对齐结果:1920x1080 编辑器一采 960x512,1344x768 → 704x384,3840x2160 → 1920x1088(与 VAE 原本向上取整一致,4K 编辑器技巧行为不变)。二采与最终输出尺寸不受影响。
  • upscale_by 是 Project 的独立参数,默认 1.250,三位小数,步长 0.001;旧工作流保留已保存的值。两条放大路径及合并导出均使用放大并对齐后的尺寸。例如 1344 × 768、倍率 1.250 的二采为 1664 × 960。若用户指定最终输出尺寸,应同时核对编辑器尺寸与倍率,不能将编辑器尺寸直接当作双采样的最终尺寸。
  • 单采样、仅一采预览保持编辑器尺寸;upscale_by = 1.000 不放大但可二采;纯音频项目(32 × 32)不放大。旧版反算缩小尺寸的一采检查点和上下文潜空间应重新生成后再按新规则续跑。
  • 1st_pass_only 仅适用于显式的一阶段检查点流程;不要自动开启。

补丁 Plan

Plan 只包含实际变更。node_id 可省略并由拓扑定位;editor.resolution 是完整 DynamicCombo 设置,editor.track_data 是完整 TRACK_DATA。不要把整份节点或工作流放入 plan。

{
  "editor": {
    "resolution": {
      "resolution": "width x height (megapixels)",
      "aspect_ratio": "16:9 (Widescreen)",
      "megapixels": 0.9
    },
    "track_data": { "tracks": [], "total_length": 120, "frame_rate": 24 },
    "format": "MiniMax"
  },
  "project": {
    "project_save": "override",
    "segment_start_number": 1,
    "segment_count": -1,
    "context_frames": "22",
    "sampling_plan": "medium",
    "sampling_mode": "single"
  }
}