listeningpy.normalization

  1"""
  2This module contains functions for normalizing audio signals.
  3"""
  4import numpy as np
  5from scipy.signal import resample
  6import pyloudnorm as pyln
  7import mosqito
  8import logging
  9
 10def fs_to_pressure(
 11        audio : np.ndarray,
 12        dbfs_db : float,
 13        p0 : float=2e-5):
 14    """Converts audio from full-scale (FS) to pressure (Pa).
 15
 16    Parameters
 17    ----------
 18    audio : np.ndarray
 19        The input audio signal.
 20    dbfs_db : float
 21        The sound pressure level associated with 0 dBFS.
 22    p0 : float, optional
 23        The reference sound pressure in pascals (Pa), by default 2e-5.
 24
 25    Returns
 26    -------
 27    np.ndarray
 28        The audio signal converted to pressure (Pa).
 29    """
 30    ratio_db = p0 * 10 ** (dbfs_db/20)
 31    audio_pressure = audio * ratio_db
 32    return audio_pressure
 33
 34def eq_loudness_lvl(
 35        audio_pressure : np.ndarray, 
 36        fs : int, 
 37        field_type : str="diffuse"):
 38    """
 39    Calculate the log average loudness level of an audio signal.
 40
 41    Parameters
 42    ----------
 43    audio_pressure : ndarray
 44        Array containing the audio pressure values.
 45    fs : int
 46        Sampling frequency of the audio signal.
 47    field_type : str, optional
 48        Type of sound field. Possible values are "diffuse" (default) or "free".
 49    
 50    Returns
 51    -------
 52    float
 53        The loudness level in phon.
 54    tuple
 55        A tuple containing the loudness values and corresponding time values.
 56    """
 57    audio_pressure = audio_pressure.mean(axis=1)
 58    audio_pressure = resample(audio_pressure, int(audio_pressure.shape[0]*48000/fs))
 59    fs=48000
 60    N, N_spec, _, time = mosqito.loudness_zwtv(
 61        audio_pressure, 
 62        fs, 
 63        field_type=field_type
 64    )
 65    loud_lvl = 40 + 10*np.log2(N.mean())
 66    return loud_lvl, (N, time)
 67
 68def peak_normalize(
 69        audio : np.ndarray, 
 70        fs : int, 
 71        peak : float=0, 
 72        reference : np.ndarray=None
 73        ) -> tuple[np.ndarray, float]:
 74    """
 75    Normalize the peak level of an audio signal.
 76
 77    Parameters
 78    ----------
 79    audio : np.ndarray
 80        The input audio signal.
 81    fs : int
 82        The sample rate of the audio signal.
 83    peak : float, optional
 84        The desired peak level in decibels (dB), by default 0.
 85    reference : np.ndarray, optional
 86        The reference audio signal for normalization, by default None.
 87
 88    Returns
 89    -------
 90    tuple[np.ndarray, float]
 91        A tuple containing the normalized audio signal and the sample rate.
 92
 93    Notes
 94    -----
 95    This function normalizes the peak level of the input audio signal to the specified peak level.
 96    If a reference audio signal is provided, the normalization is performed relative to the peak level of the reference signal.
 97    If no reference signal is provided, the normalization is performed relative to the peak level of the input audio signal itself.
 98    The normalization factor is calculated based on the desired peak level and the maximum absolute value of the reference signal.
 99    """
100    if type(reference) == type(None):
101        reference = audio
102    factor = 10**(peak/20) / abs(reference).max()
103    logging.info(f'Stimuli was peak normalized to {peak:.1f} dB')
104    return audio * factor, fs
105
106def rms_normalize(
107        audio : np.ndarray, 
108        fs : int, 
109        rms : float=-9, 
110        reference : np.ndarray=None
111        ) -> tuple[np.ndarray, float]:
112    """
113    Normalize the audio signal to a target RMS level.
114
115    Parameters
116    ----------
117    audio : np.ndarray
118        The input audio signal.
119    fs : int
120        The sample rate of the audio signal.
121    rms : float, optional
122        The target RMS level in decibels (dB), by default -9 dB.
123    reference : np.ndarray, optional
124        The reference audio signal used for normalization, by default None.
125
126    Returns
127    -------
128    tuple[np.ndarray, float]
129        A tuple containing the normalized audio signal and the sample rate.
130
131    Notes
132    -----
133    This function normalizes the audio signal to a target RMS level specified in decibels (dB).
134    If a reference audio signal is provided, the normalization is performed relative to the RMS level of the reference signal.
135    If no reference signal is provided, the normalization is performed relative to the RMS level of the input audio signal.
136    The resulting normalized audio signal is multiplied by a scaling factor to achieve the target RMS level.
137    """
138    if type(reference) == type(None):
139        reference = audio
140    factor = 10**(rms/20) / np.sqrt(np.mean(reference**2))
141    logging.info(f'Stimuli was normalized to RMS average of {rms:.1f} dB')
142    return audio * factor, fs
143
144def lufs_normalize(
145        audio : np.ndarray, 
146        fs : int, 
147        lufs : float=-16, 
148        reference : np.ndarray=None
149        ) -> tuple[np.ndarray, int]:
150    """Normalize the loudness of an audio signal to a target LUFS level.
151
152    Parameters
153    ----------
154    audio : np.ndarray
155        The input audio signal as a NumPy array.
156    fs : int
157        The sample rate of the audio signal.
158    lufs : float, optional
159        The target loudness level in LUFS (Loudness Units Full Scale). Default is -16 LUFS.
160    reference : np.ndarray, optional
161        The reference audio signal to calculate the loudness. If not provided, the input audio signal is used as the reference.
162
163    Returns
164    -------
165    tuple[np.ndarray, int]
166        A tuple containing the normalized audio signal as a NumPy array and the sample rate as an int.
167    """
168    if type(reference) == type(None):
169        reference = audio
170    meter = pyln.Meter(fs)
171    loudness = meter.integrated_loudness(reference)
172    delta = lufs - loudness
173    factor = 10**(delta/20)
174    logging.info(f'Stimuli was loudness normalized to {lufs:.1f} dB LUFS')
175    return audio * factor, fs
176
177def ir_sum_normalize(
178        audio : np.ndarray, 
179        ir : np.ndarray, 
180        fs : int, 
181        ir_sum : float=-9):
182    """Normalize the audio based on the sum of the impulse response (IR).
183
184    This function normalizes the given audio signal based on the sum of the absolute values of the impulse response (IR).
185    The normalization factor is calculated as 10^(ir_sum/20) divided by the sum of the absolute values of the IR.
186    The audio signal is then multiplied by this factor to achieve the desired normalization.
187
188    Parameters
189    ----------
190    audio : np.ndarray
191        The input audio signal.
192    ir : np.ndarray
193        The impulse response (IR) signal.
194    fs : int
195        The sampling rate of the audio signal.
196    ir_sum : float, optional
197        The desired sum of the IR in decibels (dB), by default -9.
198
199    Returns
200    -------
201    np.ndarray
202        The normalized audio signal.
203    int
204        The sampling rate of the normalized audio signal.
205    """
206    factor = 10**(ir_sum/20) / abs(ir).sum()
207    logging.info(f'Stimuli was normalized based IR sum to {ir_sum:.1f} dB')
208    return audio * factor, fs
209
210def zwicker_loudness_normalize(
211        audio : np.ndarray,
212        fs : int,
213        target_phon : float,
214        dbfs_db: float,
215        return_ratio: bool = False
216        ) -> tuple[np.ndarray, int]:
217    audio_pressure = fs_to_pressure(audio, dbfs_db)
218    loud_lvl, loudness = eq_loudness_lvl(audio_pressure, fs)
219    loud_diff = target_phon - loud_lvl
220    logging.info(f"Before normalization: N={loud_lvl:.1f}")
221    ratio_loud = 1
222    n = 0
223    while abs(loud_diff) > 0.1:
224        ratio_loud *= 10 ** ((loud_diff)/20)
225        audio_pressure_it = audio_pressure * ratio_loud
226        loud_lvl, loudness = eq_loudness_lvl(audio_pressure_it, fs)
227        loud_diff = target_phon - loud_lvl
228        print(loud_diff)
229        n += 1
230    logging.info(f" After {n}th normalization: N={loud_lvl:.1f}")
231    audio *= ratio_loud
232    headroom = 1/abs(audio).max()
233    headroom_db = 20*np.log10(headroom)
234    if abs(audio).max() > 1:
235        logging.warning("Audio signal clipped after normalization.")
236        raise ValueError("Audio signal clipped after normalization. "+
237                         f"The level overflows for {headroom_db:.2f} dB. "+
238                         "Adjust headphone level.")
239    else:
240        logging.info(f"Audio signal normalized to {target_phon:.2f} phons.")
241        logging.info(f"Normalization factor: {ratio_loud:.2f}")
242        logging.info(f"Headroom: {-headroom_db:.2f} dB")
243    
244    if return_ratio:
245        ret = audio, fs, ratio_loud
246    else:
247        ret = audio, fs
248    return ret