> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/kyutai-labs/unmute/llms.txt
> Use this file to discover all available pages before exploring further.

# Voices and Characters

> Customize conversation personalities and voice characteristics in Unmute

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:

```yaml theme={null}
- name: Watercooler
  good: true
  instructions:
    type: smalltalk
  source:
    source_type: file
    path_on_server: unmute-prod-website/p329_022.wav
    description: From the Device Recorded VCTK dataset.
    description_link: https://datashare.ed.ac.uk/handle/10283/3038
```

### Configuration Fields

<ParamField path="name" type="string" required>
  Display name for the character that appears in the UI
</ParamField>

<ParamField path="good" type="boolean">
  Quality flag - set to `true` to mark as production-ready, `false` for testing, or `null` for undecided
</ParamField>

<ParamField path="comment" type="string">
  Internal notes about the character (e.g., "man, UK, skeptical")
</ParamField>

<ParamField path="instructions" type="object" required>
  Defines the character's conversation style and personality. See [Instruction Types](#instruction-types) below.
</ParamField>

<ParamField path="source" type="object" required>
  Specifies the voice audio source. Can be either `file` or `freesound` type.
</ParamField>

## Instruction Types

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

### Smalltalk

For general conversation with context-aware greetings:

```yaml theme={null}
instructions:
  type: smalltalk
  language: en  # optional: en, fr, en/fr, or fr/en
```

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:

```yaml theme={null}
instructions:
  type: constant
  text: "Offer life advice. Be kind and sympathetic. Your name is Gertrude."
  language: en  # optional
```

**Example - Gertrude (Life Advice Counselor)**:

```yaml theme={null}
- name: Gertrude
  good: true
  instructions:
    type: constant
    text: Offer life advice. Be kind and sympathetic. Your name is Gertrude.
  source:
    source_type: file
    path_on_server: unmute-prod-website/gertrude.wav
```

### Quiz Show

For a game show host personality:

```yaml theme={null}
instructions:
  type: quiz_show
  language: en  # optional
```

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:

```yaml theme={null}
instructions:
  type: news
  language: en  # optional
```

Requires the `NEWSAPI_API_KEY` environment variable to be set.

### Guess Animal

For playing a guessing game:

```yaml theme={null}
instructions:
  type: guess_animal
  language: en  # optional
```

### Unmute Explanation

For answering questions about Unmute itself:

```yaml theme={null}
instructions:
  type: unmute_explanation
```

## Voice Sources

Unmute supports multiple ways to source voice samples:

### File-based Voices

Reference voice files stored on the server:

```yaml theme={null}
source:
  source_type: file
  path_on_server: unmute-prod-website/developer-1.mp3
  description: This is the voice of a Kyutai developer
  description_link: https://example.com  # optional
```

### Freesound Voices

Automatically download voices from Freesound.org:

```yaml theme={null}
source:
  source_type: freesound
  url: https://freesound.org/people/InspectorJ/sounds/519189/
  path_on_server: unmute-prod-website/freesound/519189.mp3
```

## Available Voices

Browse the [Kyutai TTS voice repository](https://huggingface.co/kyutai/tts-voices) 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:

```yaml theme={null}
path_on_server: voice-donations/Haku.wav
```

## Adding a New Character

<Steps>
  <Step title="Choose or Create a Voice Sample">
    Select a voice from the [voice repository](https://huggingface.co/kyutai/tts-voices) or prepare your own 10-second audio sample in WAV or MP3 format.
  </Step>

  <Step title="Edit voices.yaml">
    Open `voices.yaml` in the root of the Unmute repository and add your character definition:

    ```yaml theme={null}
    - name: My Character
      good: true
      instructions:
        type: constant
        text: You are a friendly robot assistant. Be helpful and enthusiastic.
      source:
        source_type: file
        path_on_server: voice-donations/robot-voice.wav
    ```
  </Step>

  <Step title="Restart the Backend">
    The `voices.yaml` file is cached when the backend starts:

    ```bash theme={null}
    # For Docker Compose
    docker compose restart backend

    # For dockerless deployment
    # Stop and restart the backend service
    ```
  </Step>

  <Step title="Test Your Character">
    Open Unmute in your browser and select your new character from the voice selector.
  </Step>
</Steps>

## 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:

```yaml theme={null}
- name: Bilingual Assistant
  good: true
  instructions:
    type: smalltalk
    language: en/fr
  source:
    source_type: file
    path_on_server: unmute-prod-website/bilingual.wav
```

## 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

<Tip>
  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
</Tip>

<Warning>
  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.
</Warning>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.