WebSound Library

Web-based audio content downloading, caching, and playback system for the Lilia framework.

---

Overview

The websound library provides comprehensive functionality for managing web-based audio content in the Lilia framework. It handles downloading, caching, validation, and playback of sound files from HTTP/HTTPS URLs, with automatic local storage and retrieval. The library operates on both server and client sides, providing seamless integration with Garry's Mod's sound system through enhanced versions of sound.PlayFile, sound.PlayURL, and surface.PlaySound functions. It includes robust URL validation, file format verification, caching mechanisms, and statistics tracking. The library ensures optimal performance by avoiding redundant downloads and providing fallback mechanisms for failed downloads while maintaining compatibility with existing sound APIs.

---

lia.websound.download(name, url, cb)

Download or reuse a cached web sound by name, running a callback with the local file path.

Whenever a module needs to ensure a URL-based sound exists before playback, especially during initialization.

Parameters:

string name The logical name for this sound; normalized before saving.

string url optional Optional override URL; falls back to previously registered URLs.

function cb optional Completion callback that receives (path, fromCache, error).

Example Usage:

    -- Preload multiple tracks in sequence, falling back to cached copies.
    local playlist = {
        {"music/combat_theme.mp3", "https://assets.example.com/music/combat_theme.mp3"},
        {"music/stealth_loop.ogg", "https://assets.example.com/music/stealth_loop.ogg"}
    }
    local function preloadNext(i)
        local entry = playlist[i]
        if not entry then return end
        lia.websound.download(entry[1], entry[2], function(path, fromCache, err)
            if not path then
                lia.util.logError("Failed to preload " .. entry[1] .. ": " .. tostring(err))
                return
            end
            if not fromCache then
                lia.log.add(nil, "websoundCached", entry[1])
            end
            preloadNext(i + 1)
        end)
    end
    hook.Add("InitPostEntity", "PreloadMusicPlaylist", function() preloadNext(1) end)

---

lia.websound.register(name, url, cb)

Register a named URL so future calls can rely on a cached entry and optionally download it immediately.

During gamemode setup when you want to associate a friendly key with a remote sound asset.

Parameters:

string name Logical identifier used for caching and later lookup.

string url HTTP/HTTPS link pointing to the desired sound file.

function cb optional Optional callback same as `download`.

Returns:

string? Returns the cached path if already downloaded.

Example Usage:

    hook.Add("PostGamemodeLoaded", "RegisterUIAudio", function()
        lia.websound.register("ui/alert.wav", "https://assets.example.com/sounds/ui/alert.wav", function(path)
            if path then surface.PlaySound(path) end
        end)
        lia.websound.register("ui/ambient.mp3", "https://assets.example.com/sounds/ui/ambient.mp3", function(path)
            if not path then return end
            timer.Create("UIAmbientLoop", 120, 0, function()
                sound.PlayFile(path, "", function() end)
            end)
        end)
    end)

---

lia.websound.get(name)

Lookup the cached filesystem path for a registered web sound when you need to play it immediately.

Within any playback logic that wants to skip downloading and use an already fetched file.

Parameters:

string name The normalized identifier previously registered or downloaded.

Returns:

string|nil Local `data/` path to the sound file, or `nil` if not downloaded yet.

Example Usage:

    -- Play from cache or queue a download with a one-time completion hook.
    local function playAmbient()
        local cachedPath = lia.websound.get("ui/ambient.mp3")
        if cachedPath then
            sound.PlayFile(cachedPath, "mono", function() end)
            return
        end
        lia.websound.download("ui/ambient.mp3", nil, function(path)
            if path then sound.PlayFile(path, "mono", function() end) end
        end)
    end
    hook.Add("InitPostEntity", "PlayAmbientCached", playAmbient)

---

lia.websound.getStats()

Provide download statistics for diagnostic interfaces or admin reporting.

When showing status panels or logging background downloads.

Returns:

table `{ downloaded = number, stored = number, lastReset = timestamp }`.

Example Usage:

    hook.Add("PlayerSay", "ReportWebSoundStats", function(ply, text)
        if text ~= "!soundstats" then return end
        local stats = lia.websound.getStats()
        ply:notifyLocalized("webSoundStats", stats.downloaded, stats.stored, os.date("%c", stats.lastReset))
    end)

---

lia.websound.clearCache(skipReRegister)

Delete all cached web sounds and optionally trigger re-registration.

During round resets or when you want to force a fresh download of every entry.

Parameters:

boolean skipReRegister If true, registered entries are not re-downloaded automatically.

Example Usage:

    -- Force-refresh all cached sounds when admins reload content packs.
    hook.Add("OnConfigReload", "ResetWebSounds", function()
        lia.websound.clearCache(false)
        for name, url in pairs(lia.websound.stored) do
            lia.websound.download(name, url)
        end
    end)

---

lia.websound.playButtonSound(customSound, callback)

Play the configured button click sound with optional overrides and fallbacks.

Whenever a UI element wants to use a consistent button audio cue.

Parameters:

string customSound optional Optional override path or URL.

function callback optional Receives `(success, errStr)` once playback is attempted.

Example Usage:

    -- Use a per-skin override and fall back to the global default.
    local button = vgui.Create("DButton")
    button.DoClick = function()
        lia.websound.playButtonSound("https://assets.example.com/sounds/ui/blue_click.wav", function(success, err)
            if not success then
                lia.websound.playButtonSound(nil) -- fallback to default
            end
        end)
    end

---