minimax-studio
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.
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues