Skip to content

Shenrui-Ma/video-regen-recipes / templates/character-short/bit-by-bit-heartache

bit-by-bit-heartache

Verified

用角色参考图在本机制作 Heartache 连续动作配乐短片.

FileKindSize
.gitignoreother430 B
LICENSEother1.1 KB
LICENSES.mdmarkdown1.4 KB
README.mdmarkdown9.3 KB
SKILL.mdskill md7.3 KB
assets/README.mdmarkdown4.9 KB
assets/default/manifest.jsonconfig3.8 KB
assets/runtime-assets.jsonconfig5.5 KB
profile.jsonconfig3.8 KB
prompts/ref2va.template.txtmarkdown1.6 KB
prompts/yaoguang.historical.txtmarkdown5.0 KB
references/background-removal.mdmarkdown5.5 KB
references/changelog.mdmarkdown916 B
references/character-input.mdmarkdown4.7 KB
references/deployment.mdmarkdown4.9 KB
references/editing.mdmarkdown3.7 KB
references/environment.lock.jsonconfig1.5 KB
references/first-segment-validation.jsonconfig1.8 KB
references/generation.mdmarkdown3.8 KB
references/media-preflight.mdmarkdown4.2 KB
references/native-continuation.mdmarkdown17.8 KB
references/node-sources.jsonconfig6.7 KB
references/node-sources.mdmarkdown3.8 KB
references/package-verification.jsonconfig1.7 KB
references/reference-check.jsonconfig968 B
references/reproduction.mdmarkdown10.1 KB
references/validation.mdmarkdown2.6 KB
references/workflow-recovery.mdmarkdown2.2 KB
references/workflow.lock.jsonconfig1.2 KB
references/yaoguang-run.jsonconfig7.4 KB
scripts/character/prepare_character.pyscript6.5 KB
scripts/distribution/fetch_assets.pyscript5.8 KB
scripts/distribution/package_skill.pyscript5.6 KB
scripts/plan_segments.pyscript3.4 KB
scripts/prepare_driver.pyscript5.2 KB
scripts/render_default.pyscript5.5 KB
scripts/runtime/graphs.pyscript11.3 KB
scripts/runtime/heartache.pyscript14.6 KB
scripts/runtime/local_io.pyscript3.3 KB
scripts/runtime/media.pyscript13.2 KB
scripts/runtime/run_segment.pyscript13.3 KB
sources.mdmarkdown2.4 KB
tests/test_background_removal.pyscript2.6 KB
tests/test_character_input.pyscript12.2 KB
tests/test_default.pyscript879 B
tests/test_distribution.pyscript12.3 KB
tests/test_media_preflight.pyscript2.1 KB
tests/test_prepare_driver.pyscript1.9 KB
tests/test_release_review.pyscript1.7 KB
tests/test_reproduction.pyscript1.9 KB
tests/test_runtime_cli.pyscript11.3 KB
tests/test_runtime_graph.pyscript4.8 KB
tests/test_runtime_io.pyscript2.1 KB
tests/test_runtime_media.pyscript10.2 KB
tests/test_runtime_runner.pyscript1.6 KB
tests/test_segment_plan.pyscript3.4 KB
tests/test_skill_contract.pyscript1.6 KB
workflows/continue.editor.jsonconfig23.8 KB
workflows/first.editor.jsonconfig19.8 KB
workflows/node-schema.jsonconfig22.2 KB
workflows/provenance.jsonconfig911 B

references/native-continuation.md

View on GitHub
# 原生 AV latent 续接:参数语义与对照检查

