Luau SDK

[server-dependencies]
AudioScape = "this-fifo/audioscape-sdk@0.19.0"

local ServerScriptService = game:GetService("ServerScriptService")
local HttpService = game:GetService("HttpService")
local RunService = game:GetService("RunService")

local AudioScape = require(ServerScriptService.Packages.AudioScape)

-- Use a test key in Studio, Secrets Store in production
local apiKey = if RunService:IsStudio()
    then "your-test-key"
    else HttpService:GetSecret("AudioScapeKey")

AudioScape.setApiKey(apiKey)

-- Only needed to develop against a local or staging API
AudioScape.setEndpoints({
    baseUrl = "http://localhost:3000/developer",
    analyticsUrl = "http://localhost:3001/analytics",
})

local result, err = AudioScape:search({
    query = "chill lo-fi beats",
    limit = 10,
    playerId = player.UserId,  -- optional
    filters = {
        genres = { "electronic" },
        duration = { min = 60, max = 180 },
        min_play_count = 100000,    -- Roblox lifetime plays
        min_likes = 500,
        created_after = "2024-01-01",
    },
})

if not result then
    warn("Search failed:", err)
    return
end

for _, track in result.tracks do
    print(track.artist, "—", track.name)
end

local result, err = AudioScape:similar({
    asset_id = "123456789",
    limit = 5,
    playerId = player.UserId,
})

if result then
    print("Found", result.meta.total, "similar tracks")
end

-- List all genres — each item exposes a URL-safe slug alongside the canonical name
local genres, err = AudioScape:browse({ type = "genre" })

for _, genre in genres.items do
    print(genre.display_name, "—", genre.track_count, "tracks")
end

-- Get tracks for a specific genre. `name` accepts the slug (e.g. "hip-hop-rap")
-- or the canonical (e.g. "Hip Hop / Rap"). Slugs are stable URL-safe ids; pass
-- back genre.slug from the list response to round-trip cleanly.
--
-- `sort` orders results within the drill-down: "popular" (default — global
-- popularity ranking, omits tracks with no engagement), "alpha" (track name
-- A→Z), "recent" (newest first). Pick alpha or recent to see fresh uploads.
local tracks, err = AudioScape:browse({
    type = "genre",
    name = "electronic",  -- or genres.items[i].slug
    limit = 20,
    sort = "popular",
})

-- Resolve up to 100 known asset IDs in one request
local result, err = AudioScape:lookup({
    asset_ids = { "1843209165", "9120386436", "1234567890" },
})
-- Tracks come back in input order; filters are bypassed.
-- IDs that didn't resolve are listed separately:
print(result.meta.missing_ids)  -- { "1234567890" }

-- Free-text search, or browse a UCS category
local result, err = AudioScape:sfxSearch({
    query = "metal sword impact short",
    limit = 20,
    filters = {
        categories = { "WEAPON" },
        subcategories = { "SWORD" },
        duration = { min = 0, max = 1 },
    },
})

-- Acoustically similar sound effects
local similar = AudioScape:sfxSimilar({ asset_id = "9120386436", limit = 10 })

-- Popularity-ranked, refreshed daily
local trending = AudioScape:sfxBrowse({ type = "trending", limit = 50 })

-- The full broader_category -> category -> subcategory tree, for picker UIs
local taxonomy = AudioScape:getSfxTaxonomy()

-- List all configured playlists
local list, err = AudioScape:listPlaylists()

for _, p in list.playlists do
    print(p.name, "—", p.track_count, "tracks")
end

-- Fetch a specific playlist
local result, err = AudioScape:getPlaylist({
    playlist_id = list.playlists[1].id,
})

-- result.playlist = { id, name, genre, playback_mode, track_count }
-- result.tracks = { { asset_id, name, artist, position, ... } }

-- From an asset you already have
local bank = AudioScape:createSoundBank({
    seeds = { footstep = "rbxassetid://1837879082" },
    kind = "sfx",
})

-- ...or from a bank curated in the portal
local bank = AudioScape:createSoundBank({ playlist_id = "sfx-1785256484251" })

bank:resolveAsync()
sound.SoundId = "rbxassetid://" .. bank:pick("footstep")

-- Drop-in for AssetService:SearchAudioAsync — one line changes
local AssetService = AudioScape:getAssetService()

local params = Instance.new("AudioSearchParams")
params.SearchKeyword = "rainy night jazz"

for _, audio in AssetService:SearchAudioAsync(params):GetCurrentPage() do
    print(audio.Title, audio.Artist)
end

-- Are these assets still playable?
local health = AudioScape:checkAssetHealth({ "1837879082", "9046863579" })
for _, asset in health.assets do
    print(asset.asset_id, asset.status, asset.name)
end

-- Or scan the whole place for Sound and AudioPlayer instances
local audit = AudioScape:auditAudio()
print(audit.meta.distinct_assets .. " distinct audio assets")
print(audit.meta.unavailable .. " unavailable")

-- One fetch — helpers reuse the cached structure
local structure, err = AudioScape:getStructure({ asset_id = "1843209165" })

-- Burst particles on every downbeat
for _, t in ipairs(structure.beat_grid.downbeats) do
    task.delay(t, function() emitter:Emit(20) end)
end

-- Trigger different VFX on the Drop
local section = AudioScape:sectionAtTime("1843209165", currentTime)
if section and section.label == "Drop" then
    camera:Shake(section.energy)
end

-- Track when a player listens to a song
AudioScape:trackPlay(track.asset_id, player.UserId, songDuration)

-- Track votes, favorites, skips
AudioScape:trackVote(assetId, "up", player.UserId)
AudioScape:trackFavorite(assetId, player.UserId)
AudioScape:trackSkip(assetId, player.UserId, 12.5)

-- Track custom events
AudioScape:trackCustom("station_tuned", assetId, player.UserId, {
    station = "main_stage",
})

AudioScape:configureAnalytics({
    enabled = true,           -- default true
    batchInterval = 30,       -- seconds between flushes
    maxBatchSize = 50,        -- events per batch
    maxQueueSize = 500,       -- max buffered events
})

local result, err = AudioScape:search({ query = "test" })

if not result then
    warn("AudioScape error:", err)
    -- err = "Rate limited — too many requests (429)"
    return
end