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
Section titled “equal_loudness_contour”equal_loudness_contour(phon: float) -> LoudnessContourNormal 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
Section titled “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: NumericArrayLike | None = None,) -> EqualLoudnessContoursBuild 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
Section titled “EqualLoudnessContours”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()
Section titled “EqualLoudnessContours.plot()”EqualLoudnessContours.plot( ax: Axes | None = None, *, language: Literal['en', 'es'] = 'en', **kwargs: Any,) -> AxesPlot 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
Section titled “hearing_threshold”hearing_threshold() -> LoudnessContourThreshold 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
Section titled “loudness_level”loudness_level(spl: float, frequency: float) -> floatLoudness 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
Section titled “LoudnessContour”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()
Section titled “LoudnessContour.plot()”LoudnessContour.plot( ax: Axes | None = None, *, language: Literal['en', 'es'] = 'en', **kwargs: Any,) -> AxesPlot 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.