Ir al contenido

psychoacoustics.loudness.contours

La referencia de la API se publica en inglés en los dos idiomas: se genera a partir de los docstrings del código, que son su texto original.

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(phon: float) -> LoudnessContour

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: The frequencies in Hz and the levels in dB re 20 uPa, as a LoudnessContour.

Raises

Exception When
TypeError if phon is not a single number.
equal_loudness_contours(
phons: Sequence[float] = (20.0, 30.0, 40.0, 50.0, 60.0, 70.0, 80.0, 90.0),
*,
frequencies: NumericArrayLike | 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.

Raises

Exception When
TypeError if frequencies holds a text or a value that is not a real number. An element of phons is refused the same way when it is not one real number.
EqualLoudnessContours(
frequencies: NDArray[np.float64],
phons: tuple[float, ...],
contours: NDArray[np.float64],
threshold: NDArray[np.float64],
)

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(
ax: Axes | None = None,
*,
language: Literal['en', 'es'] = '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 (the [plot] extra); 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() -> LoudnessContour

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

Returns: The frequencies in Hz and the threshold levels in dB re 20 uPa, as a LoudnessContour.

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.

Raises

Exception When
TypeError if frequency or spl is not a single number.
LoudnessContour(
frequencies: NDArray[np.float64],
levels: NDArray[np.float64],
phon: float | None,
)

A curve of pure-tone levels over the ISO 226 frequencies.

What equal_loudness_contour and hearing_threshold return: the frequencies and the levels, named, where a (frequencies, spl) tuple used to be unpacked by position.

Attributes

Name Description
frequencies The preferred third-octave frequencies of Table 1, in Hz.
levels The sound pressure level of the tone at each, in dB re 20 uPa.
phon The loudness level of the contour, in phon, or None for the threshold of hearing , which is not a contour of Formula (1).
LoudnessContour.plot(
ax: Axes | None = None,
*,
language: Literal['en', 'es'] = 'en',
**kwargs: Any,
) -> Axes

Plot the levels against frequency on a logarithmic axis.

Parameters

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

Returns: The axes.