Skip to main content
Glama
README.md
# MiniMax H3 Studio (Local Omni-Modal Video & Audio)

Local control panel and MCP server for **MiniMax H3**, running 100% locally on this machine via **ComfyUI** and **AMD ROCm (Radeon RX 9060 XT 16GB VRAM)**.

Unlike Google Flow or cloud video generators, **MiniMax H3 Studio**:
- Generates **synchronized video AND audio** simultaneously in a single omni-modal pass.
- Costs **0 credits** and has **no usage limits or cloud queues**.
- Features an **Automated GPU Synchronizer & VRAM Arbiter** that automatically manages VRAM between Ollama, ComfyUI, Open WebUI, and other apps with zero memory conflicts (`hipErrorOutOfMemory` prevention).
- Exposes native MCP tools to **Claude Code**, **Antigravity (`agy`)**, **Codex**, and **Gemini CLI**.

```
Assistant (Claude, agy, Codex) ──stdio──> minimax-studio ──REST / WebSocket──> ComfyUI (Local AMD ROCm)
                                              │                                      │
                                              └── GPU Synchronizer & Arbiter ────────┴──> Ollama VRAM Coordination
```

---

## 🚀 Quick Start

### 1. Launch the Local Web Studio
```bash
cd /home/bakhtiarrifai/projects/minimax-studio
npm run studio     # Opens Web UI at http://127.0.0.1:8795
```

### 2. Drive from AI Assistants (Claude Code, Antigravity, Codex)
The MCP server is already registered globally:
- In **Antigravity**: Type `h3_status` or ask *"Generate a 2-second clip of a cyberpunk city with orchestral audio"*.
- In **Claude Code**: *"Use the minimax tool to queue a video generation"*.
- In **Codex**: Use `h3_generate` and `h3_wait`.

To re-register at any time:
```bash
npm run register
```

---

## 🎬 MiniMax H3 Generation Capabilities

1. **Text-to-Video (T2V) + Audio:**
   - Visuals generated by the 33.1B DiT model (`minimax_h3_fl2va_pruned_fp8_scaled.safetensors`).
   - Text conditioning parsed by Qwen3-VL 32B (`qwen3vl_32b_minimax_h3_nvfp4_awq.safetensors`).
   - Native soundscape decoded by Audio VAE (`minimax_h3_audio_vae_fp32.safetensors`).

2. **First-to-Last Frame (I2V / FL2V):**
   - Provide `first_frame_path` or `last_frame_path` to smoothly animate between still images.

3. **Cinematic Techniques (`h3_techniques`):**
   - Over 40 built-in camera movements (360 Orbit, Dolly In/Out, FPV Drone, Bullet Time, Tracking Shot).
   - Visual styles (Golden Hour, Cyberpunk Neon, 35mm Film, Noir, Volumetric Fog).
   - Audio styles (Cinematic Orchestral, Nature Foley, Synthwave, Sci-Fi Atmosphere).

4. **FFmpeg Movie Stitcher (`h3_cut`):**
   - Seamlessly stitches multiple generated shots into a single finished MP4 film.
   - Mixes or replaces audio tracks with custom music or voiceovers.

---

## ⚡ Server GPU Synchronization & Conflict-Free Sequencing

The server hosts multiple AI services sharing an AMD Radeon RX 9060 XT (16 GB VRAM):
- **Ollama** (`gemma4-12b-64k`, Open WebUI, Telegram Bot)
- **ComfyUI** (MiniMax H3, Wan2.1)

### How `comfy_gpu_sync` Coordinates Seamlessly:
1. **Pre-Run Coordination:** Whenever MiniMax H3 Studio or ComfyUI receives a generation job, the synchronizer queries Ollama (`GET http://127.0.0.1:11434/api/ps`). If an LLM is in VRAM, it signals Ollama to unload (`keep_alive: 0`), releasing ~10.2 GB VRAM in under 0.5s.
2. **Pre-VAE Memory Guard (`ComfyUnloadModelForVAE`):** Automatically unloads the 33.1B DiT model from VRAM immediately after latent sampling finishes, guaranteeing that the Video and Audio VAE decoders have full 16 GB memory address space without `hipErrorInvalidValue`.
3. **Idle Auto-Release:** Once ComfyUI generation queue is empty for 60 seconds, ComfyUI unloads models and clears PyTorch ROCm cache.
4. **On-Demand LLM Reloading:** When a user or Telegram bot asks Ollama a question, Ollama reloads the LLM into full VRAM instantly with zero errors.

---

## 🛠️ MCP Tools Reference

| Tool | Description |
| :--- | :--- |
| `h3_status` | Check GPU VRAM, queue status, active jobs, and model readiness. |
| `h3_generate` | Queue a video + audio generation with prompt, techniques, duration, and resolution. |
| `h3_wait` | Wait for job completion with live progress percentage and get the output video path. |
| `h3_cut` | Join multiple clips into a final film with local FFmpeg and optional music mix. |
| `h3_techniques` | Catalog of 40+ cinematic camera movements, lighting looks, and sound presets. |
| `h3_gpu_vacate` | Manually force Ollama or ComfyUI to vacate VRAM on demand. |

---

---

## 🐧 Linux Server & AMD Radeon RX 9060 XT (16GB) Support

MiniMax H3 Studio was built and battle-tested on this Linux server with an **AMD Radeon RX 9060 XT (16 GB VRAM)** running **ROCm 7.2**.

For the complete technical setup, memory guard architecture, and ROCm configuration, read:
👉 **[LINUX_ROCM_RX9060XT_GUIDE.md](LINUX_ROCM_RX9060XT_GUIDE.md)**

### Server Highlights:
- **DiT FP8 Scaled:** Runs 33.1B diffusion transformer directly on RX 9060 XT RDNA 4 hardware.
- **CPU Offloading:** Qwen3-VL 32B text encoder offloaded to CPU to keep 100% of 16 GB VRAM free for video generation.
- **Pre-VAE Memory Guard:** Automatically unloads DiT before VAE decode to prevent ROCm `hipErrorInvalidValue`.
- **Automated Multi-Service Sync:** Coordinates with Ollama and other apps via `comfy_gpu_sync`.

---

## 🪟 Windows & NVIDIA RTX 3060 (12GB) Support

MiniMax H3 Studio is fully compatible with **Windows 10/11** and **NVIDIA GeForce RTX 3060 (12 GB VRAM)**.

For complete step-by-step setup in Indonesian & English, read:
👉 **[WINDOWS_RTX3060_GUIDE.md](WINDOWS_RTX3060_GUIDE.md)**

### One-Click Windows Scripts:
1. `setup_windows.bat`: Installs npm dependencies and copies `comfy_gpu_sync` into ComfyUI.
2. `download_models_windows.bat`: Downloads the 4 quantized models from Hugging Face Hub.
3. `start_comfyui_rtx3060.bat`: Starts ComfyUI with `--lowvram` flag for RTX 3060.
4. `start_studio.bat`: Launches the Web Studio control panel at `http://127.0.0.1:8795`.

---

## 📂 Project Structure

```
minimax-studio/
├── setup_windows.bat          # One-click Windows setup script
├── download_models_windows.bat# Automated Hugging Face model downloader for Windows
├── start_comfyui_rtx3060.bat  # ComfyUI launcher optimized for RTX 3060 12GB
├── start_studio.bat           # Web Studio launcher for Windows
├── LINUX_ROCM_RX9060XT_GUIDE.md # Complete Linux ROCm + RX 9060 XT guide
├── WINDOWS_RTX3060_GUIDE.md   # Complete Windows + RTX 3060 guide
├── LICENSE                    # MIT License
├── package.json               # MCP server & Studio scripts
├── custom_nodes/
│   └── comfy_gpu_sync/        # ComfyUI VRAM arbiter & auto-sync custom node
├── src/
│   ├── config.js              # Ports, paths, and default settings
│   ├── gpu_sync.js            # Cross-platform GPU VRAM arbiter (AMD ROCm & NVIDIA CUDA)
│   ├── comfy_client.js        # ComfyUI WebSocket & REST MiniMax H3 pipeline
│   ├── techniques.js          # 40+ cinematic camera & audio presets
│   ├── cut.js                 # Cross-platform FFmpeg video concatenation
│   ├── server.js              # HTTP & WebSocket API server + scenes gallery
│   ├── studio.js              # Web Studio launcher CLI
│   ├── mcp.js                 # MCP Server (stdio)
│   └── register.js            # AI assistant registration script
├── studio/
│   └── index.html             # Sleek dark-mode Studio Web UI with live player
└── scripts/
    ├── download_models_linux.sh # Hugging Face model downloader for Linux
    ├── download_models.py     # Cross-platform Hugging Face model downloader (Python)
    ├── generate_full_episode_13.js # Automated 4-scene episode production
    └── test-connection.js     # Health check & integration test
```


---

## 📄 License

MIT License. See [LICENSE](LICENSE) for details.