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

# Voice API

Exports and events for radio, phone calls, voice ranges and muting.

Use these exports to connect radios, phones, HUDs and admin tools to kaze\_sound voice chat. For setup and controls, see [Voice chat](/kazescripts/kaze_sound/voice-chat.md).

{% hint style="info" %}
Every pma-voice export name also works, both as `exports.kaze_sound:setRadioChannel(...)` and as `exports['pma-voice']:setRadioChannel(...)`.
{% endhint %}

## Client exports

### Radio

| Export                                                   | Description                                                                            |
| -------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| `SetRadioChannel(channel)`                               | Join a radio channel. `0` leaves.                                                      |
| `GetRadioChannel()`                                      | Current radio channel.                                                                 |
| `SetRadioEnabled(state)`                                 | Radio power. While off, the player hears no radio traffic.                             |
| `setRadioVolume(0-100)` / `getRadioVolume()`             | Radio volume. Saved between sessions.                                                  |
| `SetMicClicks(state)`                                    | Turn radio clicks on or off. Saved between sessions.                                   |
| `IsRadioTalking()`                                       | `true` while the player transmits.                                                     |
| `addRadioDisableBit(bit)` / `removeRadioDisableBit(bit)` | Block the radio for a reason (for example handcuffed) without affecting other reasons. |
| `setRadioTalkAnim(dict, clip)`                           | Custom talking animation.                                                              |
| `setDisableRadioAnim(state)`                             | Turn the talking animation off for this player.                                        |

```lua
-- Join channel 1 when the radio is turned on
exports.kaze_sound:SetRadioEnabled(true)
exports.kaze_sound:SetRadioChannel(1)
```

### Phone calls

| Export                                     | Description                                                                  |
| ------------------------------------------ | ---------------------------------------------------------------------------- |
| `SetCallChannel(channel)`                  | Join a call. Every player on the same number hears each other. `0` hangs up. |
| `GetCallChannel()`                         | Current call channel.                                                        |
| `setCallVolume(0-100)` / `getCallVolume()` | Call volume. Saved between sessions.                                         |

```lua
-- Both players join the same call number
exports.kaze_sound:SetCallChannel(callId)

-- Hang up
exports.kaze_sound:SetCallChannel(0)
```

### Ranges

| Export                                                | Description                                                                   |
| ----------------------------------------------------- | ----------------------------------------------------------------------------- |
| `GetVoiceMode()`                                      | Returns the mode index, name and range.                                       |
| `overrideProximityRange(range, lockCycle?)`           | Force a range, for example a megaphone. Pass `true` to block range switching. |
| `clearProximityOverride()`                            | Restore the player's own range.                                               |
| `setAllowProximityCycleState(state)`                  | `true` blocks range switching.                                                |
| `addVoiceMode(range, name)` / `removeVoiceMode(name)` | Add or remove a range.                                                        |

### Muting

| Export                       | Description                                      |
| ---------------------------- | ------------------------------------------------ |
| `toggleMutePlayer(serverId)` | Local mute: only this player stops hearing them. |
| `isPlayerMuted(serverId)`    | Whether they're locally muted.                   |
| `getMutedPlayers()`          | Table of locally muted players.                  |

### Advanced

| Export                                                 | Description                                                                                                                              |
| ------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `registerCustomSubmix(fn)`                             | Register your own voice effect. `fn` returns `{ name, submixId }`. Apply it to a player by setting their `submix` state bag to the name. |
| `setEffectSubmix('radio'\|'call', submixId)`           | Replace the radio or call effect.                                                                                                        |
| `overrideProximityCheck(fn)` / `resetProximityCheck()` | Custom rule for who hears the player.                                                                                                    |
| `setListenerOverride(state)`                           | Hear everyone around the camera, like spectating.                                                                                        |
| `setVoiceState('proximity'\|'channel', channel?)`      | Switch to a fixed voice channel (everyone in it hears each other) and back.                                                              |

## Server exports

| Export                              | Description                                                        |
| ----------------------------------- | ------------------------------------------------------------------ |
| `SetPlayerRadio(source, channel)`   | Set a player's radio channel.                                      |
| `SetPlayerCall(source, channel)`    | Put a player in a call, `0` to hang up.                            |
| `GetPlayersInRadioChannel(channel)` | Players on a channel, as `{ [source] = isTalking }`.               |
| `AddChannelCheck(channel, fn)`      | Only let players join if `fn(source)` returns `true`.              |
| `RemoveChannelCheck(channel)`       | Remove the check.                                                  |
| `OverrideRadioNameGetter(fn)`       | Custom name shown to radio members.                                |
| `ToggleMute(source, seconds?)`      | Mute a player for everyone. Unmutes automatically after `seconds`. |

```lua
-- Police-only radio channels 1 to 10
for channel = 1, 10 do
    exports.kaze_sound:AddChannelCheck(channel, function(source)
        local player = exports.qbx_core:GetPlayer(source)
        return player and player.PlayerData.job.name == 'police'
    end)
end
```

## Events

| Event                           | Side   | Arguments                          | Fired when                                                      |
| ------------------------------- | ------ | ---------------------------------- | --------------------------------------------------------------- |
| `kaze_sound:voice:radioActive`  | client | `talking`                          | This player starts or stops transmitting.                       |
| `kaze_sound:voice:radioTalking` | client | `serverId`, `talking`              | Someone on this player's radio channel starts or stops talking. |
| `kaze_sound:voice:modeChanged`  | client | `index`, `name`                    | This player changes voice range.                                |
| `kaze_sound:voice:playerMuted`  | server | `target`, `by`, `muted`, `seconds` | An admin mutes or unmutes a player.                             |

## State bags

| State bag                      | Value                                                 |
| ------------------------------ | ----------------------------------------------------- |
| `proximity`                    | `{ index, distance, mode }` of the current range.     |
| `radioChannel` / `callChannel` | Current radio channel and call, `0` if none.          |
| `radioActive`                  | `true` while transmitting.                            |
| `disableRadio`                 | Radio block bits, `0` when the radio is usable.       |
| `muted`                        | `true` while muted by an admin.                       |
| `submix`                       | Name of a custom voice effect applied to this player. |