psychoacoustics.quality.annoyance

Psychoacoustic annoyance (PA) after Fastl & Zwicker.

Psychoacoustic annoyance combines four hearing sensations — loudness, sharpness, fluctuation strength and roughness — into a single figure that tracks annoyance ratings from listening experiments. The model is due to Widmann (1992) and is given in Fastl & Zwicker, Psychoacoustics: Facts and Models (Equations 16.2-16.4):

P A = N_{5} (1 + w_{S}^{2} + w_{F R}^{2}) (Eq. 16.2)

with the percentile loudness N5 in sone and the two loudness-weighted terms

w_{S} = (S - 1.75) \cdot 0.25 \cdot lo g_{10} (N_{5} + 10) for S > 1.75 acum, else 0 (Eq. 16.3)

w_{F R} = \frac{2.18}{N _{5}^{0.4}} (0.4 F + 0.6 R) (Eq. 16.4)

describing sharpness S (acum) and the joint influence of fluctuation strength F (vacil) and roughness R (asper). Note the “1 +” sits outside the radical (Fastl & Zwicker 2006, Eq. (16.2), p. 328). There is no ISO standard for PA; the formula is exact, verified against a hand-computed worked tuple, and matches the combination implemented by the open SQAT reference implementation.

psychoacoustic_annoyance evaluates the model from the four quantities directly. psychoacoustic_annoyance_from_signal is a convenience that derives them from a calibrated pressure signal using the library’s existing models — N5/S from ISO 532-1 Zwicker loudness and DIN 45692 sharpness, R from ECMA-418-2 roughness and F from fluctuation_strength. That composite mixes model families (Zwicker N5/S, Sottek R, Osses F); the original PA model was calibrated with Zwicker-family sensations, so the signal convenience is an engineering estimate, while psychoacoustic_annoyance is the exact model.

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

psychoacoustic_annoyance

psychoacoustic_annoyance(
    n5: float,
    sharpness: float,
    fluctuation_strength: float,
    roughness: float,
) -> PsychoacousticAnnoyanceResult

Psychoacoustic annoyance from the four hearing sensations (16.2-16.4).

$P A = N_{5} (1 + w_{S}^{2} + w_{F R}^{2})$ with the loudness-weighted sharpness term wS (Equation 16.3) and the fluctuation/roughness term wFR (Equation 16.4). The sharpness term is zero for $S \leq 1.75$ acum.

Parameters

Name	Description
`n5`	Percentile loudness `N5`, in sone (the loudness exceeded 5 % of the time; `n5`).
`sharpness`	Sharpness `S`, in acum (DIN 45692).
`fluctuation_strength`	Fluctuation strength `F`, in vacil.
`roughness`	Roughness `R`, in asper (ECMA-418-2).

Returns: A PsychoacousticAnnoyanceResult.

Raises

Exception	When
ValueError	If any quantity is negative or non-finite.

psychoacoustic_annoyance_from_signal

psychoacoustic_annoyance_from_signal(
    x: SignalInput,
    fs: int | None = None,
    *,
    field: Literal['free', 'diffuse'] = 'free',
    calibration_factor: float | None = None,
) -> PsychoacousticAnnoyanceResult

Psychoacoustic annoyance from a calibrated pressure signal (convenience).

Derives the four sensations from the library’s models and combines them with psychoacoustic_annoyance: N5 from the ISO 532-1 Zwicker time-varying loudness, S from DIN 45692 sharpness, R from ECMA-418-2 roughness and F from fluctuation_strength.

Parameters

Name	Description
`x`	Calibrated sound-pressure signal (1-D), in Pa after `calibration_factor`. Accepts a `phonometry.io.Signal`, which is where that calibration comes from without arithmetic: all four sensations are level-dependent models, so an uncalibrated record is read as if one digital unit were one pascal and every one of them comes out wrong by however far that is from true.
`fs`	Sample rate, in Hz. Required for a bare array; a `Signal` brings its own, and an explicit value that disagrees with it raises.
`field`	`'free'` (default) or `'diffuse'` sound field for the loudness/sharpness/roughness front-ends (`F` is always free-field).
`calibration_factor`	Digital-units-to-Pa factor applied to `x`. An explicit value wins over the one a Signal carries.

Returns: A PsychoacousticAnnoyanceResult.

PsychoacousticAnnoyanceResult

PsychoacousticAnnoyanceResult(
    annoyance: float,
    n5: float,
    sharpness: float,
    fluctuation_strength: float,
    roughness: float,
    w_s: float,
    w_fr: float,
)

Psychoacoustic annoyance and its contributing terms (Fastl & Zwicker).

Attributes

Name	Description
`annoyance`	Psychoacoustic annoyance `PA` (Equation 16.2), dimensionless.
`n5`	Percentile loudness `N5` used, in sone.
`sharpness`	Sharpness `S` used, in acum.
`fluctuation_strength`	Fluctuation strength `F` used, in vacil.
`roughness`	Roughness `R` used, in asper.
`w_s`	Sharpness term `wS` (Equation 16.3).
`w_fr`	Fluctuation/roughness term `wFR` (Equation 16.4).

PsychoacousticAnnoyanceResult.plot()

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

Plot the PA value and the wS / wFR term contributions.

Created and maintained by José Manuel Requena Plens ORCID All projects