> For the complete documentation index, see [llms.txt](https://fb-scripts.gitbook.io/fb-scripts/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://fb-scripts.gitbook.io/fb-scripts/scripts/fb-blackmarket/adding-custom-voice-lines.md).

# Adding Custom Voice Lines

You can create custom NPC voice lines using **ElevenLabs** (AI voice generator) and add them to the blackmarket. This gives your server's vendors a unique personality.

#### Voice Cue Categories

| Category     | When It Plays                   | Example Lines                                 |
| ------------ | ------------------------------- | --------------------------------------------- |
| **Enter**    | Player opens the blackmarket UI | *"Welcome back... what do you need?"*         |
| **Deal**     | Player completes a purchase     | *"Pleasure doing business."*                  |
| **Delivery** | Delivery mission is started     | *"Coordinates are on your phone. Move fast."* |

***

{% stepper %}
{% step %}

### Create an ElevenLabs Account

* Go to [elevenlabs.io](https://elevenlabs.io)
* Create a free account (free tier gives you 10,000 characters/month)
* Navigate to **Speech Synthesis** from the left sidebar
  {% endstep %}

{% step %}

### Choose a Voice

* Click on the **voice selector** dropdown
* Browse the voice library or use pre-made voices
* You can also **clone a voice** or create a custom one in the Voice Lab

{% hint style="info" %}
Pick a voice that fits your NPC's character. A downtown street dealer should sound different from a VIP smuggler.
{% endhint %}
{% endstep %}

{% step %}

### Write Your Lines

Write short, punchy lines for each category.
{% endstep %}

{% step %}

### Generate the Audio

* Paste one line at a time into the ElevenLabs text box
* Click **Generate** to create the audio
* Listen to the preview — regenerate if it doesn't sound right
* Click the **⬇ Download** button to save as MP3
  {% endstep %}

{% step %}

### Prepare the Files

1. **File format:** MP3 (ElevenLabs exports as MP3 by default)
2. **File size:** Keep under 200KB per file for best performance (\~2-5 second clips)
3. **Rename files** following the naming convention:

| Shop Type | Category | File Names                                                      |
| --------- | -------- | --------------------------------------------------------------- |
| Normal    | Enter    | `entervoice1.mp3`, `entervoice2.mp3`, `entervoice3.mp3`, ...    |
| Normal    | Deal     | `deal1.mp3`, `deal2.mp3`, `deal3.mp3`, ...                      |
| Normal    | Delivery | `delivery1.mp3`, `delivery2.mp3`, `delivery3.mp3`, ...          |
| VIP       | Enter    | `vipenter1.mp3`, `vipenter2.mp3`, `vipenter3.mp3`, ...          |
| VIP       | Deal     | `vipdeal1.mp3`, `vipdeal2.mp3`, `vipdeal3.mp3`, ...             |
| VIP       | Delivery | `vipdelivery1.mp3`, `vipdelivery2.mp3`, `vipdelivery3.mp3`, ... |

{% hint style="info" %}
You can add as many variations as you want (not limited to 3). More files = more variety.
{% endhint %}
{% endstep %}

{% step %}

### Place Files in the Resource

Copy your MP3 files to the correct folders:

```
fb-blackmarket/
└── sounds/
    ├── downtownsounds/    ← Normal shop files go here
    └── vipsounds/         ← VIP shop files go here
```

{% endstep %}

{% step %}

### Register in Config

Open `config.lua` and update `Config.VoiceCues` with your new file paths:

```lua
Config.VoiceCues = {
    Enabled = true,
    Volume = 0.4,          -- 0.0 to 1.0

    VIP = {
        Enter = {
            "vipsounds/vipenter1.mp3",
            "vipsounds/vipenter2.mp3",
            "vipsounds/vipenter3.mp3",
            "vipsounds/vipenter4.mp3",   -- Add more!
            "vipsounds/vipenter5.mp3"
        },
        Deal = {
            "vipsounds/vipdeal1.mp3",
            "vipsounds/vipdeal2.mp3",
            "vipsounds/vipdeal3.mp3"
        },
        Delivery = {
            "vipsounds/vipdelivery1.mp3",
            "vipsounds/vipdelivery2.mp3",
            "vipsounds/vipdelivery3.mp3"
        }
    },

    Default = {
        Enter = {
            "downtownsounds/entervoice1.mp3",
            "downtownsounds/entervoice2.mp3",
            "downtownsounds/entervoice3.mp3"
        },
        Deal = {
            "downtownsounds/deal1.mp3",
            "downtownsounds/deal2.mp3"
        },
        Delivery = {
            "downtownsounds/delivery1.mp3",
            "downtownsounds/delivery2.mp3",
            "downtownsounds/delivery3.mp3"
        }
    }
}
```

{% endstep %}

{% step %}

### Update fxmanifest (If Adding New Folders)

If you created new subfolders in `sounds/`, make sure they're included in `fxmanifest.lua`:

```lua
files {
    -- ... existing entries ...
    'sounds/downtownsounds/*.mp3',
    'sounds/vipsounds/*.mp3',
    'sounds/mycustomsounds/*.mp3',    -- Add your new folder
}
```

{% endstep %}

{% step %}

### Test In-Game

* Restart the resource: `ensure fb-blackmarket`
* Walk up to the NPC vendor and open the blackmarket
* You should hear a random Enter voice line play
* Make a purchase → Deal voice line plays
* Start a delivery → Delivery voice line plays
* Close the UI → Exit voice line plays
  {% endstep %}
  {% endstepper %}

#### Tips for Best Results

| Tip                      | Details                                                              |
| ------------------------ | -------------------------------------------------------------------- |
| **Keep lines short**     | 2-5 seconds is ideal. Long monologues feel unnatural                 |
| **Use different voices** | VIP dealer should sound more refined than the street dealer          |
| **Match the mood**       | Street dealer = rough, fast. VIP = calm, sophisticated               |
| **Add variety**          | 5+ files per category prevents repetition                            |
| **Test volume**          | Adjust `Config.VoiceCues.Volume` (0.3-0.5 is usually good)           |
| **3D audio**             | Sounds fade with distance automatically when `Config.Sound3D = true` |
| **Multilingual**         | You can create voice lines in any language for your server           |