# environment.assessment.soundscape_binaural

> One page of the phonometry documentation, as Markdown. Index: https://docs.jmrp.io/phonometry/llms.txt

Canonical: https://docs.jmrp.io/phonometry/reference/api/environment/soundscape-binaural/
Language: en
Version: phonometry 4.0.0
Install: pip install "phonometry[full]"
Author: José Manuel Requena Plens (https://orcid.org/0000-0003-1250-6212)
Published: 2026-09-24
Updated: 2026-11-11T17:49:24Z
License: MIT (https://github.com/jmrplens/phonometry/blob/main/LICENSE)
Summary: 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.

---

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`](https://docs.jmrp.io/phonometry/reference/api/environment/soundscape-binaural/#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: $L_{\mathrm{Aeq},T}$,
  $L_{\mathrm{Ceq},T}$, $L_{\mathrm{AF5},T}$ and
  $L_{\mathrm{AF95},T}$, from [`laeq`](https://docs.jmrp.io/phonometry/reference/api/signals/levels/#laeq),
  [`leq`](https://docs.jmrp.io/phonometry/reference/api/signals/levels/#leq) of the C-weighted signal and
  [`ln_levels`](https://docs.jmrp.io/phonometry/reference/api/signals/levels/#ln_levels) with time weighting F;
* **loudness**, ISO 532-1: $N_5$, $N_\mathrm{average}$,
  $N_\mathrm{rmc}$, $N_{95}$ and the variability ratio
  $N_5/N_{95}$ of D.2, from the time-varying method of
  [`loudness_zwicker`](https://docs.jmrp.io/phonometry/reference/api/psychoacoustics/zwicker/#loudness_zwicker);
* **psychoacoustic tonality** $T$: 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`](https://docs.jmrp.io/phonometry/reference/api/psychoacoustics/tonality-ecma/#tonality_ecma) implements in its
  2025 edition;
* **roughness** $R_{10}$, $R_{50}$ and **fluctuation strength**
  $F_{10}$, $F_{50}$: 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`](https://docs.jmrp.io/phonometry/reference/api/psychoacoustics/roughness-ecma/#roughness_ecma),
  [`fluctuation_strength_ecma`](https://docs.jmrp.io/phonometry/reference/api/psychoacoustics/fluctuation-strength-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** $S_5$, $S_\mathrm{average}$ and $S_{95}$ are
**not computed**. They are percentiles of a sharpness that varies in time,
and the library's DIN 45692 sharpness
([`sharpness_din`](https://docs.jmrp.io/phonometry/reference/api/psychoacoustics/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`](https://docs.jmrp.io/phonometry/reference/api/environment/soundscape-binaural/#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`](https://docs.jmrp.io/phonometry/reference/api/environment/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

```python
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`](https://docs.jmrp.io/phonometry/reference/api/environment/soundscape-binaural/#binauralmetricrepresentative) is the
higher of the two, the single value D.2 uses "for all metrics
considered", and [`BinauralMetric.mean`](https://docs.jmrp.io/phonometry/reference/api/environment/soundscape-binaural/#binauralmetricmean) their arithmetic mean. The
loudness row adds the variability ratio $N_5/N_{95}$ 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`](https://docs.jmrp.io/phonometry/reference/api/io/io/#signal) with two channels brings its own rate and calibration. |
| `fs` | Sampling frequency, in Hz. Required for a bare array; a [`Signal`](https://docs.jmrp.io/phonometry/reference/api/io/io/#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`](https://docs.jmrp.io/phonometry/reference/api/environment/soundscape-binaural/#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`](https://docs.jmrp.io/phonometry/reference/api/environment/soundscape-binaural/#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 $N_5/N_{95}$ 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. |

## BINAURAL_PARAMETERS

*Constant* (`mapping`).

```python
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

```python
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()

```python
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`](https://docs.jmrp.io/phonometry/reference/api/environment/soundscape-binaural/#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()

```python
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 $L_{\mathrm{Aeq},T}$,
$L_{\mathrm{Ceq},T}$, $L_{\mathrm{AF5},T}$,
$L_{\mathrm{AF95},T}$, $N_5$, $N_{95}$ and
$N_\mathrm{rmc}$, keyed by those symbols, ready for
[`SoundscapeAcousticEnvironment`](https://docs.jmrp.io/phonometry/reference/api/environment/soundscape/#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()

```python
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

```python
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`](https://docs.jmrp.io/phonometry/reference/api/environment/soundscape-binaural/#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. |

### BinauralMetric.mean

*property*

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

### BinauralMetric.representative

*property*

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

## BinauralParameter

```python
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. |

## SoundscapeWarning

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