Merge pull request cloudwu#97 from yuchanns/feat-audio

feat(audio): support sound manipulation

Author: cloudwu

.gitignore

@@ -1,5 +1,7 @@
 bin
 build
+compile_commands.json
+.cache
 node_modules
 .pnpm-store
 pnpm-debug.log*

asset/sounds.dl

@@ -1,3 +1,12 @@
 --
 name : bloop
 filename : asset/sounds/bloop_x.wav
+
+--
+name : bloop_loop
+filename : asset/sounds/bloop_x.wav
+group : music
+volume : 0.6
+pitch : 0.8
+loop : true
+stream : true

docs/soluna.lua

@@ -12,6 +12,95 @@
 --- Sprite bundle mapping sprite names to IDs
 ---@alias SpriteBundle table<string, Sprite?>
 
+--- Audio playback options
+---
+--- Values provided here override defaults from `sounds.dl`.
+--- `stream = true` is intended for long-running audio such as background music.
+---
+---@class soluna.AudioPlayOptions
+---@field group? string Audio bus name
+---@field volume? number Linear volume multiplier
+---@field pan? number Stereo pan in range `[-1.0, 1.0]`
+---@field pitch? number Pitch multiplier
+---@field loop? boolean Whether playback should loop
+---@field stream? boolean Whether to stream instead of fully decoding up front
+
+--- Audio voice handle returned by `soluna.play_sound()`
+---
+--- Represents one active playback instance.
+--- When a voice finishes naturally, `:playing()` returns `false`.
+--- Mutating methods return `false` when the voice is no longer valid.
+---
+---@class soluna.AudioVoice
+local AudioVoice = {}
+
+---
+--- Stops playback
+---
+---@param fade_seconds? number Optional fade-out duration in seconds
+---@return boolean ok False when the voice is no longer valid
+function AudioVoice:stop(fade_seconds) end
+
+---
+--- Checks whether the voice is still playing
+---
+---@return boolean playing
+function AudioVoice:playing() end
+
+---
+--- Sets voice volume
+---
+---@param volume number Linear volume multiplier
+---@return boolean ok False when the voice is no longer valid
+function AudioVoice:set_volume(volume) end
+
+---
+--- Sets voice pan
+---
+---@param pan number Stereo pan in range `[-1.0, 1.0]`
+---@return boolean ok False when the voice is no longer valid
+function AudioVoice:set_pan(pan) end
+
+---
+--- Sets voice pitch
+---
+---@param pitch number Pitch multiplier
+---@return boolean ok False when the voice is no longer valid
+function AudioVoice:set_pitch(pitch) end
+
+---
+--- Enables or disables looping
+---
+---@param loop boolean
+---@return boolean ok False when the voice is no longer valid
+function AudioVoice:set_loop(loop) end
+
+---
+--- Seeks to a playback position in seconds
+---
+---@param seconds number Target playback time in seconds
+---@return boolean ok False when the voice is no longer valid
+function AudioVoice:seek(seconds) end
+
+---
+--- Returns the current playback position in seconds
+---
+---@return number? seconds Current playback time
+---@return string? err Error message when the voice is no longer valid
+function AudioVoice:tell() end
+
+--- Audio bus handle returned by `soluna.audio_bus()`
+---
+---@class soluna.AudioBus
+local AudioBus = {}
+
+---
+--- Sets bus volume
+---
+---@param volume number Linear volume multiplier
+---@return boolean ok False when the bus name is invalid
+function AudioBus:set_volume(volume) end
+
 ---@class soluna
 local soluna = {}
 
@@ -65,4 +154,50 @@ function soluna.gamedir(name) end
 ---@return SpriteBundle sprites Sprite bundle mapping sprite names to IDs
 function soluna.load_sprites(filename) end
 
+---
+--- Loads audio definitions from a datalist file
+---
+--- Each entry in `sounds.dl` must define:
+--- - `name`
+--- - `filename`
+---
+--- Optional entry fields:
+--- - `group` (defaults to `"sound"`)
+--- - `volume`
+--- - `pan`
+--- - `pitch`
+--- - `loop`
+--- - `stream`
+---
+--- `load_sounds()` may be called multiple times. Each bundle registers more sound definitions.
+--- Re-loading the same bundle is ignored. Sound names must stay unique across loaded bundles.
+--- Audio buses are created from the `group` field of loaded sound entries and reused by name.
+---
+---@param filename string Path to audio definition file (.dl format)
+function soluna.load_sounds(filename) end
+
+---
+--- Plays a sound and returns a voice handle
+---
+--- The returned handle represents the active playback instance, not the sound definition.
+--- Background music uses the same API; a typical music entry sets `group = "music"`,
+--- `loop = true`, and `stream = true` in `sounds.dl`.
+---
+---@param name string Sound definition name from `sounds.dl`
+---@param opts? soluna.AudioPlayOptions Per-playback option overrides
+---@return soluna.AudioVoice? voice Active playback handle
+---@return string? err Error message on failure
+function soluna.play_sound(name, opts) end
+
+---
+--- Returns an audio bus handle
+---
+--- Buses are created from the `group` field in loaded `sounds.dl` entries.
+--- When a sound entry omits `group`, it uses the default bus name `"sound"`.
+---
+---@param name string Audio bus name
+---@return soluna.AudioBus? bus Bus handle
+---@return string? err Error message when the bus does not exist
+function soluna.audio_bus(name) end
+
 return soluna

make.lua

@@ -162,4 +162,19 @@ lm:dll "sample" {
 
 lm:import "script/act_targets.lua"
 
+lm:runlua "cc" {
+	script = "script/compile_commands.lua",
+	args = {
+		"build/build.ninja",
+		"compile_commands.json",
+	},
+	inputs = {
+		"build/build.ninja",
+		"script/compile_commands.lua",
+	},
+	outputs = {
+		"compile_commands.json",
+	},
+}
+
 lm:default "soluna"

script/compile_commands.lua

@@ -0,0 +1,26 @@
+local subprocess = require "bee.subprocess"
+
+local ninja_file, output = ...
+
+assert(ninja_file, "missing ninja file path")
+assert(output, "missing output path")
+
+local process = assert(subprocess.spawn {
+	"ninja",
+	"-f",
+	ninja_file,
+	"-t",
+	"compdb",
+	"-x",
+	searchPath = true,
+	stdout = true,
+})
+
+local content = process.stdout:read "a"
+local code = process:wait()
+if code ~= 0 then
+	os.exit(code, true)
+end
+
+local file <close> = assert(io.open(output, "wb"))
+file:write(content)