Features
Sound (fx-sound)
The bundled 3D audio resource used by the phone and the Music app, its settings and its full export reference.
#What it is
fx-sound is a standalone 3D audio backend. It plays web audio through the Web Audio API inside a hidden NUI page, so a sound can be positioned in the world and filtered: a low-pass muffle for a closed vehicle, an interior or water, a bass boost and a per-sound parametric EQ.
It is not a phone app and has no icon. FX Phone uses it to play ringtones and notification sounds that nearby players can hear, and fx-musicapp uses it as its audio backend.
#Requirements
| Requirement | Why |
|---|---|
| Client internet access | Media is streamed from the URLs you pass in |
| HTTPS media URLs | The NUI page is https; plain http sources are blocked or upgraded |
Access to youtube.com |
Only when YouTube links are played |
| Server outbound HTTP | Only for the update notice, when Sound.VersionCheck is on |
There is no framework requirement, no database, no items and no dependency on another resource.
#Installation
Start it before any resource that plays sound through it:
cfgensure fx-sound
#How the phone uses it
fx-sound does not register anything into the phone. FX Phone looks for it at runtime:
Config.Sound.Resourceinconfigs/config_sound.luaselects the backend:auto,fx-sound,xsoundornone. Withauto,fx-soundis used when it is started.Config.Sound.Enable3D,RangeandBystanderVolumecontrol whether and how nearby players hear another phone.- Ringtones and notification sounds heard by nearby players are played with
PlayPos, moved withSetPosition, faded withSetVolumeand ended withStop.
Consumers should detect it the same way instead of adding it to dependencies{}, because it can be stopped independently:
luaif GetResourceState('fx-sound') ~= 'started' then return end
#Config highlights
All settings are in config.lua. It is sent to the NUI page at startup, so changes need a resource restart.
| Key | Default | Meaning |
|---|---|---|
Sound.Debug |
false |
F8 logging of track end, error and buffer stall |
Sound.VersionCheck |
true |
One update notice in the server console on start |
Sound.BassFreq, Sound.Bass |
120.0, 0 / 3 / 6 / 9 dB |
Bass-boost presets used by SetMasterEQ |
Sound.Env |
none 20000, car_closed 400, interior 1500, water 350 |
Muffle cutoff in Hz per environment. Lower is more muffled |
Sound.Panning |
'equalpower' |
'HRTF' is more precise but heavier |
Sound.DistanceModel |
'inverse' |
linear, inverse or exponential |
Sound.RefDistance |
3.0 |
Metres of full volume before distance falloff starts |
Sound.RolloffFactor |
1.0 |
How fast a 3D sound fades past RefDistance |
Sound.SumNormalize |
0.85 |
Pulls back the summed level of a multi-point sound. 1.0 is full compensation, 0.0 is off |
Sound.EqBandsMax |
12 |
Maximum EQ bands on one sound |
Sound.EqSmoothing |
0.05 |
Seconds an EQ value glides; 0 is off |
Sound.PosSmoothing, Sound.RotSmoothing, Sound.EnvSmoothing |
0.05, 0.12, 0.15 |
Glide times in seconds for position, facing and muffle changes |
Sound.ProgressMs |
500 |
How often the page reports play position back to Lua |
Sound.RetryCount, Sound.RetryDelayMs |
2, 400 |
Extra attempts for a track that fails before it plays |
Sound.YouTubeApiTimeoutMs |
15000 |
How long to wait for YouTube's player script |
Sound.IdleRecycleMs |
30000 |
A paused YouTube sound is torn down after this long, keeping its position. 0 is never |
Sound.YouTubeMax |
4 |
YouTube players one client may run at once. Over the cap the quietest one is cleared and comes back when it gets louder. 0 is no cap |
Sound.YouTubeReviveVolume |
0.03 |
Volume at which a cleared sound rebuilds itself |
Sound.SwapMargin |
0.05 |
How much louder a newcomer must be to evict an existing player |
Sound.ReviveDelayMs |
4000 |
Minimum time a cleared player stays gone |
#Conventions
| Term | Meaning |
|---|---|
id |
Any string you pick. It is the handle for everything afterwards. Calling Play or PlayPos with an id that already exists replaces the sound under it. Prefix your ids, for example myjob:radio:1 |
url |
Must be https. A YouTube link is also accepted |
volume |
0.0 to 1.0. Values outside the range are clamped |
coords |
A vector3, a { x, y, z } table with named fields, or a { 1, 2, 3 } array |
env |
A key of Sound.Env: none, car_closed, interior, water |
distance |
Maximum audible range in metres |
All audio exports are client side. GetVersionStatus is server side. There are no net events and no commands.
#The listener
fx-sound does not run its own loop and never reads the player's position. The consuming resource must push the listener transform itself: position plus the camera's forward vector. Without it every 3D sound stays positioned relative to the world origin.
lualocal function camForward()
local rot = GetGameplayCamRot(2)
local rx, rz = math.rad(rot.x), math.rad(rot.z)
local cosRx = math.cos(rx)
return vector3(-math.sin(rz) * cosRx, math.cos(rz) * cosRx, math.sin(rx))
end
CreateThread(function()
while true do
exports['fx-sound']:SetListener(GetEntityCoords(PlayerPedId()), camForward())
Wait(60)
end
end)
- Only run the loop while one of your 3D sounds exists. A world of 2D-only sound needs no listener.
Wait(60)is enough. The engine glides listener position and facing between updates.
#Playback exports
#Play
Plays a 2D sound: full volume everywhere, no distance falloff.
lua---@param id string
---@param url string
---@param volume number 0.0 to 1.0
---@param loop boolean
---@param fadeIn? number Milliseconds
exports['fx-sound']:Play(id, url, volume, loop, fadeIn)
luaexports['fx-sound']:Play('myui:click', 'https://example.com/click.mp3', 0.4, false)
fadeIn ramps up from the moment audio actually starts, not from the call.
#PlayPos
Plays a 3D sound anchored in the world and attenuated by distance from the listener.
lua---@param id string
---@param url string
---@param volume number 0.0 to 1.0
---@param coords vector3|table
---@param loop boolean
---@param distance number Metres
---@param fadeIn? number Milliseconds
exports['fx-sound']:PlayPos(id, url, volume, coords, loop, distance, fadeIn)
luaexports['fx-sound']:PlayPos('myjob:boombox', url, 0.8, GetEntityCoords(ped), true, 40)
Needs the listener to be driven, see above.
#Pause
Pauses a sound.
lua---@param id string
exports['fx-sound']:Pause(id)
luaexports['fx-sound']:Pause('myjob:boombox')
A pause issued while a source is still loading is applied once it is ready.
#Resume
Resumes a paused sound.
lua---@param id string
exports['fx-sound']:Resume(id)
luaexports['fx-sound']:Resume('myjob:boombox')
#Stop
Stops a sound immediately and removes it.
lua---@param id string
exports['fx-sound']:Stop(id)
luaexports['fx-sound']:Stop('myjob:boombox')
The id stops existing: Exists returns false and OnEnd does not fire.
#FadeStop
Ramps a sound to silence, then removes it.
lua---@param id string
---@param ms number Fade length in milliseconds
exports['fx-sound']:FadeStop(id, ms)
luaexports['fx-sound']:FadeStop('song:a', 800)
- The Lua record is dropped at once:
GetPositionstops answering andOnEnddoes not fire while the engine plays out the tail. - For a crossfade, use two different ids:
FadeStopthe old one andPlayPosthe new one with afadeIn.
#Seek
Jumps to a position in the track.
lua---@param id string
---@param seconds number
exports['fx-sound']:Seek(id, seconds)
luaexports['fx-sound']:Seek('myjob:boombox', 42.5)
#Sound property exports
These apply to a live sound and take effect immediately. Calling them with an unknown id does nothing.
#SetVolume
Changes a sound's volume.
lua---@param id string
---@param volume number 0.0 to 1.0
---@param rampMs? number How long the change takes, in milliseconds
exports['fx-sound']:SetVolume(id, volume, rampMs)
luaexports['fx-sound']:SetVolume('myjob:boombox', 0.35)
Without rampMs the change uses a short default ramp suited to a slider. Pass a few hundred milliseconds for changes the listener did not ask for, such as walking behind a wall.
#SetPosition
Moves a 3D sound.
lua---@param id string
---@param coords vector3|table
exports['fx-sound']:SetPosition(id, coords)
luaexports['fx-sound']:SetPosition('myjob:boombox', GetEntityCoords(veh))
3D sounds only. The engine glides between updates.
#SetPositions
Anchors one sound at several points at once, like several speaker cabinets playing the same signal.
lua---@param id string
---@param points table[] List of vector3 or { x, y, z, heading? }
---@param distance? number Metres
---@param cone? table { inner, outer, outerGain } in degrees and linear gain
exports['fx-sound']:SetPositions(id, points, distance, cone)
luaexports['fx-sound']:SetPositions('club:main', { vector3(120.0, -1280.0, 29.0), vector3(128.0, -1280.0, 29.0) }, 40)
- Passing one point is the same as
SetPosition. - A point given as a table may carry
heading(game heading). The cabinet is then directional: full level in front,cone.outerGainbehind. - An empty list does nothing.
#SetDistance
Changes a sound's maximum audible range.
lua---@param id string
---@param distance number Metres
exports['fx-sound']:SetDistance(id, distance)
luaexports['fx-sound']:SetDistance('myjob:boombox', 60)
#SetEnvironment
Sets a per-sound muffle.
lua---@param id string
---@param env string 'none', 'car_closed', 'interior' or 'water'
exports['fx-sound']:SetEnvironment(id, env)
luaexports['fx-sound']:SetEnvironment('myjob:boombox', 'car_closed')
Applies a low-pass filter with the cutoff from Sound.Env.
#SetSpatial
Switches a sound between 3D and 2D without reloading it.
lua---@param id string
---@param spatial boolean true = 3D, false = 2D
---@param coords? vector3|table One point, or a list of points; used when turning 3D on
---@param distance? number Used when turning 3D on
exports['fx-sound']:SetSpatial(id, spatial, coords, distance)
luaexports['fx-sound']:SetSpatial('myjob:boombox', false)
The track keeps playing across the switch. Useful when the listener is sitting on top of the source, for example inside the car the speaker is in.
#SetFilters
Sets a per-sound parametric EQ.
lua---@param id string
---@param bands? table[] Ordered list of { type?, freq?, q?, gain? }; nil or {} removes the EQ
exports['fx-sound']:SetFilters(id, bands)
luaexports['fx-sound']:SetFilters('myjob:boombox', {
{ type = 'lowshelf', freq = 120.0, gain = 6.0 },
{ type = 'peaking', freq = 1000.0, gain = -3.0, q = 1.2 },
})
| Field | Default | Meaning |
|---|---|---|
type |
'peaking' |
peaking, lowshelf, highshelf, lowpass, highpass, bandpass, notch, allpass |
freq |
1000.0 |
Centre or corner frequency in Hz. frequency is read too |
gain |
0.0 |
Boost or cut in dB. Only peaking and the two shelves use it |
q |
1.0 |
Bandwidth. Higher is narrower. quality is read too |
- Bands are chained in the order given.
- When only values change (same number of bands, same types) the filters are reused and their parameters glide over
Sound.EqSmoothing. Changing the band count or a type rebuilds the chain, so send a preset as one list. - One chain serves every point of a multi-point sound.
Sound.EqBandsMaxcaps how many bands one sound may carry.
#Query exports
Answered from a local cache that the engine refreshes every Sound.ProgressMs. They never yield.
#GetPosition
Returns the play position in seconds.
lua---@param id string
---@return number seconds 0 if unknown
exports['fx-sound']:GetPosition(id)
lualocal pos = exports['fx-sound']:GetPosition('myjob:boombox')
The value lags real playback by up to Sound.ProgressMs.
#GetDuration
Returns the track length in seconds.
lua---@param id string
---@return number seconds 0 until metadata has loaded
exports['fx-sound']:GetDuration(id)
lualocal dur = exports['fx-sound']:GetDuration('myjob:boombox')
#Exists
Tells whether a sound with this id is held.
lua---@param id string
---@return boolean
exports['fx-sound']:Exists(id)
lualocal playing = exports['fx-sound']:Exists('myjob:boombox')
#GetAll
Returns every live sound id.
lua---@return string[] ids
exports['fx-sound']:GetAll()
luafor _, id in ipairs(exports['fx-sound']:GetAll()) do
if id:sub(1, 6) == 'myjob:' then exports['fx-sound']:Stop(id) end
end
Sounds outlive the resource that created them. Stop your own ids when your resource stops, matching your prefix. The list includes other resources' sounds.
#GetStats
Returns the engine's last load report.
lua---@return table|nil stats { sounds, ytAlive, ytBuilt, ytBuilt5m, audioBuilt, pageMin }
exports['fx-sound']:GetStats()
lualocal stats = exports['fx-sound']:GetStats()
Returns nil before the first report. Counts restart whenever the NUI page reloads. Meant for diagnostic tools.
#Callback exports
Attach them right after Play or PlayPos; the record already exists when that call returns. One function per id: attaching again replaces it. Calling them with an unknown id does nothing.
#OnStart
Sets a function called when audio actually begins.
lua---@param id string
---@param fn fun()
exports['fx-sound']:OnStart(id, fn)
luaexports['fx-sound']:OnStart(id, function() print('playing') end)
#OnEnd
Sets a function called when the track ends.
lua---@param id string
---@param fn fun()
exports['fx-sound']:OnEnd(id, fn)
luaexports['fx-sound']:OnEnd(id, function() playNextTrack() end)
OnEnd also fires when a source fails, so a queue driven by it moves past a dead URL. The function receives no arguments.
#Listener exports
These affect everything the local player hears. One resource should own them.
#SetListener
Sets the listener's position and facing.
lua---@param coords vector3|table
---@param forward? vector3|table Camera forward vector
exports['fx-sound']:SetListener(coords, forward)
luaexports['fx-sound']:SetListener(GetEntityCoords(PlayerPedId()), camForward())
Required for 3D sound.
#SetMasterEQ
Sets the bass-boost preset on the master output.
lua---@param preset string 'off', 'low', 'medium' or 'high'
exports['fx-sound']:SetMasterEQ(preset)
luaexports['fx-sound']:SetMasterEQ('medium')
#SetListenerEnv
Sets a listener-side muffle.
lua---@param env string 'none', 'car_closed', 'interior' or 'water'
exports['fx-sound']:SetListenerEnv(env)
luaexports['fx-sound']:SetListenerEnv(IsPedSwimmingUnderWater(PlayerPedId()) and 'water' or 'none')
#Server export
#GetVersionStatus
Returns the result of the update check.
lua---@return table status { state: string, current: string, latest: string|nil, behind: number|nil }
exports['fx-sound']:GetVersionStatus()
lualocal status = exports['fx-sound']:GetVersionStatus()
state is uptodate, outdated, ahead, unknown, error or disabled. The check runs a few seconds after start, so expect unknown right after it. It is disabled when Sound.VersionCheck = false.
#YouTube URLs
Pass a normal YouTube link to Play or PlayPos. It plays through YouTube's own player on the client, with the audio routed through the same graph, so position, muffle and bass apply as usual. Nothing is set up or resolved on your server.
- Videos whose uploader disables embedding cannot play (reported as
yt_101/yt_150). Sound.IdleRecycleMsandSound.YouTubeMaxlimit how many YouTube players a client holds.
#Troubleshooting
Set Sound.Debug = true, restart and watch the F8 console. Set it back to false afterwards.
| Line | Meaning |
|---|---|
END with time close to the duration |
The track played through |
END with time=0 started=false |
It never produced audio. Treat as a failed source |
ERROR code=2 |
Network error or blocked request |
ERROR code=4 |
Source not supported, usually an expired or IP-locked URL |
ERROR code=yt_101 / yt_150 |
The uploader disallows embedding |
ERROR code=yt_api_unavailable |
YouTube's player script never loaded. Check client connectivity |
STALL / RESUME |
The stream buffer ran dry, and for how long |
- No sound at all: confirm the URL is https, and that
ensure fx-soundcomes before the consuming resource. - 3D sounds do not move: the listener is not being driven with
SetListener.