sound
game/sound layers a persistent volume Mixer, voice-limited sound Effects, crossfading Music, and automatic background muting on top of NSGo's audio package.
import (
"github.com/nsgo-dev/game/packages/game/sound"
"github.com/nsgo-dev/nsgo/audio"
)
All Mixer, Effect and Music methods run on the engine's goroutine, just like audio's methods. From any other goroutine, dispatch through cx.Post. Ship audio files under resources/ as WAV, AAC (.m4a) or MP3.
Mixer and persistent volumes
A Mixer holds one master volume and a volume for every group name your game uses (for example "effects", "music" and "ui"). Every volume is in [0, 1] and defaults to 1.
mixer := sound.NewMixer(cx, "sound")
NewMixer(cx, key) stores values in cx.Storage() (core.Storage) under:
<key>.master<key>.group.<group>
Volumes persist automatically across app launches. Passing values outside [0, 1] clamps them (and NaN resets to 1). If storage is full, SetMaster and SetVolume return *core.StorageFullError and keep the previous volume.
Reactive settings UI
Master() and Volume(group) read from core.Storage, so calling them inside a reactive view function subscribes that view to volume changes automatically:
core.Text{
ContentFunc: func() string {
return fmt.Sprintf("Music: %.0f%%", mixer.Volume("music")*100)
},
}
How volume changes take effect
- Effects: each playback uses
voice.Volume * mixer.Volume(group) * mixer.Master(). Volume changes apply to effects started afterwards; a short sound already playing keeps its starting volume, except setting its group or master volume to0stops it immediately (nsgo#1088). - Music: active tracks update live at
mixer.Volume(group) * mixer.Master(), pausing when the effective gain reaches0and resuming from the same position when raised above0.
Effect and voice limits
Short sounds (under 8 MiB encoded and 5 seconds decoded) are decoded into memory once with audio.LoadSound, then wrapped in a mixer Effect:
var hit *sound.Effect
audio.LoadSound(cx, audio.Source{URI: "asset:sounds/hit.wav"}, func(s *audio.Sound, err error) {
if err != nil {
return
}
hit = mixer.Effect(s, "effects", 4)
})
The third argument (limit) caps how many overlapping playbacks of that sound may run at once (0 means no per-effect cap, still bounded by the platform's 32 concurrent sound voices). This prevents rapid bursts — such as coins or footsteps — from starving every other sound.
Play(v audio.Voice) boolstarts a playback and reports whether it played. It returnsfalsewhen effective gain is0, the app is in the background, orLimitplaybacks are still active (tracked bys.Duration()divided byv.Rate, whereRateis clamped to[0.5, 2]and0means1). It does not evict an older playing voice (nsgo#1088).Stop()stops every playback of that sound (and any other*audio.Soundsharing the same source).- Close the underlying
*audio.Soundwhen you no longer need it, or letcx's scope disposal free it.
if hit != nil {
hit.Play(audio.Voice{Volume: 0.9, Rate: 1.05})
}
Music and crossfades
mixer.Music(group) plays streaming tracks through audio.Player, one active track at a time, with smooth crossfades:
music := mixer.Music("music")
music.Loop = true
music.Play(audio.Source{URI: "asset:music/overworld.m4a"}, 2*time.Second)
Loop: whentrue, tracks started by subsequentPlaycalls loop at their end.Play(src, fade): fades the new track in overfadewhile fading all currently playing tracks out on display frames (core.Scope.Animate), closing faded-out players once they reach silence. Whenfade <= 0, it switches immediately. Starting anotherPlaymid-crossfade smoothly fades out the incoming track from its current level.Stop(fade): fades active music out overfadeand closes its players (fade <= 0stops immediately).
On the web, browsers enforce autoplay policies and refuse playback (audio.NotAllowed) until the user interacts with the page; start music from a button press or first tap/click.
Background muting
NewMixer watches cx.Env().Lifecycle():
- When the app enters
core.LifecycleBackground(minimized, hidden or covered on desktop; backgrounded on iOS or Android), the mixer stops playing effects, drops newEffect.Playcalls, and pauses music. - When the window returns to
core.LifecycleActiveorcore.LifecycleInactive(visible, even unfocused on desktop), music resumes from where it paused and effects can play again.
Testing with nsgotest
Enable virtual audio in nsgotest with nsgotest.Environment(core.Environment{Audio: true}) and configure decoded durations on app.AudioDurations to test voice limits, crossfades, persistence and background muting deterministically:
package mygame_test
import (
"testing"
"time"
"github.com/nsgo-dev/game/packages/game/sound"
"github.com/nsgo-dev/nsgo/audio"
"github.com/nsgo-dev/nsgo/core"
"github.com/nsgo-dev/nsgo/nsgotest"
)
func TestMain(m *testing.M) { nsgotest.Main(m) }
func TestMixerCrossfadeAndMute(t *testing.T) {
var mixer *sound.Mixer
var music *sound.Music
app := nsgotest.Start(t, func(cx *core.Scope) core.Node {
mixer = sound.NewMixer(cx, "sound")
music = mixer.Music("music")
music.Loop = true
return core.View{}
},
nsgotest.Environment(core.Environment{Audio: true}),
func(a *nsgotest.App) {
a.AudioDurations = map[string]time.Duration{
"asset:a.m4a": time.Minute,
"asset:b.m4a": time.Minute,
}
},
)
mixer.SetVolume("music", 0.5)
music.Play(audio.Source{URI: "asset:a.m4a"}, 0)
music.Play(audio.Source{URI: "asset:b.m4a"}, time.Second)
app.Advance(1100 * time.Millisecond)
if !app.Players[0].Closed || !app.Players[1].Playing {
t.Fatalf("expected track A closed and track B playing")
}
app.SetEnvironment(core.Environment{Audio: true, Lifecycle: core.LifecycleBackground})
app.Settle()
if app.Players[1].Playing {
t.Fatal("expected music paused in background")
}
}