# Installation

### Dependencies

<details>

<summary>oxmysql</summary>

#### Installation

* Download the [latest build](https://github.com/overextended/oxmysql/releases/latest) of oxmysql (not the source code).
* Extract the contents of the archive to your resources folder.
* Start the resource near the top of your resources in your server.cfg.

#### Required version

Your oxmysql version must be <mark style="color:yellow;">2.0.0 or above</mark> in order to work with our system.

#### Use the built version

Make sure you have downloaded the <mark style="color:yellow;">built version</mark> of oxmysql! If you download the source code, then the resource won't start and queries are unable to execute.&#x20;

The built version can be downloaded from the [releases page](https://github.com/overextended/oxmysql/releases/latest) (oxmysql.zip).

</details>

<details>

<summary>ox_lib</summary>

#### Installation

* Download the [latest build](https://github.com/overextended/ox_lib/releases/latest) of ox\_lib (not the source code).
* Extract the contents of the archive to your resources folder.
* Start the resource near the top of your resources in your server.cfg.

#### Use the built version

Make sure you have downloaded the <mark style="color:yellow;">built version</mark> of ox\_lib! If you download the source code, then it won't function correctly and the application will have problems.&#x20;

The built version can be downloaded from the [releases page](https://github.com/overextended/ox_lib/releases/latest) (ox\_lib.zip).

</details>

### Installing the resource

1. Make sure you have the [dependencies](#dependencies) listed above installed.
2. Extract the contents of the archive to your resources folder.
3. Ensure the resource is set to start up with the server.

### Framework

If you're using QB, QBX or ESX, your framework will be automatically detected.

For other frameworks, please follow the provided instructions:

<details>

<summary>Using other frameworks</summary>

Firstly, in <mark style="color:blue;">editable\_shared/config.lua</mark> change the framework to <mark style="color:blue;">CUSTOM</mark>.

Secondly, in <mark style="color:blue;">editable\_server/framework.lua</mark>, go to the <mark style="color:blue;">supportedFrameworks</mark> variable and fill in the following:

* resourceName
* loadFramework
* prepareInventory
* giveItem
* removeItem
* getCash
* removeCash
* getIdentifier
* getVehicleIdentifier
* getLoggingText

</details>

### Youtube API key <a href="#youtube-api-key" id="youtube-api-key"></a>

Fill out <mark style="color:blue;">youtubeApiKey</mark> in <mark style="color:blue;">editable\_server/config.lua.</mark>

We have detailed insturctions on how to obtain the API key at [️2️⃣ Obtaining Youtube API key](https://docs.rahe.dev/our-scripts/speakers/integration#id-2-obtaining-youtube-api-key). We recommend following those instructions carefully to get your API key.

### Using the resource <a href="#using-the-resource" id="using-the-resource"></a>

Use the command <mark style="color:blue;">/speakers</mark> in-game to open the speaker creation menu.

**Speaker types**

> Speaker types grant you access to an unlimited amount of different, customizable speakers, each with their own unique properties, such as different 3D models, audio filters and many more.
>
> A set of predefined speaker types will be automatically generated for your comfort and in order to demonstrate the endless abilities of our resource.
>
> 🚩Use the command <mark style="color:blue;">/speakertypes</mark> to create new or edit existing speaker types.

<details>

<summary>🎧 Using forced filters</summary>

For maximum immersion we have introduced a unique funcionality.&#x20;

Forced filters are filters that automatically apply audio effects to speakers in specific situations.&#x20;

Types of forced filters:&#x20;

➖Always on - applied always, regardless of context.&#x20;

➖Interior difference - applied the speaker and player are in different interiors.&#x20;

➖Vehicle based - applied when the speaker is inside a vehicle with closed windows/doors.

When creating new speaker types, you can customize filter intensity and other parameters.

</details>

<details>

<summary>⚙️ Permissions</summary>

When creating new speaker types, permissions are a required field. Here's a list of available permissions and their functions:

* PERMISSION\_QUEUE: Enables queue usage
* PERMISSION\_CARRY: Allows carrying (requires attachData in speaker type)
* PERMISSION\_STORE: Enables storage after creation (ideal for one-time use)
* PERMISSION\_PUBLIC: Allows marking as public
* PERMISSION\_RENAME: Enables renaming
* PERMISSION\_FILTERS: Allows extra filter usage
* PERMISSION\_SETTINGS: Grants access to settings menu
* PERMISSION\_PERMANENT: Allows marking as permanent
* PERMISSION\_ADD\_GROUP: Enables adding to a speaker group
* PERMISSION\_PLAY\_MUSIC: Allows music playback (useful for group-only speakers)
* PERMISSION\_PAUSE\_RESUME: Enables pause/resume functionality
* PERMISSION\_VOLUME\_RANGE: Allows volume/range adjustments
* PERMISSION\_VEHICLE\_ATTACH: Enables vehicle attachment
* PERMISSION\_GIZMO: Allows gizmo usage (for vehicle attachment or moving permanent speakers)

</details>

**Speaker groups**

> Speaker groups allow you to connect different speakers to play the same audio.
>
> This allows you to create very immersive surround sound environments, basically granting you your own sandbox audio tool.
>
> 🚩Use the command <mark style="color:blue;">/speakergroup</mark> to create or access speaker groups.

**All available commands**

{% tabs %}
{% tab title="/speakers" %}
This command can be used to access the speaker creation menu.

See [1️⃣ Speaker creation](https://docs.rahe.dev/our-scripts/speakers/integration#id-1-speaker-creation) for more info.
{% endtab %}

{% tab title="/speakertypes" %}
This command can be used to access the [Speaker types](https://kalms-organization.gitbook.io/speakers-test/our-scripts/speakers/installation#speaker-types) menu.
{% endtab %}

{% tab title="/speakergroup" %}
This command can be used to access the [Speaker groups](https://kalms-organization.gitbook.io/speakers-test/our-scripts/speakers/installation#speaker-groups) menu.
{% endtab %}

{% tab title="/musicvolume" %}
This command can be used to control the volume of the resource.

Instead players having to go to the Windows Volume Mixer and mess with the Chromium Subprocess Volume, players can adjust their personal volume in-game.
{% endtab %}
{% endtabs %}

**Vehicles**

> Speakers can be attached to vehicles and their states saved to your database.
>
> This ensures that speakers remain attached to player-owned vehicles even after storage and respawning.
>
> To enable this feature:
>
> ➖ In <mark style="color:blue;">editable\_server/config.lua</mark>, set <mark style="color:blue;">vehicleSaving</mark> to <mark style="color:blue;">true</mark>.
>
> ➖ In <mark style="color:blue;">editable\_server/framework.lua</mark>, make sure <mark style="color:blue;">getVehicleIdentifier</mark> function is filled.
>
> ➖ Based on your garage resource, add the vehicle created event

{% tabs %}
{% tab title="qb-garages" %}
In qb-garages/server/main.lua add this line (like in the screenshot):

```
CreateThread(function()
    Wait(2000)
    TriggerEvent('rahe-speakers:server:vehicleSpawnedByServer', source, veh)
end)
```

<figure><img src="https://2340261896-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FH10xunhFUE8KSIDcSB6v%2Fuploads%2F5nIbuojj1sAlbb8oUAxu%2FCode_3GeQ8SpwQs.png?alt=media&#x26;token=326f63db-ed23-4bc5-a0b3-9efb9a41fc71" alt=""><figcaption></figcaption></figure>

Click this link to view the code on Github: [qb-garages/server/main.lua](https://github.com/qbcore-framework/qb-garages/blob/main/server/main.lua#L133)
{% endtab %}

{% tab title="esx\_garage" %}
In <mark style="color:blue;">esx\_garage/server/main.lua</mark> add this line (like in the screenshot):

```
CreateThread(function()
    Wait(2000)
    TriggerEvent('rahe-speakers:server:vehicleSpawnedByServer', source, vehicle)
end)
```

<figure><img src="https://2340261896-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FH10xunhFUE8KSIDcSB6v%2Fuploads%2Fp0O1TXZZ5s2lSBnKWNkn%2Fimage334.png?alt=media&#x26;token=456db40c-97f9-44ed-8710-ab2c3d372d57" alt=""><figcaption></figcaption></figure>

Click this link to view the code on Github: [esx\_garage/server/main.lua](https://github.com/esx-framework/esx_garage/blob/main/server/main.lua#L21)
{% endtab %}

{% tab title="cd\_garage" %}
In <mark style="color:blue;">cd\_garage/configs/client\_customise\_me.lua</mark> add this line (like in the screenshot) to the function <mark style="color:blue;">VehicleSpawned</mark>:

```
TriggerServerEvent('rahe-speakers:server:vehicleSpawnedByClient', VehToNet(vehicle))
```

<figure><img src="https://2340261896-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FH10xunhFUE8KSIDcSB6v%2Fuploads%2Fn3BrRrwOuYk2PxSYl6yZ%2Fspaces2FKFedjkS99395uPLNodPl2Fuploads2FQOZEcAgFcswhL8coXR872FCode_NUu58Cg5YN%20(1).png?alt=media&#x26;token=9444b58b-af43-4369-8065-dc8ae73edd72" alt="" width="563"><figcaption></figcaption></figure>
{% endtab %}

{% tab title="jd\_advanced" %}
If you are using <mark style="color:blue;">jg-advancedgarages</mark>, everything will work out of box as long as you have filled previous prequisites.
{% endtab %}

{% tab title="CUSTOM" %}
🚩If your garage resource is spawning vehicles on client-side&#x20;

After vehicle creation, trigger this event:

```
TriggerServerEvent('rahe-speakers:server:vehicleSpawnedByClient', VehToNet(vehicle))
```

Note: Make sure to pass <mark style="color:blue;">vehicle network ID</mark> to the event.&#x20;

🚩If your garage resource is spawning vehicles on server-side&#x20;

After vehicle creation, trigger this event:

```
TriggerEvent('rahe-speakers:server:vehicleSpawnedByServer', source, vehicleEntityId)
```

Note: Make sure to pass <mark style="color:blue;">player source</mark> and <mark style="color:blue;">vehicle entity ID</mark> to the event.
{% endtab %}
{% endtabs %}

That's it! Speaker states will be saved when attached to database-saved vehicles.