Instructions to use scriptedvn/scriptedvn-models with libraries, inference providers, notebooks, and local apps. Follow these links to get started.
- Notebooks
- Google Colab
- Kaggle
- Local Apps Settings
- llama.cpp
How to use scriptedvn/scriptedvn-models with llama.cpp:
Install (macOS, Linux)
curl -LsSf https://llama.app/install.sh | sh # Start a local OpenAI-compatible server with a web UI: llama serve -hf scriptedvn/scriptedvn-models:Q4_K_M # Run inference directly in the terminal: llama cli -hf scriptedvn/scriptedvn-models:Q4_K_M
Install from WinGet (Windows)
winget install llama.cpp # Start a local OpenAI-compatible server with a web UI: llama serve -hf scriptedvn/scriptedvn-models:Q4_K_M # Run inference directly in the terminal: llama cli -hf scriptedvn/scriptedvn-models:Q4_K_M
Build from source code
git clone https://github.com/ggml-org/llama.cpp.git cd llama.cpp cmake -B build cmake --build build -j --target llama-app # Start a local OpenAI-compatible server with a web UI: ./build/bin/llama serve -hf scriptedvn/scriptedvn-models:Q4_K_M # Run inference directly in the terminal: ./build/bin/llama cli -hf scriptedvn/scriptedvn-models:Q4_K_M
Use Docker
docker model run hf.co/scriptedvn/scriptedvn-models:Q4_K_M
- Llama new
- LM Studio
- Jan
- Ollama
How to use scriptedvn/scriptedvn-models with Ollama:
ollama run hf.co/scriptedvn/scriptedvn-models:Q4_K_M
- Unsloth Desktop
- Pi
How to use scriptedvn/scriptedvn-models with Pi:
Start the llama.cpp server
# Install llama.cpp: brew install llama.cpp # Start a local OpenAI-compatible server: llama serve -hf scriptedvn/scriptedvn-models:Q4_K_M
Configure the model in Pi
# Install Pi: npm install -g @earendil-works/pi-coding-agent # Add to ~/.pi/agent/models.json: { "providers": { "llama-cpp": { "baseUrl": "http://localhost:9931/v1", "api": "openai-completions", "apiKey": "none", "models": [ { "id": "scriptedvn/scriptedvn-models:Q4_K_M" } ] } } }Run Pi
# Start Pi in your project directory: pi
- Docker Model Runner
How to use scriptedvn/scriptedvn-models with Docker Model Runner:
docker model run hf.co/scriptedvn/scriptedvn-models:Q4_K_M
- Lemonade
How to use scriptedvn/scriptedvn-models with Lemonade:
Pull the model
# Download Lemonade from https://lemonade-server.ai/ lemonade pull scriptedvn/scriptedvn-models:Q4_K_M
Run and chat with the model
lemonade run user.scriptedvn-models-Q4_K_M
List all available models
lemonade list
- Hermes Agent
How to use scriptedvn/scriptedvn-models with Hermes Agent:
Start the llama.cpp server
# Install llama.cpp: brew install llama.cpp # Start a local OpenAI-compatible server: llama serve -hf scriptedvn/scriptedvn-models:Q4_K_M
Configure Hermes
# Install Hermes: curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash hermes setup # Point Hermes at the local server: hermes config set model.provider custom hermes config set model.base_url http://127.0.0.1:9931/v1 hermes config set model.default scriptedvn/scriptedvn-models:Q4_K_M
Run Hermes
hermes
- Atomic Chat
- OpenClaw
How to use scriptedvn/scriptedvn-models with OpenClaw:
Start the llama.cpp server
# Install llama.cpp: brew install llama.cpp # Start a local OpenAI-compatible server: llama serve -hf scriptedvn/scriptedvn-models:Q4_K_M
Configure OpenClaw
# Install OpenClaw: npm install -g openclaw@latest # Register the local server and set it as the default model: openclaw onboard --non-interactive --mode local \ --auth-choice custom-api-key \ --custom-base-url http://127.0.0.1:9931/v1 \ --custom-model-id "scriptedvn/scriptedvn-models:Q4_K_M" \ --custom-provider-id llama-cpp \ --custom-compatibility openai \ --custom-text-input \ --accept-risk \ --skip-health
Run OpenClaw
openclaw agent --local --agent main --message "Hello from Hugging Face"
Download voxcpm2_model/README.md from scriptedvn/scriptedvn-models: direct link, hf CLI and curl.
- Browser
- Download file 7.94 kB
-
https://huggingface.co/scriptedvn/scriptedvn-models/resolve/main/voxcpm2_model/README.md
- Command line
-
hf download hf://scriptedvn/scriptedvn-models/voxcpm2_model/README.md
-
curl -L -o README.md https://huggingface.co/scriptedvn/scriptedvn-models/resolve/main/voxcpm2_model/README.md
language:
- zh
- en
- ar
- my
- da
- nl
- fi
- fr
- de
- el
- he
- hi
- id
- it
- ja
- km
- ko
- lo
- ms
- 'no'
- pl
- pt
- ru
- es
- sw
- sv
- tl
- th
- tr
- vi
license: apache-2.0
library_name: voxcpm
tags:
- text-to-speech
- tts
- multilingual
- voice-cloning
- voice-design
- diffusion
- audio
pipeline_tag: text-to-speech
VoxCPM2
VoxCPM2 is a tokenizer-free, diffusion autoregressive Text-to-Speech model β 2B parameters, 30 languages, 48kHz audio output, trained on over 2 million hours of multilingual speech data.
Highlights
- π 30-Language Multilingual β No language tag needed; input text in any supported language directly
- π¨ Voice Design β Generate a novel voice from a natural-language description alone (gender, age, tone, emotion, paceβ¦); no reference audio required
- ποΈ Controllable Cloning β Clone any voice from a short clip, with optional style guidance to steer emotion, pace, and expression while preserving timbre
- ποΈ Ultimate Cloning β Provide reference audio + its transcript for audio-continuation cloning; every vocal nuance faithfully reproduced
- π 48kHz Studio-Quality Output β Accepts 16kHz reference; outputs 48kHz via AudioVAE V2's built-in super-resolution, no external upsampler needed
- π§ Context-Aware Synthesis β Automatically infers appropriate prosody and expressiveness from text content
- β‘ Real-Time Streaming β RTF as low as ~0.3 on NVIDIA RTX 4090, and ~0.13 accelerated by Nano-VLLM
- π Fully Open-Source & Commercial-Ready β Apache-2.0 license, free for commercial use
Arabic, Burmese, Chinese, Danish, Dutch, English, Finnish, French, German, Greek, Hebrew, Hindi, Indonesian, Italian, Japanese, Khmer, Korean, Lao, Malay, Norwegian, Polish, Portuguese, Russian, Spanish, Swahili, Swedish, Tagalog, Thai, Turkish, Vietnamese
Chinese Dialects: εε·θ―, η²€θ―, ε΄θ―, δΈεθ―, ζ²³εθ―, ιθ₯Ώθ―, ε±±δΈθ―, 倩ζ΄₯θ―, ι½εθ―
Quick Start
Installation
pip install voxcpm
Requirements: Python β₯ 3.10, PyTorch β₯ 2.5.0, CUDA β₯ 12.0 Β· Full Quick Start β
Text-to-Speech
from voxcpm import VoxCPM
import soundfile as sf
model = VoxCPM.from_pretrained("openbmb/VoxCPM2", load_denoiser=False)
wav = model.generate(
text="VoxCPM2 brings multilingual support, creative voice design, and controllable voice cloning.",
cfg_value=2.0,
inference_timesteps=10,
)
sf.write("output.wav", wav, model.tts_model.sample_rate)
Voice Design
Put the voice description in parentheses at the start of text, followed by the content to synthesize:
wav = model.generate(
text="(A young woman, gentle and sweet voice)Hello, welcome to VoxCPM2!",
cfg_value=2.0,
inference_timesteps=10,
)
sf.write("voice_design.wav", wav, model.tts_model.sample_rate)
Controllable Voice Cloning
# Basic cloning
wav = model.generate(
text="This is a cloned voice generated by VoxCPM2.",
reference_wav_path="speaker.wav",
)
sf.write("clone.wav", wav, model.tts_model.sample_rate)
# Cloning with style control
wav = model.generate(
text="(slightly faster, cheerful tone)This is a cloned voice with style control.",
reference_wav_path="speaker.wav",
cfg_value=2.0,
inference_timesteps=10,
)
sf.write("controllable_clone.wav", wav, model.tts_model.sample_rate)
Ultimate Cloning
Provide both the reference audio and its exact transcript for maximum fidelity. Pass the same clip to both reference_wav_path and prompt_wav_path for highest similarity:
wav = model.generate(
text="This is an ultimate cloning demonstration using VoxCPM2.",
prompt_wav_path="speaker_reference.wav",
prompt_text="The transcript of the reference audio.",
reference_wav_path="speaker_reference.wav",
)
sf.write("hifi_clone.wav", wav, model.tts_model.sample_rate)
Streaming
import numpy as np
chunks = []
for chunk in model.generate_streaming(text="Streaming is easy with VoxCPM!"):
chunks.append(chunk)
wav = np.concatenate(chunks)
sf.write("streaming.wav", wav, model.tts_model.sample_rate)
Model Details
| Property | Value |
|---|---|
| Architecture | Tokenizer-free Diffusion Autoregressive (LocEnc β TSLM β RALM β LocDiT) |
| Backbone | Based on MiniCPM-4, totally 2B parameters |
| Audio VAE | AudioVAE V2 (asymmetric encode/decode, 16kHz in β 48kHz out) |
| Training Data | 2M+ hours multilingual speech |
| LM Token Rate | 6.25 Hz |
| Max Sequence Length | 8192 tokens |
| dtype | bfloat16 |
| VRAM | ~8 GB |
| RTF (RTX 4090) | ~0.30 (standard) / ~0.13 (Nano-vLLM) |
Performance
VoxCPM2 achieves state-of-the-art or competitive results on major zero-shot and controllable TTS benchmarks.
See the GitHub repo for full benchmark tables (Seed-TTS-eval, CV3-eval, InstructTTSEval, MiniMax Multilingual Test).
Fine-tuning
VoxCPM2 supports both full SFT and LoRA fine-tuning with as little as 5β10 minutes of audio:
# LoRA fine-tuning (recommended)
python scripts/train_voxcpm_finetune.py \
--config_path conf/voxcpm_v2/voxcpm_finetune_lora.yaml
# Full fine-tuning
python scripts/train_voxcpm_finetune.py \
--config_path conf/voxcpm_v2/voxcpm_finetune_all.yaml
See the Fine-tuning Guide for full instructions.
Limitations
- Voice Design and Style Control results may vary between runs; generating 1β3 times is recommended to obtain the desired output.
- Performance varies across languages depending on training data availability.
- Occasional instability may occur with very long or highly expressive inputs.
- Strictly forbidden to use for impersonation, fraud, or disinformation. AI-generated content should be clearly labeled.
Citation
@article{voxcpm2_2026,
title = {VoxCPM2: Tokenizer-Free TTS for Multilingual Speech Generation, Creative Voice Design, and True-to-Life Cloning},
author = {VoxCPM Team},
journal = {GitHub},
year = {2026},
}
@article{voxcpm2025,
title = {VoxCPM: Tokenizer-Free TTS for Context-Aware Speech Generation and True-to-Life Voice Cloning},
author = {Zhou, Yixuan and Zeng, Guoyang and Liu, Xin and Li, Xiang and
Yu, Renjie and Wang, Ziyang and Ye, Runchuan and Sun, Weiyue and
Gui, Jiancheng and Li, Kehan and Wu, Zhiyong and Liu, Zhiyuan},
journal = {arXiv preprint arXiv:2509.24650},
year = {2025},
}
License
Released under the Apache-2.0 license, free for commercial use. For production deployments, we recommend thorough testing and safety evaluation tailored to your use case.