Skip to content

psychoacoustics: tonality (Sottek model)

Every name on this page is published by phonometry.psychoacoustics: from phonometry import psychoacoustics, then psychoacoustics.<name>.

Psychoacoustic tonality per ECMA-418-2:2025 (4th ed., Sottek Hearing Model).

Clean-room implementation of the tonality signal chain of ECMA-418-2:2025 (Clause 6.2). The shared auditory front-end (Clause 5) and the ACF-based tonal/noise decomposition with the full Clause 6.2.3 band averaging (Clause 6.2.2-6.2.7, phonometry.psychoacoustics.loudness.ecma._tonal_noise_split) are reused from phonometry.psychoacoustics.loudness.ecma, so loudness and tonality therefore report the same underlying N'_tonal(l, z) for the same signal; this module adds

  • the tonality output stages (Clause 6.2.8-6.2.11): the overall-SNR gate q(l) (Formulae 49-50), the time-dependent specific tonality (Formula 51), the average specific tonality T'(z) and its frequency f_ton,z(z) (Formulae 53-55), the time-dependent tonality T(l) with its frequency f_ton(l) (Formulae 61-62) and the representative single value T (Formulae 63-64).

The calibration factor c_T of Formula (51) is fixed by the standard so that a 1 kHz sinusoid at 40 dB SPL yields 1 tu_HMS.

The API is monaural; analyse each channel separately. (Unlike its roughness and loudness, ECMA-418-2 defines no binaural combination for tonality.)

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

EcmaTonality(
tonality: float,
specific_tonality: NDArray[np.float64],
bark: NDArray[np.float64],
frequencies: NDArray[np.float64],
tonal_frequencies: NDArray[np.float64],
times: NDArray[np.float64],
tonality_vs_time: NDArray[np.float64],
tonal_frequency_vs_time: NDArray[np.float64],
field: Literal['free', 'diffuse'],
)

Result of an ECMA-418-2:2025 (Sottek) tonality calculation.

tonality is the single representative tonality T in tu_HMS (Formula 63). specific_tonality is the average specific tonality T’(z) in tu_HMS over the 53 auditory bands (Formula 53), with bark the critical-band-rate scale z (0.5..26.5 Bark_HMS), frequencies the band centre frequencies F(z) and tonal_frequencies the per-band tonal frequency f_ton,z(z) (Formula 55). times and tonality_vs_time hold the time-dependent tonality T(l) at 187.5 Hz (Formula 61) and tonal_frequency_vs_time its frequency f_ton(l) (Formula 62). field records the assumed sound field.

EcmaTonality.plot(
ax: None = None,
*,
language: Literal['en', 'es'] = 'en',
**kwargs: Any,
) -> tuple[Axes, Axes]
EcmaTonality.plot(
ax: Axes,
*,
language: Literal['en', 'es'] = 'en',
**kwargs: Any,
) -> Axes

Plot the average specific tonality T’(z) (see phonometry._plot.psychoacoustics).

Adds a tonality-vs-time panel. Requires matplotlib (the [plot] extra).

Parameters

Name Description
language The language of the labels: "en" or "es".

Constant (float).

PROMINENT_TONALITY_TU_HMS = 0.4
tonality_ecma(
x: Signal | NumericArrayLike,
fs: float | None = None,
field: Literal['free', 'diffuse'] = 'free',
f_low: float | None = None,
f_high: float | None = None,
) -> EcmaTonality

Psychoacoustic tonality per ECMA-418-2:2025 (Sottek Hearing Model).

Parameters

Name Description
x Calibrated sound pressure signal in pascals. Accepts a phonometry.io.Signal, which is where “calibrated” comes from without arithmetic: this model reads absolute levels, so an uncalibrated record is taken as if one digital unit were one pascal and the answer is wrong by however far that is from true.
fs Sampling rate in Hz. Signals not at 48 kHz are resampled (Clause 5.1.1). Required for a bare array; a Signal brings its own, and an explicit value that disagrees with it raises instead of silently winning.
field "free" (default) or "diffuse" sound field, selecting the outer/middle-ear filter of Clause 5.1.3.
f_low Optional lower edge (Hz) of a user frequency band for the time-dependent tonality maximum search (Formulae 56-60). None uses the full range.
f_high Optional upper edge (Hz) of the user frequency band.

Returns: An EcmaTonality with the single value T (Formula 63), the average specific tonality T’(z) (Formula 53), the tonal frequencies f_ton,z(z) (Formula 55) and the time-dependent tonality T(l) (Formula 61) with its frequency (Formula 62).

Raises

Exception When
TypeError if f_high, f_low or fs is not a single number, or field is not a text.

The 1 kHz / 40 dB SPL sinusoid yields 1 tu_HMS by construction of the calibration factor of Formula (51).