Duplicate from Viggle/Viggle-Animate

Co-authored-by: Yun Chen <yycc@users.noreply.huggingface.co>

.gitattributes

@@ -0,0 +1,68 @@
+*.7z filter=lfs diff=lfs merge=lfs -text
+*.arrow filter=lfs diff=lfs merge=lfs -text
+*.bin filter=lfs diff=lfs merge=lfs -text
+*.bz2 filter=lfs diff=lfs merge=lfs -text
+*.ckpt filter=lfs diff=lfs merge=lfs -text
+*.ftz filter=lfs diff=lfs merge=lfs -text
+*.gz filter=lfs diff=lfs merge=lfs -text
+*.h5 filter=lfs diff=lfs merge=lfs -text
+*.joblib filter=lfs diff=lfs merge=lfs -text
+*.lfs.* filter=lfs diff=lfs merge=lfs -text
+*.mlmodel filter=lfs diff=lfs merge=lfs -text
+*.model filter=lfs diff=lfs merge=lfs -text
+*.msgpack filter=lfs diff=lfs merge=lfs -text
+*.npy filter=lfs diff=lfs merge=lfs -text
+*.npz filter=lfs diff=lfs merge=lfs -text
+*.onnx filter=lfs diff=lfs merge=lfs -text
+*.ot filter=lfs diff=lfs merge=lfs -text
+*.parquet filter=lfs diff=lfs merge=lfs -text
+*.pb filter=lfs diff=lfs merge=lfs -text
+*.pickle filter=lfs diff=lfs merge=lfs -text
+*.pkl filter=lfs diff=lfs merge=lfs -text
+*.pt filter=lfs diff=lfs merge=lfs -text
+*.pth filter=lfs diff=lfs merge=lfs -text
+*.rar filter=lfs diff=lfs merge=lfs -text
+*.safetensors filter=lfs diff=lfs merge=lfs -text
+saved_model/**/* filter=lfs diff=lfs merge=lfs -text
+*.tar.* filter=lfs diff=lfs merge=lfs -text
+*.tar filter=lfs diff=lfs merge=lfs -text
+*.tflite filter=lfs diff=lfs merge=lfs -text
+*.tgz filter=lfs diff=lfs merge=lfs -text
+*.wasm filter=lfs diff=lfs merge=lfs -text
+*.xz filter=lfs diff=lfs merge=lfs -text
+*.zip filter=lfs diff=lfs merge=lfs -text
+*.zst filter=lfs diff=lfs merge=lfs -text
+*tfevents* filter=lfs diff=lfs merge=lfs -text
+examples/media/before-after.png filter=lfs diff=lfs merge=lfs -text
+examples/media/output.mp4 filter=lfs diff=lfs merge=lfs -text
+examples/media/reference.png filter=lfs diff=lfs merge=lfs -text
+examples/media/compare-monkey.mp4 filter=lfs diff=lfs merge=lfs -text
+examples/media/compare-parka.mp4 filter=lfs diff=lfs merge=lfs -text
+examples/media/compare-horns.mp4 filter=lfs diff=lfs merge=lfs -text
+examples/media/compare-costume.mp4 filter=lfs diff=lfs merge=lfs -text
+examples/media/compare-prop.mp4 filter=lfs diff=lfs merge=lfs -text
+examples/media/compare-style.mp4 filter=lfs diff=lfs merge=lfs -text
+examples/media/swap-airliner.mp4 filter=lfs diff=lfs merge=lfs -text
+examples/media/swap-anime-duo.mp4 filter=lfs diff=lfs merge=lfs -text
+examples/media/swap-claymation.mp4 filter=lfs diff=lfs merge=lfs -text
+examples/media/swap-corgi.mp4 filter=lfs diff=lfs merge=lfs -text
+examples/media/swap-panda.mp4 filter=lfs diff=lfs merge=lfs -text
+examples/media/swap-penguin.mp4 filter=lfs diff=lfs merge=lfs -text
+examples/media/swap-photoreal-duo.mp4 filter=lfs diff=lfs merge=lfs -text
+examples/media/swap-robot.mp4 filter=lfs diff=lfs merge=lfs -text
+examples/media/swap-wushu-animals.mp4 filter=lfs diff=lfs merge=lfs -text
+examples/media/swap-wushu-robots.mp4 filter=lfs diff=lfs merge=lfs -text
+examples/media/hero-corgi.mp4 filter=lfs diff=lfs merge=lfs -text
+examples/media/hero-duo.mp4 filter=lfs diff=lfs merge=lfs -text
+examples/media/compare-cosplay.mp4 filter=lfs diff=lfs merge=lfs -text
+examples/media/compare-gamechar.mp4 filter=lfs diff=lfs merge=lfs -text
+examples/media/teaser.mp4 filter=lfs diff=lfs merge=lfs -text
+MiniMaxH3TransformerBlock/package.pt2 filter=lfs diff=lfs merge=lfs -text
+MiniMaxH3TokenRefinerBlock/package.pt2 filter=lfs diff=lfs merge=lfs -text
+examples/media/compare-fastmotion.mp4 filter=lfs diff=lfs merge=lfs -text
+examples/media/compare-highkick.mp4 filter=lfs diff=lfs merge=lfs -text
+examples/media/pipeline.png filter=lfs diff=lfs merge=lfs -text
+examples/media/community-tweet.png filter=lfs diff=lfs merge=lfs -text
+examples/media/audio-pin-driving.mp4 filter=lfs diff=lfs merge=lfs -text
+examples/media/audio-pin-out.mp4 filter=lfs diff=lfs merge=lfs -text
+examples/media/audio-pin-ref.png filter=lfs diff=lfs merge=lfs -text

LICENSE