> 历史来源记录:本页描述旧实现/回收阶段。新安装使用 [当前生成路径](generation.md)与[环境说明](https://github.com/Shenrui-Ma/shenrui-comfyui-toolkit/tree/667eafddb9f42bb6c72ad27b665def9ada36df45/environments/h3/README.md),不需要旧私有Save/Load/Trim节点。


本页补充 [generation.md](generation.md) 的续接规则,供 Issue #1 的社区复现者核对自己的实现。**这里只公开参数语义与当前回收源文件的 SHA-256,不发布节点实现,不保证其他同名节点行为一致。**“原生”在本页指直接使用前段联合视频/音频 latent 的路线,不表示这些自定义节点是官方内置节点。

证据是当前可读源码的静态检查:来源尚未完整固定,未固定包版本、上游 commit 或历史运行时版本;当前 SHA **不是历史生成 commit 的证明**。未执行这些源码、补丁自测或 GPU 采样。源码中的效果评价不作为本页的实测结论。

## 1. 两套接口必须分开

| 用途 | `HermesH3Continuation` 当前接口 | `h3_motion_context` 当前接口 |
| --- | --- | --- |
| 保存 | `SaveMiniMaxH3AVLatent` | `MiniMaxH3MotionContextSaveLatent` |
| 加载 | `LoadMiniMaxH3AVLatent` | `MiniMaxH3MotionContextLoadLatent` |
| 注入 | `ApplyMiniMaxH3MotionContext` | `MiniMaxH3MotionContext` |
| 解码后裁切 | `TrimMiniMaxH3MotionContext` | `MiniMaxH3MotionContextTrim` |

`generation.md` 的路线组合是左列 canonical Save/Load、右列 `MiniMaxH3MotionContext`、左列定长 Trim。不是选任意一列整套替换。类名相近不代表字段、返回值、裁切量或保存格式一致。

## 2. Canonical Save/Load 规则

证据:`HermesH3Continuation/__init__.py` 的 `_av`、`_pixel_frames`、`SaveMiniMaxH3AVLatent.save`、`LoadMiniMaxH3AVLatent.load`。

| 字段 | 精确语义 |
| --- | --- |
| `samples` | Comfy `LATENT` 字典,`samples["samples"]` 必须为包含恰好两个 tensor 的 `NestedTensor`,顺序 video、audio。不是 MP4,也不是普通单路 latent。 |
| video | 五维 `[B,24,Tv,Hl,Wl]`;`Hl/Wl` 是 latent 空间尺寸。 |
| audio | 四维 `[B,32,2,Ta]`;两路 batch 大小必须相同。 |
| 视频时间 | `P=(1,4,4,4,4)`;`F=sum(P[i mod 5], i=0..Tv-1)`。不是所有视频 token 都代表四帧。 |
| 音频时间 | 必须满足 `Ta=round(F/24*40)`。这里 40 是音频 latent 步/秒,不是音频采样率。 |
| `filename_prefix` | 相对 Comfy 输出目录的保存前缀;默认 `h3_latents/ComfyUI`,生成带计数器的 `.safetensors` 文件。 |
| `visible_frames` | 发布长度,默认 243,至少 1;只写 metadata,不裁 latent。 |
| `trim_frames` | 发布区间起点,默认 0,至少 0;只写 metadata,不裁 latent。 |
| `metadata_json` | 必须是 JSON object;键和值转为字符串。保留字段随后覆盖同名自定义字段。不要把私人运行信息直接写入公开产物。 |

文件恰好保存 `video`、`audio` 两个 tensor,detach、contiguous 后移到 CPU;不强制转换 dtype。metadata 保留字段均为字符串:

- `schema="minimax-h3-av-latent-v1"`
- `visible_frames=V`、`trim_frames=s`
- `context_end_frame=E=s+V`

发布区间为从零开始、右端不含的 `[s,E)`;要求 `s>=0`、`V>=1`、`E<=F`。**保存的是完整 canonical,而不是 `[s,E)` 的切片。**保存返回原 `samples`,另有 UI 文件信息。

Load 输入仅 `latent_path`,必须指向文件;它检查文件 tensor 键集合恰为 `{video,audio}`、上述 shape/AV 时间一致性、schema,以及 `1<=E<=F`。输出依次为 `samples`、排序后的 `metadata_json`、整数 `context_end_frame`。它重新构造 `NestedTensor`,不会把 metadata 塞进 conditioning,也不会裁 tensor。当前 Load 不重新验证 `E=trim_frames+visible_frames`;复现者应自行核对 metadata 的内部一致性。

### 另一套 Save/Load 不是相同 schema

`h3_motion_context/nodes.py` 的 Save 输入是 `latent, filename_prefix, clip_index`,返回路径字符串;metadata 为 `format="h3_motion_context_av_v1"`,没有上述发布区间规则。`clip_index>0` 保存固定槽位且会覆盖;0 使用运行计数器。Load 输入为 `latent_path, clip_index`:文件路径直接选该文件;目录索引 0 选最新文件,重试可能误选本段被拒结果;正索引匹配对应槽位。

该 Load 只要求存在 video/audio 键,不校验 canonical schema,返回 `{"samples": [video,audio]}` 普通列表,设计用途仅为 `context_latent`,不是可直接送解码器的 `NestedTensor`。因此“能读文件”不证明两套格式规则一致。续跑应固定前驱文件及其 SHA,而非只依赖“最新”。

## 3. `MiniMaxH3MotionContext`:物理尾端 → 新段头部

证据:`nodes.py` 的 `MiniMaxH3MotionContext.apply`、`_video_tail_from_latent`、`_step_offsets`、`_audio_tail_from_latent`。

必需输入为 `conditioning, vae, latent, context_length, audio_context_length`;`latent` 是本段目标 latent,前段完整 latent 接可选 `context_latent`。可选像素路线为 `context_frames` 及 `context_audio + audio_vae`。接了 `context_latent` 后,视频和音频都优先从它切取,忽略对应已解码输入;不会退回重编码来掩盖尺寸不匹配。输出只有 `conditioning, trim_frames`,不是目标 latent。

当前常量为 `ENCODE_MODE="video"`、`ANCHOR_MODE="head"`、`AUDIO_MODE="timeline"`、`CROP="disabled"`;不是任意安装都可在 UI 调整的字段。视频窗口提供 5、22、39、56 帧;可用帧不足或离散网格不匹配时存在向下选择逻辑,不能只看请求值,须检查实际返回 trim。

设前段有 `Tv` 个视频 token、物理帧数 `F`,视频窗口 `n=22`:

- `k=7` 个 token 恰好覆盖 22 帧,切片为 `video[:1,:,Tv-k:Tv]`,即只取首个 batch。
- 必须有足够 token,且 `(Tv-k) mod 5=0`,否则拒绝。合法 `17g+5` 帧对应 `5g+2` 个 token,确保这些尾窗口的周期相位相容。
- 源窗口为 **`[F-22,F)`,不是 `[E-22,E)`**。
- 每个 token 拆成一个 cond block,新段像素锚点依次为 **`0,1,5,9,13,17,18`**,覆盖 `[0,22)`;返回 `trim_frames=22`。
- 每块携带 `resolved_frame_index=0` 和真正位置 `motion_context_index=p`;由 layout patch 放到目标时间原点加 `(5/3)*p` 的位置。Ref2VA 的参考块会改变时间原点,不能一律以 text 长度代替目标原点。
- 当前源码保留头部范围以外的已有 keyframe(如 last-frame),丢弃会与头部冲突的已有锚点,并设置目标 `minimax_frame_count`。源与目标空间尺寸、通道数须匹配;这一路不提供多 batch 一致续接保证。

### `published-end` 在这里不生效

`MiniMaxH3MotionContext` 没有 `context_end_frame` 输入,也不读取 canonical metadata。Load 输出该数值,**不等于**下游使用它。按 `generation.md` 的时间账本,以完整前驱作为下一段 context 时:

| 前驱段 | canonical `F` | 发布 `[s,E)` | 下一段原生视频 context |
| --- | ---: | --- | --- |
| 1 | 158 | `[0,158)` | `[136,158)` |
| 2 | 192 | `[22,180)` | `[170,192)` |
| 3 | 175 | `[22,163)` | `[153,175)` |

后两行引用了未发布的物理尾部。不能在不改实现/输入的情况下,声称它锚定发布片段最后一帧;也不能把这些当前源码推导冒称历史执行追踪。

### `audio_context_length=24` 的精确映射

字段单位是 **24fps 下的像素帧时长**,与视频窗口独立;0 表示跟随视频 span,**不是关闭音频**。canonical 路线自动带音频,没有 `continue_audio` 开关。

```text
A = int(audio_context_length);若 A=0,则 A=span
r_requested = round(A / 24 * 40)
r = min(r_requested, Ta)
audio_slice = audio[:1, ..., Ta-r:Ta]
A=24 → 24/24=1 秒 → round(1*40)=40 个音频 latent 步
```

`round` 是源码的 Python 最近整数规则,不是向上取整;不要照 tooltip 的“widened”理解成 ceil。源音频不足则只取现有长度并告警;空窗口报错。

音频位置还有网格补偿,不可仅写“在第22帧结束”:设 `q=5/3`,`o=Ta-qF`。合法最近整数网格通常有 `o=0,±1/3`;若不满足 `-0.5<o<0.5`,当前源码告警并按 0 处理,而非拒绝。

```text
u = round(q*span + o)             # head 模式的目标音频结束坐标
motion_context_audio_end_frame = u/q
音频时间窗口 = [target_origin + u-r, target_origin + u)
```

音频以 `kind="audio"` reference 追加到 `minimax_refs`,再由 patch 移到上述目标时间线,保留原有 Ref2VA references。24帧音频窗口可以长于22帧视频窗口,不增加视频 trim。它取的是源音频物理尾端,并不从已发布音轨取尾。像素/解码音频路线会重编码尾音频且采用 `o=0`,不能与直接切 latent 视为逐值一致。

## 4. `ApplyMiniMaxH3MotionContext`:另一套端点语义

证据:`HermesH3Continuation/__init__.py` 的 `ApplyMiniMaxH3MotionContext.apply`、`_boundaries`。

| 项目 | 当前 Apply 行为 |
| --- | --- |
| 输入 | `positive, samples, context_samples, context_frames, continue_audio, audio_context_frames, context_end_frame`;默认分别涉及22帧视频、开启音频、24帧音频、端点1。端点须显式连接/设置。 |
| 源窗口 | `[E-C,E)`,`C=context_frames`;检查 `1<=C<=E<=F`,两端必须都在按 `(1,4,4,4,4)` 累加的视频 token 边界上。 |
| 头部预留 | `trim=ceil(C/17)*17`,`guide_start=trim-C`;`trim` 必须小于目标总帧数。 |
| 视频注入 | 一个 keyframe,`resolved_frame_index=guide_start`,latent 为该 token 区间;不是原生路线的逐 token 多块 marker 布局。 |
| 音频注入 | `a=min(audio_context_frames,C,trim)`;开启且 `a>0` 时,`audio_end=round(E/24*40)`,`audio_len=round(a/24*40)`,切 `[audio_end-audio_len,audio_end)` 放入该 keyframe 的 `audio_latent`。 |
| 输出 | 修改后的 positive、原目标 samples、trim。已有 keyframes 取自 positive 首项并追加;不采用原生路线的冲突锚点筛选。 |

**C=22 时,Apply 返回 trim=34、guide_start=12;音频参数24被截到22帧,得到37步,而不是40步。**这不能替代本模板的“实际裁22帧”路线。Apply 确实读取 E,但 token 边界不对齐会拒绝;仅在 metadata 写入 published-end 不能绕过这一限制。它不写两个 Motion Context marker,不安装下面的补丁,也不能假设补丁会自动替它修正中间锚点/Ref2VA payload。是否由所装 Comfy 原生支持这种 guide,需要另验。

## 5. 解码后 Trim:头尾与音频公式

两者都作用于已解码 `images` 与 `audio["waveform"]`,不修改 canonical latent。设 `N=images.shape[0]`、音频采样率 `sr`、帧率 `fps`。

| 行为 | `TrimMiniMaxH3MotionContext` | `MiniMaxH3MotionContextTrim` |
| --- | --- | --- |
| 字段 | 必需 `images,audio,trim_frames,visible_frames,fps` | 必需 `images,trim_frames`;可选 `audio,fps,match_tail` |
| 视频 | `s=int(trim_frames)`,`e=s+int(visible_frames)`,输出 `images[s:e]`;`N<e` 报错 | `n=max(0,int(trim_frames))`,输出 `images[n:]`;`n>=N` 报错 |
| 音频头 | `a=round(s/fps*sr)` | `cut=round(n/fps*sr)`,先取 `waveform[...,cut:]`;cut 耗尽音频时报错 |
| 音频尾 | `b=round(e/fps*sr)`,输出 `waveform[...,a:b]`;原音频不足 b 报错 | `match_tail=True`(默认):令 `want=round((N-n)/fps*sr)`,长则截到 want,短则尾部补零到 want |
| `match_tail=False` | **没有这个字段**,也没有补零逻辑 | 只裁音频头,保留剩余尾长,可能仍与视频时长不等 |
| 发布长度 | 同时定长选取 visible 区间 | 无 `visible_frames`,仅去头;需要另一显式 AV 定长裁切才能得到本模板的发布长度 |

左列音频样本数是 `round(e/fps*sr)-round(s/fps*sr)`,不可擅换成 `round((e-s)/fps*sr)`;分别四舍五入在部分参数下可相差一个样本。右列 match_tail 是裁去头以后按剩余帧数校尾,不是选择 source context 尾端的参数。

例:24fps、sr=32000、裁22帧,音频头切点是29333样本。模板第二段的定长 Trim 取视频 `[22,180)`,尾部12帧仍留在 canonical;192与158的差34不能统一当作头部 trim。`fps` 必须与解码视频及封装设置一致,不能用音频 latent 的40Hz替代。

## 6. 配套 patch 与注册入口要求

- `nodes.py` 通过相对导入使用 `patch_layout.py` 和 `patch_payload.py`,不能只复制一个同名类文件。layout 在首次调用时经 `_ensure_layout_patch` 安装;带音频时会经 `_ensure_payload_patch` 安装 payload patch。**导入成功或节点显示出来,不证明补丁已生效。**
- `patch_layout.py` 的 `_fixup` 将带 `motion_context_index` 的视频 cond 放到正确目标位置;`_fixup_audio` 根据 segment 表只平移带 `motion_context_audio_end_frame` 的音频 reference。音频标记块要求恰好一个,其 stereo rows 数量应为 `2*r`,不能移动所有音频 reference。
- `patch_payload.py` 的 `_patched_extra_conds` 在 keyframes 与 refs 共存且有上述 marker 时,将视频 payload 按“keyframe视频、reference视频”顺序拼接,音频同理,避免 refs 覆盖 keyframe 内容。未带 marker 的 Apply 不触发该修复分支。layout 有位置而 payload 无内容仍会失败。
- 两个 marker 字符串是节点/两补丁共享的接口,不能独立改名。layout patch 探测 `PackedLayout.__init__` 是否接受 `frame_count`,而不是仅相信版本字符串;源码注释提及不同 Comfy 版本,不代表本页已固定或验证那些版本。
- 补丁包含重复/其他包装器检测。遇到另一副本时可能让先加载的副本接管;因此 `is_applied=True` 仍不能证明正在用这里的 SHA。检查真正生效的函数来源;不要叠装多个副本或仅靠重命名文件夹禁用。
- 注册入口补查:现已从安装目录取回原生包的 `__init__.py`,核对其上游为 NikoDemon80/ComfyUI-H3-Motion-Context,详见[完整来源与版本边界](node-sources.md)。旧缓存目录缺入口不等于无法恢复完整包。当前安装含本地修改且不是历史版本锁;仍须在目标实例核对 `/object_info` 的真实 API 类名与字段。

## 7. 社区复现者对照清单

以下是可逐项操作的检查,不是声称读者已安装相同实现;不要导入来源不明的 Python 文件来“只查字段”。

- [ ] 对自己安装的四个逻辑文件计算 SHA-256(例如在已确认的对应包目录执行 `shasum -a 256 __init__.py`,或 `shasum -a 256 nodes.py patch_layout.py patch_payload.py`)。记录实际包版本/commit;不匹配时按实际源码重新审查,不能只对齐节点名称。
- [ ] 在自己的 Comfy 实例读取 `/object_info`,核对 Save/Load、Motion Context、Trim 的 API 类名、字段及返回顺序。检查包顶层注册和补丁实际加载来源;检查首次调用日志中的失败/重复副本提示。
- [ ] 用自己信任的 safetensors 读取器在 CPU 查看 tensor keys、shape、dtype、metadata:确认两路 batch、24视频通道、32×2音频通道以及 `Ta=round(F/24*40)`。另验 `[s,E)` 与 `E=s+V`;保留前驱文件 SHA。不要把普通列表 Load 输出接解码器。
- [ ] 检查实际提交图:前驱完整 canonical 接 `context_latent`;目标 `latent` 与 conditioning 属于同一目标长度/画布。原生路线不应伪接 `context_end_frame`;如选 Apply,应将其作为不同实验,显式设置 E 并验证 token 边界。
- [ ] 对22帧原生窗口核对7个源 token、起点周期相位0、目标锚点 `0,1,5,9,13,17,18` 和返回 trim22;音频24帧核对40步及补偿后的结束坐标。若是 Apply,应核对 trim34、guide_start12、音频37步,不得把两份日志称为同一参数运行。
- [ ] 在 layout/payload 检查中确认原有 Ref2VA references 保留、只有标记音频块被移位、视频和音频 payload 顺序与 segments 一致。相同 seed 或 metadata 不代替此项。此检查需要受信实现的诊断能力;本页不提供可冒充验证结果的实现代码。
- [ ] 同时保留 canonical 解码与发布 AV,按第五节公式计算帧区间和音频样本区间。可用 `ffprobe -v error -count_frames -show_streams -of json clip.mp4` 核对实际帧数/帧率/音轨;容器时长或有损音频编码后的包时长不是精确 waveform 样本数,后者应在封装前另记。
- [ ] 自行完成一次受控续接及边界试听/观看,记录真实图、版本、模型/输入/输出 SHA、源窗口、trim 和音频长度。技术形状相容不证明人物、动作或声音连续;公开记录前移除私人路径及运行标识。

## 8. 当前源证据与未决项

下面是本次对当前回收文件实际计算的 SHA-256。逻辑文件名用于定位语义,不表示可从某个已固定公开包下载相同字节。

| 逻辑文件名 | 定位入口 | 当前 SHA-256 |
| --- | --- | --- |
| `HermesH3Continuation/__init__.py` | `_av`;Save/Load/Apply/Trim 四类;`NODE_CLASS_MAPPINGS` | `edf270a641808282f5d3ff51a260518821a59ad1dffcd27e23e6f6794787c573` |
| `h3_motion_context/nodes.py` | `MiniMaxH3MotionContext.apply`;尾窗口 helpers;另一套 Trim/Save/Load;`NODE_CLASS_MAPPINGS` | `a55a99aeb9c223e33e7adf2f6ae456726903db07e61e08418aa7e62ea9d9cc97` |
| `h3_motion_context/patch_layout.py` | `_fixup`、`_fixup_audio`、`_target_origin`、`apply_patch` | `302b13b42bc6d9440e54d8030a22828a5f8b84b10c9c6727cdfcac583c6a6840` |
| `h3_motion_context/patch_payload.py` | `_patched_extra_conds`、`apply_patch` | `0b05b6ac154044bd4abad7ac7236a3bd9b1e9c887a74170f9bf44e182a07ce49` |

尚未解决:源包来源与许可链、可公开分发的固定版本、右列包顶层入口、历史运行源码与当前文件的对应关系、历史 Comfy/模型环境锁,以及读者环境的真实运行验证。本页提供精确语义作为复现对照,不以当前源码倒填历史证据,也不以文档替代安装器或端到端复现结果。
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall