Ir al contenido

electroacoustics.distortion

La referencia de la API se publica en inglés en los dos idiomas: se genera a partir de los docstrings del código, que son su texto original.

Harmonic distortion of electroacoustic equipment (IEC 60268-3 / AES17).

Single-tone distortion metrics of amplifiers and audio equipment, from a captured signal:

  • Total harmonic distortion THD (IEC 60268-3 14.12.2-3), relative to the fundamental (kind='F', the widespread convention) or to the total RMS (kind='R', the 14.12.3.2 quantity), and the nth-order harmonic distortion (14.12.5).
  • THD+N and the derived SINAD (AES17-2015 6.3.1): the fundamental is removed with the standard notch filter and the residual is compared with the total signal, both through the AES17 measurement bandwidth (20 Hz to 20 kHz by default).
  • Weighted THD (14.12.11), the harmonic residual weighted by the IEC 60268-1 / ITU-R BS.468-4 network (A/C optional), whose nominal response weighting_bs468 exposes on its own.

All metrics have an exact analytic oracle: a signal synthesised with known harmonic amplitudes reproduces the closed-form ratio. The functions assume the tones fall on (or very near) FFT bins: use coherent sampling (an integer number of periods) or supply a low-leakage window, as audio analysers do.

The two-tone metrics of IEC 60268-3 14.12.7-10 live in phonometry.electroacoustics.intermodulation, and the AES17-2015 6.4 noise levels in phonometry.electroacoustics.noise_measurements; both are built on the spectrum, notch and weighting helpers of this module.

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

harmonic_analysis(
x: Signal | NumericArrayLike,
fs: float | None = None,
fundamental: float | None = None,
*,
n_harmonics: int = 10,
notch_q: float = 2.0,
bandwidth: float | None = 20000.0,
window: str | tuple[str | NumericArrayLike, ...] = 'hann',
) -> HarmonicDistortionResult

Full harmonic analysis of a signal (THD, THD+N, SINAD).

Bundles the fundamental, the harmonic amplitudes and the THD (both conventions), THD+N and SINAD into a plottable result.

Parameters

Name Description
x Captured signal (1-D). Accepts a phonometry.io.Signal, whose calibration is applied to the samples: the three distortion ratios come out unchanged, and so does sinad_db, which is the decibel form of one such ratio rather than a level. Only harmonic_amplitudes carries the unit, and so lands in pascals when the record is calibrated.
fs Sample rate, in Hz. Required for a bare array; a Signal brings its own, and an explicit value that disagrees with it raises instead of silently winning.
fundamental Fundamental frequency, or None to auto-detect.
n_harmonics Highest harmonic order (default 10).
notch_q Effective notch quality factor for THD+N (default 2.0).
bandwidth AES17 measurement bandwidth for THD+N/SINAD, in Hz (default 20 kHz; None measures the full Nyquist band).
window FFT window, a scipy window name or a tuple of a name and its parameters (default 'hann').

Returns: A HarmonicDistortionResult.

Raises

Exception When
ValueError If the inputs are invalid.
TypeError if fs is not a single number, or x holds a text or a value that is not a real number. fundamental is refused the same way when it is not one real number.
harmonic_distortion(
x: Signal | NumericArrayLike,
fs: float | None = None,
*,
fundamental: float,
order: int | np.integer[Any],
n_harmonics: int = 10,
window: str | tuple[str | NumericArrayLike, ...] = 'hann',
) -> float

nth-order harmonic distortion (IEC 60268-3 14.12.5).

, the nth harmonic amplitude relative to the total RMS.

Parameters

Name Description
x Captured signal (1-D). Accepts a phonometry.io.Signal, whose calibration is applied to the samples and then cancels: this is a ratio of amplitudes drawn from the same record, so the factor divides out and the answer is the same calibrated or not.
fs Sample rate, in Hz. Required for a bare array; a Signal brings its own, and an explicit value that disagrees with it raises instead of silently winning.
fundamental Fundamental frequency , in Hz.
order Harmonic order n (an integer >= 2; an integral float such as 3.0 is accepted as its integer).
n_harmonics Highest harmonic order used for the total RMS.
window FFT window, a scipy window name or a tuple of a name and its parameters (default 'hann').

Returns: nth-order harmonic distortion, as a ratio.

Raises

Exception When
ValueError If order is not an integer, order < 2 or the inputs are invalid.
TypeError if fs or fundamental is not a single number, or order is a flag, a text or an array where a count goes, or x holds a text or a value that is not a real number.
HarmonicDistortionResult(
fundamental: float,
harmonic_frequencies: NDArray[np.float64],
harmonic_amplitudes: NDArray[np.float64],
thd_f: float,
thd_r: float,
thd_plus_noise: float,
sinad_db: float,
)

Harmonic analysis of a signal (IEC 60268-3 / AES17).

Attributes

