Upload 16 files

GravityLLM-Space-Demo/.gitignore

@@ -0,0 +1,6 @@
+__pycache__/
+*.pyc
+.DS_Store
+.env
+outputs/
+*.json.tmp

GravityLLM-Space-Demo/LICENSE

@@ -0,0 +1,47 @@
+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.
+
+"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.
+
+"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 patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work.
+
+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; 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.
+
+5. Submission of Contributions. Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work shall be under the terms and conditions of this License.
+
+6. Trademarks. This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor.
+
+7. Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, Licensor provides the Work on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+
+8. Limitation of Liability. In no event and under no legal theory shall any Contributor be liable to You for damages arising from the use of the Work.
+
+9. Accepting Warranty or Additional Liability. While redistributing the Work or Derivative Works thereof, You may choose to offer support or warranty protection only on Your own behalf.

GravityLLM-Space-Demo/README.md

@@ -0,0 +1,70 @@
+---
+title: GravityLLM Studio
+emoji: 🌌
+colorFrom: blue
+colorTo: indigo
+sdk: gradio
+sdk_version: 6.8.0
+python_version: "3.10"
+app_file: app.py
+fullWidth: true
+header: default
+suggested_hardware: cpu-basic
+short_description: Spatial9 immersive scene generation with branded GravityLLM UI, schema validation, and spatial preview.
+tags:
+- gravityllm
+- spatial-audio
+- immersive-audio
+- spatial9
+- iamf
+- gradio
+- json
+- demo
+- music-tech
+---
+
+![GravityLLM banner](assets/gravityllm_space_banner.png)
+
+# GravityLLM Studio
+
+A branded Hugging Face Space for **constraint-conditioned immersive scene generation**.
+
+This Space accepts a **music-constraint payload** and returns a **Spatial9Scene JSON** scene. It includes:
+
+- a polished GravityLLM studio UI
+- your Spatial9 logo in the hero section
+- remote inference through Hugging Face `InferenceClient`
+- optional JSON-schema grammar constraints
+- built-in validation against `schemas/scene.schema.json`
+- a live top-down spatial preview
+- a deterministic fallback rules engine so the demo still works before the trained model is online
+
+## How to connect your model
+
+Set the following Space secrets or variables:
+
+- `GRAVITYLLM_MODEL_ID` → your model repo id, for example `your-org/GravityLLM-AutoPosition`
+- `HF_TOKEN` → only required if the model is gated or private
+- `GRAVITYLLM_BACKEND` → optional default: `hybrid`, `remote-model`, or `rules-engine demo`
+
+## Files
+
+- `app.py` — the Gradio app
+- `schemas/scene.schema.json` — the contract used for validation and optional grammar guidance
+- `examples/` — ready-to-run sample payloads
+- `assets/` — logo and banner assets
+- `utils/scene_tools.py` — validation, heuristics, JSON extraction, plotting
+
+## Recommended workflow
+
+1. Upload your GravityLLM **Model repo**
+2. Train and push the final weights
+3. Upload this **Space repo**
+4. Set `GRAVITYLLM_MODEL_ID`
+5. Launch the Space
+
+## Notes
+
+This Space is designed to be usable in two states:
+- **before model launch** → rules-engine fallback
+- **after model launch** → remote GravityLLM inference

GravityLLM-Space-Demo/app.py

