Skip to content

Radio earpiece

The radio earpiece is an item that you fit to a radio. Once it is fitted, only the radio’s owner hears the radio. People standing nearby do not. The earpiece belongs to the proximity hearing feature of Kivo Radio, so read the first section of this page before you set it up.

When a transmission comes out of a player’s radio, everyone standing close to that player hears it too, quietly. This is proximity hearing, and it is on by default. In this documentation it is also called overhearing, and a radio that can be overheard is said to “leak”.

  • The sound carries as far as range metres from the radio (3 metres by default).
  • It is loudest right at the radio and gets quieter with distance, until it reaches a low level at the edge of range.
  • It works without any framework and without items.

Players who are on the channel already hear the transmission on their own radio. A player who can already hear the talker with normal voice chat keeps the normal voice and does not get an extra copy (see skipWithinProximity).

Settings are on the Configuration page.

Fitting an earpiece to a radio stops that radio from leaking. The owner hears the radio as normal. Nobody standing near the owner hears it. The earpiece only affects the sound that comes out of the radio. Normal voice chat is not affected, and the radio keeps working in every other way.

Situation Does a bystander in range hear the transmission?
No earpiece fitted Yes, quietly, fading with distance.
Earpiece fitted No.
Radio switched off (power knob or /m) No. The radio is not playing anything.
The bystander is on the same channel They hear it through their own radio as usual.
The bystander can already hear the talker normally They hear the normal voice. No extra sound is added.
Config.RadioProximity.enabled = false Nobody overhears anything, so the earpiece makes no difference.
Config.Items.enabled = false The earpiece does not exist and every radio can be overheard.

The sound that bystanders overhear comes out of the radio of the player who is receiving the transmission, not out of the talker. So the earpiece that matters is the one on the receiving radio:

  1. Anna and Ben are on the same channel. Chris stands next to Ben and is not on the channel.
  2. Anna talks. Ben hears Anna on his radio. If Ben has no earpiece, Chris hears Anna quietly from Ben’s radio.
  3. If Ben has an earpiece fitted, Chris hears nothing from Ben’s radio.

Anna’s earpiece does not change what comes out of Ben’s radio. To keep a whole group’s radio traffic away from bystanders, every member of the group needs an earpiece.

Item Default name Config key
Radio radio Config.Items.radio
Earpiece radio_earpiece Config.Items.earpiece

Both names can be changed in config/items.lua. The names in the config and in your inventory must be identical.

Kivo Radio has no setting for handing out the earpiece. Players get it from whatever your server already uses to hand out items: a shop, a crafting script, a job starter kit or an admin give command. Add radio_earpiece there.

Register both items in your inventory once. The exact entries are on the Installation page.

Inventory Where you add the items Where the earpiece is stored
ox_inventory (also Kivo Inventory) ox_inventory/data/items.lua In the metadata of the radio item.
qb-inventory with qb-core or qbx_core shared/items.lua of the framework For the player.
ESX default inventory The items table of the database For the player.
qs-inventory and other inventories The item list of that inventory For the player.
  1. The player needs a radio and an earpiece in the inventory.
  2. The player uses the earpiece item. With ox_inventory the player can also right click it and choose Attach to Radio.
  3. The earpiece item is used up and fitted to the first radio that does not already have one.
  4. The player sees a notification. In the radio, the Earpiece row in the Settings tab changes from NONE to FITTED.

There are two ways:

  • Open the radio, go to the Settings tab and press REMOVE on the Earpiece row.
  • With ox_inventory, right click the radio and choose Remove Earpiece.

The earpiece item goes back into the player’s inventory. Once it is removed, the radio can be overheard again.

If your inventory interface does not show item buttons, fitting by using the item and removing in the Settings tab still work.

Inventory Storage What this means
ox_inventory The radio item’s metadata The earpiece is fitted to one specific radio. If a player drops that radio and picks up a different one, the new radio can be overheard until an earpiece is fitted to it.
qb-inventory, qs-inventory, ESX default and others Stored for the player It plays the same, with one difference: a player who carries two radios has both silenced.

Config.Inventory = "auto" picks ox_inventory when it is running and the player based storage otherwise. You can force one with "ox" or "fallback". The earpiece is stored in a different place in each mode, so choose a mode before you go live and keep it.

The row is in the Settings tab.

Display Meaning
NONE No earpiece is fitted. Anyone within a few metres can hear this radio.
FITTED An earpiece is fitted. Only the owner can hear the radio. A REMOVE button appears next to it.
Row missing The earpiece is not available on your server. See Examples and troubleshooting.

The earpiece only decides whether a radio can be overheard. Everything else about how a radio without an earpiece sounds comes from config/proximity.lua:

  • range sets how far the sound carries.
  • baseVolume and edgeVolume set how loud it is close to the radio and at the edge.
  • followListenerVolume makes a radio that is turned down get overheard more quietly.
  • skipWithinProximity keeps the normal voice when the talker is already close to the bystander.

Proximity hearing and the earpiece apply to every channel in the same way. The config has no option to switch them on or off for one channel.

The overheard sound fades with distance but does not come from the direction of the radio. This is a limit of the voice system and cannot be changed in the config.

Kivo Radio remembers whether a player has an earpiece fitted for Config.Items.cacheTtlMs milliseconds (10 seconds by default). Fitting and removing through Kivo Radio updates this at once. If another script gives or takes radios or earpieces, the change is noticed within that time. Lower the value if you need it faster.

Goal What to do
Turn the earpiece feature off Config.Items.enabled = false in config/items.lua. Every radio can then be overheard.
Turn off proximity hearing and the earpiece need Config.RadioProximity.enabled = false in config/proximity.lua.
Use other item names Change Config.Items.radio and Config.Items.earpiece, and rename the items in your inventory to match.
Force storage per radio or per player Config.Inventory = "ox" or "fallback".
Hand out the earpiece Add radio_earpiece to a shop, crafting recipe or starter kit.