Meridian

.gitattributes

@@ -0,0 +1,96 @@
+*.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
+docs/assets/research/meridian_architecture.png filter=lfs diff=lfs merge=lfs -text
+docs/assets/research/meridian_illustrated_method.png filter=lfs diff=lfs merge=lfs -text
+docs/assets/research/meridian_method.png filter=lfs diff=lfs merge=lfs -text
+docs/assets/research/meridian_nba_generation.png filter=lfs diff=lfs merge=lfs -text
+examples/media/sp_bouldering_hang.mp4 filter=lfs diff=lfs merge=lfs -text
+examples/media/sp_bouldering_reach.mp4 filter=lfs diff=lfs merge=lfs -text
+videos-all/meridian_ballet_t30_female_arc/out.mp4 filter=lfs diff=lfs merge=lfs -text
+videos-all/meridian_ballet_t30_male_lowarc/out.mp4 filter=lfs diff=lfs merge=lfs -text
+videos-all/meridian_longtake_l150_nba3_apex_right14_175/out.mp4 filter=lfs diff=lfs merge=lfs -text
+videos-all/meridian_longtake_l150_nba3_apex_right14_175/render.mp4 filter=lfs diff=lfs merge=lfs -text
+videos-all/meridian_longtake_l150_nba3_apex_right14_175/source.mp4 filter=lfs diff=lfs merge=lfs -text
+videos-all/meridian_longtake_t30_gymnast_pink_rise12/out.mp4 filter=lfs diff=lfs merge=lfs -text
+videos-all/meridian_longtake_t30_gymnast_pink_rise12/source.mp4 filter=lfs diff=lfs merge=lfs -text
+videos-all/meridian_longtake_t30_moto_dust_retreat25/out.mp4 filter=lfs diff=lfs merge=lfs -text
+videos-all/meridian_longtake_t30_moto_dust_retreat25/source.mp4 filter=lfs diff=lfs merge=lfs -text
+videos-all/meridian_longtake_t30_powder_frontal_rise18/out.mp4 filter=lfs diff=lfs merge=lfs -text
+videos-all/meridian_longtake_t30_powder_frontal_rise18/source.mp4 filter=lfs diff=lfs merge=lfs -text
+videos-all/meridian_material_l150_charge_event_return22/out.mp4 filter=lfs diff=lfs merge=lfs -text
+videos-all/meridian_material_l150_charge_event_return22/source.mp4 filter=lfs diff=lfs merge=lfs -text
+videos-all/meridian_motion_l150_moto_event_return30/out.mp4 filter=lfs diff=lfs merge=lfs -text
+videos-all/meridian_motion_l150_moto_event_return30/source.mp4 filter=lfs diff=lfs merge=lfs -text
+videos-all/meridian_nba3_l150_air_left14/out.mp4 filter=lfs diff=lfs merge=lfs -text
+videos-all/meridian_nba3_l150_air_right14/out.mp4 filter=lfs diff=lfs merge=lfs -text
+videos-all/meridian_nba3_l150_moment38_left14/out.mp4 filter=lfs diff=lfs merge=lfs -text
+videos-all/meridian_nba3_l150_moment54_right14/out.mp4 filter=lfs diff=lfs merge=lfs -text
+videos-all/meridian_return_l150_berry_event22/out.mp4 filter=lfs diff=lfs merge=lfs -text
+videos-all/meridian_return_l150_berry_event22/source.mp4 filter=lfs diff=lfs merge=lfs -text
+videos-all/nba3_teacher30/nba3_full_event.mp4 filter=lfs diff=lfs merge=lfs -text
+videos-all/overnight/sources/dutch_ballet_female_2575.png filter=lfs diff=lfs merge=lfs -text
+videos-all/overnight/sources/dutch_ballet_male_1900.png filter=lfs diff=lfs merge=lfs -text
+videos-all/research_examples_v1/ballet.mp4 filter=lfs diff=lfs merge=lfs -text
+videos-all/research_examples_v1/ballet_male.mp4 filter=lfs diff=lfs merge=lfs -text
+videos-all/research_examples_v1/berry.jpg filter=lfs diff=lfs merge=lfs -text
+videos-all/research_examples_v1/berry.mp4 filter=lfs diff=lfs merge=lfs -text
+videos-all/research_examples_v1/charge.jpg filter=lfs diff=lfs merge=lfs -text
+videos-all/research_examples_v1/charge.mp4 filter=lfs diff=lfs merge=lfs -text
+videos-all/research_examples_v1/gymnast.mp4 filter=lfs diff=lfs merge=lfs -text
+videos-all/research_examples_v1/moto.jpg filter=lfs diff=lfs merge=lfs -text
+videos-all/research_examples_v1/moto.mp4 filter=lfs diff=lfs merge=lfs -text
+videos-all/research_examples_v1/moto_return.jpg filter=lfs diff=lfs merge=lfs -text
+videos-all/research_examples_v1/moto_return.mp4 filter=lfs diff=lfs merge=lfs -text
+videos-all/research_examples_v1/nba.jpg filter=lfs diff=lfs merge=lfs -text
+videos-all/research_examples_v1/nba.mp4 filter=lfs diff=lfs merge=lfs -text
+videos-all/research_examples_v1/powder.jpg filter=lfs diff=lfs merge=lfs -text
+videos-all/research_examples_v1/powder.mp4 filter=lfs diff=lfs merge=lfs -text
+videos-all/research_examples_v1/robot.jpg filter=lfs diff=lfs merge=lfs -text
+videos-all/research_examples_v1/robot.mp4 filter=lfs diff=lfs merge=lfs -text
+videos-all/studio_walkthrough/nba3_preview_live_02/studio_walkthrough_concise.mp4 filter=lfs diff=lfs merge=lfs -text
+videos-all/studio_walkthrough/nba3_preview_live_02/studio_walkthrough_concise_poster.jpg filter=lfs diff=lfs merge=lfs -text
+videos-all/teaser_meridian_showcase_v7.mp4 filter=lfs diff=lfs merge=lfs -text
+videos-all/va_pi3_hi/out.mp4 filter=lfs diff=lfs merge=lfs -text
+videos-all/va_pi3_hi/source.mp4 filter=lfs diff=lfs merge=lfs -text
+videos-all/research_examples_v2/motor_compound.jpg filter=lfs diff=lfs merge=lfs -text
+videos-all/teaser_meridian_compound_motor_dust_explained_v1.mp4 filter=lfs diff=lfs merge=lfs -text
+videos-all/meridian_ballet_l150_female_reverse45.mp4 filter=lfs diff=lfs merge=lfs -text
+videos-all/longtake_edit/multisegment/work_gpu3/takes/1789313901_4e9dd3_11/source.mp4 filter=lfs diff=lfs merge=lfs -text
+videos-all/longtake_edit/multisegment/work_gpu3/takes/1789313901_4e9dd3_11/out.mp4 filter=lfs diff=lfs merge=lfs -text
+videos-all/meridian_ballet_l150_female_reverse45/out.mp4 filter=lfs diff=lfs merge=lfs -text
+assets/meridian_method.png filter=lfs diff=lfs merge=lfs -text
+videos-all/teaser_meridian_showcase_v9.mp4 filter=lfs diff=lfs merge=lfs -text
+videos-all/teaser_meridian_showcase_v12.mp4 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,62 @@
+# 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/`
+(the `fl2va` video transformer, 50 layers) and every parameter was updated by a full finetune on a
+re-camera objective (source clip + a point-cloud render from a second camera → that camera's clip). The
+architecture, `config.json` and tensor names are unchanged, so it is a drop-in replacement for the base
+`transformer/`; 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, because HuggingFace rejects single files above 50 GB. The 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 the linear layers of `transformer/`, trained by us with DMD
+distillation. It is a delta on the finetuned transformer above, not on the base model; loading it onto
+the stock `transformer/` produces garbage. Its sampling grid is `--steps 4 --flow-shift 3`.
+
+## `assets/fixed_embed_{n}.pt`, `assets/silence_audio_{n}.pt` — new
+
+Not MiniMax files. Frozen text-conditioning tensors (one per supported output length) computed once
+with the base model's own text encoder from the prompt in `assets/prompt.txt`, so that inference never
+loads Qwen3-VL, and the audio latent of silence at each length. They are *outputs* of the base model's
+encoders in the sense of Section I.12.
+
+## `assets/prompt.txt` — new
+
+Not a MiniMax file. The prompt text the embeddings above were computed from, included so that what
+conditions every render is readable rather than opaque.
+
+## `recam/`, `inference/`, `service/` — new
+
+Not MiniMax files. Written by us against the public `diffusers` API (`recam/h3.py` calls the pipeline's
+own layout builder and scheduler; nothing in `diffusers` is patched). Licensed under Apache 2.0
+(`LICENSE-CODE`); each Python file carries an `SPDX-License-Identifier: Apache-2.0` header.
+
+## Not included: VGGT-Omega
+
+Inference depends on Meta's VGGT-Omega for geometry. It is not redistributed here (FAIR Noncommercial
+Research License, gated weights); `recam/geometry.py` imports it from a path you provide. See README.md.
+
+## `LICENSE`, `LICENSE-CODE`, `NOTICE`
+
+`LICENSE` is the MiniMax H3 Community License Agreement, included unmodified as Section III.1 requires.
+`LICENSE-CODE` is the Apache 2.0 text and covers the code directories only. `NOTICE` records the
+attribution and that the weights are not Apache 2.0.
+
+Sampling draws every noise tensor on the CPU from the seeded generator, so a `--seed` reproduces across
+GPU models. The internal tooling drew them in a different order and on the device, so a seed does not
+reproduce a take made with it.
+
+## `examples/media/` — new
+
+Two clips from Wikimedia Commons under CC0, cut to 73 frames at 1280 × 720 with the soundtrack removed.
+Provenance in `examples/CREDITS.md`. Not MiniMax material.

NOTICE

@@ -0,0 +1,22 @@
+MiniMax H3 is licensed under the MiniMax H3 Community License Agreement,
+Copyright © 2026 MiniMax. All Rights Reserved.
+
+---
+
+Viggle-Recam 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.
+
+The code in recam/, inference/ and service/ is licensed under the Apache
+License 2.0 (LICENSE-CODE). The model weights are not.
+
+This repository does not contain VGGT-Omega. Inference depends on it, and it is
+distributed by Meta under the FAIR Noncommercial Research License; see README.md.
+
+The two clips in examples/media/ are Wikimedia Commons material released under
+CC0 1.0; see examples/CREDITS.md.

README.md

