proximal-ladder

Render any sound at any simulated distance from a listener, in a room you design, with a head and a microphone you can set.

For each distance you get one mono file: the sound as the near ear of a listener in the room receives it. Every file is loudness-matched, so only the distance cues change. The exception is a file whose true peak would exceed −1 dBTP at the target loudness: it is turned down, a warning says so, and its loudness column shows the level. Each ladder comes with a verification table and a params.json that reproduces it exactly.

pip install proximal-ladder

Status: beta (0.9). The models are tested and verified. Names and defaults may still change before version 1.0.

Quick start

import proximal_ladder as pl

lad = pl.ladder("kettle.wav",
                distances=[3, 1, 0.3],        # metres from the head centre
                room_size=[8, 5, 3],          # length x width x height of the room, metres
                head_position=[2, 2.5, 1.2],  # where the head is: x, y, ear height (metres)
                rt60=0.5,                     # reverberation time, seconds (default 0.6)
                head_radius=0.08)             # metres (default 0.0875)
print(lad)                                    # summary table
lad.save("results/", formats=["wav", "mp3"])  # audio + verification.csv + params.json

pl.ladder("kettle.wav").save("results/defaults/")   # everything at its default
pl.glide("kettle.wav", far=3, near=0.2).save("results/glide")   # a moving source
y = pl.render("kettle.wav", distance=0.3)     # one position as a numpy array

The same ladder from the terminal:

proximal-ladder ladder kettle.wav --distances 3 1 0.3 --set 'room.dimensions=[8, 5, 3]' \
    --set 'room.listener=[2, 2.5, 1.2]' --set room.rt60=0.5 --set head.radius=0.08
proximal-ladder room --set room.absorption=0.2 --set room.walls.floor=carpet_cotton --measure
proximal-ladder docs guide                  # the full guide

proximal-ladder room shows a room's reverberation before you render anything.

What you can set

Any setting you leave out keeps its default. help(pl.ladder) lists the common ones, and proximal-ladder docs parameters gives the full reference.

Anything else uses the section and name joined by a double underscore, e.g. room__max_order=50. Alternatively, pass a parameter file with config= (on the terminal: -c); proximal-ladder config writes one with every setting explained. Typos are refused with a suggestion.

The model

Glides move the source continuously between two distances. Each comes in three versions:

• A: only the loudness changes.
• B: only the spatial cues change.
• C: both change, as the physics predicts.

The equations are in proximal-ladder docs model.

Limits:

• Mono output: one ear, not binaural.
• Shoebox room without scattering. With absorption on only a few surfaces the decay is longer than Sabine predicts, which room --measure shows.
• The head model is a rigid sphere.
• Sounds must be at least 0.4 s long.
• Renders are relative to the recording's own perspective.

Requirements

• Python: 3.9 or newer.
• Dependencies: numpy, scipy, soundfile, pyloudnorm, mosqito, pyroomacoustics, matplotlib (installed automatically).
• ffmpeg (optional): adds mp3, m4a and aac input, and mp3 output.

Credits

proximal-ladder implements published methods and builds on open-source libraries. Please also cite the works behind the parts you rely on.

• Room: the image-source method of Allen & Berkley (1979, JASA 65:943), computed with pyroomacoustics (Scheibler, Bezzam & Dokmanić 2018, ICASSP; MIT licence, © EPFL-LCAV). The absorption materials come from its database.
• Head: the rigid-sphere solution of Rabinowitz, Maxwell, Shao & Wei (1993, Presence 2:125), evaluated as in Duda & Martens (1998, JASA 104:3048). The validity band follows Brungart & Rabinowitz (1999, JASA 106:1465).
• Microphone: first-order gradient-microphone theory (Olson 1957; Beranek & Mellow 2012; Eargle 2004).
• Loudness: ITU-R BS.1770-4, measured with pyloudnorm (Steinmetz & Reiss 2021; MIT licence), whose K-weighting filter design is used at sample rates other than 48 kHz. ISO 532-1 loudness comes from MoSQITo (Apache 2.0).
• Also: NumPy, SciPy, python-soundfile/libsndfile, Matplotlib, and ffmpeg (optional, called as a separate program).

Licence

MIT © 2026 Rishi Yildiz. The licence covers this package's own code; the libraries above keep their own licences.