Skip to content

environment.assessment.soundscape_binaural

What a soundscape sounds like at the ears: the binaural analysis of ISO/TS 12913-3:2019 Annex D and ISO/TS 12913-2:2018 Annex D.

A soundscape study records the acoustic environment with an artificial head, because a binaural recording keeps what a listener hears with both ears. For the analysis, each of the two channels is processed on its own, after the recording has been equalized to approximate a monaural microphone measurement (ISO/TS 12913-3 clause 7, ISO/TS 12913-2 D.4). Every metric of Table D.1 is determined for each ear, and the higher of the two values is the single representative value “indicating the overall experience”; the arithmetic mean of the two may be reported as well (D.2). binaural_indicators does that for a calibrated two-channel recording, with the library’s own implementation of each metric:

  • sound pressure level, ISO 1996-1: , , and , from laeq, leq of the C-weighted signal and ln_levels with time weighting F;
  • loudness, ISO 532-1: , , , and the variability ratio of D.2, from the time-varying method of loudness_zwicker;
  • psychoacoustic tonality : Table D.1 names ECMA-74, whose current edition (the 22nd, Annex G) refers the psychoacoustic tonality calculation to ECMA-418-2 clause 6, which tonality_ecma implements in its 2025 edition;
  • roughness , and fluctuation strength , : Table D.1 cites Fastl and Zwicker for both, and ISO/TS 12913-2 Annex B notes that no standardized method existed in 2018. The library computes both with the hearing model of ECMA-418-2:2025 (roughness_ecma, fluctuation_strength_ecma), whose time-dependent values give the percentiles; the method is named in every result, as ISO/TS 12913-2 4.2 requires (“the used calculation method shall be reported”).

Sharpness , and are not computed. They are percentiles of a sharpness that varies in time, and the library’s DIN 45692 sharpness (sharpness_din) is taken from the stationary specific loudness of ISO 532-1; its time-varying loudness does not publish the specific loudness over time that a time-varying sharpness needs. The result says so in not_implemented rather than filling the row with a stationary value under a percentile’s name.

Recording requirements of ISO/TS 12913-2 Annex D that the signal itself can show are checked with a SoundscapeWarning: a measurement interval of at least 3 min (D.3) and a sampling frequency of at least 44.1 kHz (D.6). The equalization (D.4), the position (D.2) and the calibration are the caller’s: the channels are taken as equalized sound pressure, left first.

The ISO/TS 12913-3 implemented is the first edition, of 2019; ISO has since published ISO/TS 12913-3:2025, which revises Annex A (the questionnaire analysis, phonometry.environment.assessment.soundscape).

Computing cost. The ECMA-418-2 metrics run the full hearing model on every channel, and on a 3 min recording they take minutes each, tonality most of all. parameters chooses which rows of Table D.1 to compute.

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

binaural_indicators(
x: Signal | NumericArrayLike,
fs: float | None = None,
*,
calibration_factor: float | None = None,
field: Literal['free', 'diffuse'] = 'free',
parameters: Literal['sound_pressure_level', 'loudness', 'sharpness', 'tonality', 'roughness', 'fluctuation_strength'] | Sequence[Literal['sound_pressure_level', 'loudness', 'sharpness', 'tonality', 'roughness', 'fluctuation_strength']] = ('sound_pressure_level', 'loudness', 'sharpness', 'tonality', 'roughness', 'fluctuation_strength'),
) -> BinauralIndicators

The metrics of ISO/TS 12913-3 Table D.1 at each ear of a binaural recording, with their representative values (Annex D, D.2).

Each channel is analysed on its own and every metric is reported for the left and the right ear; BinauralMetric.representative is the higher of the two, the single value D.2 uses “for all metrics considered”, and BinauralMetric.mean their arithmetic mean. The loudness row adds the variability ratio D.2 suggests. Which library function computes which metric, and why the sharpness row stays empty, is in the module docstring; each metric carries its method.

Parameters

Name Description
x The equalized binaural recording, shape (2, samples) with the left ear first, in pascals after calibration_factor; a Signal with two channels brings its own rate and calibration.
fs Sampling frequency, in Hz. Required for a bare array; a Signal brings its own, and an explicit value that disagrees with it raises.
calibration_factor Multiplier from the recorded units to pascals, the same for both channels. An explicit value wins over the one a Signal carries; a bare array with neither is taken to be in pascals.
field The sound field the recording was equalized for, "free" (default) or "diffuse", passed to the loudness and the hearing-model metrics.
parameters The rows of Table D.1 to compute, keys of BINAURAL_PARAMETERS; all of them by default. One of "sound_pressure_level", "loudness", "sharpness", "tonality", "roughness" or "fluctuation_strength". Each one of "sound_pressure_level", "loudness", "sharpness", "tonality", "roughness" or "fluctuation_strength".

Returns: A BinauralIndicators.

Raises

Exception When
ValueError for a recording that is not two channels, an unknown field or row, or a loudness exceeded 95 % of the time of zero, which leaves undefined.
TypeError if field or an entry of parameters is not a text.

Warns

Warning When
SoundscapeWarning for a recording shorter than the 3 min of ISO/TS 12913-2 D.3 or sampled below the 44.1 kHz of D.6.