Name Description
fundamental Fundamental frequency , in Hz.
harmonic_frequencies Harmonic frequencies present, in Hz.
harmonic_amplitudes Peak amplitudes of the harmonics.
thd_f Total harmonic distortion relative to the fundamental.
thd_r Total harmonic distortion relative to the total RMS.
thd_plus_noise THD+N ratio (AES17).
sinad_db SINAD, in dB.
HarmonicDistortionResult.plot(
ax: Axes | None = None,
*,
language: Literal['en', 'es'] = 'en',
**kwargs: Any,
) -> Axes

Plot the magnitude spectrum with the harmonics marked.

Parameters

Name Description
language Label language, "en" (default) or "es".
sinad(
x: Signal | NumericArrayLike,
fs: float | None = None,
fundamental: float | None = None,
*,
notch_q: float = 2.0,
bandwidth: float | None = 20000.0,
window: str | tuple[str | NumericArrayLike, ...] = 'hann',
) -> float

Signal-to-noise-and-distortion ratio SINAD, in dB.

the reciprocal, in dB, of the THD+N ratio. AES17-2015 does not itself define SINAD; this value is derived from the AES17 6.3.1 THD+N measurement (same notch, same measurement bandwidth).

Parameters

Name Description
x Captured signal (1-D). Accepts a phonometry.io.Signal, whose calibration is applied to the samples and then cancels: SINAD is the decibel form of a ratio of amplitudes drawn from the same record rather than a level, so the factor divides out and the answer is the same calibrated or not.
fs Sample rate, in Hz. Required for a bare array; a Signal brings its own, and an explicit value that disagrees with it raises instead of silently winning.
fundamental Fundamental frequency, or None to auto-detect.
notch_q Effective notch quality factor (AES17: 1.2..3; default 2.0).
bandwidth Upper band-edge frequency of the AES17 chain, in Hz (default 20 kHz); None measures the full Nyquist band.
window FFT window, a scipy window name or a tuple of a name and its parameters, used only for fundamental auto-detection.

Returns: SINAD, in dB.

Raises

Exception When
ValueError If the inputs are invalid.
thd(
x: Signal | NumericArrayLike,
fs: float | None = None,
fundamental: float | None = None,
*,
kind: Literal['F', 'R'] = 'F',
n_harmonics: int = 10,
window: str | tuple[str | NumericArrayLike, ...] = 'hann',
) -> float

Total harmonic distortion (IEC 60268-3 14.12.2-3).

From the harmonic amplitudes :

relative to the fundamental (kind='F') or to the total RMS (kind='R'), respectively.

Convention note: the quantity the IEC 60268-3 14.12.3.2 formula defines is the R form (harmonic RMS over total RMS). The default kind='F' is the fundamental-referenced convention widespread in audio practice and datasheets; the two agree to first order for small distortion.

Parameters

Name Description
x Captured signal (1-D). Accepts a phonometry.io.Signal, whose calibration is applied to the samples and then cancels: this is a ratio of amplitudes drawn from the same record, so the factor divides out and the answer is the same calibrated or not. Coherent sampling (integer periods) or a low-leakage window gives the exact value.
fs Sample rate, in Hz. Required for a bare array; a Signal brings its own, and an explicit value that disagrees with it raises instead of silently winning.
fundamental Fundamental frequency in Hz, or None to take the largest spectral peak.
kind 'F' (relative to the fundamental, the default) or 'R' (relative to the total RMS, the 14.12.3.2 quantity).
n_harmonics Highest harmonic order summed (default 10).
window FFT window, a scipy window name or a tuple of a name and its parameters (default 'hann').

Returns: Total harmonic distortion, as a ratio (0..).

Raises

Exception When
ValueError If the signal/parameters are invalid, kind is unknown, or no harmonic of the fundamental lies below Nyquist.
TypeError if fs is not a single number, or kind is not a text, or x holds a text or a value that is not a real number. fundamental is refused the same way when it is not one real number.
thd_plus_noise(
x: Signal | NumericArrayLike,
fs: float | None = None,
fundamental: float | None = None,
*,
notch_q: float = 2.0,
bandwidth: float | None = 20000.0,
window: str | tuple[str | NumericArrayLike, ...] = 'hann',
as_db: bool = False,
) -> float

THD+N ratio (AES17-2015 6.3.1).

The fundamental is removed with the standard notch filter (, validated on the applied zero-phase response per 5.2.8) and the residual RMS is compared with the total RMS: (a ratio, or of it in dB). Both voltages are measured through the AES17 measurement bandwidth (a 20 Hz high-pass plus the standard low-pass at bandwidth, 5.2.5 / 6.3.1), so DC offsets and out-of-band noise do not inflate the result.

Parameters

