Upload app.py

app.py

@@ -1644,6 +1644,104 @@ def _add_preset_lora(preset, *current):
 
 load_models()
 
+# ------------------------------------------------------------------------------------------------------------------
+# Structured prompt builder
+# ------------------------------------------------------------------------------------------------------------------
+# H3 was trained on the output of H3-Context-IR, a preprocessor that rewrites a plain request into labelled sections,
+# and MiniMax's own model card calls that structure "critical to the quality of the final output". Nothing in this
+# pipeline adds it: the string reaches the transformer as typed. So the builder writes the sections instead - the
+# shot description, the soundscape and the music, in the order and under the names the model was trained to read.
+#
+# Two details from the official guide are worth knowing, because getting them wrong looks like a model fault:
+# dialogue must be verbatim inside <d> tags or the mouth moves with no words in it, and reference tags have to
+# appear in the order the inputs were connected.
+
+IR_SHOT_TYPES = {
+    "(none)": "",
+    "live-action, cinematic": "Live-action, cinematic",
+    "live-action, documentary": "Live-action, documentary, handheld",
+    "studio portrait": "Live-action, studio portrait lighting",
+    "anime": "2D anime, crisp lineart",
+    "3D animation": "3D animation, stylised",
+}
+
+IR_CAMERA = {
+    "(none)": "",
+    "static": "The camera holds a static frame",
+    "slow push in": "The camera pushes in with small amplitude at slow speed",
+    "slow pull back": "The camera pulls back with small amplitude at slow speed",
+    "truck right": "The camera trucks right with small amplitude at slow speed",
+    "truck left": "The camera trucks left with small amplitude at slow speed",
+    "orbit": "The camera orbits the subject with medium amplitude at slow speed",
+    "handheld follow": "The camera follows handheld with small amplitude at moderate speed",
+    "tilt up": "The camera tilts up with small amplitude at slow speed",
+    "crane up and back": "The camera cranes up and back with large amplitude at slow speed",
+}
+
+IR_SOUNDSCAPE = {
+    "(none)": "",
+    "quiet room": "A quiet room tone with small incidental sounds - fabric, footsteps, a distant door.",
+    "rain and traffic": "Rain ticks against glass over the low hum of distant traffic.",
+    "outdoors, wind": "Wind moves through the scene, carrying faint birdsong and rustling leaves.",
+    "city street": "City ambience: passing cars, footsteps on pavement, indistinct voices further off.",
+    "interior, machinery": "A steady mechanical hum underneath, with occasional metallic ticks.",
+    "crowd": "A crowd murmurs at a middle distance, individual voices indistinct.",
+}
+
+IR_MUSIC = {
+    "(none)": "",
+    "no music": "None.",
+    "slow strings": "Sustained cello notes at a slow tempo with widely spaced piano tones.",
+    "warm piano": "A warm solo piano at a slow tempo, sparse and unhurried.",
+    "tense low drone": "A low synth drone with a slow rising tension.",
+    "upbeat electronic": "An upbeat electronic pulse at a moderate tempo.",
+}
+
+
+def build_ir_prompt(description, shot_type, camera, soundscape, music, speaker, dialogue,
+                    reference_count):
+    """Write the labelled sections H3 was trained on, around what the user typed."""
+    body = (description or "").strip().rstrip(".")
+    if not body:
+        raise gr.Error("Describe the shot first - the builder writes the structure around it.")
+
+    lines = []
+
+    # The reference line comes first, and names the pictures in connection order, which is what the
+    # model expects to match against its inputs.
+    count = int(reference_count or 0)
+    if count > 0:
+        tags = ", ".join(f"<Picture {index}>" for index in range(1, count + 1))
+        lines.append(
+            f"For the target video, at 0.00 seconds into the target video, {tags} "
+            f"(from [Shot 1]) {'is' if count == 1 else 'are'} fully referenced."
+        )
+        lines.append("")
+
+    shot = " ".join(part for part in (IR_SHOT_TYPES.get(shot_type, ""),) if part)
+    described = f"{shot}, {body}." if shot else f"{body}."
+    if count > 0:
+        described += (" The subject keeps the appearance shown in the reference images, and the "
+                      "setting keeps its layout.")
+    if IR_CAMERA.get(camera):
+        described += f" {IR_CAMERA[camera]}."
+
+    if (dialogue or "").strip():
+        who = (speaker or "S1").strip() or "S1"
+        spoken = dialogue.strip().strip('"')
+        # Delivery and identity go outside the tag; only the language and the verbatim words go in,
+        # otherwise the mouth moves correctly with nothing in it.
+        described += f" The speaker ({who}) says: <d>[English] {spoken}</d>"
+
+    lines.append(f"integrated_multimodal_description: [Shot 1] {described}")
+    lines.append("")
+    lines.append(f"overall_soundscape: {IR_SOUNDSCAPE.get(soundscape) or 'Ambient sound suited to the scene.'}")
+    lines.append("")
+    lines.append(f"non_diegetic_music: {IR_MUSIC.get(music) or 'None.'}")
+
+    return "\n".join(lines)
+
+
 CHIPS = [
     "cinematic lighting, shallow depth of field",
     "slow push in",
@@ -1817,7 +1915,7 @@ CSS = """
     border-radius: 14px !important;
     box-shadow: 0 8px 22px rgba(29, 78, 216, .25);
 }
-#search-btn, #search-put, #extend-btn, #lora-identify, #profile-refresh, #seed-dice, #turbo-btn, #profile-save, #profile-load, #profile-delete {
+#ir-btn, #search-btn, #search-put, #extend-btn, #lora-identify, #profile-refresh, #seed-dice, #turbo-btn, #profile-save, #profile-load, #profile-delete {
     min-height: 42px !important; border-radius: 12px !important; font-weight: 600 !important;
 }
 
@@ -1856,7 +1954,7 @@ HERO = """
   <a href="https://huggingface.co/spaces/multimodalart/minimax-h3" target="_blank" rel="noopener">text / image to video</a></p>
   <div class="pills">
     <span>33B</span><span>joint video + audio</span><span>Turbo lora: 4&ndash;8 steps</span>
-    <span>ComfyUI lora accepted</span><span>up to 9 references</span><span>5 custom lora slots</span><span>named profiles</span><span>CivitAI search + links</span><span>scene continuation</span><span>kohya + LoKr auto-convert</span><span>GPU cost estimate</span><span>clip stitching with audio</span>
+    <span>ComfyUI lora accepted</span><span>up to 9 references</span><span>5 custom lora slots</span><span>structured prompt builder</span><span>named profiles</span><span>CivitAI search + links</span><span>scene continuation</span><span>kohya + LoKr auto-convert</span><span>GPU cost estimate</span><span>clip stitching with audio</span>
   </div>
 </div>
 """
@@ -1918,6 +2016,33 @@ with gr.Blocks(title="MiniMax-H3 - Custom lora + CivitAI, GPU cost, profiles, cl
                     value="The character walks through a neon-lit street in the rain, humming to themselves",
                 )
                 upsample = gr.Checkbox(label="✨ Upsample prompt", value=False)
+                with gr.Accordion("🎬 Structured prompt builder (what H3 was trained on)", open=False):
+                    gr.Markdown(
+                        "H3 was trained on the output of a preprocessor that rewrites a request into labelled "
+                        "sections, and MiniMax call that structure *critical to the quality of the final output*. "
+                        "Nothing here adds it on its own — your text reaches the model as typed. Describe the shot "
+                        "in the prompt box above, set the pieces below, and press **Build**.\n\n"
+                        "**Dialogue has to be verbatim.** Speech is generated together with the picture, so naming "
+                        "that someone speaks without giving the words produces correct mouth shapes with nothing in "
+                        "them. Aim for 350–500 words of description for a full scene."
+                    )
+                    with gr.Row():
+                        ir_shot = gr.Dropdown(list(IR_SHOT_TYPES), value="live-action, cinematic",
+                                              label="Shot type")
+                        ir_camera = gr.Dropdown(list(IR_CAMERA), value="slow push in", label="Camera move")
+                    with gr.Row():
+                        ir_sound = gr.Dropdown(list(IR_SOUNDSCAPE), value="(none)", label="Soundscape")
+                        ir_music = gr.Dropdown(list(IR_MUSIC), value="no music", label="Music")
+                    with gr.Row():
+                        ir_speaker = gr.Textbox(value="S1", label="Speaker id", max_lines=1, scale=1)
+                        ir_dialogue = gr.Textbox(label="Dialogue, word for word", scale=4,
+                                                 placeholder="I get off at the next station.")
+                    ir_references = gr.Slider(0, MAX_IMAGE_SLOTS, value=1, step=1,
+                                              label="Reference images to name",
+                                              info="Named in connection order, as <Picture 1>, <Picture 2> …")
+                    ir_button = gr.Button("🎬 Build the structured prompt", variant="secondary",
+                                          elem_id="ir-btn")
+
                 with gr.Accordion("💡 Quick tags — click to add", open=False):
                     with gr.Row(elem_classes="chip-row"):
                         chip_buttons_a = [gr.Button(text, size="sm", variant="secondary") for text in CHIPS[:4]]
@@ -2254,6 +2379,13 @@ with gr.Blocks(title="MiniMax-H3 - Custom lora + CivitAI, GPU cost, profiles, cl
     # A CivitAI download link is a bare number, so the slots can be named from CivitAI's own public
     # model-versions endpoint: the title, the version, the file behind `fileId`, and the trigger words. Pressing
     # Enter in a slot names that set as well, so the button is only there for a paste that never gets an Enter.
+    ir_button.click(
+        build_ir_prompt,
+        [prompt, ir_shot, ir_camera, ir_sound, ir_music, ir_speaker, ir_dialogue, ir_references],
+        prompt,
+        api_name=False,
+    )
+
     lora_identify_btn.click(identify_loras, lora_references, lora_names, api_name=False)
     for _field in lora_references:
         _field.submit(identify_loras, lora_references, lora_names, api_name=False)