@@ -0,0 +1,437 @@
+from __future__ import annotations
+
+import base64
+import json
+import os
+import tempfile
+from pathlib import Path
+from typing import Any, Dict
+
+import gradio as gr
+from huggingface_hub import InferenceClient
+from huggingface_hub.errors import HfHubHTTPError, InferenceTimeoutError
+
+from utils.scene_tools import (
+    SCHEMA,
+    extract_first_json_block,
+    heuristic_scene,
+    parse_json_text,
+    plot_scene,
+    scene_markdown,
+    scene_table,
+    validate_scene,
+)
+
+ROOT = Path(__file__).resolve().parent
+ASSETS = ROOT / "assets"
+EXAMPLES = ROOT / "examples"
+
+APP_TITLE = "GravityLLM"
+DEFAULT_MODEL_ID = os.getenv("GRAVITYLLM_MODEL_ID", "your-namespace/GravityLLM-AutoPosition")
+DEFAULT_BACKEND = os.getenv("GRAVITYLLM_BACKEND", "hybrid")
+HF_TOKEN = os.getenv("HF_TOKEN") or os.getenv("HUGGINGFACEHUB_API_TOKEN")
+
+SYSTEM_PREFIX = (
+    "You are GravityLLM (Spatial9 AutoPosition SLM). "
+    "Generate ONLY valid JSON matching the Spatial9Scene schema. "
+    "No markdown. No explanation. No code fences.\n\n"
+)
+
+EXAMPLE_FILES = {
+    "Club Drop": EXAMPLES / "club_drop.json",
+    "Cinematic Break": EXAMPLES / "cinematic_break.json",
+    "Podcast Voice": EXAMPLES / "podcast_voice.json",
+}
+
+
+def logo_data_uri() -> str:
+    logo_bytes = (ASSETS / "spatial9_logo.png").read_bytes()
+    return "data:image/png;base64," + base64.b64encode(logo_bytes).decode("utf-8")
+
+
+def load_example(name: str) -> str:
+    path = EXAMPLE_FILES.get(name, next(iter(EXAMPLE_FILES.values())))
+    return path.read_text(encoding="utf-8")
+
+
+def build_prompt(payload: Dict[str, Any]) -> str:
+    return SYSTEM_PREFIX + "INPUT:\n" + json.dumps(payload, ensure_ascii=False, indent=2) + "\nOUTPUT:\n"
+
+
+def remote_generate(
+    payload: Dict[str, Any],
+    model_id: str,
+    temperature: float,
+    top_p: float,
+    max_new_tokens: int,
+    use_grammar: bool,
+) -> tuple[Dict[str, Any], str]:
+    prompt = build_prompt(payload)
+    client = InferenceClient(model=model_id, token=HF_TOKEN)
+
+    call_kwargs = dict(
+        prompt=prompt,
+        model=model_id,
+        max_new_tokens=max_new_tokens,
+        temperature=temperature,
+        top_p=top_p,
+        repetition_penalty=1.05,
+        return_full_text=False,
+    )
+    if use_grammar:
+        call_kwargs["grammar"] = {"type": "json", "value": SCHEMA}
+
+    try:
+        response = client.text_generation(**call_kwargs)
+        scene = parse_json_text(response)
+        return scene, f"remote-model ({model_id})"
+    except Exception as first_error:
+        if use_grammar:
+            try:
+                call_kwargs.pop("grammar", None)
+                response = client.text_generation(**call_kwargs)
+                scene = parse_json_text(response)
+                return scene, f"remote-model ({model_id}, grammar-fallback)"
+            except Exception as second_error:
+                raise RuntimeError(f"{type(first_error).__name__}: {first_error}\n\nFallback: {type(second_error).__name__}: {second_error}") from second_error
+        raise
+
+
+def write_download_file(scene: Dict[str, Any]) -> str:
+    fd, path = tempfile.mkstemp(prefix="gravityllm_scene_", suffix=".json")
+    os.close(fd)
+    Path(path).write_text(json.dumps(scene, ensure_ascii=False, indent=2), encoding="utf-8")
+    return path
+
+
+def generate_scene(
+    payload_text: str,
+    model_id: str,
+    backend: str,
+    temperature: float,
+    top_p: float,
+    max_new_tokens: int,
+    use_grammar: bool,
+):
+    try:
+        payload = parse_json_text(payload_text)
+    except Exception as exc:
+        msg = f"### Invalid input JSON\n\n- {type(exc).__name__}: {exc}"
+        return "", msg, None, [], None, "Fix the input JSON and try again."
+
+    backend = backend or DEFAULT_BACKEND
+    model_id = model_id.strip() or DEFAULT_MODEL_ID
+
+    scene = None
+    backend_used = "rules-engine demo"
+    status = "Scene generated."
+
+    if backend in {"remote-model", "hybrid"}:
+        try:
+            scene, backend_used = remote_generate(payload, model_id, temperature, top_p, max_new_tokens, use_grammar)
+            status = f"Generated from remote model: {model_id}"
+        except (InferenceTimeoutError, HfHubHTTPError, RuntimeError, ValueError, json.JSONDecodeError) as exc:
+            if backend == "remote-model":
+                msg = f"### Remote generation failed\n\n- {type(exc).__name__}: {exc}"
+                return "", msg, None, [], None, "Remote inference failed."
+            scene = heuristic_scene(payload)
+            backend_used = "rules-engine demo (remote fallback)"
+            status = f"Remote generation failed; heuristic fallback used. Details: {type(exc).__name__}: {exc}"
+
+    if scene is None:
+        scene = heuristic_scene(payload)
+
+    valid, errors = validate_scene(scene)
+    download_path = write_download_file(scene)
+    figure = plot_scene(scene)
+    table = scene_table(scene)
+    summary = scene_markdown(scene, valid, errors, backend_used)
+    return json.dumps(scene, ensure_ascii=False, indent=2), summary, figure, table, download_path, status
+
+
+def validate_only(scene_text: str):
+    try:
+        scene = parse_json_text(scene_text)
+    except Exception as exc:
+        return f"### Invalid scene JSON\n\n- {type(exc).__name__}: {exc}", None, []
+    valid, errors = validate_scene(scene)
+    summary = scene_markdown(scene, valid, errors, "manual validation")
+    return summary, plot_scene(scene), scene_table(scene)
+
+
+def build_payload(target_format, style, section, bpm, energy, max_objects):
+    payload = {
+        "target_format": target_format,
+        "max_objects": int(max_objects),
+        "style": style,
+        "section": section,
+        "global": {"bpm": int(bpm), "energy": float(energy)},
+        "stems": [
+            {"id": "lead", "class": "lead_vocal", "lufs": -17.0, "transient": 0.25, "band_energy": {"low": 0.08, "mid": 0.67, "high": 0.25}, "leadness": 0.96},
+            {"id": "kick", "class": "kick", "lufs": -10.6, "transient": 0.96, "band_energy": {"low": 0.82, "mid": 0.12, "high": 0.06}, "leadness": 0.22},
+            {"id": "bass", "class": "bass", "lufs": -12.5, "transient": 0.58, "band_energy": {"low": 0.86, "mid": 0.10, "high": 0.04}, "leadness": 0.30},
+            {"id": "pad", "class": "pad", "lufs": -21.5, "transient": 0.05, "band_energy": {"low": 0.20, "mid": 0.50, "high": 0.30}, "leadness": 0.08},
+            {"id": "fx", "class": "fx", "lufs": -24.0, "transient": 0.22, "band_energy": {"low": 0.10, "mid": 0.24, "high": 0.66}, "leadness": 0.04},
+        ],
+        "rules": [
+            {"type": "anchor", "track_class": "lead_vocal", "az_deg": 0, "el_deg": 10, "dist_m": 1.6},
+            {"type": "mono_low_end", "hz_below": 120},
+            {"type": "width_pref", "track_class": "pad", "min_width": 0.75},
+        ],
+    }
+    return json.dumps(payload, ensure_ascii=False, indent=2)
+
+
+hero_html = f"""
+<div class="hero-wrap">
+  <div class="hero-left">
+    <div class="hero-logo-card">
+      <img class="hero-logo" src="{logo_data_uri()}" alt="Spatial9 logo"/>
+    </div>
+  </div>
+  <div class="hero-right">
+    <div class="eyebrow">SPATIAL9 • HUGGING FACE SPACE</div>
+    <h1>GravityLLM Studio</h1>
+    <p class="hero-copy">
+      Constraint-conditioned immersive scene generation with schema-guided JSON output,
+      remote Hugging Face inference, heuristic fallback, and a live spatial preview.
+    </p>
+    <div class="hero-chips">
+      <span>IAMF Ready</span>
+      <span>Schema Validated</span>
+      <span>Spatial Preview</span>
+      <span>Branded Demo</span>
+    </div>
+  </div>
+</div>
+"""
+
+css = """
+:root {
+  --g-bg: #f6f9ff;
+  --g-panel: rgba(255,255,255,0.86);
+  --g-panel-strong: rgba(255,255,255,0.96);
+  --g-line: #dbe7f6;
+  --g-ink: #15233d;
+  --g-sub: #5f728f;
+  --g-accent: #1f6fe5;
+  --g-accent-2: #0f9bb9;
+}
+.gradio-container {
+  background:
+    radial-gradient(circle at top left, rgba(55,120,246,0.10), transparent 32%),
+    radial-gradient(circle at bottom right, rgba(15,155,185,0.10), transparent 28%),
+    var(--g-bg);
+}
+.hero-wrap {
+  display: grid;
+  grid-template-columns: 280px 1fr;
+  gap: 28px;
+  padding: 22px 8px 12px 8px;
+  align-items: center;
+}
+.hero-logo-card {
+  background: linear-gradient(180deg, rgba(255,255,255,0.96), rgba(247,250,255,0.90));
+  border: 1px solid var(--g-line);
+  box-shadow: 0 18px 42px rgba(31,58,114,0.08);
+  border-radius: 28px;
+  padding: 24px;
+  display: flex;
+  justify-content: center;
+  align-items: center;
+  min-height: 170px;
+}
+.hero-logo {
+  width: 100%;
+  max-width: 220px;
+  object-fit: contain;
+}
+.hero-right h1 {
+  font-size: 2.5rem;
+  margin: 0;
+  color: var(--g-ink);
+}
+.hero-copy {
+  color: var(--g-sub);
+  font-size: 1.06rem;
+  line-height: 1.6;
+  max-width: 780px;
+}
+.eyebrow {
+  color: var(--g-accent);
+  font-size: 0.92rem;
+  letter-spacing: 0.14em;
+  font-weight: 700;
+  margin-bottom: 8px;
+}
+.hero-chips {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 10px;
+  margin-top: 14px;
+}
+.hero-chips span {
+  background: rgba(239,246,255,0.96);
+  border: 1px solid #cfe0fb;
+  color: #28558f;
+  border-radius: 999px;
+  padding: 8px 12px;
+  font-size: 0.9rem;
+  font-weight: 600;
+}
+.card-note {
+  color: var(--g-sub);
+}
+.block-panel {
+  background: var(--g-panel);
+  border: 1px solid var(--g-line);
+  border-radius: 22px;
+  padding: 10px;
+}
+footer {visibility: hidden;}
+@media (max-width: 900px) {
+  .hero-wrap {grid-template-columns: 1fr;}
+}
+"""
+
+with gr.Blocks(
+    title=f"{APP_TITLE} Studio",
+    fill_width=True,
+    css=css,
+    theme=gr.themes.Soft(
+        primary_hue="blue",
+        secondary_hue="cyan",
+        neutral_hue="slate",
+        radius_size="lg",
+    ),
+) as demo:
+    gr.HTML(hero_html)
+
+    with gr.Tabs():
+        with gr.Tab("GravityLLM Studio"):
+            with gr.Row():
+                with gr.Column(scale=11):
+                    example_name = gr.Dropdown(
+                        choices=list(EXAMPLE_FILES.keys()),
+                        value="Club Drop",
+                        label="Example payload",
+                    )
+                    load_btn = gr.Button("Load Example", variant="secondary")
+                    payload_box = gr.Code(
+                        value=load_example("Club Drop"),
+                        language="json",
+                        label="Constraint + stem feature payload",
+                        lines=26,
+                    )
+
+                with gr.Column(scale=6):
+                    model_id = gr.Textbox(
+                        value=DEFAULT_MODEL_ID,
+                        label="Model repo or endpoint",
+                        info="Set your Hugging Face model repo id or inference endpoint URL.",
+                    )
+                    backend = gr.Dropdown(
+                        choices=["hybrid", "remote-model", "rules-engine demo"],
+                        value=DEFAULT_BACKEND if DEFAULT_BACKEND in {"hybrid", "remote-model", "rules-engine demo"} else "hybrid",
+                        label="Backend",
+                    )
+                    temperature = gr.Slider(0.0, 1.2, value=0.2, step=0.05, label="Temperature")
+                    top_p = gr.Slider(0.1, 1.0, value=0.9, step=0.05, label="Top-p")
+                    max_new_tokens = gr.Slider(128, 1400, value=900, step=16, label="Max new tokens")
+                    use_grammar = gr.Checkbox(
+                        value=True,
+                        label="Use JSON schema grammar when remote backend supports it",
+                    )
+                    run_btn = gr.Button("Generate Spatial Scene", variant="primary")
+                    status = gr.Textbox(label="Status", interactive=False)
+
+            with gr.Row():
+                with gr.Column(scale=9):
+                    output_box = gr.Code(language="json", label="Generated Spatial9Scene JSON", lines=26)
+                    download = gr.File(label="Download scene JSON")
+                with gr.Column(scale=7):
+                    summary = gr.Markdown("### Ready\n\nLoad an example or paste your own payload.")
+                    plot = gr.Plot(label="Spatial scene preview")
+
+            object_table = gr.Dataframe(
+                headers=["id", "class", "az_deg", "el_deg", "dist_m", "width", "gain_db"],
+                datatype=["str", "str", "number", "number", "number", "number", "number"],
+                row_count=(0, "dynamic"),
+                col_count=(7, "fixed"),
+                label="Object inspector",
+            )
+
+        with gr.Tab("Prompt Builder"):
+            gr.Markdown("Build a starter payload, then send it to GravityLLM Studio.")
+            with gr.Row():
+                target_format = gr.Dropdown(["iamf", "binaural", "5.1.4", "7.1.4"], value="iamf", label="Target format")
+                style = gr.Dropdown(["club", "cinematic", "podcast", "live", "intimate"], value="club", label="Style")
+                section = gr.Dropdown(["intro", "verse", "break", "drop", "full"], value="drop", label="Section")
+            with gr.Row():
+                bpm = gr.Slider(0, 200, value=128, step=1, label="BPM")
+                energy = gr.Slider(0.0, 1.0, value=0.92, step=0.01, label="Energy")
+                max_objects_builder = gr.Slider(1, 32, value=10, step=1, label="Max objects")
+            build_btn = gr.Button("Build Payload", variant="primary")
+            builder_output = gr.Code(language="json", label="Starter payload", lines=24)
+            send_to_studio_btn = gr.Button("Send to Studio", variant="secondary")
+
+        with gr.Tab("Validate Existing Scene"):
+            scene_input = gr.Code(language="json", label="Paste a Spatial9Scene JSON", lines=24)
+            validate_btn = gr.Button("Validate Scene", variant="primary")
+            validate_summary = gr.Markdown()
+            validate_plot = gr.Plot()
+            validate_table = gr.Dataframe(
+                headers=["id", "class", "az_deg", "el_deg", "dist_m", "width", "gain_db"],
+                datatype=["str", "str", "number", "number", "number", "number", "number"],
+                row_count=(0, "dynamic"),
+                col_count=(7, "fixed"),
+                label="Validated object inspector",
+            )
+
+        with gr.Tab("About"):
+            gr.Image(value=str(ASSETS / "gravityllm_space_banner.png"), label="GravityLLM banner", show_download_button=False, show_fullscreen_button=False)
+            gr.Markdown(
+                """
+### What this Space does
+
+- Turns **constraints + stem descriptors** into **Spatial9Scene JSON**
+- Can call a remote Hugging Face model repo through `InferenceClient`
+- Falls back to a deterministic **rules engine** so the demo stays usable
+- Validates outputs against the included JSON schema
+- Renders a spatial top-down preview of object positions
+
+### Environment variables
+
+- `GRAVITYLLM_MODEL_ID` — model repo id or endpoint URL
+- `HF_TOKEN` — required if the model is gated or private
+- `GRAVITYLLM_BACKEND` — optional default: `hybrid`, `remote-model`, or `rules-engine demo`
+
+### Recommended setup
+
+1. Upload your GravityLLM model repo.
+2. Train and push weights.
+3. Upload this Space repo.
+4. Set `GRAVITYLLM_MODEL_ID` in the Space settings.
+                """
+            )
+
+    load_btn.click(fn=load_example, inputs=example_name, outputs=payload_box)
+    build_btn.click(
+        fn=build_payload,
+        inputs=[target_format, style, section, bpm, energy, max_objects_builder],
+        outputs=builder_output,
+    )
+    send_to_studio_btn.click(fn=lambda x: x, inputs=builder_output, outputs=payload_box)
+    run_btn.click(
+        fn=generate_scene,
+        inputs=[payload_box, model_id, backend, temperature, top_p, max_new_tokens, use_grammar],
+        outputs=[output_box, summary, plot, object_table, download, status],
+    )
+    validate_btn.click(
+        fn=validate_only,
+        inputs=scene_input,
+        outputs=[validate_summary, validate_plot, validate_table],
+    )
+
+if __name__ == "__main__":
+    demo.launch()

