Upload 24 files

custom_nodes/ComfyUI-H3-Motion-Context-main/.comfyignore

@@ -0,0 +1,9 @@
+# Caches and local env only. tests/ ships with the pack (smoke test,
+# seam/level/freeze probes, mock harness). Do not blanket-ignore it.
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+.git/
+.github/
+.cursor/

custom_nodes/ComfyUI-H3-Motion-Context-main/.gitignore

@@ -0,0 +1,2 @@
+__pycache__/
+*.pyc

custom_nodes/ComfyUI-H3-Motion-Context-main/CHANGELOG.md

@@ -0,0 +1,171 @@
+# Changelog
+
+Newest first. Dates are release dates.
+
+ComfyUI's H3 layout changed shape once so far: `PackedLayout.__init__`
+dropped its `frame_count` parameter along with the restriction that
+rejected any keyframe anchor other than the first or last frame. That
+landed in ComfyUI 0.34.0. Every release through 0.33.4 has the older
+layout. Each entry below says which of the two it works with.
+
+## 0.6.2 - 2026-09-06
+
+Requires ComfyUI 0.34.0 or newer. Use 0.3.1 on anything older.
+
+- Chain `segments` treats a blank value as 0. Graphs saved when the
+  button row was the only widget stored `""` there; after `segments` was
+  added that empty string failed INT validation.
+- Example workflow: both Chain nodes (fl2va and ref2va) now store
+  `segments` 0 instead of that leftover blank.
+
+## 0.6.1 - 2026-09-05
+
+Requires ComfyUI 0.34.0 or newer. Use 0.3.1 on anything older.
+
+- The mock harness no longer uses `importlib.import_module` (that YARA
+  hit flagged 0.5.x/0.6.0). `tests/` still ships, including the smoke
+  test, seam probe, freeze detect, and level step.
+- Clear latents and slot-exists POST routes require Origin to match Host
+  (CSRF). Latent paths must stay inside ComfyUI's output folder.
+
+## 0.6.0 - 2026-09-03
+
+Requires ComfyUI 0.34.0 or newer. Use 0.3.1 on anything older.
+
+- Chain is Approve on a loop: it advances Load/Save, then queues, then
+  keeps going. At Load 0 / Save 1 with no clip 1 on disk it generates
+  that first clip instead of walking into a missing file. `segments` is
+  how many clips that loop runs (0 = until Stop). Reset sets 0/1 and
+  does not delete files. Clear latents deletes numbered chain slots;
+  custom filenames are left alone.
+
+## 0.5.1 - 2026-09-02
+
+Requires ComfyUI 0.34.0 or newer. Use 0.3.1 on anything older.
+
+- Example workflow updated.
+
+## 0.5.0 - 2026-09-02
+
+Requires ComfyUI 0.34.0 or newer. Use 0.3.1 on anything older.
+
+#25 by feigo313 is why Load 0 is first-clip/no-context, so Motion Context
+stays enabled from the first clip, and why the Chain node exists: walking
+those indices with run-on-change queues twice and skips slots.
+
+- Load Latent `clip_index` 0 is first-clip/no-context: nothing is read,
+  Motion Context passes the original conditioning through, and
+  `trim_frames` is 0. Leave the node enabled. The chain is Load 0 / Save 1,
+  then Load 1 / Save 2. Positive indices still load that exact slot.
+  The old load-newest meaning of index 0 is gone.
+- H3 Motion Context Chain node: Approve advances Load/Save then queues
+  once, Run/Re-roll repeats the current slot (use it instead of
+  ComfyUI's Run), Chain auto-approves from the current indices, Reset
+  sets 0/1 without queuing. Load, Save, and Chain must share one canvas
+  group or the buttons do nothing. Button clicks do not open the node
+  menu. Do not use queue "run on change" to walk indices.
+- Save Latent can overwrite a slot that Load still has memory-mapped on
+  Windows (os error 1224). Load copies tensors off the file first, and
+  Save writes through a temp file.
+
+## 0.4.0 - 2026-08-26
+
+Requires ComfyUI 0.34.0 or newer. Use 0.3.1 on anything older.
+
+ComfyUI now places keyframe anchors at any frame itself, so the two
+runtime patches this pack carried are gone. Nothing in ComfyUI is
+modified any more.
+
+- `patch_layout.py` and `patch_payload.py` removed. The node builds plain
+  keyframe dicts and hands them to stock code.
+- `layout_contract.py` added. It proves, once before the first render,
+  that anchors sit where the arithmetic says and that the pinned audio
+  window is placed literally from a fractional, negative anchor index.
+  No stock node can produce such an index, so nothing upstream tests it,
+  and an integer cast added later would move the pinned sound silently.
+  If a check fails the node refuses and names what moved.
+- The pinned audio is a keyframe rather than a reference block. A Ref2VA
+  graph's reference list is left untouched.
+- Add Guide for MiniMax H3 anchors survive alongside a chained head,
+  including ones carrying their own audio. Guides landing inside the
+  pinned head are dropped with a warning, as `first_frame` anchors are.
+- Other packs may patch the layout without this one standing down, since
+  it no longer competes for that code. If it finds the constructor
+  wrapped it says who by and checks the behaviour anyway.
+- Anchor and audio window coordinates are identical to 0.3.1, verified
+  against the real upstream layout on both shapes.
+
+## 0.3.1 - 2026-08-14
+
+Works with both H3 layouts.
+
+Fixed the crash on the newer layout, reported in #12 by javawock7618 and
+#8 by azra1l. The patch had passed `frame_count` unconditionally, so its
+self-test raised `TypeError` and the node refused to run.
+
+- The patch reads the layout constructor's signature and adapts, rather
+  than assuming either shape. Verified against the real upstream file on
+  both: identical anchor and audio window coordinates to the last bit.
+- Keyframe audio latents are no longer dropped from the payload. The
+  newer layout lets a keyframe carry audio of its own, and rebuilding the
+  list from references alone filled every audio conditioning row with the
+  wrong content.
+- Pinned anchors pair with the correct rows when a stock anchor that
+  carries audio but no picture shares the graph.
+- The mixed keyframe guard is retired on the newer layout, where stock
+  compensates untagged keyframes for reference blocks itself. A Ref2VA
+  graph carrying a stock anchor is now supported rather than refused.
+- The test harness fakes both layout shapes.
+
+## 0.3.0 - 2026-08-11
+
+Works with the older H3 layout only. Refuses to run on the newer one.
+
+- **Seam Probe node.** Measures join quality inline in the graph: lag,
+  correlation, RMS step and floor level step across the join. Passes
+  clip B through unchanged so it can sit inline without rewiring.
+- **last_frame passthrough.** An fl2va graph's own anchors used to be
+  replaced outright. A last-frame anchor now survives a chained head,
+  tagged so it gets the same reference compensation as the pinned run.
+  Anchors falling inside the pinned head are dropped with a warning,
+  since the pinned run already decides those frames.
+- Conditioning carrying keyframes resolved against a different clip
+  length is refused rather than rendered at the wrong frame.
+
+## 0.2.0 - 2026-08-09
+
+Works with the older H3 layout only. First release published to the
+ComfyUI registry.
+
+- **Reference mode support.** `patch_layout.py` was rewritten to locate
+  reference blocks by segment table rather than by recomputing cursor
+  arithmetic, which made multiple reference blocks work cleanly. Ref2VA
+  graphs can carry their own image, video and audio references alongside
+  a chained head.
+- **Latent picture path.** The pinned run is sliced straight out of the
+  previous clip's latent, skipping the decode and re-encode round trip
+  that dulls the picture a little more at every link.
+- **Patches install on first use, not at import.** Having the pack in
+  `custom_nodes` now changes nothing until a Motion Context node
+  actually runs.
+- **Coexistence detection.** A second copy of the patch, vendored into
+  another pack, recognises the first and stands down instead of
+  wrapping it.
+- The payload patch is gated on this pack's own markers, so unrelated H3
+  graphs stay bit-identical to stock.
+- Two settings exposed; everything with only one correct answer was
+  removed from the UI.
+- `freeze_detect.py` and `level_step.py` added to the measurement
+  scripts.
+- The example workflow was replaced with an fl2va / ref2va one.
+
+## Initial release - 2026-08-06
+
+Works with the older H3 layout only. Not published to the registry; no
+version number, as `pyproject.toml` came later.
+
+Clip chaining for MiniMax H3 with audio continuation rather than
+imitation. Four nodes: Motion Context, Trim, Save Latent, Load Latent.
+The pinned audio window is placed so it ends at the join and reaches
+backwards, which is what makes the model continue a soundtrack instead
+of starting something that merely resembles it.

custom_nodes/ComfyUI-H3-Motion-Context-main/LICENSE

@@ -0,0 +1,234 @@
+Copyright (C) 2026 NikoDemon80
+
+GNU GENERAL PUBLIC LICENSE
+Version 3, 29 June 2007
+
+Copyright © 2007 Free Software Foundation, Inc. <https://fsf.org/>
+
+Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.
+
+Preamble
+
+The GNU General Public License is a free, copyleft license for software and other kinds of works.
+
+The licenses for most software and other practical works are designed to take away your freedom to share and change the works. By contrast, the GNU General Public License is intended to guarantee your freedom to share and change all versions of a program--to make sure it remains free software for all its users. We, the Free Software Foundation, use the GNU General Public License for most of our software; it applies also to any other work released this way by its authors. You can apply it to your programs, too.
+
+When we speak of free software, we are referring to freedom, not price. Our General Public Licenses are designed to make sure that you have the freedom to distribute copies of free software (and charge for them if you wish), that you receive source code or can get it if you want it, that you can change the software or use pieces of it in new free programs, and that you know you can do these things.
+
+To protect your rights, we need to prevent others from denying you these rights or asking you to surrender the rights. Therefore, you have certain responsibilities if you distribute copies of the software, or if you modify it: responsibilities to respect the freedom of others.
+
+For example, if you distribute copies of such a program, whether gratis or for a fee, you must pass on to the recipients the same freedoms that you received. You must make sure that they, too, receive or can get the source code. And you must show them these terms so they know their rights.
+
+Developers that use the GNU GPL protect your rights with two steps: (1) assert copyright on the software, and (2) offer you this License giving you legal permission to copy, distribute and/or modify it.
+
+For the developers' and authors' protection, the GPL clearly explains that there is no warranty for this free software. For both users' and authors' sake, the GPL requires that modified versions be marked as changed, so that their problems will not be attributed erroneously to authors of previous versions.
+
+Some devices are designed to deny users access to install or run modified versions of the software inside them, although the manufacturer can do so. This is fundamentally incompatible with the aim of protecting users' freedom to change the software. The systematic pattern of such abuse occurs in the area of products for individuals to use, which is precisely where it is most unacceptable. Therefore, we have designed this version of the GPL to prohibit the practice for those products. If such problems arise substantially in other domains, we stand ready to extend this provision to those domains in future versions of the GPL, as needed to protect the freedom of users.
+
+Finally, every program is threatened constantly by software patents. States should not allow patents to restrict development and use of software on general-purpose computers, but in those that do, we wish to avoid the special danger that patents applied to a free program could make it effectively proprietary. To prevent this, the GPL assures that patents cannot be used to render the program non-free.
+
+The precise terms and conditions for copying, distribution and modification follow.
+
+TERMS AND CONDITIONS
+
+0. Definitions.
+
+“This License” refers to version 3 of the GNU General Public License.
+
+“Copyright” also means copyright-like laws that apply to other kinds of works, such as semiconductor masks.
+
+“The Program” refers to any copyrightable work licensed under this License. Each licensee is addressed as “you”. “Licensees” and “recipients” may be individuals or organizations.
+
+To “modify” a work means to copy from or adapt all or part of the work in a fashion requiring copyright permission, other than the making of an exact copy. The resulting work is called a “modified version” of the earlier work or a work “based on” the earlier work.
+
+A “covered work” means either the unmodified Program or a work based on the Program.
+
+To “propagate” a work means to do anything with it that, without permission, would make you directly or secondarily liable for infringement under applicable copyright law, except executing it on a computer or modifying a private copy. Propagation includes copying, distribution (with or without modification), making available to the public, and in some countries other activities as well.
+
+To “convey” a work means any kind of propagation that enables other parties to make or receive copies. Mere interaction with a user through a computer network, with no transfer of a copy, is not conveying.
+
+An interactive user interface displays “Appropriate Legal Notices” to the extent that it includes a convenient and prominently visible feature that (1) displays an appropriate copyright notice, and (2) tells the user that there is no warranty for the work (except to the extent that warranties are provided), that licensees may convey the work under this License, and how to view a copy of this License. If the interface presents a list of user commands or options, such as a menu, a prominent item in the list meets this criterion.
+
+1. Source Code.
+The “source code” for a work means the preferred form of the work for making modifications to it. “Object code” means any non-source form of a work.
+
+A “Standard Interface” means an interface that either is an official standard defined by a recognized standards body, or, in the case of interfaces specified for a particular programming language, one that is widely used among developers working in that language.
+
+The “System Libraries” of an executable work include anything, other than the work as a whole, that (a) is included in the normal form of packaging a Major Component, but which is not part of that Major Component, and (b) serves only to enable use of the work with that Major Component, or to implement a Standard Interface for which an implementation is available to the public in source code form. A “Major Component”, in this context, means a major essential component (kernel, window system, and so on) of the specific operating system (if any) on which the executable work runs, or a compiler used to produce the work, or an object code interpreter used to run it.
+
+The “Corresponding Source” for a work in object code form means all the source code needed to generate, install, and (for an executable work) run the object code and to modify the work, including scripts to control those activities. However, it does not include the work's System Libraries, or general-purpose tools or generally available free programs which are used unmodified in performing those activities but which are not part of the work. For example, Corresponding Source includes interface definition files associated with source files for the work, and the source code for shared libraries and dynamically linked subprograms that the work is specifically designed to require, such as by intimate data communication or control flow between those subprograms and other parts of the work.
+
+The Corresponding Source need not include anything that users can regenerate automatically from other parts of the Corresponding Source.
+
+The Corresponding Source for a work in source code form is that same work.
+
+2. Basic Permissions.
+All rights granted under this License are granted for the term of copyright on the Program, and are irrevocable provided the stated conditions are met. This License explicitly affirms your unlimited permission to run the unmodified Program. The output from running a covered work is covered by this License only if the output, given its content, constitutes a covered work. This License acknowledges your rights of fair use or other equivalent, as provided by copyright law.
+
+You may make, run and propagate covered works that you do not convey, without conditions so long as your license otherwise remains in force. You may convey covered works to others for the sole purpose of having them make modifications exclusively for you, or provide you with facilities for running those works, provided that you comply with the terms of this License in conveying all material for which you do not control copyright. Those thus making or running the covered works for you must do so exclusively on your behalf, under your direction and control, on terms that prohibit them from making any copies of your copyrighted material outside their relationship with you.
+
+Conveying under any other circumstances is permitted solely under the conditions stated below. Sublicensing is not allowed; section 10 makes it unnecessary.
+
+3. Protecting Users' Legal Rights From Anti-Circumvention Law.
+No covered work shall be deemed part of an effective technological measure under any applicable law fulfilling obligations under article 11 of the WIPO copyright treaty adopted on 20 December 1996, or similar laws prohibiting or restricting circumvention of such measures.
+
+When you convey a covered work, you waive any legal power to forbid circumvention of technological measures to the extent such circumvention is effected by exercising rights under this License with respect to the covered work, and you disclaim any intention to limit operation or modification of the work as a means of enforcing, against the work's users, your or third parties' legal rights to forbid circumvention of technological measures.
+
+4. Conveying Verbatim Copies.
+You may convey verbatim copies of the Program's source code as you receive it, in any medium, provided that you conspicuously and appropriately publish on each copy an appropriate copyright notice; keep intact all notices stating that this License and any non-permissive terms added in accord with section 7 apply to the code; keep intact all notices of the absence of any warranty; and give all recipients a copy of this License along with the Program.
+
+You may charge any price or no price for each copy that you convey, and you may offer support or warranty protection for a fee.
+
+5. Conveying Modified Source Versions.
+You may convey a work based on the Program, or the modifications to produce it from the Program, in the form of source code under the terms of section 4, provided that you also meet all of these conditions:
+
+     a) The work must carry prominent notices stating that you modified it, and giving a relevant date.
+
+     b) The work must carry prominent notices stating that it is released under this License and any conditions added under section 7. This requirement modifies the requirement in section 4 to “keep intact all notices”.
+
+     c) You must license the entire work, as a whole, under this License to anyone who comes into possession of a copy. This License will therefore apply, along with any applicable section 7 additional terms, to the whole of the work, and all its parts, regardless of how they are packaged. This License gives no permission to license the work in any other way, but it does not invalidate such permission if you have separately received it.
+
+     d) If the work has interactive user interfaces, each must display Appropriate Legal Notices; however, if the Program has interactive interfaces that do not display Appropriate Legal Notices, your work need not make them do so.
+
+A compilation of a covered work with other separate and independent works, which are not by their nature extensions of the covered work, and which are not combined with it such as to form a larger program, in or on a volume of a storage or distribution medium, is called an “aggregate” if the compilation and its resulting copyright are not used to limit the access or legal rights of the compilation's users beyond what the individual works permit. Inclusion of a covered work in an aggregate does not cause this License to apply to the other parts of the aggregate.
+
+6. Conveying Non-Source Forms.
+You may convey a covered work in object code form under the terms of sections 4 and 5, provided that you also convey the machine-readable Corresponding Source under the terms of this License, in one of these ways:
+
+     a) Convey the object code in, or embodied in, a physical product (including a physical distribution medium), accompanied by the Corresponding Source fixed on a durable physical medium customarily used for software interchange.
+
+     b) Convey the object code in, or embodied in, a physical product (including a physical distribution medium), accompanied by a written offer, valid for at least three years and valid for as long as you offer spare parts or customer support for that product model, to give anyone who possesses the object code either (1) a copy of the Corresponding Source for all the software in the product that is covered by this License, on a durable physical medium customarily used for software interchange, for a price no more than your reasonable cost of physically performing this conveying of source, or (2) access to copy the Corresponding Source from a network server at no charge.
+
+     c) Convey individual copies of the object code with a copy of the written offer to provide the Corresponding Source. This alternative is allowed only occasionally and noncommercially, and only if you received the object code with such an offer, in accord with subsection 6b.
+
+     d) Convey the object code by offering access from a designated place (gratis or for a charge), and offer equivalent access to the Corresponding Source in the same way through the same place at no further charge. You need not require recipients to copy the Corresponding Source along with the object code. If the place to copy the object code is a network server, the Corresponding Source may be on a different server (operated by you or a third party) that supports equivalent copying facilities, provided you maintain clear directions next to the object code saying where to find the Corresponding Source. Regardless of what server hosts the Corresponding Source, you remain obligated to ensure that it is available for as long as needed to satisfy these requirements.
+
+     e) Convey the object code using peer-to-peer transmission, provided you inform other peers where the object code and Corresponding Source of the work are being offered to the general public at no charge under subsection 6d.
+
+A separable portion of the object code, whose source code is excluded from the Corresponding Source as a System Library, need not be included in conveying the object code work.
+
+A “User Product” is either (1) a “consumer product”, which means any tangible personal property which is normally used for personal, family, or household purposes, or (2) anything designed or sold for incorporation into a dwelling. In determining whether a product is a consumer product, doubtful cases shall be resolved in favor of coverage. For a particular product received by a particular user, “normally used” refers to a typical or common use of that class of product, regardless of the status of the particular user or of the way in which the particular user actually uses, or expects or is expected to use, the product. A product is a consumer product regardless of whether the product has substantial commercial, industrial or non-consumer uses, unless such uses represent the only significant mode of use of the product.
+
+“Installation Information” for a User Product means any methods, procedures, authorization keys, or other information required to install and execute modified versions of a covered work in that User Product from a modified version of its Corresponding Source. The information must suffice to ensure that the continued functioning of the modified object code is in no case prevented or interfered with solely because modification has been made.
+
+If you convey an object code work under this section in, or with, or specifically for use in, a User Product, and the conveying occurs as part of a transaction in which the right of possession and use of the User Product is transferred to the recipient in perpetuity or for a fixed term (regardless of how the transaction is characterized), the Corresponding Source conveyed under this section must be accompanied by the Installation Information. But this requirement does not apply if neither you nor any third party retains the ability to install modified object code on the User Product (for example, the work has been installed in ROM).
+
+The requirement to provide Installation Information does not include a requirement to continue to provide support service, warranty, or updates for a work that has been modified or installed by the recipient, or for the User Product in which it has been modified or installed. Access to a network may be denied when the modification itself materially and adversely affects the operation of the network or violates the rules and protocols for communication across the network.
+
+Corresponding Source conveyed, and Installation Information provided, in accord with this section must be in a format that is publicly documented (and with an implementation available to the public in source code form), and must require no special password or key for unpacking, reading or copying.
+
+7. Additional Terms.
+“Additional permissions” are terms that supplement the terms of this License by making exceptions from one or more of its conditions. Additional permissions that are applicable to the entire Program shall be treated as though they were included in this License, to the extent that they are valid under applicable law. If additional permissions apply only to part of the Program, that part may be used separately under those permissions, but the entire Program remains governed by this License without regard to the additional permissions.
+
+When you convey a copy of a covered work, you may at your option remove any additional permissions from that copy, or from any part of it. (Additional permissions may be written to require their own removal in certain cases when you modify the work.) You may place additional permissions on material, added by you to a covered work, for which you have or can give appropriate copyright permission.
+
+Notwithstanding any other provision of this License, for material you add to a covered work, you may (if authorized by the copyright holders of that material) supplement the terms of this License with terms:
+
+     a) Disclaiming warranty or limiting liability differently from the terms of sections 15 and 16 of this License; or
+
+     b) Requiring preservation of specified reasonable legal notices or author attributions in that material or in the Appropriate Legal Notices displayed by works containing it; or
+
+     c) Prohibiting misrepresentation of the origin of that material, or requiring that modified versions of such material be marked in reasonable ways as different from the original version; or
+
+     d) Limiting the use for publicity purposes of names of licensors or authors of the material; or
+
+     e) Declining to grant rights under trademark law for use of some trade names, trademarks, or service marks; or
+
+     f) Requiring indemnification of licensors and authors of that material by anyone who conveys the material (or modified versions of it) with contractual assumptions of liability to the recipient, for any liability that these contractual assumptions directly impose on those licensors and authors.
+
+All other non-permissive additional terms are considered “further restrictions” within the meaning of section 10. If the Program as you received it, or any part of it, contains a notice stating that it is governed by this License along with a term that is a further restriction, you may remove that term. If a license document contains a further restriction but permits relicensing or conveying under this License, you may add to a covered work material governed by the terms of that license document, provided that the further restriction does not survive such relicensing or conveying.
+
+If you add terms to a covered work in accord with this section, you must place, in the relevant source files, a statement of the additional terms that apply to those files, or a notice indicating where to find the applicable terms.
+
+Additional terms, permissive or non-permissive, may be stated in the form of a separately written license, or stated as exceptions; the above requirements apply either way.
+
+8. Termination.
+You may not propagate or modify a covered work except as expressly provided under this License. Any attempt otherwise to propagate or modify it is void, and will automatically terminate your rights under this License (including any patent licenses granted under the third paragraph of section 11).
+
+However, if you cease all violation of this License, then your license from a particular copyright holder is reinstated (a) provisionally, unless and until the copyright holder explicitly and finally terminates your license, and (b) permanently, if the copyright holder fails to notify you of the violation by some reasonable means prior to 60 days after the cessation.
+
+Moreover, your license from a particular copyright holder is reinstated permanently if the copyright holder notifies you of the violation by some reasonable means, this is the first time you have received notice of violation of this License (for any work) from that copyright holder, and you cure the violation prior to 30 days after your receipt of the notice.
+
+Termination of your rights under this section does not terminate the licenses of parties who have received copies or rights from you under this License. If your rights have been terminated and not permanently reinstated, you do not qualify to receive new licenses for the same material under section 10.
+
+9. Acceptance Not Required for Having Copies.
+You are not required to accept this License in order to receive or run a copy of the Program. Ancillary propagation of a covered work occurring solely as a consequence of using peer-to-peer transmission to receive a copy likewise does not require acceptance. However, nothing other than this License grants you permission to propagate or modify any covered work. These actions infringe copyright if you do not accept this License. Therefore, by modifying or propagating a covered work, you indicate your acceptance of this License to do so.
+
+10. Automatic Licensing of Downstream Recipients.
+Each time you convey a covered work, the recipient automatically receives a license from the original licensors, to run, modify and propagate that work, subject to this License. You are not responsible for enforcing compliance by third parties with this License.
+
+An “entity transaction” is a transaction transferring control of an organization, or substantially all assets of one, or subdividing an organization, or merging organizations. If propagation of a covered work results from an entity transaction, each party to that transaction who receives a copy of the work also receives whatever licenses to the work the party's predecessor in interest had or could give under the previous paragraph, plus a right to possession of the Corresponding Source of the work from the predecessor in interest, if the predecessor has it or can get it with reasonable efforts.
+
+You may not impose any further restrictions on the exercise of the rights granted or affirmed under this License. For example, you may not impose a license fee, royalty, or other charge for exercise of rights granted under this License, and you may not initiate litigation (including a cross-claim or counterclaim in a lawsuit) alleging that any patent claim is infringed by making, using, selling, offering for sale, or importing the Program or any portion of it.
+
+11. Patents.
+A “contributor” is a copyright holder who authorizes use under this License of the Program or a work on which the Program is based. The work thus licensed is called the contributor's “contributor version”.
+
+A contributor's “essential patent claims” are all patent claims owned or controlled by the contributor, whether already acquired or hereafter acquired, that would be infringed by some manner, permitted by this License, of making, using, or selling its contributor version, but do not include claims that would be infringed only as a consequence of further modification of the contributor version. For purposes of this definition, “control” includes the right to grant patent sublicenses in a manner consistent with the requirements of this License.
+
+Each contributor grants you a non-exclusive, worldwide, royalty-free patent license under the contributor's essential patent claims, to make, use, sell, offer for sale, import and otherwise run, modify and propagate the contents of its contributor version.
+
+In the following three paragraphs, a “patent license” is any express agreement or commitment, however denominated, not to enforce a patent (such as an express permission to practice a patent or covenant not to sue for patent infringement). To “grant” such a patent license to a party means to make such an agreement or commitment not to enforce a patent against the party.
+
+If you convey a covered work, knowingly relying on a patent license, and the Corresponding Source of the work is not available for anyone to copy, free of charge and under the terms of this License, through a publicly available network server or other readily accessible means, then you must either (1) cause the Corresponding Source to be so available, or (2) arrange to deprive yourself of the benefit of the patent license for this particular work, or (3) arrange, in a manner consistent with the requirements of this License, to extend the patent license to downstream recipients. “Knowingly relying” means you have actual knowledge that, but for the patent license, your conveying the covered work in a country, or your recipient's use of the covered work in a country, would infringe one or more identifiable patents in that country that you have reason to believe are valid.
+
+If, pursuant to or in connection with a single transaction or arrangement, you convey, or propagate by procuring conveyance of, a covered work, and grant a patent license to some of the parties receiving the covered work authorizing them to use, propagate, modify or convey a specific copy of the covered work, then the patent license you grant is automatically extended to all recipients of the covered work and works based on it.
+
+A patent license is “discriminatory” if it does not include within the scope of its coverage, prohibits the exercise of, or is conditioned on the non-exercise of one or more of the rights that are specifically granted under this License. You may not convey a covered work if you are a party to an arrangement with a third party that is in the business of distributing software, under which you make payment to the third party based on the extent of your activity of conveying the work, and under which the third party grants, to any of the parties who would receive the covered work from you, a discriminatory patent license (a) in connection with copies of the covered work conveyed by you (or copies made from those copies), or (b) primarily for and in connection with specific products or compilations that contain the covered work, unless you entered into that arrangement, or that patent license was granted, prior to 28 March 2007.
+
+Nothing in this License shall be construed as excluding or limiting any implied license or other defenses to infringement that may otherwise be available to you under applicable patent law.
+
+12. No Surrender of Others' Freedom.
+If conditions are imposed on you (whether by court order, agreement or otherwise) that contradict the conditions of this License, they do not excuse you from the conditions of this License. If you cannot convey a covered work so as to satisfy simultaneously your obligations under this License and any other pertinent obligations, then as a consequence you may not convey it at all. For example, if you agree to terms that obligate you to collect a royalty for further conveying from those to whom you convey the Program, the only way you could satisfy both those terms and this License would be to refrain entirely from conveying the Program.
+
+13. Use with the GNU Affero General Public License.
+Notwithstanding any other provision of this License, you have permission to link or combine any covered work with a work licensed under version 3 of the GNU Affero General Public License into a single combined work, and to convey the resulting work. The terms of this License will continue to apply to the part which is the covered work, but the special requirements of the GNU Affero General Public License, section 13, concerning interaction through a network will apply to the combination as such.
+
+14. Revised Versions of this License.
+The Free Software Foundation may publish revised and/or new versions of the GNU General Public License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns.
+
+Each version is given a distinguishing version number. If the Program specifies that a certain numbered version of the GNU General Public License “or any later version” applies to it, you have the option of following the terms and conditions either of that numbered version or of any later version published by the Free Software Foundation. If the Program does not specify a version number of the GNU General Public License, you may choose any version ever published by the Free Software Foundation.
+
+If the Program specifies that a proxy can decide which future versions of the GNU General Public License can be used, that proxy's public statement of acceptance of a version permanently authorizes you to choose that version for the Program.
+
+Later license versions may give you additional or different permissions. However, no additional obligations are imposed on any author or copyright holder as a result of your choosing to follow a later version.
+
+15. Disclaimer of Warranty.
+THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
+
+16. Limitation of Liability.
+IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
+
+17. Interpretation of Sections 15 and 16.
+If the disclaimer of warranty and limitation of liability provided above cannot be given local legal effect according to their terms, reviewing courts shall apply local law that most closely approximates an absolute waiver of all civil liability in connection with the Program, unless a warranty or assumption of liability accompanies a copy of the Program in return for a fee.
+
+END OF TERMS AND CONDITIONS
+
+How to Apply These Terms to Your New Programs
+
+If you develop a new program, and you want it to be of the greatest possible use to the public, the best way to achieve this is to make it free software which everyone can redistribute and change under these terms.
+
+To do so, attach the following notices to the program. It is safest to attach them to the start of each source file to most effectively state the exclusion of warranty; and each file should have at least the “copyright” line and a pointer to where the full notice is found.
+
+     <one line to give the program's name and a brief idea of what it does.>
+     Copyright (C) <year>  <name of author>
+
+     This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
+
+     This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more details.
+
+     You should have received a copy of the GNU General Public License along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+Also add information on how to contact you by electronic and paper mail.
+
+If the program does terminal interaction, make it output a short notice like this when it starts in an interactive mode:
+
+     <program>  Copyright (C) <year>  <name of author>
+     This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
+     This is free software, and you are welcome to redistribute it under certain conditions; type `show c' for details.
+
+The hypothetical commands `show w' and `show c' should show the appropriate parts of the General Public License. Of course, your program's commands might be different; for a GUI interface, you would use an “about box”.
+
+You should also get your employer (if you work as a programmer) or school, if any, to sign a “copyright disclaimer” for the program, if necessary. For more information on this, and how to apply and follow the GNU GPL, see <https://www.gnu.org/licenses/>.
+
+The GNU General Public License does not permit incorporating your program into proprietary programs. If your program is a subroutine library, you may consider it more useful to permit linking proprietary applications with the library. If this is what you want to do, use the GNU Lesser General Public License instead of this License. But first, please read <https://www.gnu.org/philosophy/why-not-lgpl.html>.

custom_nodes/ComfyUI-H3-Motion-Context-main/README.md

