> For the complete documentation index, see [llms.txt](https://ghiaccioscripts.gitbook.io/ghiaccioscripts-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ghiaccioscripts.gitbook.io/ghiaccioscripts-docs/radio/installation.md).

# Installation

## Requirements

* A recent FiveM server (artifact with `lua54`).
* **`pma-voice`** (mandatory). It is never modified: only its exports and events are used. Verified on pma-voice 7.x (7.0.1).
* The companion resource **`ghiaccio_radio_props`**, started **before** `ghiaccio_radio`.
* Optional, auto-detected: `oxmysql` (otherwise settings, favorites and the chosen animation go to the server KVP) and `ox_inventory` / `qb-inventory` / `qs-inventory` / ESX inventory (radio item).
* Node 20+ only if you want to edit the NUI (see `web/`). The compiled NUI is already in `web/dist/`.

## 1. Download

The script is delivered through **Cfx.re Asset Escrow**. After the purchase, log in to [portal.cfx.re](https://portal.cfx.re) with the Cfx.re account used for the purchase and open **Granted Assets**. Download `ghiaccio_radio` and `ghiaccio_radio_props` from there.

{% hint style="info" %}
Escrowed resources only run on servers whose license key belongs to the purchasing Cfx.re account.
{% endhint %}

## 2. Copy the resources

Copy `ghiaccio_radio` and `ghiaccio_radio_props` into `resources/`.

## 3. server.cfg

Start the radio **after** `pma-voice`, the framework and `oxmysql`, and `ghiaccio_radio_props` **before** `ghiaccio_radio`:

```cfg
ensure pma-voice
setr voice_enableRadioAnim 0        # REQUIRED: radio animations are handled by ghiaccio_radio
ensure oxmysql                      # optional
ensure es_extended                  # or qb-core / qbx_core
ensure ghiaccio_radio_props         # BEFORE ghiaccio_radio (radio prop)
ensure ghiaccio_radio
```

{% hint style="danger" %}
**`setr voice_enableRadioAnim 0` is required.** Set it before `ensure pma-voice` / before the server starts. Without it pma-voice plays its own animation on top of ours (the console warns you).
{% endhint %}

With `Config.MuteNativeClicks = true` (default) the pma-voice microphone clicks are muted: the radio NUI plays its own sounds.

## 4. Create the `radio` item

The radio item is required by default (`Config.RequireItem = true`). Use the snippet for your inventory, or set `Config.RequireItem = false`.

{% tabs %}
{% tab title="ox\_inventory" %}
In `ox_inventory/data/items.lua` (also for Qbox):

```lua
['radio'] = {
    label = 'Radio',
    weight = 500,
    stack = false,
    close = true,
    description = 'A walkie-talkie.',
    client = { event = 'ghiaccio_radio:client:use' },   -- using the item opens the radio
},
```

{% endtab %}

{% tab title="qb-inventory" %}
In `qb-core/shared/items.lua` (qb-inventory, ps-inventory, lj-inventory):

```lua
radio = { name = 'radio', label = 'Radio', weight = 500, type = 'item', image = 'radio.png', unique = true, useable = true, shouldClose = true, description = 'A walkie-talkie.' },
```

Use is registered by the resource with `CreateUseableItem` when `Config.UsableItem = true`.
{% endtab %}

{% tab title="qs-inventory" %}
In `qs-inventory/shared/items.lua`:

```lua
['radio'] = { name = 'radio', label = 'Radio', weight = 500, type = 'item', image = 'radio.png', unique = true, useable = true, shouldClose = true, description = 'A walkie-talkie.' },
```

{% hint style="warning" %}
Not tested: `qs-inventory` was not available in the test environment. The export names `GetItemTotalAmount` / `GetItemByName` are taken from its documentation.
{% endhint %}
{% endtab %}

{% tab title="ESX inventory" %}
Run on the `items` table:

```sql
INSERT INTO `items` (`name`, `label`, `weight`) VALUES ('radio', 'Radio', 1);
-- versions with a `limit` column:  (`name`, `label`, `limit`) VALUES ('radio', 'Radio', 1);
```

Use is registered with `ESX.RegisterUsableItem`.
{% endtab %}
{% endtabs %}

Different item name: `Config.Item`. Forced inventory: `Config.Inventory = 'ox' | 'qb' | 'qs' | 'esx' | 'none'`. Without an inventory (standalone) the requirement is ignored with a console warning.

The **server** checks the item when opening, powering on, on every connect and every `Config.ItemCheckSeconds` seconds (default 5): if the player loses it, the radio switches off and the window closes.

## 5. Start and check the console

Restart the server and read the console: it prints the chosen framework, inventory and storage. Then open the radio in game with `/radio` (or **F5**).

## Database

No SQL to run by hand. With `oxmysql` started, the tables `ghiaccio_radio_players` and `ghiaccio_radio_migrations` are created by migrations. Without `oxmysql` the data goes to the server KVP (`Config.Database = 'auto'`). `ghiaccio_radio_anims` is kept only for installs that already had it and is no longer used.

## Escrow: what you can edit

Encrypted: `client/`, `server/`, `shared/`. Plain and editable: `config.lua`, `config_server.lua`, `bridge/`, `adapters/`, `locales/`, `stream/`.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://ghiaccioscripts.gitbook.io/ghiaccioscripts-docs/radio/installation.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
