diff --git a/CHANGELOG.md b/CHANGELOG.md index bec9700..c156f88 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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. diff --git a/MANIFEST.sha256 b/MANIFEST.sha256 index 2640436..d1166dc 100644 --- a/MANIFEST.sha256 +++ b/MANIFEST.sha256 @@ -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 diff --git a/PACKAGE_INFO_JA.txt b/PACKAGE_INFO_JA.txt index 8d1a9ac..4b04bdf 100644 --- a/PACKAGE_INFO_JA.txt +++ b/PACKAGE_INFO_JA.txt @@ -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 \ No newline at end of file diff --git a/PACKAGE_VALIDATION.txt b/PACKAGE_VALIDATION.txt index f77f4c7..f28724d 100644 --- a/PACKAGE_VALIDATION.txt +++ b/PACKAGE_VALIDATION.txt @@ -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 -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 \ No newline at end of file diff --git a/README.md b/README.md index f6a66d0..e3e4aff 100644 --- a/README.md +++ b/README.md @@ -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 defines the subject's face and identity. defines the subject's clothing, body design, and skateboard. + 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 diff --git a/README_JA.md b/README_JA.md index b7371f4..9269431 100644 --- a/README_JA.md +++ b/README_JA.md @@ -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を含む安定版です。 diff --git a/docs/AB_TEST_LOG_JA.md b/docs/AB_TEST_LOG_JA.md index 3659c5c..63271e6 100644 --- a/docs/AB_TEST_LOG_JA.md +++ b/docs/AB_TEST_LOG_JA.md @@ -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を正式安定版として採用する。 diff --git a/docs/SEAM_TEST_SOURCE_JA.md b/docs/SEAM_TEST_SOURCE_JA.md new file mode 100644 index 0000000..2127a51 --- /dev/null +++ b/docs/SEAM_TEST_SOURCE_JA.md @@ -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を消費する可能性があります。 diff --git a/docs/VALIDATION_RESULTS.md b/docs/VALIDATION_RESULTS.md new file mode 100644 index 0000000..af03591 --- /dev/null +++ b/docs/VALIDATION_RESULTS.md @@ -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. diff --git a/graph_contract.py b/graph_contract.py index a4c8dc8..ce398de 100644 --- a/graph_contract.py +++ b/graph_contract.py @@ -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 diff --git a/metadata.ini b/metadata.ini index f716d81..40e84a0 100644 --- a/metadata.ini +++ b/metadata.ini @@ -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. diff --git a/model_patch.py b/model_patch.py index 27bf800..3555688 100644 --- a/model_patch.py +++ b/model_patch.py @@ -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: diff --git a/nodes.py b/nodes.py index a15d173..63a6d08 100644 --- a/nodes.py +++ b/nodes.py @@ -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", } diff --git a/pyproject.toml b/pyproject.toml index 9e024ba..c379cb6 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -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" diff --git a/reference.py b/reference.py index a804c44..961d270 100644 --- a/reference.py +++ b/reference.py @@ -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 ; " - f"connected reference count is {reference_count}" + unavailable = ", ".join(f"" 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 " - " 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"" for value in missing) + detail = ( + "the prompt contains no 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 diff --git a/reference_audio.py b/reference_audio.py new file mode 100644 index 0000000..6470d8e --- /dev/null +++ b/reference_audio.py @@ -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"") + + +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