@@ -0,0 +1,84 @@
+MiniMax H3 COMMUNITY LICENSE AGREEMENT
+MiniMax H3 release date/License date: August 2, 2026.
+The scope of this License Agreement (this “Agreement”) is expressly limited to the “Applicable Territory” as defined below.
+By clicking to accept, or by using, reproducing, modifying, distributing, running, or displaying any portion or element of the MiniMax H3 Works (including through any Hosted Services) in any manner, you acknowledge and accept the terms of this Agreement, and this Agreement shall take immediate effect upon the occurrence of such act.
+I.  Definitions
+1. “Acceptable Use Policy” means the policy published by MiniMax in Exhibit A.
+2. “Agreement” means the terms and conditions set forth herein that govern the use, reproduction, distribution, modification, running, and display of the MiniMax H3 Works or any portion or element thereof.
+3. “Applicable Territory” means worldwide, excluding the Excluded Territories.
+4. “Documentation” means the specifications, manuals, and documentation concerning MiniMax H3 that are publicly released by MiniMax.
+5. “Excluded Territories” means the European Union, the United Kingdom, the Republic of Korea and the United States of America.  
+6. “MiniMax H3” means the video generation model, together with its software and algorithms, including trained model weights, parameters (including optimizer states), machine-learning model code, inference-supporting code, and other elements thereof made publicly available by Us, as released at https://huggingface.co/MiniMaxAI/MiniMax-H3.
+7. “MiniMax H3 Works” means (i) the Materials, (ii) the Model Derivatives, and (iii) all derivatives thereof.
+8. “Hosted Services” means hosted services provided via application programming interfaces (APIs), web access, or any other electronic or remote means.
+9. “Licensee,” “you,” or “your” means the natural or legal person exercising rights and/or using the MiniMax H3 Works for any purpose in any field of use under this Agreement.
+10. “Materials” means, collectively, MiniMax H3 and the Documentation (and any portion thereof), in each case as made available by MiniMax under this Agreement and proprietary to MiniMax.
+11. “Model Derivatives” means all of the following: (i) any modification of MiniMax H3 or any Model Derivative thereof; (ii) any work based on MiniMax H3 or any Model Derivative thereof; or (iii) any other machine learning model created by transferring the patterns of the weights, parameters, operational patterns, or Outputs of MiniMax H3 or any Model Derivative thereof to another model, such that the latter model exhibits behavior similar to MiniMax H3 or its Model Derivatives, including by distillation methods, methods using intermediate data representations, or methods based on training using synthetic-data Outputs generated by MiniMax H3 or its Model Derivatives. For the avoidance of doubt, Outputs are not deemed Model Derivatives.
+12. “Output” means any result of operating or otherwise using MiniMax H3 or any Model Derivatives (including through Hosted Services).
+13. “Third Party” means any natural or legal person that is not under common control with us or with you.
+14. “Including” means “including but not limited to.”
+15. “We,” “Us”  or  “MiniMax” means Nanonoble Pte. Ltd..
+II.  Grant of Rights
+Solely within the Applicable Territory, we grant you a non-exclusive, non-transferable, royalty-free, limited license to use, reproduce, distribute, create derivative works (including Model Derivatives), and modify the Materials in accordance with the terms of this Agreement and the Acceptable Use Policy, based on the intellectual property and other rights owned by MiniMax that are embodied in or used by the Materials. You shall not violate (or encourage or permit any person to violate) any term of this Agreement or the Acceptable Use Policy.
+We will continuously evaluate the applicable laws, regulations and compliance requirements for the Excluded Territories. In the meantime, should any person in such Excluded Territories be interested in deploying our models, you are welcome to contact us about obtaining a license, which will be granted based on robust controls and guardrails for purposes of complying with the laws, regulations and compliance requirements of the Excluded Territories.
+III.  Distribution and Redistribution
+Subject to and conditioned on your continuing compliance with this Agreement, including its territorial restrictions and the Acceptable Use Policy, and solely within the Applicable Territory, you may distribute or make available the MiniMax H3 Works to Third Parties within the Applicable Territory; provided, that all of the following conditions are met:
+1. You must provide a copy of this Agreement to all such Third Parties who receive the MiniMax H3 Works or use your products or services related thereto;
+2. You must cause any modified files to carry prominent notices stating that you have modified such files;
+3. You are encouraged to:
+  a. display a notice on any product or service developed using MiniMax H3 indicating that the product or service is “Powered by MiniMax H3”; 
+  b. add an AI-generation identifier to files produced using generative AI models including MiniMax H3; and
+  c. publish at least one technical blog post or a public statement describing your experience using MiniMax H3 Works;
+4. All distributions to Third Parties (other than through Hosted Services) must be accompanied by a “NOTICE” text file containing the following notice:
+  “MiniMax H3 is licensed under the MiniMax H3 Community License Agreement, Copyright © 2026 MiniMax. All Rights Reserved.”
+You may add your own copyright notices on your modifications; except as provided in this Section and in Section V, however, you may not impose additional or different terms and conditions on the use, reproduction, or distribution of your modifications or of any aggregate Model Derivatives, and your use, reproduction, modification, distribution, running, and display of the work must otherwise comply with the terms and conditions of this Agreement (including the provisions concerning the Applicable Territory). If you receive the MiniMax H3 Works from a Licensee as part of an integrated end-user product, the provisions of Section III of this Agreement do not apply to you, but Section V and Exhibit A remain applicable.
+IV.  Additional Commercial Terms
+1. You shall obtain a separate, prior written authorization from MiniMax by contacting api@minimax.io with the subject line “MiniMax H3 licensing - authorization request”, if your commercial products and services generate more than 20 million US dollars (or equivalent in other currencies) in yearly revenue.
+2. You shall prominently display “MiniMax H3”on the user interface of commercial product or service that uses MiniMax H3 or MiniMax H3 Works.
+V. Use Restrictions
+1. Your use of the MiniMax H3 Works must comply with applicable laws and regulations (including trade-compliance laws and regulations) and must comply with the Acceptable Use Policy for the MiniMax H3 Works, which is incorporated into this Agreement by reference. 
+2. Before providing access to the MiniMax H3 Works or any product, service, or Hosted Service incorporating them, you must bind each recipient or user to enforceable terms at least as protective as the use restrictions in this Section V and Exhibit A, and you must notify each recipient or user that those restrictions apply.
+3. You may not use the MiniMax H3 Works or any of their Outputs or results to improve any other artificial intelligence model (other than MiniMax H3 or its Model Derivatives).
+4. You may not use, reproduce, modify, distribute, or display the MiniMax H3 Works or any of their Outputs or results outside the Applicable Territory. Any such use outside the Applicable Territory is not authorized by this Agreement.
+5. If you provide or make available to any Third Party a product, service, or Hosted Service that permits the generation of Outputs using MiniMax H3 or any Model Derivative, you must, before making that product or service available and throughout its operation, implement, maintain, test, and periodically review reasonable and proportionate technical and organizational safeguards designed to prevent and mitigate access, uses, and Outputs that violate this Section V or Exhibit A, including uses or Outputs that infringe, misappropriate, or otherwise violate any Third Party’s intellectual-property or other rights. You must not knowingly disable, materially weaken, or permit the circumvention of those safeguards. You must maintain a reasonably accessible mechanism for reporting suspected violations. Upon receiving a good-faith report or otherwise obtaining actual knowledge of a violation, you must promptly investigate and take reasonable steps within your control to stop or mitigate the violation, including removing or disabling access to offending content or services and suspending or terminating repeat violators where appropriate. You are responsible for implementing and enforcing these requirements with respect to your products, services, systems, users, and downstream recipients.
+VI.  Intellectual Property
+1. Subject to MiniMax’s rights in the MiniMax H3 Works (and the intellectual property therein), and to your compliance with the terms and conditions of this Agreement, as between you and MiniMax, you will own the derivative works and modifications of the Materials that you have created or had created, as well as any Model Derivatives.
+2. Except for the limited license expressly granted in this paragraph, no trademark license is granted under this Agreement; with respect to MiniMax H3 Works, the Licensee may not use any name or mark owned by or associated with MiniMax or any of its affiliates, except as reasonably and customarily necessary to describe and distribute the MiniMax H3 Works. MiniMax hereby grants you a license to use the “MiniMax H3” mark (the “Mark”) within the Applicable Territory solely for the purpose of complying with Section III.3; provided, that you comply with all applicable trademark-protection laws. All goodwill arising from your use of the Mark shall inure to the benefit of MiniMax.
+3. If you bring or assert any suit or other legal proceeding (including a cross-claim or counterclaim in any action) against us or any other natural or legal person alleging that the Materials, any Output, or any portion of the foregoing infringes any intellectual property right or other right owned by you or for which you can obtain a license, all licenses granted to you under this Agreement will terminate as of the date such suit or proceeding is filed. You shall defend, indemnify, and hold us harmless against any Third-Party claim arising out of or related to the use or distribution of the MiniMax H3 Works by you or by any Third Party.
+4. MiniMax claims no rights over the Outputs you generate. You and your users are entirely responsible for the Outputs and any subsequent use thereof.
+VII.  Disclaimers and Limitations of Liability
+1. We have no obligation to support, update, provide training for, or develop any further version of the MiniMax H3 Works, or to grant any license with respect thereto.
+2. UNLESS AND ONLY TO THE EXTENT REQUIRED BY APPLICABLE LAW, THE MINIMAX H3 WORKS AND ANY OUTPUT AND RESULTS THEREFROM ARE PROVIDED “AS IS” WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES OF ANY KIND INCLUDING ANY WARRANTIES OF TITLE, MERCHANTABILITY, NONINFRINGEMENT, COURSE OF DEALING, USAGE OF TRADE, OR FITNESS FOR A PARTICULAR PURPOSE. YOU ARE SOLELY RESPONSIBLE FOR DETERMINING THE APPROPRIATENESS OF USING, REPRODUCING, MODIFYING, PERFORMING, DISPLAYING OR DISTRIBUTING ANY OF THE MINIMAX H3 WORKS OR OUTPUTS AND ASSUME ANY AND ALL RISKS ASSOCIATED WITH YOUR OR A THIRD PARTY’S USE OR DISTRIBUTION OF ANY OF THE MINIMAX H3 WORKS OR OUTPUTS AND YOUR EXERCISE OF RIGHTS AND PERMISSIONS UNDER THIS AGREEMENT.
+3. TO THE FULLEST EXTENT PERMITTED BY APPLICABLE LAW, IN NO EVENT SHALL MINIMAX OR ITS AFFILIATES BE LIABLE UNDER ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, TORT, NEGLIGENCE, PRODUCTS LIABILITY, OR OTHERWISE, FOR ANY DAMAGES, INCLUDING ANY DIRECT, INDIRECT, SPECIAL, INCIDENTAL, EXEMPLARY, CONSEQUENTIAL OR PUNITIVE DAMAGES, OR LOST PROFITS OF ANY KIND ARISING FROM THIS AGREEMENT OR RELATED TO ANY OF THE MINIMAX H3 WORKS OR OUTPUTS, EVEN IF MINIMAX OR ITS AFFILIATES HAVE BEEN ADVISED OF THE POSSIBILITY OF ANY OF THE FOREGOING.
+VIII.  Term and Termination
+1. This Agreement is effective from the moment you accept this Agreement or begin accessing the Materials, and, subject to your compliance with its terms and conditions, will remain in effect until terminated as provided herein.
+2. If you breach any term or condition of this Agreement, we have the right to terminate this Agreement. Upon termination, you must immediately cease accessing, using, and distributing the MiniMax H3 Works; delete or destroy all copies within your possession or control; and notify each downstream recipient that your authorization has ended. The obligations in the preceding sentence and Sections VI.1, VI.3, VII, and IX survive termination.
+IX.  Governing Law and Jurisdiction
+1. This Agreement, and any dispute arising out of or related to this Agreement, shall be governed by the laws of the Hong Kong Special Administrative Region of the People’s Republic of China, without regard to its conflict-of-laws rules. The United Nations Convention on Contracts for the International Sale of Goods does not apply to this Agreement.
+2. Any dispute arising out of or related to this Agreement shall be subject to the exclusive jurisdiction of the courts of the Hong Kong Special Administrative Region of the People’s Republic of China with competent jurisdiction. Both MiniMax and the Licensee hereby consent to the exclusive jurisdiction of such courts for any such dispute.
+Additional Note: Please note that the encoder of MiniMax H3 uses Qwen3-VL-32B, which is licensed under Apache 2.0 License: https://github.com/QwenLM/Qwen3-VL/blob/main/LICENSE.
+
+Exhibit A — Acceptable Use Policy
+MiniMax reserves the right to update this Acceptable Use Policy from time to time. 
+Last revised: August 2, 2026.
+MiniMax is committed to promoting the safe and fair use of its tools and features, including MiniMax H3. You agree not to use MiniMax H3, any Model Derivatives, or any Output in any of the following ways:
+1. Use outside the Applicable Territory;
+2. Use in any manner that violates any applicable national, federal, state, local, or international law, regulation, or other legal requirement, or that infringes, misappropriates, or otherwise violates any Third Party’s intellectual-property or other proprietary rights, including through unauthorized reproduction, distribution, public display, public performance, or creation of derivative works;
+3. Use in any manner that may harm yourself or others;
+4. Use to repurpose or distribute the Outputs of MiniMax H3 or any Model Derivatives in order to harm yourself or others;
+5. Use to circumvent or bypass any safety guardrails or safeguards we have implemented;
+6. Use in any manner that exploits or harms, or intends to exploit or harm, minors;
+7. Use to generate or disseminate verifiably false information and/or content for the purpose of harming others or influencing elections;
+8. Use to manufacture or facilitate false online engagement, including fake reviews and other means of false online engagement;
+9. Use to intentionally defame, disparage, or otherwise harass others;
+10. Use to generate and/or disseminate malware (including ransomware) or any other content intended to damage electronic systems;
+11. Use to generate or disseminate personally identifiable information for the purpose of harming others;
+12. Use to generate or disseminate information (including images, code, posts, or articles) in or to any public environment (including via bot tweets or similar means) without clearly and prominently disclosing that such information and/or content is machine-generated;
+13. Use to impersonate another person without that person’s consent, authorization, or lawful right to do so;
+14. Use to make high-risk automated decisions in critical domains that affect individual safety, rights, or well-being (such as law enforcement, immigration, healthcare or medical services, critical-infrastructure management, product-safety components, essential services, credit, employment, housing, education, social scoring, or insurance);
+15. Use in any manner that violates or disregards the social, ethical, or moral standards of other countries or regions;
+16. Use to carry out, assist, threaten, incite, plan, advocate for, or encourage violent extremism or terrorism;
+17. Use for any purpose intended to discriminate against, or harm, individuals or groups based on protected characteristics or categories, online or offline social behavior, or known or predicted personality traits;
+18. Use to intentionally exploit the vulnerabilities of specific populations based on age, social, physical, or psychological characteristics, so as to materially distort the behavior of a member of that group in a manner that causes, or is likely to cause, physical or psychological harm to that person or to others;
+19. Use for military purposes;
+20. Use to engage in any unauthorized or unlicensed professional activity, including but not limited to financial, legal, medical or healthcare, or other professional practice.

