hearing.sii

Speech Intelligibility Index (SII) per ANSI S3.5-1997 (R2017).

Implements the one-third-octave-band method (18 bands, 160 Hz - 8000 Hz) of ANSI S3.5-1997, American National Standard Methods for the Calculation of the Speech Intelligibility Index. From an equivalent speech spectrum level, an equivalent noise spectrum level and an equivalent hearing threshold, the procedure forms the self-speech masking, the upward spread of masking, the equivalent internal noise and disturbance, the level-distortion factor and the band-audibility function, and weights the latter by the band-importance function of Table 3 to give the index SII in [0, 1] (clause 6).

The band-importance function (Table 3, average speech material), the standard speech spectrum levels by vocal effort (Table 3) and the reference internal noise spectrum level (Table 3) are the standard’s own tabulated constants. Spectrum levels are as defined in clauses 3.11 and 3.55.

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

SIIResult

SIIResult(
    sii: float,
    band_audibility: np.ndarray,
    band_importance: np.ndarray,
    frequencies: np.ndarray,
    speech_spectrum: np.ndarray,
    disturbance: np.ndarray,
    masking: np.ndarray,
)

Result of a Speech Intelligibility Index computation (ANSI S3.5-1997).

Attributes

Name	Description
sii	The overall Speech Intelligibility Index in [0, 1] (clause 6).
band_audibility	Per-band audibility function Ai (clause 5.8).
band_importance	Per-band importance function Ii used (Table 3).
frequencies	One-third-octave band centre frequencies, in hertz.
speech_spectrum	Equivalent speech spectrum level Ei' per band.
disturbance	Equivalent disturbance spectrum level Di (clause 5.6).
masking	Equivalent masking spectrum level Zi (clause 5.4).

SIIResult.plot()

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

Plot the per-band audibility weighted by importance, with the SII.

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

SIIResult.report()

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

Render an ANSI S3.5-1997 speech-intelligibility-index fiche to a PDF.

Writes a one-page speech-audibility report: a standard-basis line, an optional metadata header block, a per-one-third-octave-band table (the equivalent speech spectrum Ei', the band-importance function Ii of Table 3 and the band-audibility function Ai) beside the audibility and importance-weighted contribution bars (the result’s own plot), the boxed SII = X single number, an optional verdict row and a footer with the fixed disclaimer.

Parameters

Name	Description
path	Destination path of the PDF file.
metadata	Optional ReportMetadata; None produces a bare fiche (body, result and disclaimer only). A supplied requirement is read as the minimum required SII (a higher SII passes).
engine	Rendering back end; only "reportlab" is supported.
verbose	When True, the left table adds the equivalent disturbance spectrum level Di column (clause 5.6).
language	Fiche language: "en" (default, English) or "es" (Spanish, with a comma decimal separator).

Returns: The written path as a str.

Raises

Exception	When
ValueError	If engine is not "reportlab" or language is not a supported language.
ImportError	If reportlab is not installed (pip install phonometry[report]).

speech_intelligibility_index

speech_intelligibility_index(
    speech_spectrum: ArrayLike,
    noise_spectrum: ArrayLike | None = None,
    *,
    threshold: ArrayLike | None = None,
) -> SIIResult

Speech Intelligibility Index (ANSI S3.5-1997, one-third-octave method).

All spectra are equivalent spectrum levels (clauses 3.11/3.55) sampled at the 18 one-third-octave band centres from 160 Hz to 8000 Hz.

Parameters

Name	Description
speech_spectrum	Equivalent speech spectrum level Ei', in dB SPL. A vocal-effort name ("normal", "raised", "loud" or "shout") selects the corresponding standard speech spectrum (Table 3).
noise_spectrum	Equivalent noise spectrum level Ni', in dB SPL; None uses a quiet field (-80 dB in every band).
threshold	Equivalent hearing threshold Ti', in dB HL; None uses normal hearing (0 in every band).

Returns: An SIIResult with the overall index and its .plot().

Raises

Exception	When
ValueError	if a spectrum has the wrong length or effort name.

standard_speech_spectra

standard_speech_spectra(
    vocal_efforts: str | Sequence[str] = ('normal', 'raised', 'loud', 'shout'),
) -> StandardSpeechSpectrum

Build the plottable ANSI S3.5-1997 standard speech spectra (Table 3).

Collects the standard speech spectrum level Ui of the requested vocal efforts (via standard_speech_spectrum) into a StandardSpeechSpectrum that exposes .plot(). The band levels are unchanged; this is a thin, plottable wrapper around the existing function, which still returns the bare per-band array.

Parameters

Name	Description
vocal_efforts	A single vocal-effort name or a sequence of names, each one of "normal", "raised", "loud" or "shout". Defaults to the full family in the Table 3 order.

Returns: A frozen StandardSpeechSpectrum.

Raises

Exception	When
ValueError	for an unknown vocal effort, or an empty selection.

standard_speech_spectrum

standard_speech_spectrum(vocal_effort: str = 'normal') -> np.ndarray

Standard speech spectrum level by vocal effort (ANSI S3.5-1997 Table 3).

Parameters

Name	Description
vocal_effort	One of "normal", "raised", "loud", "shout".

Returns: The 18-band equivalent speech spectrum level Ui, in dB SPL.

Raises

Exception	When
ValueError	for an unknown vocal effort.

StandardSpeechSpectrum

StandardSpeechSpectrum(
    frequencies: np.ndarray,
    vocal_efforts: tuple[str, ...],
    levels: np.ndarray,
)

The ANSI S3.5-1997 standard speech spectra by vocal effort (Table 3).

Bundles the standard speech spectrum level Ui of one or more vocal efforts (ANSI S3.5-1997 Table 3) over the 18 one-third-octave bands, so the spectra can be drawn with plot. Build it with standard_speech_spectra; the frozen instance is a thin, plottable wrapper and re-runs none of the maths (the band levels are the tabulated constants that standard_speech_spectrum returns).

Attributes

Name	Description
frequencies	The 18 one-third-octave band centre frequencies, in hertz (160 Hz to 8000 Hz).
vocal_efforts	The vocal efforts carried, in order; each one of "normal", "raised", "loud" or "shout".
levels	The standard speech spectrum level Ui, in dB SPL, as a (len(vocal_efforts), 18) array; row i is the spectrum for vocal_efforts[i].

StandardSpeechSpectrum.plot()

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

Plot the standard speech spectrum level versus frequency band.

Draws the standard speech spectrum level (dB SPL) over the 18 one-third-octave bands (160 Hz to 8000 Hz) on a categorical band axis; each vocal effort in vocal_efforts is one labelled line, so the whole spectrum lifting with vocal effort reads at a glance.

Requires matplotlib (pip install phonometry[plot]); returns the Axes and never calls plt.show.

Parameters

Name	Description
ax	Existing axes, or None to create a figure.
language	Label language, "en" (default) or "es".
kwargs	Forwarded to the per-effort plot calls.

Returns: The axes.