Name Description
x Captured signal (1-D). Accepts a phonometry.io.Signal, whose calibration is applied to the samples and then cancels: this is a ratio of amplitudes drawn from the same record, so the factor divides out and the answer is the same calibrated or not.
fs Sample rate, in Hz. Required for a bare array; a Signal brings its own, and an explicit value that disagrees with it raises instead of silently winning.
fundamental Fundamental frequency, or None to auto-detect.
notch_q Effective notch quality factor (AES17: 1.2..3; default 2.0).
bandwidth Upper band-edge frequency of the AES17 chain, in Hz (default 20 kHz, the 5.2.5 standard value; capped at Nyquist). None disables the chain and measures the full Nyquist band (20 Hz high-pass included only when the chain is active).
window FFT window, a scipy window name or a tuple of a name and its parameters, used only for fundamental auto-detection.
as_db Return in dB instead of the ratio.

Returns: THD+N as a ratio (default) or in dB.

Raises

Exception When
ValueError If the inputs are invalid or notch_q out of range.
TypeError if bandwidth, fs, fundamental or notch_q is not a single number, or x holds a text or a value that is not a real number.
weighted_thd(
x: Signal | NumericArrayLike,
fs: float | None = None,
fundamental: float | None = None,
*,
notch_q: float = 2.0,
weighting: Literal['468', 'A', 'C'] = '468',
window: str | tuple[str | NumericArrayLike, ...] = 'hann',
) -> float

Weighted total harmonic distortion (IEC 60268-3 14.12.11).

The fundamental is notched out and the residual is frequency-weighted before its RMS is compared with the total signal RMS, so the perceptual emphasis of the distortion products is accounted for. The default weighting is the network required by the clause: IEC 60268-1:1985 Appendix A, the ITU-R BS.468-4 curve (peaking +12.2 dB near 6.3 kHz) with its standard 0 dB at 1 kHz normalization; 'A' and 'C' (IEC 61672-1) are kept as explicitly labelled alternatives, not 14.12.11 quantities.

Validity note (14.12.11): because of the shape of the weighting response, the weighted measurement is valid only for fundamental frequencies between 31.5 Hz and 400 Hz.

Parameters

Name Description
x Captured signal (1-D). Accepts a phonometry.io.Signal, whose calibration is applied to the samples and then cancels: this is a ratio of amplitudes drawn from the same record, so the factor divides out and the answer is the same calibrated or not.
fs Sample rate, in Hz. Required for a bare array; a Signal brings its own, and an explicit value that disagrees with it raises instead of silently winning.
fundamental Fundamental frequency, or None to auto-detect.
notch_q Effective notch quality factor (default 2.0).
weighting Frequency weighting applied to the residual: '468' (ITU-R BS.468-4 / IEC 60268-1, the 14.12.11 default), 'A' or 'C'.
window FFT window, a scipy window name or a tuple of a name and its parameters, used only for fundamental auto-detection.

Returns: Weighted THD, as a ratio.

Raises

Exception When
ValueError If the inputs are invalid.
TypeError if fs, fundamental or notch_q is not a single number, or weighting is not a text, or x holds a text or a value that is not a real number.
weighting_bs468(
frequencies: float | np.floating[Any] | np.integer[Any],
) -> float
weighting_bs468(
frequencies: Sequence[float] | Sequence[np.floating[Any]] | Sequence[np.integer[Any]] | NDArray[np.bool_ | np.integer[Any] | np.floating[Any]],
) -> NDArray[np.float64]
weighting_bs468(
frequencies: NumericArrayLike,
) -> float | NDArray[np.float64]

ITU-R BS.468-4 weighting response, in dB re 1 kHz.

Clause 1 of the Recommendation defines the nominal curve as the response of the passive network of Fig. 1a and prints Table 1 as “the values of this response at various frequencies”, so the curve exists at every frequency and the 21 printed rows are that curve rounded to 0.1 dB. This is the closed-form evaluation of the same analog prototype the '468' branch of WeightingFilter discretises,

with one zero at the origin, the six poles of the Fig. 1a ladder and set for 0 dB at the 1 kHz reference. The value is what a psophometric noise meter’s weighting network would add to a tone at that frequency: about +12.22 dB at the 6.3 kHz peak, where broadcast-chain noise is most audible, and -22.2 dB at 20 kHz. Zero frequency (dc) maps to -inf dB, which is the series capacitor of Fig. 1a. AES17-2015 5.2.7 tabulates the same curve with an additional gain of -5.63 dB (unity at 2 kHz, the “CCIR-RMS” filter). The comma is AES 17’s own: the decimal separator here follows the document being quoted, and BS.468-4 prints a point where AES 17 prints a comma.

Reading the 21 rows and interpolating between them, which is what this function used to do, departs from the network by up to 0.611 dB at 11 058 Hz, where the curve turns over fastest and the table samples it most coarsely. (The log-frequency interpolation rule of Table 1’s footnote (1) governs the tolerance column, not the response, and runs between six mask frequencies rather than all 21.)

Parameters

Name Description
frequencies Frequencies, in Hz (scalar or array-like, >= 0).

Returns: Response in dB re the 1 kHz value, same shape as the input. A float for a number, an array for a sequence or an array, a zero-dimensional one included.

Raises

Exception When
ValueError for negative or non-finite frequencies.
TypeError if frequencies holds a text or a value that is not a real number.