GravityLLM-Space-Demo/examples/cinematic_break.json

@@ -0,0 +1,81 @@
+{
+  "target_format": "iamf",
+  "max_objects": 8,
+  "style": "cinematic",
+  "section": "break",
+  "global": {
+    "bpm": 90,
+    "energy": 0.45
+  },
+  "stems": [
+    {
+      "id": "d1",
+      "class": "dialogue",
+      "lufs": -18.0,
+      "transient": 0.35,
+      "band_energy": {
+        "low": 0.05,
+        "mid": 0.75,
+        "high": 0.2
+      },
+      "leadness": 0.98
+    },
+    {
+      "id": "p1",
+      "class": "pad",
+      "lufs": -24.0,
+      "transient": 0.05,
+      "band_energy": {
+        "low": 0.25,
+        "mid": 0.55,
+        "high": 0.2
+      },
+      "leadness": 0.1
+    },
+    {
+      "id": "fx1",
+      "class": "fx",
+      "lufs": -26.0,
+      "transient": 0.15,
+      "band_energy": {
+        "low": 0.1,
+        "mid": 0.25,
+        "high": 0.65
+      },
+      "leadness": 0.05
+    },
+    {
+      "id": "a1",
+      "class": "ambience",
+      "lufs": -28.0,
+      "transient": 0.03,
+      "band_energy": {
+        "low": 0.15,
+        "mid": 0.55,
+        "high": 0.3
+      },
+      "leadness": 0.02
+    }
+  ],
+  "rules": [
+    {
+      "type": "anchor",
+      "track_class": "dialogue",
+      "az_deg": 0,
+      "el_deg": 5,
+      "dist_m": 1.8
+    },
+    {
+      "type": "keep_dialogue_clear",
+      "band_hz": [
+        1000,
+        4000
+      ]
+    },
+    {
+      "type": "width_pref",
+      "track_class": "pad",
+      "min_width": 0.8
+    }
+  ]
+}