LICENSE-CODE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

MODIFICATIONS.md

@@ -0,0 +1,90 @@
+# Modified files
+
+Section III.2 of the MiniMax H3 Community License Agreement requires that modified
+files carry a prominent notice saying so. This file is that notice.
+
+Everything below is derived from
+[`MiniMaxAI/MiniMax-H3`](https://huggingface.co/MiniMaxAI/MiniMax-H3).
+
+## `transformer/` — modified
+
+**Every weight file in `transformer/` has been modified.** It started as the base
+model's `transformer_ref/` (the `ref2va` transformer, 33.1 B parameters) and every
+parameter was updated by a full finetune on a character-replacement objective. The
+architecture, `config.json` and tensor names are unchanged, so it is a drop-in
+replacement for the base `transformer_ref/`; the numbers in it are not the base
+model's numbers.
+
+The file layout also differs: the finetune was written as one 61.7 GiB safetensors
+file and re-sharded here into 14 parts, because HuggingFace rejects single files
+above 50 GB. The 638 tensors and their contents are unchanged by that re-sharding.
+
+## `lora/pytorch_lora_weights.safetensors` — new
+
+Not a MiniMax file. A rank-128 LoRA over 302 linear layers of `transformer/`,
+trained by us with DMD2 distillation. It is a delta on the finetuned transformer
+above, not on the base model — loading it onto stock `transformer_ref/` produces
+garbage.
+
+## `assets/fixed_embed_fwd_anyframe.pt` — new
+
+Not a MiniMax file. A frozen 362 × 5120 text-conditioning tensor we computed once
+with the base model's own text encoder, so that inference never has to load
+Qwen3-VL. It is an *output* of the base model's encoder in the sense of Section
+I.12, computed from the prompt in `assets/fixed_prompt.txt`.
+
+## `assets/fixed_prompt.txt` — new
+
+Not a MiniMax file. The prompt text the tensor above was computed from, included so
+that what conditions every render is readable rather than opaque.
+
+## `inference/sample.py`, `examples/demo.sh` — new
+
+Not MiniMax files. Written by us against the public `diffusers` API.
+
+## `LICENSE-CODE`, `NOTICE` — new
+
+Not MiniMax files. `LICENSE-CODE` is the Apache 2.0 text, and it covers `inference/` and
+`examples/` only — each file there carries an `SPDX-License-Identifier: Apache-2.0` header.
+`NOTICE` records that the weights are *not* Apache 2.0. `LICENSE` is the MiniMax H3
+Community License Agreement itself, included unmodified as Section III.1 requires.
+
+## `examples/media/` — new
+
+Two kinds of media here, with different provenance.
+
+**The demo** — `reference.png`, `output.mp4`, `before-after.png` — derives from
+`assets/ref2va.mp4`, a video MiniMax published with the base model. That clip is itself a
+MiniMax H3 generation rather than camera footage. All three files are a 512 × 768 portrait
+crop of it (`crop=512:768:389:0`, no scaling):
+
+- `reference.png` — the crop's first frame with the young man repainted as an invented
+  elderly woman. Produced with OpenAI's `gpt-image-2`; the character is fictional and is
+  not a real person or an existing property.
+- `output.mp4` — that reference propagated across 124 frames by this model.
+- `before-after.png` — frames from the driving crop above frames from the output.
+
+The driving clip itself is **not** bundled. `examples/demo.sh` rebuilds it, with the
+documented crop, from your own copy of the base model.
+
+**The comparison clips** — `compare-prop.mp4`, `compare-costume.mp4`, `compare-style.mp4` — are a
+different matter. Their driving videos are
+real filmed footage that we hold the rights to, and they are among the clips this model was
+evaluated against. Each file is a four-panel stack: painted reference, driving video, this model,
+Wan2.2-Animate-14B. The Wan2.2-Animate panels were rendered by us from the official
+[`Wan-AI/Wan2.2-Animate-14B`](https://huggingface.co/Wan-AI/Wan2.2-Animate-14B) weights and code,
+unmodified, at the replacement-mode settings its own README documents (20 steps, `sample_shift 5.0`,
+`--refert_num 1 --replace_flag --use_relighting_lora`, preprocessing at `--w_len 1 --h_len 1`) —
+that panel is Wan's output, not ours.
+
+Wan's `generate.py` hardcodes a 30 fps output timebase regardless of the source, so its raw files
+claim 4.10 s for motion that is 24 fps. The panels are retimed (`setpts`), not resampled, so no
+frames are dropped and both models play at the same speed. Every panel is letterboxed into the
+driving clip's own geometry; nothing is stretched.
+
+## Not redistributed here
+
+The VAE, audio VAE, schedulers, text encoder, tokenizer and processor are **not**
+included in this repository and are not modified. They are loaded at runtime from
+your own copy of `MiniMaxAI/MiniMax-H3`, which you must download separately and
+under its own license terms.

MiniMaxH3TokenRefinerBlock/package.pt2

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:1fc10961935eb10891d1e2449b18185533d5714a40bb6f6929b8d6b7c1b4d39f
+size 604596

MiniMaxH3TransformerBlock/package.pt2

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:58c651aa49a7455aa6a49e17ae7c74b4fd73e9306456a1baaa3300d0aef1ee09
+size 853072

NOTICE

@@ -0,0 +1,13 @@
+MiniMax H3 is licensed under the MiniMax H3 Community License Agreement,
+Copyright © 2026 MiniMax. All Rights Reserved.
+
+---
+
+Viggle-Animate is a Model Derivative of MiniMax H3, as that term is defined in
+Section I.11 of the MiniMax H3 Community License Agreement. It is distributed
+under that same Agreement, a copy of which is included in this repository as
+LICENSE. See MODIFICATIONS.md for the list of files that were modified.
+
+Powered by MiniMax H3.
+
+Modifications and additions Copyright © 2026 Viggle AI.

README.md

@@ -0,0 +1,347 @@
+---
+license: other
+license_name: minimax-h3-community-license
+license_link: LICENSE
+base_model: MiniMaxAI/MiniMax-H3
+pipeline_tag: video-to-video
+tags:
+  - video-editing
+  - character-replacement
+  - video-to-video
+  - distillation
+  - dmd
+---
+
+# Viggle-Animate
+
+### Character Replacement in Video from a Single Repainted Frame
+
+**[Try the demo](https://huggingface.co/spaces/Viggle/viggle-animate)**  · 
+**[Research write-up](https://viggle.ai/research/viggle-animate-character-replacement-from-a-repainted-frame?utm_source=huggingface&utm_medium=social&utm_campaign=viggle-animate&utm_content=viggle/viggle-animate)**  · 
+**[ComfyUI nodes](https://github.com/Saganaki22/ComfyUI-Viggle-Animate-H3)**  · 
+**[viggle.ai/h3](https://viggle.ai/h3)**  · 
+Built on **[MiniMaxAI/MiniMax-H3](https://huggingface.co/MiniMaxAI/MiniMax-H3)**
+
+<a href="https://x.com/cocktailpeanut/status/2097332291844399514" style="display:block;max-width:460px;margin:0 0 .5em">
+<img src="https://huggingface.co/Viggle/Viggle-Animate/resolve/main/examples/media/community-tweet.png" width="100%" style="display:block;border-radius:14px" alt="@cocktailpeanut on X: two AI CEOs dropped into a film scene with Viggle-Animate - 1.5M views, 14K likes">
+</a>
+
+<sub>Made with Viggle-Animate by <a href="https://x.com/cocktailpeanut/status/2097332291844399514">@cocktailpeanut</a>, not by us. Click through to watch it on X.</sub>
+
+<video autoplay controls muted loop playsinline width="100%" src="https://huggingface.co/Viggle/Viggle-Animate/resolve/main/examples/media/teaser.mp4"></video>
+
+**Viggle-Animate replaces the character in a video with whatever you paint into one of its own
+frames** — motion, camera and timing untouched. You prepare that one frame in an image editor;
+from there the video stage runs no pose estimator, segmenter, face tracker or text encoder. Two
+inputs, three forward passes, 26 seconds a shot on one GPU.
+
+**It is strongest where replacement is hardest: fast motion, and pose transfer accurate enough to
+follow it.** Whipping heads, full kicks, jumps — tracked frame for frame, not smeared through.
+
+## Abstract
+
+Controlled character replacement is usually built on intermediate representations — pose skeletons,
+segmentation masks, background plates, face crops. Each needs its own extractor, and each extractor
+is another model to run and another place to lose information. Recent work drops the skeleton but
+keeps a mask channel. **Viggle-Animate uses neither.** Its two inputs are a driving video and one of
+that video's own frames with the character repainted, and its only task is to propagate that edit
+across the shot.
+
+Because the reference is a frame of the clip, its pose, camera, framing and lighting already agree
+with the footage, and nothing downstream has to align them again. The model is never told what the
+new character is: no class, no identity encoder, and no user-provided text prompt.
+**Viggle-Animate is a 33.1 B full finetune of MiniMax-H3's `ref2va` transformer, jointly distilled
+with DMD to three forward passes.** In a matched comparison on the same machine and B200 GPU, using
+the same source videos, output resolution and frame count, it renders 124 frames in 26 s, 6.1×
+faster per clip than Wan2.2-Animate-14B.
+
+## Method
+
+Character replacement asks two questions at once: *what does the new character look like*, and *how
+does it move through this shot*. Systems that condition on a standalone character photograph must
+answer both, and reconciling a photograph with footage it was never part of is what the scaffolding
+exists for.
+
+State-of-the-art image models have finished that job. Give `gpt-image` a frame and an instruction
+and it replaces the character while following the prompt exactly — transferring the pose, matching
+the lighting, preserving the background. The hard reconciliation is already solved, once, on one
+image. This model is the second half of that pipeline, not the whole of it.
+
+<img src="https://huggingface.co/Viggle/Viggle-Animate/resolve/main/examples/media/pipeline.svg"
+alt="Two inputs — a driving video and one of its own frames, repainted in any image editor — enter Viggle-Animate. No pose skeleton, segmentation mask, face crop, background plate, depth map or user-provided text prompt enters the video model." width="100%">
+
+Appearance enters only through the repainted frame; geometry enters only through the driving video.
+**The text encoder is never loaded.** Conditioning is one frozen embedding shipped with the weights
+([`assets/fixed_prompt.txt`](assets/fixed_prompt.txt)), identical for every render.
+
+Left panel is the driving video, right panel is this model:
+
+<video autoplay controls muted loop playsinline width="100%" src="https://huggingface.co/Viggle/Viggle-Animate/resolve/main/examples/media/hero-duo.mp4"></video>
+
+<video autoplay controls muted loop playsinline width="100%" src="https://huggingface.co/Viggle/Viggle-Animate/resolve/main/examples/media/hero-corgi.mp4"></video>
+
+**It is fast twice over.** Once the repainted frame exists there is nothing else to run — no pose
+estimator, no segmenter, no face tracker, no text encoder. And the sampler is distilled, so a
+finished clip is three forward passes rather than thirty. The two compound: one model, one GPU,
+and no orchestration to get wrong.
+
+The distillation is **joint, across two teachers split by noise level.** Our finetune supervises the
+high-noise end of the schedule, where the replacement itself is decided — it is the model that gets
+the swap right. The original MiniMax-H3 supervises the low-noise end, where detail and texture are
+decided — it is the model with the better image quality. Distilling each end against the teacher that
+owns it keeps both properties in one student, instead of inheriting the finetune's visual
+regressions along with its replacement ability.
+
+**It generalizes past humans**, because nothing in the loop assumes one. A pose skeleton has a neck
+and two arms; a mask has a person-shaped hole. We have neither, so the model holds no representation
+that a character must be a person. What it can animate is bounded by what you can paint.
+
+## Efficiency
+
+<div align="center">
+<div style="display:flex;gap:10px;flex-wrap:wrap;justify-content:center;margin:20px 0 6px;text-align:left">
+
+<div style="flex:1 1 170px;border:1px solid rgba(128,128,128,.35);border-top:3px solid #00D94F;border-radius:10px;padding:12px 14px">
+<div style="font-size:1.7em;font-weight:700;line-height:1.15">26 s</div>
+<b>per render</b><br>
+<small style="opacity:.7">124 frames at 24 fps, 480×832, a single B200</small>
+</div>
+
+<div style="flex:1 1 170px;border:1px solid rgba(128,128,128,.35);border-top:3px solid #00D94F;border-radius:10px;padding:12px 14px">
+<div style="font-size:1.7em;font-weight:700;line-height:1.15">3</div>
+<b>forward passes</b><br>
+<small style="opacity:.7"><code>--steps 4</code> names four sigma boundaries, so three passes</small>
+</div>
+
+<div style="flex:1 1 170px;border:1px solid rgba(128,128,128,.35);border-top:3px solid #00D94F;border-radius:10px;padding:12px 14px">
+<div style="font-size:1.7em;font-weight:700;line-height:1.15">2</div>
+<b>inputs</b><br>
+<small style="opacity:.7">a clip, and one of its own frames repainted</small>
+</div>
+
+<div style="flex:1 1 170px;border:1px solid rgba(128,128,128,.35);border-top:3px solid #00D94F;border-radius:10px;padding:12px 14px">
+<div style="font-size:1.7em;font-weight:700;line-height:1.15">0</div>
+<b>other models</b><br>
+<small style="opacity:.7">in the video stage — no pose estimator, segmenter, face tracker or text encoder</small>
+</div>
+
+</div>
+</div>
+
+One B200, 480×832, 124 frames at 24 fps, bf16, no compile, no offload. Wan ran its documented
+replacement recipe — 20 steps, `sample_shift 5.0`, `--refert_num 1 --replace_flag
+--use_relighting_lora`, `--w_len 1 --h_len 1` — after its own preprocessing pass.
+
+| | Viggle-Animate | Wan2.2-Animate-14B |
+|---|---|---|
+| Inputs | driving video + one repainted frame | driving video + character image, then a **preprocessing pass** producing pose, face, mask and background tracks |
+| Render, after weights load | **26 s** | 160 s |
+| — of which sampling | **13.6 s** | 140 s |
+| Forward passes | **3** | 40 (20 steps × 2 chunks) |
+| Parameters | 33.1 B | 17.3 B |
+
+**6.1× faster per render, 10.3× on sampling alone.** Wan's preprocessing pass is not counted in
+its 160 s.
+
+### Qualitative comparison
+
+Four panels each: **painted reference · driving video · this model · Wan2.2-Animate-14B**, the last
+at its documented replacement settings. The gap is widest under fast motion: where the comparison
+smears, this model stays sharp and lands the pose on the right frame.
+
+<video controls muted loop playsinline width="100%" src="https://huggingface.co/Viggle/Viggle-Animate/resolve/main/examples/media/compare-fastmotion.mp4"></video>
+
+<video controls muted loop playsinline width="100%" src="https://huggingface.co/Viggle/Viggle-Animate/resolve/main/examples/media/compare-highkick.mp4"></video>
+
+<video controls muted loop playsinline width="100%" src="https://huggingface.co/Viggle/Viggle-Animate/resolve/main/examples/media/compare-cosplay.mp4"></video>
+
+## Generalization
+
+The model is never told what it is animating, so how far the character can get from a person is an
+empirical question rather than a list of supported categories. Three panels each: **painted
+reference · driving video · this model.** Every clip below is one paint and one render at the
+shipped defaults, `--seed 42` — no best-of-N.
+
+**Animals.** Ears, eye patches and flippers move on limbs the driving clip does not have — the paint
+places them, the render animates them as if they had always been arms and a head.
+
+<video controls muted loop playsinline width="100%" src="https://huggingface.co/Viggle/Viggle-Animate/resolve/main/examples/media/swap-corgi.mp4"></video>
+<video controls muted loop playsinline width="100%" src="https://huggingface.co/Viggle/Viggle-Animate/resolve/main/examples/media/swap-panda.mp4"></video>
+<video controls muted loop playsinline width="100%" src="https://huggingface.co/Viggle/Viggle-Animate/resolve/main/examples/media/swap-penguin.mp4"></video>
+
+**Not humanoid.** The airliner is the hardest case we have: the paint binds wings to arms and landing
+gear to legs, and the model's job is to keep that binding for 124 frames. The robot has to relight
+specular metal as it turns.
+
+<video controls muted loop playsinline width="100%" src="https://huggingface.co/Viggle/Viggle-Animate/resolve/main/examples/media/swap-airliner.mp4"></video>
+<video controls muted loop playsinline width="100%" src="https://huggingface.co/Viggle/Viggle-Animate/resolve/main/examples/media/swap-robot.mp4"></video>
+
+**Stylized.** The clay figure holds its style boundary for the whole clip.
+
+<video controls muted loop playsinline width="100%" src="https://huggingface.co/Viggle/Viggle-Animate/resolve/main/examples/media/swap-claymation.mp4"></video>
+
+**More than one character.** The work moves into the paint prompt, which has to bind each one to a
+position — "the one on the left". The last clip is a wide arena shot, each figure a few dozen pixels
+tall.
+
+<video controls muted loop playsinline width="100%" src="https://huggingface.co/Viggle/Viggle-Animate/resolve/main/examples/media/swap-anime-duo.mp4"></video>
+<video controls muted loop playsinline width="100%" src="https://huggingface.co/Viggle/Viggle-Animate/resolve/main/examples/media/swap-photoreal-duo.mp4"></video>
+<video controls muted loop playsinline width="100%" src="https://huggingface.co/Viggle/Viggle-Animate/resolve/main/examples/media/swap-wushu-animals.mp4"></video>
+
+## Limitations
+
+**It inherits the image edit.** What the paint does not show, the model will not add, and where
+paint and video disagree the video wins. Appearance comes from the paint but shape comes from the
+driving pose: a LEGO minifigure kept its palette and yellow claw hands, yet reverted to human
+anatomy — the airliner held because the paint tied its wings to real arms.
+
+~~**Lip-sync is weak.** Mouth shapes do not track speech closely in close-ups. Identity and expression
+hold; it is the sync that lags, and we believe that is a training-data limit rather than anything
+structural.~~
+
+**Retracted — and since improved.** Broader user testing already put lip-sync and facial
+expression ahead of our own first read of them. The rest turned out not to be a training-data limit
+either. The model animates the mouth to *its own* audio track, and the fixed prompt asks that track
+to be silence — so in the shipped configuration there is nothing for the mouth to sync to. Give it a
+real soundtrack instead: encode the driving clip's audio with the audio VAE and hold it in the
+target audio rows as a **clean** latent for the whole denoise (H3's flow convention is reversed, so
+clean is `t = 1`). The audio rows stop being something the model predicts and become something it
+conditions on, and the mouth tracks that speech. This is an inference-time change only — no
+retraining, no new weights — and the pairing of noisy video rows with clean audio rows is not a
+state the model was trained on, but it holds up across the clips we have run.
+Pass `--audio` to do it here; the [hosted demo](https://huggingface.co/spaces/Viggle/viggle-animate)
+does it automatically whenever the clip you upload carries sound.
+
+**Turn the sound on for these two.** The driving clip, then the same shot with a different actor in
+it, speaking her lines:
+
+<video controls playsinline width="100%" src="https://huggingface.co/Viggle/Viggle-Animate/resolve/main/examples/media/audio-pin-driving.mp4"></video>
+
+<video controls playsinline width="100%" src="https://huggingface.co/Viggle/Viggle-Animate/resolve/main/examples/media/audio-pin-out.mp4"></video>
+
+All three files ship with the weights — the driving clip, the repainted still it is animated from
+([`audio-pin-ref.png`](examples/media/audio-pin-ref.png)), and the take above — so the second clip
+is a command rather than a claim. The same file is passed twice, once for the motion and once for
+the soundtrack:
+
+```bash
+python inference/sample.py --model-dir ./MiniMax-H3 \
+  --cond  examples/media/audio-pin-driving.mp4 \
+  --ref   examples/media/audio-pin-ref.png \
+  --audio examples/media/audio-pin-driving.mp4 \
+  --out   audio-pin-out.mp4
+```
+
+Everything else is the shipped default: 124 frames at 832x480, four steps, `--seed 42`; 51 s of
+render on a B200 after the weights load, and it comes back at 46 dB against the file above. The
+track you get back is the driving clip's own audio put through the audio VAE and decoded again —
+same level, peaks rounded off (0.95 to 0.76 here); that round trip is the evidence the rows really
+were pinned. Drop `--audio` and the same command writes a file whose audio track is digital silence,
+sample for sample, and a mouth that moves without saying anything.
+
+**Complex scenes are harder than single subjects.** Several characters at once, close interaction
+between them, and shots that cut are all cases where quality drops off — enough that we would not
+call them solved.
+
+**We are training a substantially better model right now**, aimed squarely at what is left. This
+release is the version we can ship today, not the ceiling.
+
+## What this repository contains
+
+Two parts, both derived from [`MiniMaxAI/MiniMax-H3`](https://huggingface.co/MiniMaxAI/MiniMax-H3)'s
+`ref2va` transformer:
+
+| | |
+|---|---|
+| `transformer/` | 33.1 B, bf16, 14 shards. A **full finetune** of the base `transformer_ref` on a character-replacement objective |
+| `lora/` | rank 128 over 302 linear layers, 2.5 GB. A **DMD2-distilled** delta on that finetune — this is what collapses the sampler to three forward passes |
+
+The LoRA is a delta on the *finetuned* transformer — loading it onto stock `transformer_ref` produces
+garbage.
+
+## Quickstart
+
+This repository ships only the transformer and the LoRA — the VAE, audio VAE and schedulers load
+from your own copy of the base model. Inference touches 11 GB of its 269 GB:
+
+```bash
+hf download MiniMaxAI/MiniMax-H3 --local-dir ./MiniMax-H3 \
+  --include "modular_model_index.json" "vae/*" "audio_vae/*" \
+            "scheduler/*" "audio_scheduler/*" "assets/ref2va.mp4"
+
+hf download Viggle/Viggle-Animate --local-dir ./Viggle-Animate
+
+pip install torch "git+https://github.com/huggingface/diffusers@d6726f3" av
+
+python Viggle-Animate/inference/sample.py \
+  --model-dir ./MiniMax-H3 \
+  --cond driving.mp4 --ref ref.png --out swapped.mp4
+```
+
+`d6726f3` is the tested `diffusers` commit; the upstream `minimax_h3` modular pipeline is enough,
+no fork or patch. The last `--include` is the clip [`examples/demo.sh`](examples/demo.sh) needs.
+
+**One 80 GB card is not enough at bf16** — the transformer is 62 GiB resident and a 480×832 /
+124-frame render peaks at 80.1 GiB allocated. Use a card with ≥ 96 GB, or pass `--offload` to
+stream blocks from CPU (~12 GB resident, much slower).
+
+**It also runs quantized on consumer hardware.** We deploy it on a single **RTX 5090 (32 GB)**:
+NVFP4 weights — 4.5 bits/param, dispatching to the real sm_120 cutlass block-scaled kernel, 2.70×
+bf16 per compiled linear — plus a low-rank `adaln_proj` and `torch.compile`. Quantization alone is
+not enough for 32 GB: 13.0 B of the 33.1 B parameters sit in `adaln_proj`, which the linear-layer
+quantizer does not touch. That deployment path is not shipped in this repository.
+
+Defaults are the evaluated configuration: `--steps 4 --flow-shift 3 --num-frames 124` (≈ 5.2 s at
+24 fps) `--seed 42`. Output geometry follows the driving clip and must be a multiple of 32 on both
+axes. Weights load in ~21 s, once per process. **Four steps is the operating point, not a shortcut**
+— the distilled model already renders sharper than its teacher, and raising the step count tips that
+into over-sharpening. `--steps 4` is four sigma boundaries and therefore three forward passes.
+`sample.py` drops the driving clip's audio at input and the model emits its own track, which the
+fixed prompt asks to be silence. `--audio <file>` overrides that and pins a real soundtrack instead,
+which is what makes the mouth track speech — see [Limitations](#limitations).
+
+Pull a frame with `ffmpeg -ss 1.5 -i driving.mp4 -frames:v 1 ref.png` and edit it at the same
+resolution. **It does not have to be the first frame.** The still is passed to the model with no
+frame index, so nothing downstream knows where in the clip it came from — pick whichever frame shows
+the character most clearly, front-on and unoccluded. Name the change, and pin down what must *not*
+change: pose, hands, props, framing, background, light. An editor that quietly reframes the shot will
+fight the driving motion. Prefer clips that keep one side to camera, and bind any new limb to a real
+one.
+
+[`examples/demo.sh`](examples/demo.sh) runs a swap end to end on a clip that ships with the base
+model, so it needs no media from you — and it is the fastest way to check that the LoRA loaded.
+
+## Citation
+
+```bibtex
+@misc{viggle2026animate,
+  title  = {Viggle-Animate: Character Replacement in Video from a Single Repainted Frame},
+  author = {Viggle Research},
+  year   = {2026},
+  url    = {https://huggingface.co/Viggle/Viggle-Animate}
+}
+```
+
+## License
+
+The weights are a Model Derivative of MiniMax H3, so the
+[MiniMax H3 Community License](LICENSE) applies to them — read it before you redistribute them or
+ship a product on them. Our changes are listed in [`MODIFICATIONS.md`](MODIFICATIONS.md).
+
+The code in [`inference/`](inference) and [`examples/`](examples) is Apache 2.0
+([`LICENSE-CODE`](LICENSE-CODE)).
+
+Music in the teaser at the top of this page: "Electrodoodle" by Kevin MacLeod
+([incompetech.com](https://incompetech.com)), licensed under
+[Creative Commons: By Attribution 4.0](http://creativecommons.org/licenses/by/4.0/).
+
+## Intended use
+
+This model exists to put a consenting performer into footage they did not shoot, and it will just
+as readily put someone into footage they never agreed to appear in. Note where that decision is
+made: **the identity comes from the frame you paint**, so an image editor's safeguards are upstream
+of this model and none of them are in it. It cannot verify identity or consent. Do not run it on
+people who have not agreed to it, label what you generate as AI-generated, and see Section V.5 of
+the Agreement if you offer this as a service.
+
+Powered by MiniMax H3.

assets/fixed_embed_fwd_anyframe.pt

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:e0ae90929caf7b790f5d0de599e868cc6c179f3e969577627971c9d78936a058
+size 3714413

assets/fixed_prompt.txt

@@ -0,0 +1,16 @@
+<Video 1>: <0.2 seconds><1.2 seconds><2.2 seconds><3.2 seconds><4.2 seconds><5.0 seconds><Picture 1>: subject_definitions:
+<Video 1> is the source video for the editing task.
+<Picture 1> is one frame of the target video.
+
+summary:
+[video editing + character replacement] The target video is an edited version of <Video 1> in which every performer is replaced by a different person. <Picture 1> is one frame of the target video: it already shows the replacement, together with the background, camera framing and lighting it happens in. Every other frame of the target video shows those same people in that same place, following the motion, timing and camera of <Video 1>.
+
+retention_analysis:
+<Video 1> (source video editing): fully_preserved - the camera framing, the background, the lighting, and the motion and timing of every performance are copied frame for frame.
+<Picture 1> (appears in [Shot 1]): reference - one frame of the target video, pixel for pixel. The people in it, their faces, hair, skin tone, build and clothing, and the background, the framing and the lighting are all taken from <Picture 1> and held unchanged from the first frame to the last.
+
+detailed_description:
+[Shot 1] The people of <Picture 1> perform exactly the motion of the corresponding performers in <Video 1>, in the same framing, on the same background, under the same lighting. Nothing outside the people changes. The camera framing never changes through the end of the video.
+
+overall_soundscape:
+No music and no speech.

examples/demo.sh

@@ -0,0 +1,43 @@
+#!/usr/bin/env bash
+# Reproduce the demo on the model card, and in doing so check your install.
+#
+# This repository bundles no driving footage. It builds the driving clip from a demo
+# video that ships with the base model, using the exact crop documented below, and
+# pairs it with the repainted first frame in media/reference.png.
+#
+# The result should match media/output.mp4. On the same GPU model we get it back
+# bit-identical; on different hardware bf16 kernel scheduling shifts things, and a mean
+# absolute difference around 1.5/255 is normal. What matters is that it is the same
+# elderly woman holding the same black lamb. If it comes back as the young man from the
+# source video instead, the LoRA did not load. If it comes back as noise, the weights
+# are wrong.
+#
+#   ./examples/demo.sh /path/to/MiniMax-H3
+#
+# About a minute on a B200, most of it loading weights.
+
+set -euo pipefail
+
+MODEL_DIR="${1:?usage: demo.sh /path/to/MiniMax-H3}"
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+OUT="${OUT:-$HERE/demo_out}"
+mkdir -p "$OUT"
+
+SRC="$MODEL_DIR/assets/ref2va.mp4"
+[ -f "$SRC" ] || { echo "missing $SRC -- see the download command on the model card"; exit 1; }
+
+# The source is 1344x768 and exactly 124 frames, which is the sampler's window. Crop a
+# 512x768 portrait window around the figure; it stays in frame for the whole push-in, so
+# no scaling and no padding are needed. media/reference.png is this crop's first frame,
+# repainted.
+ffmpeg -y -loglevel error -i "$SRC" \
+  -vf "crop=512:768:389:0" -frames:v 124 -an "$OUT/driving.mp4"
+
+python "$HERE/../inference/sample.py" \
+  --model-dir "$MODEL_DIR" \
+  --cond "$OUT/driving.mp4" \
+  --ref  "$HERE/media/reference.png" \
+  --out  "$OUT/output.mp4"
+
+echo
+echo "wrote $OUT/output.mp4 -- compare against $HERE/media/output.mp4"

examples/media/audio-pin-driving.mp4

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:fc3dd85a5be2e6246fb40afe46e337cb75d6c3558105fd81fa02f1ff286a5e92
+size 4223283

examples/media/audio-pin-out.mp4

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:25fc5938c25a4dc48d93f388833358ed50cbb8876753ba75ae4e89045c63cf8e
+size 389192

examples/media/compare-cosplay.mp4

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:6bd63ca750de511cbc6391664def22a9671f79d6885729c8d20bc92978fc8843
+size 1099913

examples/media/compare-costume.mp4

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:2a45ac3e161df80bff9e4b220e3282855821d450b1d14974b4e886609e001d8e
+size 447259

examples/media/compare-fastmotion.mp4

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:b79b19f959b370431dc5e090a80068c9046b07504064977d28d47d81e3ef50b7
+size 1183899

examples/media/compare-gamechar.mp4

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:69e34a0ec75f588dfa3c2cdf882fab5bb7107e357e64ceb0d1881d8dbc23452c
+size 858158

examples/media/compare-highkick.mp4

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:6a137d9d19701eb1c75aa9e6b67776cfbf069619d9c0668885a717098f42fe37
+size 847770

examples/media/compare-prop.mp4

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:4128c0e35bf144b5d0e72c5837cc1958421a749337af395977de04fa07b92fea
+size 678070

examples/media/compare-style.mp4

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:692ff38363a0162b965d0c6944e9adb98455c8a4e92419b3f9bb764ce9bd6778
+size 536776

examples/media/hero-corgi.mp4

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:4cb6c4bb9252352e257b9c8b153b5825d7b3a51227c263631169fa609663c3d5
+size 425955

examples/media/hero-duo.mp4

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:cbf81086b77ebbce703d33b9ced930d4f3cabd679c77fc764ad713a5e2bc2d27
+size 187010

examples/media/output.mp4

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:7b89a33a902cd92a1068307b701205029682bb5e5db0326775e3490767f1df04
+size 880425

examples/media/swap-airliner.mp4

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:5a7a31fd225e258633e208f13c18ff8523517834a9ea2c67b97ed060972becf3
+size 397277

examples/media/swap-anime-duo.mp4

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:205700e55841a5fd22f517c6eb08c447068d0417a8e902bc91c863dede743d86
+size 108986

examples/media/swap-claymation.mp4

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:dd08b83d8a57e77408203710cf55eccdf8d1ee136c22123cc42ed8ac14434528
+size 286267

examples/media/swap-corgi.mp4

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:5954aeab0360ac8c1c5c62b5d35935520ac0feffdb8d11b8c55a6ff84f9d9239
+size 272402

examples/media/swap-panda.mp4

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:bec174f093bf553b39d1f022b6fedd46b9616a6ac30fa10a939753cf5e4a5150
+size 390485

examples/media/swap-penguin.mp4

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:ea2ccf8ce410331d194403903e2d1e836079b2d8fbafebf113265e52aafb3cd0
+size 346127

examples/media/swap-photoreal-duo.mp4

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:a2d7c7fb36c5b2779176484b0a2fcb1735578ea3cad2fa0a2c0b057218881554
+size 108311

examples/media/swap-robot.mp4

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:e8147fb8f85eca14e372ecd26f6d7b4556c649f5c980e0dd514a582ac8619077
+size 194541

examples/media/swap-wushu-animals.mp4

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:1ed178d0c88053df75803d904bef26c83c81da78c33d575ec8f5897701b622a7
+size 204001

examples/media/swap-wushu-robots.mp4

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:63cc5dfe297ca472b7c54a9ef32aaa575f84e6cc1088a42d01236e40888785b2
+size 201465

examples/media/teaser.mp4

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:cbe5dd05057bafa9f97750788523d600c8dc1963be181fe56431393b9558ecb0
+size 14442381

inference/sample.py

@@ -0,0 +1,205 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Viggle-Animate: replace the performers in a video with the person in a still.
+
+    python inference/sample.py --cond driving.mp4 --ref character.png --out swapped.mp4
+
+`--cond` supplies the motion, camera framing, background and lighting; `--ref` supplies
+who is in it. Everything about the render except the people is copied from `--cond`.
+
+By default the model generates its own soundtrack, and the fixed prompt asks for silence --
+so there is nothing for the mouth to sync to. `--audio` pins a real one instead:
+
+    python inference/sample.py --cond driving.mp4 --ref character.png \
+        --audio driving.mp4 --out swapped.mp4
+
+The soundtrack is encoded once and held in the target audio rows as a *clean* latent for the
+whole denoise, so the model conditions on it rather than predicting it, and the mouth tracks
+that speech. The track written to `--out` is then that same audio, back through the audio VAE.
+
+The text encoder is never loaded. Conditioning comes from `assets/fixed_embed_fwd_anyframe.pt`,
+a frozen 362 x 5120 tensor computed once from the fixed prompt in `assets/fixed_prompt.txt`,
+so Qwen3-VL (63 GB of the base repo) stays on disk and the text block of the packed sequence
+is 362 rows instead of several thousand. There is no per-clip prompt and no caption: nothing
+in the output comes from text you write.
+
+Needs `--model-dir` pointing at a local copy of MiniMaxAI/MiniMax-H3 for the VAE, the audio
+VAE and the schedulers. This repository ships only the transformer and the LoRA.
+"""
+
+import argparse
+import os
+import time
+
+import torch
+from diffusers import MiniMaxH3Transformer3DModel, ModularPipeline
+from diffusers.modular_pipelines.minimax_h3 import (MiniMaxH3AudioReference, MiniMaxH3ImageReference,
+                                                    MiniMaxH3VideoReference)
+from diffusers.modular_pipelines.minimax_h3.before_encoder import MiniMaxH3Ref2VASetupStep
+from diffusers.modular_pipelines.minimax_h3.encoders import MiniMaxH3Ref2VATextEncoderStep
+from diffusers.modular_pipelines.minimax_h3.modular_pipeline import (align_num_frames,
+                                                                    audio_latent_num_frames)
+from diffusers.utils.export_utils import encode_video
+
+HERE = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+
+parser = argparse.ArgumentParser()
+parser.add_argument("--cond", required=True, help="the video whose motion, framing and background are kept")
+parser.add_argument("--ref", required=True, help="a single still of the person to put in it")
+parser.add_argument("--out", required=True)
+parser.add_argument("--model-dir", required=True,
+                    help="a local copy of MiniMaxAI/MiniMax-H3, for the VAE / audio VAE / schedulers")
+parser.add_argument("--transformer", default=os.path.join(HERE, "transformer"))
+parser.add_argument("--lora", default=os.path.join(HERE, "lora"))
+parser.add_argument("--embed", default=os.path.join(HERE, "assets", "fixed_embed_fwd_anyframe.pt"))
+parser.add_argument("--num-frames", type=int, default=124, help="at 24 fps; 124 frames is ~5.2 s")
+parser.add_argument("--steps", type=int, default=4,
+                    help="the distilled student's operating point. More is not monotonically better: "
+                         "s4 is not a degraded s12")
+parser.add_argument("--flow-shift", type=float, default=3.0,
+                    help="the base model's released default is 12; the few-step student wants 3")
+parser.add_argument("--height", type=int, default=None, help="defaults to the conditioning clip's own height")
+parser.add_argument("--width", type=int, default=None, help="defaults to the conditioning clip's own width")
+parser.add_argument("--short-edge", type=int, default=None,
+                    help="the canvas both references are laid out on. Defaults to the conditioning clip's own "
+                         "short edge, which is what this model was evaluated at")
+parser.add_argument("--offload", action="store_true",
+                    help="stream the transformer from CPU in groups of 5 blocks: ~12 GB resident instead of 62")
+parser.add_argument("--audio", default=None,
+                    help="pin the generated soundtrack to this file's audio -- usually the driving clip "
+                         "itself -- so the mouth tracks real speech instead of the silence the fixed "
+                         "prompt asks for. Any file PyAV can decode; a video's soundtrack is taken")
+parser.add_argument("--seed", type=int, default=42)
+args = parser.parse_args()
+
+fixed = torch.load(args.embed, weights_only=False)
+
+
+def use_fixed_embeds(self, components, state):
+    block_state = self.get_block_state(state)
+    block_state.prompt_embeds = fixed["prompt_embeds"].to(components._execution_device, torch.bfloat16)
+    block_state.text_token_tags = fixed["text_token_tags"]
+    self.set_block_state(state, block_state)
+    return components, state
+
+
+MiniMaxH3Ref2VATextEncoderStep.__call__ = use_fixed_embeds
+
+# `--audio` holds the *target* audio rows at a real soundtrack, clean, for the whole denoise, rather
+# than letting the model generate them. Two of the three things that takes have no argument on the
+# pipeline, so they are patched here; the third is the `audio_latents=` passed to the call below.
+if args.audio:
+    from diffusers.modular_pipelines.minimax_h3.before_denoise import MiniMaxH3SetTimestepsStep
+    from diffusers.modular_pipelines.minimax_h3.denoise import MiniMaxH3LoopSchedulerStep
+
+    # (1) Those rows carry finished audio, so they have to be told they are clean. H3's flow
+    # convention is reversed -- t = 1 is clean, not 0 -- and the library itself passes a literal 1.0
+    # for a *reference* soundtrack. `audio_timestep` is positional argument 6.
+    _build_row_timesteps = MiniMaxH3SetTimestepsStep.build_row_timesteps
+    MiniMaxH3SetTimestepsStep.build_row_timesteps = staticmethod(
+        lambda *a: _build_row_timesteps(*a[:6], 1.0, *a[7:]))
+
+    # (2) ...and the scheduler must never write them, or the first step would walk them off the
+    # soundtrack. Only the video rows are stepped. `num_condition_audio_rows` deliberately stays 0:
+    # raising it empties the decoder's `audio_latents[num_condition_audio_rows:]` slice and trips the
+    # reference-count check, and these rows are a pinned target, not a reference.
+    @torch.no_grad()
+    def video_only_step(self, components, block_state, i, t):
+        n = block_state.num_condition_video_rows
+        block_state.latents[n:] = components.scheduler.step(
+            block_state.noise_pred[0, n:].float(), t, block_state.latents[n:], return_dict=False)[0]
+        return components, block_state
+
+    MiniMaxH3LoopSchedulerStep.__call__ = video_only_step
+
+# The reference order is frozen: the presentation names `<Video 1>` then `<Picture 1>`, and that order
+# advances the shared rotary clock, so it is part of the layout rather than a detail of the prompt. The
+# driving clip's own soundtrack is dropped here, as it is in training: `--audio` puts one back, but as
+# the *target* to be matched rather than as a reference to be imitated.
+video = MiniMaxH3VideoReference.from_file(args.cond)
+video.audio, video.sample_rate = None, None
+
+# Passing an orientation that disagrees with the clip silently generates a transposed video, so the output
+# geometry is derived from the clip rather than typed.
+height = args.height or video.frames.shape[1]
+width = args.width or video.frames.shape[2]
+short_edge = args.short_edge or min(height, width)
+
+pipe = ModularPipeline.from_pretrained(args.model_dir, workflow="ref2va")
+# Both references are pinned to the target's own short edge. The base model's released defaults (768 for the
+# video reference, 2048 for the image) put the references on a grid the target never shares; this model was
+# finetuned and evaluated with them nested, and changing it changes the take.
+pipe.register_to_config(canvas_short_edge=short_edge,
+                        canvas_max_pixels=short_edge * max(height, width),
+                        reference_image_short_edge=short_edge)
+
+t0 = time.time()
+# `transformer_ref` is deliberately absent: our finetune replaces it outright, so loading the base copy
+# first would read 62 GB off disk only to drop it.
+pipe.load_components(names=["vae", "audio_vae", "scheduler", "audio_scheduler"],
+                     pretrained_model_name_or_path=args.model_dir, dtype=torch.bfloat16)
+pipe.transformer_ref = MiniMaxH3Transformer3DModel.from_pretrained(args.transformer, torch_dtype=torch.bfloat16)
+# `prefix=None` and the explicit `weight_name` are both required. The loader defaults to looking for a `.bin`
+# (raises) and to filtering keys for a `transformer.` prefix, which these bare keys do not have -- that
+# mismatch loads *nothing* and only warns, so the default would silently render the un-distilled model.
+pipe.transformer_ref.load_lora_adapter(args.lora, weight_name="pytorch_lora_weights.safetensors", prefix=None)
+pipe.scheduler.set_shift(args.flow_shift)
+
+# The pipeline snaps `num_frames` up to the next `17 * n + 5` the video VAE can encode. Doing it here
+# too means the pinned audio is cut to the length that is really rendered rather than the one asked
+# for -- off by one grid step and the rows no longer line up with the video.
+num_frames = align_num_frames(args.num_frames, pipe.vae_frames_per_chunk, pipe.vae_latents_per_chunk)
+
+if args.offload:
+    pipe.transformer_ref.enable_group_offload(
+        onload_device=torch.device("cuda"), offload_type="block_level", num_blocks_per_group=5,
+        non_blocking=True, use_stream=True, record_stream=True)
+    pipe.vae.to("cuda")
+    pipe.audio_vae.to("cuda")
+else:
+    pipe.to("cuda")
+print(f"loaded in {time.time() - t0:.0f}s; canvas {height}x{width}, references on short edge {short_edge}")
+
+# The soundtrack becomes target rows the same way the pipeline turns a *reference* soundtrack into
+# reference rows: truncate at the source rate, resample once, take the posterior mean, normalize.
+# Reusing its own helper is what keeps the two paths from drifting apart.
+audio_latents = None
+if args.audio:
+    # One video frame more than the render needs, so the encoder cannot come up short. A source
+    # shorter than the grid it renders on is padded, and that tail is real silence.
+    n_samp = round((num_frames + 1) / pipe.fps * pipe.audio_sampling_rate)
+    track = MiniMaxH3AudioReference.from_file(args.audio)
+    wav = MiniMaxH3Ref2VASetupStep._normalize_audio_condition(
+        track.audio, track.sample_rate or pipe.audio_sampling_rate, pipe.audio_sampling_rate,
+        max_duration=(num_frames + 1) / pipe.fps)
+    have = wav.shape[1]
+    wav = torch.nn.functional.pad(wav, (0, max(0, n_samp - have)))[:, :n_samp]
+    with torch.no_grad():
+        # `encode` casts to the encoder's own dtype, so a float32 waveform is fine against a bf16 VAE.
+        posterior = pipe.audio_vae.encode(wav[:, None].to(pipe.audio_vae.device), return_dict=False)[0]
+    mean = torch.tensor(pipe.audio_vae.config.latents_mean).view(1, 1, -1)
+    std = torch.tensor(pipe.audio_vae.config.latents_std).view(1, 1, -1)
+    n_lat = audio_latent_num_frames(num_frames, pipe.fps)
+    # Channel-major rows: the two stereo channels are two batch items of the mono audio VAE.
+    rows = (posterior.mode().float().cpu().transpose(1, 2)[:, :n_lat] - mean) / std
+    if rows.shape[1] != n_lat:
+        raise RuntimeError(f"the soundtrack encoded to {rows.shape[1]} latents, short of the {n_lat} "
+                           f"that {num_frames} frames need")
+    audio_latents = rows.permute(0, 2, 1).contiguous()
+    print(f"pinned {min(have, n_samp) / pipe.audio_sampling_rate:.2f}s of audio -> "
+          f"{tuple(audio_latents.shape)}, over {n_samp / pipe.audio_sampling_rate:.2f}s of video")
+
+t0 = time.time()
+result = pipe(
+    prompt=fixed["presentation"],
+    references=[video, MiniMaxH3ImageReference.from_file(args.ref)],
+    num_frames=num_frames,
+    height=height,
+    width=width,
+    num_inference_steps=args.steps,
+    audio_latents=audio_latents,
+    generator=torch.Generator().manual_seed(args.seed),
+    output=["videos", "audio", "sampling_rate"],
+)
+encode_video(result["videos"][0], fps=24, output_path=args.out,
+             audio=result["audio"][0], audio_sample_rate=result["sampling_rate"])
+print(f"{time.time() - t0:.0f}s, peak {torch.cuda.max_memory_allocated() / 2**30:.1f} GiB -> {args.out}")

lora/pytorch_lora_weights.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:bcdd60965d95e45a0b06f7d27435f21cbc2c8bd4f26f7b1cd8e66af7122c4af8
+size 2666439896

requirements.txt

@@ -0,0 +1,7 @@
+# Tested with these. Nothing here is pinned tightly except diffusers, which is pinned to a
+# commit rather than a release: the `minimax_h3` modular pipeline is newer than any tag.
+torch==2.9.1
+git+https://github.com/huggingface/diffusers@d6726f3
+transformers==4.57.3
+safetensors==0.7.0
+av==16.1.0

transformer/config.json

@@ -0,0 +1,26 @@
+{
+  "_class_name": "MiniMaxH3Transformer3DModel",
+  "_diffusers_version": "0.36.0.dev0",
+  "num_attention_heads": 56,
+  "attention_head_dim": 128,
+  "hidden_size": 5376,
+  "num_layers": 50,
+  "num_refiner_layers": 2,
+  "ffn_dim": 14336,
+  "in_channels": 24,
+  "audio_in_channels": 32,
+  "patch_size": [
+    1,
+    2,
+    2
+  ],
+  "text_dim": 5120,
+  "freq_dim": 256,
+  "time_embed_hidden_dim": 5376,
+  "time_embed_dim": 2688,
+  "rope_freq_dim": 16,
+  "rope_theta": 10000.0,
+  "norm_eps": 1e-05,
+  "qk_norm_eps": 1e-05,
+  "final_norm_eps": 1e-05
+}

transformer/diffusion_pytorch_model-00001-of-00014.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:fb30791125c5814baaefb5bac1e3de2cb9595e027866ffa3a1d1c946789ef427
+size 4945656288

transformer/diffusion_pytorch_model-00002-of-00014.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:58d254c72eb9637b86b11be13f2d648e4dd7c37faddf0fd09f7808faef83e6a4
+size 4490213792

transformer/diffusion_pytorch_model-00003-of-00014.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:bd8410138703641d2f6475f5650aaaa6e2c335b12a992b88aab4cb6465666f3d
+size 4701942704

transformer/diffusion_pytorch_model-00004-of-00014.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:c42d981e9fa75379f14622855f045f2dee79f75b91ced7eeb0247bd4aab1cd95
+size 4933368952

transformer/diffusion_pytorch_model-00005-of-00014.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:2b6fb580aef372b651083570c7c25edfb9dce065b49a3f605499b31109d0f9d2
+size 4567284240

transformer/diffusion_pytorch_model-00006-of-00014.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:a3183d396d2fc2d695145c98988742849658561e7e2f69ce8c3a78d414a363a0
+size 4701942704