---

name: matlab-evaluate-acoustic-metrics description: > Select 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. license: https://www.mathworks.com/content/dam/mathworks/license/pmrl/license.md metadata: author: MathWorks version: "1.0"

Evaluate Acoustic Metrics

Select the correct Audio Toolbox function for acoustic measurement, apply proper calibration, and choose appropriate standards — instead of reimplementing algorithms or calling nonexistent functions.

When to Use

• Computing psychoacoustic metrics (loudness, sharpness, roughness, fluctuation)
• Evaluating speech quality or intelligibility (ViSQOL, STOI, STI, SII)
• Assessing noise compliance (NC rating, RC rating, RNC, SIL)
• Measuring SPL from recordings (offline, calibrated)
• Computing broadcast loudness (EBU R 128 / LUFS)
• Measuring reverberation time (RT60) from impulse responses
• Detecting tonal content (tone-to-noise ratio, prominence ratio)
• Converting microphone sensitivity to CalibrationFactor
• User mentions PESQ or POLQA (redirect to correct alternatives)

When NOT to Use

• Real-time streaming audio processing loops — use matlab-process-streaming-audio
• Audio device I/O, recording, or live calibrateMicrophone — use matlab-play-record-audio
• Audio plugin authoring (VST/AU) — use matlab-write-audio-plugin
• General filter design unrelated to measurement — use matlab-design-digital-filter
• Spatial audio / HRTF / SOFA processing

Workflow

Follow this decision tree to route the user's goal to the right function:

1. Identify the measurement goal

| Goal | Category | Go to | |------|----------|-------| | "How loud is it?" (perceived) | Psychoacoustic | → Psychoacoustic Metrics | | "Does it comply with broadcast loudness?" | Broadcast | → Broadcast Loudness | | "Is the noise level acceptable for this space?" | Noise compliance | → Noise Compliance | | "Can people understand speech in this room?" | Speech intelligibility | → STI/SII Measurement | | "How good does processed speech sound?" | Speech quality | → Speech Quality | | "What's the SPL?" | Level measurement | → SPL Measurement | | "What's the reverberation time?" | Room acoustics | → RT60 | | "Is there a tonal component?" | Tonality | → Tonality |

2. Ask before computing

Before writing code, confirm these with the user:

• Calibration: Do they have a CalibrationFactor? Did they calibrate with calibrateMicrophone? (See Calibration section)
• Standard: Which standard or method applies? (ISO 532-1 vs 532-2, NC vs RC vs RNC)
• Sound field: Free field or diffuse field recording?
• Application context: What space type? What's the concern? (Drives NC vs RC vs RNC selection)

3. Select function and apply

Use the Key Functions table and the category-specific patterns below.

Functions That Do NOT Exist

| Function | Status | Use Instead | |----------|--------|-------------| | pesq | Does NOT exist (proprietary ITU-T P.862 license) | visqol(degraded, reference, fs, Mode="speech") | | polqa | Does NOT exist (proprietary ITU-T P.863 license) | visqol(degraded, reference, fs) |

Never suggest pesq or polqa. They are not in Audio Toolbox and cannot be added due to licensing.

Key Functions

