Log inGet started
Package

Audio.module

Newest version

This package holds more than this page lists. See all of its files in its world.

README.md

Audio

The sound of Kicked Out of the Hero's Party: crossfaded music cues, looping ambience beds, one-shot sfx that duck the music, voiced story lines, and the SETTINGS volumes. Contract in design/spec.md. Everything is local to the peer and a no-op outside play; the voices spawn under a runtime AudioRig entity.

Music: Audio.music(cue?, fade?)

Three decks, equal-power crossfade (default 1.5 s); each track loops by crossfading into itself 5 s before its measured end.

cuemood
titlesweeping bittersweet main theme
dungeondark dragon-crypt drones
tensionconfrontation / humiliation underscore
guildcozy lute-and-fiddle guild/tavern theme
whisperethereal harp + glassy synth (Software Whisper)
battleboss battle
triumphvictory fanfare
endingemotional ending
gentleslice-of-life: acoustic guitar, warm piano, light flute (everyday calm)
sadslow solo piano + cello, lonely but not hopeless
mysterymuted harp, celesta, pizzicato, investigation / suspicion
nightsoft e-piano and nylon guitar, moonlit and reflective

Ambience: Audio.ambience(id?)

Three decks, 2 s crossfade, 4 s self-crossfade loop. nil stops.

idbed
dungeonstone hall: torches, echoing drips, wind through the exit arch
cryptsealed crypt, close and dry: dust and grit trickling, single drips, a cold draft
guildbusy guild hall: crowd murmur, mugs, hearth, counter bell
guild_nightguild after hours: hissing lanterns, a few hushed tables, quiet hearth
forestriver forest by the Riverford bridge
arenaduel arena crowd
citycapital at dusk: bells, wind, distant crowd
thronevast throne hall
nightsummer night: cricket chorus, frogs, far owl, firefly shimmer
marketmidday market: merchants calling, coins, carts, awnings
tavernrowdy tavern: laughter, tankards, fireplace (no music)
archivehushed archive: candle flutter, page turns, quill, creaking shelves
rainsteady rain on cobbles and roofs, gutters, one far thunder
gardenmorning palace garden: songbirds, fountain, bees

Aliases: fireflies/crickets → night, lanterns → guild_night, library → archive, birds → garden, bustle → market, inn → tavern, storm → rain, drips → crypt.

Sfx: Audio.sfx(id, volume?)

blip advance click hover whisper_on whisper_off code_read code_edit code_patch glitch error coins level_up rank_up slam laugh door sword chapter. Per-id level, rate limit and pitch jitter; whisper/reward/drama sfx duck the music (attack 80 ms, release 0.7 s).

Voice

  • Audio.voice(id) → boolean: the cue-sheet voices and per-character reaction barks in Audio.VOICE (seraphine_useless, bark_<cast>).
  • Audio.voiceLine(lineId) → boolean: the voice of a story line, when one exists (see the convention below). Stops any line still speaking, ducks music to 0.3 while it plays, and mutes the typing blips.
  • Audio.voicePlaying() → boolean, Audio.voiceRemaining() → seconds left (0 when silent): auto mode waits on these.
  • Audio.stopVoice() cuts the speaking line (advance / skip). Audio.hasVoiceLine(lineId) → boolean.

Dropping in a voice actor's files

Every say / narration step has a stable line id <chapter>.<nnn> (for example ch1.004, prologue.012; the story writes them in game/story). Its voice is the soundClip named after the id with every . (and -, /, space) replaced by _, inside game/audio/voice/:

game/audio/voice/ch1_004.mp3      → imported as game/audio/voice/ch1_004.soundClip → plays on line "ch1.004"
game/audio/voice/prologue_012.wav → game/audio/voice/prologue_012.soundClip     → "prologue.012"

Drop the audio files (mp3/wav/ogg) into game/audio/voice/; the importer makes the soundClips. No code change: the folder is listed by asset.list with literal selectors and re-listed (at most every 4 s) when a line has no voice yet, so files added while the game runs speak on their next line. Record dry, mono or stereo, peaking around −3 dBFS; lines play at a fixed gain on the voice bus. A line with no file simply plays nothing.

Settings

Audio.setMasterVolume(v), setMusicVolume(v), setSfxVolume(v), setVoiceVolume(v), setVolume(bus, v) with bus = master | music | sfx | voice (0..1), getVolumes() → { master, music, sfx, voice }. They drive the engine mixer channels (music, sfx, ambience follows sfx, voice), saved per player in runtime_data kohp/audio.

Audio.stopAll(fade?), Audio.debugState() (decks, gains, duck, settings) for tests.

Clips live beside it in music/, ambience/, sfx/ and voice/ (all generated with audio_gen; sfx/blip_tick is the single tick cut from sfx/blip). The original cues' levels were set from measured RMS; the 2026-11 additions (gentle sad mystery night, the eight new beds) are set by ear against them.