---
title: "metrology.levels"
description: "Public API of phonometry.metrology.levels (auto-generated)."
sidebar:
  label: "levels"
---

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

Integrated and statistical sound levels (Leq, LAeq, LN percentiles).

## laeq

```python
laeq(
    x: list[float] | np.ndarray,
    fs: int,
    calibration_factor: float = 1.0,
    dbfs: bool = False,
) -> float | np.ndarray
```

A-weighted equivalent continuous sound level (LAeq).

**Parameters**

| Name | Description |
| :--- | :--- |
| `x` | Input signal (1D or 2D [channels, samples]), raw pressure units. |
| `fs` | Sample rate in Hz. |
| `calibration_factor` | Multiplier converting digital units to Pascals. |
| `dbfs` | If True, return dBFS instead of dB SPL. |

**Returns:** Scalar for 1D input, array of shape (channels,) for 2D input.

## lc_peak

```python
lc_peak(
    x: list[float] | np.ndarray,
    fs: int,
    calibration_factor: float = 1.0,
    dbfs: bool = False,
    oversample: int = 8,
) -> float | np.ndarray
```

C-weighted peak sound level, LCpeak (IEC 61672-1:2013, subclause 5.13).

The absolute maximum of the C-weighted signal, expressed in dB. This is
the quantity used by occupational-noise regulations (e.g. 135/137/140
dB(C) action limits). Verified against the reference one-cycle and
half-cycle responses of BS EN 61672-1:2013 Table 5 in the test suite.

The true peak of a continuous waveform generally falls *between* samples.
A raw on-grid maximum therefore under-reads sustained high-frequency
tones (worst near integer samples-per-cycle rates, e.g. an 8 kHz tone at
fs = 48 kHz is 6.0 samples/cycle and under-reads by up to ~1.15 dB). The
C-weighted signal is polyphase-oversampled by `oversample` before the
maximum is taken, recovering the inter-sample peak to within about
+/-0.5 dB of the analytic value.

**Parameters**

| Name | Description |
| :--- | :--- |
| `x` | Input signal (1D or 2D [channels, samples]), raw pressure units. |
| `fs` | Sample rate in Hz. |
| `calibration_factor` | Multiplier converting digital units to Pascals. |
| `dbfs` | If True, return dBFS (0 dB = peak 1.0) instead of dB SPL. |
| `oversample` | Integer oversampling factor applied before peak detection (default 8, the audit-validated value). Use 1 to disable oversampling and detect the peak on the original sample grid. |

**Returns:** Scalar for 1D input, array of shape (channels,) for 2D input.

## leq

```python
leq(
    x: list[float] | np.ndarray,
    calibration_factor: float = 1.0,
    dbfs: bool = False,
) -> float | np.ndarray
```

Equivalent continuous sound level (Leq) over the whole signal.

**Parameters**

| Name | Description |
| :--- | :--- |
| `x` | Input signal (1D or 2D [channels, samples]), raw pressure units. |
| `calibration_factor` | Multiplier converting digital units to Pascals. |
| `dbfs` | If True, return dBFS (0 dB = RMS 1.0) instead of dB SPL. |

**Returns:** Scalar for 1D input, array of shape (channels,) for 2D input.

## lex_8h

```python
lex_8h(
    x: list[float] | np.ndarray,
    fs: int,
    duration_hours: float | None = None,
    calibration_factor: float = 1.0,
) -> float | np.ndarray
```

Normalized 8-h average sound level, LEX,8h (IEC 61252, 3.3).

The daily personal noise exposure level: the steady level that, sustained
over a nominal 8 h working day, carries the same A-weighted sound
exposure as the measured event. Identical to LEP,d (Directive 86/188/EEC)
and LEX,8h of ISO 1999 (BS EN 61252:1995, 3.3 NOTES 5-6).

**Parameters**

| Name | Description |
| :--- | :--- |
| `x` | Input signal in raw pressure units (1D or 2D). |
| `fs` | Sample rate in Hz. |
| `duration_hours` | Exposure period the input represents, in hours. Default: the recording duration itself. |
| `calibration_factor` | Multiplier converting digital units to Pascals. |

**Returns:** LEX,8h in dB (scalar or per-channel array).

## ln_levels

```python
ln_levels(
    x: list[float] | np.ndarray,
    fs: int,
    n: Sequence[int] = (10, 50, 90),
    mode: str = 'fast',
    weighting: str | None = None,
    calibration_factor: float = 1.0,
    dbfs: bool = False,
) -> dict[int, float | np.ndarray]
```

Statistical percentile levels (LN) from the time-weighted level envelope.

L10 is the level exceeded 10% of the time (90th percentile of the level
distribution), L90 the level exceeded 90% of the time, etc.

**Parameters**

| Name | Description |
| :--- | :--- |
| `x` | Input signal (1D or 2D [channels, samples]), raw pressure units. |
| `fs` | Sample rate in Hz. |
| `n` | Percentile exceedance values, e.g. (10, 50, 90). |
| `mode` | Time weighting for the envelope: 'fast', 'slow' or 'impulse'. |
| `weighting` | Optional frequency weighting: 'A', 'C', 'Z' or None. |
| `calibration_factor` | Multiplier converting digital units to Pascals. |
| `dbfs` | If True, return dBFS instead of dB SPL. |

**Returns:** Dict mapping each N to its level (scalar for 1D input, array (channels,) for 2D input).

## sel

```python
sel(
    x: list[float] | np.ndarray,
    fs: int,
    weighting: str | None = None,
    calibration_factor: float = 1.0,
    dbfs: bool = False,
) -> float | np.ndarray
```

Sound exposure level (SEL / LAE): the event level normalized to 1 second.

`SEL = Leq,T + 10*log10(T / 1 s)`, the standard single-event metric
(aircraft flyovers, train passes). With `weighting="A"` this is LAE as
defined by IEC 61672-1:2013 (verified against the Table 4 toneburst
reference responses, Equation 8, in the test suite).

**Parameters**

| Name | Description |
| :--- | :--- |
| `x` | Input signal covering the whole event (1D or 2D). |
| `fs` | Sample rate in Hz. |
| `weighting` | Optional frequency weighting: 'A', 'C', 'Z' or None. |
| `calibration_factor` | Multiplier converting digital units to Pascals. |
| `dbfs` | If True, reference digital full scale instead of 20 uPa. |

**Returns:** Scalar for 1D input, array of shape (channels,) for 2D input.

## sound_exposure

```python
sound_exposure(
    x: list[float] | np.ndarray,
    fs: int,
    duration_hours: float | None = None,
    calibration_factor: float = 1.0,
) -> float | np.ndarray
```

A-weighted sound exposure E in pascal-squared hours (IEC 61252, 3.1).

The time integral of the squared A-weighted sound pressure. By default
the input is the whole event (E integrates over `len(x)/fs`); pass
`duration_hours` to treat the input as a representative sample of a
longer exposure period (E = mean-square * duration). Anchors from
BS EN 61252:1995 (3.3 NOTE 4): 3.2 Pa²h \<-> LEX,8h of exactly 90 dB.

**Parameters**

| Name | Description |
| :--- | :--- |
| `x` | Input signal in raw pressure units (1D or 2D). |
| `fs` | Sample rate in Hz. |
| `duration_hours` | Exposure period the input represents, in hours. Default: the recording duration itself. |
| `calibration_factor` | Multiplier converting digital units to Pascals. |

**Returns:** Exposure in Pa²·h (scalar or per-channel array).