Constant (mapping).

BINAURAL_PARAMETERS = {'sound_pressure_level': BinauralParameter(parameter='Sound pressure level', metrics=('LAeq,T', 'LCeq,T', 'LAF5,T', 'LAF95,T'), average_allowed=False, reference='ISO 1996-1'), 'loudness': BinauralParameter(parameter='Loudness (time-variant loudness)', metrics=('N5', 'Naverage', 'Nrmc', 'N95', 'N5/N95'), average_allowed=True, reference='ISO 532-1'), 'sharpness': BinauralParameter(parameter='Sharpness', metrics=('S5', 'Saverage', 'S95'), average_allowed=True, reference='DIN 45692'), 'tonality': BinauralParameter(parameter='Psychoacoustic tonality', metrics=('T',), average_allowed=True, reference='ECMA 74'), 'roughness': BinauralParameter(parameter='Roughness', metrics=('R10', 'R50'), average_allowed=True, reference='[32]'), 'fluctuation_strength': BinauralParameter(parameter='Fluctuation strength', metrics=('F10', 'F50'), average_allowed=True, reference='[32]')}
BinauralIndicators(
metrics: Mapping[str, BinauralMetric],
not_implemented: Mapping[str, str],
parameters: tuple[Literal['sound_pressure_level', 'loudness', 'sharpness', 'tonality', 'roughness', 'fluctuation_strength'], ...],
fs: float,
duration_s: float,
field: Literal['free', 'diffuse'],
)

The binaural analysis of a soundscape recording (ISO/TS 12913-3 Annex D, Table D.1).

Attributes

Name Description
metrics Every metric computed, keyed by its Table D.1 symbol, in the order of the table.
not_implemented Every metric of a requested row that the library does not compute, keyed by its symbol, with the reason.
parameters The rows of Table D.1 that were requested. Each one of "sound_pressure_level", "loudness", "sharpness", "tonality", "roughness" or "fluctuation_strength".
fs The sampling frequency of the recording, in Hz.
duration_s Its duration, in s.
field The sound field the loudness and hearing-model metrics assumed, "free" or "diffuse".
BinauralIndicators.plot(
ax: Axes | None = None,
*,
parameter: Literal['sound_pressure_level', 'loudness', 'sharpness', 'tonality', 'roughness', 'fluctuation_strength'] | None = None,
language: Literal['en', 'es'] = 'en',
**kwargs: Any,
) -> Axes

Plot one row of Table D.1: each metric at both ears, with the representative value marked.

Parameters

Name Description
ax Existing axes, or None to create a figure.
parameter The row to draw, a key of BINAURAL_PARAMETERS; None draws the first one computed. One of "sound_pressure_level", "loudness", "sharpness", "tonality", "roughness" or "fluctuation_strength".
language Label language, "en" (default) or "es".
kwargs Forwarded to the left-ear bars.

Returns: The axes. Requires matplotlib (the [plot] extra).

Raises

Exception When
ValueError if the row was not computed or nothing was.
TypeError if parameter is not a text.
BinauralIndicators.reporting_results() -> dict[str, float]

The results ISO/TS 12913-2 A.3 f) requires a report to give.

The representative value of each of , , , , , and , keyed by those symbols, ready for SoundscapeAcousticEnvironment.

Returns: A new dictionary, symbol to value.

Raises

Exception When
KeyError if the sound pressure level or the loudness row was not computed.
BinauralIndicators.representative(symbol: str) -> float

The single representative value of a metric: the higher ear (D.2).

Parameters

Name Description
symbol The metric, as Table D.1 prints it.

Returns: The higher of the left and right values.

Raises

Exception When
KeyError if the metric was not computed; a metric the library does not implement says why in not_implemented.
BinauralMetric(
symbol: str,
parameter: Literal['sound_pressure_level', 'loudness', 'sharpness', 'tonality', 'roughness', 'fluctuation_strength'],
left: float,
right: float,
unit: str,
method: str,
)

One metric of Table D.1 at both ears (ISO/TS 12913-3 D.2).

Attributes

Name Description
symbol The metric, as Table D.1 prints it ("LAeq,T", "N5"…).
parameter The row of Table D.1 it belongs to, a key of BINAURAL_PARAMETERS. One of "sound_pressure_level", "loudness", "sharpness", "tonality", "roughness" or "fluctuation_strength".
left The value at the left ear.
right The value at the right ear.
unit Its unit.
method How the library computed it.

property

The arithmetic mean of the two ears, which D.2 allows in addition.

property

The higher of the two ears, the single representative value of D.2.

BinauralParameter(
parameter: str,
metrics: tuple[str, ...],
average_allowed: bool,
reference: str,
)

One row of ISO/TS 12913-3 Table D.1, “Metrics and representative single values”.

Attributes

Name Description
parameter The parameter, as the first column prints it.
metrics The metrics to be determined for each channel separately, as their symbols print, in the printed order.
average_allowed Whether the row offers “the average of left and right metric values” as an alternative to the higher value; the sound pressure level row does not.
reference The document the row cites.

A recording falls short of what ISO/TS 12913-2 Annex D requires of it.