Release H3 Continuum V3.3.0

This commit is contained in:
ukr8b3g-cmyk
2026-08-16 20:32:47 +09:00
parent a908e4884f
commit fb22c20149
38 changed files with 3598 additions and 363 deletions
+30
View File
@@ -1,5 +1,35 @@
# Changelog
## 3.3.0
- Promoted Timeline Video to a stable public node with chunk-local slicing and a 0.4 MP default.
- Added `H3 Continuum Assemble + Seam` with stable Audio Seam Auto and guarded Video Seam Auto defaults.
- Kept `Auto 2` as an experimental exposure-ramp extension without widening the visible option label.
- Added native Reference Audio conditioning and retained up to three ordered Reference Images.
- Preserved stable sampler Node IDs, Run Storage compatibility, Core VAE decode, and Spectrum Interop API v1 Actual Prefix 2 behavior.
- Added consolidated runtime validation results and documented known Timeline Video and Auto 2 limitations.
## 3.2.4
- Added native MiniMax H3 Reference Audio 1 conditioning with deferred Audio VAE encoding.
- Matched Core's permissive prompt handling by warning instead of stopping on unavailable Picture or Audio tags.
- Matched Core's dynamic Reference behavior by compacting active image inputs into Picture 1 through Picture N.
- Kept Sampling, Continuation, Spectrum Interop, external Core VAE Decode, and assembly semantics unchanged.
## 3.2.3
- Formalized the third ordered Reference Image as a compatibility-preserving extension.
- Kept V3.2.2 zero, one, and two-image Reference Contract JSON unchanged.
- Added Image 3 shape, dtype, exact SHA-256, position, and preprocess metadata only for three-image runs.
- Added Golden Contract and Revision identity regression coverage for V3.2.2 saved runs.
- Kept Sampling, Continuation, Spectrum Interop, Core VAE Decode, and assembly semantics unchanged.
## 3.2.2
- Allowed Ref2VA, FL2VA, and unverified checkpoints with Reference conditioning.
- Kept checkpoint classification as diagnostics without automatic MODEL switching.
- Kept Strict Compatibility for genuinely unsafe or unsupported H3 contracts.
## 3.2.1
- Declared V3.2.1 stable after GitHub Actions, Windows Ref2VA generation, Spectrum Actual Prefix 2, chunk integrity and complete Auto Resume passed.
+100 -90
View File
@@ -1,99 +1,109 @@
15b900d02624bea6cfe8ea25b22266a0c68b38b9f10c9089be0e38988bf2e34d .github/workflows/tests.yml
0a2f69d4cec89d440f5d5aa1ec68a7c9a741382d313f80dcddf96d13f70b3e68 .gitignore
dca65fb1393e67f59c6f81f9411e3e745eb8f1097e9a2adf7ffc6f4e3901ca9f __init__.py
0005be4e1e56a88d5b2168dc3fe203d5f87944922aa400d87e8c840805d2a4e1 AGENTS.md
a972808d70077d202aece2dd6f1d6a2eac82ff46e58d039ec255d381c0fe315a CHANGELOG.md
7dbbc8ce1018d6ac07c53eaa40f2d8d144babf9c6fe6bd94b7ec1d08adffa215 compatibility.py
008c7df6864af948d8e51ba1063b3a450ad6f463984e719f6dd147eb9f12a054 v3/assembly.py
041289556cc621ea1857cbb8931ae41d817f69e084b2e8a7622e184a3197b61b tests/test_compatibility.py
0a2f69d4cec89d440f5d5aa1ec68a7c9a741382d313f80dcddf96d13f70b3e68 .gitignore
0a520b34b12e1d2556d50480c43318de7eab4221afb96ef4760127c8bc90c890 tests/test_v2_seam.py
0b5b20a8318862d167f135720e0489b8d4f93406d67c6646e052e35b03dcb876 tests/test_v2_session.py
0dbe8a5f71c92f3523942343b40787104c8b96781461ba3ba82934a6bdbe5834 THIRD_PARTY_NOTICES.md
0e59ea821081cb93165aa3f88c6949736dd225837fe1cdcf1173aa5cd54c6d29 examples/v2_prompt_timeline_example.txt
10fb950fba44f7dcbdc25d3e2b9b62bc63c217876c0eaaaf60bb0f707c47ee5d PACKAGE_INFO_JA.txt
11877692d4aadea79ff35d4d5035457c26ac2ace7443889ed3fd7ee51e99a103 continuation.py
12cfcc0c71ca087fe39a5ce2922959a62b2bb311bfe664f05c4480affce03708 v2/seeds.py
13213e7709fd02bb810af3c18e4cd7d010f8cdfb121a4b99866a9f2333331089 v2/session_io.py
1326183b1eb681381bb22704740a6cc8636c7c5606e1d6b0a38c5115c2e27275 nodes.py
15b900d02624bea6cfe8ea25b22266a0c68b38b9f10c9089be0e38988bf2e34d .github/workflows/tests.yml
1ae0369943ba2fb13f21ad0cf56ee58621ba09bf20174379595e157a1775c7fd tests/test_public_api.py
1b8b0069bc9792bffe73c48bc8cb7c59d961bac2e624acac4759a21320998dfb v2/sequence.py
1fa97d86da61149116dec41e836dda8cab32e341fe79414bddde6c0be36cd1cf tests/test_v31_run_storage.py
20b8132fb231c5b8ce61da2c1fbad310c22f332d66926a706523009deed54f65 v2/h3_builder.py
20f4e7c4ad085791f8b578f575d03e52ef09d0d4550aa58ad086c9857b59bf29 examples/H3_Continuum_V2.json
23bddc5a41d2e997f4fbf789c7128e32f4f197f1405b2aef1c76794f57482446 install_windows.bat
2c13aefd137db92a3dbf5576e9442d58012b1f0de1240c07d039ceeb702e7c1f docs/V2_1_4_UI_SIMPLIFICATION.md
2fb3dfee32c829e216198001621c55d146b848251d7b22f8c99e70b1737426f4 web/project_id.js
2fd811794c4cc0f2ce050250b80484876454926b9f20fce6af3a97d728e5acdf v2/seam_guard.py
31012ec48a64c7467ad869c79982b7f8502c1785c33f51ee1b5727ce8b4243fb v2/diagnostics.py
3919f01977599591f534f797d90424520d12fa5dce84486d5700d5dd3daafb30 PACKAGE_VALIDATION.txt
3a359a0467725cc292ccb4c86cf0c3d30bb6a114d01f5345792b09ea3d45441d state.py
3d57276669e4ce95f8537c67c6437250b52dd843ee0817c2e262018ead200107 hardening.py
3df21245f5fd1e124755343f294453dfa945942cd73b0c49478dc26b7d5ccde2 tests/test_v32_reference.py
3eeed61b7ee519631825e5f89e9a441644c66e552fce4207927cb8536867c8b1 tests/conftest.py
3fec541a675c1e4e5e287cc8e498036001f34f7a62460321e16f9ba27b5e4c18 docs/VALIDATION_RESULTS.md
4080f1875b958b316e8e76852c4be5527a6de5c71d604e7642d3098478eb4a36 v2/sampling.py
43ec4023dc06c941e5d7a04db4b8a89fb58d744ceb986f6eb9bf534d4fdcb87b temporal.py
43f810e5c1dec3350b695ae764bab6ecde13e660d1aab269bb2a3c602f58c247 tests/test_v2_prompts.py
45e8839cd82fd955df344b3bc6efa20092b8870ea378b0c898b073665d3e47d7 tests/test_nodes_logic.py
467edb2c188d024c2392aafe7423b3f835e16b10f570da76e2f7dda8a962c1c5 requirements.txt
4966a5ad0d418e85cb2bbf22d322915dd1fc4bc6848effce0977cbd83482a35e model_patch.py
4b94f779a98bfc555f6999113a694da07746cc3cf400bfc70ebc580592034d52 examples/H3_Continuum_V2_reference.webp
52b69d4f7858f9adc1030a5d3102ab9b0384283bf9df05953c0e5552d1e3336c v2/prompts.py
535316a53a656916acc8ad5c6e69b4569227feaef6a351f50febf8111454ac4c README_JA.md
58438c3ed814adf40cefde098a37cae00ddcb703b7e5548bbbb295e54bed5a6d tests/test_v2_widget_migration.py
58c06925ccf06c4feee19b927b3515c540c0536aa5f3f8d29be35b8e919915a7 tests/test_temporal.py
5a26408c770381cdb259cb710de7dab12d7ddecca262bdbf35ba1566056050f5 examples/recommended_settings_v2.json
5d89c366b4f076fa73a2695557e0af749bf95df1dad0d55dbb2fe5b1c2519ad7 reference_audio.py
5dfdd4b108ba7444c0f5f371c3b1e244b5735d23136127b9818fd60738c78b68 tests/test_v2_registration.py
6056de6c0a5322a8a51ba5a114538dca2ef67788cd1afba10fedd483b95f6afa state_io.py
659df97c35a6f473360d6312da6f275d4d4cb7e068fc83fd42c7d26301442016 pyproject.toml
66bd67c9ec7d8a7f32c7d1c1fc4ce1c19b42fda5d7cece67b171c3cffc49f0a8 v3/plan.py
6771c9905d35666121c4892d2ec26202505f96d244ce814ad9a87a02878952cd examples/H3_CONTINUUM_V1_WIRING.md
686fe4b4c228abbafc7cee37c8e8db198f5afdddfd9ba0a80184c87ab4ee0287 tests/test_v217_stable_facade.py
68e1a724d3b99458b86b8f643dcb916183e7e8dd12d7b4b3850991feb8077694 examples/recommended_settings_v1.json
6993e2f7eebe276f2a18824a193b5c615833e4aabf8ee83336035d1a2e089098 v3/seam_test_source.py
6abdbc29472c7f9d447085b189fc47b69e110b94ef83192f9689d04000408843 INSTALL_JA.txt
6b43294ebf00fde03acc3f2ac52f841f3c4323085c21643aa075a347cf4a432c layout_adapter.py
6c72d9a9e35648355c4dd4c8f060a6b7667e322f4b6c86690df9d6769ba182b7 docs/images/h3-continuum-advanced.png
707884ea5ec950165044713ba70f54ce721470cab86821fead5259120ecbe66a conditioning.py
71e3df269e226b1ecad597f9831c2a10b2215c8a3783652e9e9f536e99ce46c9 constants.py
11877692d4aadea79ff35d4d5035457c26ac2ace7443889ed3fd7ee51e99a103 continuation.py
fcc80c5630103986b26a3f8cc07cf52ffb92fd6e72158962b1a61c01bf7adc93 docs/AB_TEST_LOG_JA.md
c93a3e52e4deabe5ef0db7f34a7605856a543089574ba17227e697e9a2c0139a docs/ARCHITECTURE.md
7660570840229b6fcbe62f0fbb52966d0099d64d7e6f01a739fbf9899293c8e4 docs/FUTURE_ROADMAP.md
6c72d9a9e35648355c4dd4c8f060a6b7667e322f4b6c86690df9d6769ba182b7 docs/images/h3-continuum-advanced.png
b9f1dca35706a1cd963ba892d218568ea30173c6cf6a3bdc896f7a2266eb9407 docs/images/h3-continuum-detailed-report.png
de5f8fbce6bc423817acf7dc86bb0c8805a1fd962afdb2722cde7395f117eb56 docs/images/h3-continuum-image-scale.png
a384e26f3b088607c616be1a2b038365147d92da0961d8f47060fed09f795062 docs/images/h3-continuum-sampler.png
74e623120a963cb96b68651b44f47a836ea8449d30ce89d749c71ffad4766d4e tests/test_v2_seeds_motion.py
759d18e15e0cf139630259db38123a824be565ec844a3d7ac020b74ff8537b25 docs/images/v31b-auto-resume.png
2c13aefd137db92a3dbf5576e9442d58012b1f0de1240c07d039ceeb702e7c1f docs/V2_1_4_UI_SIMPLIFICATION.md
b08022df068576c759c8bf80ac6b6519693f3c65c917f1822aeb06ea359aa5b1 docs/V2_1_5_UI_SERIALIZATION_STABILITY.md
7660570840229b6fcbe62f0fbb52966d0099d64d7e6f01a739fbf9899293c8e4 docs/FUTURE_ROADMAP.md
78bc478a5e4edda902c80849c911782a99e75c06dfb04127391b6cc5b27b28e1 tests/test_v3_hardening.py
78c830cdf49034c6e3b2cd3da5914d5cfc5638eb63ec6dbd1bab13c50d6d4caf v3/__init__.py
7a1138fa8619247787039ddeb2f3692ba1f680b4553a13e472fadfbea1c88d07 tests/test_conditioning_modes.py
7aa30ffdb1ed818c0ffcc0caa05bd9320466c6c39a5f3008f70f30d180084981 CHANGELOG.md
7dbbc8ce1018d6ac07c53eaa40f2d8d144babf9c6fe6bd94b7ec1d08adffa215 compatibility.py
83a650322dcf02e0b2d83888ec858d9c6ad558096559c7b76982d81157b11f06 run_storage.py
892f319f0688a6f4fcac2e3a809601e63febd08065a34ff1a9f5f7521cef5dae v3/video_seam.py
912661d91c7f11f5fcaf0bd14d7d3ecf5c74c33b1507272f0ae72af6e5bffa6f tests/test_v2_decoder.py
93f07aa727b34802bce3d333426b8ba2af522500882a6d222d00cf577ca82e49 docs/SEAM_TEST_SOURCE_JA.md
94fdc2d545b2d4077a4d70229fd22ba3ccac21d49d1097d2873f76d04e9a3c7a pytest.ini
98a33c75b33ff0c10a68e04bd856e4e43b3e70b6ae1ea458a2b21b4e4d74f46d tests/test_state.py
a032738b0bc5acb136e92d8bf7694643a5f518b9c7fc0fc878d66d81ba8b1b04 docs/V2_1_6_UNIFIED_UI.md
a384e26f3b088607c616be1a2b038365147d92da0961d8f47060fed09f795062 docs/images/h3-continuum-sampler.png
aea01a48a8c03a25ed97ea05e5b137f89e388832d1be7d38f2da2be3d1b9830b v2/motion.py
aeffa4fe7b598a31741dbe2a57c9bc5ce3904cced5ad8084cad2ca12947f74e1 v3/nodes.py
af38813b6b4c7f091269c56f0ccace7c1f47f7794059bfe3e703058e58c60eaf tests/test_timeline_video.py
b08022df068576c759c8bf80ac6b6519693f3c65c917f1822aeb06ea359aa5b1 docs/V2_1_5_UI_SERIALIZATION_STABILITY.md
b42bcc0983147462d96c6b71cc4a38e846995dafa6eebefc3ae0d9bb36caf359 tests/test_v2_sequence_orchestration.py
b470819f16fc179654dc1600721a63f0a5a14e777f4c004d574b499da6886ba5 public_api.py
b708599c0f6ffba4556e77536558a415104b0d4c1d043f335197bfb6960f07df v2/session.py
b8275c8cecde12aee0418cea456d1e7f4b875cbb1bce32f1f3d9e06a44dd0be1 examples/v2_prompt_list_example.txt
b9f1dca35706a1cd963ba892d218568ea30173c6cf6a3bdc896f7a2266eb9407 docs/images/h3-continuum-detailed-report.png
bdb5e2f0557b6ea27819356e671b9be08ea6e7cedc6d5dad05f82c032ea0fb79 tests/test_v3_seam_test_source.py
be0d8585fa57e0ccd6d02577bbc7299629e5bfe20e186747f571fccc98b67d7e v2/seam_types.py
be419d6c773784823af7b58a3423ef2e21d3cc3e23c40e60e274560895ca034b examples/H3_Continuum_V2_README.txt
c3cefcdf50df9d6609f583a008453b587c011a0fb41e290d5f1196ce62f58877 examples/H3_CONTINUUM_V2_WIRING_JA.md
c44abbd789091bbead01250dbd5453e60539d2665c69f162335fdbd2936019c2 LICENSE
c93a3e52e4deabe5ef0db7f34a7605856a543089574ba17227e697e9a2c0139a docs/ARCHITECTURE.md
cde27db19b677e318cc4dfb4235be7a11429c19945f4083052a91fe117e74c82 v2/decoder.py
d3e213005670e94dee33a240349a4d245cf9a3b6602099f11ed30cf5a32e2c21 media.py
d4c53d2c260b635d70fa211029d608f63776e0a56c20253475fa47c58363f8a7 tests/test_state_io.py
d74073e7ee292ebeba913af4288284f9f197cd91fceed6c62bf6c66b784c7cec install_windows.ps1
dca65fb1393e67f59c6f81f9411e3e745eb8f1097e9a2adf7ffc6f4e3901ca9f __init__.py
ddd2df829bc72deeef5029db2ecd46ff8843556100646312e1fce42025af29f9 tests/test_v3_video_seam.py
de5f8fbce6bc423817acf7dc86bb0c8805a1fd962afdb2722cde7395f117eb56 docs/images/h3-continuum-image-scale.png
dfc20369ab87b7e2a598078f4adc0d3f95c0f3cecfadd817b100c62ae8ebe781 version.py
e480c599daf0ede07bba8b90efbae627461c1797a5ebacf228630fd74ebc48d4 tests/test_model_patch.py
e5f758180df3eaeff58fc1826fab4e889835d30015cf9879c5e6a20271b6649b tools/verify_runtime.py
e6bf5d90513982f093d7c41540fcad55926b17834fa12d39f9bec7d21d2b6044 README.md
e6fecb17e373333b315f0ce89e8dda3bda9dfdd34dac2656ae8785d26256c422 tests/test_layout_adapter.py
e7905ea8ce7b3bcfc699c232c35a23131ad4b983fbe2d9e233b562ba032e5ac1 reference.py
e9d20ba270238aec135b09887c12c4cd10eb529a4db384918440838bbbf0e0d9 graph_contract.py
ebef201b63a417ad6706a4f4e36f4a911ef6975452554f6404be99c6a5132497 metadata.ini
f0806bb2b999794ddda072e98424dbd1b613df1cd8a096b12d979f124e066d8a docs/VALIDATION_JA.md
6771c9905d35666121c4892d2ec26202505f96d244ce814ad9a87a02878952cd examples/H3_CONTINUUM_V1_WIRING.md
20f4e7c4ad085791f8b578f575d03e52ef09d0d4550aa58ad086c9857b59bf29 examples/H3_Continuum_V2.json
f218e1a93c42467c6057c5c1d04d57cc82f6331b97ec9257e4e2dfb9c831876a timeline_video.py
f67febfdd7b2bfca2ad4e477c87a9a74dbe636231f9db3e1158b944d7b9f8397 examples/H3_Continuum_V2.zip
f85ba3c69a473f0ac4bb96895c6d6532e8270121da65f858e364b19d31f05ef5 examples/H3_Continuum_V2_3x5s.json
be419d6c773784823af7b58a3423ef2e21d3cc3e23c40e60e274560895ca034b examples/H3_Continuum_V2_README.txt
4b94f779a98bfc555f6999113a694da07746cc3cf400bfc70ebc580592034d52 examples/H3_Continuum_V2_reference.webp
c3cefcdf50df9d6609f583a008453b587c011a0fb41e290d5f1196ce62f58877 examples/H3_CONTINUUM_V2_WIRING_JA.md
68e1a724d3b99458b86b8f643dcb916183e7e8dd12d7b4b3850991feb8077694 examples/recommended_settings_v1.json
5a26408c770381cdb259cb710de7dab12d7ddecca262bdbf35ba1566056050f5 examples/recommended_settings_v2.json
b8275c8cecde12aee0418cea456d1e7f4b875cbb1bce32f1f3d9e06a44dd0be1 examples/v2_prompt_list_example.txt
0e59ea821081cb93165aa3f88c6949736dd225837fe1cdcf1173aa5cd54c6d29 examples/v2_prompt_timeline_example.txt
c88e4d4c86c4e9af392c959365fee24d7593e92f69df9acf7e36117536a5f335 graph_contract.py
3d57276669e4ce95f8537c67c6437250b52dd843ee0817c2e262018ead200107 hardening.py
6abdbc29472c7f9d447085b189fc47b69e110b94ef83192f9689d04000408843 INSTALL_JA.txt
23bddc5a41d2e997f4fbf789c7128e32f4f197f1405b2aef1c76794f57482446 install_windows.bat
d74073e7ee292ebeba913af4288284f9f197cd91fceed6c62bf6c66b784c7cec install_windows.ps1
6b43294ebf00fde03acc3f2ac52f841f3c4323085c21643aa075a347cf4a432c layout_adapter.py
15fd1cdc62ffa959b49fd5088bdb1d4b5fa406fa8e420de64603e86458a1a3b8 LICENSE
d3e213005670e94dee33a240349a4d245cf9a3b6602099f11ed30cf5a32e2c21 media.py
0220d75e8fc144cfac246793fdcd7f4a99008141b17042dacdfdd8b3a593f6fa metadata.ini
49424eff88b42967e3fc0b80876ecaf5b90626d38dc740c6124f9cb8bd1d1689 model_patch.py
dcaf662210b2329ccb4478dad2430d66eae2033b8925afb312e07e6150d394e0 nodes.py
f1d6ddd86332845273cc8d29ea9f9b6b6595aa59cc3fa8df4d6f51888b6058ab PACKAGE_INFO_JA.txt
ca16f3c525c4aa67f56024e974a86401c5aada9dd43a9ac89f21bc982103c57e PACKAGE_VALIDATION.txt
b470819f16fc179654dc1600721a63f0a5a14e777f4c004d574b499da6886ba5 public_api.py
e188830c44e79e21291b7906111c605ce1b8869b748fceb6fc52a64cb7b1de24 pyproject.toml
94fdc2d545b2d4077a4d70229fd22ba3ccac21d49d1097d2873f76d04e9a3c7a pytest.ini
c24308595d82e5547996b8e832b747c2032369df38955302c58e2fba8ac7dee0 README.md
d406a9ce3446fae4f30810e8fea09d5b70c3bd027afbeecd67f007e8863998be README_JA.md
49ecdd355bcda1c8ae12b4144af531e4685a07150dbc188995970151d030e55a reference.py
467edb2c188d024c2392aafe7423b3f835e16b10f570da76e2f7dda8a962c1c5 requirements.txt
3ca3efdb3b370fa95bdad2aef35b9d34b256c66a579849bd35f6e4f5999b3089 run_storage.py
3a359a0467725cc292ccb4c86cf0c3d30bb6a114d01f5345792b09ea3d45441d state.py
6056de6c0a5322a8a51ba5a114538dca2ef67788cd1afba10fedd483b95f6afa state_io.py
43ec4023dc06c941e5d7a04db4b8a89fb58d744ceb986f6eb9bf534d4fdcb87b temporal.py
3eeed61b7ee519631825e5f89e9a441644c66e552fce4207927cb8536867c8b1 tests/conftest.py
041289556cc621ea1857cbb8931ae41d817f69e084b2e8a7622e184a3197b61b tests/test_compatibility.py
7a1138fa8619247787039ddeb2f3692ba1f680b4553a13e472fadfbea1c88d07 tests/test_conditioning_modes.py
e6fecb17e373333b315f0ce89e8dda3bda9dfdd34dac2656ae8785d26256c422 tests/test_layout_adapter.py
e0d5d75bbdfafd5f31fe773b92dc65d57451edb8e222d1a9871a92713b395f0f tests/test_model_patch.py
45e8839cd82fd955df344b3bc6efa20092b8870ea378b0c898b073665d3e47d7 tests/test_nodes_logic.py
1ae0369943ba2fb13f21ad0cf56ee58621ba09bf20174379595e157a1775c7fd tests/test_public_api.py
98a33c75b33ff0c10a68e04bd856e4e43b3e70b6ae1ea458a2b21b4e4d74f46d tests/test_state.py
d4c53d2c260b635d70fa211029d608f63776e0a56c20253475fa47c58363f8a7 tests/test_state_io.py
58c06925ccf06c4feee19b927b3515c540c0536aa5f3f8d29be35b8e919915a7 tests/test_temporal.py
912661d91c7f11f5fcaf0bd14d7d3ecf5c74c33b1507272f0ae72af6e5bffa6f tests/test_v2_decoder.py
bbbd655731cc69414aed8bef59e236e17ed4cd891a40114e490a4804f2f96fff tests/test_v2_prompts.py
5dfdd4b108ba7444c0f5f371c3b1e244b5735d23136127b9818fd60738c78b68 tests/test_v2_registration.py
0a520b34b12e1d2556d50480c43318de7eab4221afb96ef4760127c8bc90c890 tests/test_v2_seam.py
74e623120a963cb96b68651b44f47a836ea8449d30ce89d749c71ffad4766d4e tests/test_v2_seeds_motion.py
91a45db5cdcf9b96e34e264ffd23b20ed6c10c57dc8d401d130bd0c231371219 tests/test_v2_sequence_orchestration.py
0b5b20a8318862d167f135720e0489b8d4f93406d67c6646e052e35b03dcb876 tests/test_v2_session.py
58438c3ed814adf40cefde098a37cae00ddcb703b7e5548bbbb295e54bed5a6d tests/test_v2_widget_migration.py
4628d862851fb5d0f849da9262be961102ab83545f00fa435dd2495bcb4709e6 tests/test_v217_stable_facade.py
78bc478a5e4edda902c80849c911782a99e75c06dfb04127391b6cc5b27b28e1 tests/test_v3_hardening.py
abc80b8727901eaa2d8dee2284ac07cd7ea3d1eb7aad3df1b67ce4fddd4371dd tests/test_v31_run_storage.py
1a5c9e81abebd71fb6004153710c7a8ed459a9da763b9027de4562d2da25a488 tests/test_v32_reference.py
0dbe8a5f71c92f3523942343b40787104c8b96781461ba3ba82934a6bdbe5834 THIRD_PARTY_NOTICES.md
aa9cd295b3762df2f367a8d51247351c803e7507bddf8fe6bb29e7809878b845 tools/verify_runtime.py
f9375629fa1a2c4d3538442f0c3192d7ba2f46fe9544fb2e21f0c144b53d608c docs/AB_TEST_LOG_JA.md
ff959da37f08f0d433a7584478f5146aa10043da5bd52a40c9af5da9731aeb2e v2/nodes.py
ffd61f3f31c9b6430e1169007ee906c8f5000eba63ee44e2976ad4f5f1112671 v2/__init__.py
cde27db19b677e318cc4dfb4235be7a11429c19945f4083052a91fe117e74c82 v2/decoder.py
31012ec48a64c7467ad869c79982b7f8502c1785c33f51ee1b5727ce8b4243fb v2/diagnostics.py
10bbdf1f39b625cea448363aba908868d2106f960efd71115e037ad5f1e24c09 v2/h3_builder.py
aea01a48a8c03a25ed97ea05e5b137f89e388832d1be7d38f2da2be3d1b9830b v2/motion.py
d758281825cc50ff386b3b6adbc47b4dca2e3aadb2a31924e82aa7f748f76e49 v2/nodes.py
cfab4847c2fd53b507081ee21724e7120666b52d1b98d159717ad54d1ca8fd9b v2/prompts.py
4080f1875b958b316e8e76852c4be5527a6de5c71d604e7642d3098478eb4a36 v2/sampling.py
2fd811794c4cc0f2ce050250b80484876454926b9f20fce6af3a97d728e5acdf v2/seam_guard.py
be0d8585fa57e0ccd6d02577bbc7299629e5bfe20e186747f571fccc98b67d7e v2/seam_types.py
12cfcc0c71ca087fe39a5ce2922959a62b2bb311bfe664f05c4480affce03708 v2/seeds.py
e7aace33b4ea7c104f7883814841690175556cb3ff25ff21eb7c3401eedb5742 v2/sequence.py
b708599c0f6ffba4556e77536558a415104b0d4c1d043f335197bfb6960f07df v2/session.py
13213e7709fd02bb810af3c18e4cd7d010f8cdfb121a4b99866a9f2333331089 v2/session_io.py
78c830cdf49034c6e3b2cd3da5914d5cfc5638eb63ec6dbd1bab13c50d6d4caf v3/__init__.py
9cdb682168cea0cd4bb2e8ce69d043ddcbdb9204901035e6ccabad112e77f81a v3/assembly.py
5465896b8651fca4feab299579e167849624c17732139b9ae220710873a68483 v3/nodes.py
66bd67c9ec7d8a7f32c7d1c1fc4ce1c19b42fda5d7cece67b171c3cffc49f0a8 v3/plan.py
4085160d48172468901b9c0fd1229e97c3328ef1870071c2c8d0e4e7ac056e6e version.py
+12 -21
View File
@@ -1,23 +1,14 @@
名称: ComfyUI-H3-Continuum
バージョン: 3.2.1
対象: ComfyUI native MiniMax H3
主ノード: H3 Continuum Sampler
ライセンス: MIT
追加pip依存: なし
ComfyUI-H3-Continuum V3.3.0 Stable
V3.2.1:
- 正式安定版。CI、Windows実機、Ref2VA、Spectrum Actual Prefix 2、Run Storage完全再開を確認
- T2VA / I2VA / FL2VA / Reference + Continuation
- 最大2枚のReference Imageを全Chunkで維持
- Core Video/Audio VAE Decodeへ外出し
- Run StorageによるChunk保存、自動再開、部分再生成
- Graph + runtime署名とChunk SHA-256による安全側の再利用判定
- 旧V1/V2/V3 Node IDをWorkflow互換のため維持
MiniMax H3の5秒ChunkをAV latent contextで継続し、長尺映像として組み立てるComfyUIカスタムノードです。
Core:
- native H3 raw video/audio latent continuation
- 5/22/39f + Auto context
- Spectrum Interop API v1 Actual Prefix 2 request
- SageAttention / Sol-Attn / Spectrum外部併用
- Session / Run Storage resume / reroll
- Audio Seam Off / Auto
V3.3.0:
- Timeline VideoをChunk単位で参照する安定ノード
- Audio Seam Autoを既定化
- Video Seam Autoによるguarded transient / micro-flash補正
- Auto 2による実験的なexposure-ramp補正
- Reference Image 1-3 / Reference Audio 1
- Run Storage / Auto Resume
- Spectrum Interop API v1 / Actual Prefix 2を維持
詳細: README.md および docs/VALIDATION_RESULTS.md
+17 -26
View File
@@ -1,30 +1,21 @@
ComfyUI-H3-Continuum 3.2.1 - Stable Package Validation
Date: 2026-08-14
Status: PASS / Stable
ComfyUI-H3-Continuum V3.3.0 package validation
Release hardening scope:
- Graph + runtime MODEL/CLIP/VAE sampling contract
- Chunk file SHA-256 verification
- Run Storage automatic ID fallback and Storage-only partial regeneration
- V3.2.1 Windows installer/runtime verifier
- Explicit CI numpy/safetensors test dependencies
Status: Stable release candidate validated for publication.
Completed automated validation:
- Python syntax / compileall: PASS
- pytest: 129 passed
- GitHub Actions: GREEN
- Local package sync: 100 files matched, 0 hash differences
Required automated checks:
- python -m compileall -q .
- python -m pytest -q -p no:cacheprovider
- python tools/verify_runtime.py <runtime-path>
Completed Windows runtime validation:
- RTX 5060 Ti 16GB / ComfyUI v0.32.0
- Ref2VA Reference + Continuation with two images: PASS
- 3 x 5 second generation at 1056x608: 0 reused / 3 generated
- Stored manifest complete, resume_safe=true, three Chunk SHA-256 values matched
- Complete Auto Resume: 3 reused / 0 generated
- Spectrum Continuum API accepted Actual Prefix 2 on continuation chunks
- FL2VA / Ref2VA, Prompt, resolution and Reference changes created distinct contracts
- Strict FL2VA + Reference and non-32-multiple resolution rejection: PASS
Validated runtime paths include:
- Production sampler and Core VAE Decode assembly
- Reference Image 1-3 and Reference Audio 1
- Run Storage save, checksum verification, and complete reuse
- Timeline Video chunk-local slicing at Efficient 0.4 MP
- Spectrum Interop API v1 with Actual Prefix 2 on continuation chunks
- Audio Seam Auto
- Video Seam Auto guarded transient and micro-flash correction
Release decision:
- V3.2.1 is the current stable production baseline.
- A GitHub tag or Release remains a separate publication step.
Auto 2 remains experimental. It is an optional fallback for exposure-ramp boundaries and is not the default.
Detailed evidence: docs/VALIDATION_RESULTS.md
+34 -79
View File
@@ -1,8 +1,8 @@
# ComfyUI-H3-Continuum 3.2.1
# ComfyUI-H3-Continuum 3.3.0
Native long-form MiniMax H3 video and audio continuation for ComfyUI.
**Stable release:** V3.2.1. The production path has passed local syntax and pytest checks, GitHub Actions, Windows generation, Ref2VA Reference + Continuation, Spectrum Actual Prefix 2, and complete Run Storage resume.
**Stable release:** V3.3.0. It adds chunk-local Timeline Video and guarded decoded-video seam correction while preserving the stable sampler, Run Storage contracts, and Spectrum Interop API v1.
https://github.com/user-attachments/assets/bfa8c683-fc9d-48f1-9cdb-477ca110cdf2
@@ -15,10 +15,13 @@ V3 delegates video and audio decoding to normal **ComfyUI Core VAE Decode nodes*
- Raw paired video/audio latent continuation without decode/re-encode between chunks.
- One production sampler UI with normal controls first and infrequent controls marked Advanced.
- T2VA, First Frame, Last Frame, First + Last Frame, and Reference conditioning.
- Up to two persistent Reference images across every chunk.
- Up to three active Reference images across every chunk, compacted in Core connection order.
- One native Reference Audio item across every chunk.
- Disk-backed Run Storage with automatic resume and compatible Revision reuse.
- Fixed, List, and Timeline prompts through one Sequence Prompt input.
- ComfyUI Core Video/Audio VAE Decode and a separate Continuum Assemble stage.
- Chunk-local Timeline Video conditioning with an efficient 0.4 MP default.
- Guarded Audio Seam and Video Seam correction after Core decode.
- Optional Spectrum Actual Prefix 2 interoperability.
- External SageAttention, LoRA, Turbo, and Spectrum MODEL chains remain composable.
- Existing legacy node identifiers remain registered for saved-workflow compatibility.
@@ -53,7 +56,7 @@ MiniMax H3 Video VAE -------------> video_vae
Sampler --------------------------> sampler
Sigmas ---------------------------> sigmas
Text (Multiline) -----------------> Sequence Prompt
Optional images ------------------> first_frame / last_frame / reference_image_1/2
Optional images ------------------> first_frame / last_frame / reference_image_1/2/3
video_latents --> Core VAE Decode -----------+
audio_latents --> Core VAE Decode Audio -----+--> H3 Continuum Assemble V3
@@ -76,17 +79,18 @@ The sampler selects the mode from connected image inputs.
| First Frame | I2VA + Continuation |
| Last Frame | Last-frame-conditioned + Continuation |
| First + Last Frame | FL2VA + Continuation |
| Reference 1, optionally Reference 2 | Reference + Continuation |
| Reference 1, optionally Reference 2 and 3 | Reference + Continuation |
Reference images and First/Last Frame are mutually exclusive. `Reference 2` cannot be used without `Reference 1`.
Reference images and First/Last Frame are mutually exclusive. Active Reference inputs are compacted in Core connection order; bypassed sockets are ignored.
For the formally supported Reference path, connect a MiniMax H3 **Ref2VA** MODEL upstream. With **Strict Compatibility** enabled (the default), Reference generation stops unless the upstream base checkpoint can be verified as Ref2VA. FL2VA MODEL + Reference conditioning has also worked in local testing, but requires Strict Compatibility to be disabled and remains experimental.
Reference Image 1, 1+2, or 1+2+3 may be connected. A single active image is treated as Picture 1, and active images are numbered without gaps. **Ref2VA** is the reference-specialized checkpoint and may provide stronger reference fidelity, while **FL2VA + Reference** is also allowed. Checkpoint classification is diagnostic only; the sampler never switches MODELs automatically. **Strict Compatibility** remains reserved for H3 contracts that are actually unsafe or unsupported.
Reference prompts should identify the images explicitly:
```text
<Picture 1> defines the subject's face and identity.
<Picture 2> defines the subject's clothing, body design, and skateboard.
<Picture 3> optionally defines another ordered identity, object, or environment reference.
```
Reference images persist across all Continuum chunks.
@@ -115,7 +119,7 @@ Recommended safe defaults:
| Prompt Format | Auto |
| Continuity | Balanced - 22 frames |
| Audio Continuity | On |
| Audio Seam | Off |
| Audio Seam | Auto |
| Report Detail | Basic |
| Regenerate From | Auto |
| Run Storage | Off for short tests; Save + Auto Resume for long runs |
@@ -210,7 +214,7 @@ Select `Chunk N` in `Regenerate From` to reuse chunks before N and regenerate N
## Spectrum-aware continuation
With a compatible [ComfyUI Spectrum MiniMax H3](https://github.com/xmarre/ComfyUI-Spectrum-MiniMax-H3), Continuum requests **Actual Prefix 2** for continuation chunks through Interop API v1.
With a compatible [ComfyUI Spectrum MiniMax H3](https://github.com/xmarre/ComfyUI-Spectrum-MiniMax-H3), Continuum requests **Actual Prefix 2** for continuation chunks through Interop API v1. Upstream integration is currently pending in [PR #52](https://github.com/xmarre/ComfyUI-Spectrum-MiniMax-H3/pull/52); until it is merged, use the validated PR/Fork receiver and confirm the acceptance log below.
```text
Chunk 1: normal path
@@ -247,6 +251,24 @@ Experimental
Turbo + Spectrum is not the recommended default because local testing showed a higher risk of artifacts. Sol-Attn is also not part of the current recommended continuity profile.
## Timeline Video
`H3 Continuum Timeline Video` adds an optional `VIDEO` source to the existing continuation pipeline. The source is sliced per 5-second chunk, resized independently from the output, encoded only for chunks that must be generated, and released after use.
- `Efficient - 0.4 MP` is the default and recommended starting point.
- `Match Output` preserves more source detail but can be substantially slower and heavier.
- Timeline-video audio is not used; connect Reference Audio separately when needed.
- Results still depend on the checkpoint, prompt, source motion, and reference compatibility.
## Assemble + Seam
Connect decoded chunk images, audio, and `assembly_plan` to `H3 Continuum Assemble + Seam`.
- Default: `Audio Seam = Auto`, `Video Seam = Auto`, `Report Detail = Basic`.
- Video modes: `Auto`, `Auto 2`, `Analyze Only`, `Off`.
- `Auto` applies guarded transient and micro-flash correction without frame deletion.
- `Auto 2` additionally enables guarded exposure-ramp correction and remains experimental.
- `Analyze Only` reports the boundary classification without changing images or audio.
## Why Core Decode is external
Continuum owns sampling, continuation planning, chunk metadata, context trimming, audio alignment, exact duration, and final assembly.
@@ -257,78 +279,11 @@ This allows the normal Core `VAE Decode` to benefit from ComfyUI updates without
Full raw chunks are decoded before Continuum trims repeated context. Trimming latents before decode would change temporal VAE conditioning.
## Tested results
## Validation summary
### V3.2.1 stable acceptance
```text
Release baseline Commit 2be54bd / ComfyUI v0.32.0
GPU NVIDIA GeForce RTX 5060 Ti 16GB
Python checks PASS
pytest 129 passed
GitHub Actions GREEN
Local package sync 100 files matched / 0 hash differences
Conditioning Ref2VA Reference + Continuation
Reference images 2
Chunks 3 x 5 seconds
Continuity Balanced 22
Spectrum Interop Actual Prefix 2 accepted
```
The initial 1056 x 608 run generated and stored all three chunks (`0 reused / 3 generated`) in 1073.81 seconds. Its manifest completed with `resume_safe = true`, and all three stored chunk SHA-256 values matched. The follow-up run reused all three chunks (`3 reused / 0 generated`) and completed Core decode and assembly in 116.86 seconds.
The sampling contract also distinguished MODEL family, prompt, resolution, Run Storage mode, upscale path, and Reference configuration changes without observed cross-condition chunk reuse.
Local validation environment:
```text
GPU: NVIDIA GeForce RTX 5060 Ti 16GB
System RAM: 64GB
ComfyUI: v0.32.0 generation
```
Observed successful runs include:
- 3 x 5 seconds at approximately 0.3 MP, 0.5 MP, and 0.6 MP.
- 6 x 5 seconds (30 seconds) at approximately 0.3 MP.
- 12 x 5 seconds (60 seconds) at approximately 0.3 MP.
- 12 x 5 seconds at approximately 0.5 MP without OOM; generation was substantially slower.
- Reference + Continuation with two images using both FL2VA and Ref2VA MODEL tests.
- V3.2.1 Revision switching: FL2VA -> Ref2VA -> FL2VA.
- LoRA strength change created a new Revision; restoring the prior strength reused the earlier Revision.
- Complete 3-chunk reuse reported `3 reused / 0 generated`; Core decode/assembly took about 58-61 seconds at 736 x 416.
These are local results, not minimum hardware guarantees. Resolution, model precision, patches, offload behavior, and other loaded nodes determine actual limits.
## Diagnostics
`status` is a normal STRING output. Connect it to Core **Preview as Text** when you need the sampling and Run Storage report.
Useful lines include:
```text
Conditioning mode: Reference + Continuation.
interop=emitted actual_prefix=2
3 reused, 0 generated
resume=complete
```
`accelerator markers not detected (informational only)` is not an error. It only means the optional accelerator marker was not observable.
Use `Report Detail = Basic` normally. Enable detailed diagnostics and `debug` only when troubleshooting.
## Compatibility and scope
- Native MiniMax H3 PackedLayout is preserved.
- Video and audio VAEs are not run between sampling chunks.
- Accepted raw chunk latents are retained on CPU.
- MODEL input is cloned once per chunk; the workflow MODEL is not mutated.
- SageAttention, LoRA/Turbo, Spectrum, and model weights remain external.
- Unknown H3 layout contracts fail clearly.
- Legacy V1/V2/V3 node identifiers remain registered for older workflows but are not the recommended starting point.
Continuum is independently implemented. It does not copy or bundle source code from Spectrum or [H3 Motion Context](https://github.com/NikoDemon80/ComfyUI-H3-Motion-Context).
V3.3.0 passed the automated suite and Windows runtime checks for the production sampler, Reference Image/Audio, Run Storage, Timeline Video, Spectrum Actual Prefix 2, Audio Seam Auto, and guarded Video Seam Auto.
`Auto 2` is included as an experimental fallback when `Auto` does not sufficiently reduce a boundary exposure ramp. Detailed test conditions, results, and remaining limits are recorded in [docs/VALIDATION_RESULTS.md](docs/VALIDATION_RESULTS.md).
## Development checks
```bash
+173 -3
View File
@@ -1,76 +1,246 @@
# ComfyUI-H3-Continuum 2.1.7
# ComfyUI-H3-Continuum 3.3.0
**V3.3.0 Stable:** Timeline Video、Audio Seam Auto、Video Seam Auto、Reference Audio、Run Storageを含む安定版です。
**V3.3.0 Stable:** Timeline Video、Audio Seam Auto、Video Seam Auto、Reference Audio、Run Storageを含む安定版です。
MiniMax H3を複数チャンクで連続生成し、直前チャンク末尾の**映像latent / 音声latentを直接**次チャンクへ継承するComfyUIカスタムノードです。チャンク間でVideo/Audio VAEのDecode→Encodeは行いません。
## V2.1.7 Stable Facade UI
**V3.3.0 Stable:** Timeline Video、Audio Seam Auto、Video Seam Auto、Reference Audio、Run Storageを含む安定版です。
**V3.3.0 Stable:** Timeline Video、Audio Seam Auto、Video Seam Auto、Reference Audio、Run Storageを含む安定版です。
## V3.2.4 Stable
**V3.3.0 Stable:** Timeline Video、Audio Seam Auto、Video Seam Auto、Reference Audio、Run Storageを含む安定版です。
**V3.3.0 Stable:** Timeline Video、Audio Seam Auto、Video Seam Auto、Reference Audio、Run Storageを含む安定版です。
V3.2.4は、T2VA / I2VA / FL2VA / Reference + Continuationに対応し、最大3枚のReference ImageとReference Audio 1をCore互換の順序で扱います。First/Last FrameとReference Audioを併用する場合も、Tokenizer側のPicture/Audio表示とDiT側のKeyframe/Audio conditioningを分離して処理します。Run Storage、Spectrum Interop、外部Core VAE Decodeは従来どおりです。
**V3.3.0 Stable:** Timeline Video、Audio Seam Auto、Video Seam Auto、Reference Audio、Run Storageを含む安定版です。
**V3.3.0 Stable:** Timeline Video、Audio Seam Auto、Video Seam Auto、Reference Audio、Run Storageを含む安定版です。
Reference入力のバイパスされたソケットは無視され、有効な画像だけがPicture 1から連続採番されます。プロンプト内の利用できないPicture/Audioタグは警告として扱い、生成は継続します。
**V3.3.0 Stable:** Timeline Video、Audio Seam Auto、Video Seam Auto、Reference Audio、Run Storageを含む安定版です。
**V3.3.0 Stable:** Timeline Video、Audio Seam Auto、Video Seam Auto、Reference Audio、Run Storageを含む安定版です。
## Legacy V2.1.7 Stable Facade UI
**V3.3.0 Stable:** Timeline Video、Audio Seam Auto、Video Seam Auto、Reference Audio、Run Storageを含む安定版です。
**V3.3.0 Stable:** Timeline Video、Audio Seam Auto、Video Seam Auto、Reference Audio、Run Storageを含む安定版です。
V2.1.7では、V2.1.6の動的表示制御を廃止し、標準ComfyUI描画だけを使用する静的Facadeへ移行しました。生成処理は互換用`H3ContinuumSamplerV2`を再利用し、State、Session、Prompt Plan、Spectrum Interop、保存Schemaは変更していません。
**V3.3.0 Stable:** Timeline Video、Audio Seam Auto、Video Seam Auto、Reference Audio、Run Storageを含む安定版です。
**V3.3.0 Stable:** Timeline Video、Audio Seam Auto、Video Seam Auto、Reference Audio、Run Storageを含む安定版です。
通常表示は次を中心にします。
**V3.3.0 Stable:** Timeline Video、Audio Seam Auto、Video Seam Auto、Reference Audio、Run Storageを含む安定版です。
**V3.3.0 Stable:** Timeline Video、Audio Seam Auto、Video Seam Auto、Reference Audio、Run Storageを含む安定版です。
```text
**V3.3.0 Stable:** Timeline Video、Audio Seam Auto、Video Seam Auto、Reference Audio、Run Storageを含む安定版です。
model / clip / video_vae / audio_vae / sampler / sigmas
**V3.3.0 Stable:** Timeline Video、Audio Seam Auto、Video Seam Auto、Reference Audio、Run Storageを含む安定版です。
Sequence Prompt
**V3.3.0 Stable:** Timeline Video、Audio Seam Auto、Video Seam Auto、Reference Audio、Run Storageを含む安定版です。
first_frame
**V3.3.0 Stable:** Timeline Video、Audio Seam Auto、Video Seam Auto、Reference Audio、Run Storageを含む安定版です。
prompt_overrides(任意pack)
**V3.3.0 Stable:** Timeline Video、Audio Seam Auto、Video Seam Auto、Reference Audio、Run Storageを含む安定版です。
advanced(任意pack)
**V3.3.0 Stable:** Timeline Video、Audio Seam Auto、Video Seam Auto、Reference Audio、Run Storageを含む安定版です。
**V3.3.0 Stable:** Timeline Video、Audio Seam Auto、Video Seam Auto、Reference Audio、Run Storageを含む安定版です。
Prompt Format
**V3.3.0 Stable:** Timeline Video、Audio Seam Auto、Video Seam Auto、Reference Audio、Run Storageを含む安定版です。
chunks
**V3.3.0 Stable:** Timeline Video、Audio Seam Auto、Video Seam Auto、Reference Audio、Run Storageを含む安定版です。
chunk_seconds
**V3.3.0 Stable:** Timeline Video、Audio Seam Auto、Video Seam Auto、Reference Audio、Run Storageを含む安定版です。
width / height
**V3.3.0 Stable:** Timeline Video、Audio Seam Auto、Video Seam Auto、Reference Audio、Run Storageを含む安定版です。
continuity
**V3.3.0 Stable:** Timeline Video、Audio Seam Auto、Video Seam Auto、Reference Audio、Run Storageを含む安定版です。
base_seed
**V3.3.0 Stable:** Timeline Video、Audio Seam Auto、Video Seam Auto、Reference Audio、Run Storageを含む安定版です。
control after generate
Seam Correction
**V3.3.0 Stable:** Timeline Video、Audio Seam Auto、Video Seam Auto、Reference Audio、Run Storageを含む安定版です。
Seam Correction
**V3.3.0 Stable:** Timeline Video、Audio Seam Auto、Video Seam Auto、Reference Audio、Run Storageを含む安定版です。
Seam Correction
**V3.3.0 Stable:** Timeline Video、Audio Seam Auto、Video Seam Auto、Reference Audio、Run Storageを含む安定版です。
**V3.3.0 Stable:** Timeline Video、Audio Seam Auto、Video Seam Auto、Reference Audio、Run Storageを含む安定版です。
outputs: images / audio / result
**V3.3.0 Stable:** Timeline Video、Audio Seam Auto、Video Seam Auto、Reference Audio、Run Storageを含む安定版です。
```
**V3.3.0 Stable:** Timeline Video、Audio Seam Auto、Video Seam Auto、Reference Audio、Run Storageを含む安定版です。
**V3.3.0 Stable:** Timeline Video、Audio Seam Auto、Video Seam Auto、Reference Audio、Run Storageを含む安定版です。
### 補助ノード
**V3.3.0 Stable:** Timeline Video、Audio Seam Auto、Video Seam Auto、Reference Audio、Run Storageを含む安定版です。
**V3.3.0 Stable:** Timeline Video、Audio Seam Auto、Video Seam Auto、Reference Audio、Run Storageを含む安定版です。
- `H3 Continuum Clip Overrides`: Clip別Promptを1本のpackへまとめます。
**V3.3.0 Stable:** Timeline Video、Audio Seam Auto、Video Seam Auto、Reference Audio、Run Storageを含む安定版です。
- `H3 Continuum Advanced`: resume/session入力と低頻度設定をまとめます。
**V3.3.0 Stable:** Timeline Video、Audio Seam Auto、Video Seam Auto、Reference Audio、Run Storageを含む安定版です。
- `H3 Continuum Result`: resultから`last_state / session / report`を展開します。
**V3.3.0 Stable:** Timeline Video、Audio Seam Auto、Video Seam Auto、Reference Audio、Run Storageを含む安定版です。
- 補助ノードを使わない通常生成では、Sampler本体だけで動作します。
**V3.3.0 Stable:** Timeline Video、Audio Seam Auto、Video Seam Auto、Reference Audio、Run Storageを含む安定版です。
**V3.3.0 Stable:** Timeline Video、Audio Seam Auto、Video Seam Auto、Reference Audio、Run Storageを含む安定版です。
### Legacy互換
**V3.3.0 Stable:** Timeline Video、Audio Seam Auto、Video Seam Auto、Reference Audio、Run Storageを含む安定版です。
**V3.3.0 Stable:** Timeline Video、Audio Seam Auto、Video Seam Auto、Reference Audio、Run Storageを含む安定版です。
旧`H3ContinuumSamplerV2`は削除せずLegacy/Coreノードとして登録を維持します。既存WorkflowのノードID、入力順、出力順は変更していません。
**V3.3.0 Stable:** Timeline Video、Audio Seam Auto、Video Seam Auto、Reference Audio、Run Storageを含む安定版です。
**V3.3.0 Stable:** Timeline Video、Audio Seam Auto、Video Seam Auto、Reference Audio、Run Storageを含む安定版です。
## Continuity
**V3.3.0 Stable:** Timeline Video、Audio Seam Auto、Video Seam Auto、Reference Audio、Run Storageを含む安定版です。
**V3.3.0 Stable:** Timeline Video、Audio Seam Auto、Video Seam Auto、Reference Audio、Run Storageを含む安定版です。
- `Auto — conservative`
**V3.3.0 Stable:** Timeline Video、Audio Seam Auto、Video Seam Auto、Reference Audio、Run Storageを含む安定版です。
- `Balanced — 22 frames`(標準)
**V3.3.0 Stable:** Timeline Video、Audio Seam Auto、Video Seam Auto、Reference Audio、Run Storageを含む安定版です。
- `Fast — 5 frames`
**V3.3.0 Stable:** Timeline Video、Audio Seam Auto、Video Seam Auto、Reference Audio、Run Storageを含む安定版です。
- `Strong — 39 frames (Experimental)`
**V3.3.0 Stable:** Timeline Video、Audio Seam Auto、Video Seam Auto、Reference Audio、Run Storageを含む安定版です。
**V3.3.0 Stable:** Timeline Video、Audio Seam Auto、Video Seam Auto、Reference Audio、Run Storageを含む安定版です。
5/22/39フレームはH3の時間latent周期`1,4,4,4,4`に対して、それぞれ2/7/12 temporal latent stepsです。
**V3.3.0 Stable:** Timeline Video、Audio Seam Auto、Video Seam Auto、Reference Audio、Run Storageを含む安定版です。
**V3.3.0 Stable:** Timeline Video、Audio Seam Auto、Video Seam Auto、Reference Audio、Run Storageを含む安定版です。
## Spectrum
**V3.3.0 Stable:** Timeline Video、Audio Seam Auto、Video Seam Auto、Reference Audio、Run Storageを含む安定版です。
**V3.3.0 Stable:** Timeline Video、Audio Seam Auto、Video Seam Auto、Reference Audio、Run Storageを含む安定版です。
Continuumは有効な前チャンクContextがある場合だけ`h3_continuum` Interop API v1をMODEL optionsへ付与し、対応Spectrumへ`min_actual_prefix_steps=2`を要求します。初回チャンクにはInterop keyを付与しません。未知・未対応Spectrumでは通常Spectrumとしてfail-openします。
**V3.3.0 Stable:** Timeline Video、Audio Seam Auto、Video Seam Auto、Reference Audio、Run Storageを含む安定版です。
**V3.3.0 Stable:** Timeline Video、Audio Seam Auto、Video Seam Auto、Reference Audio、Run Storageを含む安定版です。
## 推奨配線
**V3.3.0 Stable:** Timeline Video、Audio Seam Auto、Video Seam Auto、Reference Audio、Run Storageを含む安定版です。
**V3.3.0 Stable:** Timeline Video、Audio Seam Auto、Video Seam Auto、Reference Audio、Run Storageを含む安定版です。
```text
**V3.3.0 Stable:** Timeline Video、Audio Seam Auto、Video Seam Auto、Reference Audio、Run Storageを含む安定版です。
UNET -> SageAttention -> Sol-Attn -> LoRA -> Spectrum -> H3 Continuum Sampler
**V3.3.0 Stable:** Timeline Video、Audio Seam Auto、Video Seam Auto、Reference Audio、Run Storageを含む安定版です。
```
**V3.3.0 Stable:** Timeline Video、Audio Seam Auto、Video Seam Auto、Reference Audio、Run Storageを含む安定版です。
**V3.3.0 Stable:** Timeline Video、Audio Seam Auto、Video Seam Auto、Reference Audio、Run Storageを含む安定版です。
まず`chunks=2 / chunk_seconds=5 / Balanced 22f / Seam Correction=Off`でNative Continuityを確認し、その後`Seam Correction=Auto`を比較してください。
**V3.3.0 Stable:** Timeline Video、Audio Seam Auto、Video Seam Auto、Reference Audio、Run Storageを含む安定版です。
**V3.3.0 Stable:** Timeline Video、Audio Seam Auto、Video Seam Auto、Reference Audio、Run Storageを含む安定版です。
## インストール
**V3.3.0 Stable:** Timeline Video、Audio Seam Auto、Video Seam Auto、Reference Audio、Run Storageを含む安定版です。
**V3.3.0 Stable:** Timeline Video、Audio Seam Auto、Video Seam Auto、Reference Audio、Run Storageを含む安定版です。
ZIPを展開して、`ComfyUI-H3-Continuum`フォルダーを`ComfyUI/custom_nodes/`へ置き、ComfyUIを再起動します。
**V3.3.0 Stable:** Timeline Video、Audio Seam Auto、Video Seam Auto、Reference Audio、Run Storageを含む安定版です。
**V3.3.0 Stable:** Timeline Video、Audio Seam Auto、Video Seam Auto、Reference Audio、Run Storageを含む安定版です。
旧`ComfyUI-H3-Continuum-Join`が残っている場合は同時ロードを避けるため削除または退避してください。同梱`install_windows.bat`は旧名・新名の既存フォルダーを日時付きでバックアップします。
**V3.3.0 Stable:** Timeline Video、Audio Seam Auto、Video Seam Auto、Reference Audio、Run Storageを含む安定版です。
**V3.3.0 Stable:** Timeline Video、Audio Seam Auto、Video Seam Auto、Reference Audio、Run Storageを含む安定版です。
## 検査
**V3.3.0 Stable:** Timeline Video、Audio Seam Auto、Video Seam Auto、Reference Audio、Run Storageを含む安定版です。
**V3.3.0 Stable:** Timeline Video、Audio Seam Auto、Video Seam Auto、Reference Audio、Run Storageを含む安定版です。
```text
**V3.3.0 Stable:** Timeline Video、Audio Seam Auto、Video Seam Auto、Reference Audio、Run Storageを含む安定版です。
python -m compileall -q .
**V3.3.0 Stable:** Timeline Video、Audio Seam Auto、Video Seam Auto、Reference Audio、Run Storageを含む安定版です。
pytest -q
**V3.3.0 Stable:** Timeline Video、Audio Seam Auto、Video Seam Auto、Reference Audio、Run Storageを含む安定版です。
```
**V3.3.0 Stable:** Timeline Video、Audio Seam Auto、Video Seam Auto、Reference Audio、Run Storageを含む安定版です。
**V3.3.0 Stable:** Timeline Video、Audio Seam Auto、Video Seam Auto、Reference Audio、Run Storageを含む安定版です。
GPL-3.0-or-later。
**V3.3.0 Stable:** Timeline Video、Audio Seam Auto、Video Seam Auto、Reference Audio、Run Storageを含む安定版です。
-27
View File
@@ -289,30 +289,3 @@ Revision 2167719e99b1e782
- FL2VAからRef2VAへの変更、およびPrompt変更を別Revisionとして扱い、旧Chunkを誤再利用しなかった。
- 00006~00008の生成時間は約749~752秒で、モデル切替やPrompt修正による異常な時間増加はない。
- 00008はユーザー目視を含め、V3.2.1 Reference + Continuationの実用可能な実機成績として保存する。
## V3.2.1 Stable 最終受け入れ
```text
Commit 2be54bd
ComfyUI v0.32.0
GPU RTX 5060 Ti 16GB
Conditioning Ref2VA Reference + Continuation
Reference images 2
Output 1056x608 / 24fps / 15秒
Chunks 3 x 5秒
Continuity Balanced 22
Spectrum Interop Actual Prefix 2
```
| 動画 | 実行 | 生成時間 | 結果 |
|---|---|---:|---|
| 00009 | 初回生成 | 1073.81秒 | 0 reused / 3 generated、manifest complete、resume_safe=true、3 Chunk SHA-256一致 |
| 00012 | 完全Auto Resume | 116.86秒 | 3 reused / 0 generated、resume=complete、Ref2VA verified |
最終判定:
- Python構文確認、pytest 129件、GitHub Actions、ローカル100ファイル一致を確認。
- Reference + Continuation、外部Core VAE Decode、Spectrum Actual Prefix 2、Run Storage保存と完全再開をWindows実機で確認。
- FL2VA/Ref2VA、Prompt、解像度、Run Storage、アップスケール経路、Reference構成の変更を別条件として識別した。
- 異なる条件のChunkを誤再利用した事例はない。
- V3.2.1を正式安定版として採用する。
+56
View File
@@ -0,0 +1,56 @@
# H3 Continuum Seam Test Source
`H3 Continuum Seam Test Source (Experimental)`は、Video Seamの比較専用ノードです。
H3 Samplingは実行せず、同じ入力画像から決定的な3つの5秒Chunkを作ります。
## 接続
```text
Load Image
image
-> H3 Continuum Seam Test Source (Experimental)
Seam Test Source: images
-> H3 Continuum Assemble + Seam: images
Seam Test Source: audio
-> H3 Continuum Assemble + Seam: audio
Seam Test Source: assembly_plan
-> H3 Continuum Assemble + Seam: assembly_plan
```
Assembler側は次の設定にします。
```text
exact_total_duration = true
Audio Seam = Off
Report Detail = Detailed Report
```
## 比較手順
同じ入力画像と`Exposure Change = 0.08`を維持し、`Video Seam`だけ変更します。
1. `Analyze Only`
2. `Auto`
3. `Auto 2`(露出ランプ補正はExperimental)
期待結果は次のとおりです。
```text
Analyze Only
-> 1->2、2->3とも class=exposure_ramp
-> フレームは未変更
Auto
-> exposure rampは補正対象外
-> action=kept native boundary
Auto 2
-> 各境界の先頭4フレームだけ露出を補間
-> action=normalized exposure/color on 4 exposure ramp boundary frame(s)
```
`Test Resolution = 256 px (Fast)`を推奨します。アルゴリズムの判定確認に高解像度は不要です。
`Input Size`は800x800入力で数GiBのRAMを消費する可能性があります。
+99
View File
@@ -0,0 +1,99 @@
# V3.3.0 Validation Results
This file consolidates the release evidence by feature. It is not a claim that every model, LoRA, prompt, resolution, or GPU produces identical visual quality.
## 1. Test environment
- Windows 11 and ComfyUI Core
- NVIDIA GeForce RTX 5060 Ti 16 GB
- MiniMax H3 Ref2VA and FL2VA paths
- Standard approximately 20-step and Turbo 4/8-step profiles
- Core Video/Audio VAE Decode followed by Continuum assembly
## 2. Core continuation
**Purpose:** verify raw paired AV continuation over multiple 5-second chunks.
**Coverage:** 1, 2, 3, and 6 chunks; T2VA, I2VA, FL2VA, and Reference conditioning.
**Result:** sampling, 22-frame context trimming, exact-duration assembly, and external Core VAE decode completed. Three-chunk outputs retained 362 source frames and assembled to 360 frames.
**Verdict:** PASS.
## 3. Reference image and audio
**Coverage:** one to three ordered images, Ref2VA and FL2VA diagnostics, native Reference Audio, and image/audio persistence across chunks.
**Result:** three-image conditioning and native Reference Audio completed. Bypassed image sockets were ignored and active images were compacted in Core order. Reference Audio influences native H3 generation but is not an exact source-audio or strict lip-sync contract.
**Verdict:** PASS with the documented native-model limitation.
## 4. Run Storage and resume
**Coverage:** initial three-chunk save, SHA-256 verification, complete reuse, condition changes, and partial regeneration.
**Representative result:** initial run reported `0 reused / 3 generated`; complete Auto Resume reported `3 reused / 0 generated`. Changed MODEL, prompt, resolution, Reference configuration, and storage conditions did not reuse incompatible chunks.
**Verdict:** PASS.
## 5. Spectrum interoperability
**Coverage:** Spectrum `continuum-interop` PR head `c68f967b47f80a95077a251e91b8ed20098de9e3`, `res_multistep`, 3 x 5 seconds.
**Result:** Chunk 1 emitted no acceptance log. Chunks 2 and 3 each accepted `actual prefix=2` exactly once. All sampling passes, Core VAE Decode, and final assembly completed at 800 x 800 for 15 seconds.
**Verdict:** PASS on the validated PR/Fork receiver. Upstream PR #52 remains pending; verify the runtime acceptance log until merged.
## 6. Timeline Video
**Coverage:** optional Core VIDEO input, omitted/bypassed fallback, chunk-local temporal slicing, 0.4 MP preprocessing, Match Output, Ref2VA/FL2VA, Turbo and standard 20-step Spectrum paths, and one/two-chunk runs.
**Representative outputs:** `MiniMax_H3_Continuum_V31_00035_.mp4`, `MiniMax_H3_Continuum_V31_00039_.mp4`, and `MiniMax_H3_Continuum_V31_00040_.mp4`.
**Result:** chunk-local slices reached sampling and assembly correctly. Efficient 0.4 MP was substantially more practical than Match Output and showed no consistent benefit from the removed 0.6 MP UI preset.
**Verdict:** PASS. Motion, identity, detail, and generated audio remain model-, LoRA-, source-, and prompt-dependent.
## 7. Audio Seam
**Coverage:** Off and Auto on real multi-chunk decoded audio.
**Result:** Auto reduced measured boundary jumps while keeping final duration aligned. Audio and Video Seam remained independently selectable.
**Verdict:** PASS; Auto is the V3.3.0 default.
## 8. Video Seam Auto
**Coverage:** Analyze Only and Auto over real three-chunk outputs with clean boundaries, transient flashes, and micro-flashes.
**Representative outputs:** `MiniMax_H3_Continuum_V31_00047_.mp4`, `00048`, `00053`, `00054`, `00057`, `00058`, `00059`, and `00060`.
**Result:** qualified transient or micro-flash frames were corrected; clean boundaries were retained. Frame count, resolution, dtype, audio payload, and exact-duration assembly were preserved. User visual comparison accepted the flicker reduction.
**Verdict:** PASS; Auto is the stable default.
## 9. Auto 2 status
**Coverage:** deterministic exposure-ramp tests and real-output comparisons including `00062`, `00064`, `00066`, `00070`, and `00071`.
**Result:** the controlled exposure-ramp path is covered and no-op/fallback behavior is safe. Real generations did not reliably produce a qualifying exposure-ramp boundary; in one comparison Auto and Auto 2 were pixel- and audio-identical because no exposure ramp was accepted.
**Verdict:** PARTIAL / EXPERIMENTAL. Use Auto first; try Auto 2 only when Auto leaves a gradual exposure ramp.
## 10. Known limitations
- Continuation improves temporal context but cannot guarantee identity, motion, detail, or audio quality for every checkpoint, LoRA, prompt, or source.
- Timeline Video is computationally expensive at Match Output; 0.4 MP is the recommended default.
- Native Reference Audio is conditioning, not sample-identical audio copying or guaranteed strict lip sync.
- Video Seam correction is deliberately guarded and may preserve a boundary when correction would be riskier.
- Auto 2 real exposure-ramp benefit is not yet broadly validated.
- Spectrum Actual Prefix 2 requires a compatible receiver and an acceptance log.
## 11. Release checks
- Python compileall
- Full pytest suite
- Runtime node-registration verifier
- Windows real-generation and decode/assembly runs listed above
The exact automated test count is recorded by the V3.3.0 release commit and GitHub Actions run.
+6 -3
View File
@@ -110,7 +110,8 @@ def _node(prompt: dict[str, Any], node_id: str, *, allowed: set[str], stack: set
def build_upstream_graph_contract(
prompt: Any, unique_id: Any, *, require_video_vae: bool
prompt: Any, unique_id: Any, *, require_video_vae: bool,
require_reference_audio_vae: bool = False,
) -> tuple[dict[str, Any], bool, list[str]]:
"""Fingerprint MODEL/CLIP/VAE routes feeding the Continuum sampler."""
if not isinstance(prompt, dict):
@@ -123,11 +124,13 @@ def build_upstream_graph_contract(
routes: dict[str, Any] = {}
safe = True
reasons: list[str] = []
specs = (
specs = [
("model", _KNOWN_MODEL_NODES, True),
("clip", _KNOWN_CLIP_NODES, True),
("video_vae", _KNOWN_VAE_NODES, bool(require_video_vae)),
)
]
if require_reference_audio_vae:
specs.append(("reference_audio_vae", _KNOWN_VAE_NODES, True))
for name, allowed, required in specs:
if not required:
continue
+1 -1
View File
@@ -1,4 +1,4 @@
[project]
name = H3 Continuum
version = 3.2.1
version = 3.3.0
description = Native MiniMax H3 continuation with Core VAE decode, Reference conditioning and crash-safe Run Storage.
+22 -12
View File
@@ -28,22 +28,32 @@ def _wrapper_factory(*, strict: bool, debug: bool) -> Callable[..., Any]:
def apply_model_wrapper(executor, *args, **kwargs):
payload = kwargs.get("minimax_payload")
if not payload_has_continuum(payload):
has_continuum = payload_has_continuum(payload)
has_mixed_keyframe_refs = (
isinstance(payload, dict)
and bool(payload.get("keyframes"))
and payload.get("refs") is not None
)
if not has_continuum and not has_mixed_keyframe_refs:
return executor(*args, **kwargs)
try:
ensure_native_h3_base_model(executor.class_obj)
patched_payload = dict(payload)
patch_layout_in_place(patched_payload, strict=True, debug=debug)
transformer_options = kwargs.get("transformer_options")
validate_native_continuity_layout(
patched_payload,
transformer_options=(
transformer_options if isinstance(transformer_options, dict) else {}
),
branch_baselines=branch_baselines,
)
input_x = args[0] if args else None
materialize_continuum_latents(patched_payload, input_x, debug=debug)
if has_continuum:
patch_layout_in_place(patched_payload, strict=True, debug=debug)
transformer_options = kwargs.get("transformer_options")
validate_native_continuity_layout(
patched_payload,
transformer_options=(
transformer_options if isinstance(transformer_options, dict) else {}
),
branch_baselines=branch_baselines,
)
input_x = args[0] if args else None
materialize_continuum_latents(patched_payload, input_x, debug=debug)
# ComfyUI Core 0.33.1 replaces keyframe condition latents with
# reference latents when both contracts are present. Rebuild the
# combined list for First/Last Frame + standalone Reference Audio.
normalize_condition_latents(patched_payload)
kwargs["minimax_payload"] = patched_payload
except (CompatibilityError, LayoutCompatibilityError, KeyError, TypeError, ValueError) as exc:
+3
View File
@@ -378,7 +378,10 @@ NODE_DISPLAY_NAME_MAPPINGS.update(V3_NODE_DISPLAY_NAME_MAPPINGS)
# ComfyUI's native deprecated-node filter hides legacy building blocks.
_primary_node_ids = {
"H3ContinuumSamplerProduction",
"H3ContinuumSamplerTimelineVideo",
"H3ContinuumAssembleV3",
"H3ContinuumAssembleSeamExperimental",
"H3ContinuumSeamTestSource",
"H3ContinuumClipOverrides",
"H3ContinuumResult",
}
+3 -3
View File
@@ -1,10 +1,10 @@
[project]
name = "comfyui-h3-continuum"
version = "3.2.1"
version = "3.3.0"
description = "Integrated N-chunk continuation for ComfyUI native MiniMax H3 video and audio"
readme = "README.md"
requires-python = ">=3.10"
license = { text = "MIT" }
license = { file = "LICENSE" }
authors = [{ name = "ukr8b3g-cmyk" }]
dependencies = []
keywords = ["comfyui", "minimax-h3", "video", "audio", "continuation"]
@@ -15,4 +15,4 @@ Repository = "https://github.com/ukr8b3g-cmyk/ComfyUI-H3-Continuum"
[tool.comfy]
PublisherId = "ukr8b3g-cmyk"
DisplayName = "H3 Continuum"
Icon = ""
requires-comfyui = ">=0.32.0"
+59 -18
View File
@@ -17,6 +17,7 @@ import torch
REFERENCE_CONTRACT_VERSION = 1
REFERENCE_PREPROCESS_VERSION = 1
REFERENCE_SIZE_MATCH_OUTPUT = "Match Output"
REFERENCE_SIZE_MAX_IDENTITY = "Max Identity"
REFERENCE_SIZE_OPTIONS = (
@@ -46,13 +47,26 @@ class ReferenceAssets:
@property
def contract(self) -> dict[str, Any]:
return {
result = {
"reference_contract_version": REFERENCE_CONTRACT_VERSION,
"count": self.count,
"size_mode": self.size_mode,
"image_hashes": list(self.image_hashes),
"combined_hash": self.combined_hash,
}
# Preserve the V3.2.2 JSON contract byte-for-byte for zero, one, and
# two references. The V3.2.3 extension exists only when Image 3 is
# connected, so removing it can resolve back to an older Revision.
if self.count == 3:
image = self.images[2]
result["reference_image_3"] = {
"reference_position": 3,
"shape": [int(value) for value in image.shape],
"dtype": str(image.dtype),
"sha256": self.image_hashes[2],
"preprocess_version": REFERENCE_PREPROCESS_VERSION,
}
return result
def _canonical_hash(value: Any) -> str:
@@ -133,16 +147,18 @@ def prepare_reference_assets(
output_width: int,
output_height: int,
size_mode: str,
reference_image_3: torch.Tensor | None = None,
) -> ReferenceAssets | None:
if reference_image_1 is None:
if reference_image_2 is not None:
raise ReferenceConditioningError(
"Reference Image 2 requires Reference Image 1"
)
# Match Core's dynamic Reference inputs: bypassed or otherwise absent
# sockets are ignored, then active images are numbered contiguously in
# connection order as Picture 1..N.
inputs = [
image
for image in (reference_image_1, reference_image_2, reference_image_3)
if image is not None
]
if not inputs:
return None
inputs = [reference_image_1]
if reference_image_2 is not None:
inputs.append(reference_image_2)
images = tuple(
_resize_reference(
_validate_image(f"Reference Image {index}", image),
@@ -181,24 +197,37 @@ def validate_reference_prompts(prompts: list[str], reference_count: int) -> str:
for prompt in prompts:
found.update(int(value) for value in _PICTURE_TAG.findall(str(prompt)))
invalid = sorted(value for value in found if value < 1 or value > reference_count)
warnings: list[str] = []
if invalid:
raise ReferenceConditioningError(
f"Prompt references unavailable <Picture {invalid[0]}>; "
f"connected reference count is {reference_count}"
unavailable = ", ".join(f"<Picture {value}>" for value in invalid)
warnings.append(
f"H3C-P102 Warning: prompt references unavailable {unavailable}; only "
f"{reference_count} active reference image(s) reached the Sampler. "
"ComfyUI Core permits this and generation will continue, but the "
"unavailable reference may be ignored or hallucinated. Enable the "
"corresponding Reference Image input or remove the unavailable tag."
)
if not found:
return (
"Reference images are connected but the prompt contains no "
"<Picture N> tag; images still condition generation, but explicit "
"identity references are recommended."
missing = sorted(set(range(1, reference_count + 1)) - found)
if missing:
labels = ", ".join(f"<Picture {value}>" for value in missing)
detail = (
"the prompt contains no <Picture N> tag"
if not found
else f"connected reference {labels} is not explicitly mentioned in the prompt"
)
return ""
warnings.append(
f"H3C-P103 Warning: {detail}; images still condition generation, but "
"explicit identity references are recommended."
)
return "\n".join(warnings)
def encode_reference_prompt(
clip: Any,
prompt: str,
assets: ReferenceAssets,
reference_audio_assets=None,
timeline_video_assets=None,
) -> list[list[Any]]:
if any(latent is None for latent in assets.latents):
raise ReferenceConditioningError("reference latents were not encoded")
@@ -206,6 +235,12 @@ def encode_reference_prompt(
{"type": "image", "data": image}
for image in assets.images
]
if timeline_video_assets is not None:
reference_items.append(dict(timeline_video_assets.item))
if reference_audio_assets is not None:
from .reference_audio import reference_audio_item
reference_items.append(reference_audio_item())
try:
tokens = clip.tokenize(str(prompt), minimax_ref_items=reference_items)
except TypeError as exc:
@@ -223,6 +258,12 @@ def encode_reference_prompt(
"latent": latent,
}
)
if timeline_video_assets is not None:
refs.append(dict(timeline_video_assets.block))
if reference_audio_assets is not None:
from .reference_audio import reference_audio_block
refs.append(reference_audio_block(reference_audio_assets))
return [
[tensor, {**dict(metadata), "minimax_refs": list(refs)}]
for tensor, metadata in conditioning
+242
View File
@@ -0,0 +1,242 @@
"""MiniMax H3 standalone audio-reference adapter for the V3 sampler."""
from __future__ import annotations
from dataclasses import dataclass
import hashlib
import json
import re
from typing import Any
import torch
REFERENCE_AUDIO_CONTRACT_VERSION = 1
REFERENCE_AUDIO_PREPROCESS_VERSION = 1
_AUDIO_TAG = re.compile(r"<Audio\s+(\d+)>")
class ReferenceAudioError(ValueError):
pass
@dataclass(frozen=True)
class ReferenceAudioSource:
waveform: torch.Tensor
source_sample_rate: int
source_shape: tuple[int, ...]
source_dtype: str
source_sha256: str
resolved_vae_sample_rate: int
resampled_shape: tuple[int, ...]
resampled_dtype: str
resampled_sha256: str
combined_hash: str
@property
def contract(self) -> dict[str, Any]:
return {
"reference_audio_contract_version": REFERENCE_AUDIO_CONTRACT_VERSION,
"source_sample_rate": self.source_sample_rate,
"source_shape": list(self.source_shape),
"source_dtype": self.source_dtype,
"source_sha256": self.source_sha256,
"resolved_vae_sample_rate": self.resolved_vae_sample_rate,
"resampled_shape": list(self.resampled_shape),
"resampled_dtype": self.resampled_dtype,
"resampled_sha256": self.resampled_sha256,
"preprocess_version": REFERENCE_AUDIO_PREPROCESS_VERSION,
"combined_hash": self.combined_hash,
}
@dataclass(frozen=True)
class ReferenceAudioAssets:
source: ReferenceAudioSource
audio_latent: torch.Tensor
@property
def combined_hash(self) -> str:
return self.source.combined_hash
def _canonical_hash(value: Any) -> str:
payload = json.dumps(
value, sort_keys=True, separators=(",", ":"), ensure_ascii=True
).encode("utf-8")
return hashlib.sha256(payload).hexdigest()
def _tensor_hash(value: torch.Tensor) -> str:
tensor = value.detach().to(device="cpu").contiguous()
digest = hashlib.sha256()
digest.update(str(tuple(int(v) for v in tensor.shape)).encode("ascii"))
digest.update(str(tensor.dtype).encode("ascii"))
digest.update(tensor.view(torch.uint8).numpy().tobytes(order="C"))
return digest.hexdigest()
def _validate_waveform(name: str, waveform: Any) -> torch.Tensor:
if not torch.is_tensor(waveform) or waveform.ndim != 3:
raise ReferenceAudioError(f"{name} waveform must have shape [B, C, L]")
if int(waveform.shape[0]) != 1:
raise ReferenceAudioError(f"{name} waveform batch size must be exactly 1")
if int(waveform.shape[1]) < 1 or int(waveform.shape[2]) < 1:
raise ReferenceAudioError(f"{name} waveform must contain channels and samples")
if not waveform.is_floating_point():
raise ReferenceAudioError(f"{name} waveform must use a floating-point dtype")
if not bool(torch.isfinite(waveform).all().item()):
raise ReferenceAudioError(f"{name} waveform contains NaN or infinity")
return waveform.detach().to(device="cpu").contiguous()
def prepare_reference_audio_source(
reference_audio_1: Any,
reference_audio_vae: Any,
) -> ReferenceAudioSource | None:
if reference_audio_1 is None:
return None
if reference_audio_vae is None:
raise ReferenceAudioError(
"reference_audio_vae is required when reference_audio_1 is connected"
)
if not isinstance(reference_audio_1, dict):
raise ReferenceAudioError("Reference Audio 1 must be a ComfyUI AUDIO value")
waveform = _validate_waveform(
"Reference Audio 1", reference_audio_1.get("waveform")
)
sample_rate_value = reference_audio_1.get("sample_rate")
if isinstance(sample_rate_value, bool):
raise ReferenceAudioError("Reference Audio 1 sample_rate must be positive")
try:
source_sample_rate = int(sample_rate_value)
except (TypeError, ValueError) as exc:
raise ReferenceAudioError(
"Reference Audio 1 sample_rate must be positive"
) from exc
if source_sample_rate <= 0:
raise ReferenceAudioError("Reference Audio 1 sample_rate must be positive")
resolved_rate = int(getattr(reference_audio_vae, "audio_sample_rate", 32000))
if resolved_rate <= 0:
raise ReferenceAudioError("Reference Audio VAE sample rate must be positive")
resampled = waveform
if source_sample_rate != resolved_rate:
try:
import torchaudio
resampled = torchaudio.functional.resample(
waveform, source_sample_rate, resolved_rate
).contiguous()
except Exception as exc:
raise ReferenceAudioError(
"Reference Audio 1 could not be resampled for the Audio VAE"
) from exc
if not bool(torch.isfinite(resampled).all().item()):
raise ReferenceAudioError(
"Reference Audio 1 contains NaN or infinity after resampling"
)
source_shape = tuple(int(value) for value in waveform.shape)
resampled_shape = tuple(int(value) for value in resampled.shape)
source_sha256 = _tensor_hash(waveform)
resampled_sha256 = _tensor_hash(resampled)
contract_base = {
"reference_audio_contract_version": REFERENCE_AUDIO_CONTRACT_VERSION,
"source_sample_rate": source_sample_rate,
"source_shape": list(source_shape),
"source_dtype": str(waveform.dtype),
"source_sha256": source_sha256,
"resolved_vae_sample_rate": resolved_rate,
"resampled_shape": list(resampled_shape),
"resampled_dtype": str(resampled.dtype),
"resampled_sha256": resampled_sha256,
"preprocess_version": REFERENCE_AUDIO_PREPROCESS_VERSION,
}
return ReferenceAudioSource(
waveform=resampled,
source_sample_rate=source_sample_rate,
source_shape=source_shape,
source_dtype=str(waveform.dtype),
source_sha256=source_sha256,
resolved_vae_sample_rate=resolved_rate,
resampled_shape=resampled_shape,
resampled_dtype=str(resampled.dtype),
resampled_sha256=resampled_sha256,
combined_hash=_canonical_hash(contract_base),
)
def encode_reference_audio(
reference_audio_vae: Any,
source: ReferenceAudioSource,
) -> ReferenceAudioAssets:
try:
latent = reference_audio_vae.encode(source.waveform.movedim(1, -1))
except Exception as exc:
raise ReferenceAudioError("Reference Audio VAE Encode failed") from exc
if (
not torch.is_tensor(latent)
or latent.ndim != 4
or int(latent.shape[0]) != 1
or int(latent.shape[1]) != 32
or int(latent.shape[2]) != 2
or int(latent.shape[3]) < 1
):
raise ReferenceAudioError(
"Reference Audio VAE must produce latent shape [1, 32, 2, T]"
)
if not bool(torch.isfinite(latent).all().item()):
raise ReferenceAudioError("Reference Audio latent contains NaN or infinity")
return ReferenceAudioAssets(source=source, audio_latent=latent)
def validate_reference_audio_prompts(
prompts: list[str], source: ReferenceAudioSource | None
) -> str:
found: set[int] = set()
for prompt in prompts:
found.update(int(value) for value in _AUDIO_TAG.findall(str(prompt)))
warnings: list[str] = []
active_count = 1 if source is not None else 0
unavailable = sorted(
value for value in found if source is None or value != 1
)
for value in unavailable:
warnings.append(
f"H3C-P102 Warning: prompt references unavailable <Audio {value}>; only "
f"{active_count} active reference audio item(s) reached the Sampler. "
"Core-compatible generation will continue; the tag may be ignored "
"or hallucinated."
)
if source is not None and 1 not in found:
warnings.append(
"H3C-P103 Warning: Reference Audio 1 is connected but the prompt contains no <Audio 1> "
"tag; audio still conditions generation, but an explicit tag is recommended."
)
return "\n".join(warnings)
def combine_reference_audio_identity(
visual_identity_hash: str,
source: ReferenceAudioSource | None,
) -> str:
if source is None:
return str(visual_identity_hash)
return _canonical_hash(
{
"reference_audio_identity_version": 1,
"visual_identity_hash": str(visual_identity_hash),
"reference_audio_hash": source.combined_hash,
}
)
def reference_audio_item() -> dict[str, str]:
return {"type": "audio"}
def reference_audio_block(assets: ReferenceAudioAssets) -> dict[str, Any]:
return {
"kind": "audio",
"ref_audio_t": int(assets.audio_latent.shape[-1]),
"audio_latent": assets.audio_latent,
}
+75 -4
View File
@@ -126,6 +126,16 @@ def automatic_project_key(prompt: Any, unique_id: Any) -> str:
next_stack.add(current_id)
if isinstance(inputs, dict):
for name in sorted(inputs):
if current_id == node_id and name == "reference_audio_vae":
audio_link = inputs.get("reference_audio_1")
if not (
isinstance(audio_link, (list, tuple))
and len(audio_link) == 2
and isinstance(audio_link[0], (str, int))
and isinstance(audio_link[1], int)
and str(audio_link[0]) in prompt
):
continue
value = inputs[name]
if (
isinstance(value, (list, tuple))
@@ -468,6 +478,26 @@ def _video_vae_signature(video_vae: Any, *, required: bool) -> tuple[dict[str, A
return observed, module_safe
def _audio_vae_signature(audio_vae: Any) -> tuple[dict[str, Any], bool]:
first_stage = getattr(audio_vae, "first_stage_model", None)
module_value, module_safe = _module_signature(first_stage)
patcher_value, patcher_safe = _patcher_signature(getattr(audio_vae, "patcher", None))
config = {
"wrapper_type": _qualified(audio_vae),
"first_stage": module_value,
"patcher": patcher_value,
"vae_dtype": str(getattr(audio_vae, "vae_dtype", "unknown")),
"audio_sample_rate": getattr(audio_vae, "audio_sample_rate", 32000),
"latent_channels": getattr(audio_vae, "latent_channels", None),
}
observed, config_safe = _observe(config)
observed["runtime_observation"] = {
"patcher_complete": bool(patcher_safe),
"config_complete": bool(config_safe),
}
return observed, module_safe
def _apply_nonce_contract(
contract: dict[str, Any], *, requested_nonce: int, effective_nonce: int,
) -> dict[str, Any]:
@@ -493,6 +523,9 @@ def _apply_nonce_contract(
"effective_reroll_nonce": int(effective_nonce) if affected else 0,
"last_frame_hash": str(result["last_frame_hash"]) if number == int(result["chunk_count"]) else "",
}
timeline_chunks = result.get("timeline_video_chunk_contracts") or []
if position < len(timeline_chunks):
chunk_contract["timeline_video"] = dict(timeline_chunks[position])
chunk_contracts.append(chunk_contract)
chunk_hashes.append(_hash(chunk_contract))
result.update(
@@ -522,6 +555,9 @@ def build_sampling_contract(
upstream_graph_contract: dict[str, Any] | None = None,
upstream_graph_safe: bool | None = None,
upstream_graph_reasons: list[str] | None = None,
reference_audio_contract: dict[str, Any] | None = None,
reference_audio_vae: Any = None,
timeline_video_contract: dict[str, Any] | None = None,
) -> tuple[dict[str, Any], bool, list[str]]:
model_value, model_safe = _model_signature(model, model_fingerprint_value)
clip_value, clip_safe = _clip_signature(clip)
@@ -538,7 +574,10 @@ def build_sampling_contract(
"conditioning mode does not match the connected image inputs: "
f"declared={conditioning_mode}, inferred={inferred_mode}"
)
uses_video_vae = conditioning_mode_uses_video_vae(conditioning_mode)
uses_video_vae = (
conditioning_mode_uses_video_vae(conditioning_mode)
or timeline_video_contract is not None
)
if uses_video_vae:
video_vae_value, video_vae_safe = _video_vae_signature(
video_vae, required=True
@@ -546,6 +585,10 @@ def build_sampling_contract(
else:
video_vae_value, video_vae_safe = None, True
sampler_value, sampler_safe = _sampler_signature(sampler)
if reference_audio_contract is not None:
audio_vae_value, audio_vae_safe = _audio_vae_signature(reference_audio_vae)
else:
audio_vae_value, audio_vae_safe = None, True
if not torch.is_tensor(sigmas) or sigmas.ndim != 1:
raise RunStorageError("Run Storage requires a one-dimensional SIGMAS tensor")
chunks = int(prompt_plan["chunks"])
@@ -567,6 +610,11 @@ def build_sampling_contract(
"runtime": video_vae_value,
"graph_route": routes.get("video_vae"),
}
if reference_audio_contract is not None:
audio_vae_value = {
"runtime": audio_vae_value,
"graph_route": routes.get("reference_audio_vae"),
}
global_contract = {
"sampling_contract_version": SAMPLING_CONTRACT_VERSION,
"conditioning_mode": conditioning_mode,
@@ -591,12 +639,25 @@ def build_sampling_contract(
global_contract["first_frame_hash"] = str(first_frame_hash)
if reference_contract is not None:
global_contract["reference"] = dict(reference_contract)
if reference_audio_contract is not None:
global_contract["reference_audio"] = dict(reference_audio_contract)
global_contract["reference_audio_vae"] = audio_vae_value
timeline_chunk_contracts = []
if timeline_video_contract is not None:
timeline_value = dict(timeline_video_contract)
timeline_chunk_contracts = list(timeline_value.pop("chunk_slices", []))
if len(timeline_chunk_contracts) != chunks:
raise RunStorageError(
"Timeline Video contract does not match the configured chunk count"
)
global_contract["timeline_video"] = timeline_value
lineage_sha256 = _hash({
"global_hash": _hash(global_contract),
"chunk_count": chunks,
"prompt_mode": str(prompt_plan["mode"]),
"prompt_hashes": prompt_hashes,
"last_frame_hash": str(last_frame_hash),
"timeline_video_chunk_contracts": timeline_chunk_contracts,
})
contract = {
"global": global_contract,
@@ -625,8 +686,10 @@ def build_sampling_contract(
reasons.append("CLIP/Qwen encoder contract is not completely observable")
if not video_vae_safe:
reasons.append("Video VAE contract is not completely observable")
if not audio_vae_safe:
reasons.append("Reference Audio VAE contract is not completely observable")
graph_safe = bool(upstream_graph_safe) if graph_authoritative else True
return contract, model_safe and clip_safe and video_vae_safe and sampler_safe and graph_safe, reasons
return contract, model_safe and clip_safe and video_vae_safe and audio_vae_safe and sampler_safe and graph_safe, reasons
def revision_identity(contract: dict[str, Any]) -> tuple[str, str]:
@@ -898,6 +961,9 @@ class RunStorageController:
existing_session: dict[str, Any] | None,
reference_contract: dict[str, Any] | None = None,
conditioning_mode: str | None = None,
reference_audio_contract: dict[str, Any] | None = None,
reference_audio_vae: Any = None,
timeline_video_contract: dict[str, Any] | None = None,
) -> dict[str, Any] | None:
if existing_session is not None:
raise RunStorageError("Run Storage cannot be combined with an explicit Session")
@@ -906,9 +972,11 @@ class RunStorageController:
graph_contract, graph_safe, graph_reasons = build_upstream_graph_contract(
self.prompt_graph,
self.sampler_node_id,
require_video_vae=conditioning_mode_uses_video_vae(
str(conditioning_mode)
require_video_vae=(
conditioning_mode_uses_video_vae(str(conditioning_mode))
or timeline_video_contract is not None
),
require_reference_audio_vae=reference_audio_contract is not None,
)
contract, safe, reasons = build_sampling_contract(
model=model, model_fingerprint_value=model_fingerprint_value,
@@ -925,6 +993,9 @@ class RunStorageController:
upstream_graph_contract=graph_contract,
upstream_graph_safe=graph_safe,
upstream_graph_reasons=graph_reasons,
reference_audio_contract=reference_audio_contract,
reference_audio_vae=reference_audio_vae,
timeline_video_contract=timeline_video_contract,
)
effective_nonce, nonce_decision = self._resolve_effective_nonce(
contract, requested_nonce=int(reroll_nonce), resume_safe=safe
+24
View File
@@ -81,6 +81,30 @@ def test_apply_model_wrapper_repairs_payload_before_executor():
assert torch.equal(result["layout"].position_ids[3:4], result["layout"].position_ids[6:7])
def test_apply_model_wrapper_repairs_keyframes_with_audio_reference_without_continuum():
first = torch.zeros(1, 24, 1, 1, 1)
last = torch.ones(1, 24, 1, 1, 1)
audio = torch.zeros(1, 32, 2, 1)
payload = {
"keyframes": [
{"resolved_frame_index": 0, "latent": first},
{"resolved_frame_index": 4, "latent": last},
],
"refs": [
{"kind": "audio", "ref_audio_t": 1, "audio_latent": audio}
],
# ComfyUI Core 0.33.1 overwrites this list while processing refs.
"cond_video_latents": [],
"cond_audio_latents": [audio],
}
wrapper = _wrapper_factory(strict=True, debug=False)
result = wrapper(Executor(), torch.zeros(1), minimax_payload=payload)
assert result["cond_video_latents"] == [first, last]
assert result["cond_audio_latents"] == [audio]
def test_apply_model_wrapper_fails_when_actual_topology_changes():
video = torch.zeros(1, 24, 1, 1, 1)
audio = torch.zeros(1, 32, 2, 1)
+210
View File
@@ -0,0 +1,210 @@
from __future__ import annotations
import io
from types import SimpleNamespace
import torch
from ComfyUI_H3_Continuum_Join.timeline_video import (
TIMELINE_VIDEO_SIZE_BALANCED,
TIMELINE_VIDEO_SIZE_EFFICIENT,
TIMELINE_VIDEO_SIZE_MATCH_OUTPUT,
combine_timeline_video_identity,
encode_timeline_video_chunk,
prepare_timeline_video_source,
validate_timeline_video_prompts,
)
from ComfyUI_H3_Continuum_Join.v3.nodes import (
H3ContinuumSamplerProduction,
H3ContinuumSamplerTimelineVideo,
)
class _Trimmed:
def __init__(self, frames):
self.frames = frames
def get_components(self):
return SimpleNamespace(images=self.frames, audio=None, frame_rate=24.0)
class _Video:
def __init__(self, frames, duration=10.0, width=32, height=32):
self.frames = frames
self.duration = duration
self.width = width
self.height = height
self.calls = []
self.stream = io.BytesIO(b"timeline-video-test")
def get_duration(self):
return self.duration
def get_dimensions(self):
return self.width, self.height
def get_stream_source(self):
return self.stream
def as_trimmed(self, start_time=0, duration=0, strict_duration=True):
self.calls.append((start_time, duration, strict_duration))
return _Trimmed(self.frames)
class _VAE:
def __init__(self):
self.calls = []
def encode(self, frames):
self.calls.append(frames)
return torch.zeros((1, 24, 8, 2, 2))
def _source(size_mode=TIMELINE_VIDEO_SIZE_MATCH_OUTPUT):
video = _Video(torch.zeros((120, 32, 32, 3)))
source = prepare_timeline_video_source(
video,
chunks=2,
chunk_seconds=5.0,
output_width=32,
output_height=32,
size_mode=size_mode,
)
return video, source
def test_timeline_node_is_separate_and_stable_schema_is_unchanged():
stable = H3ContinuumSamplerProduction.INPUT_TYPES()
experimental = H3ContinuumSamplerTimelineVideo.INPUT_TYPES()
assert "timeline_video" not in stable["required"]
assert "timeline_video_size" not in stable["required"]
assert "timeline_video" not in experimental["required"]
assert experimental["optional"]["timeline_video"][0] == "VIDEO"
def test_timeline_node_without_video_delegates_to_stable_engine(monkeypatch):
calls = []
def fake_run(self, **kwargs):
calls.append(kwargs)
return "stable"
monkeypatch.setattr(H3ContinuumSamplerProduction, "run", fake_run)
result = H3ContinuumSamplerTimelineVideo().run(
timeline_video=None,
timeline_video_size="Efficient - 0.4 MP",
marker="no-video",
)
assert result == "stable"
assert calls == [{"marker": "no-video"}]
def test_timeline_node_with_video_prepares_source(monkeypatch):
video = object()
source = object()
prepared = []
delegated = []
def fake_prepare(value, **kwargs):
prepared.append((value, kwargs))
return source
def fake_run(self, **kwargs):
delegated.append(kwargs)
return "timeline"
monkeypatch.setattr(
"ComfyUI_H3_Continuum_Join.timeline_video.prepare_timeline_video_source",
fake_prepare,
)
monkeypatch.setattr(H3ContinuumSamplerProduction, "run", fake_run)
result = H3ContinuumSamplerTimelineVideo().run(
timeline_video=video,
timeline_video_size="Efficient - 0.4 MP",
chunks=2,
chunk_seconds=5.0,
width=800,
height=800,
)
assert result == "timeline"
assert prepared == [
(
video,
{
"chunks": 2,
"chunk_seconds": 5.0,
"output_width": 800,
"output_height": 800,
"size_mode": "Efficient - 0.4 MP",
},
)
]
assert delegated == [
{
"timeline_video_source": source,
"chunks": 2,
"chunk_seconds": 5.0,
"width": 800,
"height": 800,
}
]
def test_timeline_contract_is_deterministic_and_chunked():
_, first = _source()
_, second = _source()
assert first.contract == second.contract
assert len(first.contract["chunk_slices"]) == 2
assert first.contract["chunk_slices"][1]["start_seconds"] == 5.0
def test_efficient_mode_resolves_about_point_four_megapixels():
video = _Video(torch.zeros((120, 1080, 1920, 3)), width=1920, height=1080)
source = prepare_timeline_video_source(
video,
chunks=1,
chunk_seconds=5.0,
output_width=1344,
output_height=768,
size_mode=TIMELINE_VIDEO_SIZE_EFFICIENT,
)
assert 350_000 <= source.target_width * source.target_height <= 450_000
def test_balanced_mode_resolves_about_point_six_megapixels():
video = _Video(torch.zeros((120, 1080, 1920, 3)), width=1920, height=1080)
source = prepare_timeline_video_source(
video,
chunks=1,
chunk_seconds=5.0,
output_width=1344,
output_height=768,
size_mode=TIMELINE_VIDEO_SIZE_BALANCED,
)
assert 550_000 <= source.target_width * source.target_height <= 650_000
def test_encode_processes_only_requested_chunk_and_builds_core_payload():
video, source = _source()
vae = _VAE()
assets = encode_timeline_video_chunk(vae, source, 1)
assert video.calls == [(5.0, 5.0, False)]
assert len(vae.calls) == 1
assert int(vae.calls[0].shape[0]) % 17 == 5
assert assets.item["type"] == "video"
assert assets.block["kind"] == "video"
assert assets.block["ref_audio_t"] == 0
def test_timeline_identity_is_noop_when_absent_and_changes_when_present():
_, source = _source()
assert combine_timeline_video_identity("visual", None) == "visual"
assert combine_timeline_video_identity("visual", source) != "visual"
def test_missing_video_tag_warns_without_stopping():
_, source = _source()
assert "H3C-P103" in validate_timeline_video_prompts(["A dancer moves."], source)
assert validate_timeline_video_prompts(["Follow <Video 1>."], source) == ""
+1 -1
View File
@@ -139,4 +139,4 @@ def test_v217_result_pack_expands_legacy_outputs():
def test_v217_has_no_frontend_display_controller():
assert not (ROOT / "web" / "h3_continuum_v2.js").exists()
version_source = (ROOT / "version.py").read_text(encoding="utf-8")
assert 'PACKAGE_VERSION = "3.2.1"' in version_source
assert 'PACKAGE_VERSION = "3.3.0"' in version_source
+89 -3
View File
@@ -14,6 +14,7 @@ from ComfyUI_H3_Continuum_Join.v2.prompts import (
detect_prompt_mode,
make_prompt_plan,
parse_sparse_prompt_overrides,
prompt_plan_report,
validate_sparse_prompt_overrides,
validate_prompt_plan,
)
@@ -72,14 +73,94 @@ def test_timeline_prompt_maps_ranges_and_chunk_headers():
assert plan["prompts"] == ["one", "two", "three"]
def test_timeline_requires_coverage():
with pytest.raises(PromptPlanError):
def test_timeline_preamble_is_applied_to_every_chunk():
plan = make_prompt_plan(
mode=PROMPT_FORMAT_AUTO,
script="Refer to <Picture 1>.\n[0-5s]\none\n[5-10s]\ntwo",
chunks=2,
chunk_seconds=5,
)
assert plan["prompts"] == ["Refer to <Picture 1>.\n\none", "Refer to <Picture 1>.\n\ntwo"]
assert plan["notes"] == ["Auto detected Timeline", "applied timeline preamble to all chunks"]
def test_timeline_missing_coverage_warns_and_repeats_previous_prompt():
plan = make_prompt_plan(
mode=PROMPT_MODE_TIMELINE,
script="[0-5s]\none",
chunks=2,
chunk_seconds=5,
)
assert plan["prompts"] == ["one", "one"]
assert any(item["code"] == "H3C-P101" for item in plan["diagnostics"])
assert "fallback" in prompt_plan_report(plan)
def test_timeline_leading_gap_uses_earliest_valid_prompt():
plan = make_prompt_plan(
mode=PROMPT_MODE_TIMELINE,
script="[5-10s]\nsecond",
chunks=2,
chunk_seconds=5,
)
assert plan["prompts"] == ["second", "second"]
assert plan["diagnostics"][0]["code"] == "H3C-P101"
def test_timeline_extra_sections_warn_and_are_ignored():
plan = make_prompt_plan(
mode=PROMPT_MODE_TIMELINE,
script="[0-5s]\none\n[5-10s]\ntwo\n[10-15s]\nextra",
chunks=2,
chunk_seconds=5,
)
assert plan["prompts"] == ["one", "two"]
assert any(item["code"] == "H3C-P104" for item in plan["diagnostics"])
@pytest.mark.parametrize(
("script", "code"),
[
("[0 to 5s]\none", "H3C-P001"),
("[5-5s]\none", "H3C-P002"),
("[Chunk 0]\none", "H3C-P004"),
("[0-5s]\n", "H3C-P005"),
],
)
def test_invalid_timeline_reports_actionable_diagnostic(script, code):
with pytest.raises(PromptPlanError) as captured:
make_prompt_plan(
mode=PROMPT_MODE_TIMELINE,
script="[0-5s]\none",
script=script,
chunks=2,
chunk_seconds=5,
)
message = str(captured.value)
assert code in message
assert "Suggested fix:" in message
def test_duplicate_chunk_section_is_an_error():
with pytest.raises(PromptPlanError, match="H3C-P003"):
make_prompt_plan(
mode=PROMPT_MODE_TIMELINE,
script="[Chunk 1]\none\n[Chunk 1]\ntwo",
chunks=2,
chunk_seconds=5,
)
def test_prompt_preflight_reports_explicit_chunk_sources():
plan = make_prompt_plan(
mode=PROMPT_MODE_TIMELINE,
script="[0-5s]\none\n[5-10s]\ntwo",
chunks=2,
chunk_seconds=5,
)
report = prompt_plan_report(plan)
assert "Prompt Preflight:" in report
assert "Chunk 1 source:" in report
assert "Chunk 2 source:" in report
def test_native_h3_chunk_duration_rejects_sub_four_seconds():
@@ -148,3 +229,8 @@ def test_sparse_override_rejects_out_of_range_clip():
def test_sparse_override_rejects_duplicate_clip():
with pytest.raises(PromptPlanError, match="more than once"):
parse_sparse_prompt_overrides("[Clip 2]\nfirst\n\n[Chunk 2]\nsecond")
def test_sparse_override_rejects_timeline_preamble():
with pytest.raises(PromptPlanError, match="before the first"):
parse_sparse_prompt_overrides("global text\n[Clip 1]\nopening override")
+37 -1
View File
@@ -3,7 +3,7 @@ import hashlib
import torch
from ComfyUI_H3_Continuum_Join.constants import CONTINUUM_INTEROP_KEY, DIAGNOSTICS_BASIC, PROMPT_MODE_FIXED, V2_CONTINUITY_OPTIONS
from ComfyUI_H3_Continuum_Join.temporal import audio_latent_t, video_latent_t
from ComfyUI_H3_Continuum_Join.v2.h3_builder import IdentityAssets, _tensor_fingerprint
from ComfyUI_H3_Continuum_Join.v2.h3_builder import IdentityAssets, _tensor_fingerprint, encode_prompt_conditioning
from ComfyUI_H3_Continuum_Join.v2.prompts import make_prompt_plan
from ComfyUI_H3_Continuum_Join.v2 import sequence
@@ -19,6 +19,18 @@ class FakeClip:
def encode_from_tokens_scheduled(self,tokens): self.events.append(("encode",tokens)); return [[torch.zeros(1,1,2),{}]]
class ReferenceAudioClip:
def __init__(self):
self.tokenize_options = None
def tokenize(self, prompt, **kwargs):
self.tokenize_options = kwargs
return prompt
def encode_from_tokens_scheduled(self, tokens):
return [[torch.zeros(1, 1, 2), {}]]
def test_identity_fingerprint_hashes_full_resized_rgb_tensor():
image = torch.zeros((1, 96, 64, 3), dtype=torch.float32)
image[0, 95, 63, 2] = 1.0
@@ -28,6 +40,30 @@ def test_identity_fingerprint_hashes_full_resized_rgb_tensor():
digest.update(image.contiguous().view(torch.uint8).numpy().tobytes(order="C"))
assert _tensor_fingerprint(image) == digest.hexdigest()
def test_first_last_and_reference_audio_use_ordered_tokenizer_items_only():
first = torch.zeros((1, 32, 32, 3))
last = torch.ones((1, 32, 32, 3))
audio_latent = torch.zeros((1, 32, 2, 1))
clip = ReferenceAudioClip()
conditioning = encode_prompt_conditioning(
clip,
"Use <Picture 1>, <Picture 2>, and <Audio 1>.",
first_image=first,
last_image=last,
reference_audio_assets=SimpleNamespace(audio_latent=audio_latent),
)
items = clip.tokenize_options["minimax_ref_items"]
assert [item["type"] for item in items] == ["image", "image", "audio"]
assert items[0]["data"] is first
assert items[1]["data"] is last
assert "images" not in clip.tokenize_options
assert conditioning[0][1]["minimax_refs"] == [
{"kind": "audio", "ref_audio_t": 1, "audio_latent": audio_latent}
]
def test_v2_samples_every_chunk_before_any_decode(monkeypatch):
events=[]; width,height=96,64
fake_model=SimpleNamespace(model=SimpleNamespace(diffusion_model=SimpleNamespace()),model_options={},wrappers={},model_dtype=lambda:torch.bfloat16,model_size=lambda:0)
+62
View File
@@ -18,6 +18,10 @@ from ComfyUI_H3_Continuum_Join.run_storage import (
resolve_run_storage_name,
revision_identity,
)
from ComfyUI_H3_Continuum_Join.reference import (
REFERENCE_SIZE_MATCH_OUTPUT,
ReferenceAssets,
)
from ComfyUI_H3_Continuum_Join.graph_contract import (
CHECKPOINT_FL2VA,
CHECKPOINT_REF2VA,
@@ -311,6 +315,64 @@ def _sampling_contract(
)
def test_v322_golden_reference_contract_preserves_revision_identity():
model = _Model()
clip = _Clip()
video_vae = _VideoVAE()
sampler = _Sampler()
no_reference, safe, reasons = _sampling_contract(
model=model,
clip=clip,
video_vae=video_vae,
sampler=sampler,
conditioning_mode="t2va",
first_frame_hash="",
reference_contract=None,
)
assert safe, reasons
assert "reference" not in no_reference["global"]
for count in (1, 2):
hashes = tuple(str(index) * 64 for index in range(1, count + 1))
expected_reference = {
"reference_contract_version": 1,
"count": count,
"size_mode": REFERENCE_SIZE_MATCH_OUTPUT,
"image_hashes": list(hashes),
"combined_hash": "a" * 64,
}
actual_reference = ReferenceAssets(
images=tuple(torch.zeros((1, 32, 32, 3)) for _ in range(count)),
latents=tuple(None for _ in range(count)),
image_hashes=hashes,
combined_hash="a" * 64,
size_mode=REFERENCE_SIZE_MATCH_OUTPUT,
).contract
expected, expected_safe, expected_reasons = _sampling_contract(
model=model,
clip=clip,
video_vae=video_vae,
sampler=sampler,
conditioning_mode="reference",
first_frame_hash="",
reference_contract=expected_reference,
)
actual, actual_safe, actual_reasons = _sampling_contract(
model=model,
clip=clip,
video_vae=video_vae,
sampler=sampler,
conditioning_mode="reference",
first_frame_hash="",
reference_contract=actual_reference,
)
assert expected_safe, expected_reasons
assert actual_safe, actual_reasons
assert actual == expected
assert revision_identity(actual) == revision_identity(expected)
def test_clip_and_required_video_vae_are_part_of_sampling_contract():
clip = _Clip()
vae = _VideoVAE()
+126 -11
View File
@@ -10,6 +10,7 @@ from ComfyUI_H3_Continuum_Join.reference import (
prepare_reference_assets,
validate_reference_prompts,
)
from ComfyUI_H3_Continuum_Join.reference_audio import validate_reference_audio_prompts
from ComfyUI_H3_Continuum_Join.v3.nodes import _validate_reference_checkpoint
@@ -44,14 +45,52 @@ def test_reference_contract_contains_metadata_only():
assert not any(torch.is_tensor(value) for value in contract.values())
def test_picture_tags_must_match_connected_references():
@pytest.mark.parametrize("count", (1, 2))
def test_v322_reference_contract_json_is_golden_compatible(count):
hashes = [str(index) * 64 for index in range(1, count + 1)]
assert _assets(count).contract == {
"reference_contract_version": 1,
"count": count,
"size_mode": REFERENCE_SIZE_MATCH_OUTPUT,
"image_hashes": hashes,
"combined_hash": "a" * 64,
}
def test_v323_third_reference_adds_only_the_image_3_extension():
contract = _assets(3).contract
assert set(contract) == {
"reference_contract_version",
"count",
"size_mode",
"image_hashes",
"combined_hash",
"reference_image_3",
}
assert contract["reference_image_3"] == {
"reference_position": 3,
"shape": [1, 32, 32, 3],
"dtype": "torch.float32",
"sha256": "3" * 64,
"preprocess_version": 1,
}
def test_unavailable_picture_tags_warn_without_stopping_like_core():
assert validate_reference_prompts(["Use <Picture 1> and <Picture 2>."], 2) == ""
with pytest.raises(ReferenceConditioningError, match="Picture 2"):
validate_reference_prompts(["Use <Picture 2>."], 1)
message = validate_reference_prompts(["Use <Picture 2>."], 1)
assert "H3C-P102" in message
assert "only 1 active reference image(s) reached the Sampler" in message
assert "generation will continue" in message
assert "ignored or hallucinated" in message
message = validate_reference_prompts(["Use <Picture 3>."], 2)
assert "unavailable <Picture 3>" in message
assert "generation will continue" in message
def test_missing_picture_tag_is_a_warning_not_an_error():
warning = validate_reference_prompts(["The same person walks forward."], 1)
assert "H3C-P103" in warning
assert "no <Picture N> tag" in warning
@@ -66,6 +105,83 @@ def test_reference_socket_rejects_image_batches():
)
def test_reference_image_3_rejects_image_batches():
with pytest.raises(ReferenceConditioningError, match="batch size B=1"):
prepare_reference_assets(
reference_image_1=torch.zeros((1, 32, 32, 3)),
reference_image_2=torch.zeros((1, 32, 32, 3)),
reference_image_3=torch.zeros((2, 32, 32, 3)),
output_width=32,
output_height=32,
size_mode=REFERENCE_SIZE_MATCH_OUTPUT,
)
def test_three_reference_images_are_ordered_and_contiguous():
assets = prepare_reference_assets(
reference_image_1=torch.zeros((1, 32, 32, 3)),
reference_image_2=torch.ones((1, 32, 32, 3)),
reference_image_3=torch.full((1, 32, 32, 3), 0.5),
output_width=32,
output_height=32,
size_mode=REFERENCE_SIZE_MATCH_OUTPUT,
)
assert assets is not None
assert assets.count == 3
assert validate_reference_prompts(["Use <Picture 1>, <Picture 2>, and <Picture 3>."], 3) == ""
def test_reference_image_gaps_are_compacted_like_core():
first = torch.zeros((1, 32, 32, 3))
third = torch.ones((1, 32, 32, 3))
assets = prepare_reference_assets(
reference_image_1=first,
reference_image_2=None,
reference_image_3=third,
output_width=32,
output_height=32,
size_mode=REFERENCE_SIZE_MATCH_OUTPUT,
)
assert assets is not None
assert len(assets.images) == 2
assert torch.equal(assets.images[0], first)
assert torch.equal(assets.images[1], third)
def test_reference_image_2_alone_becomes_picture_1_like_core():
second = torch.ones((1, 32, 32, 3))
assets = prepare_reference_assets(
reference_image_1=None,
reference_image_2=second,
reference_image_3=None,
output_width=32,
output_height=32,
size_mode=REFERENCE_SIZE_MATCH_OUTPUT,
)
assert assets is not None
assert len(assets.images) == 1
assert torch.equal(assets.images[0], second)
def test_unavailable_audio_tags_warn_without_stopping_like_core():
message = validate_reference_audio_prompts(
["Perform <Audio 1> and <Audio 2>."], None
)
assert "unavailable <Audio 1>" in message
assert "H3C-P102" in message
assert "unavailable <Audio 2>" in message
assert "generation will continue" in message
def test_connected_audio_keeps_unavailable_extra_tag_as_warning():
message = validate_reference_audio_prompts(
["Perform <Audio 2>."], object()
)
assert "unavailable <Audio 2>" in message
assert "no <Audio 1> tag" in message
assert "H3C-P103" in message
def _reference_prompt(checkpoint_name: str) -> dict:
return {
"1": {
@@ -79,20 +195,19 @@ def _reference_prompt(checkpoint_name: str) -> dict:
}
def test_strict_reference_requires_ref2va_checkpoint():
def test_reference_checkpoint_classification_is_diagnostic_only():
assert _validate_reference_checkpoint(
_reference_prompt("minimax_h3_ref2va_pruned_int8.safetensors"),
"2",
strict_compatibility=True,
) == "ref2va"
with pytest.raises(ValueError, match="FL2VA checkpoint"):
_validate_reference_checkpoint(
_reference_prompt("minimax_h3_fl2va_pruned_int8.safetensors"),
"2",
strict_compatibility=True,
)
assert _validate_reference_checkpoint(
_reference_prompt("minimax_h3_fl2va_pruned_int8.safetensors"),
"2",
strict_compatibility=False,
strict_compatibility=True,
) == "fl2va"
assert _validate_reference_checkpoint(
_reference_prompt("minimax_h3_unknown.safetensors"),
"2",
strict_compatibility=True,
) == "unknown"
+96
View File
@@ -0,0 +1,96 @@
import torch
from ComfyUI_H3_Continuum_Join.constants import DIAGNOSTICS_OPTIONS
from ComfyUI_H3_Continuum_Join.v3.assembly import (
H3ContinuumAssembleSeamExperimental,
VIDEO_SEAM_ANALYZE,
VIDEO_SEAM_AUTO,
VIDEO_SEAM_AUTO_2,
)
from ComfyUI_H3_Continuum_Join.v3.nodes import NODE_CLASS_MAPPINGS
from ComfyUI_H3_Continuum_Join.v3.seam_test_source import (
H3ContinuumSeamTestSource,
TEST_SIZE_256,
)
from ComfyUI_H3_Continuum_Join.v3.video_seam import analyze_decoded_boundaries
def _source_outputs():
image = torch.full((1, 256, 256, 3), 0.5, dtype=torch.float32)
return H3ContinuumSeamTestSource().create(
image,
exposure_change=0.08,
test_resolution=TEST_SIZE_256,
)
def test_seam_test_source_is_registered():
assert NODE_CLASS_MAPPINGS["H3ContinuumSeamTestSource"] is H3ContinuumSeamTestSource
def test_seam_test_source_is_public_in_root_registration():
from ComfyUI_H3_Continuum_Join import nodes as root_nodes
node_class = root_nodes.NODE_CLASS_MAPPINGS["H3ContinuumSeamTestSource"]
assert not getattr(node_class, "DEPRECATED", False)
assert node_class.CATEGORY == "MiniMax H3/Continuum/Testing"
assert root_nodes.NODE_DISPLAY_NAME_MAPPINGS["H3ContinuumSeamTestSource"] == (
"H3 Continuum Seam Test Source (Experimental)"
)
def test_seam_test_source_emits_realistic_three_chunk_contract():
images, audio, plan, instructions = _source_outputs()
assert [tuple(item.shape) for item in images] == [
(124, 256, 256, 3),
(141, 256, 256, 3),
(141, 256, 256, 3),
]
assert len(audio) == 3
assert plan["target_frames"] == 360
assert [item["trim_frames"] for item in plan["chunks"]] == [0, 22, 22]
assert "Analyze Only" in instructions
assert "Auto 2" in instructions
def test_controlled_boundaries_are_classified_as_exposure_ramps():
images, _audio, plan, _instructions = _source_outputs()
analyses = analyze_decoded_boundaries(images=images, assembly_plan=plan)
assert len(analyses) == 2
assert all(item.exposure_ramp_candidate for item in analyses)
assert [item.classification for item in analyses] == [
"exposure_ramp",
"exposure_ramp",
]
def test_auto_two_corrects_only_the_controlled_ramp_frames():
images, audio, plan, _instructions = _source_outputs()
node = H3ContinuumAssembleSeamExperimental()
common = {
"images": images,
"audio": audio,
"assembly_plan": [plan],
"exact_total_duration": [False],
"audio_seam": ["Off"],
"diagnostics": [DIAGNOSTICS_OPTIONS[0]],
}
analyzed_images, _analyzed_audio, analyzed_report = node.assemble(
video_seam=[VIDEO_SEAM_ANALYZE],
**common,
)
auto_images, _auto_audio, auto_report = node.assemble(
video_seam=[VIDEO_SEAM_AUTO],
**common,
)
auto_two_images, _auto_two_audio, auto_two_report = node.assemble(
video_seam=[VIDEO_SEAM_AUTO_2],
**common,
)
assert torch.equal(auto_images, analyzed_images)
assert "class=exposure_ramp" in analyzed_report
assert "action=kept native boundary" in auto_report
assert not torch.equal(auto_two_images, analyzed_images)
assert auto_two_report.count(
"normalized exposure/color on 4 exposure ramp boundary frame(s)"
) == 2
+356
View File
@@ -0,0 +1,356 @@
import torch
from ComfyUI_H3_Continuum_Join.constants import DIAGNOSTICS_OPTIONS
from ComfyUI_H3_Continuum_Join.hardening import enrich_assembly_plan
from ComfyUI_H3_Continuum_Join.v3.assembly import (
H3ContinuumAssembleSeamExperimental,
VIDEO_SEAM_ANALYZE,
VIDEO_SEAM_AUTO,
VIDEO_SEAM_OFF,
)
from ComfyUI_H3_Continuum_Join.v3.nodes import NODE_CLASS_MAPPINGS
from ComfyUI_H3_Continuum_Join.v3.plan import ASSEMBLY_PLAN_MAGIC
from ComfyUI_H3_Continuum_Join.v3.video_seam import analyze_video_boundary
def _frames(values, *, height=8, width=8):
return (
torch.tensor(values, dtype=torch.float32)
.reshape(-1, 1, 1, 1)
.expand(-1, height, width, 3)
.clone()
)
def _plan():
return enrich_assembly_plan(
{
"magic": ASSEMBLY_PLAN_MAGIC,
"schema_version": 1,
"fps": 24,
"width": 8,
"height": 8,
"chunk_seconds": 5.0,
"target_frames": 240,
"preserve_final_frame": True,
"chunks": [
{
"sequence_index": 1,
"chunk_index": 1,
"total_frames": 124,
"trim_frames": 0,
"net_frames": 124,
"context_frames": 0,
"expected_video_latent_t": 32,
"expected_audio_latent_t": 207,
},
{
"sequence_index": 2,
"chunk_index": 2,
"total_frames": 141,
"trim_frames": 22,
"net_frames": 119,
"context_frames": 22,
"expected_video_latent_t": 36,
"expected_audio_latent_t": 235,
},
],
}
)
def _decoded():
images = [
torch.full((124, 8, 8, 3), 0.25, dtype=torch.float32),
torch.full((141, 8, 8, 3), 0.25, dtype=torch.float32),
]
audio = [
{"waveform": torch.zeros((1, 2, 190000)), "sample_rate": 32000},
{"waveform": torch.zeros((1, 2, 190000)), "sample_rate": 32000},
]
return images, audio
def test_clean_boundary_keeps_the_nominal_cut():
previous = _frames([0.1, 0.2, 0.3, 0.4, 0.5, 0.6])
current = _frames([0.5, 0.6, 0.7, 0.8, 0.9])
analysis = analyze_video_boundary(previous, current, trim_frames=2)
assert analysis.recommended_rewind == 0
assert not analysis.scene_cut
assert not analysis.transient_flash_candidate
assert analysis.classification == "clean_boundary"
def test_single_frame_flash_recommends_an_earlier_candidate():
previous = _frames([0.1, 0.2, 0.3, 0.4, 0.5, 0.6])
current = _frames([0.5, 0.6, 1.0, 0.8, 0.9])
analysis = analyze_video_boundary(previous, current, trim_frames=2)
assert analysis.recommended_rewind == 1
assert analysis.improvement >= 0.06
assert not analysis.scene_cut
assert analysis.transient_flash_candidate
assert analysis.flash_reversal >= 0.35
assert analysis.flash_global_fraction >= 0.75
assert analysis.classification == "transient_flash"
def test_persistent_content_change_is_guarded_as_a_scene_cut():
previous = _frames([0.1, 0.2, 0.3, 0.4, 0.5, 0.6])
current = _frames([0.5, 0.6, 0.95, 0.95, 0.95])
analysis = analyze_video_boundary(previous, current, trim_frames=2)
assert analysis.scene_cut
assert analysis.recommended_rewind == 0
assert not analysis.transient_flash_candidate
assert analysis.classification == "scene_cut"
def test_small_global_reversal_is_classified_as_micro_flash():
previous = _frames([0.4, 0.4, 0.4, 0.4, 0.4, 0.4])
current = _frames([0.4, 0.4, 0.408, 0.4, 0.4, 0.4])
analysis = analyze_video_boundary(previous, current, trim_frames=2)
assert not analysis.transient_flash_candidate
assert analysis.micro_flash_candidate
assert analysis.classification == "micro_flash"
def test_persistent_global_change_is_classified_as_exposure_ramp():
previous = _frames([0.4, 0.4, 0.4, 0.4, 0.4, 0.4])
current = _frames([0.4, 0.4, 0.42, 0.44, 0.46, 0.48])
analysis = analyze_video_boundary(previous, current, trim_frames=2)
assert not analysis.transient_flash_candidate
assert analysis.exposure_ramp_candidate
assert analysis.classification == "exposure_ramp"
def test_local_velocity_jump_is_classified_as_motion_hitch():
def moving_bar(position):
frame = torch.zeros((16, 16, 3), dtype=torch.float32)
frame[:, position : position + 2, :] = 1.0
return frame
previous = torch.stack([moving_bar(position) for position in [1, 2, 3, 4, 5, 6]])
current = torch.stack([moving_bar(position) for position in [4, 5, 9, 10, 11, 12]])
analysis = analyze_video_boundary(previous, current, trim_frames=2)
assert not analysis.transient_flash_candidate
assert not analysis.micro_flash_candidate
assert analysis.motion_hitch_candidate
assert analysis.motion_jump_ratio >= 1.60
assert analysis.classification == "motion_hitch"
def test_local_motion_is_not_reported_as_a_global_flash():
previous = torch.full((6, 8, 8, 3), 0.4, dtype=torch.float32)
current = torch.full((5, 8, 8, 3), 0.4, dtype=torch.float32)
current[2, :2, :2, :] = 1.0
analysis = analyze_video_boundary(previous, current, trim_frames=2)
assert analysis.flash_global_fraction < 0.75
assert not analysis.transient_flash_candidate
def test_analyze_only_preserves_assembled_image_and_audio_content():
images, audio = _decoded()
node = H3ContinuumAssembleSeamExperimental()
common = {
"images": images,
"audio": audio,
"assembly_plan": [_plan()],
"exact_total_duration": [False],
"audio_seam": ["Off"],
"diagnostics": [DIAGNOSTICS_OPTIONS[0]],
}
off_images, off_audio, _off_report = node.assemble(
video_seam=[VIDEO_SEAM_OFF],
**common,
)
analyzed_images, analyzed_audio, report = node.assemble(
video_seam=[VIDEO_SEAM_ANALYZE],
**common,
)
assert torch.equal(analyzed_images, off_images)
assert torch.equal(analyzed_audio["waveform"], off_audio["waveform"])
assert analyzed_audio["sample_rate"] == off_audio["sample_rate"]
assert "action=analysis only" in report
assert "decoded frames and audio are unchanged" in report
def test_auto_replaces_only_qualified_transient_boundary_frame():
images, audio = _decoded()
images[1][22] = 1.0
node = H3ContinuumAssembleSeamExperimental()
common = {
"images": images,
"audio": audio,
"assembly_plan": [_plan()],
"exact_total_duration": [False],
"audio_seam": ["Off"],
"diagnostics": [DIAGNOSTICS_OPTIONS[0]],
}
off_images, off_audio, _ = node.assemble(
video_seam=[VIDEO_SEAM_OFF],
**common,
)
corrected_images, corrected_audio, report = node.assemble(
video_seam=[VIDEO_SEAM_AUTO],
**common,
)
assert float(off_images[124].mean().item()) == 1.0
assert float(corrected_images[124].mean().item()) == 0.25
assert torch.equal(corrected_images[:124], off_images[:124])
assert torch.equal(corrected_images[125:], off_images[125:])
assert torch.equal(corrected_audio["waveform"], off_audio["waveform"])
assert "Video Seam: Auto" in report
assert (
"action=normalized exposure/color on 1 transient flash boundary frame(s)"
in report
)
def test_auto_normalizes_only_the_micro_flash_boundary_frame():
images, audio = _decoded()
images[1][22] = 0.258
node = H3ContinuumAssembleSeamExperimental()
common = {
"images": images,
"audio": audio,
"assembly_plan": [_plan()],
"exact_total_duration": [False],
"audio_seam": ["Off"],
"diagnostics": [DIAGNOSTICS_OPTIONS[0]],
}
off_images, off_audio, _ = node.assemble(
video_seam=[VIDEO_SEAM_OFF],
**common,
)
corrected_images, corrected_audio, report = node.assemble(
video_seam=[VIDEO_SEAM_AUTO],
**common,
)
assert torch.allclose(off_images[124], torch.full_like(off_images[124], 0.258))
assert torch.allclose(
corrected_images[124],
torch.full_like(corrected_images[124], 0.25),
atol=1.0e-6,
)
assert torch.equal(corrected_images[:124], off_images[:124])
assert torch.equal(corrected_images[125:], off_images[125:])
assert torch.equal(corrected_audio["waveform"], off_audio["waveform"])
assert "class=micro_flash" in report
assert "action=normalized exposure/color on 1 micro-flash boundary frame(s)" in report
def test_auto_2_smooths_exposure_ramp_without_changing_frame_count():
images, audio = _decoded()
images[1][22:] = 0.33
images[1][22:26] = torch.tensor([0.27, 0.29, 0.31, 0.33]).view(4, 1, 1, 1)
node = H3ContinuumAssembleSeamExperimental()
common = {
"images": images,
"audio": audio,
"assembly_plan": [_plan()],
"exact_total_duration": [False],
"audio_seam": ["Off"],
"diagnostics": ["Off"],
}
native_images, native_audio, _ = node.assemble(video_seam=["Auto"], **common)
corrected_images, corrected_audio, report = node.assemble(
video_seam=["Auto 2"], **common
)
assert corrected_images.shape == native_images.shape
assert torch.equal(corrected_images[:124], native_images[:124])
assert torch.equal(corrected_images[128:], native_images[128:])
corrected_means = corrected_images[124:128].mean(dim=(1, 2, 3))
assert torch.all(corrected_means[1:] >= corrected_means[:-1])
assert float(corrected_means[0]) < 0.27
assert float(corrected_means[-1]) < 0.33
assert torch.equal(corrected_audio["waveform"], native_audio["waveform"])
assert "Video Seam: Auto 2 (Experimental)" in report
assert "class=exposure_ramp" in report
assert "action=normalized exposure/color on 4 exposure ramp boundary frame(s)" in report
def test_auto_1_keeps_exposure_ramp_native():
images, audio = _decoded()
images[1][22:] = 0.33
images[1][22:26] = torch.tensor([0.27, 0.29, 0.31, 0.33]).view(4, 1, 1, 1)
node = H3ContinuumAssembleSeamExperimental()
output_images, _, report = node.assemble(
images=images,
audio=audio,
assembly_plan=[_plan()],
exact_total_duration=[False],
audio_seam=["Off"],
video_seam=["Auto"],
diagnostics=["Off"],
)
expected = torch.tensor([0.27, 0.29, 0.31, 0.33])
actual = output_images[124:128].mean(dim=(1, 2, 3))
assert torch.allclose(actual, expected)
assert "Video Seam: Auto;" in report
assert "class=exposure_ramp" in report
assert "action=kept native boundary" in report
def test_auto_preserves_spatial_detail_in_corrected_frame():
images, audio = _decoded()
detail = torch.linspace(0.15, 0.35, 8 * 8 * 3).reshape(8, 8, 3)
images[0][-1] = detail
images[1][21] = detail
images[1][22] = detail + 0.2
images[1][23] = detail
node = H3ContinuumAssembleSeamExperimental()
corrected_images, _corrected_audio, report = node.assemble(
images=images,
audio=audio,
assembly_plan=[_plan()],
exact_total_duration=[False],
audio_seam=["Off"],
video_seam=[VIDEO_SEAM_AUTO],
diagnostics=[DIAGNOSTICS_OPTIONS[0]],
)
assert torch.allclose(corrected_images[124], detail, atol=1.0e-6)
assert "action=normalized exposure/color" in report
def test_auto_preserves_clean_boundary():
images, audio = _decoded()
node = H3ContinuumAssembleSeamExperimental()
common = {
"images": images,
"audio": audio,
"assembly_plan": [_plan()],
"exact_total_duration": [False],
"audio_seam": ["Off"],
"diagnostics": [DIAGNOSTICS_OPTIONS[0]],
}
off_images, off_audio, _ = node.assemble(
video_seam=[VIDEO_SEAM_OFF],
**common,
)
corrected_images, corrected_audio, report = node.assemble(
video_seam=[VIDEO_SEAM_AUTO],
**common,
)
assert torch.equal(corrected_images, off_images)
assert torch.equal(corrected_audio["waveform"], off_audio["waveform"])
assert "action=kept native boundary" in report
def test_experimental_seam_analyzer_is_registered_separately():
assert (
NODE_CLASS_MAPPINGS["H3ContinuumAssembleSeamExperimental"]
is H3ContinuumAssembleSeamExperimental
)
assert NODE_CLASS_MAPPINGS["H3ContinuumAssembleV3"] is not H3ContinuumAssembleSeamExperimental
def test_experimental_seam_analyzer_is_public_in_root_registration():
from ComfyUI_H3_Continuum_Join import nodes as root_nodes
node_class = root_nodes.NODE_CLASS_MAPPINGS["H3ContinuumAssembleSeamExperimental"]
assert not getattr(node_class, "DEPRECATED", False)
assert node_class.CATEGORY == "MiniMax H3/Continuum"
assert root_nodes.NODE_DISPLAY_NAME_MAPPINGS["H3ContinuumAssembleSeamExperimental"] == (
"H3 Continuum Assemble + Seam"
)
+342
View File
@@ -0,0 +1,342 @@
"""Chunk-local MiniMax H3 timeline-video reference conditioning."""
from __future__ import annotations
from dataclasses import dataclass
import hashlib
import io
import json
import math
from pathlib import Path
from typing import Any
import torch
from .constants import FPS
from .temporal import align_frame_count_up
TIMELINE_VIDEO_CONTRACT_VERSION = 1
TIMELINE_VIDEO_PREPROCESS_VERSION = 1
TIMELINE_VIDEO_SIZE_EFFICIENT = "Efficient - 0.4 MP"
TIMELINE_VIDEO_SIZE_BALANCED = "Balanced - 0.6 MP"
TIMELINE_VIDEO_SIZE_MATCH_OUTPUT = "Match Output"
TIMELINE_VIDEO_SIZE_OPTIONS = (
TIMELINE_VIDEO_SIZE_EFFICIENT,
TIMELINE_VIDEO_SIZE_MATCH_OUTPUT,
)
_EFFICIENT_AREA = 400_000
_BALANCED_AREA = 600_000
_CANVAS_MULTIPLE = 32
class TimelineVideoError(ValueError):
pass
def _canonical_hash(value: Any) -> str:
payload = json.dumps(
value, sort_keys=True, separators=(",", ":"), ensure_ascii=True
).encode("utf-8")
return hashlib.sha256(payload).hexdigest()
def _tensor_hash(value: torch.Tensor) -> str:
tensor = value.detach().to(device="cpu").contiguous()
digest = hashlib.sha256()
digest.update(str(tuple(int(v) for v in tensor.shape)).encode("ascii"))
digest.update(str(tensor.dtype).encode("ascii"))
digest.update(tensor.numpy().tobytes(order="C"))
return digest.hexdigest()
def _source_hash(video: Any) -> tuple[str, int]:
try:
source = video.get_stream_source()
except Exception as exc:
raise TimelineVideoError(
"Timeline Video must expose a stable ComfyUI VIDEO stream source"
) from exc
digest = hashlib.sha256()
size = 0
if isinstance(source, (str, Path)):
path = Path(source)
if not path.is_file():
raise TimelineVideoError("Timeline Video source file is unavailable")
with path.open("rb") as handle:
while True:
block = handle.read(4 * 1024 * 1024)
if not block:
break
digest.update(block)
size += len(block)
elif isinstance(source, io.BytesIO):
view = source.getbuffer()
try:
digest.update(view)
size = len(view)
finally:
view.release()
else:
raise TimelineVideoError(
"Timeline Video currently supports file-backed or in-memory Core VIDEO inputs"
)
return digest.hexdigest(), int(size)
def _round_canvas(value: float) -> int:
return max(
_CANVAS_MULTIPLE,
int(round(float(value) / _CANVAS_MULTIPLE)) * _CANVAS_MULTIPLE,
)
def _resolved_size(
source_width: int,
source_height: int,
*,
output_width: int,
output_height: int,
size_mode: str,
) -> tuple[int, int]:
if size_mode == TIMELINE_VIDEO_SIZE_MATCH_OUTPUT:
target_area = int(output_width) * int(output_height)
elif size_mode == TIMELINE_VIDEO_SIZE_EFFICIENT:
target_area = _EFFICIENT_AREA
elif size_mode == TIMELINE_VIDEO_SIZE_BALANCED:
target_area = _BALANCED_AREA
else:
raise TimelineVideoError(f"unknown Timeline Video Size: {size_mode!r}")
source_area = int(source_width) * int(source_height)
scale = min(1.0, math.sqrt(float(target_area) / float(source_area)))
return (
_round_canvas(int(source_width) * scale),
_round_canvas(int(source_height) * scale),
)
@dataclass(frozen=True)
class TimelineVideoSource:
video: Any
duration: float
source_width: int
source_height: int
source_sha256: str
source_bytes: int
target_width: int
target_height: int
size_mode: str
chunks: int
chunk_seconds: float
chunk_contracts: tuple[dict[str, Any], ...]
combined_hash: str
@property
def contract(self) -> dict[str, Any]:
return {
"timeline_video_contract_version": TIMELINE_VIDEO_CONTRACT_VERSION,
"source_sha256": self.source_sha256,
"source_bytes": self.source_bytes,
"source_duration": round(self.duration, 6),
"source_width": self.source_width,
"source_height": self.source_height,
"size_mode": self.size_mode,
"target_width": self.target_width,
"target_height": self.target_height,
"target_fps": FPS,
"preprocess_version": TIMELINE_VIDEO_PREPROCESS_VERSION,
"combined_hash": self.combined_hash,
"chunk_slices": [dict(item) for item in self.chunk_contracts],
}
@dataclass(frozen=True)
class TimelineVideoAssets:
item: dict[str, Any]
block: dict[str, Any]
processed_sha256: str
frame_count: int
def prepare_timeline_video_source(
video: Any,
*,
chunks: int,
chunk_seconds: float,
output_width: int,
output_height: int,
size_mode: str,
) -> TimelineVideoSource:
if video is None:
raise TimelineVideoError("Timeline Video is required")
for method in ("get_duration", "get_dimensions", "get_stream_source", "as_trimmed"):
if not callable(getattr(video, method, None)):
raise TimelineVideoError(
f"Timeline Video is not a compatible ComfyUI VIDEO input: missing {method}()"
)
chunks = int(chunks)
chunk_seconds = float(chunk_seconds)
duration = float(video.get_duration())
required_duration = chunks * chunk_seconds
if duration + (1.0 / FPS) < required_duration:
raise TimelineVideoError(
f"Timeline Video is {duration:.3f}s, but {required_duration:.3f}s is required "
f"for {chunks} chunk(s); looping and padding are not enabled"
)
source_width, source_height = (int(value) for value in video.get_dimensions())
if source_width < 1 or source_height < 1:
raise TimelineVideoError("Timeline Video dimensions are invalid")
source_sha256, source_bytes = _source_hash(video)
target_width, target_height = _resolved_size(
source_width,
source_height,
output_width=int(output_width),
output_height=int(output_height),
size_mode=str(size_mode),
)
chunk_contracts = []
for index in range(chunks):
item = {
"chunk_number": index + 1,
"start_seconds": round(index * chunk_seconds, 6),
"duration_seconds": round(chunk_seconds, 6),
"target_width": target_width,
"target_height": target_height,
"target_fps": FPS,
"preprocess_version": TIMELINE_VIDEO_PREPROCESS_VERSION,
}
item["slice_sha256"] = _canonical_hash(
{"source_sha256": source_sha256, **item}
)
chunk_contracts.append(item)
combined_hash = _canonical_hash(
{
"timeline_video_contract_version": TIMELINE_VIDEO_CONTRACT_VERSION,
"source_sha256": source_sha256,
"size_mode": str(size_mode),
"target_width": target_width,
"target_height": target_height,
"chunk_slices": chunk_contracts,
}
)
return TimelineVideoSource(
video=video,
duration=duration,
source_width=source_width,
source_height=source_height,
source_sha256=source_sha256,
source_bytes=source_bytes,
target_width=target_width,
target_height=target_height,
size_mode=str(size_mode),
chunks=chunks,
chunk_seconds=chunk_seconds,
chunk_contracts=tuple(chunk_contracts),
combined_hash=combined_hash,
)
def combine_timeline_video_identity(
visual_identity_hash: str,
source: TimelineVideoSource | None,
) -> str:
if source is None:
return str(visual_identity_hash)
return _canonical_hash(
{
"timeline_video_identity_version": 1,
"visual_identity_hash": str(visual_identity_hash),
"timeline_video_hash": source.combined_hash,
}
)
def validate_timeline_video_prompts(
prompts: list[str], source: TimelineVideoSource | None
) -> str:
if source is None:
return ""
if any("<Video 1>" in str(prompt) for prompt in prompts):
return ""
return (
"H3C-P103 Warning: Timeline Video is connected but the prompt contains no "
"<Video 1> tag; video still conditions generation, but an explicit motion "
"reference is recommended."
)
def encode_timeline_video_chunk(
video_vae: Any,
source: TimelineVideoSource,
chunk_index: int,
) -> TimelineVideoAssets:
chunk_index = int(chunk_index)
if chunk_index < 0 or chunk_index >= source.chunks:
raise TimelineVideoError("Timeline Video chunk index is out of range")
start = chunk_index * source.chunk_seconds
trimmed = source.video.as_trimmed(
start_time=start,
duration=source.chunk_seconds,
strict_duration=False,
)
if trimmed is None:
raise TimelineVideoError(
f"Timeline Video could not provide chunk {chunk_index + 1}"
)
components = trimmed.get_components()
frames = getattr(components, "images", None)
if not torch.is_tensor(frames) or frames.ndim != 4:
raise TimelineVideoError("Timeline Video produced invalid IMAGE frames")
if int(frames.shape[0]) < 5 or int(frames.shape[-1]) < 3:
raise TimelineVideoError(
f"Timeline Video chunk {chunk_index + 1} needs at least 5 RGB frames"
)
frames = frames[:, :, :, :3].detach().to(device="cpu", dtype=torch.float32)
if not bool(torch.isfinite(frames).all()):
raise TimelineVideoError("Timeline Video contains NaN or Inf pixels")
target_frames = align_frame_count_up(int(round(source.chunk_seconds * FPS)))
indices = torch.linspace(
0, int(frames.shape[0]) - 1, target_frames, dtype=torch.float64
).round().to(dtype=torch.long)
frames = frames.index_select(0, indices).contiguous()
if (
int(frames.shape[2]) != source.target_width
or int(frames.shape[1]) != source.target_height
):
try:
import comfy.utils
except Exception as exc:
raise TimelineVideoError(
"ComfyUI Core image resize support is unavailable"
) from exc
frames = comfy.utils.common_upscale(
frames.movedim(-1, 1),
source.target_width,
source.target_height,
"lanczos",
"disabled",
).movedim(1, -1).contiguous()
processed_sha256 = _tensor_hash(frames)
latent = video_vae.encode(frames)
qwen_step = max(1, int(round(float(FPS) / 2.0)))
qwen_frames = frames[::qwen_step].contiguous()
item = {
"type": "video",
"data": qwen_frames,
"timestamps": [index / 2.0 for index in range(int(qwen_frames.shape[0]))],
}
block = {
"kind": "video",
"latent_t": int(latent.shape[2]),
"latent_h": source.target_height // 16,
"latent_w": source.target_width // 16,
"ref_audio_t": 0,
"latent": latent,
"audio_latent": None,
}
return TimelineVideoAssets(
item=item,
block=block,
processed_sha256=processed_sha256,
frame_count=int(frames.shape[0]),
)
+3
View File
@@ -81,9 +81,12 @@ def main() -> int:
"H3ContinuumAdvanced",
"H3ContinuumResult",
"H3ContinuumSamplerProduction",
"H3ContinuumSamplerTimelineVideo",
"H3ContinuumSamplerV3",
"H3ContinuumAdvancedV3",
"H3ContinuumAssembleV3",
"H3ContinuumAssembleSeamExperimental",
"H3ContinuumSeamTestSource",
}
actual = set(module.NODE_CLASS_MAPPINGS)
if actual != expected:
+31 -2
View File
@@ -91,14 +91,43 @@ def encode_prompt_conditioning(
*,
first_image: torch.Tensor | None,
last_image: torch.Tensor | None,
reference_audio_assets=None,
timeline_video_assets=None,
) -> list:
images = []
if first_image is not None:
images.append(first_image)
if last_image is not None:
images.append(last_image)
tokens = clip.tokenize(str(prompt), images=images)
return clip.encode_from_tokens_scheduled(tokens)
tokenize_options = {"images": images}
if reference_audio_assets is not None or timeline_video_assets is not None:
from ..reference_audio import reference_audio_item
ref_items = [
*({"type": "image", "data": image} for image in images),
]
if timeline_video_assets is not None:
ref_items.append(dict(timeline_video_assets.item))
if reference_audio_assets is not None:
ref_items.append(reference_audio_item())
tokenize_options = {
"minimax_ref_items": ref_items
}
tokens = clip.tokenize(str(prompt), **tokenize_options)
conditioning = clip.encode_from_tokens_scheduled(tokens)
if reference_audio_assets is None and timeline_video_assets is None:
return conditioning
refs = []
if timeline_video_assets is not None:
refs.append(dict(timeline_video_assets.block))
if reference_audio_assets is not None:
from ..reference_audio import reference_audio_block
refs.append(dict(reference_audio_block(reference_audio_assets)))
return [
[tensor, {**dict(metadata), "minimax_refs": list(refs)}]
for tensor, metadata in conditioning
]
def attach_keyframes(
+6
View File
@@ -305,6 +305,9 @@ class H3ContinuumSamplerV2:
show_preview=True,
latent_only=False,
reference_assets=None,
reference_audio_source=None,
reference_audio_vae=None,
timeline_video_source=None,
**clip_prompt_inputs,
):
(
@@ -371,6 +374,9 @@ class H3ContinuumSamplerV2:
initial_state=initial_state,
latent_only=bool(latent_only),
reference_assets=reference_assets,
reference_audio_source=reference_audio_source,
reference_audio_vae=reference_audio_vae,
timeline_video_source=timeline_video_source,
)
+80 -20
View File
@@ -13,12 +13,19 @@ from ..constants import (
from ..version import PROMPT_PLAN_SCHEMA_VERSION
_TIMELINE_HEADER=re.compile(r"^\s*\[\s*(?P<start>\d+(?:\.\d+)?)\s*(?:s|sec|seconds)?\s*[-–—]\s*(?P<end>\d+(?:\.\d+)?)\s*(?:s|sec|seconds)?\s*\]\s*$",re.IGNORECASE)
_CHUNK_HEADER=re.compile(r"^\s*\[\s*(?:chunk|clip)\s*(?P<index>\d+)\s*\]\s*$",re.IGNORECASE)
_TIMELINE_LIKE_HEADER=re.compile(r"^\s*\[\s*(?:(?:chunk|clip)\b|\d+(?:\.\d+)?[^\]]*(?:[-–—]|\bto\b))",re.IGNORECASE)
_LIST_SEPARATOR=re.compile(r"^\s*---+\s*$",re.MULTILINE)
class PromptPlanError(ValueError): pass
def _prompt_error(code,reason,*,line_number=None,source=None,suggested_fix):
location=f" line {line_number}" if line_number is not None else ""
lines=[f"{code}{location}: {reason}"]
if source is not None: lines.append(f"Source: {source}")
if suggested_fix: lines.append(f"Suggested fix: {suggested_fix}")
raise PromptPlanError("\n".join(lines))
def prompt_hash(prompt:str)->str: return hashlib.sha256(prompt.encode("utf-8")).hexdigest()
def _normalize_prompt(value:str,*,label:str)->str:
text=str(value).strip()
if not text: raise PromptPlanError(f"{label} is empty")
if not text: _prompt_error("H3C-P005",f"{label} is empty",suggested_fix="provide non-empty prompt text")
return text
def _parse_json_list(script:str):
stripped=script.lstrip()
@@ -35,33 +42,46 @@ def _parse_list(script,chunks):
if len(values)<chunks: notes.append(f"repeated the last prompt for {chunks-len(values)} chunk(s)"); values.extend([values[-1]]*(chunks-len(values)))
elif len(values)>chunks: notes.append(f"ignored {len(values)-chunks} extra prompt(s)"); values=values[:chunks]
return values,notes
def _parse_timeline_sections(script):
def _timeline_preamble(script):
body=[]
for line in str(script).splitlines():
if _TIMELINE_HEADER.match(line) or _CHUNK_HEADER.match(line): break
body.append(line)
return "\n".join(body).strip()
def _parse_timeline_sections(script,*,allow_preamble=True):
preamble=_timeline_preamble(script)
sections=[]; current=None; body=[]
def finish():
nonlocal current,body
if current is None:
if any(line.strip() for line in body): raise PromptPlanError("timeline text before the first [0-5s] or [Chunk 1] header is not allowed")
if any(line.strip() for line in body) and not allow_preamble: raise PromptPlanError("timeline text before the first [0-5s] or [Chunk 1] header is not allowed")
body=[]; return
current["prompt"]=_normalize_prompt("\n".join(body),label="timeline section"); sections.append(current); current=None; body=[]
for line in str(script).splitlines():
if not any(line.strip() for line in body):
_prompt_error("H3C-P005","timeline section body is empty",line_number=current["line_number"],source=current["source"],suggested_fix="add prompt text below this header")
prompt=_normalize_prompt("\n".join(body),label="timeline section")
current["prompt"]=f"{preamble}\n\n{prompt}" if preamble else prompt
sections.append(current); current=None; body=[]
for line_number,line in enumerate(str(script).splitlines(),start=1):
time_match=_TIMELINE_HEADER.match(line); chunk_match=_CHUNK_HEADER.match(line)
if time_match or chunk_match:
finish()
if time_match:
start=float(time_match.group("start")); end=float(time_match.group("end"))
if not end>start: raise PromptPlanError(f"timeline range must increase: {line.strip()}")
current={"kind":"time","start":start,"end":end}
if not end>start: _prompt_error("H3C-P002","timeline end must be greater than its start",line_number=line_number,source=line.strip(),suggested_fix="use an increasing range such as [0-5s]")
current={"kind":"time","start":start,"end":end,"line_number":line_number,"source":line.strip()}
else:
index=int(chunk_match.group("index"))
if index<1: raise PromptPlanError("chunk numbers are one-based")
current={"kind":"chunk","index":index}
if index<1: _prompt_error("H3C-P004","chunk numbers are one-based",line_number=line_number,source=line.strip(),suggested_fix="use [Chunk 1] or a larger one-based chunk number")
current={"kind":"chunk","index":index,"line_number":line_number,"source":line.strip()}
continue
if _TIMELINE_LIKE_HEADER.match(line):
_prompt_error("H3C-P001","invalid timeline header",line_number=line_number,source=line.strip(),suggested_fix="use [0-5s] or [Chunk 1]")
body.append(line)
finish()
if not sections: raise PromptPlanError("timeline contains no sections")
return sections
def parse_sparse_prompt_overrides(script):
sections=_parse_timeline_sections(script); overrides={}
sections=_parse_timeline_sections(script,allow_preamble=False); overrides={}
for item in sections:
if item["kind"]!="chunk": raise PromptPlanError("Sparse Clip Overrides only accepts [Clip N] or [Chunk N] sections")
index=int(item["index"])
@@ -79,24 +99,53 @@ def validate_sparse_prompt_overrides(overrides,*,chunks):
if not validated: raise PromptPlanError("Sparse Clip Overrides contains no overrides")
return validated
def _parse_timeline(script,chunks,chunk_seconds):
sections=_parse_timeline_sections(script); prompts=[]; notes=[]
sections=_parse_timeline_sections(script); prompts=[]; notes=[]; diagnostics=[]
if _timeline_preamble(script): notes.append("applied timeline preamble to all chunks")
seen_chunks={}; total_end=chunks*chunk_seconds; usable=[]
for item in sections:
if item["kind"]=="chunk":
index=int(item["index"])
if index in seen_chunks:
_prompt_error("H3C-P003",f"timeline defines Chunk {index} more than once",line_number=item["line_number"],source=item["source"],suggested_fix=f"keep only one [Chunk {index}] section")
seen_chunks[index]=item
if index<=chunks: usable.append(item)
else: diagnostics.append({"level":"warning","code":"H3C-P104","message":f"ignored {item['source']} because the configured sequence has only {chunks} chunk(s)"})
elif min(total_end,item["end"])-max(0.0,item["start"])>0:
usable.append(item)
else:
diagnostics.append({"level":"warning","code":"H3C-P104","message":f"ignored {item['source']} because it is outside 0-{total_end:.3f}s"})
if not usable:
_prompt_error("H3C-P005","timeline contains no usable prompt section for the configured sequence",suggested_fix="add a section such as [0-5s] with non-empty prompt text")
previous_prompt=None; previous_source=None
for chunk_index in range(1,chunks+1):
chunk_sections=[item for item in sections if item["kind"]=="chunk" and item["index"]==chunk_index]
if len(chunk_sections)>1: raise PromptPlanError(f"timeline defines Chunk {chunk_index} more than once")
if chunk_sections: prompts.append(chunk_sections[0]["prompt"]); continue
if chunk_sections:
selected=chunk_sections[0]; prompts.append(selected["prompt"]); previous_prompt=selected["prompt"]; previous_source=f"{selected['source']} at line {selected['line_number']}"
diagnostics.append({"level":"info","code":"H3C-P000","message":f"Chunk {chunk_index} source: {previous_source}"}); continue
start=(chunk_index-1)*chunk_seconds; end=chunk_index*chunk_seconds; scored=[]
for order,item in enumerate(sections):
if item["kind"]!="time": continue
overlap=max(0.0,min(end,item["end"])-max(start,item["start"]))
if overlap>0: scored.append((overlap,-order,item))
if not scored: raise PromptPlanError(f"timeline does not cover chunk {chunk_index} ({start:.3f}-{end:.3f}s)")
scored.sort(reverse=True,key=lambda row:(row[0],row[1])); prompts.append(scored[0][2]["prompt"])
if not scored:
if previous_prompt is None:
selected=usable[0]; fallback_reason=f"used earliest valid prompt from {selected['source']}"
else:
selected=None; fallback_reason=f"reused previous prompt from {previous_source}"
prompt=selected["prompt"] if selected is not None else previous_prompt
source=f"{selected['source']} at line {selected['line_number']}" if selected is not None else previous_source
prompts.append(prompt); previous_prompt=prompt; previous_source=source
diagnostics.append({"level":"warning","code":"H3C-P101","message":f"Timeline does not cover Chunk {chunk_index} ({start:.3f}-{end:.3f}s); {fallback_reason}."})
diagnostics.append({"level":"info","code":"H3C-P000","message":f"Chunk {chunk_index} source: fallback to {source}"}); continue
scored.sort(reverse=True,key=lambda row:(row[0],row[1])); selected=scored[0][2]; prompts.append(selected["prompt"]); previous_prompt=selected["prompt"]; previous_source=f"{selected['source']} at line {selected['line_number']}"
diagnostics.append({"level":"info","code":"H3C-P000","message":f"Chunk {chunk_index} source: {previous_source}"})
if len(scored)>1 and abs(scored[0][0]-scored[1][0])<1e-9: notes.append(f"chunk {chunk_index} had an equal-overlap timeline tie; used the earlier section")
return prompts,notes
return prompts,notes,diagnostics
def detect_prompt_mode(script):
text=str(script)
for line in text.splitlines():
if _TIMELINE_HEADER.match(line) or _CHUNK_HEADER.match(line): return PROMPT_MODE_TIMELINE
if _TIMELINE_LIKE_HEADER.match(line): _prompt_error("H3C-P001","invalid timeline header",source=line.strip(),suggested_fix="use [0-5s] or [Chunk 1]")
if _parse_json_list(text) is not None or _LIST_SEPARATOR.search(text): return PROMPT_MODE_LIST
return PROMPT_MODE_FIXED
def resolve_prompt_mode(mode,script):
@@ -114,9 +163,11 @@ def make_prompt_plan(*,mode,script,chunks,chunk_seconds):
detected={PROMPT_MODE_FIXED:PROMPT_FORMAT_FIXED,PROMPT_MODE_LIST:PROMPT_FORMAT_LIST,PROMPT_MODE_TIMELINE:PROMPT_FORMAT_TIMELINE}[resolved_mode]; notes.append(f"Auto detected {detected}")
if resolved_mode==PROMPT_MODE_FIXED: prompt=_normalize_prompt(script,label="fixed prompt"); prompts=[prompt]*chunks
elif resolved_mode==PROMPT_MODE_LIST: prompts,parse_notes=_parse_list(script,chunks); notes.extend(parse_notes)
elif resolved_mode==PROMPT_MODE_TIMELINE: prompts,parse_notes=_parse_timeline(script,chunks,chunk_seconds); notes.extend(parse_notes)
elif resolved_mode==PROMPT_MODE_TIMELINE: prompts,parse_notes,diagnostics=_parse_timeline(script,chunks,chunk_seconds); notes.extend(parse_notes)
else: raise PromptPlanError(f"unknown prompt mode: {resolved_mode!r}")
return {"magic":PROMPT_PLAN_MAGIC,"schema_version":PROMPT_PLAN_SCHEMA_VERSION,"mode":resolved_mode,"chunks":chunks,"chunk_seconds":chunk_seconds,"prompts":prompts,"hashes":[prompt_hash(p) for p in prompts],"notes":notes}
result={"magic":PROMPT_PLAN_MAGIC,"schema_version":PROMPT_PLAN_SCHEMA_VERSION,"mode":resolved_mode,"chunks":chunks,"chunk_seconds":chunk_seconds,"prompts":prompts,"hashes":[prompt_hash(p) for p in prompts],"notes":notes}
if resolved_mode==PROMPT_MODE_TIMELINE: result["diagnostics"]=diagnostics
return result
def validate_prompt_plan(plan):
if not isinstance(plan,dict) or plan.get("magic")!=PROMPT_PLAN_MAGIC: raise PromptPlanError("invalid H3 Continuum prompt plan")
if int(plan.get("schema_version",-1))!=PROMPT_PLAN_SCHEMA_VERSION: raise PromptPlanError(f"unsupported prompt-plan schema {plan.get('schema_version')}; expected {PROMPT_PLAN_SCHEMA_VERSION}")
@@ -127,6 +178,8 @@ def validate_prompt_plan(plan):
for index,prompt in enumerate(prompts):
_normalize_prompt(prompt,label=f"prompt {index+1}")
if hashes[index]!=prompt_hash(prompt): raise PromptPlanError(f"prompt-plan hash mismatch at chunk {index+1}")
diagnostics=plan.get("diagnostics")
if diagnostics is not None and (not isinstance(diagnostics,list) or not all(isinstance(item,dict) for item in diagnostics)): raise PromptPlanError("prompt-plan diagnostics are invalid")
return plan
def build_sampler_prompt_plan(*,prompt_mode,prompt_script,sequence_prompt,prompt_plan,chunks,chunk_seconds):
chunks=int(chunks); chunk_seconds=float(chunk_seconds)
@@ -143,9 +196,16 @@ def apply_prompt_overrides(plan,overrides):
if value is None: continue
prompts[index]=_normalize_prompt(value,label=f"Clip {index+1} Prompt"); replaced.append(index+1)
if not replaced: return plan
result=dict(plan); result["mode"]=PROMPT_MODE_LIST; result["prompts"]=prompts; result["hashes"]=[prompt_hash(p) for p in prompts]; result["notes"]=list(plan.get("notes") or [])+["external Clip Prompt input(s): "+", ".join(map(str,replaced))]
result=dict(plan); result["mode"]=PROMPT_MODE_LIST; result["prompts"]=prompts; result["hashes"]=[prompt_hash(p) for p in prompts]; result["notes"]=list(plan.get("notes") or [])+["external Clip Prompt input(s): "+", ".join(map(str,replaced))]; result.pop("diagnostics",None)
return validate_prompt_plan(result)
def prompt_plan_report(plan):
plan=validate_prompt_plan(plan); unique=len(set(plan["hashes"])); note="; ".join(plan.get("notes") or [])
result=f"Prompt plan: {plan['mode']}; {plan['chunks']} chunks; {unique} unique prompt(s); {plan['chunk_seconds']:.3f}s per chunk."
return result+(" "+note+"." if note else "")
if note: result+=" "+note+"."
diagnostics=list(plan.get("diagnostics") or [])
if not diagnostics: return result+"\nPrompt Preflight: OK."
lines=[result,"Prompt Preflight:"]
for item in diagnostics:
level=str(item.get("level","info")).upper(); code=str(item.get("code","H3C-P000")); message=str(item.get("message",""))
lines.append(f"- {level} {code}: {message}")
return "\n".join(lines)
+43 -11
View File
@@ -67,19 +67,19 @@ def _preserved_prefix(*,session,prompt_hashes,chunks,reroll_from_chunk,width,hei
elif reroll_from_chunk>0: notes.append(f"preserved chunks 1-{len(preserved)}; regenerated from chunk {reroll_from_chunk}")
return preserved,notes
def _conditioning_cache(*,clip,prompts,assets,final_has_last_frame,reference_assets=None):
def _conditioning_cache(*,clip,prompts,assets,final_has_last_frame,reference_assets=None,reference_audio_assets=None,timeline_video_assets=None):
cache={}; final_index=len(prompts)-1
for index,prompt in enumerate(prompts):
include_last=bool(final_has_last_frame and index==final_index); key=(prompt,include_last)
if key in cache: continue
if reference_assets is not None:
from ..reference import encode_reference_prompt
cache[key]=encode_reference_prompt(clip,prompt,reference_assets)
cache[key]=encode_reference_prompt(clip,prompt,reference_assets,reference_audio_assets=reference_audio_assets,timeline_video_assets=timeline_video_assets)
else:
cache[key]=encode_prompt_conditioning(clip,prompt,first_image=assets.first_image,last_image=assets.last_image if include_last else None)
cache[key]=encode_prompt_conditioning(clip,prompt,first_image=assets.first_image,last_image=assets.last_image if include_last else None,reference_audio_assets=reference_audio_assets,timeline_video_assets=timeline_video_assets)
return cache
def run_sequence(*,model:Any,clip:Any,video_vae:Any,audio_vae:Any,sampler:Any,sigmas:torch.Tensor,first_frame:torch.Tensor|None,last_frame:torch.Tensor|None,prompt_plan:dict[str,Any],width:int,height:int,continuity:str,base_seed:int,audio_continuity:bool,exact_total_duration:bool,diagnostics_mode:str,reroll_from_chunk:int,reroll_nonce:int,strict_compatibility:bool,debug:bool,seam_correction:str=SEAM_CORRECTION_OFF,enable_preview:bool=True,session:dict[str,Any]|None=None,initial_state:dict[str,Any]|None=None,latent_only:bool=False,reference_assets=None):
def run_sequence(*,model:Any,clip:Any,video_vae:Any,audio_vae:Any,sampler:Any,sigmas:torch.Tensor,first_frame:torch.Tensor|None,last_frame:torch.Tensor|None,prompt_plan:dict[str,Any],width:int,height:int,continuity:str,base_seed:int,audio_continuity:bool,exact_total_duration:bool,diagnostics_mode:str,reroll_from_chunk:int,reroll_nonce:int,strict_compatibility:bool,debug:bool,seam_correction:str=SEAM_CORRECTION_OFF,enable_preview:bool=True,session:dict[str,Any]|None=None,initial_state:dict[str,Any]|None=None,latent_only:bool=False,reference_assets=None,reference_audio_source=None,reference_audio_vae=None,timeline_video_source=None):
from ..conditioning import detect_conditioning_mode, conditioning_mode_label
from ..run_storage import get_active_run_storage
storage_controller=get_active_run_storage()
@@ -97,15 +97,27 @@ def run_sequence(*,model:Any,clip:Any,video_vae:Any,audio_vae:Any,sampler:Any,si
from ..reference import validate_reference_prompts
if first_frame is not None or last_frame is not None: raise SequenceRuntimeError("Reference images cannot be combined with First Frame or Last Frame in V3.2")
reference_warning=validate_reference_prompts(prompts,reference_assets.count)
from ..reference_audio import (
combine_reference_audio_identity,
validate_reference_audio_prompts,
)
reference_audio_warning=validate_reference_audio_prompts(prompts,reference_audio_source)
from ..timeline_video import (
combine_timeline_video_identity,
validate_timeline_video_prompts,
)
timeline_video_warning=validate_timeline_video_prompts(prompts,timeline_video_source)
decode_estimate_gib=0.0; available_ram_gib=None
if not latent_only: decode_estimate_gib,available_ram_gib=_check_decode_memory_budget(width=width,height=height,chunks=chunks,chunk_seconds=chunk_seconds)
issues=check_comfy_h3_runtime()
if issues and strict_compatibility: raise SequenceRuntimeError("H3 runtime is incompatible: "+"; ".join(issues))
assets=prepare_identity_assets(video_vae,width=width,height=height,first_frame=first_frame,last_frame=last_frame,encode_latents=False)
sequence_identity_hash=reference_assets.combined_hash if reference_assets is not None else assets.identity_hash
visual_identity_hash=reference_assets.combined_hash if reference_assets is not None else assets.identity_hash
sequence_identity_hash=combine_reference_audio_identity(visual_identity_hash,reference_audio_source)
sequence_identity_hash=combine_timeline_video_identity(sequence_identity_hash,timeline_video_source)
current_model_fingerprint=model_fingerprint(model,extra_wrapper_keys=("h3_continuum_join.apply_model.v1",))
if storage_controller is not None:
stored_session=storage_controller.prepare(model=model,model_fingerprint_value=current_model_fingerprint,clip=clip,video_vae=video_vae,sampler=sampler,sigmas=sigmas,prompt_plan=plan,width=width,height=height,chunk_seconds=chunk_seconds,continuity=continuity,audio_continuity=audio_continuity,base_seed=base_seed,reroll_from_chunk=reroll_from_chunk,reroll_nonce=reroll_nonce,first_frame_hash=assets.first_frame_hash,last_frame_hash=assets.last_frame_hash,identity_hash=sequence_identity_hash,strict_compatibility=strict_compatibility,existing_session=session,reference_contract=reference_assets.contract if reference_assets is not None else None,conditioning_mode=conditioning_mode)
stored_session=storage_controller.prepare(model=model,model_fingerprint_value=current_model_fingerprint,clip=clip,video_vae=video_vae,sampler=sampler,sigmas=sigmas,prompt_plan=plan,width=width,height=height,chunk_seconds=chunk_seconds,continuity=continuity,audio_continuity=audio_continuity,base_seed=base_seed,reroll_from_chunk=reroll_from_chunk,reroll_nonce=reroll_nonce,first_frame_hash=assets.first_frame_hash,last_frame_hash=assets.last_frame_hash,identity_hash=sequence_identity_hash,strict_compatibility=strict_compatibility,existing_session=session,reference_contract=reference_assets.contract if reference_assets is not None else None,conditioning_mode=conditioning_mode,reference_audio_contract=reference_audio_source.contract if reference_audio_source is not None else None,reference_audio_vae=reference_audio_vae,timeline_video_contract=timeline_video_source.contract if timeline_video_source is not None else None)
reroll_nonce=storage_controller.effective_reroll_nonce
if stored_session is not None: session=stored_session
accelerators=accelerator_summary(model)
@@ -114,7 +126,13 @@ def run_sequence(*,model:Any,clip:Any,video_vae:Any,audio_vae:Any,sampler:Any,si
preserved,reuse_notes=_preserved_prefix(session=session,prompt_hashes=prompt_hashes,chunks=chunks,reroll_from_chunk=effective_reroll_from_chunk,width=width,height=height,chunk_seconds=chunk_seconds,identity_hash=sequence_identity_hash)
if reference_assets is not None:
reuse_notes.insert(0,f"Reference conditioning: {reference_assets.count} image(s), size={reference_assets.size_mode}; persistent across all chunks.")
if reference_warning: reuse_notes.append("Warning: "+reference_warning)
if reference_warning: reuse_notes.append(reference_warning)
if reference_audio_source is not None:
reuse_notes.insert(0,"Reference Audio 1 conditioning: persistent across all chunks.")
if reference_audio_warning: reuse_notes.append(reference_audio_warning)
if timeline_video_source is not None:
reuse_notes.insert(0,f"Timeline Video conditioning: chunk-local slices, size={timeline_video_source.size_mode}, resolved={timeline_video_source.target_width}x{timeline_video_source.target_height}.")
if timeline_video_warning: reuse_notes.append(timeline_video_warning)
if session is not None:
old_fingerprint=str(session.get("model_fingerprint",""))
if old_fingerprint and old_fingerprint!=current_model_fingerprint: reuse_notes.append("model/accelerator fingerprint differs from the saved session; accepted chunks were kept")
@@ -124,7 +142,12 @@ def run_sequence(*,model:Any,clip:Any,video_vae:Any,audio_vae:Any,sampler:Any,si
if reference_assets is not None:
from ..reference import encode_reference_latents
reference_assets=encode_reference_latents(video_vae,reference_assets)
cache=_conditioning_cache(clip=clip,prompts=prompts,assets=assets,final_has_last_frame=last_frame is not None,reference_assets=reference_assets)
reference_audio_assets=None
if reference_audio_source is not None:
from ..reference_audio import encode_reference_audio
reference_audio_assets=encode_reference_audio(reference_audio_vae,reference_audio_source)
if timeline_video_source is None:
cache=_conditioning_cache(clip=clip,prompts=prompts,assets=assets,final_has_last_frame=last_frame is not None,reference_assets=reference_assets,reference_audio_assets=reference_audio_assets)
entries=preserved[:]; previous_state=None
if entries: previous_state=entry_to_state(entries[-1])
elif initial_state is not None:
@@ -133,12 +156,18 @@ def run_sequence(*,model:Any,clip:Any,video_vae:Any,audio_vae:Any,sampler:Any,si
initial_frame_count=align_frame_count_up(int(round(chunk_seconds*FPS))); retained_frames=sum(int(entry["plan"]["net_frames"]) for entry in entries); sampling_reports=[]
for sequence_index in range(len(entries),chunks):
prompt=prompts[sequence_index]; prompt_hash_value=prompt_hashes[sequence_index]; is_final=sequence_index==chunks-1; effective_reroll_nonce=int(reroll_nonce) if int(reroll_from_chunk)>0 and sequence_index+1>=int(reroll_from_chunk) else 0; seed=derive_chunk_seed(base_seed,sequence_index,effective_reroll_nonce); motion_score=0.0; video_context=None; audio_context=None; context_before=None
timeline_video_assets=None
chunk_cache=cache
if timeline_video_source is not None:
from ..timeline_video import encode_timeline_video_chunk
timeline_video_assets=encode_timeline_video_chunk(video_vae,timeline_video_source,sequence_index)
chunk_cache=_conditioning_cache(clip=clip,prompts=[prompt],assets=assets,final_has_last_frame=bool(last_frame is not None and is_final),reference_assets=reference_assets,reference_audio_assets=reference_audio_assets,timeline_video_assets=timeline_video_assets)
if previous_state is None:
total_frames=initial_frame_count; latent=empty_h3_latent(width,height,total_frames); conditioning=attach_keyframes(cache[(prompt,bool(last_frame is not None and is_final))],frame_count=total_frames,first_latent=assets.first_latent,last_latent=assets.last_latent if is_final else None); clip_index=1; context_frames=0
total_frames=initial_frame_count; latent=empty_h3_latent(width,height,total_frames); conditioning=attach_keyframes(chunk_cache[(prompt,bool(last_frame is not None and is_final))],frame_count=total_frames,first_latent=assets.first_latent,last_latent=assets.last_latent if is_final else None); clip_index=1; context_frames=0
chunk_plan=make_plan(continuation=False,clip_index=clip_index,total_frames=total_frames,trim_frames=0,width=width,height=height,context_frames=5,state_capacity_frames=largest_context_capacity(total_frames),requested_extend_seconds=chunk_seconds,debug=debug); reason="initial clip"
else:
context_frames,motion_score,reason=choose_context_frames(continuity,previous_state); desired_cumulative=int(round((sequence_index+1)*chunk_seconds*FPS)); requested_new_frames=max(1,desired_cumulative-retained_frames); shape=make_extension_shape(context_frames,requested_new_frames/FPS); latent=empty_h3_latent(width,height,shape.total_frames)
base_conditioning=attach_keyframes(cache[(prompt,bool(last_frame is not None and is_final))],frame_count=shape.total_frames,first_latent=assets.first_latent,last_latent=assets.last_latent if is_final else None)
base_conditioning=attach_keyframes(chunk_cache[(prompt,bool(last_frame is not None and is_final))],frame_count=shape.total_frames,first_latent=assets.first_latent,last_latent=assets.last_latent if is_final else None)
video_context,audio_context,grid_offset=select_context(previous_state,context_frames,include_audio=bool(audio_continuity)); context_before=context_fingerprint(video_context,audio_context)
conditioning=prepare_conditioning(base_conditioning,video_context=video_context,audio_context=audio_context,audio_grid_offset=grid_offset,context_frames=context_frames,new_frame_count=shape.total_frames,first_frame_policy=POLICY_REPLACE,preserve_last_frame=True)
clip_index=int(previous_state["clip_index"])+1; chunk_plan=make_plan(continuation=True,clip_index=clip_index,total_frames=shape.total_frames,trim_frames=context_frames,width=width,height=height,context_frames=context_frames,state_capacity_frames=largest_context_capacity(shape.net_new_frames),requested_extend_seconds=chunk_seconds,debug=debug)
@@ -149,11 +178,14 @@ def run_sequence(*,model:Any,clip:Any,video_vae:Any,audio_vae:Any,sampler:Any,si
if storage_controller is not None: storage_controller.commit_chunk(entry, position=sequence_index)
retained_frames+=int(chunk_plan["net_frames"])
sampling_reports.append(f"chunk {sequence_index+1}/{chunks}: seed={seed}, frames={chunk_plan['total_frames']}, trim={chunk_plan['trim_frames']}, retained_total={retained_frames}, context={context_frames} ({reason}), motion={motion_score:.6f}, "+(f"interop=emitted actual_prefix={CONTINUUM_ACTUAL_PREFIX_STEPS} consumer=not_observable" if context_before is not None else "interop=not_emitted"))
del sampled,latent,conditioning,chunk_model
del sampled,latent,conditioning,chunk_model,chunk_cache
if timeline_video_assets is not None: del timeline_video_assets
if len(entries)!=chunks: raise SequenceRuntimeError(f"internal sequence length mismatch: expected {chunks}, got {len(entries)}")
if latent_only:
last_state=entry_to_state(entries[-1]); parent_id=session.get("session_id") if session is not None else None
settings={"continuity":continuity,"audio_continuity":bool(audio_continuity),"exact_total_duration":False,"prompt_mode":plan["mode"],"conditioning_mode":conditioning_mode,"base_seed":int(base_seed),"reroll_nonce":int(reroll_nonce),"diagnostics_mode":diagnostics_mode,"initial_state_source":initial_state is not None,"latent_first":True,"first_frame_hash":assets.first_frame_hash,"last_frame_hash":assets.last_frame_hash,"reference_contract":reference_assets.contract if reference_assets is not None else None}
if reference_audio_source is not None: settings["reference_audio_contract"]=reference_audio_source.contract
if timeline_video_source is not None: settings["timeline_video_contract"]=timeline_video_source.contract
new_session=make_session(chunks=entries,width=width,height=height,chunk_seconds=chunk_seconds,identity_hash=sequence_identity_hash,model_fingerprint_value=current_model_fingerprint,parent_session_id=parent_id,reroll_from_chunk=int(reroll_from_chunk),settings=settings)
report_lines=[f"H3 Continuum V3 {PACKAGE_VERSION}",f"Conditioning mode: {conditioning_mode_label(conditioning_mode)}.",prompt_plan_report(plan),"Decode: external ComfyUI Core VAE nodes; full raw AV chunks retained.",accelerators,"Execution: conditioning precomputed; single call-local MODEL clone per chunk; no internal VAE decode.",*reuse_notes]
if diagnostics_mode!=DIAGNOSTICS_OFF: report_lines.extend(sampling_reports)
+132 -2
View File
@@ -20,6 +20,16 @@ from .plan import FPS, validate_assembly_plan
AUDIO_SEAM_OFF = "Off"
AUDIO_SEAM_AUTO = "Auto"
AUDIO_SEAM_OPTIONS = (AUDIO_SEAM_OFF, AUDIO_SEAM_AUTO)
VIDEO_SEAM_OFF = "Off"
VIDEO_SEAM_ANALYZE = "Analyze Only"
VIDEO_SEAM_AUTO = "Auto"
VIDEO_SEAM_AUTO_2 = "Auto 2"
VIDEO_SEAM_ANALYSIS_OPTIONS = (
VIDEO_SEAM_AUTO,
VIDEO_SEAM_AUTO_2,
VIDEO_SEAM_ANALYZE,
VIDEO_SEAM_OFF,
)
def _singleton(value: Any, name: str) -> Any:
@@ -224,7 +234,7 @@ class H3ContinuumAssembleV3:
"audio_seam": (
AUDIO_SEAM_OPTIONS,
{
"default": AUDIO_SEAM_OFF,
"default": AUDIO_SEAM_AUTO,
"display_name": "Audio Seam",
"tooltip": (
"Auto corrects only decoded audio boundaries; "
@@ -274,4 +284,124 @@ _assemble_decoded_chunks_v300 = assemble_decoded_chunks
def assemble_decoded_chunks(*args, **kwargs):
return _assemble_with_hardening(_assemble_decoded_chunks_v300, args, kwargs)
return _assemble_with_hardening(_assemble_decoded_chunks_v300, args, kwargs)
class H3ContinuumAssembleSeamExperimental(H3ContinuumAssembleV3):
DESCRIPTION = (
"Analyze decoded chunk boundaries and apply guarded video seam correction."
)
SEARCH_ALIASES = ["H3 seam analysis", "H3 boundary flicker analysis"]
@classmethod
def INPUT_TYPES(cls):
schema = super().INPUT_TYPES()
required = dict(schema["required"])
diagnostics = required.pop("diagnostics")
required["video_seam"] = (
VIDEO_SEAM_ANALYSIS_OPTIONS,
{
"default": VIDEO_SEAM_AUTO,
"display_name": "Video Seam",
"tooltip": (
"Analyze Only reports decoded video boundaries without changing them. "
"Auto applies the validated transient and micro-flash correction. "
"Auto 2 experimentally adds qualified exposure-ramp smoothing."
),
},
)
required["diagnostics"] = diagnostics
schema["required"] = required
return schema
def assemble(
self,
images,
audio,
assembly_plan,
exact_total_duration,
audio_seam,
video_seam,
diagnostics,
):
mode = str(_singleton(video_seam, "video_seam"))
if mode not in VIDEO_SEAM_ANALYSIS_OPTIONS:
raise ValueError(f"unknown Video Seam mode: {mode!r}")
if mode == VIDEO_SEAM_OFF:
return super().assemble(
images,
audio,
assembly_plan,
exact_total_duration,
audio_seam,
diagnostics,
)
image_chunks = _chunk_list(images)
plan = _singleton(assembly_plan, "assembly_plan")
analyses = []
analysis_error = None
actions = {}
try:
from .video_seam import (
analyze_decoded_boundaries,
correct_decoded_boundaries,
format_video_boundary_analysis,
)
analyses = analyze_decoded_boundaries(
images=image_chunks,
assembly_plan=plan,
)
if mode in (VIDEO_SEAM_AUTO, VIDEO_SEAM_AUTO_2):
image_chunks, actions = correct_decoded_boundaries(
images=image_chunks,
assembly_plan=plan,
analyses=analyses,
enable_exposure_ramp=mode == VIDEO_SEAM_AUTO_2,
)
except Exception as exc:
analysis_error = exc
result_images, result_audio, report = assemble_decoded_chunks(
images=image_chunks,
audio=_chunk_list(audio),
assembly_plan=plan,
exact_total_duration=bool(
_singleton(exact_total_duration, "exact_total_duration")
),
audio_seam=str(_singleton(audio_seam, "audio_seam")),
diagnostics=str(_singleton(diagnostics, "diagnostics")),
)
if mode == VIDEO_SEAM_ANALYZE:
status = "Video Seam: Analyze Only; decoded frames and audio are unchanged."
elif mode == VIDEO_SEAM_AUTO:
status = (
"Video Seam: Auto; guarded transient and micro-flash correction enabled."
)
else:
status = (
"Video Seam: Auto 2 (Experimental); guarded transient, micro-flash, "
"and exposure-ramp correction enabled."
)
report = report.replace("Video seam correction is disabled.", status, 1)
if analysis_error is None:
lines = [
format_video_boundary_analysis(
item,
action=(
"analysis only"
if mode == VIDEO_SEAM_ANALYZE
else actions.get(item.boundary_index, "kept native boundary")
),
)
for item in analyses
]
if not lines:
lines = [f"Video Seam {mode}: no decoded chunk boundary to analyze."]
else:
lines = [
f"Video Seam {mode}: native output preserved; analysis unavailable "
f"({type(analysis_error).__name__}: {analysis_error})"
]
return result_images, result_audio, report.rstrip() + "\n" + "\n".join(lines)
+112 -24
View File
@@ -12,8 +12,9 @@ from ..v2.nodes import (
V2_CONTINUITY_OPTIONS,
validate_sparse_prompt_overrides,
)
from .assembly import H3ContinuumAssembleV3
from .assembly import H3ContinuumAssembleSeamExperimental, H3ContinuumAssembleV3
from .plan import make_assembly_plan
from ..timeline_video import TIMELINE_VIDEO_SIZE_OPTIONS
REGENERATE_AUTO = "Auto"
@@ -53,24 +54,12 @@ def _validate_regenerate_storage(run_storage: str, regenerate_from: int) -> None
def _validate_reference_checkpoint(
prompt, unique_id, *, strict_compatibility: bool
) -> str:
from ..graph_contract import (
CHECKPOINT_FL2VA,
CHECKPOINT_REF2VA,
classify_h3_checkpoint,
)
from ..graph_contract import classify_h3_checkpoint
classification = classify_h3_checkpoint(prompt, unique_id)
if strict_compatibility and classification != CHECKPOINT_REF2VA:
if classification == CHECKPOINT_FL2VA:
detail = "an FL2VA checkpoint is connected"
else:
detail = "the base checkpoint cannot be verified as Ref2VA"
raise ValueError(
"Reference Images require a verified MiniMax H3 Ref2VA MODEL when "
f"Strict Compatibility is enabled; {detail}. Disable Strict "
"Compatibility only for experimental FL2VA/unknown combinations."
)
return classification
# Checkpoint choice is diagnostic only. Strict Compatibility remains
# reserved for H3 contracts that are actually unsafe or unsupported.
_ = strict_compatibility
return classify_h3_checkpoint(prompt, unique_id)
class H3ContinuumAdvancedV3:
@@ -269,6 +258,9 @@ class H3ContinuumSamplerV3:
prompt_overrides=None,
advanced=None,
reference_assets=None,
reference_audio_source=None,
reference_audio_vae=None,
timeline_video_source=None,
):
if prompt_overrides is not None and not isinstance(prompt_overrides, dict):
raise TypeError(
@@ -339,6 +331,9 @@ class H3ContinuumSamplerV3:
show_preview=advanced_values["show_preview"],
latent_only=True,
reference_assets=reference_assets,
reference_audio_source=reference_audio_source,
reference_audio_vae=reference_audio_vae,
timeline_video_source=timeline_video_source,
**clip_prompt_inputs,
)
@@ -539,6 +534,9 @@ class H3ContinuumSamplerProduction(H3ContinuumSamplerV3):
"last_frame": ("IMAGE",),
"reference_image_1": ("IMAGE",),
"reference_image_2": ("IMAGE",),
"reference_image_3": ("IMAGE",),
"reference_audio_1": ("AUDIO",),
"reference_audio_vae": ("VAE",),
},
"hidden": {
"prompt": "PROMPT",
@@ -579,8 +577,13 @@ class H3ContinuumSamplerProduction(H3ContinuumSamplerV3):
prompt_overrides=None,
prompt=None,
unique_id=None,
reference_image_3=None,
reference_audio_1=None,
reference_audio_vae=None,
timeline_video_source=None,
):
from ..reference import prepare_reference_assets
from ..reference_audio import prepare_reference_audio_source
regenerate_from = _regenerate_from_value(
reroll_from_chunk,
chunks=int(chunks),
@@ -591,13 +594,18 @@ class H3ContinuumSamplerProduction(H3ContinuumSamplerV3):
output_width=int(width),
output_height=int(height),
size_mode=reference_size,
reference_image_3=reference_image_3,
)
reference_audio_source = prepare_reference_audio_source(
reference_audio_1,
reference_audio_vae,
)
if reference_assets is not None and (first_frame is not None or last_frame is not None):
raise ValueError(
"V3.2 Reference Images cannot be combined with First Frame or Last Frame"
"Reference Images cannot be combined with First Frame or Last Frame"
)
reference_checkpoint = None
if reference_assets is not None:
if reference_assets is not None or timeline_video_source is not None:
reference_checkpoint = _validate_reference_checkpoint(
prompt,
unique_id,
@@ -609,11 +617,10 @@ class H3ContinuumSamplerProduction(H3ContinuumSamplerV3):
return str(report)
if reference_checkpoint == "ref2va":
status = "Ref2VA verified."
elif reference_checkpoint == "fl2va":
status = "FL2VA; allowed, but reference fidelity may differ from Ref2VA."
else:
status = (
f"{reference_checkpoint}; Experimental because Strict "
"Compatibility is disabled."
)
status = "unverified; execution allowed, Core contract errors remain fatal."
return str(report) + "\nReference MODEL: " + status
def execute():
@@ -634,6 +641,9 @@ class H3ContinuumSamplerProduction(H3ContinuumSamplerV3):
first_frame=first_frame,
prompt_overrides=prompt_overrides,
reference_assets=reference_assets,
reference_audio_source=reference_audio_source,
reference_audio_vae=reference_audio_vae,
timeline_video_source=timeline_video_source,
advanced={
"audio_continuity": bool(audio_continuity),
"diagnostics": diagnostics,
@@ -680,16 +690,94 @@ class H3ContinuumSamplerProduction(H3ContinuumSamplerV3):
return video_latents, audio_latents, assembly_plan, report
class H3ContinuumSamplerTimelineVideo(H3ContinuumSamplerProduction):
"""Chunk-local Timeline Video facade over the stable engine."""
DEPRECATED = False
DESCRIPTION = (
"Timeline Video sampler. It slices one Core VIDEO per chunk, "
"resizes only that slice, and reuses the stable Continuum sampling engine."
)
SEARCH_ALIASES = [
"H3 Continuum Timeline Video",
"MiniMax H3 video reference timeline",
]
@classmethod
def INPUT_TYPES(cls):
schema = super().INPUT_TYPES()
required = {}
for name, definition in schema["required"].items():
required[name] = definition
if name == "reference_size":
required["timeline_video_size"] = (
TIMELINE_VIDEO_SIZE_OPTIONS,
{
"default": TIMELINE_VIDEO_SIZE_OPTIONS[0],
"display_name": "Timeline Video Size",
"advanced": True,
"tooltip": (
"Efficient limits each chunk-local reference slice to about 0.4 MP. "
"Match Output uses the output pixel area and may be substantially heavier."
),
},
)
schema["required"] = required
optional = dict(schema.get("optional", {}))
optional["timeline_video"] = (
"VIDEO",
{
"tooltip": (
"Optional. One continuous Core VIDEO covering every configured chunk. "
"When omitted or bypassed, the node uses the standard conditioning path. "
"Its audio is ignored; use the normal audio inputs for generated audio."
)
},
)
schema["optional"] = optional
return schema
def run(
self,
timeline_video=None,
timeline_video_size=TIMELINE_VIDEO_SIZE_OPTIONS[0],
**kwargs,
):
if timeline_video is None:
return super().run(**kwargs)
from ..timeline_video import prepare_timeline_video_source
source = prepare_timeline_video_source(
timeline_video,
chunks=int(kwargs["chunks"]),
chunk_seconds=float(kwargs["chunk_seconds"]),
output_width=int(kwargs["width"]),
output_height=int(kwargs["height"]),
size_mode=str(timeline_video_size),
)
return super().run(timeline_video_source=source, **kwargs)
from .seam_test_source import H3ContinuumSeamTestSource
NODE_CLASS_MAPPINGS = {
"H3ContinuumSamplerProduction": H3ContinuumSamplerProduction,
"H3ContinuumSamplerTimelineVideo": H3ContinuumSamplerTimelineVideo,
"H3ContinuumSamplerV3": H3ContinuumSamplerV3,
"H3ContinuumAdvancedV3": H3ContinuumAdvancedV3,
"H3ContinuumAssembleV3": H3ContinuumAssembleV3,
"H3ContinuumAssembleSeamExperimental": H3ContinuumAssembleSeamExperimental,
"H3ContinuumSeamTestSource": H3ContinuumSeamTestSource,
}
NODE_DISPLAY_NAME_MAPPINGS = {
"H3ContinuumSamplerProduction": "H3 Continuum Sampler V3.2",
"H3ContinuumSamplerTimelineVideo": "H3 Continuum Timeline Video",
"H3ContinuumSamplerV3": "H3 Continuum Sampler V3",
"H3ContinuumAdvancedV3": "H3 Continuum Advanced V3",
"H3ContinuumAssembleV3": "H3 Continuum Assemble V3",
"H3ContinuumAssembleSeamExperimental": "H3 Continuum Assemble + Seam",
"H3ContinuumSeamTestSource": "H3 Continuum Seam Test Source (Experimental)",
}
+236
View File
@@ -0,0 +1,236 @@
"""Deterministic decoded-chunk source for video seam validation."""
from __future__ import annotations
import math
from typing import Any
import torch
import torch.nn.functional as F
from ..hardening import enrich_assembly_plan
from .plan import (
ASSEMBLY_PLAN_MAGIC,
ASSEMBLY_PLAN_SCHEMA_VERSION,
FPS,
validate_assembly_plan,
)
TEST_SIZE_256 = "256 px (Fast)"
TEST_SIZE_512 = "512 px"
TEST_SIZE_INPUT = "Input Size"
TEST_SIZE_OPTIONS = (TEST_SIZE_256, TEST_SIZE_512, TEST_SIZE_INPUT)
def _prepare_image(image: Any, size_mode: str) -> torch.Tensor:
if not torch.is_tensor(image) or image.ndim != 4 or int(image.shape[-1]) < 3:
raise ValueError("image must be an IMAGE tensor [B,H,W,C]")
if int(image.shape[0]) != 1:
raise ValueError("Seam Test Source requires exactly one input image")
frame = image[0, ..., :3].detach().to(device="cpu", dtype=torch.float32)
if not bool(torch.isfinite(frame).all().item()):
raise ValueError("input image contains NaN or Inf")
frame = frame.clamp(0.0, 1.0)
if size_mode == TEST_SIZE_INPUT:
return frame.contiguous()
limits = {TEST_SIZE_256: 256, TEST_SIZE_512: 512}
if size_mode not in limits:
raise ValueError(f"unknown Test Resolution: {size_mode!r}")
height, width = int(frame.shape[0]), int(frame.shape[1])
scale = min(1.0, float(limits[size_mode]) / float(max(height, width)))
target_height = max(1, int(round(height * scale)))
target_width = max(1, int(round(width * scale)))
if (target_height, target_width) == (height, width):
return frame.contiguous()
resized = F.interpolate(
frame.permute(2, 0, 1).unsqueeze(0),
size=(target_height, target_width),
mode="bilinear",
align_corners=False,
)
return resized[0].permute(1, 2, 0).contiguous()
def _repeat_frame(frame: torch.Tensor, count: int) -> torch.Tensor:
return frame.unsqueeze(0).expand(int(count), -1, -1, -1).clone()
def _ramp_chunk(
previous_anchor: torch.Tensor,
*,
context_frames: int,
net_frames: int,
exposure_change: float,
) -> tuple[torch.Tensor, torch.Tensor]:
context = _repeat_frame(previous_anchor, context_frames)
ramp_count = 5
ramp_factors = torch.linspace(
1.0 - exposure_change,
1.0 - exposure_change * 2.0,
steps=ramp_count,
dtype=torch.float32,
)
ramp = (
previous_anchor.unsqueeze(0)
* ramp_factors.reshape(-1, 1, 1, 1)
).clamp(0.0, 1.0)
next_anchor = ramp[-1].contiguous()
tail = _repeat_frame(next_anchor, net_frames - ramp_count)
return torch.cat((context, ramp, tail), dim=0).contiguous(), next_anchor
def _silent_audio(total_frames: int, sample_rate: int) -> dict[str, Any]:
samples = int(math.ceil(total_frames / FPS * sample_rate)) + 8
return {
"waveform": torch.zeros((1, 2, samples), dtype=torch.float32),
"sample_rate": int(sample_rate),
}
def _assembly_plan(width: int, height: int) -> dict[str, Any]:
chunks = [
{
"sequence_index": 1,
"chunk_index": 1,
"total_frames": 124,
"trim_frames": 0,
"net_frames": 124,
"context_frames": 0,
"expected_video_latent_t": 32,
"expected_audio_latent_t": 207,
},
{
"sequence_index": 2,
"chunk_index": 2,
"total_frames": 141,
"trim_frames": 22,
"net_frames": 119,
"context_frames": 22,
"expected_video_latent_t": 36,
"expected_audio_latent_t": 235,
},
{
"sequence_index": 3,
"chunk_index": 3,
"total_frames": 141,
"trim_frames": 22,
"net_frames": 119,
"context_frames": 22,
"expected_video_latent_t": 36,
"expected_audio_latent_t": 235,
},
]
plan = {
"magic": ASSEMBLY_PLAN_MAGIC,
"schema_version": ASSEMBLY_PLAN_SCHEMA_VERSION,
"fps": FPS,
"width": int(width),
"height": int(height),
"chunk_seconds": 5.0,
"target_frames": 360,
"preserve_final_frame": True,
"chunks": chunks,
}
enrich_assembly_plan(plan)
return validate_assembly_plan(plan)
class H3ContinuumSeamTestSource:
DESCRIPTION = (
"Create deterministic decoded chunks for testing Video Seam modes. "
"Chunk 2 and Chunk 3 each begin with a controlled exposure ramp. "
"This node performs no H3 sampling."
)
SEARCH_ALIASES = ["H3 seam test", "H3 exposure ramp test"]
@classmethod
def INPUT_TYPES(cls):
return {
"required": {
"image": ("IMAGE",),
"exposure_change": (
"FLOAT",
{
"default": 0.08,
"min": 0.01,
"max": 0.20,
"step": 0.01,
"display_name": "Exposure Change",
"tooltip": (
"8% is the controlled default. Each new chunk ramps "
"from one step darker to two steps darker."
),
},
),
"test_resolution": (
TEST_SIZE_OPTIONS,
{
"default": TEST_SIZE_256,
"display_name": "Test Resolution",
"tooltip": (
"256 px is recommended for fast seam testing. "
"Input Size can require several GiB of RAM."
),
},
),
}
}
RETURN_TYPES = (
"IMAGE",
"AUDIO",
"H3_CONTINUUM_ASSEMBLY_PLAN",
"STRING",
)
RETURN_NAMES = ("images", "audio", "assembly_plan", "instructions")
OUTPUT_IS_LIST = (True, True, False, False)
FUNCTION = "create"
CATEGORY = "MiniMax H3/Continuum/Testing"
EXPERIMENTAL = True
def create(
self,
image,
exposure_change=0.08,
test_resolution=TEST_SIZE_256,
):
change = float(exposure_change)
if not math.isfinite(change) or not 0.01 <= change <= 0.20:
raise ValueError("Exposure Change must be between 0.01 and 0.20")
base = _prepare_image(image, str(test_resolution))
chunk_1 = _repeat_frame(base, 124)
chunk_2, anchor_2 = _ramp_chunk(
base,
context_frames=22,
net_frames=119,
exposure_change=change,
)
chunk_3, _anchor_3 = _ramp_chunk(
anchor_2,
context_frames=22,
net_frames=119,
exposure_change=change,
)
images = [chunk_1, chunk_2, chunk_3]
audio = [
_silent_audio(124, 32000),
_silent_audio(141, 32000),
_silent_audio(141, 32000),
]
plan = _assembly_plan(int(base.shape[1]), int(base.shape[0]))
instructions = (
"H3 Continuum Seam Test Source\n"
"1. Connect images, audio, and assembly_plan to the matching inputs "
"of H3 Continuum Assemble + Seam.\n"
"2. Set Audio Seam=Off and exact_total_duration=true.\n"
"3. Run Video Seam=Analyze Only, then Auto, then Auto 2.\n"
"4. Analyze Only should report class=exposure_ramp at both boundaries.\n"
"5. Auto should keep both native boundaries. Auto 2 should report "
"normalized exposure/color on 4 exposure ramp boundary frame(s).\n"
f"Source: 3 x 5 sec, 24 fps, {base.shape[1]}x{base.shape[0]}, "
f"exposure change={change:.0%}."
)
return images, audio, plan, instructions
+528
View File
@@ -0,0 +1,528 @@
"""Read-only decoded video-boundary analysis for H3 Continuum V3."""
from __future__ import annotations
from dataclasses import dataclass
import math
from typing import Any
import torch
import torch.nn.functional as F
from .plan import validate_assembly_plan
COMPARE_LONG_SIDE = 192
MAX_REWIND_FRAMES = 2
FLASH_WINDOW_FRAMES = 6
FLASH_TILE_GRID = 4
MIN_FLASH_LUMA_SHIFT = 0.01
MIN_FLASH_REVERSAL = 0.35
MIN_FLASH_GLOBAL_FRACTION = 0.75
MIN_ANOMALY_RATIO = 1.35
MIN_RELATIVE_IMPROVEMENT = 0.06
MIN_AUTO_FLASH_REVERSAL = 0.70
MIN_AUTO_FLASH_IMPROVEMENT = 0.70
SMALLER_SHIFT_TOLERANCE = 0.03
MIN_MICRO_FLASH_LUMA_SHIFT = 0.003
MIN_MICRO_FLASH_REVERSAL = 0.25
MIN_MICRO_FLASH_GLOBAL_FRACTION = 0.70
MAX_EXPOSURE_RAMP_REVERSAL = 0.25
MIN_MOTION_CROSS_DELTA = 0.006
MIN_MOTION_JUMP_RATIO = 1.60
@dataclass(frozen=True)
class VideoBoundaryAnalysis:
boundary_index: int
nominal_error: float
baseline_error: float
anomaly_ratio: float
recommended_rewind: int
best_error: float
improvement: float
luma_delta: float
chroma_delta: float
edge_delta: float
scene_cut_score: float
scene_cut: bool
flash_luma_shift: float
flash_reversal: float
flash_global_fraction: float
transient_flash_candidate: bool
cross_frame_delta: float
motion_baseline_delta: float
motion_jump_ratio: float
micro_flash_candidate: bool
exposure_ramp_candidate: bool
motion_hitch_candidate: bool
classification: str
reason: str
def _validate_frames(frames: Any, label: str) -> None:
if not torch.is_tensor(frames) or frames.ndim != 4 or frames.shape[-1] < 3:
raise ValueError(f"{label} must be an IMAGE tensor [T,H,W,C]")
if int(frames.shape[0]) < 1 or int(frames.shape[1]) < 1 or int(frames.shape[2]) < 1:
raise ValueError(f"{label} must not be empty")
def _downsample_rgb(frames: torch.Tensor) -> torch.Tensor:
_validate_frames(frames, "video seam frames")
rgb = frames[..., :3].detach().to(device="cpu", dtype=torch.float32)
rgb = rgb.permute(0, 3, 1, 2)
height, width = int(rgb.shape[-2]), int(rgb.shape[-1])
scale = min(1.0, COMPARE_LONG_SIDE / float(max(height, width)))
target_height = max(1, int(round(height * scale)))
target_width = max(1, int(round(width * scale)))
if (target_height, target_width) != (height, width):
rgb = F.interpolate(
rgb,
size=(target_height, target_width),
mode="bilinear",
align_corners=False,
)
rgb = rgb.permute(0, 2, 3, 1).clamp(0.0, 1.0)
if not bool(torch.isfinite(rgb).all().item()):
raise ValueError("video seam comparison contains NaN or Inf")
return rgb
def _luma(frame: torch.Tensor) -> torch.Tensor:
weights = frame.new_tensor((0.2126, 0.7152, 0.0722))
return torch.sum(frame * weights, dim=-1)
def _frame_delta(left: torch.Tensor, right: torch.Tensor) -> float:
return float(torch.mean(torch.abs(left - right)).item())
def _prediction_error(history: torch.Tensor, candidate: torch.Tensor) -> float:
if int(history.shape[0]) < 3:
raise ValueError("temporal prediction requires three history frames")
recent_velocity = history[-1] - history[-2]
prior_velocity = history[-2] - history[-3]
predicted = (
history[-1] + recent_velocity * 0.65 + prior_velocity * 0.35
).clamp(0.0, 1.0)
motion = torch.mean(torch.abs(recent_velocity), dim=-1)
motion_scale = motion / motion.mean().clamp_min(1.0e-6)
weights = (1.0 + motion_scale).clamp(1.0, 4.0).unsqueeze(-1)
value = float(torch.mean((predicted - candidate).square() * weights).item())
if not math.isfinite(value):
raise ValueError("video seam prediction score is not finite")
return max(0.0, value)
def _baseline_prediction_error(previous: torch.Tensor) -> float:
recent = previous[-min(8, int(previous.shape[0])) :]
errors = [
_prediction_error(recent[:index], recent[index])
for index in range(3, int(recent.shape[0]))
]
if not errors:
return 0.0
return float(torch.tensor(errors, dtype=torch.float64).median().item())
def _edge_delta(left: torch.Tensor, right: torch.Tensor) -> float:
left_y = _luma(left)
right_y = _luma(right)
left_x = left_y[:, 1:] - left_y[:, :-1]
right_x = right_y[:, 1:] - right_y[:, :-1]
left_v = left_y[1:, :] - left_y[:-1, :]
right_v = right_y[1:, :] - right_y[:-1, :]
horizontal = torch.mean(torch.abs(left_x - right_x)) if left_x.numel() else left_y.new_tensor(0.0)
vertical = torch.mean(torch.abs(left_v - right_v)) if left_v.numel() else left_y.new_tensor(0.0)
return float(((horizontal + vertical) * 0.5).item())
def _scene_cut_metrics(previous: torch.Tensor, current: torch.Tensor) -> tuple[float, bool]:
cross_delta = _frame_delta(previous[-1], current[0])
previous_internal = _frame_delta(previous[-2], previous[-1])
if int(current.shape[0]) >= 3:
current_internal = 0.5 * (
_frame_delta(current[0], current[1])
+ _frame_delta(current[1], current[2])
)
elif int(current.shape[0]) == 2:
current_internal = _frame_delta(current[0], current[1])
else:
current_internal = cross_delta
denominator = cross_delta + previous_internal + current_internal + 1.0e-8
score = cross_delta / denominator
persistent_new_scene = (
int(current.shape[0]) >= 3
and cross_delta >= 0.12
and current_internal <= cross_delta * 0.35
and cross_delta >= max(0.12, previous_internal * 3.0)
)
return max(0.0, min(1.0, score)), persistent_new_scene
def _transient_flash_metrics(
previous: torch.Tensor,
current: torch.Tensor,
) -> tuple[float, float, float]:
"""Measure a broad boundary exposure pulse that quickly returns."""
previous_y = _luma(previous[-1])
current_y = _luma(current[:FLASH_WINDOW_FRAMES])
shifts = torch.mean(current_y - previous_y.unsqueeze(0), dim=(1, 2))
initial_shift = float(torch.abs(shifts[0]).item())
if int(shifts.shape[0]) > 1 and initial_shift > 1.0e-8:
closest_later = float(torch.min(torch.abs(shifts[1:])).item())
reversal = max(0.0, min(1.0, 1.0 - closest_later / initial_shift))
else:
reversal = 0.0
height, width = int(previous_y.shape[0]), int(previous_y.shape[1])
tile_height = max(1, height // FLASH_TILE_GRID)
tile_width = max(1, width // FLASH_TILE_GRID)
delta = current_y[0] - previous_y
sign = 1.0 if float(shifts[0].item()) >= 0.0 else -1.0
tile_matches = []
for top in range(0, height, tile_height):
for left in range(0, width, tile_width):
tile = delta[
top : min(height, top + tile_height),
left : min(width, left + tile_width),
]
tile_shift = float(torch.mean(tile).item())
tile_matches.append(
tile_shift * sign >= min(MIN_FLASH_LUMA_SHIFT * 0.5, initial_shift * 0.5)
)
global_fraction = sum(tile_matches) / max(1, len(tile_matches))
return initial_shift, reversal, float(global_fraction)
def _temporal_motion_metrics(
previous: torch.Tensor,
current: torch.Tensor,
) -> tuple[float, float, float]:
"""Compare the boundary transition with nearby native frame motion."""
cross_delta = _frame_delta(previous[-1], current[0])
internal_deltas: list[float] = []
previous_start = max(1, int(previous.shape[0]) - 5)
for index in range(previous_start, int(previous.shape[0])):
internal_deltas.append(_frame_delta(previous[index - 1], previous[index]))
current_limit = min(5, int(current.shape[0]))
for index in range(1, current_limit):
internal_deltas.append(_frame_delta(current[index - 1], current[index]))
if internal_deltas:
baseline = float(
torch.tensor(internal_deltas, dtype=torch.float64).median().item()
)
else:
baseline = 0.0
if cross_delta <= 1.0e-8:
ratio = 0.0
else:
ratio = cross_delta / max(baseline, 1.0e-5)
return cross_delta, baseline, ratio
def analyze_video_boundary(
previous_images: torch.Tensor,
current_raw_images: torch.Tensor,
*,
trim_frames: int,
boundary_index: int = 1,
) -> VideoBoundaryAnalysis:
"""Analyze one boundary without modifying either input tensor."""
_validate_frames(previous_images, "previous decoded image chunk")
_validate_frames(current_raw_images, "current decoded image chunk")
trim_frames = int(trim_frames)
if int(previous_images.shape[0]) < 4:
raise ValueError("video seam analysis requires four previous frames")
if trim_frames < 0 or trim_frames >= int(current_raw_images.shape[0]):
raise ValueError("video seam trim position is outside the current chunk")
if trim_frames + 3 > int(current_raw_images.shape[0]):
raise ValueError("video seam analysis requires three retained current frames")
previous = _downsample_rgb(previous_images[-8:])
candidate_start = max(0, trim_frames - MAX_REWIND_FRAMES)
current = _downsample_rgb(
current_raw_images[
candidate_start : trim_frames + FLASH_WINDOW_FRAMES
]
)
nominal_index = trim_frames - candidate_start
nominal = current[nominal_index]
candidate_errors: dict[int, float] = {}
maximum_rewind = min(MAX_REWIND_FRAMES, trim_frames)
for rewind in range(maximum_rewind + 1):
candidate = current[nominal_index - rewind]
candidate_errors[rewind] = _prediction_error(previous, candidate)
nominal_error = candidate_errors[0]
minimum_error = min(candidate_errors.values())
tolerance = minimum_error * SMALLER_SHIFT_TOLERANCE + 1.0e-10
best_rewind = min(
rewind
for rewind, error in candidate_errors.items()
if error <= minimum_error + tolerance
)
best_error = candidate_errors[best_rewind]
baseline_error = _baseline_prediction_error(previous)
anomaly_ratio = nominal_error / max(baseline_error, 1.0e-5)
improvement = (nominal_error - best_error) / max(nominal_error, 1.0e-12)
previous_edge = previous[-1]
previous_y = _luma(previous_edge)
nominal_y = _luma(nominal)
luma_delta = float(torch.mean(torch.abs(previous_y - nominal_y)).item())
previous_chroma = previous_edge - previous_y.unsqueeze(-1)
nominal_chroma = nominal - nominal_y.unsqueeze(-1)
chroma_delta = float(
torch.mean(torch.abs(previous_chroma - nominal_chroma)).item()
)
edge_delta = _edge_delta(previous_edge, nominal)
scene_score, scene_cut = _scene_cut_metrics(
previous,
current[nominal_index : nominal_index + 3],
)
flash_luma_shift, flash_reversal, flash_global_fraction = (
_transient_flash_metrics(previous, current[nominal_index:])
)
cross_frame_delta, motion_baseline_delta, motion_jump_ratio = (
_temporal_motion_metrics(previous, current[nominal_index:])
)
transient_flash_candidate = (
not scene_cut
and flash_luma_shift >= MIN_FLASH_LUMA_SHIFT
and flash_reversal >= MIN_FLASH_REVERSAL
and flash_global_fraction >= MIN_FLASH_GLOBAL_FRACTION
)
micro_flash_candidate = (
not scene_cut
and not transient_flash_candidate
and flash_luma_shift >= MIN_MICRO_FLASH_LUMA_SHIFT
and flash_reversal >= MIN_MICRO_FLASH_REVERSAL
and flash_global_fraction >= MIN_MICRO_FLASH_GLOBAL_FRACTION
)
exposure_ramp_candidate = (
not scene_cut
and not transient_flash_candidate
and not micro_flash_candidate
and anomaly_ratio >= MIN_ANOMALY_RATIO
and flash_luma_shift >= MIN_FLASH_LUMA_SHIFT
and flash_reversal < MAX_EXPOSURE_RAMP_REVERSAL
and flash_global_fraction >= MIN_FLASH_GLOBAL_FRACTION
)
motion_hitch_candidate = (
not scene_cut
and not transient_flash_candidate
and not micro_flash_candidate
and not exposure_ramp_candidate
and cross_frame_delta >= MIN_MOTION_CROSS_DELTA
and motion_jump_ratio >= MIN_MOTION_JUMP_RATIO
)
if scene_cut:
classification = "scene_cut"
elif transient_flash_candidate:
classification = "transient_flash"
elif micro_flash_candidate:
classification = "micro_flash"
elif exposure_ramp_candidate:
classification = "exposure_ramp"
elif motion_hitch_candidate:
classification = "motion_hitch"
else:
classification = "clean_boundary"
recommended_rewind = 0
if scene_cut:
reason = "kept nominal boundary; persistent content change resembles a scene cut"
elif best_rewind == 0:
reason = "kept nominal boundary; it has the lowest prediction error"
elif (
transient_flash_candidate
and flash_reversal >= MIN_AUTO_FLASH_REVERSAL
and improvement >= MIN_AUTO_FLASH_IMPROVEMENT
):
recommended_rewind = best_rewind
reason = f"mild transient flash recommends correcting {best_rewind} frame(s)"
elif anomaly_ratio < MIN_ANOMALY_RATIO:
reason = "kept nominal boundary; anomaly ratio is below the analysis threshold"
elif improvement < MIN_RELATIVE_IMPROVEMENT:
reason = "kept nominal boundary; candidate improvement is below 6%"
else:
recommended_rewind = best_rewind
reason = f"analysis recommends shift {-best_rewind:+d} frame(s)"
return VideoBoundaryAnalysis(
boundary_index=int(boundary_index),
nominal_error=nominal_error,
baseline_error=baseline_error,
anomaly_ratio=anomaly_ratio,
recommended_rewind=recommended_rewind,
best_error=best_error,
improvement=improvement,
luma_delta=luma_delta,
chroma_delta=chroma_delta,
edge_delta=edge_delta,
scene_cut_score=scene_score,
scene_cut=scene_cut,
flash_luma_shift=flash_luma_shift,
flash_reversal=flash_reversal,
flash_global_fraction=flash_global_fraction,
transient_flash_candidate=transient_flash_candidate,
cross_frame_delta=cross_frame_delta,
motion_baseline_delta=motion_baseline_delta,
motion_jump_ratio=motion_jump_ratio,
micro_flash_candidate=micro_flash_candidate,
exposure_ramp_candidate=exposure_ramp_candidate,
motion_hitch_candidate=motion_hitch_candidate,
classification=classification,
reason=reason,
)
def analyze_decoded_boundaries(
*,
images: list[Any],
assembly_plan: dict[str, Any],
) -> list[VideoBoundaryAnalysis]:
"""Analyze every decoded chunk boundary without changing decoded content."""
plan = validate_assembly_plan(assembly_plan)
chunks = list(plan["chunks"])
if len(images) != len(chunks):
raise ValueError("decoded image count does not match the assembly plan")
analyses: list[VideoBoundaryAnalysis] = []
for index in range(1, len(chunks)):
previous_raw = images[index - 1]
current_raw = images[index]
previous_plan = chunks[index - 1]
current_plan = chunks[index]
_validate_frames(previous_raw, f"decoded image chunk {index}")
_validate_frames(current_raw, f"decoded image chunk {index + 1}")
previous_total = int(previous_plan["total_frames"])
previous_trim = int(previous_plan["trim_frames"])
current_total = int(current_plan["total_frames"])
current_trim = int(current_plan["trim_frames"])
previous_segment = previous_raw[:previous_total][previous_trim:]
current_segment = current_raw[:current_total]
analyses.append(
analyze_video_boundary(
previous_segment,
current_segment,
trim_frames=current_trim,
boundary_index=index,
)
)
return analyses
def correct_decoded_boundaries(
*,
images: list[Any],
assembly_plan: dict[str, Any],
analyses: list[VideoBoundaryAnalysis],
enable_exposure_ramp: bool = False,
) -> tuple[list[Any], dict[int, str]]:
"""Normalize qualified transient exposure shifts without changing motion."""
plan = validate_assembly_plan(assembly_plan)
chunks = list(plan["chunks"])
if len(images) != len(chunks):
raise ValueError("decoded image count does not match the assembly plan")
corrected = list(images)
actions: dict[int, str] = {}
for analysis in analyses:
boundary = int(analysis.boundary_index)
correction_kind = "transient flash"
replace_frames = int(analysis.recommended_rewind)
if analysis.micro_flash_candidate:
correction_kind = "micro-flash"
replace_frames = 1
elif enable_exposure_ramp and analysis.exposure_ramp_candidate:
correction_kind = "exposure ramp"
replace_frames = 4
if replace_frames <= 0:
actions[boundary] = "kept native boundary"
continue
if analysis.scene_cut or not (
analysis.transient_flash_candidate
or analysis.micro_flash_candidate
or (enable_exposure_ramp and analysis.exposure_ramp_candidate)
):
actions[boundary] = "kept native boundary; correction guard rejected candidate"
continue
previous_index = boundary - 1
current_index = boundary
if previous_index < 0 or current_index >= len(images):
raise ValueError("video seam boundary index is outside decoded chunks")
previous_raw = images[previous_index]
current_raw = images[current_index]
_validate_frames(previous_raw, f"decoded image chunk {previous_index + 1}")
_validate_frames(current_raw, f"decoded image chunk {current_index + 1}")
previous_plan = chunks[previous_index]
current_plan = chunks[current_index]
previous_total = int(previous_plan["total_frames"])
previous_trim = int(previous_plan["trim_frames"])
current_total = int(current_plan["total_frames"])
current_trim = int(current_plan["trim_frames"])
if current_trim + replace_frames >= current_total:
raise ValueError("video seam correction has no retained recovery frame")
previous_segment = previous_raw[:previous_total][previous_trim:]
if int(previous_segment.shape[0]) < 1:
raise ValueError("video seam correction has no previous retained frame")
current_cpu = current_raw.detach().to(device="cpu").clone()
previous_anchor = previous_segment[-1].detach().to(
device="cpu", dtype=torch.float32
)
recovery_anchor = current_cpu[current_trim + replace_frames].to(
dtype=torch.float32
)
if tuple(previous_anchor.shape) != tuple(recovery_anchor.shape):
raise ValueError("decoded image geometry changed at video seam")
for offset in range(replace_frames):
alpha = float(offset + 1) / float(replace_frames + 1)
original = current_cpu[current_trim + offset].to(dtype=torch.float32)
target = torch.lerp(previous_anchor, recovery_anchor, alpha)
original_mean = original.mean(dim=(0, 1), keepdim=True)
target_mean = target.mean(dim=(0, 1), keepdim=True)
normalized = (original + target_mean - original_mean).clamp(0.0, 1.0)
current_cpu[current_trim + offset].copy_(
normalized.to(dtype=current_cpu.dtype)
)
corrected[current_index] = current_cpu
actions[boundary] = (
f"normalized exposure/color on {replace_frames} {correction_kind} "
"boundary frame(s)"
)
return corrected, actions
def format_video_boundary_analysis(
analysis: VideoBoundaryAnalysis,
*,
action: str = "analysis only",
) -> str:
shift = -int(analysis.recommended_rewind)
return (
f"video seam {analysis.boundary_index}->{analysis.boundary_index + 1}: "
f"anomaly={analysis.anomaly_ratio:.3f}, "
f"prediction={analysis.nominal_error:.6f}->{analysis.best_error:.6f}, "
f"improvement={analysis.improvement:.1%}, shift={shift:+d}, "
f"luma={analysis.luma_delta:.6f}, chroma={analysis.chroma_delta:.6f}, "
f"edge={analysis.edge_delta:.6f}, "
f"scene_cut={'yes' if analysis.scene_cut else 'no'} "
f"flash_shift={analysis.flash_luma_shift:.6f}, "
f"flash_reversal={analysis.flash_reversal:.1%}, "
f"flash_global={analysis.flash_global_fraction:.1%}, "
f"flash_candidate={'yes' if analysis.transient_flash_candidate else 'no'} "
f"class={analysis.classification}, "
f"cross={analysis.cross_frame_delta:.6f}, "
f"motion_base={analysis.motion_baseline_delta:.6f}, "
f"motion_jump={analysis.motion_jump_ratio:.2f}x, "
f"micro_flash={'yes' if analysis.micro_flash_candidate else 'no'}, "
f"exposure_ramp={'yes' if analysis.exposure_ramp_candidate else 'no'}, "
f"motion_hitch={'yes' if analysis.motion_hitch_candidate else 'no'} "
f"({analysis.reason}); action={action}"
)
+1 -1
View File
@@ -1,6 +1,6 @@
"""Package version and public schema identifiers."""
PACKAGE_VERSION = "3.2.1"
PACKAGE_VERSION = "3.3.0"
STATE_SCHEMA_VERSION = 1
PLAN_SCHEMA_VERSION = 1
PUBLIC_API_VERSION = 3
+151
View File
@@ -0,0 +1,151 @@
import { app } from "../../scripts/app.js";
const PRODUCTION_NODE_CLASS = "H3ContinuumSamplerProduction";
const TIMELINE_NODE_CLASS = "H3ContinuumSamplerTimelineVideo";
const PROJECT_WIDGET = "project_id";
const LEGACY_RUN_NAME_WIDGET = "run_name";
const CHUNKS_WIDGET = "chunks";
const REGENERATE_WIDGET = "reroll_from_chunk";
const PROMPT_OVERRIDES_INPUT = "prompt_overrides";
function createProjectId() {
if (globalThis.crypto?.randomUUID) {
return globalThis.crypto.randomUUID();
}
const bytes = new Uint8Array(16);
globalThis.crypto.getRandomValues(bytes);
bytes[6] = (bytes[6] & 0x0f) | 0x40;
bytes[8] = (bytes[8] & 0x3f) | 0x80;
const hex = Array.from(bytes, (value) => value.toString(16).padStart(2, "0")).join("");
return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
}
function findWidget(node, name) {
return node.widgets?.find((widget) => widget.name === name);
}
function hidePersistentWidget(widget) {
if (!widget || widget.__h3ContinuumHidden) {
return;
}
widget.__h3ContinuumHidden = true;
widget.hidden = true;
widget.type = "converted-widget";
widget.options ||= {};
widget.options.hidden = true;
widget.computeSize = () => [0, -4];
}
function removeUnusedInput(node, name) {
const index = node.inputs?.findIndex((input) => input.name === name) ?? -1;
if (index < 0) {
return;
}
const input = node.inputs[index];
if (input.link != null) {
app.graph?.removeLink(input.link);
}
node.removeInput(index);
}
function regenerateOptions(chunks) {
const count = Math.max(1, Math.min(16, Number.parseInt(chunks, 10) || 1));
return ["Auto", ...Array.from({ length: count }, (_, index) => `Chunk ${index + 1}`)];
}
function configureRegenerateFrom(node) {
const chunksWidget = findWidget(node, CHUNKS_WIDGET);
const regenerateWidget = findWidget(node, REGENERATE_WIDGET);
if (!chunksWidget || !regenerateWidget) {
return;
}
const refresh = () => {
const values = regenerateOptions(chunksWidget.value);
regenerateWidget.options ||= {};
regenerateWidget.options.values = values;
const numeric = typeof regenerateWidget.value === "number"
? regenerateWidget.value
: Number.parseInt(String(regenerateWidget.value).replace(/^Chunk\s+/, ""), 10);
if (regenerateWidget.value === "Auto" || numeric === 0) {
regenerateWidget.value = "Auto";
} else if (Number.isInteger(numeric) && numeric >= 1 && numeric < values.length) {
regenerateWidget.value = `Chunk ${numeric}`;
} else {
regenerateWidget.value = "Auto";
}
};
if (!chunksWidget.__h3ContinuumRegenerateCallback) {
const previous = chunksWidget.callback;
chunksWidget.callback = function(value, ...args) {
const result = previous?.call(this, value, ...args);
refresh();
return result;
};
chunksWidget.__h3ContinuumRegenerateCallback = true;
}
refresh();
}
function configureNode(node) {
const isProduction = node.comfyClass === PRODUCTION_NODE_CLASS;
const isTimeline = node.comfyClass === TIMELINE_NODE_CLASS;
if (!isProduction && !isTimeline) {
return null;
}
const projectWidget = findWidget(node, PROJECT_WIDGET);
if (isProduction) {
if (projectWidget && !String(projectWidget.value || "").trim()) {
projectWidget.value = createProjectId();
}
hidePersistentWidget(findWidget(node, LEGACY_RUN_NAME_WIDGET));
removeUnusedInput(node, PROMPT_OVERRIDES_INPUT);
}
hidePersistentWidget(projectWidget);
configureRegenerateFrom(node);
node.setDirtyCanvas?.(true, true);
return isProduction ? projectWidget : null;
}
function configureNodeAfterSetup(node) {
configureNode(node);
setTimeout(() => configureNode(node), 0);
setTimeout(() => configureNode(node), 100);
}
app.registerExtension({
name: "H3Continuum.ProjectId",
nodeCreated(node) {
configureNodeAfterSetup(node);
},
loadedGraphNode(node) {
configureNodeAfterSetup(node);
},
afterConfigureGraph() {
for (const node of app.graph?._nodes || []) {
configureNodeAfterSetup(node);
}
},
async beforeQueuePrompt(prompt) {
const seen = new Set();
for (const node of app.graph?._nodes || []) {
const projectWidget = configureNode(node);
if (!projectWidget) {
continue;
}
let projectId = String(projectWidget.value || "").trim();
if (!projectId || seen.has(projectId)) {
projectId = createProjectId();
projectWidget.value = projectId;
}
seen.add(projectId);
const apiNode = prompt.output?.[String(node.id)];
if (apiNode?.inputs) {
apiNode.inputs.project_id = projectId;
}
}
},
});