WebSound¶
Web sound helpers for registering, downloading, caching, and playing remote audio through Lilia.
Overview
lia.websound.download(name, url, cb)View Source
Purpose
Downloads and caches a remote web sound, using either the provided URL or the URL registered under the sound name.
Realm
Client
Parameters
string name The sound name or cache path relative to `lilia/websounds/`.
string url optional The HTTP or HTTPS URL to download. When nil, the URL registered in `lia.websound.stored[name]` is used.
function cb optional Optional callback called with the local path and cache state on success, or nil, false, and an error message on failure.
Example Usage
lia.websound.download("effects/click.mp3", "https://example.com/click.mp3", function(path, fromCache, err)
if path then sound.PlayFile(path, "", function() end) end
end)
lia.websound.register(name, url, cb)View Source
Purpose
Registers a web sound URL under a normalized name and immediately starts downloading it into the local cache.
Realm
Client
Parameters
string name The sound name or cache path used to reference the web sound later.
string url The HTTP or HTTPS URL for the sound file.
function cb optional Optional callback passed through to `lia.websound.download`.
Example Usage
lia.websound.register("effects/click.mp3", "https://example.com/click.mp3")
lia.websound.get(name)View Source
Purpose
Gets the local cached data path for a registered or downloaded web sound when the file is available.
Realm
Client
Parameters
string name The sound name, URL, or cache key to resolve.
Returns
string|nil The local `data/` path for the cached sound file, or nil when no cached file exists.
Example Usage
local path = lia.websound.get("effects/click.mp3")
if path then sound.PlayFile(path, "", function() end) end
lia.websound.getStats()View Source
Purpose
Returns current web sound cache statistics.
Realm
Client
Returns
table A table containing the number of freshly downloaded sounds, the number of registered stored sounds, and the last reset timestamp.
Example Usage
local stats = lia.websound.getStats()
print(stats.downloaded, stats.stored, stats.lastReset)
lia.websound.clearCache(skipReRegister)View Source
Purpose
Clears the in-memory web sound cache, removes cached web sound files from data storage, and optionally re-registers stored sounds.
Realm
Client
Parameters
boolean skipReRegister optional When true, stored sounds are not registered again after the cache is cleared.
Example Usage
lia.websound.clearCache()
lia.websound.clearCache(true)
lia.websound.playButtonSound(customSound, callback)View Source
Purpose
Plays a button sound using a custom sound when provided, otherwise using the cached default web button sound.
Realm
Client
Parameters
string customSound optional Optional sound path or HTTP/HTTPS URL to play instead of the default button click sound.
function callback optional Optional callback called with true when playback was started successfully, or false when the default fallback path was used after a download failure.
Example Usage
lia.websound.playButtonSound()
lia.websound.playButtonSound("https://example.com/ui/button.wav", function(success)
print(success)
end)
Hooks
Library-specific hooks documented for this library.