Developer integration guide

Choose a supported seam

Authority and data flow

Player input and NUI
        |
        v
san_andreas_radio client
        | validated requests
        v
san_andreas_radio server <--- snapshots/events --- san_andreas_dispatch
        | authoritative vehicle state
        v
Radio client audio adapter
        |
        +--- san_andreas_sound provider (default)
        +--- xSound provider or another registered backend

Synchronization model

Native Sound integration pattern

fx_version 'cerulean'
game 'gta5'
dependency 'san_andreas_sound'
client_script 'client.lua'

local RESOURCE = GetCurrentResourceName()
local ownedSounds = {}

local function playVehicleAlert(vehicle)
    local netId = NetworkGetNetworkIdFromEntity(vehicle)
    local name = ('%s:alert:%d'):format(RESOURCE, netId)
    ownedSounds[name] = true

    return exports.san_andreas_sound:PlayPositional({
        name = name,
        url = 'https://cdn.example.com/authorized-alert.ogg',
        volume = 0.35,
        entityHandle = vehicle,
        entityNetId = netId,
        maxDistance = 55.0,
        trunkAffectsEnclosure = true,
        relationshipOverrides = {
            inside = { volumeMultiplier = 0.65, maxDistance = 25.0 },
            outside = { volumeMultiplier = 1.0, maxDistance = 55.0 }
        },
        loop = false,
        destroyOnFinish = true,
        onPlayStart = function(info)
            print(('started %s'):format(info.id))
        end
    })
end

AddEventHandler('onClientResourceStop', function(resourceName)
    if resourceName ~= RESOURCE then return end
    for name in pairs(ownedSounds) do
        exports.san_andreas_sound:Destroy(name)
    end
end)

• Use stable resource-prefixed sound names to prevent collisions and make cleanup ownership auditable.
• Supply both the local handle and network ID only when the caller already owns the client entity; the network ID is the shared contract.
• Relationship override profile names normalize camel/Pascal aliases. Each override can set volumeMultiplier from 0.0-2.0 and maxDistance of at least 0.1.
• PlayPositional returning true means local validation queued the request. Use onPlayStart for renderer confirmation.
• Destroy only names owned by the current resource when that same resource stops.

Target one validated client

RegisterNetEvent('my_resource:server:requestNotice', function(x, y, z)
    local target = tonumber(source)
    if not target or target <= 0 then return end

    -- Validate authorization and coordinates for this resource here.
    exports.san_andreas_sound:PlayUrlPos(
        target,
        ('my_resource:notice:%d'):format(target),
        'https://cdn.example.com/authorized-notice.ogg',
        0.30,
        {
            x = tonumber(x) or 0.0,
            y = tonumber(y) or 0.0,
            z = tonumber(z) or 0.0
        },
        false,
        { maxDistance = 30.0, destroyOnFinish = true }
    )
end)

Consume Dispatch, Station Pack, and Radio state

local tx = exports.san_andreas_dispatch:GetChannel('police')
if tx and tx.offset < tx.duration then
    print(tx.label, tx.url, tx.offset, tx.duration)
end

AddEventHandler(
    'san_andreas_dispatch:server:transmissionChanged',
    function(channelId, descriptor)
        if channelId ~= 'police' then return end
        -- Choose recipients and relay only required fields.
    end
)

for _, station in ipairs(
    exports.san_andreas_station_pack:GetStations()
) do
    print(station.id, station.label)
end

local snapshot = exports.san_andreas_station_pack:GetSnapshot()
local source = snapshot['SERVER_VINEWOOD_DEMO']
if source and source.track then
    print(source.track.kind, source.track.artist, source.track.title, source.offset)
end

local state = exports.san_andreas_radio:GetVehicleRadioState(vehicleNetId)
if not state then return end

local summary = {
    powered = state.powered == true,
    mode = state.mode,
    station = state.station,
    volume = state.volume,
    revision = state.revision
}

if state.bluetooth then
    local position = state.bluetooth.position or 0.0
    if state.bluetooth.playing then
        position = position + math.max(0, os.time() - state.bluetooth.startedAt)
    end
    summary.bluetoothPosition = position
end

• Dispatch's local event marks transmission start only. offset >= duration means the channel is in its synchronized silent gap.
• Station Pack getters return safe copied definitions and current program sources.
• Radio returns a raw internal state table. Copy required fields immediately; do not mutate or retain it and do not call internal player-authenticated events as setters.
• If a server-owned feature needs a Radio mutation, add a validated public server export to Radio and document its authority rules rather than bypassing validation.

Add a Radio audio provider

Radio core calls SanAndreasRadioAudio only. Provider-specific normalization belongs in client/audio/providers and server/audio/providers, loaded before Radio core scripts.

SanAndreasRadioAudio.registerProvider(name, provider)

isAvailable()

isProviderResource(resourceName)

playPositional(options)

destroy(name)

setPosition(name, position)

setDistance(name, distance)

setVolume(name, volume)

reset()

setTime(name, position)

setPlaying(name, playing)

setSpectrumTarget(name, callback, slot)

SanAndreasRadioAudio.registerProvider(name, provider)

isAvailable()

isProviderResource(resourceName)

1. Audit which Radio adapter operations the backend genuinely supports.
2. Create matching client and server provider files and register the same provider name on both sides.
3. Normalize provider-specific options inside the adapter without changing Radio station or lifecycle code.
4. Load provider files before core scripts, map the provider resource in Config.Audio.Resources, and select Config.Audio.Provider.
5. Test same-name replacement, initial distance, seek, pause/resume, natural completion, destroy, resource restart, vehicle deletion, and two-client synchronization.
6. Document unsupported optional operations and return false rather than pretending success.

Extend the live scanner voice provider

Public API index by component

Security, privacy, and operations

• Keep Bluetooth HTTP and direct URLs disabled unless the server has an explicit trusted requirement. Restrict hosts and length, reject credentials and control characters, and revalidate everything on the server.
• Retain Radio state-change and metadata rate limits and test repeated rejected requests as well as normal use.
• Before replacing Dispatch media, listen to every file and document permission, privacy review, source, review date, license, and a recoverable staging plan.
• Distinguish private server playback, rebroadcasting, inclusion in a downloadable resource, and public redistribution; permission for one does not imply the others.
• Treat successful Builder validation as a packaging result, never proof of ownership, consent, privacy compliance, or runtime playback.

1. Use at least two clients and two vehicles on a staging server.
2. Exercise all direct, fallback, native, server-hosted, Bluetooth, scanner, and optional voice paths.
3. Move between world/inside/outside/other-vehicle profiles, doors/windows/trunk, boats, and occlusion while inspecting diagnostics.
4. Stop and start each component independently and confirm no unrelated resource is stopped and no audio remains orphaned.
5. Measure client/server frame time, bandwidth, NUI memory, active sound count, renderer mode, and errors in an area with representative nearby vehicles.

Terminology and source paths