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.
What proximity hearing does
Section titled “What proximity hearing does”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
rangemetres 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.
What the earpiece does
Section titled “What the earpiece does”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. |
Whose earpiece counts
Section titled “Whose earpiece counts”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:
- Anna and Ben are on the same channel. Chris stands next to Ben and is not on the channel.
- Anna talks. Ben hears Anna on his radio. If Ben has no earpiece, Chris hears Anna quietly from Ben’s radio.
- 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.
How players get the earpiece
Section titled “How players get the earpiece”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.
How the items are registered
Section titled “How the items are registered”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. |
Fitting the earpiece
Section titled “Fitting the earpiece”- The player needs a radio and an earpiece in the inventory.
- The player uses the earpiece item. With
ox_inventorythe player can also right click it and choose Attach to Radio. - The earpiece item is used up and fitted to the first radio that does not already have one.
- The player sees a notification. In the radio, the Earpiece row in the Settings tab changes from
NONEtoFITTED.
Removing the earpiece
Section titled “Removing the earpiece”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.
Per radio or per player
Section titled “Per radio or per player”| 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 Earpiece row in the radio
Section titled “The Earpiece row in the radio”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. |
Interaction with proximity settings
Section titled “Interaction with proximity settings”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:
rangesets how far the sound carries.baseVolumeandedgeVolumeset how loud it is close to the radio and at the edge.followListenerVolumemakes a radio that is turned down get overheard more quietly.skipWithinProximitykeeps 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.
Changes made by other resources
Section titled “Changes made by other resources”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.
Quick reference for admins
Section titled “Quick reference for admins”| 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. |
