[soltros]

Longshot is preserving this upstream proposal for review. This draft is not an adopted or functionally verified fix.

Source: NotRexed/Hookshot#1063
Original contributor: blushOFF.
Original head: c40dc0a4e5b518cb960d1994974c5e8435bca543.
Exact source tree: 1afc6a695745127a767f49d112547c107ececf05.
Import parent: 7dbdcdc00889ccf038ad95c7481ad6e10397f8a5 (common ancestor with the migration base).

The source-tree checksum matches exactly. Original commits after the common ancestor are represented by one reconstructed import commit; source links and authorship are recorded. This snapshot can contain prerequisites beyond our migration base. Review its complete diff and overlapping proposals before merging.

Validation here: copying fidelity only. Platform builds, gameplay, functional behavior and the upstream author's claims have not been independently verified. Keep draft until reviewed, rebased and tested.

Original proposal

OoT calls nn::audio effects that the import handler took until now, so the mixes they sit on came out dry: no
reverb on the sub mixes the game gives one, no delay, and no filter on a mix. A gameplay log listed them as
unimplemented import (43 nn::audio symbols, with lr, so called). This implements them in host/nn_audio.c.

What it adds

• Plain reverb (AddReverb, Set/IsReverb*, Set/GetReverbInputOutput): run on the existing I3DL2 network, from the
  plain reverb's parameters: linear early, late, reverb and out gains; the early mode as the size of the early-reflection
  taps (small room to cavern; none); the late mode as the late delay (room, hall, plate, cavern, maximum); pre-delay,
  decay time and high-frequency decay ratio. This is an approximation of the console's reverb, not a copy of it.
• Delay (AddDelay, Set/GetDelay*, Set/IsDelayEnabled, SetDelayInputOutput): a delay line per channel; what
  comes back is low-passed (LowPassAmount), mixed with the neighbour channel's (ChannelSpread) and fed back
  (FeedbackGain); out = DryGain x input + the delayed signal. HOS_AUDIO_NO_DELAY=1 leaves it out.
• Biquad filter on a mix (AddBiquadFilter, SetBiquadFilterParameter, SetBiquadFilterEnabled,
  SetBiquadFilterInputOutput): the float TBiquadFilterParameter (flag @0, numerator @4, additive denominator @16, as
  audio: honor the float voice biquad parameter ABI NotRexed/Hookshot#669 reads it for voices), transposed direct form II as the voices' filters, with the same blow-up guard.
• Splitter destination filters (SetSplitterBiquadFilterParameter, sub mix and final mix): two filters per
  destination, applied to that destination's copy of the voice.
• Accepted with nothing behind them: SetAuxEnabled, SetAuxInputOutput (aux stays pass-through),
  AcquireAudioOutputDeviceNotification, the device output volume and auto-tune calls, ListVirtualInputDevices, the
  voice-drop parameter.
• Effects on a mix run in the order the game added them. Each running effect logs its wet level the first few times
  (audio: reverb 0 on mix 7: wet rms ...), as a check that it does something.

The voices' float biquad parameter is left to NotRexed/Hookshot#669.

Measured

• Windows 11, RTX 3070, a Kokiri Forest save: the log shows audio: biquad filter 0 on mix 2, audio: delay 0 on mix 4, 6 channels, up to 500 ms, audio: reverb 0..2 on mix 7/8/9; the low pass the game keeps on mix 2
  (b 0.416 0.833 0.416, a -0.461 -0.205) now filters. 142 s of output dumped (HOS_AUDIO_DUMP) without clipping.
• A gameplay log has one unimplemented import left for nn::audio: the voices' float biquad parameter, which audio: honor the float voice biquad parameter ABI NotRexed/Hookshot#669
  implements.
• A scripted tour of 29 teleport destinations (Add opt-in Ocarina of Time developer debug tools NotRexed/Hookshot#785's tools) with this in: no crash or device lost from it, no flicker.
• tests/test_audio_effects.py (registered in tests/run_all.py with gcc) compiles the real delay and mix-filter
  section with synthetic signals: echoes at the delay time and at the feedback, dry gain, channel spread, a NaN input,
  a one-pole low pass (50 Hz kept, 12 kHz down by more than 20 dB) and unstable coefficients (silence, no burst).

Not done

• I compared the result by logs and dumps, not by ear against the console.
• The reverb modes are mapped to sizes and delays by hand; if someone has the console's reverb tables, the mapping in
  reverb_frame is where they go.