GravityLLM-Space-Demo/examples/club_drop.json

@@ -0,0 +1,110 @@
+{
+  "target_format": "iamf",
+  "max_objects": 10,
+  "style": "club",
+  "section": "drop",
+  "global": {
+    "bpm": 128,
+    "energy": 0.92
+  },
+  "stems": [
+    {
+      "id": "v1",
+      "class": "lead_vocal",
+      "lufs": -16.8,
+      "transient": 0.25,
+      "band_energy": {
+        "low": 0.1,
+        "mid": 0.6,
+        "high": 0.3
+      },
+      "leadness": 0.95
+    },
+    {
+      "id": "k1",
+      "class": "kick",
+      "lufs": -10.5,
+      "transient": 0.95,
+      "band_energy": {
+        "low": 0.8,
+        "mid": 0.15,
+        "high": 0.05
+      },
+      "leadness": 0.25
+    },
+    {
+      "id": "b1",
+      "class": "bass",
+      "lufs": -12.2,
+      "transient": 0.55,
+      "band_energy": {
+        "low": 0.85,
+        "mid": 0.12,
+        "high": 0.03
+      },
+      "leadness": 0.35
+    },
+    {
+      "id": "p1",
+      "class": "pad",
+      "lufs": -20.3,
+      "transient": 0.1,
+      "band_energy": {
+        "low": 0.2,
+        "mid": 0.5,
+        "high": 0.3
+      },
+      "leadness": 0.1
+    },
+    {
+      "id": "s1",
+      "class": "synth_lead",
+      "lufs": -18.0,
+      "transient": 0.4,
+      "band_energy": {
+        "low": 0.1,
+        "mid": 0.55,
+        "high": 0.35
+      },
+      "leadness": 0.75
+    },
+    {
+      "id": "fx1",
+      "class": "fx",
+      "lufs": -23.0,
+      "transient": 0.2,
+      "band_energy": {
+        "low": 0.1,
+        "mid": 0.3,
+        "high": 0.6
+      },
+      "leadness": 0.05
+    }
+  ],
+  "rules": [
+    {
+      "type": "anchor",
+      "track_class": "lead_vocal",
+      "az_deg": 0,
+      "el_deg": 10,
+      "dist_m": 1.6
+    },
+    {
+      "type": "mono_low_end",
+      "hz_below": 120
+    },
+    {
+      "type": "width_pref",
+      "track_class": "pad",
+      "min_width": 0.75
+    },
+    {
+      "type": "avoid_band_masking",
+      "mask_target": "lead_vocal",
+      "band_hz": [
+        1500,
+        4500
+      ]
+    }
+  ]
+}

