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.Resource in configs/config_sound.lua selects the backend: auto, fx-sound, xsound or none. With auto, fx-sound is used when it is started.
  • Config.Sound.Enable3D, Range and BystanderVolume control whether and how nearby players hear another phone.
  • Ringtones and notification sounds heard by nearby players are played with PlayPos, moved with SetPosition, faded with SetVolume and ended with Stop.

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: GetPosition stops answering and OnEnd does not fire while the engine plays out the tail.
  • For a crossfade, use two different ids: FadeStop the old one and PlayPos the new one with a fadeIn.

#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.outerGain behind.
  • 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.EqBandsMax caps 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.IdleRecycleMs and Sound.YouTubeMax limit 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-sound comes before the consuming resource.
  • 3D sounds do not move: the listener is not being driven with SetListener.