---
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