GravityLLM-Space-Demo/examples/podcast_voice.json

@@ -0,0 +1,81 @@
+{
+  "target_format": "binaural",
+  "max_objects": 5,
+  "style": "podcast",
+  "section": "full",
+  "global": {
+    "bpm": 0,
+    "energy": 0.28
+  },
+  "stems": [
+    {
+      "id": "host",
+      "class": "dialogue",
+      "lufs": -18.5,
+      "transient": 0.22,
+      "band_energy": {
+        "low": 0.12,
+        "mid": 0.7,
+        "high": 0.18
+      },
+      "leadness": 0.97
+    },
+    {
+      "id": "guest",
+      "class": "back_vocal",
+      "lufs": -19.8,
+      "transient": 0.18,
+      "band_energy": {
+        "low": 0.1,
+        "mid": 0.68,
+        "high": 0.22
+      },
+      "leadness": 0.82
+    },
+    {
+      "id": "bed",
+      "class": "pad",
+      "lufs": -29.0,
+      "transient": 0.02,
+      "band_energy": {
+        "low": 0.18,
+        "mid": 0.52,
+        "high": 0.3
+      },
+      "leadness": 0.04
+    },
+    {
+      "id": "stinger",
+      "class": "fx",
+      "lufs": -25.5,
+      "transient": 0.3,
+      "band_energy": {
+        "low": 0.05,
+        "mid": 0.25,
+        "high": 0.7
+      },
+      "leadness": 0.08
+    }
+  ],
+  "rules": [
+    {
+      "type": "anchor",
+      "track_class": "dialogue",
+      "az_deg": 0,
+      "el_deg": 4,
+      "dist_m": 1.4
+    },
+    {
+      "type": "width_pref",
+      "track_class": "pad",
+      "min_width": 0.7
+    },
+    {
+      "type": "keep_dialogue_clear",
+      "band_hz": [
+        1200,
+        3800
+      ]
+    }
+  ]
+}

GravityLLM-Space-Demo/requirements.txt

@@ -0,0 +1,5 @@
+gradio>=6.8.0,<7
+huggingface_hub>=1.5.0
+jsonschema>=4.23.0
+matplotlib>=3.8.0
+Pillow>=10.0.0

GravityLLM-Space-Demo/schemas/scene.schema.json

