Skip to content
Get packs

Guide · Open source

How to use PersonaPlex: install, launch and prompt the voice model

Updated · written with AI from the project's own documentation and checked against our catalogue data

PersonaPlex is an open-source, real-time speech-to-speech conversational model from NVIDIA. It listens and replies with speech in full duplex, and you can set its role with a text prompt and pick a voice from a fixed list. This guide covers the prerequisites, installation, launching the local web server, running offline evaluation on audio files, and writing prompts. By the end you will be able to get the model running on a suitable NVIDIA GPU and try different personas.

PersonaPlexNVIDIA/personaplex · ★ 12k · MIT

Quick start

  1. 1Install the Opus codec. Install libopus-dev on Ubuntu/Debian or opus-devel on Fedora/RHEL.
  2. 2Clone the repository. Download the PersonaPlex code so you have the moshi folder locally.
  3. 3Install the package. Run pip install moshi/. from the repository folder.
  4. 4Accept the model license. Log in to Hugging Face and accept the PersonaPlex model license on the model page.
  5. 5Set your token. Export HF_TOKEN with your Hugging Face access token.
  6. 6Launch the server. Run the moshi.server command with a temporary SSL directory and open localhost:8998 in your browser.

Check the prerequisites before you install

PersonaPlex is a research code release. You need Python, pip, PyTorch with GPU support, and the Opus audio codec development library. You also need a Hugging Face account and access token, because the model weights are downloaded through Hugging Face.

The README notes that the model needs a GPU with enough memory. If yours does not have enough, it offers a CPU offload option, but that requires extra packages.

  • Python and pip
  • PyTorch with GPU support
  • Opus codec development library (libopus-dev on Ubuntu/Debian, opus-devel on Fedora/RHEL)
  • A Hugging Face account and access token
# Ubuntu/Debian sudo apt install libopus-dev # Fedora/RHEL sudo dnf install opus-devel

Install PersonaPlex from the repository

Download (clone) the repository, then install the included moshi package with pip from the repository folder.

If you have a Blackwell-based GPU, the README suggests an extra step to install PyTorch from the index it lists. Use that only if your GPU is Blackwell-based.

pip install moshi/.

Accept the model license and set your Hugging Face token

The weights are released under the NVIDIA Open Model license, which is separate from the MIT license that covers the code. Log in to Hugging Face and accept the PersonaPlex model license on the model page before downloading. Then set your token as an environment variable.

  • Open the model page at huggingface.co/nvidia/personaplex-7b-v1 and accept the license.
  • Replace the placeholder with your own token.
export HF_TOKEN=<YOUR_HUGGINGFACE_TOKEN>

Launch the local web server

The server command creates a temporary folder for SSL certificates so the page is served over https. When it starts locally, open the Web UI in your browser at localhost:8998. If you run it on a remote machine, use the access link the script prints.

If your GPU has insufficient memory, add the --cpu-offload flag. This needs the accelerate package, which you install with pip.

  • Local access: localhost:8998
  • Low GPU memory: add --cpu-offload and run pip install accelerate first
SSL_DIR=$(mktemp -d); python -m moshi.server --ssl "$SSL_DIR" # With CPU offload SSL_DIR=$(mktemp -d); python -m moshi.server --ssl "$SSL_DIR" --cpu-offload

Run offline evaluation on a WAV file

If you do not want a live session, the offline script streams an input WAV file through the model and writes an output WAV file made from the captured output. The output is the same duration as the input. You choose a voice with --voice-prompt and a role with --text-prompt. The README gives an assistant example and a service example, both with a fixed seed.

The README also says you can install CPU-only PyTorch for offline evaluation without a GPU.

  • --voice-prompt selects a voice file such as NATF2.pt or NATM1.pt
  • --text-prompt sets the role; the service example reads it from a text file
  • --input-wav, --output-wav and --output-text set the input and output files
  • --seed sets the random seed used in the README examples
HF_TOKEN=<TOKEN> \ python -m moshi.offline \ --voice-prompt "NATF2.pt" \ --input-wav "assets/test/input_assistant.wav" \ --seed 42424242 \ --output-wav "output.wav" \ --output-text "output.json"

Choose a voice

PersonaPlex ships with a fixed set of pre-packaged voice embeddings. They are grouped as natural (NAT) voices, which the README describes as more natural and conversational, and variety (VAR) voices, which are more varied. You cannot add arbitrary voices from this source; you pick from the list.

  • Natural female: NATF0, NATF1, NATF2, NATF3
  • Natural male: NATM0, NATM1, NATM2, NATM3
  • Variety female: VARF0 to VARF4
  • Variety male: VARM0 to VARM4

Write a role prompt

The text prompt sets the persona. The README says the model was trained on synthetic conversations for a fixed assistant role and on varied customer service roles. For a customer service agent, the prompt states the company, the agent's name, and the facts the agent should use, such as prices or schedules. For open conversation, the README suggests starting with 'You enjoy having a good conversation.' and adding a topic.

The README reports that the model can respond plausibly to prompts outside its training, so experimenting is encouraged, but it does not promise results for every scenario.

  • Assistant: 'You are a wise and friendly teacher. Answer questions or provide advice in a clear and engaging way.'
  • Customer service: name the company, the agent's name, and the facts to use
  • Casual: start with 'You enjoy having a good conversation.' and add a topic

What people use it for

  • Prototyping a voice assistant that keeps one set persona, using the teacher assistant prompt.
  • Testing a customer service voice agent by writing a role prompt with company facts and a name.
  • Researching full-duplex speech conversation by running offline evaluation on your own WAV files.
  • Trying different voices from the fixed NAT and VAR sets to compare how a persona sounds.

Frequently asked questions

Is PersonaPlex free to use?

The code is released under the MIT license. The model weights are released under the NVIDIA Open Model license, and you must accept that license on Hugging Face before downloading them. Read the license text yourself before commercial use, since this guide does not interpret it.

What do I need to run PersonaPlex?

You need Python, pip, PyTorch with GPU support, the Opus codec development library, and a Hugging Face account with an access token. The README says the model needs a GPU with enough memory.

How do I install PersonaPlex?

Install the Opus development library, clone the repository, and run pip install moshi/. from the repository folder. Then accept the model license on Hugging Face and export your HF_TOKEN.

What if I get a CUDA out of memory error?

The README suggests adding the --cpu-offload flag to the server or offline command. This offloads model layers to the CPU and requires the accelerate package, which you can install with pip install accelerate. The README says this option needs extra packages and is not a substitute for enough GPU memory in every case.

Can I run PersonaPlex without a GPU?

The README says you can install CPU-only PyTorch for offline evaluation on a pure CPU. It does not describe CPU-only live server use, so check the repository for current details before relying on it.

How does PersonaPlex compare to Moshi?

PersonaPlex is based on the Moshi architecture and weights, and the README says it finetunes Moshi. Its added value is role control through text prompts and voice selection from a fixed set. For the details of Moshi itself, see its own project.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

PersonaPlex suits developers, researchers and teams with a suitable NVIDIA GPU who want to test a speech model with a set persona. It is a research code release with a basic web UI, so people who need a polished end-user app or cannot accept the separate model license should choose another option.

Install options & downloads