matlab/matlab-agentic-toolkit / skills-catalog/signal-processing/matlab-evaluate-acoustic-metrics
matlab-evaluate-acoustic-metrics
VerifiedSelect and use Audio Toolbox acoustic, psychoacoustic, and speech quality metrics. Use when computing loudness, sharpness, roughness, fluctuation strength, noise criteria (NC/RNC/RC), speech transmission index (STI), speech intelligibility index (SII), speech quality (ViSQOL, STOI), SPL, reverberation time (RT60), tone-to-noise ratio, or prominence ratio. Also use when asked about PESQ, POLQA, calibration factor, EBU R 128, LUFS, HVAC noise, background noise evaluation, or how to measure audio quality or noise compliance. Covers calibration, standard selection, signal alignment, and the complete function inventory including what does NOT exist.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 22.7 KB |
| manifest.yaml | config | 444 B |
| references/function-arguments.md | markdown | 7.3 KB |
| references/noise-compliance.md | markdown | 16.4 KB |
| references/psychoacoustic-metrics.md | markdown | 16.0 KB |
| references/rt60-measurement.md | markdown | 14.4 KB |
| references/sii-measurement.md | markdown | 16.9 KB |
| references/spl-measurement.md | markdown | 12.5 KB |
| references/sti-measurement.md | markdown | 14.0 KB |
references/sii-measurement.md
View on GitHub# SII Measurement
## Intake Questions
### 1. What is the application?
SII measures whether speech is audible and intelligible under given noise and hearing conditions. Common use cases:
| Application | Typical Approach |
|-------------|-----------------|
| Room/system evaluation with a recording | IR-based or Direct method (like STI) |
| Hearing aid evaluation | Level-only method with `InsertionGain` and `HearingThresholdLevel` |
| Telecom or communication system design | Direct method through the system |
| Noise environment assessment (no audio) | Level-only method with estimated noise and speech levels |
| Classroom design for hearing-impaired students | Level-only method with `HearingThresholdLevel` and room noise |
### 2. Do they have audio, or just level specifications?
- **Have IR or audio:** Use IR-based or Direct method (same as STI)
- **Only have noise levels and speech specs:** Use the Level-only method -- no audio signal needed. Provide noise level, vocal effort, and distance.
### 3. Listener characteristics
Ask about:
- **Hearing loss:** Does the listener have elevated hearing thresholds? -> `HearingThresholdLevel` (dB HL per band)
- **Conductive hearing loss:** -> `ConductiveHearingLossLevel` (must be <= `HearingThresholdLevel`)
- **Hearing device:** Is an amplification device being evaluated? -> `InsertionGain` (gain curve per band)
- **Binaural advantage:** Is the listener using both ears? -> `IsBinaural=true` (adds ~1 dB effective SNR benefit)
### 4. Communication conditions (Level-only method)
- **Vocal effort:** Normal, raised, loud, or shout? (Changes spectral shape, not just level)
- **Distance:** Talker-to-listener distance in meters (inverse-square-law attenuation applied)
- **Noise level:** Measured or estimated background noise (scalar dB OASPL or per-band vector)
- **Measurement location:** Free-field or at eardrum? (Affects the transfer function applied)
### 5. Band procedure
SII can use different frequency resolution:
- `"critical band"` -- 21 bands (default for IR/Direct methods)
- `"1/3 octave band"` -- 18 bands
- `"equally-contributing critical band"` -- 17 bands
- `"octave band"` -- 6 bands (least precise, fastest)
The choice affects precision slightly; `"1/3 octave band"` is common for practical measurements.
## Standard Clauses & Workflow Selection
The ANSI/ASA S3.5-1997 standard defines three calculation methods (clauses 5.1-5.3) in increasing order of generality. The standard also allows workflows outside these clauses.
### When to Use Each Clause
| Clause | Conditions Required | Typical Scenario |
|--------|-------------------|------------------|
| 5.1 (Levels only) | Low reverberation; listener faces source directly (or omnidirectional); speech and noise are independent; system is linear | Office noise assessment, outdoor environments, simple room predictions |
| 5.2 (Measurements at listener position) | Well-mixed sound field OR direct facing/omnidirectional; linear system; identical conditions in both ears | Room acoustics with measurement mic at head center, PA system evaluation |
| 5.3 (Measurements at eardrum) | Linear system; identical conditions in both ears; measurements taken at eardrum (HATS or probe mic) | Hearing device evaluation, eardrum-level assessment, binaural research |
### Practical Scenario Mapping
| Scenario | Recommended Approach | Rationale |
|----------|---------------------|-----------|
| "Will speech be intelligible in this room design?" (no measurements) | Clause 5.1 -- level-only method with estimated noise and standard speech | Fastest; no equipment needed; sufficient for design-stage predictions |
| "Evaluate speech intelligibility of installed PA system" | Clause 5.2 -- IR or direct method with mic at listener head position | Captures room acoustics and system response; standard positioning |
| "Assess hearing aid benefit for a patient" | Clause 5.3 -- with InsertionGain, HearingThresholdLevel, eardrum measurement location | Models device insertion gain and listener-specific hearing loss |
| "Compare noise environments for regulatory compliance" | Clause 5.1 -- with measured noise levels per band | Standard-compliant with measured noise; speech levels from standard |
| "Evaluate classroom acoustics with measured IR" | Clause 5.2 -- IR method with measured ambient noise | Realistic room assessment; compare to ANSI S12.60 targets |
| "Assess telecom system speech quality" | Clause 5.2 -- direct method with siiExcitation through the codec | Captures codec distortion and frequency shaping |
### Measurement Positioning by Clause
**Clause 5.1 (free-field, no audio):**
- No physical microphone measurement required for the SII computation itself
- If measuring noise levels: place mic at center of listener's head position, without listener present
- Speech levels typically come from the standard (selected via VocalEffort) or custom measurements at 1 m from talker
**Clause 5.2 (free-field, at listener position):**
- Microphone at center of listener's head, mid-point between ears
- Listener must NOT be present during measurement
- Transmit excitation signal from the talker/source position
- Set `SpeechMeasurementLocation="free-field"` and `NoiseMeasurementLocation="free-field"`
**Clause 5.3 (eardrum):**
- Use a Head and Torso Simulator (HATS) designed for eardrum measurements, OR
- Probe tube microphone within 5 mm of eardrum on >=8 otologically normal subjects (age 18-30)
- Set `SpeechMeasurementLocation="eardrum"` and `NoiseMeasurementLocation="eardrum"`
- Must specify `SpeechAndNoiseLevel` when using IR or direct method with eardrum location
### Workflows Beyond the Standard
The three standard clauses do not cover every valid use case. Common non-standard workflows:
| Workflow | Approach | Key Differences from Standard Clauses |
|----------|----------|---------------------------------------|
| Hearing device evaluation (no room measurement) | Level-only method + InsertionGain + HearingThresholdLevel | Uses clause 5.1 inputs but adds device/listener parameters |
| Binaural advantage assessment | Any clause + `IsBinaural=true` | Reduces equivalent hearing threshold by 1.7 dB |
| Custom speech material weighting | Any clause + custom `BandImportanceFunction` vector | Weights bands differently than standard speech |
| Noise environment comparison (parametric) | Level-only method, vary NoiseLevel | Quick what-if analysis without re-measuring |
| In-ear monitor evaluation | Direct method + eardrum location + InsertionGain | Combines clause 5.3 positioning with device modeling |
| Classroom design for hearing-impaired | Level-only method + HearingThresholdLevel + room noise | Clause 5.1 with listener-specific hearing model |
### BandImportanceFunction Selection
The BIF weights frequency bands by their relative importance to intelligibility. Choice depends on the speech material being evaluated:
| BIF Value | Speech Material | When to Use |
|-----------|----------------|-------------|
| `"standard"` | Average English sentences | Default for most assessments -- general-purpose |
| `"NNS"` | Nonsense syllables (CVC) | When testing pure audibility without linguistic context |
| `"CID-22"` | CID Everyday Sentences | Clinical audiometry with sentence-level material |
| `"NU6"` | Northwestern University Auditory Test No. 6 | Monosyllabic word recognition testing |
| `"DRT"` | Diagnostic Rhyme Test | Military/tactical communication systems assessment |
| `"Short Passages"` | Connected discourse (paragraphs) | Lecture/presentation intelligibility; high redundancy |
| `"SPIN"` | Speech Perception in Noise sentences | Assessment in noisy environments; high-context and low-context |
| Custom vector | User-defined | Specialized material, non-English languages, music intelligibility |
**Guidance:**
- Use `"standard"` unless the assessment targets a specific test protocol
- For hearing aid fitting/evaluation, match the BIF to the clinical test material used
- For communication system certification, match the BIF to the test protocol (e.g., DRT for military standards)
- Custom vectors must have one value per band (B values) and contain at least one nonzero element -- the function normalizes so they sum to 1
### SpeechAndNoiseLevel for Standard Compliance
For IR-based and direct methods, the standard recommends specifying `SpeechAndNoiseLevel`. This corresponds to the Combined Speech and Noise Spectrum Level (CSNSL) in ANSI/ASA S3.5-1997 clauses 5.2/5.3 -- the unmodulated spectrum level of the received signal (speech + noise together) measured at the listener position or eardrum.
- Measure with a calibrated SPL meter at the listener position during normal operational conditions (speech + noise simultaneously present)
- Report as a per-band vector in dB SPL for standard compliance (scalar OASPL is accepted but may be non-compliant)
- If you cannot measure combined levels, specify `NoiseLevel` separately (the function derives E' and N' differently)
**When using the IR method with separately measured noise:** The IR captures the room's effect on speech but does not contain ambient noise. If background noise is present during operation, specify `NoiseLevel` as a per-band vector measured at the listener position with the speech source off. The function adds this noise contribution to the SII calculation. Without it, the function assumes negligible noise (-50 dB/Hz per band).
## speechIntelligibilityIndex
Three syntaxes are available. **NV arguments are syntax-specific** -- using the wrong argument for a syntax causes an error.
### Method 1: IR-based
```matlab
[ir, fs] = audioread("room_ir.wav");
sii = speechIntelligibilityIndex(ir, fs);
```
### Method 2: Direct (test signal)
```matlab
fs = 48000;
[reference, speechRef] = siiExcitation(fs, Duration=16);
% --- Transmit 'reference' through system, record 'processed' ---
% Align signals (required -- SII is more sensitive to misalignment than STI)
% alignsignals requires vector input; use finddelay on one column instead
delay = finddelay(reference(:,1), processed(:,1));
if delay > 0
processed = processed(delay+1:end, :);
reference = reference(1:size(processed,1), :);
elseif delay < 0
reference = reference(-delay+1:end, :);
processed = processed(1:size(reference,1), :);
end
sii = speechIntelligibilityIndex(processed, reference, fs);
```
### Method 3: From levels only (no audio signal)
SII can be computed from speech and noise level specifications alone:
```matlab
sii = speechIntelligibilityIndex();
sii = speechIntelligibilityIndex(Method="1/3 octave band", ...
NoiseLevel=40, VocalEffort="raised", Distance=2);
```
### Name-Value Arguments by Syntax
**Valid for IR-based and Direct methods only:**
| Argument | Default | Purpose |
|----------|---------|---------|
| `SpeechAndNoiseLevel` | -- | Combined speech+noise level per band (dB SPL vector). Recommended for standard compliance. |
| `NoiseLevel` | -50 dB/Hz per band | Noise level -- numeric vector (dB SPL) or scalar (dB OASPL) |
**Note:** For standard-compliant SII results with the IR or Direct method, specify `SpeechAndNoiseLevel` as a per-band vector. Without it, the function uses default levels and emits a warning.
**Valid for Level-only method only:**
| Argument | Default | Purpose |
|----------|---------|---------|
| `SpeechLevel` | `"standard"` | `"standard"`, `"idealized"`, or numeric vector (dB SPL) |
| `NoiseLevel` | -50 dB/Hz per band | Noise level -- numeric vector (dB SPL) or scalar (dB OASPL) |
| `Distance` | 1 m | Talker-to-listener distance |
| `VocalEffort` | `"normal"` | `"normal"`, `"raised"`, `"loud"`, `"shout"` |
**Valid for all syntaxes:**
| Argument | Default | Purpose |
|----------|---------|---------|
| `Method` | -- | Band procedure: `"critical band"`, `"1/3 octave band"`, `"equally-contributing critical band"`, `"octave band"` |
| `InsertionGain` | 0 dB | Hearing device gain (scalar or 1-by-B vector) |
| `HearingThresholdLevel` | 0 dB HL | Listener hearing threshold (scalar or 1-by-B vector) |
| `ConductiveHearingLossLevel` | 0 dB HL | Conductive hearing loss (must be <= HearingThresholdLevel) |
| `BandImportanceFunction` | `"standard"` | `"standard"`, `"NNS"`, `"CID-22"`, `"NU6"`, `"DRT"`, `"Short Passages"`, `"SPIN"` |
| `SpeechMeasurementLocation` | `"free-field"` | `"free-field"` or `"eardrum"` |
| `NoiseMeasurementLocation` | `"free-field"` | `"free-field"` or `"eardrum"` |
| `IsBinaural` | `false` | Binaural listening advantage |
**Critical constraints:**
- `VocalEffort`, `Distance`, and `SpeechLevel` are INVALID for IR-based and Direct methods -- they cause an error
- `SpeechAndNoiseLevel` is INVALID for the Level-only method -- use `SpeechLevel` and `NoiseLevel` separately instead
- `ConductiveHearingLossLevel` must be <= `HearingThresholdLevel` in all bands
**Ask the user about:**
- What is the talker-to-listener distance? (level-only method)
- What vocal effort level? (level-only method)
- Does the listener have hearing loss? (affects HearingThresholdLevel)
- Is a hearing device being evaluated? (InsertionGain)
- What noise level is present? (measured or estimated)
### Outputs
```matlab
[sii, baf, mtf] = speechIntelligibilityIndex(ir, fs, ...
NoiseLevel=40);
```
- `sii` -- Speech intelligibility index (0 to 1)
- `baf` -- Band audibility function (table)
- `mtf` -- Modulation transfer function (table)
## siiExcitation
```matlab
[mtfExcitation, speechExcitation, expLevels] = siiExcitation(fs, Duration=16);
mtfExcitation = siiExcitation(fs, Duration=20, ...
VocalEffort="raised", Method="1/3 octave band");
```
The `expLevels` output provides expected speech spectrum levels for system calibration.
## Signal Alignment
`speechIntelligibilityIndex` does not perform internal alignment for the direct method. SII is more sensitive to misalignment than STI.
**Impact of misalignment (empirically measured):**
| Delay | SII Error (20s signal) |
|-------|----------------------|
| <=50 ms | 0.016 (significant) |
| 100 ms | 0.029 |
| 200 ms | 0.036 |
Always align for the direct method. Because `siiExcitation` returns an N-by-9 matrix (not a vector), use `finddelay` on one column:
```matlab
delay = finddelay(reference(:,1), processed(:,1));
if delay > 0
processed = processed(delay+1:end, :);
reference = reference(1:size(processed,1), :);
elseif delay < 0
reference = reference(-delay+1:end, :);
processed = processed(1:size(reference,1), :);
end
```
The IR-based method avoids this issue entirely -- `impzest` deconvolution handles propagation delay during IR extraction.
## Complete Workflow: Evaluate SII for Hearing Device
```matlab
sii = speechIntelligibilityIndex( ...
Method="1/3 octave band", ...
NoiseLevel=50, ...
VocalEffort="normal", ...
Distance=1, ...
InsertionGain=gainCurve, ...
HearingThresholdLevel=audiogram);
```
## Interpreting Results
### SII Scale
| SII Range | Interpretation |
|-----------|---------------|
| 0.75-1.00 | Speech highly intelligible; nearly all speech cues audible |
| 0.45-0.75 | Moderate intelligibility; context helps significantly |
| 0.20-0.45 | Poor intelligibility; only familiar phrases understood |
| < 0.20 | Speech essentially inaudible above the noise |
### Key Differences from STI
- SII measures **audibility** of speech given noise and hearing -- can the listener detect speech cues?
- STI measures **transmission fidelity** -- does the channel preserve modulations?
- SII can be computed without any audio (level-only method) -- just noise spectrum + speech level + hearing threshold
- SII accounts for listener hearing loss; STI does not
- SII is more appropriate for hearing device evaluation; STI is more appropriate for room/PA evaluation
### Band Audibility Function (BAF) Diagnostics
The BAF output shows the proportion of speech information audible in each frequency band (0 = completely masked, 1 = fully audible):
- **Low BAF at low frequencies:** Low-frequency noise masks speech fundamentals -- less critical for intelligibility
- **Low BAF at 1-4 kHz:** Critical concern -- these bands carry the most speech information (consonant cues)
- **Low BAF at high frequencies with normal hearing:** HF noise or air absorption
- **Low BAF at high frequencies with hearing loss:** Expected sensorineural pattern -- evaluate hearing device InsertionGain in these bands
## Troubleshooting
| Observation | Likely Cause | Action |
|-------------|-------------|--------|
| Error about invalid NV argument | Wrong argument for the syntax -- VocalEffort/Distance only valid for Level-only method | Check which syntax is being used; see constraints table above |
| SII = 1.0 (perfect) | Speech far above noise in all bands | Expected for close-range, quiet conditions with normal hearing |
| SII near 0 with moderate noise | HearingThresholdLevel too high, or noise level wrong | Verify units -- noise should be dB SPL, hearing in dB HL |
| SII doesn't change with InsertionGain | Gain doesn't overcome the hearing threshold deficit | Check that InsertionGain + SpeechLevel - NoiseLevel > HearingThresholdLevel in critical bands |
| Warning about default levels | SpeechAndNoiseLevel not specified for IR/Direct method | Provide measured per-band levels for standard-compliant results |
----
Copyright 2026 The MathWorks, Inc.
----
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |