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
7.94 kB
| 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. | |
| [](https://github.com/OpenBMB/VoxCPM) | |
| [](https://voxcpm.readthedocs.io/en/latest/) | |
| [](https://huggingface.co/spaces/OpenBMB/VoxCPM-Demo) | |
| [](https://openbmb.github.io/voxcpm2-demopage) | |
| [](https://discord.gg/KZUx7tVNwz) | |
| [](https://applink.feishu.cn/client/chat/chatter/add_by_link?link_token=acds0b9d-23d8-4d7e-b696-d200f3e22a7f) [](https://modelbest.feishu.cn/wiki/UtWxwcERfiRIpIkBOjuc3h9tn1D) | |
| ## 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](https://github.com/a710128/nanovllm-voxcpm) | |
| - π **Fully Open-Source & Commercial-Ready** β Apache-2.0 license, free for commercial use | |
| <summary><b>Supported Languages (30)</b></summary> | |
| 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 | |
| ```bash | |
| pip install voxcpm | |
| ``` | |
| **Requirements:** Python β₯ 3.10, PyTorch β₯ 2.5.0, CUDA β₯ 12.0 Β· [Full Quick Start β](https://voxcpm.readthedocs.io/en/latest/quickstart.html) | |
| ### Text-to-Speech | |
| ```python | |
| 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: | |
| ```python | |
| 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 | |
| ```python | |
| # 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: | |
| ```python | |
| 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 | |
| ```python | |
| 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](https://github.com/OpenBMB/VoxCPM#-performance) 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: | |
| ```bash | |
| # 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](https://voxcpm.readthedocs.io/en/latest/finetuning/finetune.html) 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 | |
| ```bibtex | |
| @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](https://www.apache.org/licenses/LICENSE-2.0) license, free for commercial use. For production deployments, we recommend thorough testing and safety evaluation tailored to your use case. | |