| Function | Purpose | Standard | Available From | |----------|---------|----------|----------------| | acousticLoudness | Perceived loudness (sones) | ISO 532-1/2 | R2020a | | acousticSharpness | Perceived sharpness (acum) | DIN 45692 | R2020a | | acousticRoughness | Perceived roughness (asper) | — | R2021a | | acousticFluctuation | Fluctuation strength (vacil) | — | R2020b | | integratedLoudness | Broadcast loudness (LUFS) | EBU R 128 / ITU-R BS.1770 | R2016b | | loudnessMeter | Streaming broadcast loudness meter | EBU R 128 / ITU-R BS.1770 | R2018a | | visqol | Full-reference audio quality (MOS) | — | R2024a | | stoi | Short-time objective intelligibility | — | R2024a | | mnru | Modulated noise reference unit | ITU-T P.810 | R2024a | | dBov | Power level relative to overload (dB) | ITU-T G.100.1 | R2024a | | speechTransmissionIndex | STI from IR or test signals | IEC 60268-16 | R2026a | | speechIntelligibilityIndex | SII from IR, test signals, or levels | ANSI/ASA S3.5-1997 | R2026b | | stipaExcitation | Generate STI/STIPA test signals | IEC 60268-16 | R2026a | | siiExcitation | Generate SII test signals | ANSI/ASA S3.5-1997 | R2026b | | noiseCriteria | NC rating + SIL + spectrum imbalance + rattle risk | ANSI/ASA S12.2 | R2026b | | roomNoiseCriteria | RNC rating (detects surging/fluctuations) | ANSI/ASA S12.2 | R2026b | | roomCriteria | RC Mark II rating (HVAC systems) | ANSI/ASA S12.2 | R2026b | | noiseCriteriaCurves | Look up NC curve values | ANSI/ASA S12.2 | R2026b | | noiseCriteriaRecommendations | Recommended NC levels by room type | ANSI/ASA S12.2 | R2026b | | speechInterferenceLevel | SIL from recording | ANSI/ASA S12.2 | R2026b | | rt60 | Reverberation time from impulse response | ISO 3382-1/2 | R2025a | | acousticToneToNoiseRatio | Detect/quantify tones | ECMA-418-1 | R2023b | | acousticProminenceRatio | Tonality via critical band comparison | ECMA-418-1 | R2023b | | splMeter | SPL measurement (time-weighted, per-band) | IEC 61672 | R2018a | | calibrateMicrophone | Compute calibration factor from known tone | — | R2018b | | weightingFilter | A/C/Z/K frequency weighting | IEC 61672-1 | R2016b | | octaveFilter | Single octave-band filter | ANSI S1.11-2004 | R2017b | | octaveFilterBank | Multi-band octave filtering | ANSI S1.11-2004 | R2019a |

See references/function-arguments.md for complete argument lists, defaults, and valid values for each function — consult when constructing calls with non-default parameters.

Calibration

CalibrationFactor from microphone sensitivity

Convert dB sensitivity (dBV/Pa) to the linear CalibrationFactor:

sensitivity_dBV = -26;  % Example: -26 dBV/Pa microphone
calibrationFactor = 1 / 10^(sensitivity_dBV/20);

The CalibrationFactor is the 3rd positional argument for acousticLoudness, acousticSharpness, acousticRoughness, and acousticFluctuation (default: sqrt(8)). For noise compliance functions, pass it as a name-value: CalibrationFactor=value.

System-level calibration advice

Always ask the user about their signal chain. If the recording path includes a preamp, audio interface, or ADC with unknown gain, the mic sensitivity spec alone is insufficient. Recommend:

1. Play a 1 kHz tone through the system and record it through the full signal chain (mic → preamp → ADC → WAV). Use a pistonphone for a known 94 dB reference, or place a physical SPL meter next to the microphone to get an SPL reading.
2. Compute the system calibration factor: calibrationFactor = calibrateMicrophone(calRecording, fs, SPLreading, FrequencyWeighting="Z-weighting")
3. Pass that factor to the measurement function

calibrateMicrophone expects a 1 kHz tone recording as input. The SPLreading argument is the known SPL in dB (e.g., 94 from a pistonphone, or the value shown on a physical SPL meter).

Cross-reference: for the physical recording workflow with calibrateMicrophone, see the matlab-play-record-audio skill.

Patterns

Psychoacoustic Metrics

[audioIn, fs] = audioread("recording.wav");
calFactor = 1 / 10^(-26/20);

loudness = acousticLoudness(audioIn, fs, calFactor, ...
    Method="ISO 532-1", SoundField="diffuse", TimeVarying=true);

sharpness = acousticSharpness(audioIn, fs, calFactor, ...
    SoundField="diffuse", TimeVarying=true);

