speech.sti

Speech Transmission Index (STI) per IEC 60268-16:2020 (Edition 5).

Implements the full-STI indirect method from impulse responses (Schroeder modulation transfer function), the direct STIPA method on recorded signals (Annex B), an Ed.5-conformant STIPA test-signal generator (clauses A.4 and A.6.1) and the Annex M adjustment of a measured result to other speech and occupancy-noise levels. Only the male speech option exists: Edition 5 removed the female spectrum and weighting factors (foreword, item d).

The computation chain (octave-band MTF -> auditory masking and reception threshold correction -> effective SNR clipped to +/-15 dB -> transmission indices -> band MTI -> weighted STI) is numerically identical between Ed.4 (2011) clauses A.5.2-A.5.6 and Ed.5; the only Ed.5 numeric change is the male test-signal spectrum (A.6.1).

The level adjustment of sti_adjusted_for_levels is the four-step procedure of Ed.4 (2011) Annex M, verified against the printed intermediates of its Table M.1. The Ed.5 foreword (item g) says greater information is given in Annex M about these adjustments, and its table of contents grows the annex from three printed pages to ten and adds a flow chart of the steps; the body of the Ed.5 annex could not be obtained, so what those pages add beside this procedure is unknown here.

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

sti_adjusted_for_levels(
    mtf: np.ndarray,
    *,
    measured_level: Sequence[float] | np.ndarray,
    measured_ambient: Sequence[float] | np.ndarray | None = None,
    operational_level: Sequence[float] | np.ndarray,
    operational_ambient: Sequence[float] | np.ndarray | None = None,
) -> STIResult

STI of a measured MTF matrix moved to other speech and noise levels.

A room is measured empty, at whatever level the test signal ran; the question is what the STI would be with the room occupied and the talker at the operational level. The four steps of IEC 60268-16 Annex M answer it without measuring again:

1. acquire the modulation transfer matrix together with the speech and background-noise octave-band levels that were present during the measurement (mtf, measured_level, measured_ambient);
2. divide out the correction those levels produced, which removes the background noise, the auditory masking and the reception threshold and leaves the matrix of the transmission channel alone;
3. multiply by the correction the operational levels produce, putting the occupancy noise, masking and threshold of the simulated condition back in;
4. process the resulting matrix into the index by the usual A.5.4 to A.5.6 chain.

Steps 2 and 3 run the one level-dependent correction of clause A.5.3 that the forward chain applies, once inverted and once as it stands, so the adjustment cannot drift from the masking and threshold model the rest of the module uses.

What is implemented is the Ed.4 (2011) Annex M procedure, verified against the printed intermediates of its Table M.1 worked example. The Ed.5 foreword (item g) says greater information is given in Annex M about these adjustments, and its table of contents grows the annex from three printed pages to ten; the body of the Ed.5 annex could not be obtained, so what those pages add beside this procedure is unknown here.

Parameters

Returns: STIResult at the operational levels, carrying them in band_levels and ambient_levels.

Raises

sti_from_impulse_response(
    ir: Signal | list[float] | np.ndarray,
    fs: int | None,
    snr: None,
    level: Sequence[float] | np.ndarray,
    ambient: Sequence[float] | np.ndarray,
) -> STIResult

sti_from_impulse_response(
    ir: Signal | list[float] | np.ndarray,
    fs: int | None = ...,
    snr: None = ...,
    *,
    level: Sequence[float] | np.ndarray,
    ambient: Sequence[float] | np.ndarray,
) -> STIResult

sti_from_impulse_response(
    ir: Signal | list[float] | np.ndarray,
    fs: int | None = ...,
    snr: float | Sequence[float] | np.ndarray | None = ...,
    level: Sequence[float] | np.ndarray | None = ...,
) -> STIResult

Full STI from a room/system impulse response (indirect method).

The impulse response is filtered into the seven octave bands 125 Hz - 8 kHz (IEC 61260-1 filters) and the modulation transfer function is obtained from the Schroeder integral (IEC 60268-16, indirect method):

at the 14 modulation frequencies 0,63-12,5 Hz (A.2.2). The result then follows the standard chain: optional noise degradation, optional auditory masking and absolute reception threshold correction, effective SNR clipped to +/-15 dB, transmission indices, band MTIs and the male-weighted STI (Ed.5 Table A.1).

When neither level nor ambient is given the level-dependent auditory masking and the absolute reception threshold corrections are skipped (they require absolute band levels), matching the common “noise-free indirect measurement” use of the standard.

Parameters

Returns: STIResult with mtf of shape (7, 14).

stipa(
    x: Signal | list[float] | np.ndarray,
    fs: int | None,
    reference: Signal | list[float] | np.ndarray | None,
    level: Sequence[float] | np.ndarray,
    ambient: Sequence[float] | np.ndarray,
) -> STIResult