@@ -0,0 +1,169 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Spatial9Scene",
+  "type": "object",
+  "required": [
+    "version",
+    "bed",
+    "objects",
+    "constraints_applied"
+  ],
+  "properties": {
+    "version": {
+      "type": "string"
+    },
+    "bed": {
+      "type": "object",
+      "required": [
+        "layout",
+        "loudness_target_lufs",
+        "room_preset"
+      ],
+      "properties": {
+        "layout": {
+          "type": "string",
+          "enum": [
+            "binaural",
+            "5.1.4",
+            "7.1.4",
+            "iamf"
+          ]
+        },
+        "loudness_target_lufs": {
+          "type": "number"
+        },
+        "room_preset": {
+          "type": "string"
+        }
+      },
+      "additionalProperties": false
+    },
+    "objects": {
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 32,
+      "items": {
+        "type": "object",
+        "required": [
+          "id",
+          "class",
+          "az_deg",
+          "el_deg",
+          "dist_m",
+          "width",
+          "gain_db",
+          "reverb_send",
+          "early_reflections",
+          "motion"
+        ],
+        "properties": {
+          "id": {
+            "type": "string"
+          },
+          "class": {
+            "type": "string",
+            "enum": [
+              "lead_vocal",
+              "back_vocal",
+              "kick",
+              "snare",
+              "hihat",
+              "bass",
+              "drums_bus",
+              "pad",
+              "synth_lead",
+              "guitar",
+              "piano",
+              "strings",
+              "brass",
+              "fx",
+              "dialogue",
+              "ambience",
+              "other"
+            ]
+          },
+          "az_deg": {
+            "type": "number",
+            "minimum": -180,
+            "maximum": 180
+          },
+          "el_deg": {
+            "type": "number",
+            "minimum": -45,
+            "maximum": 90
+          },
+          "dist_m": {
+            "type": "number",
+            "minimum": 0.5,
+            "maximum": 15.0
+          },
+          "width": {
+            "type": "number",
+            "minimum": 0.0,
+            "maximum": 1.0
+          },
+          "gain_db": {
+            "type": "number",
+            "minimum": -60,
+            "maximum": 12
+          },
+          "reverb_send": {
+            "type": "number",
+            "minimum": 0.0,
+            "maximum": 1.0
+          },
+          "early_reflections": {
+            "type": "number",
+            "minimum": 0.0,
+            "maximum": 1.0
+          },
+          "motion": {
+            "type": "array",
+            "maxItems": 64,
+            "items": {
+              "type": "object",
+              "required": [
+                "t",
+                "az_deg",
+                "el_deg",
+                "dist_m"
+              ],
+              "properties": {
+                "t": {
+                  "type": "number",
+                  "minimum": 0.0,
+                  "maximum": 1.0
+                },
+                "az_deg": {
+                  "type": "number",
+                  "minimum": -180,
+                  "maximum": 180
+                },
+                "el_deg": {
+                  "type": "number",
+                  "minimum": -45,
+                  "maximum": 90
+                },
+                "dist_m": {
+                  "type": "number",
+                  "minimum": 0.5,
+                  "maximum": 15.0
+                }
+              },
+              "additionalProperties": false
+            }
+          }
+        },
+        "additionalProperties": false
+      }
+    },
+    "constraints_applied": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "maxItems": 64
+    }
+  },
+  "additionalProperties": false
+}

GravityLLM-Space-Demo/utils/scene_tools.py

