psychoacoustics.loudness_contours

Normal equal-loudness-level contours per ISO 226:2023.

Implements Formula (1) (clause 4.1: SPL of a pure tone from its loudness level) and Formula (2) (clause 4.2: the inverse) with the Table 1 (p. 4) parameters at the 29 preferred third-octave frequencies of ISO 266.

Auto-generated from the source docstrings by scripts/generate_api_docs.py (make api-docs). Do not edit by hand.

equal_loudness_contour

equal_loudness_contour(phon: float) -> tuple[np.ndarray, np.ndarray]

Normal equal-loudness-level contour (ISO 226:2023 Formula 1).

Returns the sound pressure levels of pure tones judged equally loud as a 1 kHz tone at phon dB SPL, at the 29 preferred third-octave frequencies of Table 1.

Validity (clause 4.1): 20 phon to 90 phon between 20 Hz and 4 kHz, and up to 80 phon between 5 kHz and 12.5 kHz; above 80 phon the returned contour therefore stops at 4 kHz.

Parameters

Name	Description
phon	Loudness level in phons (20 to 90).

Returns: Tuple (frequencies, spl) in Hz and dB re 20 uPa.

equal_loudness_contours

equal_loudness_contours(
    phons: Sequence[float] = (20.0, 30.0, 40.0, 50.0, 60.0, 70.0, 80.0, 90.0),
    frequencies: Sequence[float] | np.ndarray | None = None,
) -> EqualLoudnessContours

Build the ISO 226:2023 equal-loudness-level contour family.

Evaluates equal_loudness_contour at each level in phons and hearing_threshold, and bundles them into an EqualLoudnessContours result that exposes .plot(). The maths is unchanged; this is a thin, plottable wrapper around the existing functions.

Parameters

Name	Description
phons	Loudness levels of the contours, in phon; each must be in the 20 phon to 90 phon validity range of Formula (1). Defaults to the classic family from 20 phon to 90 phon in 10 phon steps.
frequencies	Frequency grid in Hz; None (default) uses the 29 preferred third-octave frequencies of Table 1. Any value given must be one of those preferred frequencies (the standard specifies no interpolation between them).

Returns: An EqualLoudnessContours.

EqualLoudnessContours

EqualLoudnessContours(
    frequencies: np.ndarray,
    phons: tuple[float, ...],
    contours: np.ndarray,
    threshold: np.ndarray,
)

The ISO 226:2023 normal equal-loudness-level contour family.

Bundles a set of equal-loudness contours (ISO 226:2023 Formula 1) with the threshold of hearing (Table 1) over a shared frequency grid, so the iconic chart can be drawn with plot.

frequencies is the frequency grid in Hz (by default the 29 preferred third-octave frequencies of Table 1). phons lists the loudness levels of the contours, in phon. contours holds the sound pressure levels in dB re 20 uPa as a (len(phons), len(frequencies)) array, row i being the contour for phons[i]; entries the standard does not define are nan (Formula 1 is valid only up to 4 kHz above 80 phon, so those rows stop at 4 kHz). threshold is the threshold of hearing T_f in dB re 20 uPa on the same grid.

EqualLoudnessContours.plot()

EqualLoudnessContours.plot(
    ax: Axes | None = None,
    *,
    language: str = 'en',
    **kwargs: Any,
) -> Axes

Plot the equal-loudness contour family with the hearing threshold.

Draws sound pressure level in dB against a logarithmic frequency axis: one line per loudness level in phons, plus the threshold of hearing. Requires matplotlib (pip install phonometry[plot]); returns the Axes.

Parameters

Name	Description
ax	Existing axes to draw on, or None to create a figure.
language	Label language, "en" (default) or "es".
kwargs	Forwarded to the contour plot calls.

Returns: The axes.

hearing_threshold

hearing_threshold() -> tuple[np.ndarray, np.ndarray]

Threshold of hearing T_f (ISO 226:2023 Table 1).

Returns: Tuple (frequencies, threshold) in Hz and dB re 20 uPa.

loudness_level

loudness_level(spl: float, frequency: float) -> float

Loudness level of a pure tone (ISO 226:2023 Formula 2).

Parameters

Name	Description
spl	Sound pressure level of the tone in dB re 20 uPa.
frequency	Tone frequency in Hz; must be one of the 29 preferred third-octave frequencies of Table 1 (the standard specifies no interpolation between them).

Returns: Loudness level in phons. Values outside 20-90 phon (80 above 4 kHz) are extrapolations the standard labels as informative only.