stipa(
    x: Signal | list[float] | np.ndarray,
    fs: int | None = ...,
    reference: Signal | list[float] | np.ndarray | None = ...,
    *,
    level: Sequence[float] | np.ndarray,
    ambient: Sequence[float] | np.ndarray,
) -> STIResult

stipa(
    x: Signal | list[float] | np.ndarray,
    fs: int | None = ...,
    reference: Signal | list[float] | np.ndarray | None = ...,
    level: Sequence[float] | np.ndarray | None = ...,
) -> STIResult

STIPA on a recorded test signal (direct method, Annex B).

The recording is filtered into the seven octave bands, squared and low-passed (~100 Hz) into intensity envelopes, and the modulation depths at the two Table B.1 modulation frequencies of each band are measured with the sine/cosine correlation over an integer number of periods (Ed.4 A.5.2 = Ed.5). The modulation transfer values are the measured depths normalized by the source modulation index 0,55 (Annex B) - or by the depths measured on reference when the actually emitted signal is supplied - and feed the same masking / threshold / TI / STI chain as the full method.

Physical background noise is already contained in the recording; use level (and optionally ambient) only to enable the absolute level-dependent corrections, which are otherwise skipped.

An STIWarning is emitted when the recording is shorter than the recommended 15 s (IEC 60268-16 STIPA practice, 15 s to 25 s), because the slow modulation components are then averaged over too few periods and the recovered modulation depths - and hence the STI - are biased low (an ideal loopback gives STI ~0.956 at 5 s vs ~0.998 at 18 s).

Parameters

Returns: STIResult with mtf of shape (7, 2).

stipa_signal(
    fs: int,
    seconds: float = 18.0,
    level_db: float | None = None,
    seed: int | None = None,
) -> np.ndarray

Generate an IEC 60268-16:2020 conformant STIPA test signal.

Pink-noise carriers are band-limited to half-octave bands centred on the seven octave-band frequencies (clause A.4), set to the Ed.5 male speech spectrum of clause A.6.1 (-2,5; 0,5; 0; -6; -12; -18; -24 dB re the 500 Hz band) and intensity-modulated with 0,5 (1 + 0,55 (sin 2 pi f1 t - sin 2 pi f2 t)) - the Table B.1 frequency pair of each band, 180 degrees between components, applied in amplitude through its square root (Annex B).

Parameters

Returns: Test signal, 1D array of round(seconds * fs) samples.

STIResult(
    sti: float,
    mti: np.ndarray,
    mtf: np.ndarray,
    band_levels: np.ndarray | None,
    rating: str,
    ambient_levels: np.ndarray | None = None,
)

Result of a Speech Transmission Index computation.

mtf holds the modulation transfer values actually used for the transmission indices, i.e. after the optional SNR / masking / reception-threshold corrections and after clipping to [0, 1]; its shape is (7, 14) for full STI and (7, 2) for STIPA. mti is the per-band modulation transfer index (7,), band_levels and ambient_levels echo the speech and background-noise octave-band levels used for the level-dependent corrections (None when they were skipped) and rating is the Annex F qualification letter (A+ .. U).

The two level spectra are what adjusted_for_levels reads to undo the corrections they produced, so a result that carries them can be moved to another speech and occupancy-noise condition.

STIResult.adjusted_for_levels(
    *,
    operational_level: Sequence[float] | np.ndarray,
    operational_ambient: Sequence[float] | np.ndarray | None = None,
) -> STIResult

This result moved to another speech and noise condition (Annex M).

The measurement condition is the one this result already carries in band_levels and ambient_levels, so only the target condition is passed: what the room would have scored occupied, or with the talker raised to the operational level. See sti_adjusted_for_levels, which does the work and states the edition the procedure comes from.

Parameters

Returns: A new STIResult at the operational levels.

Raises

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

Plot the per-band MTI bars with the STI and rating letter.

Requires matplotlib (pip install phonometry[plot]); returns the Axes.

STIResult.report(
    path: str,
    *,
    metadata: ReportMetadata | None = None,
    engine: str = 'reportlab',
    verbose: bool = False,
    language: str = 'en',
) -> str

Render an IEC 60268-16 speech-transmission-index fiche to a PDF.

Writes a one-page voice-alarm / public-address intelligibility verification report: a standard-basis line stating the measurement method (the full STI indirect method from an impulse response, or the direct STIPA method on a recorded signal), an optional metadata header block, a per-octave-band modulation transfer index table beside the per-band MTI bars (the result’s own plot), the boxed STI = X single number with the Annex F qualification band, an optional verdict row and a footer with the fixed disclaimer.

Parameters

Returns: The written path as a str.

Raises

Warns about suspect STI/STIPA measurements or inputs.