@@ -0,0 +1,307 @@
+from __future__ import annotations
+
+import json
+import math
+import re
+from pathlib import Path
+from typing import Any, Dict, List, Tuple
+
+import matplotlib.pyplot as plt
+from jsonschema import Draft7Validator
+
+
+SCHEMA_PATH = Path(__file__).resolve().parents[1] / "schemas" / "scene.schema.json"
+SCHEMA: Dict[str, Any] = json.loads(SCHEMA_PATH.read_text(encoding="utf-8"))
+VALIDATOR = Draft7Validator(SCHEMA)
+
+CLASS_DEFAULTS = {
+    "lead_vocal": {"az": 0, "el": 10, "dist": 1.6, "width": 0.15, "gain": 0.0, "rev": 0.18, "er": 0.22},
+    "dialogue": {"az": 0, "el": 5, "dist": 1.5, "width": 0.10, "gain": 0.0, "rev": 0.08, "er": 0.18},
+    "back_vocal": {"az": -18, "el": 8, "dist": 1.9, "width": 0.25, "gain": -1.2, "rev": 0.16, "er": 0.16},
+    "kick": {"az": 0, "el": 0, "dist": 2.2, "width": 0.0, "gain": 0.0, "rev": 0.02, "er": 0.05},
+    "snare": {"az": 8, "el": 4, "dist": 2.4, "width": 0.1, "gain": -0.3, "rev": 0.05, "er": 0.07},
+    "hihat": {"az": 22, "el": 7, "dist": 2.7, "width": 0.18, "gain": -1.0, "rev": 0.06, "er": 0.08},
+    "bass": {"az": 0, "el": -5, "dist": 2.6, "width": 0.05, "gain": -0.5, "rev": 0.03, "er": 0.06},
+    "drums_bus": {"az": 0, "el": 2, "dist": 2.8, "width": 0.25, "gain": -0.6, "rev": 0.08, "er": 0.10},
+    "pad": {"az": -70, "el": 18, "dist": 4.8, "width": 0.82, "gain": -4.0, "rev": 0.28, "er": 0.12},
+    "synth_lead": {"az": 24, "el": 15, "dist": 2.0, "width": 0.35, "gain": -1.0, "rev": 0.12, "er": 0.10},
+    "guitar": {"az": -28, "el": 10, "dist": 2.8, "width": 0.28, "gain": -1.5, "rev": 0.09, "er": 0.11},
+    "piano": {"az": -14, "el": 8, "dist": 2.6, "width": 0.34, "gain": -1.5, "rev": 0.09, "er": 0.10},
+    "fx": {"az": 105, "el": 28, "dist": 6.2, "width": 0.66, "gain": -7.0, "rev": 0.42, "er": 0.08},
+    "ambience": {"az": -120, "el": 15, "dist": 8.0, "width": 0.90, "gain": -8.0, "rev": 0.55, "er": 0.10},
+    "other": {"az": 0, "el": 8, "dist": 3.0, "width": 0.25, "gain": -2.0, "rev": 0.10, "er": 0.10},
+}
+
+SPATIAL_CLASSES = list(CLASS_DEFAULTS)
+
+
+def clip(value: float, lo: float, hi: float) -> float:
+    return max(lo, min(hi, value))
+
+
+def extract_first_json_block(text: str) -> str:
+    match = re.search(r"\{.*\}", text, flags=re.DOTALL)
+    return match.group(0).strip() if match else text.strip()
+
+
+def parse_json_text(text: str) -> Dict[str, Any]:
+    return json.loads(extract_first_json_block(text))
+
+
+def validate_scene(scene: Dict[str, Any]) -> Tuple[bool, List[str]]:
+    errors = sorted(VALIDATOR.iter_errors(scene), key=lambda e: list(e.path))
+    if not errors:
+        return True, []
+    messages = []
+    for err in errors[:50]:
+        path = ".".join(str(x) for x in err.path)
+        messages.append(f"{path or '<root>'}: {err.message}")
+    return False, messages
+
+
+def make_motion(az: float, el: float, dist: float, sweep: float = 0.0) -> List[Dict[str, float]]:
+    if abs(sweep) < 0.001:
+        return [
+            {"t": 0.0, "az_deg": round(az, 2), "el_deg": round(el, 2), "dist_m": round(dist, 2)},
+            {"t": 1.0, "az_deg": round(az, 2), "el_deg": round(el, 2), "dist_m": round(dist, 2)},
+        ]
+    return [
+        {"t": 0.0, "az_deg": round(az - sweep / 2, 2), "el_deg": round(el, 2), "dist_m": round(dist, 2)},
+        {"t": 1.0, "az_deg": round(az + sweep / 2, 2), "el_deg": round(el, 2), "dist_m": round(dist, 2)},
+    ]
+
+
+def find_anchor_rules(payload: Dict[str, Any]) -> Dict[str, Dict[str, float]]:
+    anchors: Dict[str, Dict[str, float]] = {}
+    for rule in payload.get("rules", []):
+        if rule.get("type") == "anchor":
+            key = rule.get("track_class")
+            if key:
+                anchors[key] = {
+                    "az": float(rule.get("az_deg", 0.0)),
+                    "el": float(rule.get("el_deg", 0.0)),
+                    "dist": float(rule.get("dist_m", 1.6)),
+                }
+    return anchors
+
+
+def width_preference(payload: Dict[str, Any], track_class: str) -> float | None:
+    for rule in payload.get("rules", []):
+        if rule.get("type") == "width_pref" and rule.get("track_class") == track_class:
+            value = rule.get("min_width")
+            if value is not None:
+                return float(value)
+    return None
+
+
+def target_layout(payload: Dict[str, Any]) -> str:
+    fmt = str(payload.get("target_format", "iamf")).lower()
+    if fmt in {"binaural", "iamf", "5.1.4", "7.1.4"}:
+        return fmt
+    return "iamf"
+
+
+def room_preset(payload: Dict[str, Any]) -> str:
+    style = str(payload.get("style", "neutral")).lower()
+    mapping = {
+        "club": "club_medium",
+        "cinematic": "cinema_large",
+        "film": "cinema_large",
+        "podcast": "studio_dry",
+        "live": "stage_wide",
+        "intimate": "studio_small",
+    }
+    return mapping.get(style, "studio_neutral")
+
+
+def heuristic_scene(payload: Dict[str, Any]) -> Dict[str, Any]:
+    anchors = find_anchor_rules(payload)
+    objects: List[Dict[str, Any]] = []
+    constraints_applied: List[str] = []
+    max_objects = int(payload.get("max_objects", 10))
+    style = str(payload.get("style", "neutral")).lower()
+
+    for rule in payload.get("rules", []):
+        rtype = rule.get("type")
+        if rtype == "anchor":
+            constraints_applied.append(
+                f"anchor:{rule.get('track_class')}@{rule.get('az_deg')}/{rule.get('el_deg')}/{rule.get('dist_m')}"
+            )
+        elif rtype == "mono_low_end":
+            constraints_applied.append(f"mono_low_end<{rule.get('hz_below', 120)}Hz")
+        elif rtype == "width_pref":
+            constraints_applied.append(f"{rule.get('track_class')}_width>={rule.get('min_width')}")
+        elif rtype == "keep_dialogue_clear":
+            band = rule.get("band_hz", [1000, 4000])
+            constraints_applied.append(f"keep_dialogue_clear_{band[0]}-{band[1]}Hz")
+        elif rtype == "avoid_band_masking":
+            band = rule.get("band_hz", [1500, 4500])
+            constraints_applied.append(f"avoid_masking_{rule.get('mask_target')}_{band[0]}-{band[1]}Hz")
+
+    for idx, stem in enumerate(payload.get("stems", [])[:max_objects]):
+        cls = stem.get("class", "other")
+        defaults = dict(CLASS_DEFAULTS.get(cls, CLASS_DEFAULTS["other"]))
+        if cls in anchors:
+            defaults["az"] = anchors[cls]["az"]
+            defaults["el"] = anchors[cls]["el"]
+            defaults["dist"] = anchors[cls]["dist"]
+
+        width_min = width_preference(payload, cls)
+        if width_min is not None:
+            defaults["width"] = max(defaults["width"], width_min)
+
+        leadness = float(stem.get("leadness", 0.0))
+        transient = float(stem.get("transient", 0.0))
+        lufs = float(stem.get("lufs", -20.0))
+
+        if leadness > 0.8 and cls not in {"kick", "bass", "dialogue", "lead_vocal"}:
+            defaults["dist"] = clip(defaults["dist"] - 0.35, 0.8, 15.0)
+            defaults["gain"] = clip(defaults["gain"] + 0.8, -60.0, 12.0)
+
+        if transient > 0.7 and cls in {"fx", "synth_lead"}:
+            defaults["az"] += 12.0
+
+        if lufs < -24 and cls in {"fx", "ambience", "pad"}:
+            defaults["dist"] = clip(defaults["dist"] + 0.5, 0.5, 15.0)
+
+        # Add style-specific touch
+        sweep = 0.0
+        if style == "club" and cls in {"fx", "synth_lead"}:
+            sweep = 28.0 if cls == "fx" else 10.0
+        elif style in {"cinematic", "film"} and cls in {"fx", "ambience"}:
+            sweep = 18.0
+        elif style == "podcast" and cls in {"dialogue", "back_vocal"}:
+            sweep = 0.0
+
+        obj = {
+            "id": str(stem.get("id", f"obj_{idx+1}")),
+            "class": cls if cls in SPATIAL_CLASSES else "other",
+            "az_deg": round(clip(defaults["az"], -180, 180), 2),
+            "el_deg": round(clip(defaults["el"], -45, 90), 2),
+            "dist_m": round(clip(defaults["dist"], 0.5, 15.0), 2),
+            "width": round(clip(defaults["width"], 0.0, 1.0), 2),
+            "gain_db": round(clip(defaults["gain"], -60, 12), 2),
+            "reverb_send": round(clip(defaults["rev"], 0.0, 1.0), 2),
+            "early_reflections": round(clip(defaults["er"], 0.0, 1.0), 2),
+            "motion": make_motion(defaults["az"], defaults["el"], defaults["dist"], sweep=sweep),
+        }
+
+        # Low-end mono safety
+        if cls in {"kick", "bass"}:
+            obj["az_deg"] = 0.0
+            obj["width"] = 0.0 if cls == "kick" else min(obj["width"], 0.08)
+            obj["motion"] = make_motion(0.0, obj["el_deg"], obj["dist_m"], sweep=0.0)
+
+        objects.append(obj)
+
+    scene = {
+        "version": "1.0",
+        "bed": {
+            "layout": target_layout(payload),
+            "loudness_target_lufs": -16.0 if payload.get("style") == "cinematic" else -14.0,
+            "room_preset": room_preset(payload),
+        },
+        "objects": objects or [
+            {
+                "id": "placeholder",
+                "class": "other",
+                "az_deg": 0.0,
+                "el_deg": 0.0,
+                "dist_m": 2.0,
+                "width": 0.2,
+                "gain_db": 0.0,
+                "reverb_send": 0.1,
+                "early_reflections": 0.1,
+                "motion": make_motion(0.0, 0.0, 2.0),
+            }
+        ],
+        "constraints_applied": constraints_applied,
+    }
+    return scene
+
+
+def scene_stats(scene: Dict[str, Any]) -> Dict[str, Any]:
+    objects = scene.get("objects", [])
+    dominant = sorted(objects, key=lambda o: float(o.get("gain_db", -99.0)), reverse=True)[:3]
+    return {
+        "layout": scene.get("bed", {}).get("layout", "unknown"),
+        "room_preset": scene.get("bed", {}).get("room_preset", "unknown"),
+        "object_count": len(objects),
+        "dominant": ", ".join(f"{o.get('id')} ({o.get('class')})" for o in dominant) or "n/a",
+    }
+
+
+def scene_table(scene: Dict[str, Any]) -> List[List[Any]]:
+    rows = []
+    for obj in scene.get("objects", []):
+        rows.append([
+            obj.get("id"),
+            obj.get("class"),
+            obj.get("az_deg"),
+            obj.get("el_deg"),
+            obj.get("dist_m"),
+            obj.get("width"),
+            obj.get("gain_db"),
+        ])
+    return rows
+
+
+def scene_markdown(scene: Dict[str, Any], valid: bool, errors: List[str], backend_used: str) -> str:
+    stats = scene_stats(scene)
+    badge = "✅ Schema valid" if valid else "⚠️ Validation issues"
+    lines = [
+        f"### {badge}",
+        "",
+        f"- **Backend:** {backend_used}",
+        f"- **Layout:** `{stats['layout']}`",
+        f"- **Room preset:** `{stats['room_preset']}`",
+        f"- **Objects:** `{stats['object_count']}`",
+        f"- **Top objects:** {stats['dominant']}",
+    ]
+    if errors:
+        lines.append("")
+        lines.append("**Validation messages**")
+        for err in errors[:8]:
+            lines.append(f"- {err}")
+    return "\n".join(lines)
+
+
+def plot_scene(scene: Dict[str, Any]):
+    fig = plt.figure(figsize=(7.0, 7.0))
+    ax = fig.add_subplot(111)
+    ax.set_facecolor("#f8fbff")
+    fig.patch.set_facecolor("#f8fbff")
+
+    # rings
+    for r in [2, 4, 6, 8, 10]:
+        circle = plt.Circle((0, 0), r, color="#d9e5f7", fill=False, linewidth=1)
+        ax.add_artist(circle)
+
+    # axes
+    ax.axhline(0, color="#d9e5f7", linewidth=1)
+    ax.axvline(0, color="#d9e5f7", linewidth=1)
+
+    # labels
+    ax.text(0, 10.7, "Front", ha="center", va="bottom", fontsize=11, color="#4a5b77")
+    ax.text(10.7, 0, "Right", ha="left", va="center", fontsize=11, color="#4a5b77")
+    ax.text(-10.7, 0, "Left", ha="right", va="center", fontsize=11, color="#4a5b77")
+    ax.text(0, -10.7, "Rear", ha="center", va="top", fontsize=11, color="#4a5b77")
+
+    palette = ["#1d4ed8", "#0891b2", "#7c3aed", "#ea580c", "#0f766e", "#be123c", "#0369a1", "#4d7c0f"]
+
+    for idx, obj in enumerate(scene.get("objects", [])):
+        az = math.radians(float(obj.get("az_deg", 0.0)))
+        dist = float(obj.get("dist_m", 1.0))
+        x = dist * math.sin(az)
+        y = dist * math.cos(az)
+        size = 120 + 220 * float(obj.get("width", 0.2))
+        color = palette[idx % len(palette)]
+        ax.scatter([x], [y], s=size, c=color, alpha=0.85, edgecolors="white", linewidths=1.5, zorder=3)
+        ax.text(x, y + 0.42, f"{obj.get('id')}\n{obj.get('class')}", ha="center", va="bottom", fontsize=9, color="#1f2937")
+
+    ax.set_xlim(-11, 11)
+    ax.set_ylim(-11, 11)
+    ax.set_xticks([])
+    ax.set_yticks([])
+    ax.set_title("Spatial Scene Preview", fontsize=15, color="#15233d", pad=12)
+    return fig