Skip to main content
Unmute allows you to create custom characters with unique voices and personalities. Characters are defined in the voices.yaml configuration file, which combines voice samples with conversation instructions.

​
Understanding Character Configuration

Each character in Unmute consists of two main components:
  1. Voice Sample: An audio file that defines how the character sounds
  2. Instructions: System prompts that define the character’s personality and behavior

​
The voices.yaml File

The voices.yaml file is located in the root of the Unmute repository. Each character is defined with the following structure:

​
Configuration Fields

​
string
required
Display name for the character that appears in the UI
​
boolean
Quality flag - set to true to mark as production-ready, false for testing, or null for undecided
​
string
Internal notes about the character (e.g., “man, UK, skeptical”)
​
object
required
Defines the character’s conversation style and personality. See Instruction Types below.
​
object
required
Specifies the voice audio source. Can be either file or freesound type.

​
Instruction Types

Unmute provides several built-in instruction types that define character behavior:

​
Smalltalk

For general conversation with context-aware greetings:
This type automatically includes the current date, time, and timezone in the system prompt, and randomly selects conversation starters.

​
Constant

For custom character personalities with specific instructions:
Example - Gertrude (Life Advice Counselor):

​
Quiz Show

For a game show host personality:
Randomly selects 5 questions from a predefined question bank and acts as a snarky quiz show host.

​
News

For tech news discussions using live headlines from The Verge:
Requires the NEWSAPI_API_KEY environment variable to be set.

​
Guess Animal

For playing a guessing game:

​
Unmute Explanation

For answering questions about Unmute itself:

​
Voice Sources

Unmute supports multiple ways to source voice samples:

​
File-based Voices

Reference voice files stored on the server:

​
Freesound Voices

Automatically download voices from Freesound.org:

​
Available Voices

Browse the Kyutai TTS voice repository for hundreds of available voices, including:
  • Voices from open datasets (VCTK, Expresso, etc.)
  • Community-donated voices from the Voice Donation Project
  • Freesound.org voice samples
To use a voice from the repository, set the path_on_server to the relative path:

​
Adding a New Character

1

Choose or Create a Voice Sample

Select a voice from the voice repository or prepare your own 10-second audio sample in WAV or MP3 format.
2

Edit voices.yaml

Open voices.yaml in the root of the Unmute repository and add your character definition:
3

Restart the Backend

The voices.yaml file is cached when the backend starts:
4

Test Your Character

Open Unmute in your browser and select your new character from the voice selector.

​
Language Support

The TTS model supports English and French. Configure language support using the language field:
  • en: Primarily English (default)
  • fr: Primarily French
  • en/fr: Fluent in both, English preference
  • fr/en: Fluent in both, French preference
Example for a bilingual character:

​
Advanced Customization

For more complex character behaviors, you can create custom instruction types by modifying unmute/llm/system_prompt.py. See the existing instruction classes for examples:
  • SmalltalkInstructions: Adds dynamic date/time context
  • QuizShowInstructions: Randomly selects questions
  • NewsInstructions: Fetches live news data
Each instruction type must implement a make_system_prompt() method that returns the final system prompt string.

​
Voice Quality Tips

For best results, voice samples should:
  • Be 5-10 seconds long
  • Contain clear speech without background noise
  • Be in WAV or MP3 format at 24kHz (will be resampled if needed)
  • Represent the desired speaking style
The voices.yaml file is only loaded when the backend starts. You must restart the backend service after making changes for them to take effect.