surround-audio - GitLite

KO | EN

gitlite — search

#postgresql #gemini #ruby #video #awesome #redis #python #macos #bash #rag

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.

파일 탐색기

ZIP 다운로드

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

# CDN으로 사용하기

jsDelivr

jsDelivr는 공개 GitHub 리포지토리를 별도 설정 없이 CDN으로 즉시 서빙합니다. 버전과 파일을 고르면 웹페이지에 바로 붙일 수 있는 링크와 예시 코드가 만들어집니다.

버전

파일

링크

예시

명령어 용어집

이 문서에서 사용된 명령어를 모아봤습니다. 낯선 명령어가 있다면 펼쳐서 확인해보세요.

🔍

`luajit`

설명 보기 ▼

Lua 프로그래밍 언어를 위한 즉시 컴파일러(JIT).
관련 항목: `lua`.
더 많은 정보: <https://luajit.org/luajit.html>.

luajit

대화형 Lua 셸 시작:

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

Lua 스크립트 실행:

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

Lua 표현식 실행:

🔍

`mods`

설명 보기 ▼

파이프라인을 위해 설계된 커맨드라인 AI.
더 많은 정보: <https://github.com/charmbracelet/mods#usage>.

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

일반적인 질문하기:

mods --settings

`$EDITOR`에서 설정 열기:

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

코드에 대한 의견을 마크다운 형식으로 요청하기:

🔍

`python3`

설명 보기 ▼

이 명령은 `python`의 별칭입니다.

tldr python

자세한 내용은 원본 명령을 참고하세요:

// 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.