Skip to content

psychoacoustics.quality.tonality

Prominent discrete tone assessment per ECMA-418-1:2024 (3rd edition).

Implements the tone-to-noise ratio (TNR, clause 11) and prominence ratio (PR, clause 12) methods on Hann-windowed, RMS-averaged FFT spectra (clauses 11.1 / 12.1), with the clause 10 critical-band model.

The prominent verdict is the numeric criterion only (Formulae (12)/(13) resp. (25)/(26)). The standard additionally requires prominent tones to be confirmed by aural examination (clauses 11.8/12.8) and to pass the clause 8/9 lower-threshold-of-hearing screen (its Formula (1), which needs calibrated absolute levels); both audibility requirements are the caller’s responsibility.

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

prominence_ratio(
x: Signal | NumericArrayLike,
fs: float | None = None,
*,
tone_frequency: float | None = None,
resolution_hz: float = 1.0,
) -> ToneAssessment

Prominence ratio of a discrete tone (ECMA-418-1:2024, clause 12).

Compares the level of the critical band centred on the tone (LM) with the mean of the two contiguous critical bands (LL, LU, band edges from the fitted Formulae 21-22 with Tables 2-3). For tones at or below 171.4 Hz the lower band is truncated at 20 Hz and rescaled to a 100 Hz bandwidth (Formula 24; Formula 23 otherwise, per the clause 12.5 prose; the condition printed beside Formula 23 is that of Formula 24, a misprint recorded in docs/ERRATA.md).

Parameters

Name Description
x Input signal (1D). Accepts a phonometry.io.Signal, whose calibration is applied to the samples and then cancels: the ratio compares the tone against the masking noise inside the same spectrum, so a factor common to both leaves it exactly where it was.
fs Sample rate in Hz. Required for a bare array; a Signal brings its own, and an explicit value that disagrees with it raises instead of silently winning.
tone_frequency Approximate tone frequency in Hz (default: highest peak in the range of interest).
resolution_hz FFT bin spacing (default 1.0 Hz).

Returns: ToneAssessment with ratio_db = PR in dB.

Raises

Exception When
TypeError if fs, resolution_hz or tone_frequency is not a single number.

Warns about biased tonality estimates (e.g. coarse FFT resolution).

tone_to_noise_ratio(
x: Signal | NumericArrayLike,
fs: float | None = None,
*,
tone_frequency: float | None = None,
resolution_hz: float = 1.0,
) -> ToneAssessment

Tone-to-noise ratio of a discrete tone (ECMA-418-1:2024, clause 11).

The spectrum is Hann-windowed and RMS-averaged (clause 11.1). The tone level Lt is the tone-band level above the line connecting the band edges (Formula 9); the masking-noise level Ln is the remaining critical-band level rescaled to the full critical bandwidth (Formula 10); TNR = Lt - Ln (Formula 11). Proximate secondary tones in the same critical band are combined per clause 11.6 (Formulae 14-16).

Parameters

Name Description
x Input signal (1D). Accepts a phonometry.io.Signal, whose calibration is applied to the samples and then cancels: the ratio compares the tone against the masking noise inside the same spectrum, so a factor common to both leaves it exactly where it was.
fs Sample rate in Hz. Required for a bare array; a Signal brings its own, and an explicit value that disagrees with it raises instead of silently winning.
tone_frequency Approximate tone frequency in Hz. Default (None) assesses the highest spectral peak in the 89.1 Hz to 11.2 kHz range of interest. For harmonic complexes, call once per component (clause 11.7).
resolution_hz FFT bin spacing (default 1.0 Hz; the tone band must stay within 15 % of the critical bandwidth, clause 11.2).

Returns: ToneAssessment with ratio_db = TNR in dB.

Raises

Exception When
TypeError if fs, resolution_hz or tone_frequency is not a single number.
ToneAssessment(
frequency: float,
ratio_db: float,
method: Literal['tone_to_noise_ratio', 'prominence_ratio'],
)

Result of a discrete-tone prominence assessment.

ratio_db is the tone-to-noise ratio (clause 11) or the prominence ratio (clause 12), as method says. The prominence criterion at frequency (prominence_limit_db) is the standard’s formula for that ratio and the verdict (prominent) is read from it, so an assessment cannot be built against another criterion. prominent applies the numeric criterion only; the standard’s audibility requirements (aural examination per clauses 11.8/12.8 and the clause 8/9 lower-threshold-of-hearing screen, which needs calibrated absolute levels) are the caller’s responsibility.

Attributes

Name Description
frequency The tone frequency, in hertz.
ratio_db The ratio, in decibels.
method "tone_to_noise_ratio" or "prominence_ratio".
ToneAssessment.plot(
ax: Axes | None = None,
*,
language: Literal['en', 'es'] = 'en',
**kwargs: Any,
) -> Axes

Plot the assessed tone against the ECMA-418-1 prominence criterion.

Draws the frequency-dependent criterion curve over the 89.1 Hz to 11.2 kHz range of interest with this tone at its own frequency and the margin to the criterion marked; a tone on or above the curve is prominent. The criterion family (tone-to-noise ratio, clause 11, or prominence ratio, clause 12) is recovered from prominence_limit_db.

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 assessed-tone marker plot call.

Returns: The axes.

property

The prominence limit at frequency, in dB.

Returns: Formulae (12)-(13) for the tone-to-noise ratio, (25)-(26) for the prominence ratio.

property

Whether the ratio reaches the criterion inside the range of interest.