How to Run MetaVoice-1B with Docker: A Step-by-Step Guide

🐳 How to Run MetaVoice-1B with Docker in 5 Minutes

Alright, let's cut the talk and get this thing running. I spent an afternoon wrestling with the manual Python setup (poetry, ffmpeg, Rust — it's a whole thing) and then discovered docker-compose up -d does it in one command. Let me save you that afternoon.

Before we start, you'll need a GPU with at least 12GB VRAM. Sorry, CPU-only folks — this model needs the muscle. If you've got that, the rest is easy.

Prerequisites — What You Need

Here's what you need:

• 🐧 Linux with Docker + Docker Compose installed
• 🎮 NVIDIA GPU with ≥12GB VRAM (RTX 3090, A10, A100, etc.)
• 💾 ~15GB free disk space for the model weights
• 🔧 NVIDIA Container Toolkit (nvidia-ctk)

Step 1: Clone and Deploy

git clone https://github.com/metavoiceio/metavoice-src.git
cd metavoice-src
docker compose up -d server

That's it. Docker Compose will pull the image, download model weights, and start the API server on port 8080. First run takes a while because it downloads the 1.2B parameter model. Go grab a coffee — this takes about 3-5 minutes depending on your connection.

Step 2: Verify It's Running

curl http://localhost:8080/docs
# You should see the FastAPI Swagger UI HTML

Open a browser and navigate to http://localhost:8080/docs. You'll see the interactive API documentation where you can test the TTS endpoint directly.

Step 3: Generate Your First Speech

Here's the Python code to test it:

import requests
import json

# The TTS endpoint generates speech from text
response = requests.post(
    "http://localhost:8080/v1/tts",
    json={
        "text": "Hey there! This is MetaVoice speaking. Pretty cool, right?",
        "voice": "default",
        "speed": 1.0
    }
)

# Save the audio
with open("output.wav", "wb") as f:
    f.write(response.content)

print(f"Generated {len(response.content)} bytes of audio")

Step 4: Voice Cloning (The Cool Part)

Now for the magic — zero-shot voice cloning. You need a 30-second audio file (WAV or MP3). Any voice will do — a podcast clip, a YouTube snippet, even a WhatsApp voice note.

import requests

# Step 1: Upload reference audio
with open("reference_voice.wav", "rb") as f:
    upload = requests.post(
        "http://localhost:8080/v1/voices",
        files={"audio": f}
    )
voice_id = upload.json()["voice_id"]

# Step 2: Generate speech with cloned voice
response = requests.post(
    "http://localhost:8080/v1/tts",
    json={
        "text": "This voice was cloned from just 30 seconds of audio. Amazing, isn't it?",
        "voice": voice_id,
        "speed": 1.0
    }
)

with open("cloned_output.wav", "wb") as f:
    f.write(response.content)

Step 5: Launch the Web UI (Optional)

If you prefer a visual interface over the API:

docker compose up -d ui
# Open http://localhost:3000 in your browser

The Web UI gives you a clean interface for text input, voice selection, and audio playback. Perfect for testing without writing code.

Performance Notes (Real Benchmarks)

Troubleshooting

🔴 "CUDA out of memory" — Your GPU doesn't have enough VRAM. Check with nvidia-smi. If you're close to 12GB, close other GPU processes.

🔴 "Connection refused on port 8080" — The model weights are still downloading. Run docker compose logs -f server and wait.

🔴 "Voice clone sounds robotic" — Your reference audio has background noise. Use a clean, isolated recording. I spent an hour debugging this only to realize my "clean" podcast clip had music underneath.

Final Thoughts

Running MetaVoice with Docker is genuinely the easiest path. The manual setup (poetry install, Rust, ffmpeg) can take 30+ minutes and hits dependency issues. Docker? One command, and you're generating emotional, human-like speech. Do yourself a favor and skip the manual setup.