San Andreas Dispatch

Channel and scheduler contract

Dispatch is a server-authoritative local call scheduler. It selects and randomizes MP3 clips, publishes lore-friendly metadata and shared timestamps, and leaves playback to Radio or another consumer.

initial delay
-> choose a randomized clip
-> publish URL, revision, start time, duration, and metadata
-> clip expires
-> randomized silent gap
-> choose the next clip

Installation and startup verification

• Keep the exact san_andreas_dispatch folder name.
• Dispatch itself has no framework, database, or audio-provider dependency.
• Keep matching MP3 files under audio/<channel> and catalog entries in shared/catalog.lua.
• Use a consumer such as San Andreas Radio to select recipients and render the descriptor.
• Start Dispatch before Radio so the first scanner snapshot can use local programming immediately.

ensure san_andreas_sound
ensure san_andreas_dispatch
ensure san_andreas_station_pack
ensure san_andreas_radio

1. Start Dispatch and watch the server console for catalog errors.
2. Start Radio and enter a vehicle mapped to each intended channel.
3. Confirm the scanner HUD shows the correct channel in STANDBY.
4. Wait for a scheduled call and confirm the state changes to RECEIVING.
5. Confirm system, talkgroup, destination, and frequency are lore-friendly.
6. Use a second client and confirm both hear the same call at the same offset.

Global and per-channel configuration

Config.Channels.air = {
    Enabled = true,
    Label = 'San Andreas Air Operations',
    PublicMetadata = {
        Label = 'Air Traffic Control',
        Talkgroup = 'LSIA-TWR',
        TalkgroupLabel = 'LSIA Tower',
        Frequency = '119.8000',
        System = 'San Andreas Aviation Authority'
    },
    MinGapMs = 30000,
    MaxGapMs = 60000
}

Connect Dispatch to Radio

Config.Dispatch = {
    Enabled = true,
    Resource = 'san_andreas_dispatch',
    ProfileChannels = {
        emergency = 'police',
        fire = 'fire',
        ems = 'ems',
        service = 'service',
        aviation = 'air',
        marine = 'marine'
    }
}

Maintain the local call catalog

Treat every replacement as one transaction: media, exact duration, catalog entry, provenance, privacy review, attribution, and acceptance testing must remain aligned.

1. Confirm that the candidate may be downloaded, hosted, and distributed for the intended release.
2. Listen from beginning to end. Reject private names, real addresses, phone numbers, plates, medical details, or other inappropriate identifying information.
3. Trim long silence without cutting words and add very short edge fades when needed.
4. For speech, MP3 mono at 48 kHz and 64-96 kbps is a practical target. Use lowercase ASCII filenames without spaces.
5. Measure the final encoded file with ffprobe; never reuse a duration measured before trimming or conversion.
6. Stage the MP3 and catalog edit outside the active resource, then swap them together.
7. Update ATTRIBUTION.md and any private audit record, restart Dispatch, check catalog validation, and verify the affected channel in game.

ffprobe -v error -show_entries format=duration -of default=noprint_wrappers=1:nokey=1 state-dispatch-078.mp3

{
    id = 'police_replacement_078',
    file = 'audio/police/state-dispatch-078.mp3',
    duration = 12.736,
    system = 'source-system-id',
    talkgroup = 1,
    talkgroupLabel = 'Source talkgroup',
    description = 'Internal audit description',
    recordedAt = '2026-08-01T12:00:00.000Z',
    sourcePage = 'https://source.example/system/page',
    callId = 'source-call-id'
}

• Every top-level catalog key must have a matching Config.Channels entry.
• IDs and file paths must be unique; paths must be normalized, relative, and resolve beneath the resource.
• Every referenced file must exist, be MP3, and be declared by the manifest; no unreferenced media should remain.
• Durations must be positive and match the final encoded file.
• Player-facing lore text comes from Config.Channels.PublicMetadata, not raw catalog provenance.
• Adding clips must not bypass shuffled-deck and no-repeat behavior.

Add a new channel

1. Create a disabled Config.Channels entry with appropriate public metadata and gap settings.
2. Add the audio/<channel> folder and an aligned Catalog.<channel> table of audited local MP3 entries.
3. Add the channel ID to CHANNEL_ORDER in san_andreas_dispatch/server/main.lua for the bundled resource.
4. Add Config.Dispatch.ProfileChannels.<profile> = '<channel>' in Radio and create or adapt the matching scanner profile.
5. Update automated catalog expectations for IDs, counts, prefixes, metadata, and timing before enabling the channel.

Public server API

GetSnapshot()

GetChannel(channelId)

GetCatalogCounts()

(channelId, descriptor)

Verification, troubleshooting, and privacy

• Enter one eligible vehicle for every enabled profile and confirm correct standby metadata.
• Listen to several calls per channel and verify shuffled order, no immediate boundary repeat, exact stop time, and configured quiet gaps.
• Use two clients on the same channel and compare offsets.
• Test startup fade, pause, vehicle exit/re-entry, deletion, and independent resource restarts.
• Confirm Radio suppresses GTA's native scanner only for intended profiles.