@@ -0,0 +1,477 @@
+# H3 Motion Context
+
+Chain MiniMax H3 clips so motion and sound keep going across the cut.
+
+Generate clip A. Feed its last frames and audio into this node. Generate
+clip B. B picks up where A left off: same motion, same speed, same
+direction, and the same audio continued rather than a new take that
+sounds similar. Repeat as long as you like.
+
+Nothing on disk is edited and nothing in ComfyUI is modified. The nodes
+check their arithmetic against the live ComfyUI code before the first
+render, and if an update breaks an assumption they refuse to run and say
+what moved. A loud failure beats a bad render you don't notice.
+
+Requires ComfyUI 0.34.0 or newer, which is where H3 gained arbitrary
+keyframe anchors. Version 0.3.1 runs on that and on everything older;
+see [CHANGELOG.md](CHANGELOG.md).
+
+## Why this exists
+
+ComfyUI can anchor a still or a short clip at any frame of an H3
+generation, with the Add Guide for MiniMax H3 node. If that is all you
+need, use it. You do not need this pack for it.
+
+Chaining is a different problem, and two parts of it are still unsolved
+by anything else.
+
+**The picture goes out to pixels and back at every link.** Add Guide takes
+images and encodes them. Chain through it and every join costs a decode, a
+resize and a re-encode. That round trip is where the colour drift and the
+softening down a long chain come from. This pack slices the previous
+clip's tail straight out of its latent, so the pinned frames are the same
+numbers they were, bit for bit.
+
+**The sound restarts instead of continuing.** Add Guide anchors audio
+starting at a frame and running forward. To actually continue a
+soundtrack, the pinned window has to END at the join and reach backwards
+into the sound that already played. That is the difference between the
+model continuing your track and the model writing something that sounds
+like it, and on anything with a beat you hear it immediately.
+
+Everything else here follows from those two: the Trim node that removes
+the pinned head from the delivery, the Save/Load Latent pair that carries
+a clip across without touching pixels, and the Seam Probe that measures
+whether a join is a real continuation or a convincing imitation.
+
+Audio was the harder half, and it's the more useful half, since H3
+generates picture and sound together. See "Why the audio needed work"
+below if you care how.
+
+## Install
+
+Drop the folder in `ComfyUI/custom_nodes/` and restart. At startup you'll
+just see:
+
+```
+h3_motion_context: nodes registered. ComfyUI is not modified; the layout
+checks run on the first use of a Motion Context node.
+```
+
+Having the pack installed changes nothing about your other H3 workflows,
+and nothing runs until you actually chain a clip. The first time you do,
+you'll see:
+
+```
+h3_motion_context: ComfyUI H3 layout checks passed, anchors and pinned audio will land where intended
+```
+
+Anything else and the node refuses to run. The reason is logged.
+
+On ComfyUI 0.33.4 or older the node says so and points you at version
+0.3.1, which runs on both. That is read from the layout code itself
+rather than a version number, so a nightly or a fork gets the right
+answer.
+
+## Wiring
+
+```
+MiniMaxH3ImageToVideo / MiniMaxH3ReferenceToVideo (or the t2v path)
+  -> H3 Motion Context      <- previous clip's latent (picture + sound)
+  -> guider / sampler
+  ...
+  decoded IMAGE + AUDIO
+  -> H3 Motion Context Trim         <- wire trim_frames across
+  -> Create Video / save
+```
+
+Wire `trim_frames` into the Trim node. The pinned frames come back at the
+start of the new clip and have to come off before you concatenate, picture
+and sound together.
+
+### Carrying the previous clip across
+
+The previous clip reaches the node as a latent, but you can't wire the sampler
+straight into `context_latent`. ComfyUI will call it a circular
+connection, and it's right: the latent you want is from the previous run,
+not this one. Two helper nodes move it across runs the same way your
+frames and audio already move across, through a file:
+
+```
+this run:   SamplerCustomAdvanced -> H3 Motion Context Save Latent
+next run:   H3 Motion Context Load Latent -> context_latent
+```
+
+Both have a `clip_index` and the numbers mean what they say. On Load, the
+clip you're continuing FROM. On Save, the clip this one IS. First clip:
+Load 0, Save 1. Making clip 2 from clip 1: Load 1, Save 2.
+
+Load 0 does not read a file. Motion Context then passes the incoming
+conditioning through and reports `trim_frames` 0, so you can leave the
+node enabled for the first clip. Do not mute it.
+
+Do not use queue **run on change** to walk the chain. Each index change is
+a separate graph edit, so two widgets incrementing will queue two runs and
+skip slots. Use **H3 Motion Context Chain** instead of ComfyUI's Run
+button.
+
+**The Chain node only sees Load and Save if all three sit in the same
+canvas group** (one of those coloured boxes you draw around nodes). If
+they are not grouped together, every button does nothing. Select Load,
+Save, and Chain, then Group Selected (or drop Chain into the existing
+Motion Context group).
+
+- **Run/Re-roll** is the Run button for this graph. It queues at the
+  current Load/Save indices and does not advance them. First clip: leave
+  Load 0 / Save 1 and click it. Hate the result? Click it again; the
+  retry overwrites that slot.
+- **Approve** advances both indices, then queues the next clip once.
+- **Chain** is Approve on a loop. After a finished clip it bumps
+  Load/Save and keeps going, so a 0/1 clip you already made becomes 1/2
+  rather than a re-roll. The exception is Load 0 / Save 1 with no clip 1
+  on disk: it generates that first clip, then auto-approves. **segments**
+  is how many clips that loop runs: 5 means five clips then stop, 0 means
+  keep going until you click **Stop**.
+- **Reset** sets Load 0 / Save 1. It does not queue and does not delete
+  files.
+- **Clear latents** deletes numbered chain slots
+  (`clip_00001.safetensors` and so on) in the Load folder. Files you
+  renamed are left alone. Indices stay put.
+
+Files are named the obvious way, `clip_00002.safetensors` is clip 2.
+
+Auto-saved files (Save at 0) get a trailing underscore
+(`clip_00002_.safetensors`) because they're numbered by run, not by clip,
+and indexed loading skips them on purpose.
+
+You can also point the loader at a specific file when `clip_index` is
+greater than 0; the file is loaded and the index is ignored. Index 0
+never reads a file.
+Its output is only for `context_latent`. Don't wire it into a decode node.
+Stock Save/Load Latent won't work here, it can't handle H3's paired
+video/audio latent.
+
+The latent carries both streams, so with it wired you don't need to load
+the previous clip's video at all. The pinned frames are sliced straight
+out of it rather than decoded to pixels and encoded again, so they're
+exactly what the model made instead of a reconstruction. Nothing shifts
+the colour or the contrast, so there's no seam to see, and it's faster.
+
+Nothing to set for any of that. Leave `context_frames` unwired. Resolution
+has to match between clips, since a latent can't be resized; if it doesn't
+the node refuses and names both resolutions rather than quietly dropping
+to the lossy path.
+
+There's an older path for graphs with no latent: the previous clip's
+frames into `context_frames`, its decoded audio into `context_audio`, and
+the H3 audio VAE into `audio_vae`. It works, but it costs a lossy round
+trip per link on both streams and it's where the visible seams came from.
+Use the latent unless you have a reason not to.
+
+### Reference mode
+
+Put this node after `MiniMaxH3ReferenceToVideo` and wire it as above. Your
+reference blocks (image, video, video with audio, audio) are left alone
+entirely: the pinned sound rides as a keyframe, not a reference, so the
+two mechanisms no longer share a list.
+
+Nothing to configure. Worth mentioning only because versions before 0.2.0
+overwrote that list, so turning chaining on quietly threw your references
+away, and because up to 0.3.1 the pinned audio was added to it.
+
+References still push the target timeline along, and the pinned frames
+follow it. That is ComfyUI's own arithmetic now rather than this pack's.
+
+### Alongside Add Guide
+
+Anchor whatever you like with Add Guide for MiniMax H3 and put this node
+after it. Both survive: the pinned head decides how the clip starts, the
+guide decides what happens where you put it. Guides that carry audio keep
+their own placement, which is forward from the anchor frame, while the
+pinned sound keeps its backwards-reaching window.
+
+Guides anchored inside the pinned head are dropped with a warning, for
+the same reason a `first_frame` anchor is.
+
+### Keeping a last-frame target
+
+Wire `last_frame` on the stock conditioning node as usual and put this
+node after it. The anchor is kept and pinned alongside the head: the
+pinned run decides how the clip starts, your image decides where it
+ends. It keeps the coordinates ComfyUI gave it, including the shift
+references apply, so it stays put whatever else is in the graph.
+
+A `first_frame` anchor is dropped, with a warning. The pinned head owns
+those frames, and a second block pinned at the same instant with
+different content would fight it. Older versions silently replaced both
+anchors, so if a chain graph carried a last-frame target before this
+version, it never reached the model.
+
+## Settings
+
+Two, because everything else had exactly one right answer.
+
+**context_length** - frames of the previous clip's picture to carry over.
+5, 22, 39 or 56. Those are the lengths that are a whole number of latent
+steps, which is why the others aren't offered. 5 is just barely fluid, 22
+is nearly seamless. Longer windows pin more motion but they come off the
+front of the delivered clip, so 56 spends 2.3 seconds of every render on
+frames you throw away. **Use 22.**
+
+**audio_context_length** - frames of tail audio to pin, independent of the
+picture window. It ends at the same instant as the pinned video, so this
+only controls how far back the sound reaches. 0 follows context_length.
+**Use 24**: that is exactly one second of sound, and any multiple of 3
+lands exactly on the model's 40 Hz audio grid (a frame is 5/3 of an
+audio step), so the window is pinned at precisely the width you asked
+for. Off-grid values are widened to the nearest whole step. Increments
+of 24 keep whole seconds: 48 pins the last two.
+
+Everything else is fixed: the pinned run is encoded in one VAE call, it
+sits at the head of the clip where the Trim node removes it, and the
+pinned audio goes on this clip's own timeline. The alternatives all
+existed only to reproduce their own failures, so they're constants at the
+top of `nodes.py` now. Change one there if you ever need to see what they
+did.
+
+`match_tail` on the Trim node stays a setting because that node has no
+idea what the other one did. Leave it on. H3 rounds its audio grid up, so
+every clip carries about 8ms more sound than picture, and that error
+stacks at every join.
+
+## Writing prompts for a chain
+
+The settings get motion and sound across the join. What happens in the
+next clip is on you, and there are a few traps.
+
+**The model renders contradictions as unions.** Clip N ends on a close-up
+of A, clip N+1's prompt opens with "a two-shot of B and C," and the model
+doesn't pick. You get all three. The pinned frames aren't a suggestion, so
+a prompt describing a different arrangement of people reads as an addition
+to them, not a replacement.
+
+**The airlock.** Don't ask for the change and the continuation at the same
+moment. Open clip N+1 holding clip N's exact closing framing, no dialogue,
+about two seconds, then cut to the new setup. Joins done this way measure
+tighter than an ordinary frame-to-frame cut. Joins that skip it measure
+like two different rooms spliced together.
+
+**Give the hold something to do.** A held framing with nothing happening
+renders as a literal freeze, and two seconds of a motionless actor looks
+like the video stalled. Write in a breath, a weight shift, an eyeline
+change. The camera holds still, the performer doesn't.
+`tests/freeze_detect.py` finds these.
+
+**Budget the pinned head in your timecodes.** In `head` mode the clip
+comes out `context_length` frames shorter than it was sampled. At 22 that's
+0.92 seconds. Your prompt timings land against the sampled version, which
+starts 0.92s earlier, so a beat you wrote for 4.0s shows up at 3.08s in the
+file.
+
+## Why the audio needed work
+
+The first version ran pinned audio through H3's reference mechanism, which
+is where audio conditioning normally goes. Every join had a small tick,
+like the audio briefly sped up and went offbeat. Looking at the waveform
+showed nothing wrong. Both sides of every join were smooth on their own.
+
+Cross-correlating each clip's opening against the previous clip's ending
+(that's `tests/seam_probe.py`) showed what was actually happening: the new
+clip's audio resembled the old one. Same instruments, same groove, never
+the same recording. A cover band. The model was reading the reference as
+"a separate clip that sounds like this," which is what references are for
+and exactly wrong for continuation.
+
+The fix is the same one that already worked for video. The rows the model
+sees are identical either way. What differs is their time coordinates, and
+the coordinates are what say "separate clip" versus "this clip, earlier."
+So the pinned audio still rides the reference machinery, but its
+coordinates get rewritten onto the new clip's timeline, ending exactly
+where the pinned video ends. Correlation at the joins went from about 0.45
+with incoherent timing to 0.95+ with a flat offset, and the tick was gone.
+Measured across a chain, the offset doesn't grow from join to join.
+
+## Limitations
+
+**Quality degrades down a chain.** The big one, and it's mostly audio.
+Each clip is generated from the previous clip's output, which came from
+the one before it. Losses compound like photocopying a photocopy, and in
+audio the top end goes first. Timing and tempo stay locked, but after
+several clips the sound gets duller and more muffled. Picture holds up
+much better.
+
+Two things stack per link: the model's own smoothing, and a round trip
+out to pixels and back. `context_latent` removes the second one for both
+streams. On picture that's the difference between a visible join and no
+join at all. On sound it helps, but the model's own smoothing is still
+there. Long chains are worth listening to critically, and restarts land
+best at a natural musical transition.
+
+**A small audio offset, now believed fixed.** Chained clips used to come
+out about 8ms late. The cause was arithmetic: a frame is 5/3 of an audio
+step, so unless the pinned window's length works out to a whole number of
+steps it landed between the ones the model was filling. The window is now
+snapped to that grid. The offset was constant, well under where lip-sync
+errors get noticeable, and it didn't grow down a chain, so this is a
+tidy-up rather than a rescue. `tests/seam_probe.py` reports the lag in
+milliseconds if you want to check it on your own material.
+
+**H3 emits 32 kHz audio, not 48.** Read the rate off the clip in any script
+that remuxes or concatenates. A stream-copy concat can't change rate
+partway, so a hardcoded 48000 silently turns the tail of a long episode
+into nothing while every duration check still passes.
+`tests/level_step.py` prints every clip's rate and flags a mismatch.
+
+**Turbo LoRAs and Spectrum both cost you audio.** A turbo LoRA hits a
+result in very few steps, and fine detail is what those last steps were
+for. It thickens the sound and softens the picture. Step-skipping
+optimizers like ComfyUI-Spectrum-MiniMax-H3 do the same thing to the
+audio, less so to the picture, and they also mispredict the pinned rows,
+which never change. Run both together and it stacks. If a chain sounds
+duller or closer than you expected, try turning these off before blaming
+the chaining. **Keep Spectrum off for these graphs.**
+
+**Resolution can't change mid-chain** while using `context_latent`. A
+latent can't be resized, so the node refuses. Regenerate the previous clip
+at the new resolution, or start a fresh chain there.
+
+**Prompting a chain takes work**, especially with reference mode. Every
+reference conditions the whole clip; there's no way to say "this one
+starts two seconds in." Timing has to come from the shot structure and
+the description. See "Writing prompts for a chain" above.
+
+**Tested narrowly.** Joins have been verified on dense beat-driven
+electronic music, where timing errors are most audible, and on spoken word
+through the latent path, where nothing hides a seam. One Windows machine,
+one resolution, one sampler. The math self-tests every startup. The
+perceptual results are one person's renders.
+
+**ComfyUI's H3 support is young.** This pack no longer patches any of it,
+but it still depends on how the layout places things, and one of those
+dependencies has no upstream test behind it: the pinned audio window is
+positioned with a fractional, negative anchor index. That is legal
+arithmetic in the layout and no stock node can produce one, so nothing
+upstream exercises it. `layout_contract.py` checks it before the first
+render and refuses if it ever stops holding.
+
+The failure mode after a ComfyUI update is therefore "the node won't
+run," not bad output. There is a worked example: when the layout
+constructor changed, 0.3.0 of this pack refused until 0.3.1 caught up.
+Annoying, but the alternative was joins landing at the wrong instant with
+nothing to tell you.
+
+**License.** The H3 community license reportedly doesn't currently cover
+the EU, UK, Korea or the US. Check for yourself before shipping anything
+on it.
+
+## Recommended starting point
+
+`context_length 22`, `audio_context_length 24`, `context_latent` wired
+through the Save/Load Latent pair, Trim node wired for picture and sound
+with `match_tail` on, Spectrum off. Every "it works" in this README means
+that config.
+
+## Testing
+
+Six scripts, all runnable without ComfyUI or a GPU.
+
+```
+python tests/_mock_harness.py        # the layout checks against a fake stock model
+python tests/_node_smoke_test.py     # the node end to end, refs + save/load
+python tests/_probe_node_test.py     # the seam probe node, joins with known answers
+python tests/seam_probe.py A.flac B_untrimmed.flac    # is the join real continuation?
+python tests/level_step.py clip*.flac                 # does the level or room tone jump?
+python tests/freeze_detect.py clip*.mp4               # did a held shot render as a still?
+```
+
+The first three print their checks and end with a pass line. The other
+three measure real output; `level_step` and `freeze_detect` take
+`--self-test` to check their own math on made-up data first, and
+`seam_probe`'s math is what `_probe_node_test.py` exercises.
+
+The three measurement scripts ask different questions and a join can fail
+any one on its own. `seam_probe` is timing: is the audio the same waveform
+continued, or a sound-alike. `level_step` is volume: does the loudness, or
+the room tone underneath it, jump at the cut. `freeze_detect` is picture:
+is anything happening in that shot.
+
+For `seam_probe` and `level_step`, give them the UNTRIMMED audio of the new
+clip. Branch the audio decode to a second Save Audio node alongside the
+Trim.
+
+### Measuring a join in-graph
+
+The H3 Motion Context Seam Probe node runs the same measurements inside
+the graph, where the seam position is known exactly rather than inferred
+from file ends (that inference is where the CLI probe's phantom ~8 ms lag
+came from). Wire it inline between the audio VAE decode and the Trim
+node:
+
+```
+clip_a_latent     the same latent wired into context_latent
+audio_vae         the same audio VAE
+clip_b_untrimmed  this clip's audio off the VAE decode, before the trim
+trim_frames       from the Motion Context node, same value the Trim gets
+```
+
+The audio output is the input unchanged, so it drops into an existing
+chain without changing the render. The report goes to a Preview Text
+node: lag, correlation, broadband and floor steps, judged against the
+same thresholds the CLI scripts document.
+
+## Upgrading
+
+[CHANGELOG.md](CHANGELOG.md) lists what changed in each release and which
+ComfyUI H3 layout it works with. Worth a look before opening an issue or
+starting a fork: several fixes people have rebuilt from scratch were
+already in an earlier release.
+
+The node's widgets changed. ComfyUI stores widget values by position, so a
+workflow saved against an older version will load its numbers into the
+wrong slots. Delete the Motion Context node, add it again and rewire it.
+Takes a minute and beats rendering with scrambled settings.
+
+**Only install this once.** A fork of this repo, a manual clone next to a
+Manager install, or a renamed backup still sitting in `custom_nodes` will
+all load. Renaming a folder does not stop ComfyUI loading it.
+
+Older versions of this pack, and other H3 packs, patch ComfyUI's layout
+code at runtime. This one does not, so it no longer competes for that
+code and will run alongside them. If it finds the layout wrapped it says
+who by, then checks whether anchors still land correctly and carries on
+if they do. Keeping one H3 chaining pack installed is still the quiet
+life.
+
+## Credits
+
+The Ref2VA multi-reference support was worked out by **seitanism** in the
+Banodoco MiniMax H3 seamless-extension thread and first implemented in
+**ethanfel**'s fork of this repo. The code here is written independently,
+but the idea is theirs and they got there first.
+
+The prompting section comes out of a 16-clip, 4:34 multicam sitcom episode
+chained with this pack at 736x576 on a 5070 Ti, about two hours of
+generation. The airlock, the freeze warning, the 32 kHz trap and the
+timecode budget are all that build's findings. Same run measured a
+video-only chain at a median seam level step of 0.905, dropping to 0.16
+with the audio carried across.
+
+**javawock7618** and **azra1l** reported the layout change that broke
+0.3.0 and narrowed it to specific commits, which turned a hunt into a
+diff. **ChimeraWerks** found and fixed the audio grid overhang.
+
+If you build something long with this, numbers are more useful than praise.
+Open an issue.
+
+## Files
+
+| File | Role |
+|---|---|
+| `layout_contract.py` | Proves ComfyUI still places anchors and pinned audio where this pack needs them, once, before the first render. Modifies nothing. |
+| `nodes.py` | The four core nodes: Motion Context, Trim, and the latent Save/Load pair. |
+| `probe_node.py` | The Seam Probe node: measures a join in-graph, with the seam at a known sample instead of inferred from file ends. |
+| `tests/seam_probe.py` | Is a join's audio a real continuation, a sound-alike, or drifting. |
+| `tests/level_step.py` | Level and room-tone continuity at each join. Also catches sample-rate mismatches. |
+| `tests/freeze_detect.py` | Stretches where the picture stops moving. |
+| `tests/_mock_harness.py`, `tests/_node_smoke_test.py`, `tests/_probe_node_test.py` | Layout, node and probe tests, numpy only. |
+| `CHANGELOG.md` | What changed in each release, and which ComfyUI H3 layout it works with. |

custom_nodes/ComfyUI-H3-Motion-Context-main/__init__.py

@@ -0,0 +1,48 @@
+"""H3 Motion Context.
+
+Clip chaining for MiniMax H3: pin the tail of the previous clip, picture
+and sound, so the next clip genuinely continues it.
+
+This registers the nodes and nothing else. Nothing in ComfyUI is
+modified. Earlier versions wrapped ComfyUI's H3 layout constructor to
+lift a restriction on where a keyframe could be anchored; ComfyUI 0.34.0
+lifted it upstream, so the nodes now build plain keyframe dicts and hand
+them to stock code.
+
+What remains is a dependency on meaning rather than structure: the pinned
+audio window is placed with a fractional, negative anchor index, which is
+legal arithmetic in the layout but is not reachable through any stock
+node and therefore has no upstream test. layout_contract.py checks it
+before the first render and refuses if it ever stops holding, so an
+upstream change produces a clear error rather than a silently wrong join.
+
+That check runs on first use, not at import, so having the pack installed
+changes nothing until you actually chain a clip.
+
+Requires ComfyUI 0.34.0 or newer. Pack version 0.3.1 is the last release
+that works with 0.33.4 and older.
+"""
+
+import logging
+
+from .nodes import (
+    NODE_CLASS_MAPPINGS,
+    NODE_DISPLAY_NAME_MAPPINGS,
+    register_chain_routes,
+)
+from .probe_node import (
+    NODE_CLASS_MAPPINGS as _PROBE_CLASSES,
+    NODE_DISPLAY_NAME_MAPPINGS as _PROBE_NAMES,
+)
+
+NODE_CLASS_MAPPINGS.update(_PROBE_CLASSES)
+NODE_DISPLAY_NAME_MAPPINGS.update(_PROBE_NAMES)
+register_chain_routes()
+
+logging.getLogger("h3_motion_context").info(
+    "h3_motion_context: nodes registered. ComfyUI is not modified; the "
+    "layout checks run on the first use of a Motion Context node.")
+
+WEB_DIRECTORY = "./web"
+
+__all__ = ["NODE_CLASS_MAPPINGS", "NODE_DISPLAY_NAME_MAPPINGS", "WEB_DIRECTORY"]

custom_nodes/ComfyUI-H3-Motion-Context-main/csrf_guard.py

@@ -0,0 +1,82 @@
+"""Same-origin gate for mutating Motion Context HTTP routes.
+
+The Comfy Registry flags unauthenticated POST/DELETE that write or delete
+files as CSRF-forgeable (policy-v0.2 UNAUTHENTICATED_SIDE_EFFECT). ComfyUI's
+own loopback Origin/Host middleware is not part of this pack, so the
+clear-latents handler must check the request itself.
+
+A same-origin UI fetch sends Origin matching Host. A cross-site form POST
+sends a different Origin, or Origin: null from a sandboxed iframe.
+"""
+
+from functools import wraps
+from urllib.parse import urlparse, urlsplit
+
+from aiohttp import web
+
+_MUTATING = frozenset({"POST", "PUT", "PATCH", "DELETE"})
+
+
+def _origin_parts(value):
+    raw = (value or "").strip()
+    if not raw or raw.lower() == "null":
+        return "", None
+    parsed = urlparse(raw)
+    hostname = (parsed.hostname or "").lower()
+    if not hostname:
+        return "", None
+    port = parsed.port
+    if port is None:
+        port = 443 if parsed.scheme == "https" else 80
+    return hostname, port
+
+
+def _host_parts(host_header):
+    parsed = urlsplit("//" + (host_header or "").strip().lower())
+    hostname = (parsed.hostname or "").lower()
+    port = parsed.port
+    if port is None:
+        port = 80
+    return hostname, port
+
+
+def reject_csrf(request):
+    """Return a 403 response if this mutating request is not same-origin."""
+    if request.method not in _MUTATING:
+        return None
+
+    site = (request.headers.get("Sec-Fetch-Site") or "").strip().lower()
+    if site == "cross-site":
+        return web.json_response(
+            {"error": "Cross-site request blocked."}, status=403)
+
+    host = (request.headers.get("Host") or "").strip()
+    hh, hp = _host_parts(host)
+    if not hh:
+        return web.json_response({"error": "Missing Host."}, status=403)
+
+    origin_raw = (request.headers.get("Origin") or "").strip()
+    oh, op = _origin_parts(origin_raw)
+    if not oh:
+        oh, op = _origin_parts(request.headers.get("Referer") or "")
+        if not oh:
+            return web.json_response(
+                {"error": "Missing Origin. Same-origin UI requests send it."},
+                status=403,
+            )
+
+    if oh != hh or op != hp:
+        return web.json_response(
+            {"error": "Origin does not match Host."}, status=403)
+    return None
+
+
+def require_same_origin(handler):
+    """Decorator: reject CSRF-forgeable unauthenticated POST/DELETE."""
+    @wraps(handler)
+    async def wrapped(request):
+        blocked = reject_csrf(request)
+        if blocked is not None:
+            return blocked
+        return await handler(request)
+    return wrapped

custom_nodes/ComfyUI-H3-Motion-Context-main/layout_contract.py

@@ -0,0 +1,243 @@
+"""Check that ComfyUI's H3 layout still means what this pack thinks it means.
+
+Nothing here modifies ComfyUI. The pack used to wrap
+`PackedLayout.__init__` because stock rejected any keyframe anchor other
+than the first or last frame. ComfyUI 0.34.0 lifted that restriction, so the
+node now just builds keyframe dicts and hands them over. No wrapper, no
+ownership of a constructor, and no argument with other packs that patch
+the same place.
+
+What is left is a dependency on meaning rather than on structure. Stock
+positions a keyframe at
+
+    cond_t = cursor + FRAME_RESCALE * kf["resolved_frame_index"]
+
+where `cursor` is the target timeline's origin, already advanced past any
+reference blocks. Two properties of that line matter to this pack and
+neither is guaranteed by anything upstream:
+
+  fractional  the audio window has to END at the join, so its index is
+              end_frame - rt / FRAME_RESCALE, which is not a whole number
+  negative    that index is usually below zero, because the pinned audio
+              is a tail that played before this clip starts
+
+Stock's own Add Guide node validates `frame_idx` to a non-negative integer
+before it ever reaches the layout, so upstream has no test covering either
+property. An int cast or a bounds check added later would not fail loudly
+on its own: it would quietly move the pinned audio and put the join in the
+wrong place.
+
+So this runs once, before the first render, and proves the arithmetic
+still holds. If it does not, the node refuses and says what moved. Same
+policy as the patch self-test it replaces, without touching anything.
+"""
+
+import logging
+
+import comfy.ldm.minimax.model as mm
+
+_LOG = logging.getLogger("h3_motion_context")
+
+_checked = None  # None not yet run, True passed, str the failure
+
+
+class _Stub:
+    """Stands in for a latent. The layout reads only the shape."""
+
+    def __init__(self, shape):
+        self.shape = shape
+
+
+def _origin(layout):
+    """The coordinate the target clip starts at, read off the built layout.
+
+    The target video rows are always the last segment and their first row
+    sits exactly on the cursor, so this reads the origin rather than
+    recomputing stock's reference arithmetic. Everything else here is
+    expressed as a distance from it.
+    """
+    a, b, kind = layout.segments[-1]
+    if kind != "video" or b <= a:
+        raise RuntimeError(
+            "expected the target video rows to be the last layout segment, "
+            "found %r spanning %d rows" % (kind, b - a))
+    return float(layout.position_ids[a, 0])
+
+
+def _seg(layout, kind):
+    return [(a, b) for a, b, k in layout.segments if k == kind]
+
+
+def _check():
+    text_len, latent_t, lh, lw, audio_t = 7, 7, 22, 38, 16
+    fr = mm.FRAME_RESCALE
+
+    if hasattr(mm.PackedLayout.__init__, "__wrapped__"):
+        pass  # reported by ensure(); the checks below decide either way
+
+    def build(keyframes=None, refs=None):
+        return mm.PackedLayout(text_len, latent_t, lh, lw, audio_t,
+                               keyframes=keyframes, refs=refs)
+
+    video = _Stub((1, 24, 1, lh, lw))
+
+    # 1. a whole-number anchor lands FRAME_RESCALE per pixel frame past the
+    # target origin. This is the line the whole pack is built on.
+    lay = build(keyframes=[{"resolved_frame_index": p, "latent": video}
+                           for p in (0, 3)])
+    o = _origin(lay)
+    got = [float(lay.position_ids[a, 0]) - o for a, _ in _seg(lay, "cond")]
+    want = [0.0, fr * 3]
+    if len(got) != 2 or any(abs(g - w) > 1e-9 for g, w in zip(got, want)):
+        raise RuntimeError(
+            "keyframe anchors no longer sit at FRAME_RESCALE per pixel "
+            "frame past the target origin: got %s, expected %s" % (got, want))
+
+    # 2. a reference must not move an anchor relative to the target. Stock
+    # advances its cursor past the references before placing anchors, so
+    # the anchor-to-origin distance is unchanged.
+    lay = build(keyframes=[{"resolved_frame_index": 3, "latent": video}],
+                refs=[{"kind": "audio", "ref_audio_t": 8}])
+    a, _ = _seg(lay, "cond")[0]
+    gap = float(lay.position_ids[a, 0]) - _origin(lay)
+    if abs(gap - fr * 3) > 1e-9:
+        raise RuntimeError(
+            "a reference moved the anchors relative to the target: anchor "
+            "sits %.6f past the origin, expected %.6f. Stock no longer "
+            "compensates keyframes for reference blocks." % (gap, fr * 3))
+
+    # 3. the audio window: fractional AND negative index, window ending at
+    # a chosen target frame. This is the property with no upstream test.
+    # The numbers matter. An index is end_frame - rt / FRAME_RESCALE, and
+    # the node snaps end_frame so that FRAME_RESCALE * end_frame is a whole
+    # audio coordinate, which leaves the index whole whenever that
+    # coordinate and rt differ by a multiple of 5. Picking such a pair here
+    # would let an integer cast slip through the check, so this pair is
+    # deliberately not one of them.
+    rt, end_coord = 40, 8
+    end_frame = end_coord / fr
+    idx = end_frame - rt / fr
+    if idx >= 0 or idx == int(idx):
+        raise RuntimeError("the audio check is not exercising a fractional "
+                           "negative index; its own numbers are wrong")
+    lay = build(keyframes=[{"resolved_frame_index": idx,
+                            "audio_latent": _Stub((1, 32, 2, rt))}])
+    spans = _seg(lay, "cond_audio")
+    if len(spans) != 1:
+        raise RuntimeError(
+            "a keyframe carrying an audio latent produced %d cond_audio "
+            "segments, expected 1" % len(spans))
+    a, b = spans[0]
+    if b - a != 2 * rt:
+        raise RuntimeError(
+            "the pinned audio window has %d rows for %d latent steps, "
+            "expected %d (stereo, channel-major)" % (b - a, rt, 2 * rt))
+    o = _origin(lay)
+    t = lay.position_ids[a:b, 0]
+    start = float(t.min()) - o
+    end = start + float(rt)
+    if abs(end - fr * end_frame) > 1e-9:
+        raise RuntimeError(
+            "the pinned audio window ends %.6f past the target origin, "
+            "expected %.6f. A fractional or negative resolved_frame_index "
+            "is no longer taken literally, so pinned audio would land at "
+            "the wrong instant." % (end, fr * end_frame))
+
+    # 4. and it must reach BACKWARDS from there, not forwards. If upstream
+    # ever flips the window's anchor end this stays silent otherwise.
+    if start >= 0.0:
+        raise RuntimeError(
+            "the pinned audio window starts %.6f past the target origin; it "
+            "should start before it and end at the join" % start)
+
+
+def _wrapper_origin():
+    """Who wrapped PackedLayout.__init__, if anyone. None if nobody has.
+
+    This matters because a wrapper's signature is not ComfyUI's. Every
+    known wrapper of this constructor is a copy of this pack's old layout
+    patch, vendored into another pack or left behind in a second folder,
+    and its signature carries `frame_count` on every ComfyUI version. Read
+    naively that looks exactly like ComfyUI 0.32, which is a confusing
+    thing to tell someone running 0.33.
+
+    So a wrapper is reported rather than interpreted, and the behavioural
+    checks below decide whether the layout still works. Usually it does:
+    the old patch passes anything without this pack's markers straight
+    through, and nothing built here carries them any more.
+    """
+    init = getattr(mm.PackedLayout, "__init__", None)
+    if init is None:
+        return None
+    if getattr(init, "_h3_motion_context_layout_patch", False):
+        return "an older copy of this pack's layout patch"
+    if getattr(init, "__name__", "") == "_patched_init":
+        return "a copy of this pack's layout patch (a fork, or an older version)"
+    if hasattr(init, "__wrapped__"):
+        return "another pack (%s)" % getattr(init, "__module__", "unknown")
+    home = getattr(mm.PackedLayout, "__module__", None)
+    where = getattr(init, "__module__", None)
+    if home and where and where != home:
+        return "another pack (%s)" % where
+    return None
+
+
+def ensure(context=""):
+    """Run the checks once. Raises with a usable message if they fail."""
+    global _checked
+    if _checked is True:
+        return
+    if isinstance(_checked, str):
+        raise RuntimeError(_checked)
+
+    if not hasattr(mm, "PackedLayout") or not hasattr(mm, "FRAME_RESCALE"):
+        _checked = ("h3_motion_context: ComfyUI's MiniMax H3 model module is "
+                    "missing PackedLayout or FRAME_RESCALE. This pack cannot "
+                    "run against it.")
+        raise RuntimeError(_checked)
+
+    import inspect
+    try:
+        params = inspect.signature(mm.PackedLayout.__init__).parameters
+    except (TypeError, ValueError):
+        params = {}
+    wrapped = _wrapper_origin()
+    if wrapped:
+        _LOG.warning(
+            "h3_motion_context: H3's layout constructor has been wrapped by "
+            "%s. This pack does not patch it and does not need it patched. "
+            "Checking whether anchors still land correctly; if they do, "
+            "nothing needs doing, but keeping only one H3 chaining pack "
+            "installed avoids surprises.", wrapped)
+    elif "frame_count" in params:
+        _checked = (
+            "h3_motion_context: this ComfyUI still has the older H3 layout, "
+            "which rejects keyframe anchors other than the first and last "
+            "frame. This version of the pack no longer works around that. "
+            "Update ComfyUI, or use pack version 0.3.1, which runs on both "
+            "layouts. (Detected from PackedLayout.__init__ still taking "
+            "frame_count, not from a version number.)")
+        raise RuntimeError(_checked)
+
+    try:
+        _check()
+    except Exception as exc:
+        _checked = (
+            "h3_motion_context: ComfyUI's H3 layout does not behave the way "
+            "this pack needs%s. %s. Refusing to run rather than rendering a "
+            "join at the wrong instant.%s"
+            % (" (%s)" % context if context else "", exc,
+               (" H3's layout constructor is wrapped by %s, which is the "
+                "first thing to rule out: disable it and try again."
+                % wrapped) if wrapped else
+               " This is an upstream ComfyUI change; please open an issue "
+               "with your ComfyUI version."))
+        raise RuntimeError(_checked) from exc
+
+    _checked = True
+    _LOG.info("h3_motion_context: ComfyUI H3 layout checks passed, anchors "
+              "and pinned audio will land where intended")
+
+
+def is_checked():
+    return _checked is True

custom_nodes/ComfyUI-H3-Motion-Context-main/nodes.py

@@ -0,0 +1,1201 @@
+"""Pin previous-clip motion at the head of an H3 clip.
+
+Wire it between a stock H3 conditioning node and the sampler:
+
+    MiniMaxH3ImageToVideo / MiniMaxH3ReferenceToVideo (or the t2v path)
+        -> H3 Motion Context
+        -> guider / sampler
+
+Two axes to test, both cheap.
+
+encode_mode
+  frames  one VAE call per frame, each pinned as its own cond block. The
+          model sees N snapshots at N instants.
+  video   one VAE call for the whole run. The H3 video VAE has latent_dim
+          3, so it reads the batch axis as time and compresses the run
+          into fewer latent steps (5 pixel frames -> 2 steps, 22 -> 7).
+          Each step becomes one cond block, so the motion between frames
+          lives inside the latent instead of being implied across separate
+          stills. Far fewer rows and one VAE load.
+
+anchor_mode
+  head    pinned frames occupy indices 0..N-1 of the delivered timeline.
+          They come back in the output, so trim that many frames off the
+          front before concatenating.
+  before  pinned frames sit at negative indices, ending at -1, so
+          delivered frame 0 continues from them and nothing is wasted.
+          Their time coordinates land below text_len, which is the range
+          the text rows occupy. Whether that collision matters is exactly
+          what this mode is asking.
+"""
+
+import gc
+import logging
+import os
+import re
+
+import comfy.utils
+import folder_paths
+import node_helpers
+import torch
+
+try:
+    from safetensors.torch import load_file as _st_load, save_file as _st_save
+except ImportError:  # ComfyUI always ships safetensors; belt and braces
+    _st_load = _st_save = None
+
+from .layout_contract import ensure as _ensure_layout_contract
+from .layout_contract import is_checked as _layout_checked
+
+try:
+    import torchaudio
+except ImportError:
+    torchaudio = None
+
+_LOG = logging.getLogger("h3_motion_context")
+
+
+def _ensure_layout_ok():
+    """Prove ComfyUI still places anchors the way this pack needs, once.
+
+    This used to install two runtime patches. ComfyUI 0.33 does natively
+    what they existed to do, so the node now builds plain keyframe dicts
+    and only has to check that the arithmetic behind them still holds. See
+    layout_contract.py for what is checked and why it is not free.
+
+    Run on first use rather than at import, same as the patches were: the
+    pack sitting in custom_nodes should change nothing at all until you
+    actually chain a clip. The cost is that a failure shows up on the
+    first render instead of in the startup log.
+    """
+    _ensure_layout_contract("pinning a clip")
+
+
+FRAME_PER_TOKEN = (1, 4, 4, 4, 4)
+FPS = 24  # H3's native rate; audio latents run at 40 Hz, hence FRAME_RESCALE 5/3
+FRAME_RESCALE = 5.0 / 3.0
+AUDIO_HZ = 40.0
+
+# Run lengths the video VAE's downscale formula max(1, (n - 5) // 17 * 5 + 2)
+# actually distinguishes. Anything between two grid points encodes to the same
+# number of latent steps as the lower one, but the steps then cover the FIRST
+# `covered` frames of the input rather than the last: encoding 10 frames yields
+# the same 2 steps as encoding 5, representing frames [-10..-6] of the source
+# clip instead of [-5..-1]. The pinned run would end five frames early and the
+# delivered clip would continue from the wrong instant. So off-grid requests
+# are snapped DOWN before slicing, keeping content and coverage in agreement.
+# The grid is 17m+5 and continues upward; the node only offers up to 56,
+# but the snap-down logic knows the higher points so an out-of-range
+# request lands on the nearest real one instead of being clamped to 39.
+VIDEO_RUN_GRID = (124, 107, 90, 73, 56, 39, 22, 5, 1)
+
+# Settings that used to be widgets. Each had exactly one right answer, so
+# offering the wrong one was noise. The losing branches are still in the
+# code below: change a constant here to reproduce the failure they cause.
+#
+#   ENCODE_MODE   "video" encodes the pinned run in one VAE call, so the
+#                 motion lives inside the latent. "frames" encodes each
+#                 frame as its own still, costs twice the rows and left a
+#                 visible seam in testing.
+#   ANCHOR_MODE   "head" pins the run at the start of the clip, where the
+#                 Trim node removes it. "before" places it at negative
+#                 time so nothing needs trimming, but the coordinates
+#                 collide with the text rows, which weakens the anchors
+#                 and darkens the output.
+#   AUDIO_MODE    "timeline" puts the pinned audio on this clip's own
+#                 timeline so the model continues it. "ref" is the stock
+#                 placement, which the model imitates instead: similar
+#                 music, not the same recording, plus a tick at the join.
+#   CROP          only ever applied when an aspect ratio changed between
+#                 clips, which the resolution check now refuses outright.
+ENCODE_MODE = "video"
+ANCHOR_MODE = "head"
+AUDIO_MODE = "timeline"
+CROP = "disabled"
+
+
+def _pixel_frames(latent_t):
+    """Pixel frames covered by latent_t latent steps."""
+    return sum(FRAME_PER_TOKEN[k % 5] for k in range(latent_t))
+
+
+def _step_offsets(latent_t):
+    """Pixel-frame index at which each latent step begins."""
+    out, acc = [], 0
+    for k in range(latent_t):
+        out.append(acc)
+        acc += FRAME_PER_TOKEN[k % 5]
+    return out
+
+
+def _resize(image, width, height, crop):
+    # image [B, H, W, C] -> [B, height, width, 3]; matches the stock helper
+    samples = image[..., :3].movedim(-1, 1)
+    samples = comfy.utils.common_upscale(samples, width, height, "lanczos", crop)
+    return samples.movedim(1, -1)
+
+
+def _encode_tail_audio(audio_vae, audio, seconds):
+    """Encode the last `seconds` of a clip's audio with the H3 audio VAE.
+
+    Returns ([1, 32, 2, T] latent, T) where T counts 40 Hz latent steps,
+    matching what the layout calls ref_audio_t.
+    """
+    waveform = audio["waveform"]  # [B, C, L]
+    sr = int(audio["sample_rate"])
+    vae_sr = int(getattr(audio_vae, "audio_sample_rate", 32000))
+    if sr != vae_sr:
+        if torchaudio is None:
+            raise RuntimeError(
+                "h3_motion_context: context_audio is %d Hz but the VAE wants %d Hz "
+                "and torchaudio is not available to resample." % (sr, vae_sr))
+        waveform = torchaudio.functional.resample(waveform, sr, vae_sr)
+    want = int(round(seconds * vae_sr))
+    have = int(waveform.shape[-1])
+    if have < want:
+        _LOG.warning("h3_motion_context: context_audio is %.3fs, shorter than the "
+                     "%.3fs of pinned video. Pinning what there is.",
+                     have / vae_sr, seconds)
+    else:
+        waveform = waveform[..., have - want:]
+    z = audio_vae.encode(waveform[:1].movedim(1, -1))  # [1, 32, 2, T]
+    return z, int(z.shape[-1])
+
+
+def _streams_from_latent(latent):
+    """Unpack an H3 AV latent into its contained streams.
+
+    NestedTensor.__getitem__ broadcasts the index into every contained
+    tensor rather than selecting one, so samples[0] would strip the batch
+    dimension off both streams. unbind() returns the pair.
+    """
+    samples = latent["samples"]
+    if hasattr(samples, "unbind"):
+        parts = list(samples.unbind())
+    elif isinstance(samples, (tuple, list)):
+        parts = list(samples)
+    else:
+        raise ValueError(
+            "h3_motion_context: expected a MiniMax H3 AV latent (a nested "
+            "video/audio pair), got %r" % type(samples))
+    if not parts:
+        raise ValueError("h3_motion_context: AV latent contains no streams")
+    return parts
+
+
+def _video_from_latent(latent):
+    """Pull the video stream out of an H3 AV latent."""
+    video = _streams_from_latent(latent)[0]
+    if video.ndim == 4:  # unbatched [C,T,H,W]
+        video = video.unsqueeze(0)
+    if video.ndim != 5:
+        raise ValueError("h3_motion_context: expected video latent [B,C,T,H,W], "
+                         "got shape %s" % (tuple(video.shape),))
+    return video
+
+
+def _steps_for_frames(n):
+    """Latent steps covering exactly n pixel frames from cycle position 0.
+
+    Returns None when no whole number of steps covers n. The video VAE's
+    steps alternate 1, 4, 4, 4, 4 pixel frames, so only certain totals are
+    reachable: 1, 5, 9, ... and of the windows this node offers, 5, 22, 39
+    and 56 land on 2, 7, 12 and 17 steps. The 1-frame window does not,
+    because the last step of a clip spans 4 frames, not 1.
+    """
+    k, covered = 0, 0
+    while covered < n:
+        covered += FRAME_PER_TOKEN[k % 5]
+        k += 1
+    return k if covered == n else None
+
+
+def _video_tail_from_latent(latent, n):
+    """Slice the last n pixel frames of video straight out of a generated
+    H3 latent, skipping the h264 decode and the VAE encode.
+
+    Returns (blocks, offsets, covered) in the same shape the encode path
+    produces, so everything downstream is unchanged.
+
+    This is only sound because the tail window always starts at cycle
+    position 0. A clip is 17g+5 frames, which is 5g+2 latent steps; the
+    windows are 2, 7, 12 and 17 steps; and 5g+2 minus any of those is a
+    multiple of 5. So the sliced run has the same 1, 4, 4, 4, 4 phase as a
+    freshly encoded one and _step_offsets applies unchanged. Asserted
+    below rather than assumed, because if it ever stopped holding the
+    pinned content would silently disagree with the positions written for
+    it and the join would land at the wrong instant.
+    """
+    video = _video_from_latent(latent)
+    total = int(video.shape[2])
+    steps = _steps_for_frames(n)
+    if steps is None:
+        raise ValueError(
+            "h3_motion_context: a %d frame window is not a whole number of "
+            "latent steps, so it cannot be sliced from a latent. Use 5, 22, "
+            "39 or 56, or unwire context_latent to encode pixels." % n)
+    if steps > total:
+        raise ValueError(
+            "h3_motion_context: asked for %d latent steps, context_latent "
+            "has %d." % (steps, total))
+    start = total - steps
+    if start % 5 != 0:
+        raise RuntimeError(
+            "h3_motion_context: the %d step tail of a %d step latent starts "
+            "at cycle position %d, not 0, so its frame spans would not match "
+            "the positions written for them. Clip lengths are meant to make "
+            "this impossible; refusing rather than rendering a shifted join."
+            % (steps, total, start % 5))
+    covered = _pixel_frames(steps)
+    if covered != n:
+        raise RuntimeError(
+            "h3_motion_context: %d steps cover %d frames, expected %d."
+            % (steps, covered, n))
+    blocks = [video[:1, :, start + k:start + k + 1].clone()
+              for k in range(steps)]
+    return blocks, _step_offsets(steps), covered
+
+
+def _audio_tail_from_latent(latent, a_frames):
+    """Slice the last `a_frames` worth of audio steps straight out of a
+    generated H3 latent, skipping the decode -> re-encode round trip.
+
+    Returns (tail latent [1, C, 2, rt], rt, overhang) where rt counts
+    40 Hz latent steps and overhang is the signed fraction of a step by
+    which the clip's audio grid overshoots its last pixel frame.
+
+    H3 rounds the audio grid to the NEAREST step, not up, so overhang is
+    negative for a third of legal clip lengths. 5/3 of a frame count
+    lands on .0, .333 or .667 and never on .5, so there are exactly three
+    cases:
+
+        frames % 3 == 0   243 wants 405.00, allocates 405, overhang    0
+        frames % 3 == 1   124 wants 206.67, allocates 207, overhang +1/3
+        frames % 3 == 2   260 wants 433.33, allocates 433, overhang -1/3
+
+    A positive overhang means the latent's final step reaches past the
+    last frame, a negative one means it stops short. Either way the
+    caller compensates the placement with it, so the pinned content lands
+    where its samples actually sit. The decoded-audio path never sees
+    this because match_tail cuts at the frame.
+    """
+    parts = _streams_from_latent(latent)
+    if len(parts) < 2:
+        raise ValueError(
+            "h3_motion_context: context_latent has no audio stream. Wire the "
+            "sampler output of an H3 AV graph, not a video-only latent.")
+    video, audio = parts[0], parts[1]
+    if video.ndim == 4:
+        video = video.unsqueeze(0)
+    if audio.ndim == 3:  # unbatched [C,2,T]
+        audio = audio.unsqueeze(0)
+    if audio.ndim != 4:
+        raise ValueError("h3_motion_context: expected audio latent [B,C,2,T], "
+                         "got shape %s" % (tuple(audio.shape),))
+    total_t = int(audio.shape[-1])
+    frames = _pixel_frames(int(video.shape[2]))
+    overhang = total_t - FRAME_RESCALE * frames
+    # legal values are exactly 0, +1/3 and -1/3; the band is the widest
+    # one that admits all three and still rejects a grid that is out by a
+    # whole step or more
+    if not (-0.5 < overhang < 0.5):
+        _LOG.warning(
+            "h3_motion_context: context_latent audio grid is unexpected "
+            "(%d steps for %d frames); assuming no overhang.", total_t, frames)
+        overhang = 0.0
+    rt = int(round(a_frames / float(FPS) * AUDIO_HZ))
+    if rt > total_t:
+        _LOG.warning("h3_motion_context: asked for %d audio steps, the latent "
+                     "has %d. Pinning all of it.", rt, total_t)
+        rt = total_t
+    if rt < 1:
+        raise ValueError("h3_motion_context: audio window is empty")
+    tail = audio[:1, ..., total_t - rt:].clone()
+    return tail, rt, float(overhang)
+
+
+class MiniMaxH3MotionContext:
+    @classmethod
+    def INPUT_TYPES(cls):
+        return {
+            "required": {
+                "conditioning": ("CONDITIONING",),
+                "vae": ("VAE",),
+                "latent": ("LATENT",),
+                "context_length": (["22", "5", "39", "56"], {
+                    "default": "22",
+                    "tooltip": "Frames of the previous clip's picture to "
+                               "carry over. Only these lengths are whole "
+                               "numbers of latent steps, so only these are "
+                               "offered. 5 is just barely fluid, 22 is "
+                               "nearly seamless. Longer windows pin more "
+                               "motion but come off the front of the "
+                               "delivered clip, so 56 spends 2.3 seconds of "
+                               "the render on frames you throw away."}),
+                "audio_context_length": ("INT", {
+                    "default": 24, "min": 0, "max": 240,
+                    "tooltip": "Frames of tail audio to pin, independent of "
+                               "the picture window. 0 follows it. The window "
+                               "is END-aligned with the pinned video, so "
+                               "this only controls how far back the sound "
+                               "reaches. Multiples of 3 land exactly on the "
+                               "40 Hz audio grid and multiples of 24 are "
+                               "whole seconds: 24 pins the last second. "
+                               "Off-grid values are widened to the nearest "
+                               "whole step."}),
+            },
+            "optional": {
+                "context_frames": ("IMAGE", {
+                    "tooltip": "Decoded frames of the previous clip. Used "
+                               "when no context_latent is wired. When one "
+                               "is, the picture comes from it instead and "
+                               "this is ignored."}),
+                "context_latent": ("LATENT", {
+                    "tooltip": "Previous clip's SAMPLER OUTPUT latent (the "
+                               "same one you wire into the decode nodes). "
+                               "Supplies both picture and sound, sliced "
+                               "straight out, skipping the decode and "
+                               "re-encode that cost a little quality at "
+                               "every link of a chain. Must be the same "
+                               "resolution as the clip being generated."}),
+                "audio_vae": ("VAE", {
+                    "tooltip": "H3 audio VAE. Supply with context_audio to "
+                               "carry the previous clip's tail sound across "
+                               "the join. Not needed when context_latent is "
+                               "wired."}),
+                "context_audio": ("AUDIO", {
+                    "tooltip": "Audio of the previous clip. The tail "
+                               "matching the pinned frames is encoded and "
+                               "pinned alongside them. Ignored when "
+                               "context_latent is wired."}),
+            },
+        }
+
+    RETURN_TYPES = ("CONDITIONING", "INT")
+    RETURN_NAMES = ("conditioning", "trim_frames")
+    FUNCTION = "apply"
+    CATEGORY = "conditioning/minimax"
+    DESCRIPTION = ("Pin a run of consecutive frames from a previous clip as "
+                   "never-denoised conditioning rows, so the model reads real "
+                   "motion instead of guessing it from a single still. With "
+                   "context_latent wired, both picture and sound are sliced "
+                   "from the previous clip's latent, skipping the decode and "
+                   "re-encode that cost a little quality at every link. A "
+                   "last_frame anchor on the incoming conditioning is kept "
+                   "and pinned alongside the head.")
+
+    def apply(self, conditioning, vae, latent, context_length,
+              audio_context_length=24, context_frames=None,
+              context_latent=None, audio_vae=None, context_audio=None):
+        if context_latent is None and context_frames is None:
+            return (conditioning, 0)
+        encode_mode, anchor_mode = ENCODE_MODE, ANCHOR_MODE
+        audio_mode, crop = AUDIO_MODE, CROP
+        context_length = int(context_length)
+        _ensure_layout_ok()
+
+        video = _video_from_latent(latent)
+        latent_t = int(video.shape[2])
+        width = int(video.shape[4]) * 16
+        height = int(video.shape[3]) * 16
+        frame_count = _pixel_frames(latent_t)
+
+        # Decide where the pinned VIDEO comes from before anything else,
+        # because it decides how many frames are even available. Slicing it
+        # out of the previous clip's latent removes an h264 decode and a
+        # VAE encode from the path, and the blocks come out bit-identical
+        # to what the model produced rather than a reconstruction of it.
+        # A wired latent supplies the picture as well as the sound: the
+        # pinned blocks are then exactly the steps the model produced,
+        # with no h264 decode, no resize and no VAE round trip to shift
+        # colour or contrast. Frames are the path when no latent is wired.
+        if context_latent is not None:
+            src_video = _video_from_latent(context_latent)
+            src_w = int(src_video.shape[4]) * 16
+            src_h = int(src_video.shape[3]) * 16
+            if src_w != width or src_h != height:
+                # a latent cannot be resized. Falling back to frames here
+                # would quietly take the lossy path on a graph the user
+                # thinks is fine, and a resolution change mid-chain is
+                # nearly always a mistake, so say so instead.
+                raise ValueError(
+                    "h3_motion_context: context_latent is %dx%d but this "
+                    "clip is %dx%d. A latent cannot be resized, so the "
+                    "previous clip has to be regenerated at this "
+                    "resolution, or the chain restarted here."
+                    % (src_w, src_h, width, height))
+            if int(src_video.shape[1]) != int(video.shape[1]):
+                raise ValueError(
+                    "h3_motion_context: context_latent has %d channels, "
+                    "this clip has %d. That is not an H3 video latent from "
+                    "the same model."
+                    % (int(src_video.shape[1]), int(video.shape[1])))
+            available = _pixel_frames(int(src_video.shape[2]))
+            video_src = "latent"
+        else:
+            available = int(context_frames.shape[0])
+            video_src = "pixels"
+
+        n = min(int(context_length), available)
+        if n < 1:
+            raise ValueError("h3_motion_context: no frames available to pin")
+        if n < context_length:
+            _LOG.warning("h3_motion_context: only %d frames available, pinning %d",
+                         available, n)
+
+        if encode_mode == "video":
+            # snap down to the VAE grid BEFORE slicing, so the frames encoded
+            # are exactly the frames the latent steps will cover (see
+            # VIDEO_RUN_GRID). Slicing the last n and letting the VAE keep the
+            # first `covered` of them would pin a run ending before the clip
+            # does, and the join would jump by the difference.
+            run = next(g for g in VIDEO_RUN_GRID if g <= n)
+            if run != n:
+                _LOG.warning(
+                    "h3_motion_context: %d frames is off the VAE grid; pinning "
+                    "the last %d instead (usable runs: 1, 5, 22, 39, 56)", n, run)
+            n = run
+
+        if n >= frame_count:
+            raise ValueError(
+                "h3_motion_context: asked to pin %d frames into a %d frame clip. "
+                "The pinned run must be a small fraction of the timeline."
+                % (n, frame_count))
+
+        if video_src == "latent" and _steps_for_frames(n) is None:
+            # every window the node offers is a whole number of steps, so
+            # reaching this means the grid moved underneath us
+            raise RuntimeError(
+                "h3_motion_context: a %d frame window is not a whole number "
+                "of latent steps. VIDEO_RUN_GRID no longer matches the "
+                "VAE; refusing rather than rendering a shifted join." % n)
+
+        if video_src == "latent":
+            blocks, offsets, covered = _video_tail_from_latent(
+                context_latent, n)
+            span = covered
+        else:
+            # the LAST n frames of the incoming clip become the pinned run
+            tail = _resize(context_frames[available - n:], width, height, crop)
+
+        if video_src == "pixels" and encode_mode == "video":
+            # one call; the VAE reads the batch axis as time and compresses
+            enc = vae.encode(tail)
+            if getattr(enc, "ndim", 0) != 5:
+                raise ValueError(
+                    "h3_motion_context: video-mode encode returned shape %s, "
+                    "expected [B,C,T,H,W]. Try encode_mode=frames."
+                    % (tuple(getattr(enc, "shape", ())),))
+            steps = int(enc.shape[2])
+            offsets = _step_offsets(steps)
+            covered = _pixel_frames(steps)
+            if covered != n:
+                # n was snapped to the grid above, so a mismatch here means
+                # the VAE's downscale formula changed underneath us and the
+                # pinned content no longer lines up with the positions we
+                # would write. Refuse rather than render a shifted join.
+                raise RuntimeError(
+                    "h3_motion_context: %d frames encoded to %d latent steps "
+                    "covering %d frames; the VAE grid no longer matches "
+                    "VIDEO_RUN_GRID. Upstream VAE change, refusing to run."
+                    % (n, steps, covered))
+            blocks = [enc[:, :, k:k + 1] for k in range(steps)]
+            span = covered
+        elif video_src == "pixels":
+            blocks, offsets = [], []
+            for i in range(n):
+                blocks.append(vae.encode(tail[i:i + 1]))
+                offsets.append(i)
+            span = n
+
+        if anchor_mode == "before":
+            indices = [o - span for o in offsets]
+        else:
+            indices = list(offsets)
+
+        keyframes = []
+        for p, blk in zip(indices, blocks):
+            # Straight to stock. `resolved_frame_index` is the real pixel
+            # frame the block sits at, which ComfyUI 0.33 accepts for any
+            # value, so there is nothing to smuggle and nothing to rewrite
+            # afterwards. One keyframe per latent step rather than a single
+            # multi-step block: `indices` already carries each step's real
+            # offset, which keeps the encode_mode=frames path (offsets
+            # 0..n-1, one still each) on exactly the same code. Stock lays
+            # a 1-step latent at cursor + FRAME_RESCALE * index either way,
+            # so the two forms produce identical rows.
+            keyframes.append({
+                "resolved_frame_index": p,
+                "latent": blk,
+            })
+
+        ref_audio_t = 0
+        audio_ref = None
+        audio_kf = None
+        audio_end_frame = None
+        a_frames = 0
+        audio_src = "off"
+        if context_latent is not None or context_audio is not None:
+            # the audio window is independent of the video one: audio cond
+            # rows cost rows but never cost delivered frames
+            a_frames = int(audio_context_length) or span
+            if context_latent is not None:
+                if context_audio is not None:
+                    _LOG.info("h3_motion_context: both context_latent and "
+                              "context_audio wired; using the latent (skips "
+                              "one VAE round trip).")
+                audio_latent, ref_audio_t, overhang = _audio_tail_from_latent(
+                    context_latent, a_frames)
+                audio_src = "latent"
+            else:
+                if audio_vae is None:
+                    raise ValueError(
+                        "h3_motion_context: context_audio supplied without "
+                        "audio_vae. Wire the H3 audio VAE, or wire "
+                        "context_latent instead.")
+                audio_latent, ref_audio_t = _encode_tail_audio(
+                    audio_vae, context_audio, a_frames / float(FPS))
+                overhang = 0.0  # decoded audio was match_tail-cut at the frame
+                audio_src = "vae"
+            if audio_mode == "timeline":
+                # end-align the audio window with the pinned video: both are
+                # the tail of clip A, so both must end at the same instant
+                # of the new timeline, frame `span` in head mode (where
+                # A's last frame sits), frame 0 in before mode. On the
+                # latent path the sliced content overshoots A's last
+                # frame by `overhang` of a step, signed, because H3
+                # rounds its audio grid to the nearest step and so falls
+                # short as often as it reaches past. The end coordinate
+                # moves by exactly that much, and a keyframe index is a
+                # plain multiplier so it takes a fractional frame.
+                end_frame = float(span if anchor_mode == "head" else 0)
+                end_frame += overhang / FRAME_RESCALE
+                # then snap the window onto the target's own audio grid.
+                # The end coordinate is FRAME_RESCALE * end_frame, and
+                # FRAME_RESCALE is 5/3, so unless that product happens to
+                # be a whole number the pinned rows land between the
+                # integer coordinates the target's audio rows occupy. A
+                # third of a step is 8.3 ms, which is the size of the
+                # constant late offset measured on chained clips. Whether
+                # it lands on or off the grid depends on the window
+                # length, the path, and the clip's own grid overhang, so
+                # it cycles rather than staying put. Rounding the end
+                # coordinate to the nearest integer costs at most a third
+                # of a step of placement and puts the pinned content on
+                # the same grid as the sound being generated from it.
+                end_coord = round(FRAME_RESCALE * end_frame)
+                end_frame = end_coord / FRAME_RESCALE
+                # Stock places a keyframe's audio window STARTING at
+                # FRAME_RESCALE * index past the target origin and running
+                # forward. We need it to END at the join, so the index is
+                # the start of a window `ref_audio_t` steps wide:
+                #
+                #   start coord = FRAME_RESCALE * end_frame - ref_audio_t
+                #   index       = end_frame - ref_audio_t / FRAME_RESCALE
+                #
+                # which is fractional, and negative whenever the window is
+                # longer than the pinned head, which it normally is. Both
+                # are legal arithmetic in the layout and neither is
+                # reachable through the stock Add Guide node, so
+                # layout_contract checks them before the first render.
+                audio_kf = {
+                    "resolved_frame_index": (end_frame
+                                             - ref_audio_t / FRAME_RESCALE),
+                    "audio_latent": audio_latent,
+                }
+                audio_end_frame = end_frame
+            else:
+                # stock reference placement: the window sits in its own
+                # span ahead of the target, which is what makes the model
+                # imitate the sound rather than continue it. Kept as the
+                # comparison the timeline mode is measured against.
+                audio_ref = {
+                    "kind": "audio",
+                    "ref_audio_t": ref_audio_t,
+                    "audio_latent": audio_latent,
+                }
+
+        # MERGE with any keyframes already on the conditioning instead of
+        # replacing them. A last_frame anchor from the upstream node, or an
+        # Add Guide anchor, is a legitimate companion to a chained head: the
+        # pinned run decides how the clip starts, the anchor decides where
+        # it ends. They need no special handling now that every keyframe
+        # carries its real index, ours included, and stock compensates all
+        # of them for references the same way.
+        #
+        # Anchors inside the pinned head are dropped: the pinned run
+        # already decides those frames, and a second cond block at the
+        # same coordinate would fight it.
+        head_end = span if anchor_mode == "head" else 0
+        tail_kfs = [audio_kf] if audio_kf is not None else []
+        out = []
+        dropped = []
+        for emb, extra in conditioning:
+            d = extra.copy()
+            prior = d.get("minimax_keyframes") or []
+            kept = []
+            for kf in prior:
+                p = kf.get("resolved_frame_index", 0)
+                if p >= frame_count:
+                    raise ValueError(
+                        "h3_motion_context: the conditioning carries a "
+                        "keyframe anchored at frame %s, but this clip is "
+                        "only %d frames. Wire the conditioning and the "
+                        "latent from the same node." % (p, frame_count))
+                if p < head_end:
+                    dropped.append(p)
+                    continue
+                kept.append(dict(kf))
+            d["minimax_keyframes"] = kept + keyframes + tail_kfs
+            out.append([emb, d])
+        if dropped:
+            _LOG.warning(
+                "h3_motion_context: dropped %d keyframe anchor(s) at "
+                "frame(s) %s: the pinned head already decides frames "
+                "0..%d. A last_frame anchor is kept.",
+                len(dropped), sorted(set(dropped)), head_end - 1)
+
+        if audio_ref is not None:
+            out = node_helpers.conditioning_set_values(
+                out, {"minimax_refs": [audio_ref]}, append=True)
+
+        trim = span if anchor_mode == "head" else 0
+        _LOG.info("h3_motion_context: video from %s, %s/%s, %d frames -> %d "
+                  "cond blocks at indices %d..%d, %d frame clip at %dx%d, "
+                  "trim %d, audio %s",
+                  video_src, encode_mode, anchor_mode, n, len(blocks),
+                  indices[0], indices[-1], frame_count, width, height, trim,
+                  ("%d frames -> %d latent steps (%.3fs) from %s, %s"
+                   % (a_frames, ref_audio_t, ref_audio_t / AUDIO_HZ, audio_src,
+                      "on the timeline ending at frame %.3f" % audio_end_frame
+                      if audio_end_frame is not None
+                      else "stock ref placement"))
+                  if ref_audio_t else "off")
+        return (out, trim)
+
+
+class MiniMaxH3MotionContextTrim:
+    """Drop the pinned head off a decoded clip, picture and sound together.
+
+    The pinned frames occupy the start of the delivered timeline, so they
+    have to come off before concatenating. Trimming only the images would
+    leave the audio a full trim_frames longer than the video, and muxing
+    those puts the whole soundtrack ahead of the picture by trim_frames/24
+    seconds. At 5 frames that is 208ms, silent on ambience but squarely
+    offbeat on anything with a pulse.
+
+    So this takes both streams and removes the same span from each: whole
+    frames from the images, the matching number of samples from the
+    waveform. Wire trim_frames from the motion context node so the count
+    follows whatever the encoder actually produced.
+
+    The tail needs the same treatment for a different reason. H3's audio
+    latent runs at 40 Hz against 24 fps picture, and FRAME_RESCALE is 5/3,
+    so the grid rarely lands on a frame boundary. It rounds to the
+    NEAREST step, which means a clip ships either about 8.3 ms more sound
+    than picture or about 8.3 ms less, depending on its length:
+
+        frames % 3 == 0   243 wants 405.00 steps, gets 405, exact
+        frames % 3 == 1   124 wants 206.67 steps, gets 207, sound is long
+        frames % 3 == 2   260 wants 433.33 steps, gets 433, sound is short
+
+    Either way the error compounds. Concatenate two clips and the second
+    seam is out by 16.7 ms, three and it is 25 ms, and it grows without
+    bound down a chain. It reads as a faint dampening at the first join
+    and a short click at later ones. Matching the tail to exactly
+    frames/fps stops it accumulating: a long tail is truncated, a short
+    one is zero-padded. The padded samples are sound the model never
+    generated, so silence is the only honest fill.
+    """
+
+    @classmethod
+    def INPUT_TYPES(cls):
+        return {
+            "required": {
+                "images": ("IMAGE",),
+                "trim_frames": ("INT", {"default": 0, "min": 0, "max": 4096}),
+            },
+            "optional": {
+                "audio": ("AUDIO", {
+                    "tooltip": "Decoded audio for the same clip. Trimmed by the "
+                               "matching duration so sound stays locked to "
+                               "picture. Leave unwired for silent clips."}),
+                "fps": ("FLOAT", {
+                    "default": 24.0, "min": 1.0, "max": 240.0, "step": 0.001,
+                    "tooltip": "Frame rate used to convert the trim into an "
+                               "audio duration. Must match what you feed "
+                               "Create Video."}),
+                "match_tail": ("BOOLEAN", {
+                    "default": True,
+                    "tooltip": "Make the audio duration equal frames/fps "
+                               "exactly, trimming a long tail or padding a "
+                               "short one with silence. H3 rounds its audio "
+                               "grid to the nearest step, so each clip "
+                               "carries about 8ms too much or too little "
+                               "sound, which accumulates at every join in a "
+                               "chain."}),
+            },
+        }
+
+    RETURN_TYPES = ("IMAGE", "AUDIO")
+    RETURN_NAMES = ("images", "audio")
+    FUNCTION = "trim"
+    CATEGORY = "conditioning/minimax"
+    DESCRIPTION = ("Remove the leading pinned frames from a decoded H3 clip, "
+                   "trimming picture and sound by the same duration.")
+
+    def trim(self, images, trim_frames, audio=None, fps=24.0, match_tail=True):
+        n = max(0, int(trim_frames))
+        total = int(images.shape[0])
+        if n >= total:
+            raise ValueError(
+                "h3_motion_context: asked to trim %d frames from a %d frame clip"
+                % (n, total))
+        out_images = images[n:] if n else images
+
+        out_audio = audio
+        if audio is not None:
+            waveform = audio["waveform"]
+            sr = int(audio["sample_rate"])
+            seconds = n / float(fps)
+            cut = int(round(seconds * sr))
+            length = int(waveform.shape[-1])
+            if cut >= length:
+                raise ValueError(
+                    "h3_motion_context: trimming %.3fs from %.3fs of audio would "
+                    "leave nothing. Check that fps matches the clip."
+                    % (seconds, length / sr))
+            waveform = waveform[..., cut:]
+
+            if match_tail:
+                frames_left = total - n
+                want = int(round(frames_left / float(fps) * sr))
+                have = int(waveform.shape[-1])
+                if have > want:
+                    over = have - want
+                    waveform = waveform[..., :want]
+                    _LOG.info("h3_motion_context: tail trimmed %d samples "
+                              "(%.2fms) so audio matches %d frames exactly",
+                              over, over / sr * 1000.0, frames_left)
+                elif have < want:
+                    # H3 rounds to the nearest audio step, so a third of
+                    # clip lengths ship slightly LESS sound than picture
+                    # rather than more. The missing samples are sound
+                    # that was never generated, so zero is the honest
+                    # fill; anything else would fabricate or attenuate
+                    # real content to hide a seam. Leaving it short
+                    # instead drifts every later clip earlier, and unlike
+                    # the long case that error compounds down the chain.
+                    # This also restores what the vae path assumes when
+                    # it sets overhang to 0.
+                    missing = want - have
+                    waveform = torch.nn.functional.pad(waveform,
+                                                       (0, missing))
+                    _LOG.info("h3_motion_context: tail padded %d zero "
+                              "samples (%.2fms) so audio matches %d "
+                              "frames exactly",
+                              missing, missing / sr * 1000.0, frames_left)
+
+            out_audio = {"waveform": waveform, "sample_rate": sr}
+            _LOG.info("h3_motion_context: %d frames / %.4fs picture, %.4fs sound, "
+                      "drift %.2fms",
+                      total - n, (total - n) / float(fps),
+                      int(waveform.shape[-1]) / sr,
+                      abs((total - n) / float(fps) - int(waveform.shape[-1]) / sr) * 1000.0)
+        elif n:
+            _LOG.info("h3_motion_context: trimmed %d leading frames, %d remain. "
+                      "No audio wired; if this clip has sound, mux it through "
+                      "this node or it will run %.3fs ahead of the picture.",
+                      n, total - n, n / float(fps))
+
+        return (out_images, out_audio)
+
+
+def _under_output(path):
+    """Resolve `path` inside ComfyUI's output folder. None if it would escape.
+
+    Absolute paths are allowed only when they already live under output/.
+    Relative paths join onto output/. This is what keeps latent_path from
+    becoming an arbitrary file read or a delete-anywhere on Clear.
+    """
+    root = os.path.realpath(folder_paths.get_output_directory())
+    p = (path or "").strip().strip('"').strip("'") or "h3_context"
+    resolved = os.path.realpath(p if os.path.isabs(p) else os.path.join(root, p))
+    if resolved != root and not resolved.startswith(root + os.sep):
+        return None
+    return resolved
+
+
+def _resolve_latent_path(path, clip_index=0):
+    """Turn the loader's path input into a concrete file under output/.
+
+    Accepts a path relative to ComfyUI's output folder, an absolute path
+    that already lives there, or a directory in either form. For a
+    directory, clip_index must be a positive slot: clip 1 is
+    *_00001.safetensors. Auto-mode files carry a trailing underscore
+    (*_00001_.safetensors) and are never matched, because their numbers
+    count runs and could hold a reject. clip_index 0 is handled by the
+    Load node itself (no file, first clip).
+    """
+    c = _under_output(path)
+    if not c:
+        raise FileNotFoundError(
+            "h3_motion_context: path must stay inside the ComfyUI output folder.")
+    if os.path.isfile(c):
+        return c
+    if os.path.isdir(c):
+        idx = int(clip_index)
+        if idx <= 0:
+            raise FileNotFoundError(
+                "h3_motion_context: clip_index 0 does not load a file.")
+        # indexed slots use the natural name: clip 2 lives in
+        # *_00002.safetensors. Auto-mode files carry a trailing
+        # underscore (*_00002_.safetensors) and are deliberately
+        # NOT matched: their numbers count runs, not clips, so a
+        # reject could be sitting in any of them.
+        endings = ("_%05d.safetensors" % idx,
+                   "_clip%03d.safetensors" % idx)  # older versions
+        files = [os.path.join(c, f) for f in os.listdir(c)
+                 if f.endswith(endings)]
+        if not files:
+            near = [f for f in os.listdir(c)
+                    if f.endswith("_%05d_.safetensors" % idx)]
+            hint = ""
+            if near:
+                hint = (" Found %s, which is an auto-numbered save "
+                        "(trailing underscore = numbered by RUN, so "
+                        "it may be a reject). If it really is clip "
+                        "%d, rename it to drop the trailing "
+                        "underscore: %s" %
+                        (near[0], idx,
+                         near[0].replace("_%05d_" % idx,
+                                         "_%05d" % idx)))
+            raise FileNotFoundError(
+                "h3_motion_context: no saved latent for clip %d "
+                "(no *_%05d.safetensors in %s).%s"
+                % (idx, idx, c, hint))
+        return max(files, key=os.path.getmtime)
+    raise FileNotFoundError(
+        "h3_motion_context: %r is neither a file nor a folder under the "
+        "ComfyUI output directory." % ((path or "").strip() or "h3_context"))
+
+
+def _latent_folder(path):
+    """Directory that holds this chain's slot files, or None.
+
+    Refuses anything outside ComfyUI's output folder so Clear cannot
+    delete numbered safetensors elsewhere on disk.
+    """
+    c = _under_output(path)
+    if not c:
+        return None
+    if os.path.isdir(c):
+        return c
+    if os.path.isfile(c):
+        return os.path.dirname(c)
+    return None
+
+
+def _clip_slot_exists(latent_path, clip_index=1):
+    try:
+        _resolve_latent_path(latent_path, int(clip_index))
+        return True
+    except FileNotFoundError:
+        return False
+
+
+_CHAIN_SLOT_FILE = re.compile(
+    r"(?:_\d{5}|_\d{5}_|_clip\d{3})\.safetensors(?:\.tmp)?$"
+)
+
+
+def _clear_clip_slots(latent_path):
+    """Delete numbered chain slots. Custom filenames are left alone."""
+    folder = _latent_folder(latent_path)
+    if not folder:
+        return 0
+    removed = 0
+    for name in os.listdir(folder):
+        if not _CHAIN_SLOT_FILE.search(name):
+            continue
+        fp = os.path.join(folder, name)
+        try:
+            os.remove(fp)
+        except OSError:
+            gc.collect()
+            os.remove(fp)
+        removed += 1
+    if removed:
+        _LOG.info("h3_motion_context: cleared %d chain slot(s) from %s",
+                  removed, folder)
+    return removed
+
+
+def register_chain_routes():
+    """POST slot_exists / clear_latents for the Chain node's start and Clear."""
+    try:
+        from aiohttp import web
+        from server import PromptServer
+    except ImportError:
+        return
+    server = getattr(PromptServer, "instance", None)
+    if server is None or getattr(register_chain_routes, "_done", False):
+        return
+
+    from .csrf_guard import require_same_origin
+
+    @server.routes.post("/h3_motion_context/slot_exists")
+    @require_same_origin
+    async def _slot_exists_route(request):
+        data = await request.json()
+        exists = _clip_slot_exists(data.get("latent_path") or "h3_context",
+                                   int(data.get("clip_index") or 1))
+        return web.json_response({"exists": exists})
+
+    @server.routes.post("/h3_motion_context/clear_latents")
+    @require_same_origin
+    async def _clear_latents_route(request):
+        data = await request.json()
+        n = _clear_clip_slots(data.get("latent_path") or "h3_context")
+        return web.json_response({"removed": n})
+
+    register_chain_routes._done = True
+
+
+def _write_safetensors(path, tensors):
+    # safetensors load_file memory-maps on Windows. Overwriting a mapped
+    # slot (re-roll, or Load 0 aimed at the file Save is about to replace)
+    # fails with os error 1224. Write a sibling temp file and replace.
+    tmp = path + ".tmp"
+    try:
+        _st_save(tensors, tmp,
+                 metadata={"format": "h3_motion_context_av_v1"})
+        try:
+            os.replace(tmp, path)
+        except OSError:
+            gc.collect()
+            os.replace(tmp, path)
+    finally:
+        try:
+            os.remove(tmp)
+        except OSError:
+            pass
+
+
+class MiniMaxH3MotionContextSaveLatent:
+    """Save an H3 AV latent to disk so the NEXT run can load it.
+
+    Wiring the sampler's output straight into context_latent is a cycle:
+    the sampler would be consuming its own result. The latent that motion
+    context needs is the PREVIOUS clip's, which lives in the previous run
+    -- so it has to cross runs through disk, the same way the frames and
+    audio already do. Stock Save/Load Latent can't serialise H3's nested
+    video/audio pair; this saves the two streams side by side.
+    """
+
+    @classmethod
+    def INPUT_TYPES(cls):
+        return {
+            "required": {
+                "latent": ("LATENT", {
+                    "tooltip": "The sampler's output latent (the same one "
+                               "you wire into the decode nodes)."}),
+                "filename_prefix": ("STRING", {
+                    "default": "h3_context/clip",
+                    "tooltip": "Saved under the ComfyUI output folder. The "
+                               "default keeps all chain latents in one "
+                               "folder so the Load node can always pick "
+                               "the newest."}),
+                "clip_index": ("INT", {
+                    "default": 1, "min": 0, "max": 9999, "step": 1,
+                    "tooltip": "Which clip of the chain THIS is. Saves to "
+                               "that clip's fixed slot, so a re-roll "
+                               "overwrites its own reject instead of "
+                               "stacking new files. First clip: 1 here "
+                               "and 0 on the Load node. Clip 2: 2 here "
+                               "and 1 on the Load node. 0 = old behaviour, "
+                               "a new numbered file every run (numbers "
+                               "count runs, not clips)."}),
+            },
+        }
+
+    RETURN_TYPES = ("STRING",)
+    RETURN_NAMES = ("latent_path",)
+    FUNCTION = "save"
+    OUTPUT_NODE = True
+    CATEGORY = "conditioning/minimax"
+    DESCRIPTION = ("Save the sampler's AV latent so the next run's Motion "
+                   "Context node can pin audio from it via the matching "
+                   "Load node.")
+
+    def save(self, latent, filename_prefix, clip_index=0):
+        if _st_save is None:
+            raise RuntimeError("h3_motion_context: safetensors is not "
+                               "available; cannot save latents.")
+        parts = _streams_from_latent(latent)
+        if len(parts) < 2:
+            raise ValueError(
+                "h3_motion_context: latent has no audio stream; wire the "
+                "sampler output of an H3 AV graph.")
+        video = parts[0].cpu().contiguous()
+        audio = parts[1].cpu().contiguous()
+        folder, filename, counter, _, _ = folder_paths.get_save_image_path(
+            filename_prefix, folder_paths.get_output_directory())
+        if int(clip_index) > 0:
+            # fixed slot with the natural name: clip 2 -> *_00002. A
+            # re-roll of this clip overwrites its own save, so rejects
+            # never accumulate or get loaded later. Auto mode (below)
+            # keeps a trailing underscore, which is what excludes its
+            # run-numbered files from indexed loading.
+            path = os.path.join(folder, "%s_%05d.safetensors"
+                                % (filename, int(clip_index)))
+        else:
+            path = os.path.join(folder, "%s_%05d_.safetensors"
+                                % (filename, counter))
+        _write_safetensors(path, {"video": video, "audio": audio})
+        _LOG.info("h3_motion_context: saved AV latent to %s (video %s, "
+                  "audio %s)", path, tuple(video.shape), tuple(audio.shape))
+        return (path,)
+
+
+class MiniMaxH3MotionContextLoadLatent:
+    """Load a saved H3 AV latent for the context_latent input.
+
+    clip_index means exactly what it says: set it to the clip you want to
+    CONTINUE FROM, and that clip's slot is loaded. Generating clip 2 from
+    clip 1: Load node 1, Save node 2. Use H3 Motion Context Chain to
+    advance the pair and queue: Approve walks forward, Run/Re-roll stays
+    on the current slot (use it instead of ComfyUI's Run), Chain is
+    Approve on a loop (at 0/1 with no clip 1 yet it generates that
+    first), Reset sets Load 0 / Save 1, Clear latents deletes numbered
+    slots. All three nodes must sit in the same canvas group.
+
+    At 0 there is no previous clip: the loader returns nothing and Motion
+    Context passes the conditioning through. First clip of a chain is
+    Load 0 / Save 1, then Load 1 / Save 2, and so on.
+
+    The output is ONLY for the Motion Context node's context_latent input.
+    It is not a decodable latent -- do not wire it into VAE decode.
+    """
+
+    @classmethod
+    def INPUT_TYPES(cls):
+        return {
+            "required": {
+                "latent_path": ("STRING", {
+                    "default": "h3_context",
+                    "tooltip": "A saved latent file, or a folder (relative "
+                               "paths resolve against the ComfyUI output "
+                               "directory). Pointing at a specific FILE "
+                               "always loads that file when clip_index "
+                               "is greater than 0, ignoring the index. "
+                               "clip_index 0 never reads a file."}),
+                "clip_index": ("INT", {
+                    "default": 0, "min": 0, "max": 9999, "step": 1,
+                    "tooltip": "The clip to CONTINUE FROM: that clip's "
+                               "slot is loaded. First clip: 0 here and 1 "
+                               "on the Save node (nothing is loaded). "
+                               "Clip 2 from clip 1: 1 here and 2 on the "
+                               "Save node."}),
+            },
+        }
+
+    RETURN_TYPES = ("LATENT",)
+    FUNCTION = "load"
+    CATEGORY = "conditioning/minimax"
+    DESCRIPTION = ("Load a latent saved by H3 Motion Context Save Latent, "
+                   "for the context_latent input only.")
+
+    @classmethod
+    def IS_CHANGED(cls, latent_path, clip_index=0):
+        # the path string stays constant while the file behind it changes
+        # (an overwritten slot), so cache on the resolved file identity
+        # instead -- otherwise ComfyUI would happily serve a stale latent
+        # forever. Index 0 never reads a file.
+        if int(clip_index) <= 0:
+            return "disabled"
+        try:
+            p = _resolve_latent_path(latent_path, clip_index)
+            return "%s:%d:owned" % (p, os.stat(p).st_mtime_ns)
+        except Exception:
+            return float("NaN")  # unresolvable: never cache
+
+    def load(self, latent_path, clip_index=0):
+        if int(clip_index) <= 0:
+            return (None,)
+        if _st_load is None:
+            raise RuntimeError("h3_motion_context: safetensors is not "
+                               "available; cannot load latents.")
+        path = _resolve_latent_path(latent_path, clip_index)
+        data = _st_load(path)
+        if "video" not in data or "audio" not in data:
+            raise ValueError(
+                "h3_motion_context: %s is not an h3_motion_context latent "
+                "(missing video/audio streams). Was it saved by the stock "
+                "Save Latent node instead?" % path)
+        # copy off the mmap so a later Save can overwrite this slot on Windows
+        video = data.pop("video").contiguous().clone()
+        audio = data.pop("audio").contiguous().clone()
+        _LOG.info("h3_motion_context: loaded AV latent from %s", path)
+        # a plain list, not a NestedTensor: only this repo's context_latent
+        # input accepts it, which is the point -- it cannot be mistaken
+        # for a decodable latent without failing loudly downstream
+        return ({"samples": [video, audio]},)
+
+
+class MiniMaxH3MotionContextChain:
+    """Approve, Run/Re-roll, auto-chain, reset indices, or clear slots.
+
+    Load, Save, and this node must sit in the same canvas group or the
+    buttons do nothing. Chain is Approve on a loop. At Load 0 / Save 1
+    with no clip 1 on disk it generates that first clip instead of
+    advancing into a missing file. segments > 0 stops Chain after that
+    many clips; 0 keeps going until Stop. Reset only sets 0/1. Clear
+    latents deletes numbered chain slots, not custom filenames.
+    Execute is a no-op; the buttons and two HTTP routes do the work.
+    """
+
+    @classmethod
+    def INPUT_TYPES(cls):
+        return {
+            "required": {
+                "segments": ("INT", {
+                    "default": 0, "min": 0, "max": 9999, "step": 1,
+                    "tooltip": "How many clips Chain generates before it "
+                               "stops. 0 keeps going until you click Stop."
+                }),
+            },
+        }
+
+    RETURN_TYPES = ()
+    FUNCTION = "noop"
+    OUTPUT_NODE = True
+    CATEGORY = "conditioning/minimax"
+    DESCRIPTION = ("Approve advances Load/Save and runs the next clip. "
+                   "Run/Re-roll queues the current slot (use this instead "
+                   "of ComfyUI's Run). Chain is Approve on a loop; at "
+                   "Load 0 / Save 1 with no clip 1 saved it generates "
+                   "clip 1 first. segments is how many clips Chain runs "
+                   "before stopping (0 = until Stop). Reset sets Load 0 / "
+                   "Save 1. Clear latents deletes numbered chain slots. "
+                   "Load, Save, and this node must sit in the same canvas "
+                   "group or the buttons do nothing.")
+
+    def noop(self, segments=0):
+        return ()
+
+
+NODE_CLASS_MAPPINGS = {
+    "MiniMaxH3MotionContext": MiniMaxH3MotionContext,
+    "MiniMaxH3MotionContextTrim": MiniMaxH3MotionContextTrim,
+    "MiniMaxH3MotionContextSaveLatent": MiniMaxH3MotionContextSaveLatent,
+    "MiniMaxH3MotionContextLoadLatent": MiniMaxH3MotionContextLoadLatent,
+    "MiniMaxH3MotionContextChain": MiniMaxH3MotionContextChain,
+}
+NODE_DISPLAY_NAME_MAPPINGS = {
+    "MiniMaxH3MotionContext": "H3 Motion Context",
+    "MiniMaxH3MotionContextTrim": "H3 Motion Context Trim",
+    "MiniMaxH3MotionContextSaveLatent": "H3 Motion Context Save Latent",
+    "MiniMaxH3MotionContextLoadLatent": "H3 Motion Context Load Latent",
+    "MiniMaxH3MotionContextChain": "H3 Motion Context Chain",
+}

custom_nodes/ComfyUI-H3-Motion-Context-main/probe_node.py

@@ -0,0 +1,446 @@
+"""Seam probe node: measure a join without leaving the graph.
+
+seam_probe.py and level_step.py answer the two questions that matter at a
+join, but both work on rendered files and both have to infer where the
+seam is. That inference is the source of the constant ~8ms lag the CLI
+probe reports: anchoring on a file's end rather than on the frame the
+picture actually ends at is off by exactly the audio grid overhang, which
+is a third of a step.
+
+This node does not have to infer anything. It takes clip A as the same
+latent you already pin from, and clip B before the trim, so the seam is
+at a known sample and the pinned span is given rather than guessed. It
+decodes A's audio and applies match_tail itself, which matters: comparing
+against an untrimmed clip A would move the anchor by the overhang and
+hand back a very convincing lag that is purely an artifact. Doing it
+inside the node means that cannot be got wrong from the canvas.
+
+Wire it inline: the audio VAE decode feeds this node, and this node feeds
+the trim. The audio output is the input unchanged, so dropping it into an
+existing chain changes nothing about the render.
+
+    clip_a_latent      the same latent wired into Motion Context's
+                       context_latent
+    audio_vae          the same audio VAE
+    clip_b_untrimmed   this clip's audio off the VAE decode, before trim
+    trim_frames        from Motion Context, the same value the trim gets
+
+Reported per join:
+
+    lag_ms    how far B's reconstruction of the pinned span runs behind
+              A's original. Positive means B is late.
+    corr      normalised cross-correlation over the pinned span. 1.0 is
+              identical shape, ~0 is unrelated. Low corr means the model
+              is imitating rather than continuing.
+    broadband RMS step across the cut, normalised to [0, 1].
+    floor     the same for the 10th-percentile short-window RMS, which
+              tracks the bed under the content. This is the one that
+              catches a clip inventing its own silence.
+
+Thresholds in the summary are the ones documented in the two scripts, not
+new judgments. Numbers are always reported; the labels are a reading aid.
+
+One limitation to know before trusting a lag figure. Cross-correlation
+cannot tell a true alignment from one a whole cycle away, so on strongly
+periodic content a lag larger than half a period reads as the nearest
+alias instead: a 60 ms offset on material with an 18 ms period comes back
+as -12.7 ms, confidently and at high correlation. Beat-driven music is
+exactly this case. The tracker follows continuity between windows so a
+drift cannot cycle-hop mid-span, and the first window takes the global
+peak rather than assuming zero, which is what lets a uniform whole-step
+offset be seen at all. But a large uniform offset on periodic content is
+not something the method can resolve. Read a small lag as reliable and a
+large one as "at least this much, possibly plus a whole number of
+cycles".
+"""
+
+import logging
+
+import numpy as np
+
+from .nodes import FPS, _pixel_frames, _streams_from_latent
+
+_LOG = logging.getLogger("h3_motion_context")
+
+# from seam_probe.py: a match below this is not credible enough to track
+CORR_CREDIBLE = 0.6
+# from level_step.py
+FLOOR_CLEAN, FLOOR_MARGINAL = 0.25, 0.50
+BROADBAND_OK = 0.40
+
+
+def _mono(waveform):
+    """Any [.., C, L] or [.., L, C] audio tensor -> mono float64 numpy.
+
+    The audio VAE's decode output orientation is not something to assume,
+    so the channel axis is identified by being the short one rather than
+    by position. Audio is thousands of samples long and at most a handful
+    of channels wide, so this is unambiguous in practice.
+    """
+    a = waveform
+    if hasattr(a, "detach"):
+        a = a.detach()
+    if hasattr(a, "cpu"):
+        a = a.cpu()
+    a = np.asarray(a, dtype=np.float64)
+    while a.ndim > 2:
+        a = a[0]
+    if a.ndim == 2:
+        axis = 0 if a.shape[0] <= a.shape[1] else 1
+        a = a.mean(axis=axis)
+    return a
+
+
+def _norm_xcorr(win, ref):
+    """Slide `win` across `ref`; return normalised correlation curve."""
+    win = win - win.mean()
+    ref = ref - ref.mean()
+    wn = np.sqrt((win ** 2).sum())
+    if wn < 1e-12:
+        return None
+    corr = np.correlate(ref, win, mode="valid")
+    csum = np.concatenate(([0.0], np.cumsum(ref ** 2)))
+    seg = csum[len(win):] - csum[:-len(win)]
+    denom = wn * np.sqrt(np.maximum(seg, 1e-12))
+    return corr / denom
+
+
+def _tracked_peak(ncc, expect_idx):
+    """Pick the alignment closest to the previous window's, among local
+    maxima within 10% of the best. Music is periodic, so the global argmax
+    can hop a whole cycle between windows and read as drift."""
+    best = float(ncc.max())
+    i = np.arange(1, len(ncc) - 1)
+    peaks = i[(ncc[i] >= ncc[i - 1]) & (ncc[i] >= ncc[i + 1]) &
+              (ncc[i] >= 0.9 * best)]
+    if len(peaks) == 0:
+        peaks = np.array([int(np.argmax(ncc))])
+    pick = int(peaks[np.argmin(np.abs(peaks - expect_idx))])
+    return pick, float(ncc[pick])
+
+
+def _rms(x):
+    if len(x) == 0:
+        return 0.0
+    return float(np.sqrt(np.mean(np.square(x))))
+
+
+def _floor_level(x, sr, win_ms=20.0, pct=10.0):
+    """A low percentile of short-window RMS: the bed under the content."""
+    win = max(1, int(round(win_ms / 1000.0 * sr)))
+    n = len(x) // win
+    if n < 3:
+        return _rms(x)
+    trimmed = x[:n * win].reshape(n, win)
+    levels = np.sqrt(np.mean(np.square(trimmed), axis=1))
+    return float(np.percentile(levels, pct))
+
+
+def _step_ratio(a, b):
+    denom = a + b
+    if denom <= 1e-12:
+        return 0.0
+    return abs(a - b) / denom
+
+
+def _db(a, b):
+    if a <= 1e-12 or b <= 1e-12:
+        return float("inf")
+    return abs(20.0 * np.log10(a / b))
+
+
+class MiniMaxH3MotionContextSeamProbe:
+    """Measure a chain join: continuation quality and level step."""
+
+    @classmethod
+    def INPUT_TYPES(cls):
+        return {
+            "required": {
+                "clip_b_untrimmed": ("AUDIO", {
+                    "tooltip": "This clip's audio straight off the VAE "
+                               "decode, BEFORE the trim node. It still "
+                               "carries the pinned head, which is what "
+                               "gets compared."}),
+                "trim_frames": ("INT", {
+                    "default": 0, "min": 0, "max": 4096,
+                    "tooltip": "Wire this from the Motion Context node's "
+                               "trim output, the same value the trim node "
+                               "gets. It is the pinned span."}),
+            },
+            "optional": {
+                "clip_a_latent": ("LATENT", {
+                    "tooltip": "The PREVIOUS clip's AV latent: the same "
+                               "one wired into Motion Context's "
+                               "context_latent. The node decodes and "
+                               "tail-matches it itself. Without it only "
+                               "clip B is described, nothing is "
+                               "measured."}),
+                "audio_vae": ("VAE", {
+                    "tooltip": "The H3 audio VAE, needed to decode clip "
+                               "A's audio out of its latent."}),
+                "fps": ("FLOAT", {
+                    "default": 24.0, "min": 1.0, "max": 240.0,
+                    "step": 0.001,
+                    "tooltip": "Must match what you feed Create Video."}),
+                "window_ms": ("FLOAT", {
+                    "default": 50.0, "min": 5.0, "max": 500.0,
+                    "step": 1.0,
+                    "tooltip": "Correlation analysis window."}),
+                "search_ms": ("FLOAT", {
+                    "default": 40.0, "min": 5.0, "max": 500.0,
+                    "step": 1.0,
+                    "tooltip": "Maximum lag searched either side."}),
+            },
+        }
+
+    RETURN_TYPES = ("AUDIO", "STRING")
+    RETURN_NAMES = ("audio", "report")
+    OUTPUT_TOOLTIPS = (
+        "clip_b_untrimmed, unchanged. Wire it on to the trim node.",
+        "The measurement report, for a Preview Text node.",
+    )
+    FUNCTION = "probe"
+    CATEGORY = "conditioning/minimax"
+    OUTPUT_NODE = True
+    DESCRIPTION = ("Measure a chain join in the graph: does clip B "
+                   "continue clip A's audio, and does the level step at "
+                   "the cut.")
+
+    def probe(self, clip_b_untrimmed, trim_frames, clip_a_latent=None,
+              audio_vae=None, fps=24.0, window_ms=50.0, search_ms=40.0):
+        passthrough = clip_b_untrimmed
+        sr = int(clip_b_untrimmed["sample_rate"])
+        b = _mono(clip_b_untrimmed["waveform"])
+        span_s = max(0, int(trim_frames)) / float(fps)
+        span = int(round(span_s * sr))
+
+        lines = ["H3 seam probe",
+                 "clip B (untrimmed): %.4fs at %d Hz" % (len(b) / sr, sr),
+                 "pinned span: %d frames = %.4fs = %d samples"
+                 % (int(trim_frames), span_s, span)]
+
+        if span <= 0:
+            lines += ["", "trim_frames is 0, so there is no pinned span "
+                          "and nothing to measure. Wire it from the "
+                          "Motion Context node."]
+            return self._finish(passthrough, lines)
+        if len(b) < span:
+            lines += ["", "clip B is shorter than the pinned span. This "
+                          "is the TRIMMED audio; wire the VAE decode "
+                          "output instead."]
+            return self._finish(passthrough, lines)
+        if clip_a_latent is None or audio_vae is None:
+            missing = "clip_a_latent" if clip_a_latent is None else "audio_vae"
+            lines += ["", "no %s wired: measuring the join needs the "
+                          "previous clip's latent and the audio VAE to "
+                          "decode it." % missing]
+            return self._finish(passthrough, lines)
+
+        try:
+            a, raw, frames = self._clip_a_audio(clip_a_latent, audio_vae,
+                                                sr, fps)
+        except ValueError as exc:
+            lines += ["", str(exc)]
+            return self._finish(passthrough, lines)
+
+        pad = len(a) - len(raw)
+        lines.append("clip A: %d frames, decoded %.4fs, tail-matched to "
+                     "%.4fs (%s %d samples)"
+                     % (frames, len(raw) / sr, len(a) / sr,
+                        "padded" if pad > 0 else "trimmed" if pad < 0
+                        else "exact", abs(pad)))
+        lines.append("")
+        if len(a) < span:
+            lines.append("clip A is shorter than the pinned span, so "
+                         "there is nothing to compare against.")
+            return self._finish(passthrough, lines)
+        lines += self._continuation(a, b, sr, span, window_ms, search_ms)
+        if pad > 0 and len(raw) >= span:
+            # Padding lengthened the array without moving the content, so
+            # the two anchors sit `pad` samples apart and one of them is
+            # wrong. Measuring both says which: a lag that vanishes
+            # against the raw end is an anchoring artifact, one that
+            # survives both is in the render.
+            alt = self._continuation(raw, b, sr, span, window_ms,
+                                     search_ms)
+            lines += ["", "cross-check: same audio anchored on the raw "
+                          "decode instead of the padded end"]
+            lines += ["  " + ln for ln in alt[1:]]
+            lines.append("  the padding is %.2f ms, so these two should "
+                         "differ by that much. Whichever reads near zero "
+                         "is the true alignment."
+                         % (pad / sr * 1000.0,))
+        lines.append("")
+        lines += self._level(a, b, sr, span)
+        return self._finish(passthrough, lines)
+
+    @staticmethod
+    def _clip_a_audio(latent, audio_vae, sr, fps):
+        """Decode clip A's audio and return (tail-matched, raw, frames).
+
+        The tail is the only part that gets read, and its position is
+        what the whole measurement is anchored on, so it has to sit
+        exactly where the delivered clip's does. H3 rounds its audio grid
+        to the nearest step, so a raw decode is up to a third of a step
+        long or short; leaving that in would shift every reported lag by
+        the same amount and look exactly like a real finding. The head
+        trim is not applied because it does not move the tail.
+
+        The raw decode comes back too, because tail-matching a SHORT clip
+        pads it, and padding moves the end of the array without moving
+        the content. On those clips the two arrays disagree about where
+        the anchor is by exactly the overhang, so the probe measures
+        against both and reports the difference rather than picking one
+        and hoping.
+        """
+        parts = _streams_from_latent(latent)
+        if len(parts) < 2:
+            raise ValueError(
+                "clip_a_latent has no audio stream. Wire the sampler "
+                "output of an H3 AV graph, not a video-only latent.")
+        video, audio = parts[0], parts[1]
+        if video.ndim == 4:
+            video = video.unsqueeze(0)
+        frames = _pixel_frames(int(video.shape[2]))
+        if audio.ndim == 3:
+            audio = audio.unsqueeze(0)
+        decoded = audio_vae.decode(audio[:1])
+        a = _mono(decoded)
+        vae_sr = int(getattr(audio_vae, "audio_sample_rate", 32000))
+        if vae_sr != sr:
+            raise ValueError(
+                "clip A decodes at %d Hz but clip B is %d Hz. Not "
+                "comparable." % (vae_sr, sr))
+        want = int(round(frames / float(fps) * sr))
+        have = len(a)
+        raw = a
+        if have > want:
+            a = a[:want]
+        elif have < want:
+            a = np.concatenate([a, np.zeros(want - have)])
+        return a, raw, frames
+
+    def _continuation(self, a, b, sr, span, window_ms, search_ms):
+        """B's first `span` samples should reconstruct A's last `span`."""
+        win = max(1, int(round(window_ms / 1000.0 * sr)))
+        hop = max(1, int(round(0.025 * sr)))  # one audio latent step
+        search = max(1, int(round(search_ms / 1000.0 * sr)))
+        a_tail_start = len(a) - span
+
+        lags, corrs = [], []
+        t, prev_lag = 0, None
+        while t + win <= span:
+            centre = a_tail_start + t
+            lo = max(0, centre - search)
+            hi = min(len(a), centre + win + search)
+            ref = a[lo:hi]
+            if len(ref) <= win:
+                break
+            ncc = _norm_xcorr(b[t:t + win], ref)
+            if ncc is None:
+                t += hop
+                continue
+            # positive lag = B is LATE, matching an earlier part of A
+            if prev_lag is None:
+                # Nothing to track from yet, so take the global peak. Not
+                # zero: assuming the first window is aligned makes a join
+                # that is uniformly offset by a whole audio step read as
+                # the nearest cycle alias instead, which for periodic
+                # content can be a fraction of the real number. That is
+                # exactly the failure this probe exists to find.
+                pick = int(np.argmax(ncc))
+                corr = float(ncc[pick])
+            else:
+                expect = (centre - prev_lag) - lo
+                pick, corr = _tracked_peak(ncc, expect)
+            lag = centre - (lo + pick)
+            lags.append(lag / sr * 1000.0)
+            corrs.append(corr)
+            if corr > CORR_CREDIBLE:
+                prev_lag = lag
+            t += hop
+
+        out = ["continuation over the pinned span"]
+        if not corrs:
+            out.append("  window longer than the span; nothing analysed")
+            return out
+        corrs = np.array(corrs)
+        lags = np.array(lags)
+        strong = corrs > CORR_CREDIBLE
+        out.append("  mean corr   %.3f   (%d/%d windows above %.1f)"
+                   % (corrs.mean(), int(strong.sum()), len(corrs),
+                      CORR_CREDIBLE))
+        if strong.any():
+            sl = lags[strong]
+            out.append("  lag         %+.2f ms mean, %+.2f to %+.2f "
+                       "(credible windows only)"
+                       % (sl.mean(), sl.min(), sl.max()))
+            at_edge = np.abs(sl) >= (search / sr * 1000.0 - 1.0)
+            if at_edge.any():
+                out.append("  %d window(s) pegged at the search limit; the "
+                           "real lag is outside it. Raise search_ms."
+                           % int(at_edge.sum()))
+        else:
+            out.append("  lag         not reported: no window correlated "
+                       "well enough to trust an alignment")
+        if corrs.mean() < 0.3:
+            out.append("  reading: the pinned audio is not being continued "
+                       "at all. Check that context_latent or "
+                       "context_audio is actually wired.")
+        elif corrs.mean() < CORR_CREDIBLE:
+            out.append("  reading: weak. The model is imitating the tail "
+                       "rather than continuing it.")
+        elif strong.any() and abs(lags[strong].mean()) > 12.0:
+            out.append("  reading: locked but offset by more than half an "
+                       "audio step. Placement, not continuation.")
+        else:
+            out.append("  reading: clean continuation.")
+        return out
+
+    def _level(self, a, b, sr, span):
+        """The delivered join: A's tail against B's first post-trim audio."""
+        b_delivered = b[span:]
+        n = min(int(0.5 * sr), len(a), len(b_delivered))
+        out = ["level step across the delivered cut"]
+        if n < int(0.05 * sr):
+            out.append("  too little audio either side of the cut to "
+                       "measure")
+            return out
+        left, right = a[-n:], b_delivered[:n]
+        bb = _step_ratio(_rms(left), _rms(right))
+        fl = _step_ratio(_floor_level(left, sr), _floor_level(right, sr))
+        out.append("  broadband   %.3f  (%.1f dB)   %s"
+                   % (bb, _db(_rms(left), _rms(right)),
+                      "ok" if bb < BROADBAND_OK else "high"))
+        out.append("  floor       %.3f  (%.1f dB)   %s"
+                   % (fl, _db(_floor_level(left, sr),
+                              _floor_level(right, sr)),
+                      "clean" if fl < FLOOR_CLEAN
+                      else "marginal" if fl < FLOOR_MARGINAL
+                      else "audible step"))
+        out.append("  measured over %.0f ms either side" % (n / sr * 1000.0,))
+        if fl >= FLOOR_MARGINAL and bb < BROADBAND_OK:
+            out.append("  reading: the music matches but the bed underneath "
+                       "restarts at the cut. Wire the previous clip's "
+                       "audio into Motion Context.")
+        out.append("  note: the floor figure reads the quiet moments "
+                   "between content, so wall to wall music with no rests "
+                   "gives it nothing to measure and it collapses onto the "
+                   "broadband number.")
+        return out
+
+    @staticmethod
+    def _finish(passthrough, lines):
+        report = "\n".join(lines)
+        for line in lines:
+            _LOG.info("h3_motion_context: %s", line)
+        return {"ui": {"text": [report]},
+                "result": (passthrough, report)}
+
+
+NODE_CLASS_MAPPINGS = {
+    "MiniMaxH3MotionContextSeamProbe": MiniMaxH3MotionContextSeamProbe,
+}
+NODE_DISPLAY_NAME_MAPPINGS = {
+    "MiniMaxH3MotionContextSeamProbe": "H3 Motion Context Seam Probe",
+}

custom_nodes/ComfyUI-H3-Motion-Context-main/pyproject.toml

@@ -0,0 +1,31 @@
+[project]
+name = "comfyui-h3-motion-context"
+description = "Clip chaining for MiniMax H3 in ComfyUI: pin the tail of the previous clip, picture and sound, so the next clip genuinely continues it. The picture is sliced out of the previous latent with no VAE round trip, and the pinned audio window ends at the join and reaches backwards, so the soundtrack continues rather than restarts. ComfyUI is not modified. Node ids MiniMaxH3MotionContext, MiniMaxH3MotionContextTrim, MiniMaxH3MotionContextSaveLatent, MiniMaxH3MotionContextLoadLatent, MiniMaxH3MotionContextChain, MiniMaxH3MotionContextSeamProbe."
+version = "0.6.2"
+license = { file = "LICENSE" }
+readme = "README.md"
+requires-python = ">=3.10"
+authors = [
+    { name = "NikoDemon80", email = "262659861+NikoDemon80@users.noreply.github.com" },
+]
+keywords = ["comfyui", "minimax-h3", "video-generation", "audio", "clip-chaining", "video-continuation"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: End Users/Desktop",
+    "License :: OSI Approved :: GNU General Public License v3 (GPLv3)",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Multimedia :: Video",
+    "Topic :: Multimedia :: Sound/Audio",
+]
+
+[project.urls]
+Homepage = "https://github.com/NikoDemon80/ComfyUI-H3-Motion-Context"
+Repository = "https://github.com/NikoDemon80/ComfyUI-H3-Motion-Context"
+Issues = "https://github.com/NikoDemon80/ComfyUI-H3-Motion-Context/issues"
+
+[tool.comfy]
+PublisherId = "nikodemon80"
+DisplayName = "H3 Motion Context"

custom_nodes/ComfyUI-H3-Motion-Context-main/tests/_mock_harness.py

@@ -0,0 +1,373 @@
+"""Standalone harness for layout_contract, no ComfyUI and no GPU needed.
+
+Fakes `comfy.ldm.minimax.model` with a PackedLayout that reproduces the
+structure of the real one in comfy/ldm/minimax/model.py as of ComfyUI
+0.33:
+
+  segment order   text, then keyframe rows, then reference blocks, then
+                  target audio, then target video. The target rows are
+                  always the last two segments.
+  segment kinds   text / cond / cond_audio / ref_img / ref_audio /
+                  audio / video
+  position_ids    [S, 3] float64, columns (t, h, w)
+  origin          the target timeline starts past the span of every
+                  reference block, and keyframe anchors are measured from
+                  there, so stock compensates anchors for references
+  keyframe rows   cond_t = origin + FRAME_RESCALE * resolved_frame_index.
+                  A keyframe emits a cond segment only if it carries a
+                  video latent, sized by that latent's step count, and a
+                  cond_audio segment only if it carries an audio latent,
+                  running FORWARD from cond_t for as many steps as the
+                  latent has.
+  references      laid out from a cursor starting at text_len:
+                    image        one ref_img segment, cursor += 1
+                    audio        one ref_audio segment of rt*2 rows,
+                                 channel-major stereo; cursor += rt, and
+                                 the segment is skipped when rt is 0
+                    video,       ref_audio then ref_img, both sharing the
+                    video_audio  cursor origin; cursor advances by
+                                 max(rt, sum of the video spans)
+
+The pack no longer patches any of this. What it needs is that the
+keyframe line above stays literal for a fractional, negative index, which
+is how the pinned audio window is made to END at the join. No stock node
+can produce such an index, so nothing upstream tests it. The mutation
+knobs on make_mm are the ways that could plausibly stop being true, and
+every one of them must be caught.
+
+Checks:
+  1. the contract passes against a faithful 0.33 layout
+  2. an integer cast on the anchor index is caught
+  3. an audio window anchored at its end rather than its start is caught
+  4. a layout that stops compensating anchors for references is caught
+  5. a changed audio row count is caught
+  6. the older constructor is refused by signature, before anything is
+     built, with a message that describes the layout rather than naming a
+     ComfyUI version, and points at the pack version that runs on both
+  7. the failure is remembered, so a second render does not re-run the
+     checks and does not fail silently either
+"""
+
+import os
+import sys
+import types
+
+import numpy as np
+
+# the package dir has to be on sys.path so layout_contract imports by name
+_PKG_DIR = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+if _PKG_DIR not in sys.path:
+    sys.path.insert(0, _PKG_DIR)
+
+FRAME_RESCALE = 5.0 / 3.0
+FRAME_PER_TOKEN = (1, 4, 4, 4, 4)
+
+
+def _video_t_spans(latent_t):
+    return [FRAME_RESCALE * FRAME_PER_TOKEN[k % 5] for k in range(latent_t)]
+
+
+def _frame_grid(h, w):
+    """[n, 2] (h, w) coordinates for one latent frame's 2x2-patch rows.
+
+    The values only have to be deterministic and shaped right; nothing
+    under test reads these columns.
+    """
+    n_h, n_w = h // 2, w // 2
+    hh, ww = np.meshgrid(np.arange(n_h, dtype=np.float64),
+                         np.arange(n_w, dtype=np.float64), indexing="ij")
+    return np.stack([hh.reshape(-1), ww.reshape(-1)], axis=-1)
+
+
+def _audio_grid(cursor, t, rows_per_step=2):
+    g = np.zeros((t * rows_per_step, 3), dtype=np.float64)
+    g[:, 0] = np.tile(cursor + np.arange(t, dtype=np.float64), rows_per_step)
+    if rows_per_step == 2:
+        g[:t, 2] = -1.0
+        g[t:, 2] = 1.0
+    return g
+
+
+def _video_t_grid(n, origin):
+    spans = np.array(_video_t_spans(n), dtype=np.float64)
+    head = np.cumsum(spans[:-1]) if n > 1 else np.zeros(0, dtype=np.float64)
+    return float(origin) + np.concatenate(([0.0], head))
+
+
+def _video_grid(vt, frame, cursor):
+    g = np.empty((vt, frame.shape[0], 3), dtype=np.float64)
+    g[:, :, 0] = _video_t_grid(vt, cursor)[:, None]
+    g[:, :, 1:] = frame[None]
+    return g.reshape(-1, 3)
+
+
+def make_mm(audio_rows_per_step=2, int_index=False, audio_anchor="start",
+            compensate_refs=True, legacy=False):
+    """Build a fake comfy.ldm.minimax.model.
+
+    Defaults reproduce ComfyUI 0.33. Each other argument breaks one
+    property the pack depends on:
+
+      int_index          upstream adds a cast, and the fractional audio
+                         index silently rounds
+      audio_anchor="end" the audio window is measured from its end rather
+                         than its start, so it runs the wrong way
+      compensate_refs    False puts the 0.32 behaviour back, where anchors
+                         are computed from text_len and references slide
+                         them relative to the target
+      audio_rows_per_step  a change to how many rows one audio step takes
+      legacy             the 0.32 constructor, frame_count and all
+    """
+    mm = types.ModuleType("comfy.ldm.minimax.model")
+    mm.FRAME_RESCALE = FRAME_RESCALE
+    mm.FRAME_PER_TOKEN = FRAME_PER_TOKEN
+    mm._video_t_spans = _video_t_spans
+
+    def _ref_t_span(blk):
+        kind = blk["kind"]
+        if kind == "image":
+            return 1.0
+        if kind == "audio":
+            return float(blk["ref_audio_t"])
+        if kind in ("video", "video_audio"):
+            return max(float(blk["ref_audio_t"]),
+                       sum(_video_t_spans(blk["latent_t"])))
+        raise ValueError("mock: unsupported ref kind %r" % kind)
+
+    def _build(self, text_len, latent_t, latent_h, latent_w, audio_t,
+               keyframes, refs, frame_count):
+        frame = _frame_grid(latent_h, latent_w)
+        frame_rows = frame.shape[0]
+        segs, blocks = [], []
+
+        def emit(kind, g):
+            segs.append((kind, g.shape[0]))
+            blocks.append(g)
+
+        g = np.zeros((text_len, 3), dtype=np.float64)
+        g[:, 0] = np.arange(text_len, dtype=np.float64)
+        emit("text", g)
+
+        origin = float(text_len)
+        if compensate_refs:
+            for blk in (refs or []):
+                origin += _ref_t_span(blk)
+
+        for kf in (keyframes or []):
+            p = kf["resolved_frame_index"]
+            if legacy:
+                if p == 0:
+                    cond_t = float(text_len)
+                elif frame_count is not None and p == frame_count - 1:
+                    cond_t = (float(text_len) + sum(_video_t_spans(latent_t))
+                              - FRAME_RESCALE)
+                else:
+                    raise ValueError(
+                        "only first/last keyframe anchors are supported")
+                g = np.empty((frame_rows, 3), dtype=np.float64)
+                g[:, 0] = cond_t
+                g[:, 1:] = frame
+                emit("cond", g)
+                continue
+            if int_index:
+                p = int(p)
+            cond_t = origin + FRAME_RESCALE * p
+            video_latent = kf.get("latent")
+            if video_latent is not None:
+                emit("cond", _video_grid(video_latent.shape[2], frame, cond_t))
+            audio_latent = kf.get("audio_latent")
+            if audio_latent is not None:
+                rt = audio_latent.shape[-1]
+                start = cond_t if audio_anchor == "start" else cond_t - rt
+                emit("cond_audio", _audio_grid(start, rt, audio_rows_per_step))
+
+        cursor = float(text_len)
+        for blk in (refs or []):
+            kind = blk["kind"]
+            if kind == "image":
+                r_frame = _frame_grid(blk["latent_h"], blk["latent_w"])
+                g = np.empty((r_frame.shape[0], 3), dtype=np.float64)
+                g[:, 0] = cursor
+                g[:, 1:] = r_frame
+                emit("ref_img", g)
+                cursor += 1.0
+            elif kind == "audio":
+                rt = int(blk["ref_audio_t"])
+                if rt > 0:
+                    emit("ref_audio",
+                         _audio_grid(cursor, rt, audio_rows_per_step))
+                cursor += float(rt)
+            elif kind in ("video", "video_audio"):
+                rt = int(blk["ref_audio_t"])
+                vt = int(blk["latent_t"])
+                r_frame = _frame_grid(blk["latent_h"], blk["latent_w"])
+                if rt > 0:
+                    emit("ref_audio",
+                         _audio_grid(cursor, rt, audio_rows_per_step))
+                emit("ref_img", _video_grid(vt, r_frame, cursor))
+                cursor += max(float(rt), sum(_video_t_spans(vt)))
+            else:
+                raise ValueError("mock: unsupported ref kind %r" % kind)
+
+        # target audio then target video, always the last two segments
+        emit("audio", _audio_grid(cursor, audio_t))
+        emit("video", _video_grid(latent_t, frame, cursor))
+
+        seg_abs, off = [], 0
+        for kind, n in segs:
+            seg_abs.append((off, off + n, kind))
+            off += n
+        self.segments = seg_abs
+        self.seq_len = off
+        self.position_ids = np.concatenate(blocks)
+
+    # Two real signatures, not one with **kwargs: the pack decides whether
+    # this ComfyUI is too old by inspecting the signature, and 0.33 has to
+    # raise a real TypeError on frame_count.
+    if legacy:
+        class PackedLayout:
+            def __init__(self, text_len, latent_t, latent_h, latent_w,
+                         audio_t, keyframes=None, refs=None,
+                         frame_count=None):
+                _build(self, text_len, latent_t, latent_h, latent_w, audio_t,
+                       keyframes, refs, frame_count)
+    else:
+        class PackedLayout:
+            def __init__(self, text_len, latent_t, latent_h, latent_w,
+                         audio_t, keyframes=None, refs=None):
+                _build(self, text_len, latent_t, latent_h, latent_w, audio_t,
+                       keyframes, refs, None)
+
+    mm.PackedLayout = PackedLayout
+    return mm
+
+
+def make_torch():
+    t = types.ModuleType("torch")
+    t.equal = lambda a, b: a.shape == b.shape and bool(np.array_equal(a, b))
+
+    # nodes.py pads a short audio tail with torch.nn.functional.pad. Only
+    # the trailing-last-dim form is used, which is what this covers.
+    def _pad(x, pad, mode="constant", value=0.0):
+        before, after = int(pad[0]), int(pad[1])
+        widths = [(0, 0)] * (x.a.ndim - 1) + [(before, after)]
+        return type(x)(np.pad(x.a, widths, mode="constant",
+                              constant_values=value))
+
+    functional = types.ModuleType("torch.nn.functional")
+    functional.pad = _pad
+    nn = types.ModuleType("torch.nn")
+    nn.functional = functional
+    t.nn = nn
+    return t
+
+
+def load_contract(mm):
+    for name in ("comfy", "comfy.ldm", "comfy.ldm.minimax"):
+        sys.modules.setdefault(name, types.ModuleType(name))
+    sys.modules["comfy.ldm.minimax.model"] = mm
+    sys.modules["comfy"].ldm = sys.modules["comfy.ldm"]
+    sys.modules["comfy.ldm"].minimax = sys.modules["comfy.ldm.minimax"]
+    sys.modules["comfy.ldm.minimax"].model = mm
+    sys.modules["torch"] = make_torch()
+    sys.modules.pop("layout_contract", None)
+    import layout_contract
+    return layout_contract
+
+
+def _refused(mm, label, expect):
+    """The contract must refuse this layout, for the stated reason."""
+    lc = load_contract(mm)
+    try:
+        lc.ensure()
+    except RuntimeError as e:
+        assert expect in str(e), "%s: wrong reason: %s" % (label, e)
+        assert not lc.is_checked()
+        return str(e)
+    raise AssertionError("%s: the contract accepted it" % label)
+
+
+def main():
+    # 1. faithful 0.33: the checks must pass and stay passed
+    mm = make_mm()
+    lc = load_contract(mm)
+    lc.ensure()
+    assert lc.is_checked()
+    lc.ensure()  # second call is a no-op, not a second layout build
+    print("1. contract passes against a faithful ComfyUI 0.33 layout")
+
+    # 2. an int cast on the anchor index. The video anchors are whole
+    # numbers and survive it, so only the audio window moves, which is
+    # exactly the silent breakage this check exists for.
+    _refused(make_mm(int_index=True), "int cast",
+             "fractional or negative resolved_frame_index")
+    print("2. an integer cast on the anchor index is caught")
+
+    # 3. the window measured from its end instead of its start: it would
+    # run forwards from the join instead of backwards into it
+    _refused(make_mm(audio_anchor="end"), "audio anchored at end",
+             "pinned audio window")
+    print("3. an audio window anchored at its end is caught")
+
+    # 4. references stop compensating the anchors, as they did on 0.32
+    _refused(make_mm(compensate_refs=False), "no ref compensation",
+             "moved the anchors relative to the target")
+    print("4. a layout that stops compensating anchors for references is "
+          "caught")
+
+    # 5. a changed audio row count: the window is no longer the shape the
+    # placement assumes
+    _refused(make_mm(audio_rows_per_step=3), "audio rows",
+             "rows for")
+    print("5. a changed audio row count is caught")
+
+    # 6. the older constructor: refused by signature, before anything is
+    # built. The message must describe the LAYOUT, not guess a ComfyUI
+    # version. A wrapper's signature is not ComfyUI's, and the new layout
+    # sat on master unreleased for a while, so a version number inferred
+    # here would have been wrong in both directions.
+    msg = _refused(make_mm(legacy=True), "legacy", "older H3 layout")
+    assert "0.3.1" in msg, msg
+    assert "0.32" not in msg, "the refusal is guessing a ComfyUI version: %s" % msg
+    print("6. the older constructor refused by signature, pointing at pack "
+          "0.3.1 without guessing a ComfyUI version")
+
+    # 7. a failure is remembered. The node calls ensure() on every render,
+    # and the second call must raise the same way rather than quietly
+    # passing because some module state got left behind.
+    lc_bad = load_contract(make_mm(int_index=True))
+    for attempt in (1, 2):
+        try:
+            lc_bad.ensure()
+        except RuntimeError:
+            pass
+        else:
+            raise AssertionError("attempt %d did not raise" % attempt)
+    assert not lc_bad.is_checked()
+    print("7. a failed check stays failed on the next render")
+
+    # 8. the case that actually bit: another pack vendoring this project's
+    # old layout patch wraps the constructor, and that wrapper's signature
+    # carries frame_count on EVERY ComfyUI. Read naively it looks exactly
+    # like the older layout, and the user gets told to update a ComfyUI
+    # that is already current. Behaviour has to decide, not the signature.
+    mm = make_mm()
+    stock_init = mm.PackedLayout.__init__
+
+    def _patched_init(self, text_len, latent_t, latent_h, latent_w, audio_t,
+                      keyframes=None, refs=None, frame_count=None):
+        stock_init(self, text_len, latent_t, latent_h, latent_w, audio_t,
+                   keyframes=keyframes, refs=refs)
+
+    mm.PackedLayout.__init__ = _patched_init
+    lc = load_contract(mm)
+    lc.ensure()
+    assert lc.is_checked(), "a wrapped constructor was mistaken for the old layout"
+    print("8. a vendored copy of the old patch wrapping the constructor does "
+          "not get mistaken for an older ComfyUI")
+
+    print("all checks passed")
+
+
+if __name__ == "__main__":
+    main()

custom_nodes/ComfyUI-H3-Motion-Context-main/tests/_node_smoke_test.py

@@ -0,0 +1,676 @@
+"""Smoke test: run MiniMaxH3MotionContext.apply() end to end with fakes.
+
+Fakes ComfyUI's modules and tensor ops (numpy-backed) and drives the node
+exactly as a graph would: a 124-frame clip at 480x864, 22 context frames,
+audio from the previous clip's LATENT. Checks the produced conditioning
+values: keyframe count and indices, the audio ref's step count, and the
+fractional end_frame carrying the grid-overhang compensation.
+"""
+
+import sys
+import types
+
+import numpy as np
+
+import os
+_TESTS_DIR = os.path.dirname(os.path.abspath(__file__))
+_PKG_DIR = os.path.dirname(_TESTS_DIR)  # repo root, where the package lives
+sys.path.insert(0, _TESTS_DIR)
+from _mock_harness import make_mm, make_torch  # noqa: E402
+
+
+class T:
+    """Minimal numpy-backed tensor stand-in."""
+
+    def __init__(self, a):
+        self.a = np.asarray(a)
+
+    @property
+    def shape(self):
+        return self.a.shape
+
+    @property
+    def ndim(self):
+        return self.a.ndim
+
+    def __getitem__(self, idx):
+        return T(self.a[idx])
+
+    def movedim(self, src, dst):
+        return T(np.moveaxis(self.a, src, dst))
+
+    def unsqueeze(self, d):
+        return T(np.expand_dims(self.a, d))
+
+    def clone(self):
+        return T(self.a.copy())
+
+    def cpu(self):
+        return self
+
+    def contiguous(self):
+        return T(np.ascontiguousarray(self.a))
+
+
+class Nested:
+    def __init__(self, parts):
+        self.parts = parts
+
+    def unbind(self):
+        return list(self.parts)
+
+
+def main():
+    # fake modules the package imports
+    mm = make_mm()
+    for name in ("comfy", "comfy.ldm", "comfy.ldm.minimax"):
+        sys.modules.setdefault(name, types.ModuleType(name))
+    sys.modules["comfy.ldm.minimax.model"] = mm
+    sys.modules["comfy"].ldm = sys.modules["comfy.ldm"]
+    sys.modules["comfy.ldm"].minimax = sys.modules["comfy.ldm.minimax"]
+    sys.modules["comfy.ldm.minimax"].model = mm
+    sys.modules["torch"] = make_torch()
+
+    cu = types.ModuleType("comfy.utils")
+    cu.common_upscale = lambda s, w, h, m, c: T(
+        np.zeros((s.shape[0], 3, h, w), dtype=np.float32))
+    sys.modules["comfy.utils"] = cu
+    sys.modules["comfy"].utils = cu
+
+    mb = types.ModuleType("comfy.model_base")
+
+    class MiniMaxH3:
+        def extra_conds(self, **kw):
+            return {}
+    mb.MiniMaxH3 = MiniMaxH3
+    sys.modules["comfy.model_base"] = mb
+    sys.modules["comfy"].model_base = mb
+
+    captured = {}
+    nh = types.ModuleType("node_helpers")
+
+    def conditioning_set_values(cond, values, append=False):
+        # faithful to ComfyUI's node_helpers: copy each entry's dict, and
+        # when appending, concatenate onto whatever is already under the
+        # key instead of replacing it. The append path is what lets a
+        # Ref2VA graph keep its own reference blocks.
+        out = []
+        for t in cond:
+            n = [t[0], t[1].copy()]
+            for k, v in values.items():
+                if append:
+                    old = n[1].get(k, None)
+                    if old is not None:
+                        v = old + v
+                n[1][k] = v
+            out.append(n)
+        captured.clear()
+        captured.update(out[0][1])
+        return out
+    nh.conditioning_set_values = conditioning_set_values
+    sys.modules["node_helpers"] = nh
+
+    import os
+    import tempfile
+    outdir = tempfile.mkdtemp()
+    fp = types.ModuleType("folder_paths")
+    fp.get_output_directory = lambda: outdir
+
+    def get_save_image_path(prefix, out, *a):
+        sub, name = os.path.split(prefix)
+        folder = os.path.join(out, sub)
+        os.makedirs(folder, exist_ok=True)
+        counter = 1 + sum(1 for f in os.listdir(folder)
+                          if f.startswith(name))
+        return folder, name, counter, sub, prefix
+    fp.get_save_image_path = get_save_image_path
+    sys.modules["folder_paths"] = fp
+
+    st = types.ModuleType("safetensors")
+    stt = types.ModuleType("safetensors.torch")
+
+    def save_file(d, path, metadata=None):
+        np.savez(path + ".npz", **{k: v.a for k, v in d.items()})
+        open(path, "w").write(path + ".npz")
+
+    def load_file(path):
+        real = open(path).read()
+        z = np.load(real)
+        return {k: T(z[k]) for k in z.files}
+    stt.save_file, stt.load_file = save_file, load_file
+    st.torch = stt
+    sys.modules["safetensors"] = st
+    sys.modules["safetensors.torch"] = stt
+
+    # Load as a package so relative imports work whatever the folder is
+    # called (hyphens are not a valid module name).
+    pkg = types.ModuleType("h3mc_pkg")
+    pkg.__path__ = [_PKG_DIR]
+    pkg.__file__ = os.path.join(_PKG_DIR, "__init__.py")
+    sys.modules["h3mc_pkg"] = pkg
+    import h3mc_pkg.nodes as nodes
+    import h3mc_pkg.probe_node as probe_node
+    pkg.NODE_CLASS_MAPPINGS = dict(nodes.NODE_CLASS_MAPPINGS)
+    pkg.NODE_CLASS_MAPPINGS.update(probe_node.NODE_CLASS_MAPPINGS)
+
+    def audio_kf():
+        """The one keyframe carrying pinned audio, from the last apply()."""
+        got = [k for k in captured["minimax_keyframes"]
+               if k.get("audio_latent") is not None]
+        assert len(got) == 1, "expected 1 pinned audio keyframe, got %d" % len(got)
+        return got[0]
+
+    def audio_end():
+        """Target frame the pinned audio window ends at.
+
+        Stock places the window STARTING at the anchor index and running
+        forward, so the end is the index plus the window's own width in
+        pixel frames. That is the number the node solved for.
+        """
+        kf = audio_kf()
+        return (kf["resolved_frame_index"]
+                + kf["audio_latent"].shape[-1] / nodes.FRAME_RESCALE)
+    assert pkg.NODE_CLASS_MAPPINGS
+    # importing the pack must not have touched ComfyUI yet
+    assert not nodes._layout_checked(), \
+        "the layout checks ran at import time"
+    stock_init = mm.PackedLayout.__init__
+
+    # a 124-frame clip: latent_t 37 (7 full 17-frame groups + 1 + 4),
+    # audio grid ceil(124 * 5/3) = 207 steps, overhang exactly 1/3
+    latent_t, frames, audio_t = 37, 124, 207
+    assert nodes._pixel_frames(latent_t) == frames
+    h, w = 480 // 16, 864 // 16
+    target = {"samples": Nested([
+        T(np.zeros((1, 16, latent_t, h, w), dtype=np.float32)),
+        T(np.zeros((1, 32, 2, audio_t), dtype=np.float32)),
+    ])}
+    # previous clip's sampler latent (same dims in this setup)
+    prev = {"samples": Nested([
+        T(np.arange(1 * 16 * latent_t * h * w, dtype=np.float32
+                    ).reshape(1, 16, latent_t, h, w)),
+        T(np.arange(1 * 32 * 2 * audio_t, dtype=np.float32
+                    ).reshape(1, 32, 2, audio_t)),
+    ])}
+    context = T(np.zeros((124, 480, 864, 3), dtype=np.float32))
+
+    class VAE:
+        def encode(self, x):
+            n = x.shape[0]
+            steps = max(1, (n - 5) // 17 * 5 + 2)
+            return T(np.zeros((1, 16, steps, h, w), dtype=np.float32))
+
+    node = nodes.MiniMaxH3MotionContext()
+
+    def run(**kw):
+        """apply(), capturing the conditioning it returns.
+
+        The node used to reach node_helpers to append its audio reference,
+        which is where these assertions used to read the result from. It
+        now builds the conditioning itself and touches no reference list,
+        so read what it actually hands the sampler.
+        """
+        got = node.apply(**kw)
+        captured.clear()
+        captured.update(got[0][0][1])
+        return got
+    out, trim = run(
+        conditioning=[["c", {}]], vae=VAE(), latent=target,
+        context_frames=context, context_length="22",
+        audio_context_length=22, context_latent=prev)
+
+    # ... and running one must have checked the layout, and left it alone
+    assert nodes._layout_checked(), "the layout checks did not run"
+    assert mm.PackedLayout.__init__ is stock_init, \
+        "ComfyUI's constructor was modified"
+
+    kfs = captured["minimax_keyframes"]
+    # video keyframes carry a latent, the pinned audio is one more
+    # keyframe carrying only an audio latent, and it goes last
+    vid = [kf for kf in kfs if kf.get("latent") is not None]
+    aud = [kf for kf in kfs if kf.get("audio_latent") is not None]
+    assert len(kfs) == 8 and len(vid) == 7 and len(aud) == 1, len(kfs)
+    assert kfs[-1] is aud[0], "the audio keyframe is not last"
+    assert "minimax_refs" not in captured, \
+        "the pinned audio went out as a reference, not a keyframe"
+    idx = [kf["resolved_frame_index"] for kf in vid]
+    assert idx == [0, 1, 5, 9, 13, 17, 18], idx
+    assert "minimax_frame_count" not in captured
+    assert trim == 22
+
+    # the index is rt / FRAME_RESCALE frames before the end coordinate, so
+    # the window ENDS at the join rather than starting there. Here the
+    # audio and video windows are both 22 frames, so it starts exactly at
+    # frame 0; the 24-frame audio case below is the one that goes negative.
+    a_idx = aud[0]["resolved_frame_index"]
+    assert a_idx <= 0, a_idx
+    ref = {"ref_audio_t": aud[0]["audio_latent"].shape[-1],
+           "audio_latent": aud[0]["audio_latent"]}
+    assert ref["ref_audio_t"] == 37, ref["ref_audio_t"]  # round(22/24*40)
+    tail = ref["audio_latent"]
+    assert tuple(tail.shape) == (1, 32, 2, 37), tail.shape
+    # tail must be the LAST 37 steps of the source
+    assert float(tail.a[0, 0, 0, -1]) == float(prev["samples"].parts[1]
+                                               .a[0, 0, 0, -1])
+    # the window must land on the target's own integer audio grid: the
+    # end coordinate is FRAME_RESCALE * end_frame and the target's audio
+    # rows sit on integers, so a fractional end coordinate would place
+    # the pinned content between them (a third of a step is 8.3 ms)
+    got_end = a_idx + ref["ref_audio_t"] / nodes.FRAME_RESCALE
+    end_coord = nodes.FRAME_RESCALE * got_end
+    assert abs(end_coord - round(end_coord)) < 1e-9, end_coord
+    assert abs(end_coord - 37.0) < 1e-9, end_coord
+    assert abs(got_end - 22.2) < 1e-6, got_end
+    # the pinned VIDEO must have come out of the latent too, not the VAE.
+    # The fake VAE returns zeros, so any nonzero block proves the source,
+    # and each block must equal the matching step of the source latent.
+    kf_blocks = [kf["latent"] for kf in vid]
+    src = prev["samples"].parts[0].a
+    start = latent_t - len(kf_blocks)          # 37 - 7 = 30, cycle pos 0
+    assert start % 5 == 0, start
+    for k, blk in enumerate(kf_blocks):
+        assert tuple(blk.shape) == (1, 16, 1, h, w), blk.shape
+        assert np.array_equal(blk.a[0, :, 0], src[0, :, start + k]), k
+    assert nodes._steps_for_frames(22) == 7
+    assert nodes._steps_for_frames(5) == 2
+    assert nodes._steps_for_frames(39) == 12
+    assert nodes._steps_for_frames(1) == 1
+    assert nodes._steps_for_frames(3) is None    # not a whole step boundary
+    print("latent path: 7 cond blocks at %s sliced from the latent tail "
+          "(bit-identical to the source steps), audio 37 steps, end_frame "
+          "%.4f (overhang-compensated)" % (idx, got_end))
+
+    # the recommended config pins 22 frames of picture and 24 of sound, so
+    # the audio window reaches back past the start of the clip. That index
+    # is negative AND fractional, which no stock node can produce and
+    # nothing upstream tests, so it is worth asserting here as well as in
+    # the layout contract.
+    run(conditioning=[["c", {}]], vae=VAE(), latent=target,
+        context_frames=context, context_length="22",
+        audio_context_length=24, context_latent=prev)
+    wide = audio_kf()
+    assert wide["audio_latent"].shape[-1] == 40, wide["audio_latent"].shape
+    w_idx = wide["resolved_frame_index"]
+    assert w_idx < 0 and w_idx != int(w_idx), w_idx
+    assert abs(w_idx - (37 - 40) / nodes.FRAME_RESCALE) < 1e-9, w_idx
+    w_end = nodes.FRAME_RESCALE * audio_end()
+    assert abs(w_end - round(w_end)) < 1e-9, w_end
+    print("wide audio window: 24 frames of sound against 22 of picture, "
+          "anchor index %.3f, still ending on the audio grid at %.1f"
+          % (w_idx, w_end))
+
+    # no latent wired: the pixel path, same offsets, and the fake VAE
+    # returns zeros so the blocks must now be zero rather than sliced.
+    # No audio either, so node_helpers is never called: read the
+    # conditioning the node returns rather than the capture hook
+    res, _ = run(
+        conditioning=[["c", {}]], vae=VAE(), latent=target,
+        context_frames=context, context_length="22",
+        audio_context_length=22)
+    px = res[0][1]["minimax_keyframes"]
+    assert [kf["resolved_frame_index"] for kf in px] == idx, \
+        "offsets differ by source"
+    assert float(px[0]["latent"].a.max()) == 0.0, "did not use the VAE"
+    print("pixels path: same %d blocks at the same offsets, encoded rather "
+          "than sliced" % len(px))
+
+    # a resolution change cannot slice a latent and must refuse, not
+    # quietly take the lossy path
+    small = {"samples": Nested([
+        T(np.zeros((1, 16, latent_t, h // 2, w // 2), dtype=np.float32)),
+        T(np.zeros((1, 32, 2, audio_t), dtype=np.float32)),
+    ])}
+    try:
+        run(
+            conditioning=[["c", {}]], vae=VAE(), latent=target,
+            context_frames=context, context_length="22",
+            audio_context_length=22, context_latent=small)
+    except ValueError as e:
+        assert "cannot be resized" in str(e), str(e)
+        print("resolution change: refused, with the reason and the two "
+              "resolutions named")
+    else:
+        raise AssertionError("mismatched latent did not refuse")
+
+    # nothing wired: first clip of a chain. Pass the conditioning
+    # through and report trim_frames 0 so Trim is a no-op.
+    cond = [["c", {"untouched": True}]]
+    res, trim = run(
+        conditioning=cond, vae=VAE(), latent=target,
+        context_length="22", audio_context_length=22)
+    assert trim == 0, trim
+    assert res is cond
+    assert captured.get("untouched") is True
+    assert "minimax_keyframes" not in captured
+    print("nothing wired: original conditioning passed through, "
+          "trim_frames 0")
+
+    # the constants that replaced the widgets must be on the good values
+    assert nodes.ENCODE_MODE == "video"
+    assert nodes.ANCHOR_MODE == "head"
+    assert nodes.AUDIO_MODE == "timeline"
+    assert nodes.CROP == "disabled"
+
+    # the cycle-position property the whole latent video path rests on,
+    # checked across every clip length and window rather than argued for
+    for g in range(1, 40):
+        steps_total = 5 * g + 2
+        frames_total = nodes._pixel_frames(steps_total)
+        assert (frames_total - 5) % 17 == 0, (g, frames_total)
+        for wnd in (5, 22, 39, 56):
+            st = nodes._steps_for_frames(wnd)
+            if st is None or st > steps_total:
+                continue
+            begin = steps_total - st
+            assert begin % 5 == 0, (frames_total, wnd, begin % 5)
+            assert nodes._pixel_frames(st) == wnd
+            # offsets computed for a fresh run must match the sliced run
+            assert (nodes._step_offsets(st)
+                    == [nodes._pixel_frames(k) for k in range(st)])
+    print("cycle check: every clip length 22..%d x windows 5/22/39/56 "
+          "slices from cycle position 0" % nodes._pixel_frames(5 * 39 + 2))
+
+    # decoded-audio path must still work and carry integer end_frame
+    captured.clear()
+
+    class AudioVAE:
+        audio_sample_rate = 32000
+
+        def encode(self, x):
+            steps = int(round(x.shape[-2] / 32000 * 40))
+            return T(np.zeros((1, 32, 2, steps), dtype=np.float32))
+
+    audio = {"waveform": T(np.zeros((1, 2, 32000), dtype=np.float32)),
+             "sample_rate": 32000}
+    run(
+        conditioning=[["c", {}]], vae=VAE(), latent=target,
+        context_frames=context, context_length="22",
+        audio_context_length=22, audio_vae=AudioVAE(), context_audio=audio)
+    # no overhang to compensate on this path, but the same grid rule
+    # applies: 22 frames is 36.667 steps, which must snap to 37
+    end2 = nodes.FRAME_RESCALE * audio_end()
+    assert abs(end2 - 37.0) < 1e-9, end2
+    print("vae path: window snapped to the audio grid, end coord %.1f" % end2)
+
+    # every clip length on the ladder, every window, both paths: the
+    # pinned window must always end on an integer audio coordinate
+    for g in range(2, 13):
+        f = 17 * g + 5
+        # nearest, not ceil: ceil would simulate +2/3 on the lengths that
+        # actually run -1/3, so this loop used to exercise a value the
+        # model never produces
+        at = round(nodes.FRAME_RESCALE * f)
+        oh = at - nodes.FRAME_RESCALE * f
+        for span in (5, 22, 39, 56):
+            for ohv in (0.0, oh):
+                ef = span + ohv / nodes.FRAME_RESCALE
+                ec = round(nodes.FRAME_RESCALE * ef)
+                ef = ec / nodes.FRAME_RESCALE
+                c = nodes.FRAME_RESCALE * ef
+                assert abs(c - round(c)) < 1e-9, (f, span, ohv, c)
+    print("grid check: every ladder length x window 5/22/39/56 x both "
+          "audio paths ends on an integer audio coordinate")
+
+    # All three frame-count residues, latent path, 22-frame window. The
+    # 124-frame case above is frames % 3 == 1, the one residue where
+    # rounding up and rounding to nearest agree, so on its own it cannot
+    # tell the two rules apart. 260 frames is the negative-overhang case:
+    # compensation moves the end coordinate to 36.33, which rounds to 36,
+    # where failing open would leave it at 36.67 and round to 37, a whole
+    # audio step (25 ms) late.
+    import logging as _logging
+
+    class _Catcher(_logging.Handler):
+        def __init__(self):
+            _logging.Handler.__init__(self)
+            self.msgs = []
+
+        def emit(self, record):
+            self.msgs.append(record.getMessage())
+
+    catcher = _Catcher()
+    catcher.setLevel(_logging.WARNING)
+    nodes._LOG.addHandler(catcher)
+    try:
+        for lt, f, at, want_coord, want_end in (
+                (37, 124, 207, 37, 22.2),   # +1/3, reaches past
+                (72, 243, 405, 37, 22.2),   #    0, exact
+                (77, 260, 433, 36, 21.6)):  # -1/3, falls short
+            assert nodes._pixel_frames(lt) == f, (lt, f)
+            assert at == round(nodes.FRAME_RESCALE * f), (f, at)
+            captured.clear()
+            del catcher.msgs[:]
+            tgt = {"samples": Nested([
+                T(np.zeros((1, 16, lt, h, w), dtype=np.float32)),
+                T(np.zeros((1, 32, 2, at), dtype=np.float32)),
+            ])}
+            src = {"samples": Nested([
+                T(np.arange(1 * 16 * lt * h * w, dtype=np.float32
+                            ).reshape(1, 16, lt, h, w)),
+                T(np.arange(1 * 32 * 2 * at, dtype=np.float32
+                            ).reshape(1, 32, 2, at)),
+            ])}
+            run(
+                conditioning=[["c", {}]], vae=VAE(), latent=tgt,
+                context_frames=T(np.zeros((f, 480, 864, 3),
+                                          dtype=np.float32)),
+                context_length="22", audio_context_length=22,
+                context_latent=src)
+            got = audio_end()
+            coord = nodes.FRAME_RESCALE * got
+            assert abs(coord - round(coord)) < 1e-9, (f, coord)
+            assert abs(coord - want_coord) < 1e-9, (f, coord, want_coord)
+            assert abs(got - want_end) < 1e-6, (f, got, want_end)
+            # the grid is legal on all three, so nothing may warn about it
+            assert not [m for m in catcher.msgs if "audio grid" in m], \
+                (f, catcher.msgs)
+    finally:
+        nodes._LOG.removeHandler(catcher)
+    print("residue check: frames % 3 in 0/1/2 all accepted, end coords "
+          "37/37/36 (the -1/3 case would be 37 if it failed open)")
+
+    # The trim node's match_tail: a long tail is truncated, a short one is
+    # padded, both to exactly frames/fps. The short case only occurs on
+    # frames % 3 == 2 clips, which is why it went unexercised.
+    trimmer = nodes.MiniMaxH3MotionContextTrim()
+    for f, direction in ((124, "long"), (243, "exact"), (260, "short")):
+        sr = 32000
+        # what H3 actually ships: the audio grid at nearest rounding,
+        # decoded back to samples
+        steps = round(nodes.FRAME_RESCALE * f)
+        have = int(round(steps / nodes.AUDIO_HZ * sr))
+        want = int(round((f - 22) / 24.0 * sr))
+        imgs = T(np.zeros((f, 8, 8, 3), dtype=np.float32))
+        wav = T(np.zeros((1, 2, have), dtype=np.float32))
+        _, out = trimmer.trim(
+            images=imgs, trim_frames=22,
+            audio={"waveform": wav, "sample_rate": sr}, fps=24.0,
+            match_tail=True)
+        got = int(out["waveform"].shape[-1])
+        assert got == want, (f, direction, got, want)
+        # and the drift the node reports must be under half a sample
+        assert abs(got / sr - (f - 22) / 24.0) * 1000.0 < 0.02, (f, got)
+    print("match_tail check: long tail trimmed, short tail padded, all "
+          "three residues land on the exact sample count")
+
+    # Ref2VA: a graph whose conditioning already carries reference blocks
+    # must keep every one of them, with the motion context audio block
+    # appended rather than replacing the lot. Before this, the node
+    # assigned minimax_refs outright and an R2V graph silently lost its
+    # references at the moment chaining was switched on.
+    captured.clear()
+    existing = [
+        {"kind": "image", "latent_h": 8, "latent_w": 12},
+        {"kind": "video_audio", "latent_h": 8, "latent_w": 12,
+         "latent_t": 3, "ref_audio_t": 5},
+        {"kind": "audio", "ref_audio_t": 9},
+    ]
+    r2v_cond = [["c", {"minimax_refs": [dict(r) for r in existing]}]]
+    out_cond, _ = run(
+        conditioning=r2v_cond, vae=VAE(), latent=target,
+        context_frames=context, context_length="22",
+        audio_context_length=22, context_latent=prev)
+    refs_out = captured["minimax_refs"]
+    assert len(refs_out) == 3, len(refs_out)
+    for got, want in zip(refs_out, existing):
+        assert got["kind"] == want["kind"], (got, want)
+    # the pinned audio is a keyframe now, so the graph's reference list is
+    # not touched at all. Its blocks still push the target origin along,
+    # and the anchors follow it, which is stock's arithmetic and not ours.
+    assert captured["minimax_keyframes"], "keyframes lost on the R2V path"
+    assert audio_kf()["audio_latent"].shape[-1] == 37
+    assert len(r2v_cond[0][1]["minimax_refs"]) == 3
+    print("R2V path: 3 incoming references untouched, motion context audio "
+          "rides as a keyframe, keyframes intact")
+
+    # last_frame passthrough: an fl2va graph's own anchors used to be
+    # replaced outright. The last-frame anchor must survive untouched,
+    # because every keyframe now carries its real index and stock
+    # compensates them all the same way. The first-frame anchor sits
+    # inside the pinned head, which the pinned run already decides, so it
+    # is dropped with a warning.
+    captured.clear()
+    up_kf = [{"resolved_frame_index": 0, "latent": "FF"},
+             {"resolved_frame_index": frames - 1, "latent": "LF"}]
+    fl_cond = [["c", {"minimax_keyframes": [dict(k) for k in up_kf]}]]
+    catcher2 = _Catcher()
+    nodes._LOG.addHandler(catcher2)
+    try:
+        run(
+            conditioning=fl_cond, vae=VAE(), latent=target,
+            context_frames=context, context_length="22",
+            audio_context_length=22, context_latent=prev)
+    finally:
+        nodes._LOG.removeHandler(catcher2)
+    merged = captured["minimax_keyframes"]
+    # kept anchor + 7 pinned steps + the pinned audio keyframe
+    assert len(merged) == 1 + 7 + 1, len(merged)
+    assert merged[0]["latent"] == "LF"
+    assert merged[0]["resolved_frame_index"] == frames - 1
+    assert merged[0] is not fl_cond[0][1]["minimax_keyframes"][1], \
+        "the caller's dict was passed through by reference"
+    assert [kf["resolved_frame_index"] for kf in merged[1:8]] == idx
+    assert any("dropped 1 keyframe anchor" in m for m in catcher2.msgs), \
+        catcher2.msgs
+    # an anchor past the end of this clip is a wiring error: the
+    # conditioning was resolved against a longer clip, so the anchor would
+    # land at the wrong frame. Refuse rather than render it.
+    bad_cond = [["c", {"minimax_keyframes": [
+        {"resolved_frame_index": frames + 17, "latent": "LF"}]}]]
+    try:
+        run(conditioning=bad_cond, vae=VAE(), latent=target,
+                   context_frames=context, context_length="22",
+                   audio_context_length=22, context_latent=prev)
+    except ValueError as e:
+        assert "only %d frames" % frames in str(e), str(e)
+    else:
+        raise AssertionError("out-of-range anchor did not refuse")
+    print("last_frame path: upstream last-frame anchor kept unmodified, "
+          "first-frame anchor dropped from the pinned head, out-of-range "
+          "anchor refused")
+
+    # save -> load -> context_latent roundtrip across "runs"
+    import time
+    saver = nodes.MiniMaxH3MotionContextSaveLatent()
+    loader = nodes.MiniMaxH3MotionContextLoadLatent()
+    (p1,) = saver.save(prev, "h3_context/clip")
+    time.sleep(0.02)
+    prev2 = {"samples": Nested([
+        prev["samples"].parts[0],
+        T(prev["samples"].parts[1].a * 2.0),  # distinguishable content
+    ])}
+    (p2,) = saver.save(prev2, "h3_context/clip")
+    assert p1 != p2
+    (loaded,) = loader.load(p2, clip_index=1)  # specific file
+    parts = loaded["samples"]
+    assert isinstance(parts, list) and len(parts) == 2
+    captured.clear()
+    run(
+        conditioning=[["c", {}]], vae=VAE(), latent=target,
+        context_frames=context, context_length="22",
+        audio_context_length=22, context_latent=loaded)
+    kf3 = audio_kf()
+    want = float(prev2["samples"].parts[1].a[0, 0, 0, -1])
+    got = float(kf3["audio_latent"].a[0, 0, 0, -1])
+    assert got == want, (got, want)
+    assert abs(audio_end() - 22.2) < 1e-6
+    ic1 = loader.IS_CHANGED(p2, clip_index=1)
+    assert isinstance(ic1, str) and p2 in ic1  # cache keys on the real file
+    assert loader.IS_CHANGED("h3_context", clip_index=0) == "disabled"
+    (empty,) = loader.load("h3_context", clip_index=0)
+    assert empty is None
+    print("save/load roundtrip: file loaded, pinned, end_frame %.4f, "
+          "index 0 is first-clip/no-context" % audio_end())
+
+    # retry safety with indexed slots: generating clip 3, re-rolling it
+    # must overwrite slot 3 and always load slot 2, never its own save
+    prevA = {"samples": Nested([prev["samples"].parts[0],
+                                T(np.full((1, 32, 2, audio_t), 7.0,
+                                          dtype=np.float32))])}
+    prevB1 = {"samples": Nested([prev["samples"].parts[0],
+                                 T(np.full((1, 32, 2, audio_t), 8.0,
+                                           dtype=np.float32))])}
+    prevB2 = {"samples": Nested([prev["samples"].parts[0],
+                                 T(np.full((1, 32, 2, audio_t), 9.0,
+                                           dtype=np.float32))])}
+    (pa,) = saver.save(prevA, "h3_context/clip", clip_index=2)   # clip 2 ok
+    assert pa.endswith("_00002.safetensors"), pa  # natural slot name
+    time.sleep(0.02)
+    (pb1,) = saver.save(prevB1, "h3_context/clip", clip_index=3)  # clip 3 try 1
+    time.sleep(0.02)
+    (pb2,) = saver.save(prevB2, "h3_context/clip", clip_index=3)  # re-roll
+    assert pb1 == pb2 and pa != pb1  # re-roll overwrote its own slot
+    # generating clip 3, continuing FROM clip 2: loader index is 2, literally
+    (l3,) = loader.load("h3_context", clip_index=2)
+    got = float(l3["samples"][1].a[0, 0, 0, 0])
+    assert got == 7.0, got  # clip 2's latent, NOT the rejected attempt (8/9)
+    # index 0 is first-clip/no-context: it must not pick up the reject
+    (lnew,) = loader.load("h3_context", clip_index=0)
+    assert lnew is None
+    # asking for a slot that was never saved says so plainly
+    try:
+        loader.load("h3_context", clip_index=7)
+    except FileNotFoundError as e:
+        assert "no saved latent for clip 7" in str(e)
+    else:
+        raise AssertionError("missing slot did not refuse")
+    # an auto-numbered near-miss (trailing underscore) is never matched,
+    # and the error explains the rename
+    (pauto,) = saver.save(prevA, "h3_context/clip", clip_index=0)
+    assert pauto.endswith("_.safetensors"), pauto
+    import re as _re
+    runno = int(_re.search(r"_(\d{5})_\.safetensors$", pauto).group(1))
+    try:
+        loader.load("h3_context", clip_index=runno)
+    except FileNotFoundError as e:
+        assert "trailing underscore" in str(e) and "rename" in str(e), str(e)
+    else:
+        raise AssertionError("auto-numbered file was matched by index")
+    print("indexed slots: re-roll overwrites its slot, loads previous "
+          "clip's latent; auto mode confirmed to return the reject")
+
+    import shutil
+    td = os.path.join(outdir, "clear_test")
+    os.makedirs(td)
+    try:
+        open(os.path.join(td, "clip_00001.safetensors"), "wb").close()
+        open(os.path.join(td, "clip_00002.safetensors"), "wb").close()
+        open(os.path.join(td, "hero_take.safetensors"), "wb").close()
+        open(os.path.join(td, "keep_me.txt"), "w").write("x")
+        assert nodes._clip_slot_exists(td, 1)
+        assert nodes._clip_slot_exists(td, 2)
+        assert not nodes._clip_slot_exists(td, 3)
+        n = nodes._clear_clip_slots(td)
+        assert n == 2, n
+        assert not nodes._clip_slot_exists(td, 1)
+        assert os.path.exists(os.path.join(td, "keep_me.txt"))
+        assert os.path.exists(os.path.join(td, "hero_take.safetensors"))
+    finally:
+        shutil.rmtree(td)
+    print("reset clear: numbered slots gone, custom names left alone")
+
+    print("smoke test passed")
+
+
+if __name__ == "__main__":
+    main()

custom_nodes/ComfyUI-H3-Motion-Context-main/tests/_probe_node_test.py

@@ -0,0 +1,356 @@
+"""Probe node test: drive the seam probe with joins whose answer is known.
+
+No ComfyUI and no GPU. Builds audio where the continuation, the lag and
+the level step are all constructed, then checks the node reports them.
+Clip A goes in as a latent, so the fake audio VAE's decode is what the
+node reads, exactly as it would in a graph.
+"""
+
+import os
+import sys
+import types
+
+import numpy as np
+
+_TESTS_DIR = os.path.dirname(os.path.abspath(__file__))
+_PKG_DIR = os.path.dirname(_TESTS_DIR)
+sys.path.insert(0, _TESTS_DIR)
+
+from _mock_harness import make_mm, make_torch  # noqa: E402
+
+SR = 32000
+FPS = 24.0
+TRIM = 22
+SPAN = int(round(TRIM / FPS * SR))
+# a legal clip length on the ladder: 5g+2 latent steps, 17g+5 frames
+LATENT_T, FRAMES = 37, 124
+
+
+def _install_fakes():
+    """nodes.py imports ComfyUI, and the probe imports nodes.py.
+
+    Only enough of each module to get through import: this test never
+    runs the other nodes, so the fakes do not have to be faithful the way
+    the smoke test's are.
+    """
+    mm = make_mm()
+    for name in ("comfy", "comfy.ldm", "comfy.ldm.minimax"):
+        sys.modules.setdefault(name, types.ModuleType(name))
+    sys.modules["comfy.ldm.minimax.model"] = mm
+    sys.modules["comfy"].ldm = sys.modules["comfy.ldm"]
+    sys.modules["comfy.ldm"].minimax = sys.modules["comfy.ldm.minimax"]
+    sys.modules["comfy.ldm.minimax"].model = mm
+    sys.modules["torch"] = make_torch()
+
+    # safetensors must be faked even though nodes.py never uses it here:
+    # the real package imports torch at module scope, and with the fake
+    # torch in sys.modules that dies with an AttributeError the ImportError
+    # guard in nodes.py does not catch
+    for name, attrs in (("comfy.utils", {}),
+                        ("comfy.model_base", {"MiniMaxH3": type(
+                            "MiniMaxH3", (), {"extra_conds": lambda s, **k: {}})}),
+                        ("folder_paths", {"get_output_directory": lambda: ".",
+                                          "get_save_image_path":
+                                          lambda *a: (".", "x", 1, "", "")}),
+                        ("node_helpers", {"conditioning_set_values":
+                                          lambda c, v, **k: c}),
+                        ("safetensors", {}),
+                        ("safetensors.torch", {"load_file": None,
+                                               "save_file": None})):
+        mod = types.ModuleType(name)
+        for k, v in attrs.items():
+            setattr(mod, k, v)
+        sys.modules[name] = mod
+        if name.startswith("comfy."):
+            setattr(sys.modules["comfy"], name.split(".", 1)[1], mod)
+
+
+_install_fakes()
+# Relative imports (from .nodes) need a package. The folder name has
+# hyphens, so a stub name is used instead of a dynamic import.
+_pkg = types.ModuleType("h3mc_pkg")
+_pkg.__path__ = [_PKG_DIR]
+_pkg.__file__ = os.path.join(_PKG_DIR, "__init__.py")
+sys.modules["h3mc_pkg"] = _pkg
+import h3mc_pkg.probe_node as probe_node  # noqa: E402
+CORR_LIMIT = probe_node.CORR_CREDIBLE
+
+
+class Tensor:
+    """Enough of a tensor for the node's shape checks and the fake VAE."""
+
+    def __init__(self, a):
+        self.a = np.asarray(a)
+
+    @property
+    def shape(self):
+        return self.a.shape
+
+    @property
+    def ndim(self):
+        return self.a.ndim
+
+    def __getitem__(self, idx):
+        return Tensor(self.a[idx])
+
+    def unsqueeze(self, d):
+        return Tensor(np.expand_dims(self.a, d))
+
+    def __array__(self, dtype=None, copy=None):
+        # real torch tensors implement this, which is how np.asarray()
+        # accepts one; without it numpy falls back to iterating the
+        # object and the conversion fails
+        return self.a if dtype is None else self.a.astype(dtype)
+
+
+class Nested:
+    def __init__(self, parts):
+        self.parts = parts
+
+    def unbind(self):
+        return list(self.parts)
+
+
+class FakeAudioVAE:
+    """Decodes by handing back the waveform stashed on it.
+
+    The point of the test is the node's anchoring and measurement, not
+    the VAE, so the decode is a lookup. It returns [B, C, L], which the
+    node must not assume the orientation of.
+    """
+
+    audio_sample_rate = SR
+
+    def __init__(self, mono):
+        self.mono = mono
+
+    def decode(self, z):
+        return Tensor(np.stack([self.mono, self.mono])[None, ...])
+
+
+def _latent(mono, latent_t=LATENT_T):
+    """An AV latent whose video stream says how many frames the clip is."""
+    steps = max(1, int(round(len(mono) / SR * 40)))
+    return {"samples": Nested([
+        Tensor(np.zeros((1, 16, latent_t, 4, 4), dtype=np.float32)),
+        Tensor(np.zeros((1, 32, 2, steps), dtype=np.float32)),
+    ])}
+
+
+def _audio(mono):
+    return {"waveform": np.stack([mono, mono])[None, ...],
+            "sample_rate": SR}
+
+
+def _bed(n, seed, freq=110.0, amp=1.0, noise=0.02):
+    """Periodic content plus a steady floor. The tone is deliberately
+    periodic: it is what the peak tracker has to avoid cycle-hopping on."""
+    rng = np.random.default_rng(seed)
+    t = np.arange(n) / SR
+    return (amp * np.sin(2 * np.pi * freq * t)
+            + 0.3 * amp * np.sin(2 * np.pi * freq * 2.5 * t)
+            + noise * rng.standard_normal(n))
+
+
+def _gated(n, seed, floor_amp, freq=110.0, on_ms=120.0, off_ms=80.0):
+    """Tone bursts over a continuous noise bed.
+
+    The floor metric reads the quiet moments between content, so a fully
+    sustained tone gives it nothing and it collapses onto broadband. That
+    limitation is documented in level_step.py, so the fixture for a floor
+    step has to have rests in it.
+    """
+    rng = np.random.default_rng(seed)
+    t = np.arange(n) / SR
+    tone = np.sin(2 * np.pi * freq * t)
+    period = int(round((on_ms + off_ms) / 1000.0 * SR))
+    on = int(round(on_ms / 1000.0 * SR))
+    gate = (np.arange(n) % period) < on
+    return tone * gate + floor_amp * rng.standard_normal(n)
+
+
+def _run(a_mono, b_mono, **kw):
+    node = probe_node.MiniMaxH3MotionContextSeamProbe()
+    out = node.probe(clip_b_untrimmed=_audio(b_mono), trim_frames=TRIM,
+                     clip_a_latent=_latent(a_mono),
+                     audio_vae=FakeAudioVAE(a_mono), fps=FPS, **kw)
+    return out["result"][0], out["result"][1]
+
+
+def _num(report, label):
+    for line in report.splitlines():
+        s = line.strip()
+        if s.startswith(label):
+            for tok in s[len(label):].split():
+                try:
+                    return float(tok)
+                except ValueError:
+                    continue
+    raise AssertionError("no %r line in:\n%s" % (label, report))
+
+
+def main():
+    # clip A is exactly FRAMES long, which is what the latent declares.
+    # The node tail-matches to that, so the fixtures must agree.
+    a_len = int(round(FRAMES / FPS * SR))
+    source = _bed(a_len + SPAN * 3, seed=1)
+    a = source[:a_len]
+
+    # 1. perfect continuation: B's head IS A's tail
+    b = np.concatenate([a[-SPAN:], source[a_len:a_len + SPAN * 2]])
+    passthru, rep = _run(a, b)
+    corr, lag = _num(rep, "mean corr"), _num(rep, "lag")
+    assert corr > 0.95, (corr, rep)
+    assert abs(lag) < 1.0, (lag, rep)
+    assert "clean continuation" in rep, rep
+    assert passthru["sample_rate"] == SR
+    print("1. exact continuation: corr %.3f, lag %+.2f ms" % (corr, lag))
+
+    # 2. late by one audio step
+    shift = int(round(0.025 * SR))
+    b_late = np.concatenate([source[a_len - SPAN - shift:a_len - shift],
+                             source[a_len:a_len + SPAN * 2]])
+    _, rep = _run(a, b_late)
+    corr, lag = _num(rep, "mean corr"), _num(rep, "lag")
+    assert corr > 0.9, (corr, rep)
+    assert abs(lag - 25.0) < 2.0, (lag, rep)
+    print("2. one step late: corr %.3f, lag %+.2f ms (built as +25.0)"
+          % (corr, lag))
+
+    # 3. imitation, not continuation. A different noise seed alone is not
+    #    enough, the deterministic tone would still correlate at 0.99.
+    b_fake = np.concatenate([_bed(SPAN, seed=99, freq=173.0),
+                             source[a_len:a_len + SPAN * 2]])
+    _, rep = _run(a, b_fake)
+    corr = _num(rep, "mean corr")
+    assert corr < CORR_LIMIT, (corr, rep)
+    assert "imitating" in rep or "not being continued" in rep, rep
+    print("3. unrelated head: corr %.3f, flagged as imitation" % corr)
+
+    # 4. same music either side, but B's bed is 30 dB quieter. Invisible
+    #    to broadband because the content matches.
+    gated_a = _gated(a_len, seed=11, floor_amp=0.02)
+    loud = np.concatenate([gated_a[-SPAN:],
+                           _gated(SPAN * 2, seed=12, floor_amp=0.02)])
+    quiet = np.concatenate([gated_a[-SPAN:],
+                            _gated(SPAN * 2, seed=12, floor_amp=0.0006)])
+    _, rep = _run(gated_a, quiet)
+    floor, bb = _num(rep, "floor"), _num(rep, "broadband")
+    assert floor > 0.5, (floor, rep)
+    assert bb < 0.4, (bb, rep)
+    assert "bed underneath" in rep, rep
+    print("4. floor drop: floor %.3f (audible), broadband %.3f (ok), "
+          "diagnosed as ambience restart" % (floor, bb))
+
+    # 5. no level step when both sides share a bed
+    _, rep = _run(gated_a, loud)
+    floor = _num(rep, "floor")
+    assert floor < 0.25, (floor, rep)
+    assert "bed underneath" not in rep, rep
+    print("5. matched bed: floor step %.3f, below the clean threshold"
+          % floor)
+
+    # 6. a lag outside the search window must not become a confident
+    #    number. On non-periodic content nothing correlates, so no lag.
+    rng = np.random.default_rng(21)
+    na = rng.standard_normal(a_len)
+    big = int(round(0.060 * SR))
+    nb = np.concatenate([na[-SPAN - big:-big],
+                         rng.standard_normal(SPAN * 2)])
+    _, rep = _run(na, nb, search_ms=20.0)
+    assert "not reported" in rep, rep
+    assert _num(rep, "mean corr") < CORR_LIMIT, rep
+    print("6. lag outside the search window: no lag reported rather than "
+          "a confident wrong one")
+
+    # 7. the aliasing limitation, asserted rather than left implicit.
+    #    Beat-driven music is exactly this case.
+    period_ms = 1000.0 / 55.0  # 110 and 275 Hz share a 55 Hz fundamental
+    b_alias = np.concatenate([source[a_len - SPAN - big:a_len - big],
+                              source[a_len:a_len + SPAN * 2]])
+    _, rep = _run(a, b_alias, search_ms=20.0)
+    lag = _num(rep, "lag")
+    assert _num(rep, "mean corr") > 0.9, rep
+    assert abs(lag - 60.0) > 10.0, (lag, rep)
+    assert abs(((60.0 - lag) / period_ms)
+               - round((60.0 - lag) / period_ms)) < 0.05, (lag, rep)
+    print("7. periodic aliasing: 60.0 ms offset read as %+.2f ms, a whole "
+          "number of cycles out (known limitation)" % lag)
+
+    # 8. the node must tail-match clip A itself. Hand it a decode that is
+    #    a third of an audio step long, the real grid overhang, and the
+    #    lag must stay at zero. Without the internal match this reads as
+    #    a confident 8.3 ms, which is exactly the artifact the node
+    #    exists to remove.
+    over = int(round(SR / 40.0 / 3.0))
+    a_long = np.concatenate([a, source[a_len:a_len + over]])
+    node = probe_node.MiniMaxH3MotionContextSeamProbe()
+    out = node.probe(clip_b_untrimmed=_audio(b), trim_frames=TRIM,
+                     clip_a_latent=_latent(a),  # declares FRAMES frames
+                     audio_vae=FakeAudioVAE(a_long), fps=FPS)
+    lag = _num(out["result"][1], "lag")
+    assert abs(lag) < 1.0, (lag, out["result"][1])
+    print("8. overlong decode (%d samples, %.2f ms): trimmed internally, "
+          "lag stays %+.2f ms" % (over, over / SR * 1000.0, lag))
+
+    # 9. wrong wiring refused with a reason, audio still passed through
+    node = probe_node.MiniMaxH3MotionContextSeamProbe()
+    cases = [
+        ("TRIMMED", dict(clip_b_untrimmed=_audio(b[SPAN:][:SPAN // 2]),
+                         trim_frames=TRIM, clip_a_latent=_latent(a),
+                         audio_vae=FakeAudioVAE(a))),
+        ("trim_frames is 0", dict(clip_b_untrimmed=_audio(b),
+                                  trim_frames=0, clip_a_latent=_latent(a),
+                                  audio_vae=FakeAudioVAE(a))),
+        ("no clip_a_latent", dict(clip_b_untrimmed=_audio(b),
+                                  trim_frames=TRIM)),
+        ("no audio_vae", dict(clip_b_untrimmed=_audio(b),
+                              trim_frames=TRIM,
+                              clip_a_latent=_latent(a))),
+    ]
+    for needle, kwargs in cases:
+        res = node.probe(fps=FPS, **kwargs)
+        assert needle in res["result"][1], (needle, res["result"][1])
+        assert res["result"][0]["sample_rate"] == SR
+    vid_only = {"samples": Nested([
+        Tensor(np.zeros((1, 16, LATENT_T, 4, 4), dtype=np.float32))])}
+    res = node.probe(clip_b_untrimmed=_audio(b), trim_frames=TRIM,
+                     clip_a_latent=vid_only, audio_vae=FakeAudioVAE(a),
+                     fps=FPS)
+    assert "no audio stream" in res["result"][1], res["result"][1]
+    print("9. bad wiring: trimmed input, zero span, missing latent, "
+          "missing VAE and video-only latent each refused with a reason, "
+          "audio still passed through")
+
+    # 10. a SHORT clip A gets padded, and padding moves the end of the
+    #     array without moving the content. So the padded anchor and the
+    #     raw one disagree by exactly the pad, and the node must report
+    #     both rather than pick one. Built here so the raw anchor is the
+    #     correct one: B's head is A's real tail.
+    short = int(round(SR / 40.0 / 3.0))
+    a_short = a[:a_len - short]
+    b_short = np.concatenate([a_short[-SPAN:],
+                              source[a_len:a_len + SPAN * 2]])
+    node = probe_node.MiniMaxH3MotionContextSeamProbe()
+    out = node.probe(clip_b_untrimmed=_audio(b_short), trim_frames=TRIM,
+                     clip_a_latent=_latent(a),  # declares FRAMES frames
+                     audio_vae=FakeAudioVAE(a_short), fps=FPS)
+    rep = out["result"][1]
+    assert "cross-check" in rep, rep
+    assert "padded %d samples" % short in rep, rep
+    lags = [float(l.strip()[len("lag"):].split()[0])
+            for l in rep.splitlines() if l.strip().startswith("lag")]
+    assert len(lags) == 2, (lags, rep)
+    padded_lag, raw_lag = lags
+    assert abs(raw_lag) < 1.0, (raw_lag, rep)
+    assert abs(abs(padded_lag - raw_lag) - short / SR * 1000.0) < 1.0, \
+        (padded_lag, raw_lag, rep)
+    print("10. short clip A: both anchors reported, %+.2f ms padded vs "
+          "%+.2f ms raw, differing by the %.2f ms pad"
+          % (padded_lag, raw_lag, short / SR * 1000.0))
+
+    print("probe node test passed")
+
+
+if __name__ == "__main__":
+    main()

custom_nodes/ComfyUI-H3-Motion-Context-main/tests/freeze_detect.py

@@ -0,0 +1,286 @@
+"""Freeze probe: did a shot render as a still instead of a held frame?
+
+The airlock technique for chaining across a setup change asks clip N+1 to
+open by holding clip N's exact closing framing for a beat before cutting
+to the new setup. That works, but a held framing with nothing happening
+in it renders as a literal freeze: several seconds of a motionless actor
+that reads as a stalled video player, not a pause. It is easy to miss on
+a first watch and obvious once someone points at it.
+
+This walks a clip and reports every stretch where the picture stops
+moving.
+
+Usage:
+    python freeze_detect.py clip01.mp4 clip02.mp4 ...
+    python freeze_detect.py --head-frames 22 --min-ms 400 clip02.mp4
+
+Method: decode, downscale each frame to a small grey thumbnail, and take
+the mean absolute difference between consecutive thumbnails. Downscaling
+is what makes this work on compressed video, since it averages away the
+codec noise that would otherwise register as motion in an otherwise
+static frame.
+
+The threshold is relative, not absolute. An absolute one cannot serve
+both a dim interior and a bright exterior, so each clip is scored against
+its own median frame difference and a stretch is flagged when motion
+drops below `--rel` of that median (default 0.15) for at least `--min-ms`
+(default 400). A separate absolute floor catches duplicated frames that
+are identical to within rounding.
+
+The first `--head-frames` are reported separately whatever they score,
+because on a chained clip those are the pinned head: the model's re-render
+of the previous clip's tail, which is the region the trim removes and the
+region an airlock hold lives in. Motion there that is far below the rest
+of the clip means the hold had no business in it.
+
+Reading the result:
+    no runs                  nothing held
+    a run inside the head    the airlock hold has nothing happening in
+                             it. Give it a breath, a weight shift, an
+                             eyeline change. The framing holds; the
+                             performer should not.
+    a run elsewhere          the prompt ran out of things for the shot
+                             to do, or the clip is longer than the
+                             action written for it
+
+Dependencies: numpy, plus ONE of av / cv2 / imageio for decoding.
+ComfyUI's embedded python has numpy and PyAV; run it with that
+interpreter if your system python lacks them.
+"""
+
+import argparse
+import os
+import sys
+
+import numpy as np
+
+THUMB_W, THUMB_H = 64, 36
+
+
+def _to_thumb(rgb):
+    """[H, W, 3] uint8 -> [THUMB_H, THUMB_W] float64 grey, box averaged.
+
+    Box averaging rather than nearest sampling, because nearest keeps the
+    per-pixel codec noise this is trying to average away.
+    """
+    a = np.asarray(rgb)
+    if a.ndim == 3 and a.shape[2] >= 3:
+        grey = a[..., :3].astype(np.float64) @ np.array([0.299, 0.587, 0.114])
+    else:
+        grey = a.astype(np.float64).squeeze()
+    h, w = grey.shape
+    ys = np.linspace(0, h, THUMB_H + 1).astype(int)
+    xs = np.linspace(0, w, THUMB_W + 1).astype(int)
+    out = np.empty((THUMB_H, THUMB_W), dtype=np.float64)
+    for i in range(THUMB_H):
+        y0, y1 = ys[i], max(ys[i] + 1, ys[i + 1])
+        row = grey[y0:y1]
+        for j in range(THUMB_W):
+            x0, x1 = xs[j], max(xs[j] + 1, xs[j + 1])
+            out[i, j] = row[:, x0:x1].mean()
+    return out
+
+
+def iter_thumbs(path):
+    """Yield (thumbnail, fps). Tries PyAV, then OpenCV, then imageio."""
+    try:
+        import av
+        with av.open(path) as container:
+            stream = container.streams.video[0]
+            fps = float(stream.average_rate) if stream.average_rate else 24.0
+            for frame in container.decode(stream):
+                yield _to_thumb(frame.to_ndarray(format="rgb24")), fps
+        return
+    except ImportError:
+        pass
+
+    try:
+        import cv2
+        cap = cv2.VideoCapture(path)
+        if not cap.isOpened():
+            raise RuntimeError("cv2 could not open %s" % path)
+        fps = cap.get(cv2.CAP_PROP_FPS) or 24.0
+        while True:
+            ok, frame = cap.read()
+            if not ok:
+                break
+            yield _to_thumb(frame[..., ::-1]), float(fps)
+        cap.release()
+        return
+    except ImportError:
+        pass
+
+    try:
+        import imageio.v3 as iio
+        meta = iio.immeta(path)
+        fps = float(meta.get("fps", 24.0))
+        for frame in iio.imiter(path):
+            yield _to_thumb(frame), fps
+        return
+    except ImportError:
+        pass
+
+    raise RuntimeError(
+        "no video decoder available. Install one of av, opencv-python or "
+        "imageio, or run this with ComfyUI's embedded python which ships "
+        "PyAV.")
+
+
+def frame_deltas(path):
+    """Mean absolute difference between consecutive frames, 0..255 scale."""
+    deltas, prev, fps = [], None, 24.0
+    for thumb, f in iter_thumbs(path):
+        fps = f
+        if prev is not None:
+            deltas.append(float(np.abs(thumb - prev).mean()))
+        prev = thumb
+    return np.array(deltas), fps
+
+
+def find_runs(deltas, fps, rel=0.15, abs_floor=0.15, min_ms=400.0):
+    """Stretches where motion sits below the clip's own normal.
+
+    Returns a list of (start_frame, end_frame_exclusive, mean_delta,
+    mean_ratio). `deltas[i]` is the motion between frame i and i+1, so a
+    run over delta indices [a, b) means frames a..b are the still ones.
+    """
+    if len(deltas) < 2:
+        return []
+    median = float(np.median(deltas))
+    if median <= 1e-9:
+        # the entire clip is static; report it as one run rather than
+        # dividing by a zero normal
+        return [(0, len(deltas) + 1, float(deltas.mean()), 0.0)]
+    ratio = deltas / median
+    still = (ratio < rel) | (deltas < abs_floor)
+    min_frames = max(1, int(round(min_ms / 1000.0 * fps)))
+
+    runs, start = [], None
+    for i, s in enumerate(list(still) + [False]):
+        if s and start is None:
+            start = i
+        elif not s and start is not None:
+            if i - start >= min_frames:
+                seg = deltas[start:i]
+                runs.append((start, i + 1, float(seg.mean()),
+                             float((seg / median).mean())))
+            start = None
+    return runs
+
+
+def report(path, head_frames, rel, abs_floor, min_ms):
+    deltas, fps = frame_deltas(path)
+    name = os.path.basename(path)
+    if len(deltas) < 2:
+        print("%-28s  too few frames to score" % name)
+        return 0
+    median = float(np.median(deltas))
+    runs = find_runs(deltas, fps, rel, abs_floor, min_ms)
+    print("%-28s  %d frames @ %.3f fps, median motion %.3f" %
+          (name, len(deltas) + 1, fps, median))
+
+    if head_frames > 0 and len(deltas) > head_frames:
+        head = deltas[:head_frames]
+        h_ratio = float(head.mean()) / median if median > 0 else 0.0
+        flag = "  <- HELD, give it something to do" if h_ratio < rel else ""
+        print("    head (first %d frames): motion %.3f, %.2fx the clip "
+              "median%s" % (head_frames, float(head.mean()), h_ratio, flag))
+
+    if not runs:
+        print("    no freezes")
+        return 0
+    for a, b, mean_d, mean_r in runs:
+        # deltas[i] is the motion between frame i and frame i+1, so a run
+        # over frames a..b-1 holds still for b-1-a intervals
+        secs = (b - 1 - a) / fps
+        where = "head" if a < head_frames else "body"
+        print("    FREEZE %6.2fs to %6.2fs  (%5.2fs, %s)  motion %.3f "
+              "= %.2fx median" %
+              (a / fps, (b - 1) / fps, secs, where, mean_d, mean_r))
+    return len(runs)
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("files", nargs="+", help="video clips to scan")
+    ap.add_argument("--head-frames", type=int, default=22,
+                    help="frames of pinned head to report separately; match "
+                         "your context_length, or 0 to skip")
+    ap.add_argument("--rel", type=float, default=0.15,
+                    help="fraction of the clip's median frame motion below "
+                         "which a frame counts as still")
+    ap.add_argument("--abs-floor", type=float, default=0.15,
+                    help="absolute motion floor on a 0-255 scale, for "
+                         "duplicated frames in an already still shot")
+    ap.add_argument("--min-ms", type=float, default=400.0,
+                    help="shortest stretch worth reporting")
+    args = ap.parse_args()
+
+    total = 0
+    for path in args.files:
+        total += report(path, args.head_frames, args.rel, args.abs_floor,
+                        args.min_ms)
+        print()
+    print("%d freeze run(s) across %d clip(s)" % (total, len(args.files)))
+    if total:
+        print("A held framing needs a breath, a weight shift or an eyeline "
+              "change written into the prompt. The camera holds; the "
+              "performer should not.")
+
+
+def _self_test():
+    """Synthetic checks for the detection maths, no video files needed."""
+    rng = np.random.default_rng(0)
+    fps = 24.0
+
+    # 120 frames of ordinary motion with a 48 frame (2s) freeze at 30
+    deltas = rng.uniform(1.8, 2.2, 120)
+    deltas[30:78] = rng.uniform(0.0, 0.02, 48)
+    runs = find_runs(deltas, fps, min_ms=400.0)
+    assert len(runs) == 1, runs
+    a, b, mean_d, mean_r = runs[0]
+    assert a == 30 and b == 79, (a, b)          # frames 30..78 identical
+    assert abs((b - 1 - a) / fps - 2.0) < 1e-9  # which is exactly 2.0s
+    assert mean_r < 0.02, mean_r
+
+    # a short dip must not be reported at the default 400 ms
+    short = rng.uniform(1.8, 2.2, 120)
+    short[50:55] = 0.01
+    assert find_runs(short, fps, min_ms=400.0) == []
+    assert len(find_runs(short, fps, min_ms=100.0)) == 1
+
+    # a dim clip with small absolute motion but no freeze must stay clean,
+    # which is the case an absolute-only threshold would fail
+    dim = rng.uniform(0.30, 0.34, 120)
+    assert find_runs(dim, fps, min_ms=400.0) == [], "dim clip false positive"
+
+    # and a freeze inside that same dim clip must still be caught
+    dim2 = dim.copy()
+    dim2[60:100] = 0.001
+    assert len(find_runs(dim2, fps, min_ms=400.0)) == 1
+
+    # a wholly static clip reports one run rather than dividing by zero
+    assert len(find_runs(np.zeros(60), fps)) == 1
+
+    # thumbnailing must average codec noise away: two frames of the same
+    # picture plus independent noise read as far less motion than two
+    # genuinely different pictures
+    base = rng.integers(0, 255, (360, 640, 3)).astype(np.uint8)
+    noisy = np.clip(base.astype(int) +
+                    rng.integers(-6, 7, base.shape), 0, 255).astype(np.uint8)
+    other = rng.integers(0, 255, (360, 640, 3)).astype(np.uint8)
+    still_d = float(np.abs(_to_thumb(base) - _to_thumb(noisy)).mean())
+    moved_d = float(np.abs(_to_thumb(base) - _to_thumb(other)).mean())
+    assert still_d < 0.5, still_d
+    assert moved_d > 10 * still_d, (still_d, moved_d)
+
+    print("freeze_detect self-test passed "
+          "(still %.3f vs moved %.3f after thumbnailing)" %
+          (still_d, moved_d))
+
+
+if __name__ == "__main__":
+    if "--self-test" in sys.argv:
+        _self_test()
+    else:
+        main()

custom_nodes/ComfyUI-H3-Motion-Context-main/tests/level_step.py

@@ -0,0 +1,334 @@
+"""Level step probe: does the sound level jump at a join?
+
+Companion to seam_probe.py. seam_probe answers "is clip B's audio a real
+continuation of clip A's, or an imitation" by cross-correlation. This
+answers a different and simpler question: "does the loudness or the room
+tone change abruptly across the cut?" A chain can be perfectly phase
+locked and still audibly step if one clip invents its own silence.
+
+Usage:
+    python level_step.py clip01.flac clip02.flac clip03.flac ...
+    python level_step.py --joins 12.5,25.0 episode.wav
+
+Give the DELIVERED clips in chain order (trimmed, the ones you actually
+concatenate), or one already concatenated file plus the join times in
+seconds. Either way each join is scored twice:
+
+    broadband   RMS of the window either side. Catches gain jumps.
+    floor       10th percentile of short-window RMS, which tracks the
+                room tone under the content. Catches the failure where
+                each clip invents its own silence and the ambience
+                restarts at every cut, even though the music matches.
+
+Both are reported as a normalised step in [0, 1]:
+
+    step = |a - b| / (a + b)
+
+so 0.0 is identical level, 1.0 means one side is digitally silent. The
+dB difference is printed alongside because it is easier to judge by ear.
+
+Reading the result:
+    floor < 0.25       clean, the bed runs through the cut
+    floor 0.25 to 0.50 marginal, listen to it
+    floor > 0.50       audible step
+
+Broadband is judged more loosely (ok below 0.40) because the content
+either side of a real cut is different by definition, so some movement
+there is the edit, not a fault. The floor is the one that should hold
+still. If broadband is fine and floor is bad,
+                   the ambience is resetting: wire the previous clip's
+                   audio (context_latent, or context_audio + audio_vae)
+                   into Motion Context so the next clip hears it.
+
+One limitation worth knowing: the floor figure reads the quiet moments
+between content, so it only means something when the content lets up.
+Wall to wall music with no gaps has nothing underneath it to measure and
+the floor number collapses onto the broadband one. Dialogue, ambience
+and anything with rests are where it earns its keep.
+
+Sample rates are printed per file and any mismatch is called out loudly.
+A stream-copy concat cannot change rate mid stream, so mixing 32 kHz H3
+output with a 48 kHz assumption decodes the tail to silence while every
+duration assert stays green. H3 emits 32 kHz. Read it, never assume it.
+
+Dependencies: numpy, plus ONE of torchaudio / soundfile / stdlib wave.
+ComfyUI's embedded python has numpy and torchaudio; run it with that
+interpreter if your system python lacks them.
+"""
+
+import argparse
+import sys
+
+import numpy as np
+
+
+def load_audio(path):
+    """Return (mono float64 array, sample_rate). Same loader as seam_probe."""
+    try:
+        import torchaudio
+        wav, sr = torchaudio.load(path)
+        return wav.mean(dim=0).numpy().astype(np.float64), int(sr)
+    except Exception:
+        pass
+    try:
+        import soundfile as sf
+        data, sr = sf.read(path, always_2d=True)
+        return data.mean(axis=1).astype(np.float64), int(sr)
+    except Exception:
+        pass
+    import wave
+    with wave.open(path, "rb") as w:
+        sr = w.getframerate()
+        n = w.getnframes()
+        width = w.getsampwidth()
+        ch = w.getnchannels()
+        raw = w.readframes(n)
+    dtype = {1: np.uint8, 2: np.int16, 4: np.int32}.get(width)
+    if dtype is None:
+        raise RuntimeError("unsupported wav sample width %d" % width)
+    data = np.frombuffer(raw, dtype=dtype).astype(np.float64)
+    if width == 1:
+        data -= 128.0
+    scale = {1: 128.0, 2: 32768.0, 4: 2147483648.0}[width]
+    data = data.reshape(-1, ch).mean(axis=1) / scale
+    return data, sr
+
+
+def _pair_label(a_name, b_name):
+    import os
+    short = lambda p: os.path.splitext(os.path.basename(p))[0][-8:]
+    return "%s|%s" % (short(a_name), short(b_name))
+
+
+def rms(x):
+    if len(x) == 0:
+        return 0.0
+    return float(np.sqrt(np.mean(np.square(x))))
+
+
+def floor_level(x, sr, win_ms=20.0, pct=10.0):
+    """Noise floor estimate: a low percentile of short-window RMS.
+
+    The quietest moments of a window are room tone plus whatever the
+    encoder left behind. Content (a note, a word) raises the mean but
+    barely moves the 10th percentile, so this isolates the bed that is
+    supposed to run continuously underneath the whole chain.
+    """
+    win = max(1, int(round(win_ms / 1000.0 * sr)))
+    n = len(x) // win
+    if n < 3:
+        return rms(x)
+    trimmed = x[:n * win].reshape(n, win)
+    levels = np.sqrt(np.mean(np.square(trimmed), axis=1))
+    return float(np.percentile(levels, pct))
+
+
+def step_ratio(a, b):
+    """Normalised difference in [0, 1]. 1.0 when one side is silent."""
+    denom = a + b
+    if denom <= 1e-12:
+        return 0.0
+    return abs(a - b) / denom
+
+
+def db_delta(a, b):
+    """Level change from a to b in dB, clamped so digital silence on one
+    side prints as a readable -99 rather than a wall of digits."""
+    if a <= 1e-9 and b <= 1e-9:
+        return 0.0
+    lo = 1e-9
+    d = 20.0 * np.log10(max(b, lo) / max(a, lo))
+    return float(np.clip(d, -99.0, 99.0))
+
+
+# broadband level legitimately moves across a real cut, because the
+# content on either side is different by definition. The floor should
+# not: the bed under the content is supposed to run continuously
+# through the whole chain. So they get different thresholds.
+BROADBAND_OK, BROADBAND_BAD = 0.40, 0.65
+FLOOR_OK, FLOOR_BAD = 0.25, 0.50
+
+
+def verdict(step, ok=0.25, bad=0.50):
+    if step < ok:
+        return "ok"
+    if step < bad:
+        return "MARGINAL"
+    return "STEP"
+
+
+def score_join(tail, head, sr, label):
+    """Score one join given the audio either side of it."""
+    b_tail, b_head = rms(tail), rms(head)
+    f_tail, f_head = floor_level(tail, sr), floor_level(head, sr)
+    b_step = step_ratio(b_tail, b_head)
+    f_step = step_ratio(f_tail, f_head)
+    print("%-20s  broadband %.3f (%+6.1f dB) %-8s   "
+          "floor %.3f (%+6.1f dB) %-8s" %
+          (label, b_step, db_delta(b_tail, b_head),
+           verdict(b_step, BROADBAND_OK, BROADBAND_BAD),
+           f_step, db_delta(f_tail, f_head),
+           verdict(f_step, FLOOR_OK, FLOOR_BAD)))
+    return b_step, f_step
+
+
+def from_clips(paths, win_ms, guard_ms):
+    rates, joins = [], []
+    prev = None
+    for p in paths:
+        data, sr = load_audio(p)
+        rates.append((p, sr, len(data) / sr))
+        if prev is not None:
+            joins.append((prev[0], data, sr, prev[1], p))
+        prev = (data, p)
+
+    print("clips:")
+    for p, sr, dur in rates:
+        print("  %-40s %6d Hz  %7.3fs" % (p[-40:], sr, dur))
+    uniq = sorted(set(sr for _, sr, _ in rates))
+    if len(uniq) > 1:
+        print()
+        print("  !! SAMPLE RATE MISMATCH across the chain: %s" % uniq)
+        print("     A stream-copy concat cannot switch rate mid stream. "
+              "Resample to one rate before joining, or the tail decodes "
+              "to silence with every duration check still passing.")
+    print()
+
+    win = None
+    results = []
+    print("%-20s  %-42s   %s" % ("join", "broadband", "floor"))
+    for a_data, b_data, sr, a_name, b_name in joins:
+        win = int(round(win_ms / 1000.0 * sr))
+        guard = int(round(guard_ms / 1000.0 * sr))
+        tail = a_data[max(0, len(a_data) - guard - win):len(a_data) - guard]
+        head = b_data[guard:guard + win]
+        if len(tail) < win // 2 or len(head) < win // 2:
+            print("%-20s  too short to score" % _pair_label(a_name, b_name))
+            continue
+        results.append(score_join(tail, head, sr,
+                                  _pair_label(a_name, b_name)))
+    return results
+
+
+def from_single(path, join_times, win_ms, guard_ms):
+    data, sr = load_audio(path)
+    print("file: %s   %d Hz   %.3fs" % (path, sr, len(data) / sr))
+    print()
+    win = int(round(win_ms / 1000.0 * sr))
+    guard = int(round(guard_ms / 1000.0 * sr))
+    results = []
+    print("%-20s  %-42s   %s" % ("join", "broadband", "floor"))
+    for t in join_times:
+        c = int(round(t * sr))
+        tail = data[max(0, c - guard - win):max(0, c - guard)]
+        head = data[min(len(data), c + guard):min(len(data), c + guard + win)]
+        if len(tail) < win // 2 or len(head) < win // 2:
+            print("%-20s  outside the file" % ("%.2fs" % t))
+            continue
+        results.append(score_join(tail, head, sr, "%.2fs" % t))
+    return results
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("files", nargs="+",
+                    help="delivered clips in chain order, or one "
+                         "concatenated file with --joins")
+    ap.add_argument("--joins", default=None,
+                    help="comma separated join times in seconds; use with "
+                         "a single concatenated file")
+    ap.add_argument("--win-ms", type=float, default=400.0,
+                    help="measurement window either side of the join. Long "
+                         "enough to span typical gaps in the content: a "
+                         "window that lands entirely inside a musical rest "
+                         "on one side and a downbeat on the other reports a "
+                         "step that is really just the material")
+    ap.add_argument("--guard-ms", type=float, default=5.0,
+                    help="skipped either side, so a single splice sample "
+                         "cannot dominate the window")
+    args = ap.parse_args()
+
+    if args.joins:
+        if len(args.files) != 1:
+            sys.exit("--joins takes exactly one concatenated file")
+        times = [float(t) for t in args.joins.split(",") if t.strip()]
+        results = from_single(args.files[0], times, args.win_ms, args.guard_ms)
+    else:
+        if len(args.files) < 2:
+            sys.exit("give at least two clips, or one file with --joins")
+        results = from_clips(args.files, args.win_ms, args.guard_ms)
+
+    print()
+    if not results:
+        sys.exit("no joins scored")
+    b = np.array([r[0] for r in results])
+    f = np.array([r[1] for r in results])
+    print("summary over %d joins:" % len(results))
+    print("  broadband  median %.3f  worst %.3f  passing (<%.2f) %d/%d" %
+          (np.median(b), b.max(), BROADBAND_OK,
+           int((b < BROADBAND_OK).sum()), len(b)))
+    print("  floor      median %.3f  worst %.3f  passing (<%.2f) %d/%d" %
+          (np.median(f), f.max(), FLOOR_OK,
+           int((f < FLOOR_OK).sum()), len(f)))
+    if np.median(f) >= FLOOR_OK and np.median(b) < BROADBAND_OK:
+        print()
+        print("  -> AMBIENCE RESET: content levels match but the bed under "
+              "them does not. Each clip is inventing its own room tone. "
+              "Carry the previous clip's audio across the join "
+              "(context_latent, or context_audio + audio_vae).")
+    elif np.median(b) >= BROADBAND_BAD:
+        print()
+        print("  -> LEVEL STEP: check for a gain change between clips, or "
+              "a normalisation pass applied per clip instead of once at "
+              "the end.")
+    elif np.median(b) < BROADBAND_OK and np.median(f) < FLOOR_OK:
+        print()
+        print("  -> joins are level-continuous. If they still sound wrong, "
+              "run seam_probe.py: the problem is phase, not level.")
+
+
+def _self_test():
+    """Synthetic checks for the scoring maths, no audio files needed."""
+    sr = 32000
+    rng = np.random.default_rng(0)
+    t = np.arange(sr) / sr
+    # gated tone, not a continuous one: the floor estimator reads the
+    # quiet moments between content, so content that never stops has no
+    # floor underneath it to find (see the note in the module docstring)
+    gate = ((t * 4).astype(int) % 2 == 0).astype(np.float64)
+    tone = 0.3 * np.sin(2 * np.pi * 220 * t) * gate
+    bed = 0.01 * rng.standard_normal(sr)
+
+    assert abs(step_ratio(0.5, 0.5)) < 1e-12
+    assert abs(step_ratio(0.5, 0.0) - 1.0) < 1e-12
+    assert abs(step_ratio(0.0, 0.0)) < 1e-12
+    assert 0.0 < step_ratio(0.5, 0.4) < 0.2
+
+    # a floor estimate must track the bed, not the tone on top of it
+    with_bed = floor_level(tone + bed, sr)
+    without = floor_level(tone, sr)
+    assert with_bed > without * 2, (with_bed, without)
+    assert abs(with_bed - rms(bed)) < rms(bed), (with_bed, rms(bed))
+
+    # ambience reset: same content, one side has no bed under it
+    a_step = step_ratio(rms(tone + bed), rms(tone))
+    f_step = step_ratio(floor_level(tone + bed, sr), floor_level(tone, sr))
+    assert a_step < 0.25, a_step        # broadband says fine
+    assert f_step > 0.50, f_step        # floor catches it
+    assert verdict(a_step, BROADBAND_OK, BROADBAND_BAD) == "ok"
+    assert verdict(f_step, FLOOR_OK, FLOOR_BAD) == "STEP"
+
+    # a 6 dB gain jump must register broadband
+    assert step_ratio(rms(tone), rms(tone * 2)) > 0.3
+    assert abs(db_delta(rms(tone), rms(tone * 2)) - 6.02) < 0.05
+    assert db_delta(0.1, 0.0) == -99.0 and db_delta(0.0, 0.1) == 99.0
+    assert db_delta(0.0, 0.0) == 0.0
+
+    print("level_step self-test passed")
+
+
+if __name__ == "__main__":
+    if "--self-test" in sys.argv:
+        _self_test()
+    else:
+        main()

custom_nodes/ComfyUI-H3-Motion-Context-main/tests/seam_probe.py

@@ -0,0 +1,262 @@
+"""Seam probe: is clip B's regenerated head audio a drifting copy of clip
+A's tail, or unrelated noise?
+
+Usage:
+    python seam_probe.py clip_A.flac clip_B_UNTRIMMED.flac [--frames 22] [--fps 24]
+
+clip_B_UNTRIMMED must be B's audio BEFORE the trim node -- branch the audio
+VAE decode output to a Save Audio node in parallel with the trim. clip_A is
+the previous clip as delivered (tail-matched is fine; match_tail only
+removes ~8ms and the probe aligns on content, not file length).
+
+The pinned video covers B's frames 0..N-1, which the model generates as a
+reconstruction of A's last N frames. This script slides short windows of
+B's head over the corresponding region of A's tail and reports, per window:
+
+    t_B      window position in B (seconds from B's start)
+    lag_ms   how far B runs behind A (positive = B is LATE: its copy of
+             the bassline arrives after A's original did). Tracked with
+             period-ambiguity handling, so a repeating bassline does not
+             fake a drift by cycle-hopping.
+    corr     normalised cross-correlation peak (1.0 = identical shape,
+             ~0 = unrelated)
+
+Reading the result:
+    corr high (>0.6) and lag ~0 throughout        clean continuation; the
+                                                  blip is something else
+    corr high, lag grows/shifts toward the seam   PHASE DRIFT -- crossfade
+                                                  at the join is the fix,
+                                                  shorter video window
+                                                  should shrink it
+    corr low from the start                       the ref path is not
+                                                  continuing A's audio at
+                                                  all; windowing will never
+                                                  fix it (idea 4 territory)
+
+One limitation to know before trusting a lag. Cross-correlation cannot
+tell a true alignment from one a whole cycle away, so on strongly
+periodic content a lag larger than half a period reads as the nearest
+alias: 60 ms on material with an 18 ms period comes back as -12.7 ms, at
+high correlation. Beat-driven music is exactly this case. Tracking keeps
+a drift from cycle-hopping mid-span, and the first window takes the
+global peak so a uniform whole-step offset is visible at all, but a large
+uniform offset on periodic content is not something the method resolves.
+Read a small lag as reliable and a large one as "at least this much,
+possibly plus a whole number of cycles".
+
+The node does the same measurement without the file round trip, and
+without having to infer where the seam is: H3 Motion Context Seam Probe,
+wired between the audio VAE decode and the trim node.
+
+Dependencies: numpy, plus ONE of torchaudio / soundfile / stdlib wave
+(16/32-bit PCM wav). ComfyUI's embedded python has numpy and torchaudio.
+Run it with that interpreter if your system python lacks them, e.g.:
+    python_embeded\\python.exe seam_probe.py A.flac B_untrimmed.flac
+"""
+
+import argparse
+import sys
+
+import numpy as np
+
+
+def load_audio(path):
+    """Return (mono float64 array, sample_rate)."""
+    try:
+        import torchaudio
+        wav, sr = torchaudio.load(path)
+        return wav.mean(dim=0).numpy().astype(np.float64), int(sr)
+    except Exception:
+        pass
+    try:
+        import soundfile as sf
+        data, sr = sf.read(path, always_2d=True)
+        return data.mean(axis=1).astype(np.float64), int(sr)
+    except Exception:
+        pass
+    import wave
+    with wave.open(path, "rb") as w:
+        sr = w.getframerate()
+        n = w.getnframes()
+        width = w.getsampwidth()
+        ch = w.getnchannels()
+        raw = w.readframes(n)
+    dtype = {1: np.uint8, 2: np.int16, 4: np.int32}.get(width)
+    if dtype is None:
+        raise RuntimeError("unsupported wav sample width %d" % width)
+    data = np.frombuffer(raw, dtype=dtype).astype(np.float64)
+    if width == 1:
+        data -= 128.0
+    data = data.reshape(-1, ch).mean(axis=1)
+    return data, sr
+
+
+def norm_xcorr(win, ref):
+    """Slide `win` across `ref`; return (offsets, ncc) where offsets index
+    positions of the window's start within ref."""
+    win = win - win.mean()
+    ref = ref - ref.mean()
+    wn = np.sqrt((win ** 2).sum())
+    if wn < 1e-12:
+        return None, None
+    corr = np.correlate(ref, win, mode="valid")
+    csum = np.concatenate(([0.0], np.cumsum(ref ** 2)))
+    seg = csum[len(win):] - csum[:-len(win)]
+    denom = wn * np.sqrt(np.maximum(seg, 1e-12))
+    return np.arange(len(corr)), corr / denom
+
+
+def tracked_peak(ncc, expect_idx):
+    """Pick this window's alignment with period-ambiguity handling.
+
+    Music is periodic -- a 100 Hz bassline repeats every 10 ms -- so the
+    global NCC argmax can hop a whole cycle between windows and fake a
+    drift. Instead: take every local maximum within 10% of the global
+    peak, and follow the one CLOSEST to the alignment predicted by the
+    previous window (starting from zero lag). Genuine drift moves far
+    less than a period per 25 ms hop, so continuity keeps the true peak
+    and discards cycle aliases.
+    """
+    best = float(ncc.max())
+    i = np.arange(1, len(ncc) - 1)
+    peaks = i[(ncc[i] >= ncc[i - 1]) & (ncc[i] >= ncc[i + 1]) &
+              (ncc[i] >= 0.9 * best)]
+    if len(peaks) == 0:
+        peaks = np.array([int(np.argmax(ncc))])
+    pick = int(peaks[np.argmin(np.abs(peaks - expect_idx))])
+    return pick, float(ncc[pick])
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("clip_a")
+    ap.add_argument("clip_b_untrimmed")
+    ap.add_argument("--frames", type=int, default=22,
+                    help="pinned video frames (the span the model regenerates)")
+    ap.add_argument("--fps", type=float, default=24.0)
+    ap.add_argument("--win-ms", type=float, default=50.0,
+                    help="analysis window length")
+    ap.add_argument("--hop-ms", type=float, default=25.0,
+                    help="hop between windows (25ms = one audio latent step)")
+    ap.add_argument("--search-ms", type=float, default=40.0,
+                    help="max lag searched either side")
+    args = ap.parse_args()
+
+    a, sr_a = load_audio(args.clip_a)
+    b, sr_b = load_audio(args.clip_b_untrimmed)
+    if sr_a != sr_b:
+        sys.exit("sample rates differ (%d vs %d); resample first" % (sr_a, sr_b))
+    sr = sr_a
+
+    span_s = args.frames / args.fps
+    span = int(round(span_s * sr))
+    if len(b) < span:
+        sys.exit("clip B shorter than the pinned span -- is this the "
+                 "UNTRIMMED audio?")
+    if len(a) < span:
+        sys.exit("clip A shorter than the pinned span")
+
+    # B[0:span] should reconstruct A[-span:]
+    a_tail_start = len(a) - span
+    win = int(round(args.win_ms / 1000.0 * sr))
+    hop = int(round(args.hop_ms / 1000.0 * sr))
+    search = int(round(args.search_ms / 1000.0 * sr))
+
+    print("clip A: %.3fs   clip B (untrimmed): %.3fs   sr %d" %
+          (len(a) / sr, len(b) / sr, sr))
+    print("pinned span: %d frames = %.4fs = %d samples" %
+          (args.frames, span_s, span))
+    print("window %.0fms, hop %.0fms, search +/-%.0fms" %
+          (args.win_ms, args.hop_ms, args.search_ms))
+    print()
+    print("%8s  %9s  %6s   region" % ("t_B (s)", "lag (ms)", "corr"))
+
+    lags, corrs = [], []
+    t = 0
+    prev_lag = None  # samples; seeded from the first window's global peak
+    # continue a little past the seam to see whether alignment against
+    # A's (now nonexistent) continuation collapses, as it should
+    while t + win <= span + int(0.2 * sr) and t + win <= len(b):
+        centre_in_a = a_tail_start + t
+        lo = max(0, centre_in_a - search)
+        hi = min(len(a), centre_in_a + win + search)
+        ref = a[lo:hi]
+        if len(ref) <= win:
+            break
+        offsets, ncc = norm_xcorr(b[t:t + win], ref)
+        if ncc is None:
+            t += hop
+            continue
+        # index in the ncc curve where lag == prev_lag; sign convention:
+        # positive lag = B is LATE (its content matches an EARLIER part
+        # of A than the nominal position), so match offset = centre - lag
+        if prev_lag is None:
+            # Nothing to track from yet, so take the global peak. Seeding
+            # at zero instead assumes the first window is already
+            # aligned, and when the whole join is offset by a step that
+            # assumption makes the tracker pick the nearest cycle alias:
+            # a uniform 25 ms lag on 55 Hz-fundamental content reads as
+            # 6.8 ms. That is the failure this probe exists to find, so
+            # it must not be the one case it cannot see.
+            pick = int(np.argmax(ncc))
+            corr = float(ncc[pick])
+        else:
+            expect_idx = (centre_in_a - prev_lag) - lo
+            pick, corr = tracked_peak(ncc, expect_idx)
+        lag = centre_in_a - (lo + pick)
+        in_span = t + win <= span
+        tag = "reconstruction" if in_span else "past seam"
+        print("%8.3f  %9.2f  %6.3f   %s" %
+              (t / sr, lag / sr * 1000.0, corr, tag))
+        if in_span:
+            lags.append(lag / sr * 1000.0)
+            corrs.append(corr)
+            if corr > 0.6:
+                prev_lag = lag  # only track when the match is credible
+        t += hop
+
+    print()
+    if not corrs:
+        sys.exit("no windows analysed")
+    corrs = np.array(corrs)
+    lags = np.array(lags)
+    strong = corrs > 0.6
+    at_edge = np.abs(lags) >= (args.search_ms - 1.0)
+    print("summary over the reconstruction span:")
+    print("  mean corr %.3f   windows with corr>0.6: %d/%d   "
+          "lags pinned at search edge: %d" %
+          (corrs.mean(), int(strong.sum()), len(corrs), int(at_edge.sum())))
+    usable = strong & ~at_edge
+    if usable.sum() >= 5 and corrs.mean() > 0.55:
+        # fit lag = a*t + b over the credible windows; drift is a coherent
+        # trend, so demand small residuals before calling it that
+        idx = np.nonzero(usable)[0].astype(np.float64)
+        sl = lags[usable]
+        a_fit, b_fit = np.polyfit(idx, sl, 1)
+        resid = sl - (a_fit * idx + b_fit)
+        rms = float(np.sqrt((resid ** 2).mean()))
+        total = a_fit * (len(corrs) - 1)
+        print("  lag trend: %.2fms across the span, residual rms %.2fms" %
+              (total, rms))
+        if rms < 2.0 and corrs.mean() > 0.75 and abs(total) > 2.0:
+            print("  -> DRIFT: B tracks A with a coherent %.1fms slide. A "
+                  "~40ms crossfade at the join should mask it; a shorter "
+                  "video window should shrink it." % total)
+        elif rms < 2.0 and corrs.mean() > 0.75:
+            print("  -> B tracks A with stable phase. The blip is not "
+                  "accumulated drift; look at the first generated steps "
+                  "past the seam instead.")
+        else:
+            print("  -> PARTIAL RESEMBLANCE: B resembles A's tail but does "
+                  "not phase-lock to it (mean corr %.2f, lag rms %.1fms). "
+                  "Imitation, not continuation -- idea 4 territory."
+                  % (corrs.mean(), rms))
+    else:
+        print("  -> LOW/INCOHERENT CORRELATION: the regenerated head does "
+              "not phase-track A's tail. The ref path is imitating, not "
+              "continuing; no window length will fix the seam. Idea 4 "
+              "(audio on the keyframe path) is the direction.")
+
+
+if __name__ == "__main__":
+    main()

custom_nodes/ComfyUI-H3-Motion-Context-main/web/h3_motion_context.js

@@ -0,0 +1,389 @@
+import { app } from "../../scripts/app.js";
+import { api } from "../../scripts/api.js";
+
+const LOAD = "MiniMaxH3MotionContextLoadLatent";
+const SAVE = "MiniMaxH3MotionContextSaveLatent";
+const CHAIN = "MiniMaxH3MotionContextChain";
+const MAX = 9999;
+
+const CSS = `
+.h3mc-chain{display:flex;flex-direction:column;gap:6px;color:#ddd;font:12px/1.3 sans-serif;width:100%;box-sizing:border-box;padding:2px 0 4px;}
+.h3mc-chain-row{display:flex;gap:6px;}
+.h3mc-chain-row button{flex:1;cursor:pointer;border:1px solid #555;background:#2a2a2a;color:#ddd;border-radius:4px;padding:6px 4px;font:12px sans-serif;}
+.h3mc-chain-row button:hover{background:#3a3a3a;}
+.h3mc-chain-row button:disabled{opacity:.45;cursor:default;}
+.h3mc-chain-row button.on{border-color:#6f8bbd;background:#1f2a3a;color:#c5d4ee;}
+.h3mc-chain-meta{opacity:.75;font-size:11px;min-height:14px;}
+`;
+
+let cssOnce = false;
+function injectCss() {
+  if (cssOnce) return;
+  cssOnce = true;
+  const s = document.createElement("style");
+  s.textContent = CSS;
+  document.head.appendChild(s);
+}
+
+function swallow(el) {
+  for (const type of ["pointerdown", "mousedown", "pointerup", "mouseup",
+                      "click", "dblclick", "contextmenu"]) {
+    el.addEventListener(type, (e) => e.stopPropagation());
+  }
+}
+
+function graphNodes(graph) {
+  return graph?._nodes || graph?.nodes || [];
+}
+
+function groupList(graph) {
+  return graph?._groups || graph?.groups || [];
+}
+
+function groupMembers(group) {
+  if (typeof group.recomputeInsideNodes === "function") {
+    try { group.recomputeInsideNodes(); } catch (e) { /* older litegraph */ }
+  }
+  if (Array.isArray(group._nodes) && group._nodes.length) return group._nodes;
+  if (Array.isArray(group.nodes) && group.nodes.length) return group.nodes;
+  const kids = group._children || group.children;
+  if (kids) return Array.from(kids);
+  return [];
+}
+
+function inGroup(group, node) {
+  const members = groupMembers(group);
+  if (members.includes(node) || members.some((n) => n.id === node.id)) return true;
+  const b = group._bounding || group.bounding;
+  if (!b || b.length < 4 || !node.pos) return false;
+  const x = node.pos[0] + (node.size?.[0] || 0) / 2;
+  const y = node.pos[1] + (node.size?.[1] || 0) / 2;
+  return x >= b[0] && x <= b[0] + b[2] && y >= b[1] && y <= b[1] + b[3];
+}
+
+function findPair(ctrl) {
+  const graph = ctrl.graph || app.graph;
+  const nodes = graphNodes(graph);
+  const loads = nodes.filter((n) => n.comfyClass === LOAD);
+  const saves = nodes.filter((n) => n.comfyClass === SAVE);
+  for (const g of groupList(graph)) {
+    if (!inGroup(g, ctrl)) continue;
+    const members = groupMembers(g);
+    const pool = members.length ? members : nodes.filter((n) => inGroup(g, n));
+    const load = pool.find((n) => n.comfyClass === LOAD);
+    const save = pool.find((n) => n.comfyClass === SAVE);
+    if (load && save) return { load, save };
+  }
+  if (loads.length === 1 && saves.length === 1) return { load: loads[0], save: saves[0] };
+  return null;
+}
+
+function clipWidget(node) {
+  return node?.widgets?.find((w) => w.name === "clip_index");
+}
+
+function readClip(node) {
+  return (clipWidget(node)?.value | 0) || 0;
+}
+
+function widgetValue(node, name) {
+  return node?.widgets?.find((w) => w.name === name)?.value;
+}
+
+function loadPath(pair) {
+  const p = widgetValue(pair.load, "latent_path");
+  return (p == null || p === "") ? "h3_context" : p;
+}
+
+async function firstClipExists(pair) {
+  try {
+    const r = await api.fetchApi("/h3_motion_context/slot_exists", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ latent_path: loadPath(pair), clip_index: 1 }),
+    });
+    if (!r.ok) return false;
+    const j = await r.json();
+    return !!j.exists;
+  } catch (e) {
+    return false;
+  }
+}
+
+async function clearLatents(pair) {
+  try {
+    const r = await api.fetchApi("/h3_motion_context/clear_latents", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ latent_path: loadPath(pair) }),
+    });
+    if (!r.ok) return 0;
+    const j = await r.json();
+    return j.removed | 0;
+  } catch (e) {
+    return 0;
+  }
+}
+
+function writeClip(node, value) {
+  const w = clipWidget(node);
+  if (!w) return false;
+  const next = Math.max(0, Math.min(MAX, value | 0));
+  w.value = next;
+  return true;
+}
+
+function coerceSegments(node) {
+  const w = node?.widgets?.find((x) => x.name === "segments");
+  if (!w) return 0;
+  const n = parseInt(w.value, 10);
+  const v = Number.isFinite(n) && n >= 0 ? n : 0;
+  w.value = v;
+  return v;
+}
+
+function wireSegments(node) {
+  const w = node?.widgets?.find((x) => x.name === "segments");
+  if (!w || w._h3mcSeg) return;
+  w._h3mcSeg = true;
+  const prev = w.serializeValue?.bind(w);
+  w.serializeValue = async function (n, i) {
+    if (prev) {
+      try { await prev(n, i); } catch (e) { /* keep coercing */ }
+    }
+    return coerceSegments(node);
+  };
+  const prevCb = w.callback;
+  w.callback = function () {
+    coerceSegments(node);
+    return prevCb?.apply(this, arguments);
+  };
+  coerceSegments(node);
+}
+
+function readSegments(ctrl) {
+  return coerceSegments(ctrl);
+}
+
+function paint(ctrl) {
+  const meta = ctrl._h3mc?.meta;
+  if (!meta) return;
+  const pair = findPair(ctrl);
+  if (!pair) {
+    meta.textContent = "Load, Save, and Chain must share one canvas group.";
+    return;
+  }
+  const a = readClip(pair.load);
+  const b = readClip(pair.save);
+  const left = ctrl._h3mc.remaining | 0;
+  if (ctrl._h3mc.chaining) {
+    meta.textContent = left
+      ? `Chaining  Load ${a} / Save ${b}  ·  ${left} left`
+      : `Chaining  Load ${a} / Save ${b}`;
+  } else {
+    meta.textContent = `Load ${a} / Save ${b}`;
+  }
+  const chainBtn = ctrl._h3mc.chainBtn;
+  if (chainBtn) {
+    chainBtn.textContent = ctrl._h3mc.chaining ? "Stop" : "Chain";
+    chainBtn.classList.toggle("on", !!ctrl._h3mc.chaining);
+  }
+}
+
+let live = null;
+
+function stopChain(ctrl) {
+  if (ctrl) {
+    ctrl._h3mc.chaining = false;
+    ctrl._h3mc.awaiting = false;
+    ctrl._h3mc.remaining = 0;
+    paint(ctrl);
+  }
+  if (live === ctrl) live = null;
+}
+
+function advance(ctrl) {
+  const pair = findPair(ctrl);
+  if (!pair) return false;
+  const load = readClip(pair.load) + 1;
+  let save = readClip(pair.save) + 1;
+  if (save < 1) save = 1;
+  writeClip(pair.load, Math.min(load, MAX));
+  writeClip(pair.save, Math.min(save, MAX));
+  app.graph?.setDirtyCanvas?.(true, true);
+  paint(ctrl);
+  return true;
+}
+
+function resetFirst(ctrl) {
+  const pair = findPair(ctrl);
+  if (!pair) return false;
+  writeClip(pair.load, 0);
+  writeClip(pair.save, 1);
+  app.graph?.setDirtyCanvas?.(true, true);
+  paint(ctrl);
+  return true;
+}
+
+async function startChain(ctrl) {
+  const pair = findPair(ctrl);
+  if (!pair) return false;
+  const load = readClip(pair.load);
+  const save = readClip(pair.save);
+  const atFirst = load === 0 && save <= 1;
+  if (atFirst && !(await firstClipExists(pair))) {
+    await queueOnce(ctrl);
+    return true;
+  }
+  if (!advance(ctrl)) return false;
+  await queueOnce(ctrl);
+  return true;
+}
+
+async function queueOnce(ctrl) {
+  const pair = findPair(ctrl);
+  if (!pair) return;
+  ctrl._h3mc.awaiting = true;
+  live = ctrl;
+  await app.queuePrompt(0, 1);
+}
+
+function onPromptDone(ok) {
+  const ctrl = live;
+  if (!ctrl?._h3mc?.awaiting) return;
+  ctrl._h3mc.awaiting = false;
+  if (!ok) {
+    stopChain(ctrl);
+    return;
+  }
+  if (!ctrl._h3mc.chaining) {
+    live = null;
+    paint(ctrl);
+    return;
+  }
+  const left = ctrl._h3mc.remaining | 0;
+  if (left > 0) {
+    ctrl._h3mc.remaining = left - 1;
+    if (ctrl._h3mc.remaining === 0) {
+      ctrl._h3mc.chaining = false;
+      live = null;
+      paint(ctrl);
+      return;
+    }
+  }
+  if (!advance(ctrl)) {
+    stopChain(ctrl);
+    return;
+  }
+  queueOnce(ctrl);
+}
+
+api.addEventListener("execution_success", () => onPromptDone(true));
+api.addEventListener("execution_error", () => onPromptDone(false));
+api.addEventListener("execution_interrupted", () => onPromptDone(false));
+
+app.registerExtension({
+  name: "h3_motion_context.chain",
+  async beforeRegisterNodeDef(nodeType, nodeData) {
+    if (nodeData.name !== CHAIN) return;
+    const onNodeCreated = nodeType.prototype.onNodeCreated;
+    nodeType.prototype.onNodeCreated = function () {
+      const r = onNodeCreated?.apply(this, arguments);
+      wireSegments(this);
+      injectCss();
+      const root = document.createElement("div");
+      root.className = "h3mc-chain";
+      const row = document.createElement("div");
+      row.className = "h3mc-chain-row";
+      const row2 = document.createElement("div");
+      row2.className = "h3mc-chain-row";
+      const row3 = document.createElement("div");
+      row3.className = "h3mc-chain-row";
+      const approve = document.createElement("button");
+      approve.textContent = "Approve";
+      approve.title = "Advance Load/Save, then run the next clip.";
+      const reroll = document.createElement("button");
+      reroll.textContent = "Run/Re-roll";
+      reroll.title = "Queue at the current Load/Save indices. Use this instead of ComfyUI's Run button.";
+      const chainBtn = document.createElement("button");
+      chainBtn.textContent = "Chain";
+      chainBtn.title = "Approve on a loop. segments > 0 stops after that many clips; 0 runs until Stop.";
+      const resetBtn = document.createElement("button");
+      resetBtn.textContent = "Reset";
+      resetBtn.title = "Set Load 0 / Save 1. Does not queue or delete files.";
+      const clearBtn = document.createElement("button");
+      clearBtn.textContent = "Clear latents";
+      clearBtn.title = "Delete numbered chain slots (clip_00001.safetensors and so on). Custom filenames are left alone. Does not change indices or queue.";
+      row.append(approve, reroll);
+      row2.append(chainBtn, resetBtn);
+      row3.append(clearBtn);
+      const meta = document.createElement("div");
+      meta.className = "h3mc-chain-meta";
+      root.append(row, row2, row3, meta);
+      swallow(root);
+      this.addDOMWidget("h3mc_chain", "CHAIN", root, { serialize: false });
+      this._h3mc = { chaining: false, awaiting: false, remaining: 0, meta, chainBtn };
+      approve.onclick = async (e) => {
+        e.stopPropagation();
+        if (this._h3mc.awaiting) return;
+        stopChain(this);
+        if (!advance(this)) return;
+        await queueOnce(this);
+      };
+      reroll.onclick = async (e) => {
+        e.stopPropagation();
+        if (this._h3mc.awaiting) return;
+        stopChain(this);
+        await queueOnce(this);
+      };
+      chainBtn.onclick = async (e) => {
+        e.stopPropagation();
+        if (this._h3mc.chaining) {
+          stopChain(this);
+          return;
+        }
+        if (this._h3mc.awaiting) return;
+        if (!findPair(this)) {
+          paint(this);
+          return;
+        }
+        this._h3mc.chaining = true;
+        this._h3mc.remaining = readSegments(this);
+        paint(this);
+        if (!await startChain(this)) stopChain(this);
+      };
+      resetBtn.onclick = (e) => {
+        e.stopPropagation();
+        if (this._h3mc.awaiting) return;
+        stopChain(this);
+        resetFirst(this);
+      };
+      clearBtn.onclick = async (e) => {
+        e.stopPropagation();
+        if (this._h3mc.awaiting || this._h3mc.chaining) return;
+        const pair = findPair(this);
+        if (!pair) {
+          paint(this);
+          return;
+        }
+        const n = await clearLatents(pair);
+        paint(this);
+        if (this._h3mc?.meta) {
+          this._h3mc.meta.textContent = n
+            ? `Removed ${n} numbered slot${n === 1 ? "" : "s"}. Custom names kept.`
+            : "No numbered chain slots to remove.";
+        }
+      };
+      paint(this);
+      this.setSize?.([270, 168]);
+      return r;
+    };
+    const onConfigure = nodeType.prototype.onConfigure;
+    nodeType.prototype.onConfigure = function () {
+      const r = onConfigure?.apply(this, arguments);
+      wireSegments(this);
+      coerceSegments(this);
+      return r;
+    };
+  },
+});