# Sounds

koja-lib plays audio through its NUI page. Sounds can come from koja-lib's own `sounds/` folder or from any other resource.

***

## Playing a Sound (Client Export)

Play a sound for the local player directly from another resource's client script:

```lua
exports['koja-lib']:PlaySound(file, volume, soundId, loop)
```

| Parameter | Type       | Description                                |
| --------- | ---------- | ------------------------------------------ |
| `file`    | `string`   | Short name **or** full NUI URL (see below) |
| `volume`  | `number?`  | Volume 0.0 – 1.0 (default: 0.5)            |
| `soundId` | `string?`  | Unique ID for stopping the sound later     |
| `loop`    | `boolean?` | Whether to loop (default: false)           |

***

## Stopping a Sound (Client Export)

```lua
exports['koja-lib']:StopSound(soundId)
```

| Parameter | Type     | Description                        |
| --------- | -------- | ---------------------------------- |
| `soundId` | `string` | The ID used when playing the sound |

***

## Sound File Sources

### Sounds inside koja-lib

Place `.mp3` files in `web/build/sounds/` and reference them by name (without extension):

```lua
exports['koja-lib']:PlaySound('alert')           -- plays koja-lib/web/build/sounds/alert.mp3
exports['koja-lib']:PlaySound('alert', 0.8, 'myAlert', false)
```

### Sounds from another resource

Add the `.mp3` to the other resource's `files {}` block in its `fxmanifest.lua`:

```lua
-- my-script/fxmanifest.lua
files {
    'sounds/alarm.mp3',
}
```

Then pass the full NUI URL:

```lua
exports['koja-lib']:PlaySound('https://cfx-nui-my-script/sounds/alarm.mp3', 0.8, 'alarm')
```

> FiveM serves every file listed in `files {}` at `https://cfx-nui-<resourcename>/<path>`.

***

## Server Exports

Trigger sounds for players from a server script:

### PlaySoundForSource

Play a sound for a specific player.

```lua
exports['koja-lib']:PlaySoundForSource(source, file, volume, soundId, loop)
```

### PlaySoundForAll

Play a sound for every connected player.

```lua
exports['koja-lib']:PlaySoundForAll(file, volume, soundId, loop)
```

### PlayDistanceSound

Play a sound for all players within `dist` metres of `coords`. Volume fades with distance.

```lua
exports['koja-lib']:PlayDistanceSound(coords, dist, file, volume, soundId, loop)
```

| Parameter | Type       | Description                        |
| --------- | ---------- | ---------------------------------- |
| `coords`  | `vector3`  | Origin coordinates                 |
| `dist`    | `number`   | Maximum hearing distance (max 250) |
| `file`    | `string`   | Short name or full NUI URL         |
| `volume`  | `number?`  | Base volume at the origin          |
| `soundId` | `string?`  | ID for later stop                  |
| `loop`    | `boolean?` | Loop                               |

### StopSoundForAll

Stop a looping sound for every player.

```lua
exports['koja-lib']:StopSoundForAll(soundId)
```

***

## Examples

### Looping alarm that can be stopped

```lua
-- Server: start alarm
exports['koja-lib']:PlaySoundForAll('alarm', 0.6, 'heistAlarm', true)

-- Server: stop alarm after 30 seconds
SetTimeout(30000, function()
    exports['koja-lib']:StopSoundForAll('heistAlarm')
end)
```

### Distance-based explosion sound from another resource

```lua
-- server script in my-heist resource
local origin = GetEntityCoords(GetPlayerPed(source))
exports['koja-lib']:PlayDistanceSound(
    origin,
    80.0,
    'https://cfx-nui-my-heist/sounds/explosion.mp3',
    1.0
)
```

### Client: one-shot UI sound

```lua
-- client script in my-shop resource
exports['koja-lib']:PlaySound('https://cfx-nui-my-shop/sounds/purchase.mp3', 0.4)
```

***

## Net Events (alternative)

If you prefer events over exports:

```lua
-- Client: play for self
TriggerEvent('koja-lib:client:onlySourceSound', file, volume, soundId, loop)

-- Client: stop
TriggerEvent('koja-lib:client:stopSound', soundId)

-- Server: play for triggering player
TriggerServerEvent('koja-lib:server:onlySourceSound', file, volume, soundId, loop)

-- Server: play distance sound from player's position
TriggerServerEvent('koja-lib:server:distanceSound', dist, file, volume, soundId, loop)
```

## Related pages

- [Callbacks](/koja-lib/api-reference/client-api/callbacks) — koja-lib provides a callback system that lets client scripts request data from the server and vice versa.
- [Inventory](/koja-lib/api-reference/client-api/inventory) — Client-side inventory functions let you check what items the local player has without a server round-trip.
- [DUI](/koja-lib/api-reference/client-api/dui) — DUI (Dynamic UI) allows you to render a web page as a texture on any in-game surface — screens, billboards, laptops, phones, etc.
- [Money](/koja-lib/api-reference/client-api/money) — Retrieve the local player's money balance from the client side via a server callback.
- [Keybinds](/koja-lib/api-reference/client-api/keybinds) — Register persistent key bindings that players can rebind in the GTA V settings menu.
- [Notifications](/koja-lib/api-reference/client-api/notifications) — koja-lib provides two notification interfaces: SendNotify (routes through the configured backend) and LibNotify (built-in koja-lib notification).
- [Client API](/koja-lib/api-reference/client-api) — back to the section overview