roughness = acousticRoughness(audioIn, fs, calFactor, SoundField="diffuse");

fluctuation = acousticFluctuation(audioIn, fs, calFactor, SoundField="diffuse");

Return types: acousticLoudness returns a scalar (sones) for stationary analysis. With TimeVarying=true, it returns a column vector (time-varying loudness in sones). The second output (specificLoudness) is a matrix (time x critical bands). It does NOT return a struct or timetable.

Ask the user:

• ISO 532-1 (Zwicker, stationary/time-varying) or ISO 532-2 (Moore-Glasberg)?
• Free-field or diffuse-field recording?
• Time-varying analysis needed?

See references/psychoacoustic-metrics.md for method selection guidance (ISO 532-1 vs 532-2), interpretation tables (sone values, sharpness/roughness/fluctuation scales), tonality metric selection, and combined sound quality assessment workflows.

Unit Conversions

Use built-in functions — do NOT reimplement conversion formulas manually:

| Conversion | Function | Method selection | |------------|----------|-----------------| | phon → sone | phon2sone(phon, standard) | "ISO 532-1" (default), "ISO 532-2" | | sone → phon | sone2phon(sone, standard) | "ISO 532-1" (default), "ISO 532-2" | | Hz → ERB | hz2erb(freq) | Single formula (no variants) | | ERB → Hz | erb2hz(erb) | Single formula (no variants) | | Hz → bark | hz2bark(freq) | Single formula (no variants) | | bark → Hz | bark2hz(bark) | Single formula (no variants) | | Hz → mel | hz2mel(freq, MelStyle=s) | "oshaughnessy" (default), "slaney" | | mel → Hz | mel2hz(mel, MelStyle=s) | "oshaughnessy" (default), "slaney" |

When the user specifies a standard (e.g., "ISO 532-2"), pass it as the second positional argument for phon2sone/sone2phon. For hz2mel/mel2hz, use the MelStyle name-value pair.

Noise Compliance

Choose the function based on the application:

| Situation | Function | Why | |-----------|----------|-----| | General background noise rating | noiseCriteria | Standard NC curves (ANSI/ASA S12.2) | | HVAC system noise specifically | roomCriteria | RC Mark II designed for HVAC evaluation | | Noise with audible surging/fluctuation | roomNoiseCriteria | RNC penalizes time-varying noise (requires ≥15 s recording) | | Quick speech interference check | speechInterferenceLevel | Direct SIL value | | Need recommended levels for room type | noiseCriteriaRecommendations | Lookup table by room use |

[audioIn, fs] = audioread("office_noise.wav");

[NC, SIL, specImbalance, rattleRisk] = noiseCriteria(audioIn, fs, ...
    CalibrationFactor=2.3);

[RC, LMF, QAI, rattleRisk] = roomCriteria(audioIn, fs, ...
    CalibrationFactor=2.3);

SIL = speechInterferenceLevel(audioIn, fs, CalibrationFactor=2.3);

rec = noiseCriteriaRecommendations("NC", Occupancy="all");

Return types:

• NC is a string (e.g., "NC-35" or "NC-56 (1000 Hz)" if a band exceeds)
• RC is a string (e.g., "RC-32(N)" — the letter indicates spectrum quality: N/R/H/RV)
• SIL and LMF are double scalars (dB)
• QAI is a double scalar (dB; 0 = ideal neutral)
• specImbalance and rattleRisk are structs with .Summary (string) and .Details (table) — access .Summary for display. Exception: specImbalance degrades to a char scalar (not a struct) when NC exceeds the curve range (e.g., "Above NC-70") or falls below NC-15. Guard with isstruct(specImbalance) before dot-indexing.
• noiseCriteriaRecommendations requires a criteria name argument: "NC", "RNC", or "RC"

Ask the user:

• What type of space? (office, classroom, hospital, concert hall)
• Is the noise source HVAC? → prefer roomCriteria
• Is the noise steady or fluctuating? → if fluctuating, use roomNoiseCriteria

See `referenc