@@ -0,0 +1,259 @@
+---
+license: other
+license_name: minimax-h3-community-license
+license_link: LICENSE
+base_model: MiniMaxAI/MiniMax-H3
+pipeline_tag: video-to-video
+tags:
+  - video-to-video
+  - novel-view-synthesis
+  - camera-control
+  - re-camera
+---
+
+# Meridian: A new perspective on space and time
+
+By **Viggle AI** · built on **[MiniMax-H3](https://huggingface.co/MiniMaxAI/MiniMax-H3)** ·
+geometry by **[VGGT-Omega](https://github.com/facebookresearch/vggt-omega)**
+
+**One event. Anywhere. Anytime.**
+
+**Meridian is a geometry-guided video model for authoring new observations of existing events.**
+Revisit a recorded event from a new viewpoint. Let the action unfold, slow it down, or hold a
+moment still—all while moving the camera along a path you choose.
+You can also create a camera move from a single image.
+
+[Quickstart](#quickstart) · [Method](#method)
+
+<div class="film hero-film">
+  <video id="teaser-film" controls playsinline preload="none" width="100%" poster="https://huggingface.co/Viggle/Meridian/resolve/main/videos-all/longtake_showcase/teaser_v12/intro_059.jpg" src="https://huggingface.co/Viggle/Meridian/resolve/main/videos-all/teaser_meridian_showcase_v12.mp4" aria-label="Meridian teaser: a new perspective on space and time">
+    <a href="https://huggingface.co/Viggle/Meridian/resolve/main/videos-all/teaser_meridian_showcase_v12.mp4">Watch the Meridian teaser</a>.
+  </video>
+  <p class="film-caption">51-second teaser</p>
+</div>
+
+## See it in motion
+
+The motocross example includes the original video and a diagram of the planned camera path.
+The ballet example uses a single photograph. The NBA edit labels the parts taken from the original footage.
+
+<table class="video-grid">
+  <tr>
+    <td width="50%" valign="top">
+      <video id="nba-film" controls playsinline preload="none" width="100%" poster="https://huggingface.co/Viggle/Meridian/resolve/main/videos-all/research_examples_v1/nba.jpg" src="https://huggingface.co/Viggle/Meridian/resolve/main/videos-all/research_examples_v1/nba.mp4" aria-label="NBA edit combining labeled source footage and generated views of held moments">
+        <a href="https://huggingface.co/Viggle/Meridian/resolve/main/videos-all/research_examples_v1/nba.mp4">Watch the example</a>.
+      </video>
+      <p><strong>A dunk.</strong> A new look at the same play. This edit combines generated views with original footage, including the dunk's finish.</p>
+    </td>
+    <td width="50%" valign="top">
+      <video id="berry-film" controls playsinline preload="none" width="100%" poster="https://huggingface.co/Viggle/Meridian/resolve/main/videos-all/research_examples_v1/berry.jpg" src="https://huggingface.co/Viggle/Meridian/resolve/main/videos-all/research_examples_v1/berry.mp4" aria-label="Strawberries: source time advances, holds while the camera moves, then resumes">
+        <a href="https://huggingface.co/Viggle/Meridian/resolve/main/videos-all/research_examples_v1/berry.mp4">Watch the example</a>.
+      </video>
+      <p><strong>Play. Hold. Resume.</strong> Pause the splash, move the camera, then let the action continue.</p>
+    </td>
+  </tr>
+  <tr>
+    <td width="50%" valign="top">
+      <video id="moto-film" controls playsinline preload="none" width="100%" poster="https://huggingface.co/Viggle/Meridian/resolve/main/videos-all/research_examples_v2/motor_compound.jpg" src="https://huggingface.co/Viggle/Meridian/resolve/main/videos-all/teaser_meridian_compound_motor_dust_explained_v1.mp4" aria-label="Motocross: one uncut take with a compound camera path, selected source video, and requested camera diagrams">
+        <a href="https://huggingface.co/Viggle/Meridian/resolve/main/videos-all/teaser_meridian_compound_motor_dust_explained_v1.mp4">Watch the example</a>.
+      </video>
+      <p><strong>Compose a camera path.</strong> Orbit, move sideways, and change distance—all in one continuous shot.</p>
+    </td>
+    <td width="50%" valign="top">
+      <video id="ballet-film" controls playsinline preload="none" width="100%" poster="https://huggingface.co/Viggle/Meridian/resolve/main/videos-all/research_examples_v2/ballet_reverse45.jpg" src="https://huggingface.co/Viggle/Meridian/resolve/main/videos-all/meridian_ballet_l150_female_reverse45.mp4" aria-label="Female ballet dancer: generated camera movement from one still image">
+        <a href="https://huggingface.co/Viggle/Meridian/resolve/main/videos-all/meridian_ballet_l150_female_reverse45.mp4">Watch the example</a>.
+      </video>
+      <p><strong>One image. Another viewpoint.</strong> A camera move from a single ballet photograph.</p>
+    </td>
+  </tr>
+</table>
+
+## Space and time, independently
+
+| Choose… | What you can do |
+|---|---|
+| **Where to watch from** | Orbit, move in or out, slide sideways, or move up and down. Set the viewing direction and field of view. |
+| **When to watch** | Choose a sequence, hold one frame, or slow down / speed up the input video before generation. |
+| **How the two meet** | Move around a frozen moment, follow slow-motion action, or choose a new angle for a sped-up sequence. |
+
+Bullet time is one combination—not the boundary of the model. To slow down or speed up the
+action, retime the input video first. Then design the camera path over that timeline.
+
+## Beyond the frame
+
+A camera's position shapes how an event is seen: what draws our attention, what feels close,
+and what remains outside the frame. Meridian explores keeping some of those choices open
+after capture.
+
+For filmmakers, this opens room to compose a new shot around an existing moment—not just edit
+what the camera recorded, but generate another way of observing it. In the longer term, that
+freedom could extend to viewers: choosing a perspective, following a subject, or lingering on
+a detail rather than watching only a predetermined sequence.
+
+**The event has passed. The choice of how to see it remains open.**
+
+## Method
+
+![VGGT-Omega estimates depth and camera poses from the input video. Colored 3D points are rendered along the chosen camera path to produce a warped video. Meridian uses this reference and the matching input frames to generate a new view. Video frames are real examples; points and cameras are schematic.](https://huggingface.co/Viggle/Meridian/resolve/main/assets/meridian_method.png)
+
+*The same moment in the input, warped reference, and output. The 3D points and cameras are schematic.*
+
+**Choose the moment. Place the camera. Render the reference. Complete the view.**
+
+1. **Build the geometry.** VGGT-Omega estimates depth and camera poses from the input video.
+   We use these estimates to turn the selected frames into colored 3D points.
+2. **Render the new view.** For each output frame, choose a moment from the input and a camera
+   viewpoint. Render the corresponding points from that view, leaving uncovered regions grey.
+3. **Generate the shot.** Meridian takes the input video and the matching rendered video as
+   references, then fills in missing regions and refines the image.
+
+**Preview before generation.** Once the 3D points are available, rendering the reference is fast.
+You can check the framing and camera motion, spot gaps in the view, and adjust the path before
+running the video model.
+
+## Model
+
+Meridian uses **MiniMax-H3's transformer and VAE, without loading a text encoder at inference**.
+The task's text embeddings are precomputed; the transformer architecture is unchanged.
+
+| Component | Role |
+|---|---|
+| `transformer/` | Meridian's finetuned MiniMax-H3 checkpoint; 61.7 GiB in bf16. |
+| `lora/` | Fast-inference adapter; 2.5 GiB. Default: `--steps 4 --flow-shift 3`, **3 forwards**. |
+| `assets/` | Precomputed text embeddings, audio-layout assets, and the readable task prompt. |
+
+**Use the adapter with Meridian's transformer, not the unmodified MiniMax-H3 checkpoint.**
+
+- **Output:** 24 fps, aspect-matched 768-class canvas; 1344 × 768 for a 16:9 input.
+- **Lengths:** 73, 90, 107, 124, 141, 158, 175, or 243 frames—approximately 3–10 seconds per take.
+- **Included tools:** inference CLI, runtime assets, sample clips, and a prototype Studio.
+
+## Install
+
+Follow the **[installation guide](docs/installation.md)** for code, checkpoint setup, dependencies,
+and the separately obtained VGGT-Omega geometry model. Inference requires Meridian's transformer
+and adapter, the MiniMax-H3 VAE, and VGGT-Omega. Checkpoint availability and paths are listed in the guide.
+
+The reference implementation runs on one high-memory CUDA GPU; memory and timings are reported below.
+It does not currently expose quantization, CPU offloading, or multi-GPU sharding.
+
+**Community: bring Meridian to smaller GPUs.** Keeping MiniMax-H3's architecture and omitting the
+text encoder provides a starting point for adapting community memory-saving techniques. We welcome
+work on quantization and CPU offloading toward consumer GPUs such as the **RTX 4090**. These are
+integration targets, not supported or validated configurations in the current scripts.
+
+Review the licenses before use: the code license does not cover the weights or remove
+VGGT-Omega's noncommercial restrictions.
+
+## Quickstart
+
+After completing installation, including the separately supplied weights, run from the Meridian
+directory. The included CC0 sample clips are already 24 fps and contain 73 frames each.
+
+```bash
+# A gentle 15° orbit over the live event.
+python inference/sample.py --video examples/media/sp_bouldering_hang.mp4 \
+  --yaw 15 --sweep --ease --out out/orbit
+
+# Play 24 frames, then hold frame 24 for 49 output frames while orbiting.
+python inference/sample.py --video examples/media/sp_bouldering_reach.mp4 \
+  --yaw 35 --freeze 24:49 --out out/bullet
+```
+
+Open `out/orbit/grid.mp4` to compare **source → geometry reference → generated take**. The take is
+`out.mp4`; `render.mp4` shows the geometric input with grey holes.
+
+For your own footage, use a continuous shot exported at **constant 24 fps**. The CLI reads frames
+by index: an ordinary take needs at least `start + frames` input frames. It does not normalize the
+frame rate or detect cuts for you.
+
+## Self-hosting the demo
+
+<div class="film">
+  <video id="studio-film" controls playsinline preload="none" width="100%" poster="https://huggingface.co/Viggle/Meridian/resolve/main/videos-all/studio_walkthrough/nba3_preview_live_02/studio_walkthrough_concise_poster.jpg" src="https://huggingface.co/Viggle/Meridian/resolve/main/videos-all/studio_walkthrough/nba3_preview_live_02/studio_walkthrough_concise.mp4" aria-label="Early Studio demo: actual authoring and geometric preview, not final generation">
+    <a href="https://huggingface.co/Viggle/Meridian/resolve/main/videos-all/studio_walkthrough/nba3_preview_live_02/studio_walkthrough_concise.mp4">Watch the Studio walkthrough</a>.
+  </video>
+  <p class="film-caption">Designing a camera path and previewing the geometry.</p>
+</div>
+
+**Early prototype.** The Studio is a very basic, vibe-coded demo, not a production editor.
+The walkthrough shows one simple way to use it.
+
+```bash
+CARD=0 bash service/run.sh --host 127.0.0.1 --port 8412
+```
+
+Open `http://127.0.0.1:8412` once the terminal prints `ready`.
+
+Upload a clip, design a path with multiple camera keyframes, preview the geometry, then generate.
+The browser provides **real-time 3D feedback** once geometry is loaded; full-path rendering and
+final video generation are separate GPU operations, not real-time generative video.
+
+The service has no authentication. The command above binds to loopback; do not expose this
+prototype directly to the internet.
+
+## Performance
+
+Reported results on **one B200 with the service resident**, using the default adapter:
+
+| Output length | Take generation | Peak GPU memory |
+|---|---|---|
+| 73 frames | ~36 s | 88 GiB |
+| 124 frames | ~80 s | 89 GiB |
+| 243 frames | ~150 s | 113 GiB |
+
+Generation timings start with geometry prepared; upload processing and reconstruction are separate.
+A 73-frame reference warp was reported at **0.24 s**, versus approximately 36 s for generation.
+These are indicative measurements, not guarantees across GPUs, resolutions, or cache states.
+
+## Limitations
+
+Unseen surfaces are generated, not recovered.
+
+- **Geometry robustness.** Meridian generally handles imperfect geometry well, but cannot reliably
+  recover from severe errors or a badly warped reference.
+- **Large moves are less stable.** Full 360° orbits can work, but large viewpoint changes can cause
+  distortion, drift, or inconsistent details in newly visible areas.
+- **Timing and continuity.** Retiming changes which input frames are used; it does not recover
+  missing motion. Separately generated clips may not join smoothly.
+
+## Documentation and code
+
+[Inference guide](docs/inference.md) — camera recipes, source timing, CLI options, and troubleshooting.
+
+Implementation lives in `recam/`, the CLI in `inference/sample.py`, and the Studio in `service/`.
+
+## License
+
+- **Weights** (`transformer/`, `lora/`, `assets/*.pt`): the
+  [MiniMax H3 Community License Agreement](LICENSE). Meridian (released as Viggle-Recam) is a Model
+  Derivative of MiniMax-H3; `MODIFICATIONS.md` is the Section III.2 notice. Powered by MiniMax H3.
+  The Agreement licenses use
+  and distribution of the weights and their outputs in its Applicable Territory only, which excludes
+  the European Union, the United Kingdom, the Republic of Korea and the United States (Section I.3,
+  I.5, V.4); read it before you download.
+- **Code** (`recam/`, `inference/`, `service/`): [Apache 2.0](LICENSE-CODE).
+- **VGGT-Omega**: not included. FAIR Noncommercial Research License v1, obtained from Meta separately;
+  see [Install](#install).
+- **Sample clips**: Wikimedia Commons, CC0; see [`examples/CREDITS.md`](examples/CREDITS.md).
+
+## Intended use
+
+Exploring new viewpoints and timing in footage you have the rights to, for previsualisation, editing,
+and creative work. Do not use it to fabricate footage of real people or events presented as genuine,
+and label what you generate as AI-generated. If you pass the weights on or host them, the Agreement
+makes you bind your users to its
+use restrictions and tell them so (Section V.2), keep safeguards on any generation service (V.5),
+display "MiniMax H3" in a commercial product's interface (IV.2), and ask MiniMax for authorization above
+US$20M yearly revenue (IV.1).
+
+## Citation
+
+```bibtex
+@misc{viggle-meridian-2026,
+  title  = {Meridian: A New Perspective on Space and Time},
+  author = {Viggle AI},
+  year   = {2026},
+  url    = {https://huggingface.co/Viggle/Meridian}
+}
+```

assets/fixed_embed_107.pt

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

assets/fixed_embed_124.pt

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

assets/fixed_embed_141.pt

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

assets/fixed_embed_158.pt

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

assets/fixed_embed_175.pt

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

assets/fixed_embed_243.pt

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

assets/fixed_embed_73.pt

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

assets/fixed_embed_90.pt

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

assets/prompt.txt

@@ -0,0 +1,16 @@
+subject_definitions:
+<Video 1> is the source video for the editing task.
+<Video 2> is a rough render of the same scene from the new camera: the pixels of <Video 1> re-projected through a point cloud, so wherever it shows content its colours, framing and layout are correct, and its flat mid-grey areas are holes where the source camera saw nothing.
+
+summary:
+[video editing + viewpoint change] The target video shows exactly the same scene as <Video 1>, at exactly the same moments in time, filmed by the second camera that <Video 2> was rendered from. Every subject, every piece of clothing, the background, the lighting and the whole performance are the ones in <Video 1>; only the camera differs, so the same things are seen from a different angle and at a different distance. The target video is <Video 2> completed: its framing and everything it shows are kept, and its grey holes are filled with what belongs there.
+
+retention_analysis:
+<Video 1> (source video editing): fully_preserved - the subjects, their faces, hair, build and clothing, the background, the props and the lighting are the same objects seen from a new viewpoint, and the motion and its timing are frame for frame the motion of <Video 1>. Nothing is added, removed or restyled.
+<Video 2> (layout reference): fully_preserved - the camera path, the framing and the placement of everything it shows are kept exactly; its grey holes are not content and are filled in so that they agree with <Video 1>, and its speckles and jagged edges are cleaned up.
+
+detailed_description:
+[Shot 1] One continuous shot of the scene of <Video 1>, framed exactly as <Video 2> is, frame for frame. The subjects perform the motion of <Video 1> with the same timing, in the same place, under the same lighting. The camera moves exactly as the camera of <Video 2> does, and there is no cut.
+
+overall_soundscape:
+No music and no speech.

assets/silence_audio_107.pt

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

assets/silence_audio_124.pt

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

assets/silence_audio_141.pt

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

assets/silence_audio_158.pt

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

assets/silence_audio_175.pt

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

assets/silence_audio_243.pt

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

assets/silence_audio_73.pt

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

assets/silence_audio_90.pt

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

docs/api.md

@@ -0,0 +1,168 @@
+# Local studio API
+
+[← Meridian](../README.md) · [Studio and deployment](studio.md) · [Method](method.md)
+
+The FastAPI service exposes the same preparation and rendering operations used by the studio.
+This is a development API for a trusted, single-GPU deployment—not an authenticated multi-user
+service. Requests are plain JSON except for multipart upload. All source indices refer to the
+**normalized 24 fps clip**, not the original upload's timestamps.
+
+## Request flow
+
+```text
+/upload or /sample → /prepare → /warp → inspect → /render → /job/{job} → /take/{job}/{name}
+```
+
+`/prepare` must populate the source-span cache before `/warp` or `/render`. Keep the same `clip`,
+`start`, and `span_end` across those calls. If that cache entry is evicted or the service restarts,
+prepare again. Do not change requests while assuming a previously inspected preview still applies.
+
+## Shared fields
+
+| Field | Meaning |
+|---|---|
+| `clip` | ID returned by `/upload` or `/sample`. |
+| `start` | First source frame of the prepared span, inclusive. |
+| `span_end` | Last source frame of that span, inclusive. Must satisfy `0 <= start < span_end < clip.frames`. |
+| `frames` | Output length. Use one of `73, 90, 107, 124, 141, 158, 175, 243` for generation. |
+| `pivot` | Optional `[u, v]` in normalized source-image fractions; default `[0.5, 0.5]`. Sets the depth-scale neighborhood. |
+| `pivot_frame` | Source frame at which to measure pivot depth; set it explicitly, normally to `start`. |
+| `seed` | Generation seed, default `1234`. |
+| `path` | List of at least two camera keys. |
+
+The current API's per-endpoint validation is limited; unsupported output lengths may fail only when
+loading conditioning assets. Validate requests before submitting expensive GPU work. Choose a
+continuous source span: the browser avoids detected cuts, but the API does not enforce that policy.
+
+### Camera keys
+
+| Field | Meaning |
+|---|---|
+| `pos` | `[x, y, z]` position in the coordinate frame of the source camera at `start`, in units of `zm`. |
+| `look` | Look-at point in the same frame and units. |
+| `src` | Absolute source-frame index, within the prepared span. |
+| `t` | Output-frame index. First key is `0`, last is `frames - 1`; intermediate values strictly increase. |
+| `ease` | Optional boolean, default `false`. Eases camera position/look-at motion in the segment leaving this key. |
+| `focal` | Optional positive focal multiplier, default `1`, relative to that source frame's estimated lens. |
+
+Axes are **x right, y down, z forward**. Source indices must be non-decreasing. Position and look-at
+points follow slope-limited cubic Hermite/Catmull-Rom interpolation; source indices and focal
+multipliers interpolate linearly. Source indices are rounded to integers. Orientation is derived
+from the look-at direction with zero roll. Equal adjacent `src` values create a hold.
+
+## Minimal walkthrough
+
+Start the [service](studio.md#start-the-service), then upload a continuous clip containing at least
+73 normalized frames:
+
+```bash
+curl -sS -F 'file=@clip.mp4' http://127.0.0.1:8412/upload
+```
+
+Copy the response's `clip` value into the following JSON and save it as `take.json`. This example
+slides the camera right by `0.15 zm` while looking toward a point one depth unit ahead of the initial
+camera. For subject-specific framing, use the `piv` returned by `/prepare` as your look-at reference.
+
+```json
+{
+  "clip": "CLIP_ID_FROM_UPLOAD",
+  "start": 0,
+  "span_end": 72,
+  "frames": 73,
+  "pivot": [0.5, 0.5],
+  "pivot_frame": 0,
+  "seed": 1234,
+  "path": [
+    {"pos": [0, 0, 0], "look": [0, 0, 1], "src": 0, "t": 0, "ease": true, "focal": 1},
+    {"pos": [0.15, 0, 0], "look": [0, 0, 1], "src": 72, "t": 72, "ease": false, "focal": 1}
+  ]
+}
+```
+
+Prepare the geometry, then produce a preview. `/prepare` ignores the extra path fields:
+
+```bash
+curl -sS -H 'Content-Type: application/json' --data-binary @take.json \
+  http://127.0.0.1:8412/prepare
+
+curl -sS -H 'Content-Type: application/json' --data-binary @take.json \
+  http://127.0.0.1:8412/warp
+```
+
+Open the returned `truth` and `holes` URLs relative to the service origin, and inspect `ahead`,
+`moved`, and `speed`. Generation is a separate, expensive step:
+
+```bash
+curl -sS -H 'Content-Type: application/json' --data-binary @take.json \
+  http://127.0.0.1:8412/render
+```
+
+Copy the returned job ID into the commands below. Poll until `done` is true, and check that there is
+**no `error`** before downloading; failed jobs also set `done: true`.
+
+```bash
+curl -sS http://127.0.0.1:8412/job/JOB_ID_FROM_RENDER
+curl -f -o out.mp4 http://127.0.0.1:8412/take/JOB_ID_FROM_RENDER/out.mp4
+```
+
+`/render` does not enforce the browser's clearance or camera-change gates and does not require that
+`/warp` was called first. This walkthrough includes preview inspection intentionally. A returned job
+ID means the background task was started, not that input validation or generation succeeded.
+
+## Endpoints
+
+Paths below are relative to the service origin. “Shared fields” refers to the table above; not every
+endpoint consumes every field.
+
+| Endpoint | Request | Response |
+|---|---|---|
+| `GET /` | — | Studio HTML. |
+| `GET /samples` | — | Array of available sample MP4 filenames. |
+| `POST /upload` | Multipart `file`. | `{clip, frames, w, h, name, cuts, seconds, lengths}`. |
+| `POST /sample` | `{name}` from `/samples`. | Same clip metadata as upload. |
+| `POST /prepare` | `clip, start, span_end`; optional `pivot, pivot_frame`. | `{box, canvas, cond_canvas, ms, src_poses, piv, zm}`. |
+| `POST /cloud` | Shared fields plus absolute source `frame`, optional `stride` (default `5`). | `{n, zm, pts, rgb}`; flattened triples in path coordinates. |
+| `POST /warp1` | Shared fields plus `src, pos, look`; optional `focal`. | One geometry-reference JPEG at conditioning resolution. |
+| `POST /warp` | Shared fields plus `path`; optional `lite`. | Gauges, cameras, source mapping, and preview URLs. `lite: true` omits the hole/sketch previews. |
+| `POST /render` | Shared fields plus `path`. | `{job}`; rendering continues in a background thread. |
+| `GET /job/{job}` | — | Status including `stage, pct, done, payload`; `t`, `error`, or `gauges` when available. |
+| `GET /frame/{clip}/{i}.jpg` | Source index in the URL. | JPEG of the normalized source frame. |
+| `GET /warpfile/{clip}/{name}` | Use a URL returned by `/warp`. | Preview file. |
+| `GET /take/{job}/{name}` | Completed job ID and filename. | `out.mp4`, `source.mp4`, `render.mp4`, `grid.mp4`, or `last.png`. |
+
+`lengths` in upload metadata is the studio's four-option length menu, not an exhaustive list of
+asset-supported lengths. `src_poses[i]` in `/prepare` corresponds to absolute source frame
+`start + i`; each entry includes `pos`, `look`, `roll`, and normalized lens values `k`.
+
+Job `t` is elapsed time **since submission, including queue wait**. It first appears when processing
+starts and updates at stage transitions, not continuously on polling. It is not a pure render-time
+measurement.
+
+### Warp response
+
+- **`truth`**: grey-hole reference MP4 at conditioning resolution.
+- **`holes`**: magenta-hole diagnostic MP4, unless `lite` is true.
+- **`sketch`**: output-resolution geometric rasterization, unless `lite` is true; not the final
+  conditioning-resolution reference.
+- **`canvas`, `cond_canvas`**: `[width, height]` for the target and references.
+- **`tmap`**: selected source index for every output frame.
+- **`cams`**: per-output-frame position/look-at description; `piv` and `zm` describe the pivot/scale.
+- **`speed`**: source-frame rate per key segment; zero is a hold, one preserves the input pace.
+- **`coverage`**: mean geometric coverage at the rasterization resolution, not a calibrated quality score.
+- **`ahead`, `near`, `behind`, `coll`, `moved`**: geometric diagnostics. See [Preview checks](studio.md#preview-checks).
+- **`ms`**: elapsed time for the warp endpoint, including preview encoding.
+
+`turned` and `zoomed` are computed by the browser from keys; they are not fields returned by `/warp`.
+
+## Operational boundaries
+
+One process serializes GPU work through a lock. The API has no cancellation, durable queue, session
+restoration, authentication, or automatic file retention policy. Clip and geometry caches can evict
+entries while files remain on disk. Do not assume an old ID remains usable after a restart or eviction.
+
+Assertions and runtime failures may surface as HTTP errors rather than structured validation
+responses. Render failures can arrive asynchronously through `/job/{job}`. The automatically served
+FastAPI schema does not describe these JSON payloads fully because the handlers read request bodies
+directly; use this guide alongside [`service/app.py`](../service/app.py).
+
+For service flags, cache behavior, and deployment precautions, see [Studio](studio.md#memory-and-lifecycle).

docs/assets/research/README.md

@@ -0,0 +1,162 @@
+# Research figure assets
+
+[← Research article](../../research.md) · [Technical method](../../method.md)
+
+## Illustrated method
+
+The article uses one integrated illustration:
+[editable SVG](meridian_illustrated_method.svg) · [PNG](meridian_illustrated_method.png) ·
+[provenance](illustrated_method_provenance.json).
+
+- **Video strips:** actual matched source / warp / output samples from
+  `meridian_longtake_l150_nba3_apex_right14_175`. The front card is output index **95**;
+  the partially visible back cards are indices **40** and **150**, representing video rather
+  than a single-image input. Aspect ratios are preserved; the front frames are uncropped.
+- **3D illustration:** a procedural, colored basketball point cloud and camera frustums,
+  explicitly labeled **schematic**. These are not saved VGGT-Omega points, estimated poses,
+  or the measured target path from this take. No reconstruction was run to make the figure.
+- **Data flow:** VGGT-Omega estimates depth and source cameras; source RGB and depth are
+  unprojected into per-frame colored points. User-specified target cameras produce the warp.
+  The time-aligned source video bypasses geometry and joins the warp as the model's other
+  video input. Blue frustums denote estimated source cameras; gold denotes authored cameras.
+
+This depicts the released [`reconstruct`, `unproject`, and `warp`](../../../recam/geometry.py)
+pipeline, not a fused persistent world or direct point-cloud conditioning of the video model.
+The model consumes **two videos**, not the plotted points or camera icons. As in the compact
+earlier figures, noise, VAE/token packing, and the discarded audio branch are omitted.
+
+The front samples map to prepared-input frame **70**, original movie frame **85**, PTS
+**2.836167 s**. The other frame mappings and file hashes are in the provenance JSON.
+NBA source-use clearance remains pending; no public promotional permission or endorsement
+is implied. The Spring figure's CC BY license does not apply to the NBA samples.
+
+Rebuild from the repository root:
+
+```bash
+/home/chenyun/miniforge3/envs/wan_new/bin/python docs/assets/research/build_illustrated_method.py
+```
+
+This reads retained videos and writes only this illustration's SVG, PNG and provenance.
+It uses CPU decoding and vector rasterization; no Studio requests, model runs, production
+video edits, or generative image replacements. Earlier figures are retained below.
+
+## NBA method figures
+
+The previous two-figure version is retained for reference:
+
+1. **Camera poses and warp:** [editable SVG](meridian_poses.svg) · [PNG](meridian_poses.png).
+   VGGT-Omega estimates source poses and depth; colored points are reprojected with manually
+   specified target-camera poses. This is a schematic, not a measured camera-path plot.
+2. **Video + warp → output:** [editable SVG](meridian_nba_generation.svg) ·
+   [PNG](meridian_nba_generation.png). The three NBA panels are actual decoded frames from one take,
+   with no generated replacements, retouching, or cropping.
+
+[Frame provenance and media hashes](nba_method_provenance.json) ·
+[Source, warp, output, and recorded controls](../../../videos-all/longtake_edit/review.html?take=nba_apex14_lora)
+
+All three panels use output index **95** (zero-based) of
+`meridian_longtake_l150_nba3_apex_right14_175`. This is inside the requested hold: prepared-input
+frame **70**, original movie frame **85**, original PTS **2.836167 s**. The source panel comes from the
+take's time-aligned `source.mp4`, not frame 95 of the original movie. The output uses Full200 / LoRA150 /
+CLI4 / shift3 / seed1234. This single-frame illustration does not certify exact pose locking or
+continuous-motion quality.
+
+**NBA footage was supplied for local research. Public promotional permission and endorsement are
+not established. The Spring figure's CC BY license below does not apply to the NBA panels.**
+
+The SVGs are the editable sources. PNGs are direct rasterizations. For either figure, run from the
+repository root, replacing `meridian_poses` with `meridian_nba_generation` for the second figure:
+
+```bash
+ffmpeg -v error -threads 2 -i docs/assets/research/meridian_poses.svg \
+  -frames:v 1 -threads 2 -y docs/assets/research/meridian_poses.png
+```
+
+## Architecture overview
+
+[Editable, full-size SVG](meridian_architecture.svg) · [PNG](meridian_architecture.png) ·
+[Frame provenance](method_provenance.json)
+
+The previous single-diagram version separates **estimated source geometry**, **user-authored target
+cameras and time**, and **the two video-model inputs**. Its data flow was checked against the released
+code:
+
+| Diagram element | Implementation |
+|---|---|
+| VGGT-Omega depth and source-camera estimates; unprojection with source RGB | [`reconstruct`, `unproject`, `warp`](../../../recam/geometry.py) |
+| Camera position, look-at point, focal scale, and integer source-frame map | [`plan_path`](../../../recam/path.py) |
+| The same frame map selects both source images and geometry; the target camera projects the points | [`geo`](../../../service/app.py) |
+| Two VAE-encoded video references, packed as tokens; target denoising and decoding | [`pack`, `denoise`, `decode_video`](../../../recam/h3.py), [`do_render`](../../../service/app.py) |
+
+Target-camera control is explicit, but does not guarantee pixel-perfect generated frames. Studio
+orientation is derived from position and look-at with zero roll; focal scale multiplies the estimated
+source focal lengths, rather than specifying an arbitrary intrinsic matrix. Time selection repeats
+or skips supplied frames, without interpolating new motion. The diagram omits target noise, reference
+noise augmentation, and the discarded audio branch; the [technical method](../../method.md) covers
+those details.
+
+The three photographic panels reuse the **same embedded JPEGs, unchanged**, from the original figure
+below. The frame indices, source attribution, transformations, and provenance below apply to both
+figures. The schematic video-strip icon is not a data sample. The SVG is the editable source; its PNG
+is a direct rasterization, not an AI-generated or retouched image.
+
+To refresh the PNG after editing the SVG, run from the repository root:
+
+```bash
+ffmpeg -v error -threads 2 -i docs/assets/research/meridian_architecture.svg \
+  -frames:v 1 -threads 2 -y docs/assets/research/meridian_architecture.png
+```
+
+## Two controls, two references, one new shot
+
+[Full-size SVG](meridian_method.svg) · [PNG](meridian_method.png) ·
+[Machine-readable provenance](method_provenance.json)
+
+The upper diagram follows the released inference implementation, not a proposed architecture:
+
+- `recam/geometry.py`: joint source reconstruction, filtered per-frame colored points, z-buffered
+  projection and grey uncovered pixels. No fused persistent 4D scene or geometric inpainting.
+- `recam/path.py`: source-frame selection `s(t)` and target camera `C(t)`.
+- `recam/h3.py` and `service/app.py`: both video references are VAE encoded and packed as reference
+  tokens; the model denoises the target, then the VAE decodes it. Coverage is diagnostic, not a
+  separate transformer mask input. The diagram omits target noise and the discarded audio branch;
+  see the [technical method](../../method.md#4-condition-the-video-transformer) for the full layout.
+
+The lower panels are **actual decoded source, geometric-reference and generated frames** from
+`meridian_grand_l150_flowers_forward70_baseaim243`, all at output index **121** (zero-based).
+This maps to prepared-input frame 121 and original movie frame 9057 / PTS 377.382 s.
+The geometric panel is taken from the saved conditioning-resolution preview, not a cleaned-up
+render. Aspect ratios are preserved; small black margins are layout padding. This is a single-frame
+illustration, not evidence of continuous motion quality or recovered ground truth.
+
+The source/output exports are 1920 × 800; the geometric export is 960 × 416. These are this take's
+production settings, not the default quickstart buckets. The generated frame uses Full200 + LoRA150,
+CLI `--steps 4 --flow-shift 3 --seed 1234`; it is not a teacher-30 result.
+
+### Attribution and transformations
+
+*Spring* (2019), © Blender Foundation | [project](https://cloud.blender.org/spring).
+Retained source: [Spring — Blender Open Movie](https://commons.wikimedia.org/wiki/File:Spring_-_Blender_Open_Movie.webm),
+identified as [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) in the retained source records.
+
+The input was slowed by repeating source frames before inference. The geometry projection and
+generated view are transformations of that material. Figure preparation extracts one matched
+frame, downsamples source/output thumbnails, JPEG-encodes the panels and fits them without cropping.
+No generative image editing, enhancement, surface repair or color treatment is used for the figure.
+Retain the attribution and transformation notice when reusing the visual.
+
+[Original input preparation and exact map](../../../videos-all/longtake_edit/plates/flowers_linger243.json)
+· [Recorded recipe and raw audit](../../../videos-all/longtake_edit/review/meridian_grand_l150_flowers_forward70_baseaim243/audit.json)
+· [Source, projection and output in motion](../../../videos-all/longtake_edit/grand.html?take=flowers_forward70_baseaim)
+
+### Rebuild
+
+From the repository root, with FFmpeg's `librsvg` decoder available:
+
+```bash
+/home/chenyun/miniforge3/envs/wan_new/bin/python docs/assets/research/build_method_figure.py
+```
+
+This reads the retained MP4s and writes only the SVG, PNG and provenance beside this file.
+It uses CPU decoding and SVG rasterization; it does not invoke the model,
+contact the Studio service, or change production videos.

docs/assets/research/illustrated_method_provenance.json

@@ -0,0 +1,101 @@
+{
+  "take": "videos-all/meridian_longtake_l150_nba3_apex_right14_175",
+  "media": {
+    "source": {
+      "path": "videos-all/meridian_longtake_l150_nba3_apex_right14_175/source.mp4",
+      "sha256": "642f992fdc516c57fbaeabd9c4a6aa773c76fb9f1fd342412e20baa27b3dbb46",
+      "samples": [
+        {
+          "frame": 40,
+          "jpeg_sha256": "993b86a03df949e23a31b6ba4b64c0fd896516851d633cf279b9dad8faf4c19c"
+        },
+        {
+          "frame": 95,
+          "jpeg_sha256": "638ad3ceee19eaf238979fa5deb302394c3e750cba67d989405d303f80afd522"
+        },
+        {
+          "frame": 150,
+          "jpeg_sha256": "dd976c5db5a7861dbbdf174a79e3a233e98ef67bebf4e156203a2f749049720d"
+        }
+      ]
+    },
+    "render": {
+      "path": "videos-all/meridian_longtake_l150_nba3_apex_right14_175/render.mp4",
+      "sha256": "e4f130524c2e09351203ca6dd410b3505031e72cdb4411e3d231787dba62bd23",
+      "samples": [
+        {
+          "frame": 40,
+          "jpeg_sha256": "b83be569064e26cefdf9bba2c5c89e3e63cd0c35beca4eeb57a8bda181406d2d"
+        },
+        {
+          "frame": 95,
+          "jpeg_sha256": "36347035ab0051f8a93fd1f1bb2bd31420de3a5be21b942a76f78e3742ce4171"
+        },
+        {
+          "frame": 150,
+          "jpeg_sha256": "1383ab0dd947894b3c05986e3f5b7b901061eca752f263e6e69aa8d4b4dff730"
+        }
+      ]
+    },
+    "out": {
+      "path": "videos-all/meridian_longtake_l150_nba3_apex_right14_175/out.mp4",
+      "sha256": "49d33d29dca587f252dc43171e6b98513348770332ca44a8eb3a8b46b4300fb0",
+      "samples": [
+        {
+          "frame": 40,
+          "jpeg_sha256": "8ab722c84d3f21c5984cc9f294de6a208d2fd02dfcba71851660ed125b239792"
+        },
+        {
+          "frame": 95,
+          "jpeg_sha256": "dbd0138d1f7e03a002aefcceed8e3faededaade3319bc6940b0d0fb0f13876cd"
+        },
+        {
+          "frame": 150,
+          "jpeg_sha256": "7c6ed5f9f3b2003665d4e0322c0c4fa3ab9a79edcbd627eae4879a1e222d83b3"
+        }
+      ]
+    }
+  },
+  "front_frame": 95,
+  "back_frames": [
+    40,
+    150
+  ],
+  "matched_frames": [
+    {
+      "output_frame": 40,
+      "input_frame": 40,
+      "original_frame": 48,
+      "original_seconds": 1.6016,
+      "held": false
+    },
+    {
+      "output_frame": 95,
+      "input_frame": 70,
+      "original_frame": 85,
+      "original_seconds": 2.8361666666666667,
+      "held": true
+    },
+    {
+      "output_frame": 150,
+      "input_frame": 99,
+      "original_frame": 120,
+      "original_seconds": 4.004,
+      "held": false
+    }
+  ],
+  "video_display": "Actual decoded frames, JPEG downsampling, fit-only; overlapping cards expose parts of back frames. The front frame is uncropped. No generative replacement, retouching or repair.",
+  "geometry_display": "Procedural illustrative point cloud, camera frustums, and path; not actual VGGT-Omega output or recorded camera poses. Fixed seed 17. No reconstruction or service call.",
+  "implementation": [
+    "recam/geometry.py: reconstruct, unproject, warp",
+    "recam/path.py: plan_path",
+    "service/app.py: geo, do_render",
+    "recam/h3.py: pack, denoise, decode_video"
+  ],
+  "scope": "Architecture illustration, not measured reconstruction quality or a globally consistent world. Source time selects supplied moments. Model completion is generated, not recovered.",
+  "credit": "User-supplied NBA footage for local research. Public promotional permission and endorsement are not established.",
+  "source_map": {
+    "path": "videos-all/longtake_edit/nba_study_data.json",
+    "sha256": "d596edd2904fc3c7d1b5d5a0248ea9da05db1a43feafb5b0224acbc8f7f2d27f"
+  }
+}

docs/assets/research/method_provenance.json

@@ -0,0 +1,29 @@
+{
+  "take": "videos-all/meridian_grand_l150_flowers_forward70_baseaim243",
+  "output_frame_zero_based": 121,
+  "prepared_input_frame": 121,
+  "original_movie_frame": 9057,
+  "original_movie_pts_seconds": 377.382,
+  "media": {
+    "source": {
+      "path": "videos-all/meridian_grand_l150_flowers_forward70_baseaim243/source.mp4",
+      "sha256": "0270cc8f8ce6e1ed3c0ceb9d6b5000c4ccaddda03f4f220359d32c2def7f3e2e"
+    },
+    "render": {
+      "path": "videos-all/meridian_grand_l150_flowers_forward70_baseaim243/render.mp4",
+      "sha256": "d1b1ad58b9c661cc780e43ceb4ca19b7f41640566d9fc36ab093e1fab7157c25"
+    },
+    "out": {
+      "path": "videos-all/meridian_grand_l150_flowers_forward70_baseaim243/out.mp4",
+      "sha256": "35d85aeda901c7c12e95de6ad2d33ad0946745282e2c2313d5dd21e5bd746961"
+    }
+  },
+  "display": "Exact decoded frame selection; JPEG encoding and fit-only thumbnail downsampling. No crop, repair or generated replacement images.",
+  "source_url": "https://commons.wikimedia.org/wiki/File:Spring_-_Blender_Open_Movie.webm",
+  "credit": "Spring (2019) \u00a9 Blender Foundation | cloud.blender.org/spring",
+  "license": "CC BY 4.0",
+  "license_url": "https://creativecommons.org/licenses/by/4.0/",
+  "source_time_scope": "Published animated-film timeline, not physical capture time.",
+  "recipe": "Full200 / LoRA150 / CLI4 / flow shift3 / seed1234; production output1920x800, conditioning960x416.",
+  "scope": "An explanatory diagram and a single matched frame, not a quality benchmark or a continuous-motion review."
+}

docs/assets/research/nba_method_provenance.json

@@ -0,0 +1,41 @@
+{
+  "take": "meridian_longtake_l150_nba3_apex_right14_175",
+  "study_key": "nba_apex14_lora",
+  "output_frame_zero_based": 95,
+  "output_pts_seconds": 3.9583333333333335,
+  "prepared_input_frame": 70,
+  "original_movie_frame": 85,
+  "original_movie_pts_seconds": 2.8361666666666667,
+  "source_time_held": true,
+  "media": {
+    "source": {
+      "path": "videos-all/meridian_longtake_l150_nba3_apex_right14_175/source.mp4",
+      "sha256": "642f992fdc516c57fbaeabd9c4a6aa773c76fb9f1fd342412e20baa27b3dbb46",
+      "width": 1920,
+      "height": 1088,
+      "thumbnail_sha256": "1395f7e2ed780b6fbaaa060ac3ff7ff4b46f6765437d694757d53bb44daf4204"
+    },
+    "render": {
+      "path": "videos-all/meridian_longtake_l150_nba3_apex_right14_175/render.mp4",
+      "sha256": "e4f130524c2e09351203ca6dd410b3505031e72cdb4411e3d231787dba62bd23",
+      "width": 832,
+      "height": 480,
+      "thumbnail_sha256": "ba196eb57c5c7e5c0ae9c9ca8734c5a3c8c74bf9f986d21a59a285e898be155c"
+    },
+    "out": {
+      "path": "videos-all/meridian_longtake_l150_nba3_apex_right14_175/out.mp4",
+      "sha256": "49d33d29dca587f252dc43171e6b98513348770332ca44a8eb3a8b46b4300fb0",
+      "width": 1920,
+      "height": 1088,
+      "thumbnail_sha256": "4008729e25915ce072ab733d13a806dd85623d2f9a7537cf1f2ee82267ce56b8"
+    }
+  },
+  "source_time_map": "videos-all/longtake_edit/nba_study_data.json",
+  "audit": "videos-all/longtake_edit/review/meridian_longtake_l150_nba3_apex_right14_175/audit.json",
+  "recipe": "Full200 / LoRA150 / CLI4 / shift3 / seed 1234",
+  "credit": "NBA footage supplied for local research; public promotional permission and endorsement are not established.",
+  "license": "No public-use license established; the Spring figure CC BY license does not apply.",
+  "display": "All panels select decoded output frame 95 from the same take. FFmpeg scale=960:-2 and JPEG quality 2; aspect-ratio-preserving fit in SVG. No cropping, repair, image generation, or retouching.",
+  "extraction_filter": "select='eq(n,95)',scale=960:-2",
+  "scope": "Single matched-frame architecture example, not a continuous-motion review, exact pose-locking benchmark, or public-use clearance."
+}

docs/inference.md

@@ -0,0 +1,296 @@
+# Inference: camera and time
+
+[← Meridian](../README.md) · [Installation](installation.md) · [Method](../README.md#method) · [Studio demo](../README.md#self-hosting-the-demo)
+
+Run the examples from the release directory after completing installation. The CLI selects one GPU
+through `CUDA_VISIBLE_DEVICES`; it does not split a take across cards.
+
+```bash
+CUDA_VISIBLE_DEVICES=0 python inference/sample.py \
+  --video examples/media/sp_bouldering_hang.mp4 \
+  --yaw 15 --sweep --out out/orbit
+```
+
+The default is a 73-frame, 24 fps take using the distilled student: `--steps 4 --flow-shift 3`.
+Use a fresh `--out` directory for each take; filenames are fixed rather than automatically versioned.
+
+## Prepare the input
+
+Use a single continuous shot. The **CLI does not normalize frame rate or detect cuts**: it reads
+decoded frames by index and always writes at 24 fps. A 30 fps or variable-frame-rate input can
+therefore change pace and lose audio alignment unless you normalize it first.
+
+```bash
+# Preserve playback duration while exporting a constant 24 fps input.
+ffmpeg -i clip.mp4 -vf "setpts=PTS-STARTPTS,fps=24" \
+  -c:v libx264 -crf 18 -pix_fmt yuv420p -c:a aac clip_24fps.mp4
+
+# Inspect the actual decoded frame count, not only the container's FPS label.
+ffprobe -v error -select_streams v:0 -count_frames \
+  -show_entries stream=width,height,r_frame_rate,nb_read_frames \
+  -of default=noprint_wrappers=1 clip_24fps.mp4
+```
+
+For a normal take, the input must contain at least `start + frames` decoded frames. The two included
+sample clips each contain exactly **73 frames at 24 fps** and no audio. A longer take needs a longer
+input or an explicit hold; simply increasing `--frames` on those samples will not extend the action.
+
+## Camera recipes
+
+The following commands all work with the included 73-frame sample as an input, subject to the
+hardware and model setup. Motion quality still depends on reconstruction and viewpoint coverage.
+
+### Orbit with a gentle start and stop
+
+```bash
+python inference/sample.py --video examples/media/sp_bouldering_hang.mp4 \
+  --yaw 15 --sweep --ease --out out/eased_orbit
+```
+
+Positive yaw moves the camera **left** around the pivot. Without `--sweep`, the offset is applied
+throughout the clip instead of ramping from the original view. It remains an offset from each source
+camera, not necessarily a camera fixed in world space.
+
+### Push in without changing the lens
+
+```bash
+python inference/sample.py --video examples/media/sp_bouldering_hang.mp4 \
+  --dolly 0.8 --zoom 1 --sweep --ease --out out/push_in
+```
+
+**`--dolly` alone performs a dolly zoom:** it changes both the camera radius and focal length to
+approximately preserve the pivot plane's size. Add `--zoom 1` for a fixed-lens push-in, where the
+subject grows in frame. `--zoom 1.5` without translation is an optical zoom; these pure-zoom takes
+can be ignored by the model. Prefer moves with parallax.
+
+### Slide or crane while keeping the subject framed
+
+```bash
+# Move right by 0.15 pivot-depth units and aim back toward the pivot.
+python inference/sample.py --video examples/media/sp_bouldering_hang.mp4 \
+  --truck 0.15 --aim --sweep --ease --out out/slide
+
+# Raise the camera by 0.15 pivot-depth units.
+python inference/sample.py --video examples/media/sp_bouldering_hang.mp4 \
+  --boom 0.15 --aim --sweep --ease --out out/crane
+```
+
+### Choose the orbit center
+
+```bash
+python inference/sample.py --video examples/media/sp_bouldering_hang.mp4 \
+  --pivot 0.5,0.5 --pivot-lock --yaw 15 --sweep --out out/pivot_orbit
+```
+
+`--pivot fx,fy` uses fractions of the **center-cropped picture**, not the full letterbox or original
+uncropped image. Choose a point on the subject, away from image boundaries, sky, and missing depth.
+The example selects the crop center; adjust it for your footage. `--pivot` sets the depth scale;
+`--pivot-lock` additionally moves the orbit center to the picked 3D point.
+
+**Choose the point in the frame used for pivot depth.** Without `--freeze`, this is
+the first selected source frame (`--start`). With `--freeze F:N`, it is frame `F`.
+An athlete-centered point at the held apex can land on the distant audience in the
+approach frame: do not reuse it unchanged when removing the hold. The depth is a
+median over a neighborhood extending roughly 5% of the picture in each direction,
+so check that neighborhood as well as the exact pixel. `--pivot-lock` is not dynamic
+subject tracking; inspect the projected reference throughout the shot before
+treating the requested trajectory as a successful composition.
+
+## Timing
+
+All CLI source indices are **zero-based absolute frame indices** in the supplied file.
+
+### Select a passage
+
+```bash
+# On an input with at least 121 frames, use source frames 48 through 120 inclusive.
+python inference/sample.py --video clip_24fps.mp4 \
+  --start 48 --frames 73 --yaw 15 --sweep --out out/later_moment
+```
+
+`--start 48` is two seconds into a 24 fps input. It is not a seek time in seconds.
+
+### Hold a moment while moving the camera
+
+```bash
+# 24 live frames, then source frame 24 repeated for 49 output frames; no tail.
+python inference/sample.py --video examples/media/sp_bouldering_reach.mp4 \
+  --yaw 35 --freeze 24:49 --out out/bullet
+
+# Hold one instant for the entire take; the camera still sweeps through 20 degrees.
+python inference/sample.py --video examples/media/sp_bouldering_reach.mp4 \
+  --yaw 20 --freeze 24:73 --start 24 --out out/held_moment
+```
+
+For `--freeze F:N`, the output consists of:
+
+1. Source frames `start` through `F - 1`, once each.
+2. Source frame `F`, repeated `N` times.
+3. Source frames after `F`, once each, until the requested output length is reached.
+
+The tail length is `frames - N - (F - start)`. Use a positive `N`, `F >= start`, and a non-negative
+tail. The source must reach frame `F + tail`. With a hold, fewer distinct source frames can produce
+a longer output, but the repeated interval contains no new event motion.
+
+By default, the camera ramp progresses only during the held interval. Add `--sweep` to move during
+the live lead-in and tail too; `--live-speed` sets their ramp speed relative to the held interval
+(default `0.33`). It controls the **camera ramp**, not playback speed.
+
+The CLI can also decode a still image, for example
+`--video still.png --freeze 0:73 --yaw 15`. This is a camera move over a held image, not animation of
+the subject. The studio's video upload workflow does not offer this short-input path.
+
+### Slow motion and speed-ups
+
+**Set the event's pace first, then author the camera.** Export the retimed source at a constant
+24 fps and use that export as the input to either the CLI or the studio.
+
+```bash
+# 0.5x: twice the duration.
+ffmpeg -i clip.mp4 -vf "setpts=2*(PTS-STARTPTS),fps=24" -an clip_slow.mp4
+
+# 2x: half the duration.
+ffmpeg -i clip.mp4 -vf "setpts=0.5*(PTS-STARTPTS),fps=24" -an clip_fast.mp4
+
+python inference/sample.py --video clip_slow.mp4 \
+  --yaw 15 --sweep --out out/slow_orbit
+
+python inference/sample.py --video clip_fast.mp4 \
+  --yaw 15 --sweep --out out/fast_orbit
+```
+
+Changing playback metadata alone is not enough for the CLI: timing must be baked into the **decoded
+frame sequence**. `fps=24` duplicates or drops frames; it does not interpolate new motion. Slow-motion
+smoothness depends on the source frame rate and any interpolation applied before inference.
+
+Check the retimed file's frame count before rendering. In particular, acceleration shortens the input:
+the included 73-frame samples become too short for an ordinary 73-frame take at 2x. Use longer footage
+or explicitly hold a moment. The commands above omit audio; retime a soundtrack separately if needed.
+
+In the studio, one source frame per output frame preserves the export's retimed pace. Stretching keys
+across the unchanged source is a different workflow: it duplicates or skips reconstructed frames and
+can trigger a speed warning.
+
+## Output lengths and resolution
+
+| `--frames` | Duration at 24 fps |
+|---|---|
+| 73 | 3.04 s |
+| 90 | 3.75 s |
+| 107 | 4.46 s |
+| 124 | 5.17 s |
+| 141 | 5.88 s |
+| 158 | 6.58 s |
+| 175 | 7.29 s |
+| 243 | 10.13 s |
+
+These are the lengths with shipped text and audio-layout assets. Other values are not accepted by
+the CLI. This is a per-take limit, not a limit on the total duration of the input file.
+
+Output uses an aspect-matched 768-class bucket, usually about 1.03 million pixels; 16:9 maps to
+1344 × 768. Both references use the smaller 480-class bucket: 832 × 480 for a 16:9 input.
+
+## Output files
+
+| File in `--out` | Contents |
+|---|---|
+| `out.mp4` | Generated take, 24 fps, no generated audio. |
+| `render.mp4` | Geometry reference at conditioning resolution, including grey holes. |
+| `source.mp4` | Source images after the selected frame mapping and output crop. A hold is visible here too. |
+| `grid.mp4` | Source, geometry reference, and generated take side by side. |
+| `out_audio.mp4` | For non-freeze commands: source-window audio muxed onto the take, when the input has audio. A silent input remains silent. |
+| `last.png` | Final generated frame. Reusing it is possible, but does not guarantee cross-take consistency. |
+| `cams.npz` | Source/target camera matrices, intrinsics, pivot metadata, crop, canvas, FPS, and command arguments. |
+
+`cams.npz` stores `c2w_src` and `c2w_dst` as camera-to-world matrices; `intr_src` and `intr_dst` are
+in the 512-space geometry grid. The `*_px` arrays are exported for the output canvas. Translation
+units are reconstruction-relative, not meters. The archive is diagnostic metadata, not a scene model.
+
+For reproducibility, retain the input export, command, seed, checkpoint revisions, and environment.
+Do not assume the CLI and studio, or different dependency/backend versions, produce bit-identical
+results from the same seed.
+
+## CLI reference
+
+Run `python inference/sample.py --help` for the parser's complete help. The tables below group the
+options by purpose; boolean flags are off unless stated otherwise.
+
+### Input and model
+
+| Option | Default | Meaning |
+|---|---|---|
+| `--video` | Required | Input video or decodable still image. |
+| `--out` | Required | Output directory. |
+| `--start` | `0` | First source-frame index. |
+| `--frames` | `73` | Supported output length from the table above. |
+| `--seed` | `1234` | Random seed. |
+| `--ckpt` | `<release>/transformer` | Finetuned teacher directory. |
+| `--lora` | `<release>/lora` | Student adapter directory. |
+| `--no-lora` | Off | Disable the adapter; pair with the teacher sampling settings. |
+| `--steps` | `4` | Scheduler grid points, including the terminal point. |
+| `--flow-shift` | `3` | Video schedule shift; use `12` for the teacher. |
+| `--model-dir` | `MiniMaxAI/MiniMax-H3` | Hub repo or local directory containing `vae/`. |
+| `--vggt-repo`, `--vggt` | Environment-based | VGGT-Omega source checkout and checkpoint; see [Installation](installation.md#2-obtain-vggt-omega-separately). |
+| `--attn-backend` | `_native_cudnn` | Diffusers attention backend. Alternatives are hardware- and version-dependent. |
+
+To use the teacher:
+
+```bash
+python inference/sample.py --video examples/media/sp_bouldering_hang.mp4 \
+  --yaw 15 --sweep --no-lora --steps 50 --flow-shift 12 --out out/teacher
+```
+
+### Camera and motion
+
+| Option | Default | Meaning |
+|---|---|---|
+| `--yaw` | `0` | Orbit angle in degrees; positive moves left. |
+| `--yaw-from` | `0` | Initial yaw when ramping; the live lead-in holds this value unless also swept. |
+| `--truck` | `0` | Sideways shift in pivot-depth units; positive moves right. |
+| `--boom` | `0` | Vertical shift in pivot-depth units; positive raises the camera. |
+| `--dolly` | `1` | Orbit-radius scale; below one moves closer and, by default, widens the lens. |
+| `--zoom` | `0` | Zero means automatic dolly-linked focal scaling; a positive value specifies the final focal multiplier. |
+| `--pivot` | Unset | `fx,fy` in the crop; selects the depth-scale neighborhood. |
+| `--pivot-lock` | Off | With `--pivot`, orbit about the selected 3D point. |
+| `--aim` | Off | Reorient toward the pivot after translation. |
+| `--pivot-to` | Unset | With `--aim`, a second `fx,fy` point toward which the aim transitions. |
+| `--sweep` | Off | Ramp from the initial to the final offset over the take. |
+| `--ease` | Off | Cosine ease-in/out applied to the ramp; it does not create a ramp by itself. |
+| `--bounce` | Off | There-and-back ramp, `0 → 1 → 0`; implies a ramp even without `--sweep`. |
+| `--swing` | Off | Sine ramp, `0 → 1 → 0 → −1 → 0`; implies a ramp. |
+| `--freeze` | Unset | `F:N`: hold source frame `F` for `N` output frames. |
+| `--live-speed` | `0.33` | With `--freeze --sweep`, relative camera-ramp speed outside the hold. |
+
+Use one basic ramp shape at a time. Combining `--ease`, `--bounce`, and `--swing` composes their
+functions in code order; it does not select between independent motion presets.
+
+### Advanced and diagnostic controls
+
+| Option | Default | Meaning and caveat |
+|---|---|---|
+| `--gauge-only` | Off | Reconstruct, warp, print geometry gauges, then stop before loading H3. No normal output artifacts are written. |
+| `--follow` | Off | Replay estimated source cameras over the **first selected frame's fixed geometry and RGB**. Ignores the authored yaw/translation/lens controls; it does not retain the event's live motion. |
+| `--smooth` | `8` | With `--follow`, Gaussian smoothing sigma in frames for estimated camera poses and intrinsics. `0` disables smoothing. |
+| `--cull` | Off | Reject surfaces seen from behind according to estimated depth-map normals. This removes misleading splats; it does not reveal hidden surfaces. |
+| `--fast-back` | `1` | Above one, compress the middle half of the camera ramp. Does not improve the reconstruction of an unseen back view. |
+| `--canvas` | Automatic | Explicit `WxH`, with dimensions divisible by 32; advanced override outside the reported default benchmarks. |
+| `--full` | `0` → 1280 | Override the square letterbox side. Higher values increase point-cloud sampling and memory, not VGGT's 512-pixel input resolution. |
+
+The CLI prints `ahead`, coverage, and other geometry diagnostics but **does not reject a take using
+the studio's clearance/motion thresholds**. Inspect the diagnostics and `render.mp4`; do not treat a
+successful process exit as a quality check.
+
+## Improving a take
+
+1. **Inspect the geometry reference first.** A bent subject or unstable depth in `render.mp4` usually
+   needs a better source shot or a smaller move, not more denoising steps.
+2. **Use modest viewpoint changes.** Large orbits reveal surfaces absent from the source. A plausible
+   completion can still be wrong; roughly 40° is a reported caution point, not a universal threshold.
+3. **Check the depth scale.** If a small numerical move sends the camera through the scene, pick a
+   pivot on the subject and reduce the translation.
+4. **Add parallax to lens changes.** Use a small dolly rather than relying on a pure optical zoom.
+5. **Check timing before inference.** Stuttering from repeated input frames is not a geometry failure;
+   use higher-frame-rate footage or an interpolated export when smooth slow motion matters.
+6. **Do not cross cuts.** Split the input into continuous shots yourself when using the CLI.
+
+For dependency and memory errors, see [Setup problems](installation.md#setup-problems).

docs/installation.md

@@ -0,0 +1,189 @@
+# Installation
+
+[← Meridian](../README.md) · [Inference](inference.md) · [Studio demo](../README.md#self-hosting-the-demo)
+
+## Before downloading
+
+- **Review the [licenses and intended use](../README.md#license).** The weights are not Apache 2.0,
+  the MiniMax-H3 license has territorial restrictions, and the VGGT-Omega dependency is licensed
+  separately for noncommercial research.
+- **Use a CUDA GPU with substantial memory.** The released scripts run on one GPU and do not expose
+  CPU inference, multi-GPU sharding, quantization, or CPU-offload options. The reported resident-service
+  peak is approximately 88 GiB for 73 frames. The CLI logs approximately 82 GiB of peak PyTorch-allocated
+  memory during denoising; this does not measure the whole-process peak or driver-level GPU usage.
+  A 96 GB-class GPU is the reported configuration for takes up to 124 frames; 243-frame takes reach
+  approximately 113 GiB in the service.
+  Leave headroom for geometry caches, other processes, and differences between GB and GiB.
+- **Allow disk space beyond the weights.** The teacher and adapter total approximately 64 GiB;
+  the H3 VAE, VGGT-Omega checkpoint, package caches, uploads, and generated videos are additional.
+- **Reference environment:** Python 3.12, CUDA 12.8, PyTorch 2.9.1, and torchvision 0.24.1.
+  B200 is the reported benchmark GPU, not a claim that every CUDA GPU is validated.
+- Have **Git**, **FFmpeg**, and **FFprobe** on `PATH`. Git is needed for the pinned Diffusers install;
+  the Python packages do not install the FFmpeg command-line executable.
+
+## 1. Create an environment and download the code
+
+Run these commands in a shell with Python 3.12 available. `python` below always means the Python in
+the activated environment. Sign in if repository access requires it. The command fetches code,
+runtime assets, guides, and sample clips, not the optional showcase videos or model weights.
+
+```bash
+python3.12 -m venv .venv-meridian
+source .venv-meridian/bin/activate
+python -m pip install --upgrade pip
+python -m pip install huggingface_hub
+
+hf auth login
+hf download Viggle/Meridian --local-dir Meridian \
+  --include "README.md" "LICENSE*" "NOTICE" "MODIFICATIONS.md" "requirements.txt" \
+  "recam/*" "inference/*" "service/*" "assets/*" "examples/*" \
+  "docs/installation.md" "docs/inference.md"
+cd Meridian
+python -m pip install -r requirements.txt
+python -m pip install peft==0.18.0
+
+# These must work before loading any model weights or starting the GPU service.
+python inference/sample.py --help
+python service/app.py --help
+```
+
+The PEFT package is needed by the student adapter loader and is not currently listed in
+`requirements.txt`; install it explicitly. Use a dedicated environment rather than upgrading a
+shared inference environment in place.
+
+Keep the Diffusers commit pinned by `requirements.txt` (`d6726f3`). The scripts use MiniMax-H3 classes
+and modular-pipeline helpers that may not exist in another build, even if its version string includes
+`dev`. Do not replace that dependency with an arbitrary PyPI release.
+
+### Supply the teacher and LoRA weights
+
+**Checkpoint availability:** `transformer/` and `lora/` are not hosted in this repository yet;
+a verified download source is pending. Supply the checkpoints separately using the layout below.
+Without them, the help checks can pass, but generation and Studio startup cannot run.
+
+If you already have the Meridian checkpoints, place the complete Diffusers transformer directory
+(including its configuration, weight shards, and any index file) and the student adapter alongside
+the code:
+
+```text
+Meridian/
+  inference/sample.py
+  assets/
+  transformer/
+    config.json
+    ... checkpoint files ...
+  lora/
+    pytorch_lora_weights.safetensors
+```
+
+Alternatively, add `--ckpt /absolute/path/to/transformer --lora /absolute/path/to/lora` to the CLI
+or Studio command. Use Meridian's finetuned teacher, not the unmodified MiniMax-H3 transformer.
+
+## 2. Obtain VGGT-Omega separately
+
+VGGT-Omega code and weights are **not redistributed here**. Request access to
+[facebook/VGGT-Omega](https://huggingface.co/facebook/VGGT-Omega), read its license, and authenticate
+with a Hugging Face account that has been granted access.
+
+```bash
+# Run from the Meridian release directory; the checkout is placed beside it.
+git clone https://github.com/facebookresearch/vggt-omega ../vggt-omega
+export VGGT_OMEGA_DIR="$(cd ../vggt-omega && pwd)"
+
+hf auth login
+hf download facebook/VGGT-Omega vggt_omega_1b_512.pt \
+  --local-dir "$VGGT_OMEGA_DIR/checkpoints"
+```
+
+Follow the VGGT-Omega checkout's own dependency instructions if additional packages are needed.
+Its source directory is imported directly; this release does not install it as a Python package.
+
+By default, Meridian looks for
+`$VGGT_OMEGA_DIR/checkpoints/vggt_omega_1b_512.pt`. If you already store the weight file elsewhere:
+
+```bash
+export VGGT_OMEGA_CKPT=/absolute/path/to/vggt_omega_1b_512.pt
+```
+
+Keep these exports in the shell that starts inference. The CLI and service also accept
+`--vggt-repo /absolute/path/to/vggt-omega` and `--vggt /absolute/path/to/the/checkpoint.pt`.
+
+Meta's FAIR Noncommercial Research License v1 restricts commercial use of the research materials
+and their outputs or results. Here those results include the geometry used to make the reference
+render. The Apache license on Meridian's code does not remove that restriction. Commercial use
+requires an appropriately licensed geometry solution or permission from Meta; swapping the
+geometry front end is not a built-in CLI option and requires integration work.
+
+## 3. Provide the MiniMax-H3 VAE
+
+By default, inference loads `vae/` from
+[`MiniMaxAI/MiniMax-H3`](https://huggingface.co/MiniMaxAI/MiniMax-H3). It does **not** need the base
+transformer or the text encoder. To download only the VAE for local use:
+
+```bash
+hf download MiniMaxAI/MiniMax-H3 --include "vae/*" --local-dir ../MiniMax-H3
+```
+
+Then add `--model-dir ../MiniMax-H3` to your CLI or service command. This path is the directory
+**containing** `vae/`, not `vae/` itself. Without the flag, the default Hub identifier is used and
+the VAE is loaded through the Hugging Face cache.
+
+Do not put Meridian's LoRA on the base MiniMax-H3 transformer: it was distilled on Meridian's
+finetuned teacher.
+
+## 4. Check the setup
+
+These checks import the required components without loading their weights or starting inference:
+
+```bash
+ffmpeg -version
+ffprobe -version
+python -m pip check
+python -c "import torch; print('torch:', torch.__version__, 'CUDA:', torch.version.cuda, 'available:', torch.cuda.is_available())"
+python -c "import peft; from diffusers import AutoencoderKLMiniMaxH3, MiniMaxH3Transformer3DModel, MiniMaxH3Scheduler; from recam.h3 import pack; print('H3 and PEFT imports OK')"
+python -c "import os, sys; sys.path.insert(0, os.environ['VGGT_OMEGA_DIR']); from vggt_omega.models import VGGTOmega; print('VGGT-Omega import OK')"
+```
+
+For a geometry-only check on the selected GPU:
+
+```bash
+CUDA_VISIBLE_DEVICES=0 python inference/sample.py \
+  --video examples/media/sp_bouldering_hang.mp4 \
+  --yaw 15 --sweep --gauge-only --out out/check
+```
+
+This loads VGGT-Omega and prints geometry diagnostics. It does not load the VAE or transformer, and
+does not write the normal output videos. It is not a full inference or model-memory test.
+
+Next: run the [first take](../README.md#quickstart), learn the [camera controls](inference.md), or
+start the [Studio demo](../README.md#self-hosting-the-demo).
+
+## Setup problems
+
+| Symptom | Check |
+|---|---|
+| `hf` or `ffmpeg` not found | Activate the environment for `hf`; install the system FFmpeg tools separately and check `PATH`. |
+| Hub access denied | Confirm the account has accepted the model's terms and received access; authenticate with that account. A token alone does not grant gated access. |
+| `No module named vggt_omega` | `VGGT_OMEGA_DIR` must contain the `vggt_omega/` package. Export it in the same shell that starts the process. |
+| `VGGT-Omega not found` | Check both the source checkout and checkpoint path; `VGGT_OMEGA_CKPT` must name the `.pt` file. |
+| Cannot import a MiniMax-H3 class or layout helper | Reinstall the pinned requirements in the active environment; inspect `python -c "import diffusers; print(diffusers.__file__)"` for a conflicting checkout. |
+| Missing PEFT or adapter-loading error | Install PEFT, use the finetuned teacher, and confirm the adapter filename and `--lora` directory. |
+| CUDA or attention-backend failure | Check the PyTorch/CUDA/driver combination against the reference environment. The service selects `_native_cudnn`; other hardware/backend combinations are not validated here. |
+| Out of memory | Start with 73 output frames, a short source span, and no other GPU workload. The scripts do not automatically offload to CPU. The Studio keeps its models and recent geometry caches resident. |
+
+## Lower-memory community work
+
+Meridian retains MiniMax-H3's transformer architecture and uses precomputed text embeddings, so
+inference does not load the text encoder. This is a starting point for adapting community memory-saving
+techniques—not evidence that the remaining transformer, activations, VAE, and geometry fit a smaller GPU.
+
+We welcome work on quantization and CPU offloading toward consumer GPUs such as the RTX 4090.
+Diffusers documents [quantization](https://huggingface.co/docs/diffusers/main/en/quantization/overview)
+and [memory reduction and offloading](https://huggingface.co/docs/diffusers/main/en/optimization/memory).
+These are general integration references, not a tested Meridian recipe or a reason to replace the
+pinned Diffusers build indiscriminately.
+
+The current CLI and service move their models onto one CUDA device; neither exposes those optimizations.
+A contribution needs to integrate them into the custom inference path and validate adapter loading,
+reference conditioning, image quality, peak GPU/host memory, and end-to-end latency. There is no
+verified RTX 4090 configuration or performance claim for this release.

docs/method.md

@@ -0,0 +1,169 @@
+# Method
+
+[← Meridian](../README.md) · [Inference](inference.md) · [Studio](studio.md)
+
+Meridian synthesizes a new observation of an existing event. It separates **which source moment is
+shown** from **which camera observes it**, then uses geometry to make that choice visible to a video
+model. The geometry supplies a spatial constraint; the model supplies the appearance of the completed
+shot, including regions the source camera did not see.
+
+This is geometry-guided video re-camera, not a persistent 4D reconstruction or an action-conditioned
+simulator. A new view is a generated interpretation of the recorded event, not evidence of what an
+unobserved camera would actually have captured.
+
+[![Meridian method overview with actual source, geometric-reference and generated flower frames](assets/research/meridian_method.png)](assets/research/meridian_method.svg)
+
+**Overview.** Source time selects both appearance and geometry; the authored camera makes a
+projected reference. Both references condition the video model. Real example: *Spring* (2019),
+© Blender Foundation, CC BY 4.0; input retimed, view projected and generated.
+[Full figure, attribution and provenance](assets/research/README.md).
+
+## 1. Choose a source timeline
+
+For each output frame `t`, a source-frame map `s(t)` selects the image and geometry to use:
+
+| Timeline | Source-frame selection |
+|---|---|
+| Preserve the input's pace | Advance one source frame per output frame. |
+| Hold a moment | Repeat one source frame while the target camera can keep moving. |
+| Slow motion or accelerated action | Retime the input to a constant 24 fps **before** reconstruction, then advance through that export normally. |
+
+Both video references follow the same selected timeline. Meridian is not asked to invent a different
+action speed from an unchanged reference. See [Timing](inference.md#timing) for frame-index semantics,
+freeze windows, and FFmpeg recipes.
+
+The CLI constructs `s(t)` from `--start`, `--frames`, and optionally `--freeze`. The studio constructs it
+from keyframes: source indices interpolate linearly and are rounded to integers. Studio source keys
+must be non-decreasing; easing affects the camera path, not the source-frame mapping.
+
+## 2. Reconstruct the source span
+
+The input is resized and letterboxed into a 1280 × 1280 square, then downsampled to 512 × 512 for
+VGGT-Omega. **One model call processes the selected source span jointly**, returning per-frame depth,
+confidence, camera extrinsics, and intrinsics. Per-frame outputs do not mean independent single-frame
+inference. Changing the reconstruction span can change estimates for frames shared by both spans.
+
+Before unprojection, the implementation removes:
+
+- Non-finite depth or confidence, and confidence values at or below `1e-5`.
+- Depth discontinuities whose 3 × 3 local range exceeds 30% of the depth magnitude.
+- The lowest-confidence 2% of the remaining candidates in each frame.
+
+Depth and validity are upsampled to the letterboxed input resolution. A pixel is retained only when
+the interpolated validity exceeds `0.999`, limiting points introduced across rejected boundaries.
+Source RGB supplies the point colors. There is no fused mesh, persistent scene optimization, or
+cross-frame point-cloud accumulation in this stage.
+
+### Coordinates and scale
+
+Geometry has a reconstruction-relative scale, not calibrated meters. Camera translations use `zm`,
+a median scene depth. Choosing a distant background as the depth reference makes the same numerical
+move much larger than choosing the subject.
+
+- **CLI:** a camera offset is applied in each selected source camera's local coordinates:
+  `C_target(t) = C_source(s(t)) @ delta(t)`. By default, `zm` comes from valid depths in the first
+  selected frame; for `--freeze`, it comes from the held frame. `--pivot fx,fy` restricts the depth
+  measurement to a neighborhood of a pixel in the **cropped image**. `--pivot-lock` also places the
+  orbit center at the corresponding 3D point.
+- **Studio:** all keys share the coordinate frame of the source camera at `start`: **x right,
+  y down, z forward**. Positions and look-at points are expressed in units of `zm`. The API measures
+  `zm` around a chosen pixel at `pivot_frame`, falling back to valid picture depths when too few
+  local points remain. The current page uses the picture center at `start` as this scale reference;
+  a key's **aims at** control changes its look-at point, not the scale reference.
+
+The CLI's source-relative trajectory and the studio's shared-frame trajectory are different ways of
+authoring a camera. Similar-looking controls need not produce identical paths on a moving-camera clip.
+
+## 3. Render a geometric reference
+
+At each output time, the selected source frame's colored point cloud is projected through the target
+camera and its lens. A z-buffer resolves visibility; each point splats onto a 3 × 3 pixel neighborhood.
+Uncovered pixels are filled with RGB `(128, 128, 128)`.
+
+The current implementation rasterizes at the **output canvas**, then downsamples the result to the
+**480-class conditioning canvas**. There is no geometric inpainting before generation. Coverage is
+computed for diagnostics, but **no coverage mask is fed to the transformer**.
+
+The studio's *what the model sees* preview and the saved `render.mp4` show this downsampled reference.
+They are encoded video previews, not lossless copies of the in-memory conditioning pixels. The
+magenta-hole view is a diagnostic visualization only; the model receives the grey-hole version.
+
+## 4. Condition the video transformer
+
+MiniMax-H3's VAE encodes two references:
+
+1. **`<Video 1>` — source:** the selected source images, at the 480 class.
+2. **`<Video 2>` — geometry:** the rendered target view, at the same conditioning class.
+
+The target is generated at the 768 class. Here “class” means an aspect-ratio bucket, not a fixed
+width or height. For a 16:9 input, the reference canvas is 832 × 480 and the output is 1344 × 768;
+square inputs use 640 × 640 and 1024 × 1024 respectively. The nearest bucket is chosen by log aspect
+ratio, with a centered crop inside the letterbox.
+
+```text
+source span ──► joint VGGT-Omega reconstruction ──► per-frame geometry
+      │                                                   │
+      │                     source-frame map + camera path│
+      │                                                   ▼
+      │                                       z-buffered point splat
+      │                                                   │
+      ▼                                                   ▼
+source reference, 480 class                    view reference, 480 class
+      └────────────────────────┬──────────────────────────┘
+                               ▼
+              VAE → packed reference tokens + fixed text
+                               ▼
+               finetuned H3 + distilled LoRA → VAE decode
+                               ▼
+                     new shot, 768 class, 24 fps
+```
+
+**The references are concatenated as tokens, not added as channels.** `recam/h3.py` uses Diffusers'
+`MiniMaxH3Ref2VAPrepareLayoutStep.build_ref2va_packed_sequence` to create the reference layout,
+position IDs, and modality tags. The transformer architecture is unchanged.
+
+Reference video rows receive the upstream conditioning-noise convention
+`0.999 × latent + 0.001 × noise` and stay fixed during denoising. Target video rows begin as random
+noise. The source is also VAE-encoded at target resolution to establish the target latent shape;
+its values are **not** used to initialize the target rows.
+
+### Fixed text and the audio branch
+
+[`assets/prompt.txt`](../assets/prompt.txt) describes the two-reference editing task: retain the source
+event and complete the geometry reference's grey holes. Its embeddings are precomputed for each
+supported output length, so inference does not load Qwen3-VL. Editing the text file alone does not
+change inference; the shipped embeddings are what the model reads. An embedding-generation script
+is not included in this release.
+
+The packed layout retains H3's audio branch. Cached silence latents supply its shape and length;
+the current code initializes audio rows with noise, denoises them, and discards the result. Meridian
+does not generate or preserve a soundtrack through that branch. The CLI's optional audio file is
+instead made by muxing the source soundtrack after video generation.
+
+## 5. Sample the new shot
+
+| Mode | CLI settings | Transformer evaluations |
+|---|---|---|
+| Fast adapter, default | `--steps 4 --flow-shift 3` with the LoRA loaded | 3 |
+| Teacher | `--no-lora --steps 50 --flow-shift 12` | 49 |
+
+The H3 scheduler counts the terminal zero-noise point in `--steps`; that endpoint does not require
+another model evaluation. The adapter must be loaded on Meridian's finetuned transformer, not the
+unmodified MiniMax-H3 checkpoint. Forward counts do not equal end-to-end speedups: geometry,
+VAE work, and file writing still take time.
+
+## Training overview
+
+Training provenance, augmentations, and distillation design have moved to [Training and distillation](training.md).
+
+## Implementation map
+
+| Source | What to read |
+|---|---|
+| [`recam/geometry.py`](../recam/geometry.py) | `reconstruct`, `warp`, and `render_hw`: geometry filtering, projection, and visibility. |
+| [`recam/path.py`](../recam/path.py) | `plan_path` and `hermite`: keyframe interpolation, time mapping, and zero-roll look-at cameras. |
+| [`recam/h3.py`](../recam/h3.py) | `bucket`, `pack`, and `denoise`: canvases, reference conditioning, and the scheduler. |
+| [`inference/sample.py`](../inference/sample.py) | CLI time windows, parametric camera moves, diagnostics, and output files. |
+| [`service/app.py`](../service/app.py) | `prepare`, `geo`, and `do_render`: cached reconstruction and resident inference. |
+
+For weight provenance and modification notices, see [`MODIFICATIONS.md`](../MODIFICATIONS.md).

docs/release_checklist.md

@@ -0,0 +1,35 @@
+# Release preparation — internal checklist
+
+**Keep `Viggle/Meridian` private. Do not publish it without the user's explicit approval.**
+Release-facing wording does not authorize changing repository visibility.
+
+## Outstanding publication checks
+
+- Public-use clearance, including for the NBA footage and figures, remains pending. The presentation
+  examples are research previews; retain source credits and edit records before choosing publication assets.
+- Confirm and upload the intended transformer and LoRA weights before calling the model download complete.
+  The old `Viggle/Viggle-Recam` identifier was inaccessible during verification; do not restore it as a working download.
+- Low-memory configurations, including RTX 4090, are community integration targets, not validated support.
+- Fast point-cloud preview helps inspect an authored path; it does not guarantee generated-view fidelity.
+
+## Presentation and review
+
+- Replace local preview links with cleared publication assets.
+- Method video strips use actual matched frames; the 3D points and camera path are explicitly schematic. Retain this distinction and the source provenance.
+- Studio overview is recorded and preview-only; capture and review a matching generated take before extending it to demonstrate final generation.
+- Complete continuous visual motion review; automated playback and sampled frames are not sufficient.
+- Retain exact camera controls if presenting an isolated space/time ablation.
+- Confirm permission to use every source clip and to publish the corresponding demonstrations.
+- Keep source-time labels accurate when comparing live, retimed, and held sequences.
+- Verify the reported timing against a retained run log before publishing it as a headline result.
+- Do not add a speedup ratio, quality comparison, ablation, or metric without supporting results.
+- Hub destination: Viggle/Meridian (private). Do not point weight-download commands here until the weights are present.
+- Upload referenced presentation media with the Markdown; keep the private Hub snapshot separate from public-use clearance. The legacy push_docs.py targets a different repository.
+
+## Retained provenance
+
+- [Current example sources and edit notes](../videos-all/research_examples_v2/README.md)
+- [Teaser credits](../videos-all/longtake_showcase/TEASER_V7_NOTES.md)
+- [Method figure sources](assets/research/README.md#illustrated-method)
+- [Studio recording notes](studio_walkthrough.md)
+- [Training and distillation](training.md)

docs/research.html

@@ -0,0 +1,242 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Meridian: A new perspective on space and time</title>
+<style>
+:root { color-scheme: light; --ink: #202923; --muted: #647068; --accent: #21634c; --line: #dee5df; }
+* { box-sizing: border-box; }
+html { scroll-behavior: smooth; scroll-padding-top: 2rem; }
+body { margin: 0; background: #f6f7f3; color: var(--ink); font: 17px/1.8 system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; }
+a { color: var(--accent); text-underline-offset: .2em; }
+a:hover { text-decoration-thickness: 2px; }
+a:focus-visible { outline: 3px solid var(--accent); outline-offset: 4px; }
+.skip-link { position: absolute; left: 1rem; top: -5rem; padding: .5rem 1rem; background: white; }
+.skip-link:focus { top: 1rem; }
+.page-header { max-width: 1280px; margin: auto; padding: 1.5rem 2.5rem; display: flex; justify-content: space-between; gap: 1rem; border-bottom: 1px solid var(--line); color: var(--muted); font-size: .8rem; }
+.page-header span { font-weight: 700; letter-spacing: .12em; text-transform: uppercase; }
+.layout { max-width: 1280px; margin: auto; padding: 3.5rem 2.5rem 5rem; display: grid; grid-template-columns: 220px minmax(0, 1fr); gap: 3.5rem; align-items: start; }
+nav { position: sticky; top: 2rem; max-height: calc(100vh - 4rem); overflow-y: auto; font-size: .8rem; line-height: 1.5; }
+nav h2 { margin: 0 0 1rem; color: var(--muted); font-size: .75rem; letter-spacing: .1em; text-transform: uppercase; }
+nav ul { padding: 0; margin: 0; list-style: none; }
+nav ul ul { padding-left: 1rem; border-left: 1px solid var(--line); margin-top: .5rem; }
+nav li { margin-bottom: .65rem; }
+nav a { color: var(--muted); text-decoration: none; }
+nav a:hover { color: var(--accent); }
+article { min-width: 0; max-width: 850px; padding: 3rem; border: 1px solid var(--line); border-radius: 12px; background: #fff; }
+h1, h2, h3 { line-height: 1.25; letter-spacing: -.025em; text-wrap: balance; }
+h1 { margin: 0 0 1.6rem; font-size: clamp(2rem, 4vw, 3.2rem); }
+article h2 { margin: 3rem 0 1.2rem; padding-top: 1.8rem; border-top: 1px solid var(--line); font-size: 1.7rem; }
+article h3 { margin: 2.2rem 0 1rem; font-size: 1.25rem; }
+p { margin: 1.2rem 0; }
+article a { overflow-wrap: anywhere; }
+img { display: block; max-width: 100%; height: auto; margin: 1.6rem auto; border-radius: 6px; }
+video { display: block; width: 100%; height: auto; object-fit: contain; background: #0b0c0c; border-radius: 6px; }
+video:focus-visible, summary:focus-visible { outline: 3px solid var(--accent); outline-offset: 4px; }
+.film { min-width: 0; margin: 1.6rem 0; }
+.film .film-caption { margin-top: .65rem; color: var(--muted); font-size: .8rem; line-height: 1.6; }
+.video-grid { display: table; width: 100%; table-layout: fixed; border-collapse: separate; border-spacing: 0; margin: 1.8rem 0; }
+.video-grid td { width: 50%; padding: 0 1rem 1.5rem 0; border: 0; vertical-align: top; }
+.video-grid td:nth-child(2) { padding-right: 0; padding-left: .5rem; }
+.video-grid p { margin: .65rem 0 0; color: var(--muted); font-size: .8rem; line-height: 1.6; }
+.video-grid video { aspect-ratio: 1920 / 1088; }
+.more-examples { margin: 1.8rem 0; padding: 1rem 0; border-top: 1px solid var(--line); border-bottom: 1px solid var(--line); }
+.more-examples summary { color: var(--accent); cursor: pointer; }
+.more-examples > p { font-size: .85rem; }
+.studio-demo { margin-top: 1.5rem; }
+.studio-demo summary { color: var(--accent); cursor: pointer; }
+.studio-demo .film { margin-bottom: 0; }
+code { padding: .15em .35em; border-radius: 4px; background: #eef2ed; font-size: .87em; }
+pre { overflow-x: auto; padding: 1rem; background: #eef2ed; border-radius: 6px; }
+pre code { padding: 0; }
+blockquote { margin: 1.5rem 0; padding-left: 1.2rem; border-left: 3px solid var(--accent); color: var(--muted); }
+li { margin-bottom: .4rem; }
+hr { border: 0; border-top: 1px solid var(--line); margin: 3rem 0; }
+table { display: block; overflow-x: auto; border-collapse: collapse; }
+th, td { padding: .5rem .8rem; border: 1px solid var(--line); text-align: left; }
+@media (max-width: 1000px) {
+  .layout { grid-template-columns: 1fr; gap: 2rem; max-width: 900px; padding: 2rem 1.5rem; }
+  nav { position: static; max-height: none; }
+  nav > .toc > ul { columns: 2; column-gap: 2rem; }
+  nav li { break-inside: avoid; }
+  article { padding: 2rem; }
+}
+@media (max-width: 600px) {
+  body { font-size: 16px; }
+  .page-header { padding: 1rem; }
+  .layout { padding: 1.5rem .75rem; }
+  nav { padding: 0 .5rem; }
+  nav > .toc > ul { columns: 1; }
+  article { padding: 1.4rem; }
+  .video-grid, .video-grid tbody, .video-grid tr, .video-grid td { display: block; width: 100%; }
+  .video-grid td, .video-grid td:nth-child(2) { padding: 0 0 1.5rem; }
+}
+@media (prefers-reduced-motion: reduce) { html { scroll-behavior: auto; } }
+@media print {
+  body { background: white; font-size: 11pt; }
+  .page-header, nav, .skip-link { display: none; }
+  .layout { display: block; padding: 0; }
+  article { max-width: none; padding: 0; border: 0; }
+  h1, h2, h3 { break-after: avoid; }
+  img { break-inside: avoid; }
+  a { color: inherit; }
+}
+</style>
+</head>
+<body>
+<a class="skip-link" href="#article">Skip to article</a>
+<header class="page-header"><span>Meridian · Research</span><a href="research.md">Markdown source</a></header>
+<div class="layout">
+<nav aria-label="Table of contents"><h2>Contents</h2><div class="toc">
+<ul>
+<li><a href="#choose-where-choose-when">Choose where. Choose when.</a></li>
+<li><a href="#method">Method</a></li>
+<li><a href="#why-this-matters">Why this matters</a></li>
+<li><a href="#try-meridian">Try Meridian</a></li>
+</ul>
+</div>
+
+</nav>
+<main id="article"><article>
+<h1 id="meridian-a-new-perspective-on-space-and-time">Meridian: A new perspective on space and time</h1>
+<p><strong>One event. Anywhere. Anytime.</strong></p>
+<p>By <strong>Viggle AI</strong></p>
+<p><em>14 September 2026.</em></p>
+<div class="film hero-film">
+  <video id="teaser-film" controls playsinline preload="none" width="100%" poster="../videos-all/longtake_showcase/teaser_v7/intro_059.jpg" src="../videos-all/teaser_meridian_showcase_v7.mp4" aria-label="Meridian teaser: a new perspective on space and time">
+    <a href="../videos-all/teaser_meridian_showcase_v7.mp4">Watch the Meridian teaser</a>.
+  </video>
+  <p class="film-caption">48-second teaser</p>
+</div>
+
+<p><strong>Meridian is a geometry-guided video model for authoring new observations of existing events.</strong>
+Given a video, choose a new camera path and the source moments to observe. Follow the action from
+another angle, linger on a gesture, or hold an instant while the camera keeps moving.</p>
+<h2 id="choose-where-choose-when">Choose where. Choose when.</h2>
+<ul>
+<li><strong>Where:</strong> design the camera's position, viewing direction, and lens over a shot.</li>
+<li><strong>When:</strong> let the action advance, hold a source moment, or change its pace by retiming the input.</li>
+</ul>
+<p><strong>Bullet time is one possibility, not the whole idea.</strong> Camera motion and source time can be
+composed into different ways of watching the same event. A single image can also be the starting
+point for a moving view.</p>
+<p>The compound-camera example shows its source and requested path. The ballet examples use still images.</p>
+<table class="video-grid">
+  <tr>
+    <td width="50%" valign="top">
+      <video id="nba-film" controls playsinline preload="none" width="100%" poster="../videos-all/research_examples_v1/nba.jpg" src="../videos-all/research_examples_v1/nba.mp4" aria-label="NBA edit combining labeled source footage and generated views of held moments">
+        <a href="../videos-all/research_examples_v1/nba.mp4">Watch the example</a>.
+      </video>
+      <p><strong>A dunk.</strong> Source action, revisited from new angles. An edited sequence; dunk completion is source footage.</p>
+    </td>
+    <td width="50%" valign="top">
+      <video id="berry-film" controls playsinline preload="none" width="100%" poster="../videos-all/research_examples_v1/berry.jpg" src="../videos-all/research_examples_v1/berry.mp4" aria-label="Strawberries: source time advances, holds while the camera moves, then resumes">
+        <a href="../videos-all/research_examples_v1/berry.mp4">Watch the example</a>.
+      </video>
+      <p><strong>Play. Hold. Resume.</strong> Linger on the splash, then let it continue.</p>
+    </td>
+  </tr>
+  <tr>
+    <td width="50%" valign="top">
+      <video id="moto-film" controls playsinline preload="none" width="100%" poster="../videos-all/research_examples_v2/motor_compound.jpg" src="../videos-all/teaser_meridian_compound_motor_dust_explained_v1.mp4" aria-label="Motocross: one uncut take with a compound camera path, selected source video, and requested camera diagrams">
+        <a href="../videos-all/teaser_meridian_compound_motor_dust_explained_v1.mp4">Watch the example</a>.
+      </video>
+      <p><strong>Compose a camera path.</strong> Widen, orbit, slide, approach, retreat—one uncut take.</p>
+    </td>
+    <td width="50%" valign="top">
+      <video id="ballet-film" controls playsinline preload="none" width="100%" poster="../videos-all/research_examples_v2/ballet_reverse45.jpg" src="../videos-all/meridian_ballet_l150_female_reverse45.mp4" aria-label="Female ballet dancer: generated camera movement from one still image">
+        <a href="../videos-all/meridian_ballet_l150_female_reverse45.mp4">Watch the example</a>.
+      </video>
+      <p><strong>One image. Another viewpoint.</strong> A camera move from a single ballet image.</p>
+    </td>
+  </tr>
+</table>
+
+<details class="more-examples">
+  <summary>More examples · robots, animation, dance, and sport</summary>
+  <table class="video-grid">
+  <tr>
+    <td width="50%" valign="top">
+      <video id="robot-film" controls playsinline preload="none" width="100%" poster="../videos-all/research_examples_v1/robot.jpg" src="../videos-all/research_examples_v1/robot.mp4" aria-label="Robot folding cloth from a higher generated viewpoint, with aligned input">
+        <a href="../videos-all/research_examples_v1/robot.mp4">Watch the example</a>.
+      </video>
+      <p><strong>Robot manipulation.</strong> The task continues from a higher viewpoint.</p>
+    </td>
+    <td width="50%" valign="top">
+      <video id="charge-film" controls playsinline preload="none" width="100%" poster="../videos-all/research_examples_v1/charge.jpg" src="../videos-all/research_examples_v1/charge.mp4" aria-label="Charge animation: play, hold, resume with a moving viewpoint">
+        <a href="../videos-all/research_examples_v1/charge.mp4">Watch the example</a>.
+      </video>
+      <p><strong>An animated event.</strong> Hold the action; move the camera.</p>
+    </td>
+  </tr>
+  <tr>
+    <td width="50%" valign="top">
+      <video id="ballet_male-film" controls playsinline preload="none" width="100%" poster="../videos-all/research_examples_v1/ballet_male.jpg" src="../videos-all/research_examples_v1/ballet_male.mp4" aria-label="Male ballet dancer: a separate single-image input and generated viewpoint">
+        <a href="../videos-all/research_examples_v1/ballet_male.mp4">Watch the example</a>.
+      </video>
+      <p><strong>Another ballet photograph.</strong> One image, a moving view.</p>
+    </td>
+    <td width="50%" valign="top">
+      <video id="gymnast-film" controls playsinline preload="none" width="100%" poster="../videos-all/research_examples_v1/gymnast.jpg" src="../videos-all/research_examples_v1/gymnast.mp4" aria-label="Gymnastics: action continues while the generated camera rises">
+        <a href="../videos-all/research_examples_v1/gymnast.mp4">Watch the example</a>.
+      </video>
+      <p><strong>A rising view.</strong> The gesture unfolds.</p>
+    </td>
+  </tr>
+  <tr>
+    <td width="50%" valign="top">
+      <video id="powder-film" controls playsinline preload="none" width="100%" poster="../videos-all/research_examples_v1/powder.jpg" src="../videos-all/research_examples_v1/powder.mp4" aria-label="Snow sports: action continues with a moving generated viewpoint">
+        <a href="../videos-all/research_examples_v1/powder.mp4">Watch the example</a>.
+      </video>
+      <p><strong>Through the powder.</strong> Move with the action.</p>
+    </td>
+  </tr>
+</table>
+</details>
+
+<h2 id="method">Method</h2>
+<p><img alt="Input video enters VGGT-Omega; estimated depth and source cameras give colored 3D points. User-specified target cameras reproject those points into a warped video. Both the time-aligned source video and warped video condition Meridian to generate the output video. Video samples are real; 3D points and cameras are schematic." src="assets/research/meridian_illustrated_method.png" /></p>
+<p><em>Matched source, warp, and output frames; the 3D points and cameras are schematic.</em></p>
+<p>The method is simple: <strong>use geometry to show a video model where to look.</strong></p>
+<p><strong>1. Reproject the source.</strong> VGGT-Omega estimates depth and source-camera poses. We build colored
+3D points, select the source moments, and project those points through an authored camera path
+into a warped video.</p>
+<p><strong>2. Generate the new view.</strong> Meridian, built on MiniMax-H3, takes <strong>the source video and warped
+video</strong>, aligned to the same source moments, and generates the new shot. Geometry guides the view;
+the video model fills missing regions and refines appearance.</p>
+<p><strong>Preview before generation.</strong> Once geometry is available, fast point-cloud rendering makes the
+chosen path visible. Check the framing, viewing direction, and uncovered regions—and adjust the
+camera before running the video model. This inexpensive preview is a useful consequence of making
+camera control explicit.</p>
+<h2 id="why-this-matters">Why this matters</h2>
+<p>The shift is from generating another scene to <strong>choosing another observation of the same event</strong>.
+This is the world-model perspective behind Meridian: connect what we see to where and when we
+observe it, grounded in supplied footage rather than unrestricted simulation.</p>
+<p>Unseen regions are generated, not recovered. Geometry errors and large moves—including 360°
+orbits—can destabilize the view. Time edits revisit supplied frames, and separate takes need not
+form a consistent world.</p>
+<h2 id="try-meridian">Try Meridian</h2>
+<p><a href="../README.md#quickstart">Get started with Meridian</a>.</p>
+<p>Meridian uses MiniMax-H3 with precomputed text embeddings, <strong>without loading a text encoder</strong>.
+We welcome community work on quantization and CPU offloading toward smaller GPUs, including the
+RTX 4090; those configurations are not yet supported or validated by the provided implementation.</p>
+<p>The release also includes a <strong>very basic, vibe-coded Studio demo</strong> to illustrate how
+to use the model—not a production editor. It supports multi-key camera paths and real-time 3D
+preview, not real-time video generation.</p>
+<details class="studio-demo">
+  <summary>Watch the 38-second Studio walkthrough</summary>
+  <div class="film">
+    <video id="studio-film" controls playsinline preload="none" width="100%" poster="../videos-all/studio_walkthrough/nba3_preview_live_02/studio_walkthrough_concise_poster.jpg" src="../videos-all/studio_walkthrough/nba3_preview_live_02/studio_walkthrough_concise.mp4" aria-label="Early Studio demo: actual authoring and geometric preview, not final generation">
+      <a href="../videos-all/studio_walkthrough/nba3_preview_live_02/studio_walkthrough_concise.mp4">Watch the Studio walkthrough</a>.
+    </video>
+    <p class="film-caption">Authoring and geometric preview only, with some operations and waits omitted—not a final generated take.</p>
+  </div>
+</details>
+
+<hr />
+<p>Powered by MiniMax H3. See the <a href="../README.md#license">licenses and intended use</a>.</p>
+</article></main>
+</div>
+</body>
+</html>

docs/research.md

@@ -0,0 +1,159 @@
+# Meridian: A new perspective on space and time
+
+**One event. Anywhere. Anytime.**
+
+By **Viggle AI**
+
+*14 September 2026.*
+
+<div class="film hero-film">
+  <video id="teaser-film" controls playsinline preload="none" width="100%" poster="https://huggingface.co/Viggle/Meridian/resolve/main/videos-all/longtake_showcase/teaser_v7/intro_059.jpg" src="https://huggingface.co/Viggle/Meridian/resolve/main/videos-all/teaser_meridian_showcase_v7.mp4" aria-label="Meridian teaser: a new perspective on space and time">
+    <a href="https://huggingface.co/Viggle/Meridian/resolve/main/videos-all/teaser_meridian_showcase_v7.mp4">Watch the Meridian teaser</a>.
+  </video>
+  <p class="film-caption">48-second teaser</p>
+</div>
+
+**Meridian is a geometry-guided video model for authoring new observations of existing events.**
+Given a video, choose a new camera path and the source moments to observe. Follow the action from
+another angle, linger on a gesture, or hold an instant while the camera keeps moving.
+
+## Choose where. Choose when.
+
+- **Where:** design the camera's position, viewing direction, and lens over a shot.
+- **When:** let the action advance, hold a source moment, or change its pace by retiming the input.
+
+**Bullet time is one possibility, not the whole idea.** Camera motion and source time can be
+composed into different ways of watching the same event. A single image can also be the starting
+point for a moving view.
+
+The compound-camera example shows its source and requested path. The ballet examples use still images.
+
+<table class="video-grid">
+  <tr>
+    <td width="50%" valign="top">
+      <video id="nba-film" controls playsinline preload="none" width="100%" poster="https://huggingface.co/Viggle/Meridian/resolve/main/videos-all/research_examples_v1/nba.jpg" src="https://huggingface.co/Viggle/Meridian/resolve/main/videos-all/research_examples_v1/nba.mp4" aria-label="NBA edit combining labeled source footage and generated views of held moments">
+        <a href="https://huggingface.co/Viggle/Meridian/resolve/main/videos-all/research_examples_v1/nba.mp4">Watch the example</a>.
+      </video>
+      <p><strong>A dunk.</strong> Source action, revisited from new angles. An edited sequence; dunk completion is source footage.</p>
+    </td>
+    <td width="50%" valign="top">
+      <video id="berry-film" controls playsinline preload="none" width="100%" poster="https://huggingface.co/Viggle/Meridian/resolve/main/videos-all/research_examples_v1/berry.jpg" src="https://huggingface.co/Viggle/Meridian/resolve/main/videos-all/research_examples_v1/berry.mp4" aria-label="Strawberries: source time advances, holds while the camera moves, then resumes">
+        <a href="https://huggingface.co/Viggle/Meridian/resolve/main/videos-all/research_examples_v1/berry.mp4">Watch the example</a>.
+      </video>
+      <p><strong>Play. Hold. Resume.</strong> Linger on the splash, then let it continue.</p>
+    </td>
+  </tr>
+  <tr>
+    <td width="50%" valign="top">
+      <video id="moto-film" controls playsinline preload="none" width="100%" poster="https://huggingface.co/Viggle/Meridian/resolve/main/videos-all/research_examples_v2/motor_compound.jpg" src="https://huggingface.co/Viggle/Meridian/resolve/main/videos-all/teaser_meridian_compound_motor_dust_explained_v1.mp4" aria-label="Motocross: one uncut take with a compound camera path, selected source video, and requested camera diagrams">
+        <a href="https://huggingface.co/Viggle/Meridian/resolve/main/videos-all/teaser_meridian_compound_motor_dust_explained_v1.mp4">Watch the example</a>.
+      </video>
+      <p><strong>Compose a camera path.</strong> Widen, orbit, slide, approach, retreat—one uncut take.</p>
+    </td>
+    <td width="50%" valign="top">
+      <video id="ballet-film" controls playsinline preload="none" width="100%" poster="https://huggingface.co/Viggle/Meridian/resolve/main/videos-all/research_examples_v2/ballet_reverse45.jpg" src="https://huggingface.co/Viggle/Meridian/resolve/main/videos-all/meridian_ballet_l150_female_reverse45.mp4" aria-label="Female ballet dancer: generated camera movement from one still image">
+        <a href="https://huggingface.co/Viggle/Meridian/resolve/main/videos-all/meridian_ballet_l150_female_reverse45.mp4">Watch the example</a>.
+      </video>
+      <p><strong>One image. Another viewpoint.</strong> A camera move from a single ballet image.</p>
+    </td>
+  </tr>
+</table>
+
+<details class="more-examples">
+  <summary>More examples · robots, animation, dance, and sport</summary>
+  <table class="video-grid">
+  <tr>
+    <td width="50%" valign="top">
+      <video id="robot-film" controls playsinline preload="none" width="100%" poster="https://huggingface.co/Viggle/Meridian/resolve/main/videos-all/research_examples_v1/robot.jpg" src="https://huggingface.co/Viggle/Meridian/resolve/main/videos-all/research_examples_v1/robot.mp4" aria-label="Robot folding cloth from a higher generated viewpoint, with aligned input">
+        <a href="https://huggingface.co/Viggle/Meridian/resolve/main/videos-all/research_examples_v1/robot.mp4">Watch the example</a>.
+      </video>
+      <p><strong>Robot manipulation.</strong> The task continues from a higher viewpoint.</p>
+    </td>
+    <td width="50%" valign="top">
+      <video id="charge-film" controls playsinline preload="none" width="100%" poster="https://huggingface.co/Viggle/Meridian/resolve/main/videos-all/research_examples_v1/charge.jpg" src="https://huggingface.co/Viggle/Meridian/resolve/main/videos-all/research_examples_v1/charge.mp4" aria-label="Charge animation: play, hold, resume with a moving viewpoint">
+        <a href="https://huggingface.co/Viggle/Meridian/resolve/main/videos-all/research_examples_v1/charge.mp4">Watch the example</a>.
+      </video>
+      <p><strong>An animated event.</strong> Hold the action; move the camera.</p>
+    </td>
+  </tr>
+  <tr>
+    <td width="50%" valign="top">
+      <video id="ballet_male-film" controls playsinline preload="none" width="100%" poster="https://huggingface.co/Viggle/Meridian/resolve/main/videos-all/research_examples_v1/ballet_male.jpg" src="https://huggingface.co/Viggle/Meridian/resolve/main/videos-all/research_examples_v1/ballet_male.mp4" aria-label="Male ballet dancer: a separate single-image input and generated viewpoint">
+        <a href="https://huggingface.co/Viggle/Meridian/resolve/main/videos-all/research_examples_v1/ballet_male.mp4">Watch the example</a>.
+      </video>
+      <p><strong>Another ballet photograph.</strong> One image, a moving view.</p>
+    </td>
+    <td width="50%" valign="top">
+      <video id="gymnast-film" controls playsinline preload="none" width="100%" poster="https://huggingface.co/Viggle/Meridian/resolve/main/videos-all/research_examples_v1/gymnast.jpg" src="https://huggingface.co/Viggle/Meridian/resolve/main/videos-all/research_examples_v1/gymnast.mp4" aria-label="Gymnastics: action continues while the generated camera rises">
+        <a href="https://huggingface.co/Viggle/Meridian/resolve/main/videos-all/research_examples_v1/gymnast.mp4">Watch the example</a>.
+      </video>
+      <p><strong>A rising view.</strong> The gesture unfolds.</p>
+    </td>
+  </tr>
+  <tr>
+    <td width="50%" valign="top">
+      <video id="powder-film" controls playsinline preload="none" width="100%" poster="https://huggingface.co/Viggle/Meridian/resolve/main/videos-all/research_examples_v1/powder.jpg" src="https://huggingface.co/Viggle/Meridian/resolve/main/videos-all/research_examples_v1/powder.mp4" aria-label="Snow sports: action continues with a moving generated viewpoint">
+        <a href="https://huggingface.co/Viggle/Meridian/resolve/main/videos-all/research_examples_v1/powder.mp4">Watch the example</a>.
+      </video>
+      <p><strong>Through the powder.</strong> Move with the action.</p>
+    </td>
+  </tr>
+</table>
+</details>
+
+## Method
+
+![Input video enters VGGT-Omega; estimated depth and source cameras give colored 3D points. User-specified target cameras reproject those points into a warped video. Both the time-aligned source video and warped video condition Meridian to generate the output video. Video samples are real; 3D points and cameras are schematic.](https://huggingface.co/Viggle/Meridian/resolve/main/docs/assets/research/meridian_illustrated_method.png)
+
+*Matched source, warp, and output frames; the 3D points and cameras are schematic.*
+
+The method is simple: **use geometry to show a video model where to look.**
+
+**1. Reproject the source.** VGGT-Omega estimates depth and source-camera poses. We build colored
+3D points, select the source moments, and project those points through an authored camera path
+into a warped video.
+
+**2. Generate the new view.** Meridian, built on MiniMax-H3, takes **the source video and warped
+video**, aligned to the same source moments, and generates the new shot. Geometry guides the view;
+the video model fills missing regions and refines appearance.
+
+**Preview before generation.** Once geometry is available, fast point-cloud rendering makes the
+chosen path visible. Check the framing, viewing direction, and uncovered regions—and adjust the
+camera before running the video model. This inexpensive preview is a useful consequence of making
+camera control explicit.
+
+## Why this matters
+
+The shift is from generating another scene to **choosing another observation of the same event**.
+This is the world-model perspective behind Meridian: connect what we see to where and when we
+observe it, grounded in supplied footage rather than unrestricted simulation.
+
+Unseen regions are generated, not recovered. Geometry errors and large moves—including 360°
+orbits—can destabilize the view. Time edits revisit supplied frames, and separate takes need not
+form a consistent world.
+
+## Try Meridian
+
+[Get started with Meridian](../README.md#quickstart).
+
+Meridian uses MiniMax-H3 with precomputed text embeddings, **without loading a text encoder**.
+We welcome community work on quantization and CPU offloading toward smaller GPUs, including the
+RTX 4090; those configurations are not yet supported or validated by the provided implementation.
+
+The release also includes a **very basic, vibe-coded Studio demo** to illustrate how
+to use the model—not a production editor. It supports multi-key camera paths and real-time 3D
+preview, not real-time video generation.
+
+<details class="studio-demo">
+  <summary>Watch the 38-second Studio walkthrough</summary>
+  <div class="film">
+    <video id="studio-film" controls playsinline preload="none" width="100%" poster="https://huggingface.co/Viggle/Meridian/resolve/main/videos-all/studio_walkthrough/nba3_preview_live_02/studio_walkthrough_concise_poster.jpg" src="https://huggingface.co/Viggle/Meridian/resolve/main/videos-all/studio_walkthrough/nba3_preview_live_02/studio_walkthrough_concise.mp4" aria-label="Early Studio demo: actual authoring and geometric preview, not final generation">
+      <a href="https://huggingface.co/Viggle/Meridian/resolve/main/videos-all/studio_walkthrough/nba3_preview_live_02/studio_walkthrough_concise.mp4">Watch the Studio walkthrough</a>.
+    </video>
+    <p class="film-caption">Authoring and geometric preview only, with some operations and waits omitted—not a final generated take.</p>
+  </div>
+</details>
+
+---
+
+Powered by MiniMax H3. See the [licenses and intended use](../README.md#license).

docs/studio.md

@@ -0,0 +1,210 @@
+# Studio: author a new shot
+
+[← Meridian](../README.md) · [Installation](installation.md) · [API](api.md) · [CLI](inference.md)
+
+The self-hosted studio lets you place cameras in a reconstructed scene, inspect the geometry reference,
+and generate a take without writing a command for every path revision.
+
+## What updates in real time?
+
+After reconstruction and point-cloud loading, the **browser's 3D view updates interactively** as you
+move cameras, change their aim or look through a key. This is the real-time authoring preview—not
+real-time generative video.
+
+The **full-path geometric-reference video** is refreshed by the server after a valid edit. It uses
+GPU warping and video encoding, and may wait behind reconstruction or generation on the same service.
+The **final generated take** is a separate job started with **Render this take**. No fixed preview
+latency or frame-rate guarantee is implied.
+
+## Start the service
+
+After [installation](installation.md), run from the release directory:
+
+```bash
+CARD=0 bash service/run.sh --host 127.0.0.1 --port 8412
+```
+
+Open `http://127.0.0.1:8412` after the terminal prints `ready`. Startup loads VGGT-Omega, the VAE,
+the finetuned teacher, and the student adapter onto one GPU; the previously reported B200 cold-start
+time is about 95 seconds. The active shell must have the VGGT-Omega environment variables set.
+
+If you downloaded the VAE locally, append `--model-dir ../MiniMax-H3`.
+
+**Keep the service private.** The program defaults to `0.0.0.0` when `--host` is omitted; the command
+above deliberately binds to loopback. The service has no authentication, per-user isolation, upload
+quota, or bounded durable job queue. For access to a remote machine, use an SSH tunnel or a protected
+deployment with authentication, resource limits, and the safeguards required by the model license.
+Do not expose this development service directly to the internet.
+
+## From clip to take
+
+### 1. Choose a clip and source window
+
+Upload an MP4/MOV/WebM or choose one of the sample clips. The service normalizes it to H.264,
+24 fps, and an aspect-preserving frame bounded by 1280 × 1280, with rotation baked in. Unlike the
+CLI, it performs this normalization automatically.
+
+The current page requires at least **73 normalized input frames**. It detects candidate hard cuts and
+prepares an initial window of at most **124 source frames**, stopping before the next detected cut.
+Cut detection is heuristic; split a clip manually if a cut is missed or a flash is mistaken for one.
+Moving the window's start reconstructs the new span and **resets the keys**.
+
+Select the take length separately. The page offers **73, 124, 175, or 243 output frames**; the CLI
+exposes all eight supported model lengths. A longer take does not automatically mean a longer source
+window or additional captured action.
+
+### 2. Start from a camera move
+
+Use a template: **orbit**, **push in**, **slide**, **crane**, **freeze + orbit**, or **the clip's own
+camera**. Templates replace the existing keys; **Ctrl+Z** undoes an edit.
+
+The source-camera template initializes editable endpoints; it is not an exact replay of every
+estimated source pose. Likewise, a template translated into a few keys is an editable approximation
+of its underlying parametric move. Inspect the resulting reference rather than assuming it matches
+a CLI command exactly.
+
+### 3. Refine the keys
+
+Each key chooses a camera and a time:
+
+| Control | Meaning |
+|---|---|
+| Camera position | Where to observe the scene from. Drag a camera in the 3D view. |
+| **aims at** | The key's look-at point. Use **pick in 3D** or **centre**. This does not change the reconstruction's depth scale. |
+| **clip frame it shows** | Source frame, indexed in the normalized uploaded clip. |
+| **output frame it lands on** | Position in the generated take. The first and last keys anchor its endpoints. |
+| **lens** | Horizontal field of view, converted to a multiplier over the selected source frame's estimated focal length. |
+
+Click a key's row or thumbnail to look through its camera; use **back to the overview** to see the
+whole path. While looking through a key, drag to aim, Shift-drag to translate, and scroll to dolly.
+Add a key at the preview frame to refine a segment. Camera roll is fixed to zero.
+
+### Go beyond a preset
+
+A path can combine several stages: **push forward → turn toward a detail → slide right → retreat**.
+Add a key at each change of intention, then set its position and look-at point in the shared 3D scene.
+Position and aim interpolate along cubic curves; the source-frame map is interpolated separately.
+This is different from ramping yaw, translation and dolly together in one CLI sweep.
+
+To let the camera travel while an instant holds, assign the same **clip frame it shows** to two or
+more keys at different output frames. Resume with a later source frame. Inspect every segment and
+the joins: several keys do not guarantee adequate geometry, subject visibility or generated continuity.
+The [walkthrough plan](studio_walkthrough.md#source-and-camera-design) includes a concrete timing
+sketch, not scene-independent camera coordinates or an already-generated demonstration.
+
+### 4. Inspect the reference
+
+After a valid edit, the studio re-warps the path before enabling generation:
+
+- **what the model sees:** the grey-hole geometry reference at conditioning resolution.
+- **where the pixels are missing:** the same view with missing regions highlighted in magenta.
+
+The reference is generated by the same geometry path used for inference. Its browser playback is a
+compressed visualization, not a pixel-exact copy of the tensor. Coherent framing and stable surfaces
+matter more than a low missing-pixel percentage. Pay special attention to faces, thin structures,
+subject silhouettes, and new surfaces revealed by the camera.
+
+### 5. Render and compare
+
+Choose **Render this take** after checking the path. The service performs VAE encoding, three student
+forwards, decoding, and video writing; progress appears on the render screen. Generation recomputes
+the warp rather than reading the preview MP4 back into the model.
+
+The take screen shows the selected source timeline, geometry reference, and generated shot in sync.
+Download `out.mp4` or the three-up `grid.mp4`. Service outputs have no soundtrack; the CLI's
+`out_audio.mp4` muxing workflow is not part of the studio. Camera archives (`cams.npz`) are CLI-only.
+
+## Source time and output time
+
+The keyframe representation is `{pos, look, src, t, ease, focal}`. `src` is an absolute source index;
+`t` is an output index. Between two keys, the source rate is:
+
+```text
+rate = (next.src - current.src) / (next.t - current.t)
+```
+
+- **Rate 1:** preserve the uploaded video's pace, including any slow motion or speed-up already
+  baked into that video.
+- **Rate 0:** hold one instant while the camera may move.
+- **Other positive rates:** interpolate the source indices and round to frames, duplicating or
+  skipping them. The UI warns outside holds and approximately 1:1 playback; this is not a motion
+  interpolation system.
+- **Negative rates:** rejected. Source keys must never run backward.
+
+For slow motion or speed-ups, use the [24 fps source-retiming workflow](inference.md#slow-motion-and-speed-ups)
+first, then author a 1:1 path over that export. A warning about a keyframe segment does not mean
+pre-retimed footage is unsupported.
+
+**Check long takes carefully.** The page prepares at most 124 source frames. If you stretch that
+entire source window across a 243-frame take with two endpoints, the source advances at roughly
+half speed; it does not play 124 frames normally and then automatically hold. To preserve pace,
+place an explicit key where live motion ends, followed by a hold, or use the CLI with enough
+pre-retimed input frames. Changing take length or choosing a template can change these rates.
+
+## Preview checks
+
+The page enables rendering only after the latest valid warp passes these checks:
+
+| Check | Current threshold |
+|---|---|
+| Clearance proxy | `ahead >= -0.1`, in pivot-depth units. |
+| Difference from source camera | Translation `moved > 0.004`, key orientation change `turned > 0.5°`, or focal change `zoomed > 0.01`. |
+
+`ahead` is the minimum over time of the fifth-percentile target-camera depth for valid points in
+the central source region. It helps flag fly-throughs; it is **not** a complete collision test or a
+guarantee that the camera stays outside every surface. `moved` measures departure from the source
+camera, not whether the target camera travels over time. A different but stationary view can pass.
+
+The missing-pixel percentage is informative, not a gate. A pure focal change may pass the motion
+check while still being ignored by the model.
+
+**These clearance and camera-change checks live in the browser, not `/render`.** API clients must
+inspect previews and validate their own requests; calling `/render` bypasses the page's checks.
+The API also does not enforce the page's cut-aware 124-frame window policy.
+
+## Memory and lifecycle
+
+One process owns one GPU. A lock serializes GPU work, including preparation, previews, and generation;
+multiple requests do not yield concurrent GPU inference. Render requests start background threads
+that can wait on the lock, but there is no bounded queue, cancellation API, or durable job scheduler.
+Run **one worker**, not multiple Uvicorn workers that each load a model copy.
+
+| Option | Default | Purpose |
+|---|---|---|
+| `--host`, `--port` | `0.0.0.0`, `8412` | Listen address; use loopback unless the deployment is protected. |
+| `--work` | `<release>/work` | Uploads, preview files, and generated takes. |
+| `--samples` | `<release>/examples/media` | Sample MP4s listed on the first screen. |
+| `--max-clips` | `8` | Maximum number of decoded clips in the in-memory clip cache. |
+| `--max-prep` | `8` | Maximum number of prepared source spans in the geometry cache. |
+| `--ckpt`, `--lora` | Release directories | Teacher and student adapter. The service always loads an adapter. |
+| `--model-dir` | `MiniMaxAI/MiniMax-H3` | VAE location. |
+| `--vggt-repo`, `--vggt` | Environment-based | Geometry code and checkpoint. |
+| `--steps`, `--flow-shift` | `4`, `3` | Keep these at the student sampling settings for this release. |
+
+Prepared spans retain tensors on the GPU, and cache limits count **entries**, not bytes. Memory can
+grow as you explore different windows. Lower `--max-prep`, use shorter windows, or restart to release
+old sessions when operating near the memory limit. Reported single-take peaks do not bound a
+long-running service with many cached spans.
+
+`service/run.sh` restarts the process only after exit code `3`, used for a poisoned CUDA context.
+Other exits stop the wrapper. Clip, preparation, and job registries are in memory: a restart loses
+the live session even if files remain on disk. Re-upload/select the clip and prepare it again.
+Evicted clips or prepared spans can similarly invalidate older browser tabs.
+
+Generated files are not automatically expired. Monitor `<work>/clips`, `<work>/warp`, and
+`<work>/takes`; stop the service before manually removing data still referenced by an active session.
+Keep uploaded footage private and use material you have permission to process.
+
+## Troubleshooting the studio
+
+| Symptom | Next step |
+|---|---|
+| Render is disabled | Wait for the latest warp, check key order and source direction, then inspect the clearance and camera-change messages. |
+| The take unexpectedly slows down | Compare source and output indices, especially after choosing 175/243 frames or applying a template. |
+| Preparation fails near a cut | Move to a continuous span with at least two source frames, or trim and upload the shot separately. |
+| An old tab starts failing | Its cached clip or span may have been evicted, or the service restarted. Select the clip again. |
+| Previews stop while a take renders | GPU work is serialized; there is no separate preview GPU. |
+| Memory rises over a session | Reduce the prepared-span cache or restart; source-window length and cached tensors matter as well as output length. |
+| Page reports a GPU restart | Watch the terminal for `ready`, then start a new session. Previous job IDs will not be restored. |
+
+See [Installation](installation.md#setup-problems) for dependencies and [API](api.md) for programmatic use.

docs/studio_walkthrough.md

@@ -0,0 +1,251 @@
+# Meridian Studio — walkthrough film
+
+[← Research article](research.md#try-meridian) · [Studio guide](studio.md)
+
+**Status: a 38-second preview-only overview is available; a matching generated take is still pending.**
+[Watch the concise Studio overview](../videos-all/studio_walkthrough/nba3_preview_live_02/studio_walkthrough_concise.mp4)
+· [Editing recipe](../videos-all/studio_walkthrough/nba3_preview_live_02/edit_concise_01/edit.json).
+
+The concise edit uses restrained English titles and enlarged details of the actual UI:
+**one source → camera position and aim → held source time → geometric reference**.
+It omits repetitive authoring and backend waits, disclosed on screen, without accelerating the
+remaining actions. The complete supplied input and 243-frame geometric reference are retained;
+the UI capture is resampled from 25 to 24 fps. It is silent, with no final generated video implied.
+The original recording remains unchanged:
+
+[Watch the revised, uncut recording](../videos-all/studio_walkthrough/nba3_preview_live_02/studio_walkthrough_review.mp4)
+· [10-second geometric reference](../videos-all/studio_walkthrough/nba3_preview_live_02/preview_truth.mp4)
+· [Before / after camera comparison](../videos-all/studio_walkthrough/nba3_preview_live_02/review_camera_comparison.jpg)
+· [Session evidence](../videos-all/studio_walkthrough/nba3_preview_live_02/session.json).
+
+NBA3 replaces the flower scene as the current walkthrough candidate: approach → airborne hold with
+camera travel → resumed dunk and landing. The
+[earlier flower pilot](../videos-all/studio_walkthrough/flowers_preview_live_01/studio_walkthrough_review.mp4)
+is retained, not overwritten.
+
+**Revision 02 replaces the large orbit/approach with small athlete-framed lateral travel.**
+The athlete and hoop are substantially more legible in the held reference, and the source map
+continues through the dunk and landing. Review included contact sheets covering all 243 reference
+frames and larger comparisons at output frames 60, 134 and 179. The backend's average coverage
+rose from 61.2% to 83.9%; that is a geometric diagnostic, not a generated-quality score.
+
+**The reference still has conspicuous disocclusion holes and tearing around the athlete's outline.**
+This is a more useful authoring demonstration, not an approved cinematic result. Native-speed motion
+review and a matching generated take are still needed before publishing the research-page film.
+The [rejected first camera pilot](../videos-all/studio_walkthrough/nba3_preview_live_01/studio_walkthrough_review.mp4)
+is retained for comparison, not silently replaced.
+
+The September 13 recordings ran through Chromium against the existing Studio at `127.0.0.1:8412` on GPU 0,
+with permission to execute outside the restricted sandbox. It records actual seven-key authoring and
+geometric previews; **no final generation was submitted**. The running main-repository Studio has
+the same authoring controls as the release, with minor comment/warning-text differences; the served
+HTML is retained. Revision 02 completed 81 POST requests with no recorded API/browser errors and
+no `/render` request. The preview workflow passed its live checks; the script's `--render` branch remains
+untested. This is raw workflow evidence, not yet an approved research-page film.
+
+The older files named `browser_studio.png` are screenshots of a separate source/control gallery,
+not this camera-authoring application. Do not substitute them for a Studio demonstration.
+
+## Record with Playwright
+
+[Recording script](record_studio_walkthrough.py) — run it in a terminal where Chromium can launch
+and `http://127.0.0.1:8412` is reachable. That address means **the machine running the script**;
+use an existing private tunnel or `--url` if the Studio runs elsewhere. Do not expose the unauthenticated
+service publicly. The script connects to an existing service; it does not launch, restart or cancel it.
+
+**Arrange a free service/GPU slot first.** Even without `--render`, uploading triggers reconstruction,
+and editing triggers point-cloud, thumbnail and full-path warp work. The script waits between edits;
+it is not a CPU-only recording tool and cannot determine whether other users need that GPU.
+
+From the release root, make a preview-only pilot:
+
+```bash
+PY=/home/chenyun/miniforge3/envs/wan_new/bin/python
+"$PY" docs/record_studio_walkthrough.py \
+  --source videos-all/nba3_teacher30/nba3_full_event.mp4 \
+  --camera-style nba-glide \
+  --url http://127.0.0.1:8412 \
+  --out videos-all/studio_walkthrough/nba3_preview_02
+```
+
+This NBA3 plate contains the complete event in **124 frames at 24 fps**, already prepared from the
+supplied clip. The hold uses frame 60, during the airborne ball sweep before the dunk; the action
+then resumes through the landing. For another scene, choose a clean clip with at least 124 normalized frames
+before its first detected cut. It stops if that prepared span is shorter; it does not silently adapt
+the timing sketch. Retain source permission/attribution when substituting footage.
+
+The pilot uses actual UI controls to:
+
+1. Upload and reconstruct, select 243 output frames, then start from the source-camera path.
+2. Add and retime five intermediate keys using the source-time table below.
+3. Look through keys, make small sideways Shift-drags, and adjust the aim to retain the athlete and hoop.
+4. Return to the overview, scrub the hold, and play the real grey-hole and magenta references.
+
+`nba-glide` is **specific to the NBA3 full-event plate**. It reads the reconstructed torso point near
+normalized source-image coordinate `(0.367, 0.435)` at frame 60, then uses genuine pointer gestures
+to place it near `(0.40, 0.435)` during the hold. This preserves space for the ball and hoop rather
+than aiming every key at the scene centre. It does not inject camera state or replace UI responses.
+Read-only projection calculations guide the automated gestures; this is not an automatic subject-tracking feature.
+
+Nominal sideways offsets reach 0.024 scene-centre-depth units, with no forward push. Exact positions
+and aims are retained in `path_preview.json`; these depth-normalized units are not metres.
+The older nominal 30° orbit workflow remains available as `--camera-style orbit-pilot` (the script's
+default for compatibility), **not as the recommended NBA3 path**. Neither workflow is a
+reproduction of an approved CLI take, a large-angle benchmark or a guarantee of generated quality.
+Inspect both downloaded reference videos continuously before spending time on final generation.
+Passing the Studio's clearance gate is not a visual-quality verdict.
+
+To capture the same scripted workflow **including a new generated take**, use a new directory and
+add `--render`:
+
+```bash
+"$PY" docs/record_studio_walkthrough.py \
+  --source videos-all/nba3_teacher30/nba3_full_event.mp4 \
+  --camera-style nba-glide \
+  --out videos-all/studio_walkthrough/nba3_render_01 \
+  --render
+```
+
+This is a new session, not a resume of the preview. The script retains and checks the accepted job's
+payload against the path displayed in **that recording**. It never bypasses a disabled Render button.
+Add `--headed` to watch in Chromium on a machine with a display; let the automation finish without
+editing the same page. Default headless mode records the same viewport without needing a desktop.
+`--timeout` sets each backend wait in seconds; the default is 1800. A timeout or closed browser
+**does not cancel an already submitted job**. Check its recorded job ID before retrying.
+
+If Playwright or Chromium is missing, install them in the recording environment first:
+
+```bash
+"$PY" -m pip install playwright
+"$PY" -m playwright install chromium
+```
+
+### What gets saved
+
+- `studio_walkthrough_raw.webm`: the actual 1920 × 1080 browser viewport, **including real waits**.
+  It records neither browser chrome nor audio; do not rely on it to include the OS mouse cursor.
+  No fake cursor, replacement UI, simulated responses or accelerated preview are injected.
+- `input.*` and, when present, `input_provenance.json`: a retained upload and its adjacent source record.
+- `prepared.json`, `path_preview.json`, `warp_preview.json`: the normalized span, geometry, exact
+  edited keys, source-frame map and preview diagnostics. Preview-only runs do not claim a render payload.
+- `preview_truth.mp4`, `preview_holes.mp4`, numbered screenshots: reference footage and review stills.
+- With `nba-glide`, `subject_anchor.json`: the selected reconstructed torso point and its source projection.
+- `session.json`, `studio_served.html`: source/download hashes, served UI, request payloads and
+  client-observed wall-clock milestones. These timestamps are relative to script startup, **not exact
+  WebM edit points or an interactive-latency benchmark**.
+- With `--render`: `render_request.json`, `job.json`, and the matching `source.mp4`, `render.mp4`,
+  `out.mp4`, `grid.mp4`. `source.mp4` follows the authored source-time map; it is not the untouched input.
+
+The API does not expose checkpoint identities or the launch recipe. Retain the service launch command,
+checkpoint/adapter identifiers and server log separately. Also preserve the normalized upload from
+`<service --work>/clips/<clip>/clip.mp4` if an exact input archive is needed; `<clip>` is recorded in
+`prepared.json`. The script does not inspect the server filesystem or guess its configuration.
+
+For an MP4 viewing copy, without cutting waits or changing playback speed:
+
+```bash
+ffmpeg -n -i videos-all/studio_walkthrough/nba3_render_01/studio_walkthrough_raw.webm \
+  -c:v libx264 -crf 18 -pix_fmt yuv420p -movflags +faststart \
+  videos-all/studio_walkthrough/nba3_render_01/studio_walkthrough_review.mp4
+```
+
+Keep the raw recording. A 45-second research-page film is a **separate editorial pass**, following
+the outline below, with omitted waits disclosed. Use the downloaded full `out.mp4` for the cinematic
+reveal, not a screen-recorded crop of its small comparison pane. Do not publish a Studio-film link
+until the actual recording and generated motion have been reviewed.
+
+## The story
+
+**Design the observation. See the reference. Generate the shot.**
+
+One beautiful source, one deliberate camera path, one uninterrupted generated result. Show that the
+released Studio is an authoring tool—not only a gallery or a menu of orbit presets. The point is the
+relationship between an edit and its visible consequence, rather than a tour of every control.
+
+Place the film in the research article's Studio section, after the method and speed discussion.
+Keep the cinematic hero separate: the hero shows the result; this film explains how to author it.
+
+## Capture outline · approximately 45 seconds
+
+These are editorial allocations, **not measured service timings**. Extend the capture if an operation
+needs longer; do not speed up pointer movement or pretend the model generated instantaneously.
+
+| Passage | Actual screen action | Minimal caption |
+|---|---|---|
+| Establish · 0–4 s | Show the chosen source, then the actual Studio with a prepared source span. The source must remain identifiable. | One source. A new observation. |
+| Author · 4–16 s | Show the multi-key path, look through a key, Shift-drag sideways and adjust its aim. Keep the athlete and hoop legible; do not exaggerate the small travel. | Place the camera. Shape its path. |
+| Shape time · 16–23 s | Show two keys sharing a source frame at different output frames. Scrub across the hold and the subsequent advancing segment. | Hold the moment. Keep the camera moving. |
+| Inspect · 23–29 s | Let the genuine full-path warp finish. Play the grey-hole reference; briefly switch to the magenta diagnostic. Keep one actual edit-to-preview response at native speed. | Preview the geometry before generating. |
+| Generate · 29–32 s | Click **Render this take** and show the real progress screen. If waiting is cut, say so and report the retained run's elapsed time. | Generation wait omitted: [measured duration]. |
+| Reveal · 32–42.125 s | Play the matching 243-frame output intact at 24 fps, large and uncluttered. | Generated view. |
+| Close · about 3 s | End on the Studio's source / reference / output comparison or a quiet wordmark. | Meridian Studio · included in the code release. |
+
+The final take must be generated from **the exact Studio keys shown**. An existing CLI flower or
+motorcycle output is useful for choosing a scene, but is not evidence of an unexecuted Studio path.
+
+## Source and camera design
+
+**NBA3 is the current walkthrough source.** Its wide view makes the approach, airborne ball sweep,
+dunk and landing legible as one event. The retained 124-frame plate covers the full supplied clip;
+its frame 60 maps to original frame 73 / PTS 2.435767 s. See the
+[exact input preparation](../videos-all/nba3_teacher30/provenance.json). These are source-file
+timestamps, not a claim about physical capture speed. The footage is user-supplied; public
+redistribution rights and endorsement have not been established.
+
+The *Spring* flower scene remains an alternate, with Blender Foundation attribution and CC BY 4.0
+notice in [its input preparation](../videos-all/longtake_edit/plates/flowers_linger243.json).
+
+Use a source export appropriate for the Studio's **maximum 124-frame prepared window**. Do not claim
+the Studio reproduced a 243-source-frame CLI reconstruction; selecting a 243-frame *output* does
+not enlarge its prepared source window. Begin with a modest, well-framed path. Only increase travel
+after inspecting the projection—an impressive trajectory that loses the athlete is a worse demo.
+
+For a 124-frame prepared span starting at `start`, this **timing sketch** fits a 243-frame output:
+
+| Output index `t` | Source index | Camera intention, to tune in the actual scene |
+|---|---|---|
+| 0 | `start + 0` | Establish the source-side composition. |
+| 40 | `start + 40` | Follow the source framing with a small lateral offset. |
+| 60 | `start + 60` | Begin the time hold with breathing room around the subject. |
+| 105 | `start + 60` | Glide sideways while retaining the athlete. |
+| 145 | `start + 60` | Travel sideways, keeping the aim on the subject. |
+| 179 | `start + 60` | Ease back toward the source-side camera before action resumes. |
+| 242 | `start + 123` | Let the action advance again. |
+
+This uses all 124 prepared source frames and adds 119 held output frames. It preserves the prepared
+input's pace outside the hold; any slow motion already in that input remains baked in. The exact
+camera keys are saved with each recording. This table specifies intent, not a promise of seamless
+generated motion.
+
+## What “real-time preview” may honestly mean
+
+- **Browser 3D view:** a loaded point cloud and camera handles redraw during interaction. Capture
+  this normally; do not attach an FPS or latency claim without measuring it.
+- **Full-path geometric reference:** generated by the backend after a committed valid edit. This
+  requires GPU work and video encoding; it can wait behind other service work.
+- **Final generated video:** a separate render job. Never label its replay as a live model response.
+
+The point-cloud overview is not the full conditioning tensor. The grey-hole video is a compressed
+preview of that reference; the magenta view is diagnostic and is not given to the model.
+
+## Capture and acceptance checklist
+
+- Record the actual released `service/index.html`, not a UI mock or the `videos-all` gallery.
+- Arrange a dedicated service/GPU recording slot separately. Do not interrupt existing jobs to make
+  this recording. No service was started or render queued as part of this documentation update.
+- Capture at native 1920 × 1080 or another readable desktop size. Keep pointer motion deliberate;
+  show the key table when explaining source time. Avoid cinematic overlays on the actual output.
+- Retain the source export, normalized frame window, exact `/render` path payload, seed, model
+  recipe, output files and status timings alongside the raw capture. The UI has no path-export
+  button, so retain the request through browser network tools or the client used for the session.
+- Disclose omitted reconstruction/generation waits. Keep one representative edit-to-warp update
+  unaccelerated, including its real waiting time. Cold reconstruction is not interactive preview.
+- Check subject visibility, transitions into/out of the hold, thin geometry and newly exposed
+  backgrounds continuously. Sampled frames and successful playback alone are insufficient.
+- Confirm the generated take matches the recorded path and source map. Record any crops or omitted
+  output frames; the first choice is to keep the complete generated take intact.
+- Add source credits and transformation notices. Do not imply that a view inferred from a film is
+  documentary footage, or that a nominal orbit angle was measured in the generated output.
+
+Once recorded and reviewed, add a real poster and MP4 link to the research article. Until then,
+link this plan explicitly as a plan; no broken “Watch Studio” button or fabricated placeholder video.

docs/training.md

@@ -0,0 +1,46 @@
+# Training and distillation
+
+[← Meridian](../README.md) · [Inference method](method.md)
+
+Training provenance and design are collected here rather than in the model card or research blog.
+
+## Training overview
+
+The following is the release's training description; this repository contains inference code and
+artifacts, **not the training or distillation pipeline**.
+
+The teacher was trained on
+[MultiCamVideo](https://huggingface.co/datasets/KwaiVGI/MultiCamVideo-Dataset): 13,600 Unreal Engine
+scenes, each filmed by ten synchronized cameras over 81 frames. A sample pairs one camera's clip
+with a point-cloud render from a second camera; the second camera's actual clip is the target.
+Both directions of camera pairs are used, and geometry is reconstructed from the source clip alone.
+
+Later stages added still-frame references, temporally extended examples made by slowing, reversing,
+or holding the 81-frame window, and eased sweeps. The student was distilled at 73, 90, and 124 frames,
+with 243-frame holds also reported. Training-time temporal augmentation is not a promise that every
+time mapping or reverse-playback path is supported by the released interfaces.
+
+## Distillation and checkpoint design
+
+The release has two learned components:
+
+| Component | Role |
+|---|---|
+| `transformer/` | Fully finetuned MiniMax-H3 teacher: stock `fl2va` architecture, 50 layers, hidden size 5376; reported weight size 61.7 GiB in bf16. |
+| `lora/` | Rank-128 DMD student adapter on **that finetuned teacher**, reported size 2.5 GiB. It is not an adapter for the unmodified base transformer. |
+
+| Mode | CLI settings | Transformer evaluations |
+|---|---|---|
+| Student, default | `--steps 4 --flow-shift 3` with the LoRA loaded | 3 |
+| Teacher | `--no-lora --steps 50 --flow-shift 12` | 49 |
+
+The H3 scheduler counts the terminal zero-noise point in `--steps`. That endpoint does not require a
+model evaluation, hence four grid points produce three forwards. Reducing the teacher's step count
+is not equivalent to using the distilled student. Forward counts also do not directly translate to
+end-to-end speedups: reconstruction, warping, VAE work, and file writing still take time.
+
+The source and point-cloud-rendered references share the selected source timeline. Synchronized
+multi-camera supervision is followed by temporal and camera-path augmentation and student distillation.
+The training footage is synthetic; real-world performance depends on the scene.
+
+For weight provenance and modification notices, see [`MODIFICATIONS.md`](../MODIFICATIONS.md).

examples/CREDITS.md

@@ -0,0 +1,13 @@
+# Sample clips
+
+Both clips in `media/` are from Wikimedia Commons and were released by their uploaders under
+[CC0 1.0](https://creativecommons.org/publicdomain/zero/1.0/) (public domain dedication). We modified
+them: cut to a 73-frame window, scaled to 1280 × 720, re-encoded as H.264, soundtrack removed.
+
+| file | source | uploader | window |
+|---|---|---|---|
+| `sp_bouldering_hang.mp4` | [2020-11-28 - IFSC Euros - Combined M-B - Alex Khazanov - Video 3.webm](https://commons.wikimedia.org/wiki/File:2020-11-28_-_IFSC_Euros_-_Combined_M-B_-_Alex_Khazanov_-_Video_3.webm) | Voltmetro | from 9.5 s |
+| `sp_bouldering_reach.mp4` | [Anna Stohr JMM 2013 Annecy Bloc.webm](https://commons.wikimedia.org/wiki/File:Anna_Stohr_JMM_2013_Annecy_Bloc.webm) | Shev123 | from 13.75 s |
+
+Both show identifiable athletes at public competitions. The CC0 dedication covers the uploader's
+copyright, not the athletes' personality rights; the clips are here as technical demo inputs only.

examples/media/sp_bouldering_hang.mp4

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