surround-audio - GitLite

KO | EN

gitlite — search

#privacy #mysql #large-language-models #data-science #cli #web #rust #react-native #c #ruby

surround-audio

(★ 10)

Stereo & 5.1 Audio mod for Gen 1 Recomp: Crystal's SOUND option (MONO/STEREO) plus center-channel SFX. Toggle with L.

File Explorer

ZIP Download

- - release.yml
- surround_audio_test.lua
.modkitignore
CHANGELOG.md
main.lua
manifest.json
mod.card
README.md

# Use via CDN

jsDelivr

jsDelivr serves any public GitHub repository as a CDN with zero setup. Pick a version and a file to get a ready-to-paste link and snippet.

Version

File

Link

Example

Command Glossary

Commands referenced in this DOCs, explained below.

🔍

`luajit`

View Details ▼

A just-in-time compiler (JIT) for the Lua programming language.
See also: `lua`.

luajit

Start an interactive Lua shell:

luajit {{path/to/script.lua}} {{--optional-argument}}

Execute a Lua script:

luajit -e '{{print("Hello World")}}'

Execute a Lua expression:

🔍

`mods`

View Details ▼

AI for the command-line, built for pipelines.

mods "{{write me a poem about platypuses}}"

Ask a generic question:

mods --settings

Open settings in your `$EDITOR`:

mods < {{path/to/file}} {{[-f|--format]}} "{{what are your thoughts on improving this code?}}"

Ask for comments on your code, in markdown format:

🔍

`python3`

View Details ▼

This command is an alias of `python`.

tldr python

View documentation for the original command:

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

Pokémon Crystal's SOUND option, ported to the 8-bit music of Red/Blue/Yellow:
**MONO** sums every music channel into both speakers, **STEREO** splits the
channels: 1-2 to the left speaker, 3-4 to the right. On top of that, every sound effect (menu beeps,
battle hits, cries, fanfares, the low-health alarm) plays from the center
channel on 5.1 output, or the middle of the image on stereo.

## Try it

```sh
python3 tools/modkit.py validate mods/surround_audio --base imported
luajit mods/surround_audio/tests/surround_audio_test.lua
```

Enable it (`surround_audio = true` under `mods` in `options.lua`, or via the
mod manager), then:

1. Press **M** (keyboard) or **Select + R** (gamepad) to switch between
   MONO and STEREO. The current song restarts (Crystal's
   `RestartMapMusic`) so you hear the change immediately. A confirm blip
   plays: high note for STEREO, low note for MONO.
2. Or open **OPTIONS** and cycle the **SOUND** row.
3. The choice is saved to `options.lua`, so it survives restarts and
   New Game.

## How it works

Crystal's option is two lines of asm: when STEREO is on, the song's pan
bytes are honored; when off, the pan byte is skipped — every channel to
both speakers. This mod implements the same contract on this engine's
synthesizer, with one twist: **Gen 1 songs never write the pan register**
(measured: 0/24 real songs differ between the speakers), so honoring the
song would be silent. STEREO therefore forces Crystal's split — channels
1-2 to the left, 3-4 to the right:

- **STEREO** renders each buffer as two mixes: channels 1+2 scaled /2 to
  the left speaker, channels 3+4 scaled /2 to the right.
- **MONO** renders through `Engine:sample()` — the pan-less sum of all four
  channels — written to both speakers.

With the forced split, 23/24 real songs separate audibly between the
speakers.

The chip music mix happens on the synthesis worker thread
(`src/core/chip_worker.lua`), created once by
`love.thread.newThread("src/core/chip_worker.lua")`. The mod substitutes a
pan-aware copy of that worker — LÖVE treats a newline-bearing string as
inline source — and steers it with a `pan` command pushed onto the engine's
`chipaudio_cmd` channel. Toggling also restarts the current song, so the
new mode is heard on the next buffer instead of after the ~6s playback
look-ahead. If the engine ever changes the worker so the substitution can't
be made, the mod degrades to the vanilla worker instead of breaking.

The engine's mod sandbox blocks `love.thread` and `love.filesystem`, and
`mod.fetch` only covers background HTTP — it can't reach the worker. The mod
gets the real LÖVE table through `require("love")` (the deny list refuses
`love.*` but lets the bare root through) and degrades to routing-only if a
future engine closes that path.

**Why not a filter/effect plugin?** This LÖVE build compiles OpenAL's EFX
extension out (`love.audio.isEFXsupported()` is false), which disables every
DSP — `Source:setFilter` beyond the basic types, all reverb/echo effects,
and the engine's own MUSIC FILTER option. Only the render-level mix above
can change the music, so the mod works at the synth instead of the speaker.

The SFX half uses positional audio: every `Source` is created through
`love.audio.newSource` / `newQueueableSource`, so the mod wraps those two
factories and classifies by kind — `static` is SFX, `stream` and queueable
are music. SFX sources get `setPosition(0, 0, -1)` + `setRelative(true)`
(azimuth zero = the center channel on 5.1), and the distance model is set
to `none` so nothing attenuates. Toggling off restores the engine defaults.

## Diagnostics

If STEREO ever sounds identical to MONO, the save dir gets a one-line
probe file (`surround_audio_probe.txt`):

- `efx=false` means the build has no DSP (expected for this LÖVE build).
- `worker=1` means the pan-aware worker was substituted; `worker=0` means
  the engine's worker changed shape and the mod degraded to vanilla.

## Notes

- On stereo speakers, MONO vs STEREO is the audible difference: the music
  snaps between the centered mix and the per-channel L/R split. The center
  SFX channel is what lights up on a real 5.1 device.
- The engine's own audio options (volumes, filter) are unaffected; the
  MUSIC FILTER is inert on this LÖVE build anyway.
- Thanks to pret/pokecrystal for the option semantics this ports.