Scaper sometimes produces soundscapes with clipping if ref_db is set badly.

[pseeth]

Scaper clips sometimes.

I suggest we add some logic to the Scaper.generate and Scaper._generate_audio functions. Namely two parameters:

Parameters
------------
fix_clipping : bool
    Checks the soundscape audio for clipping (abs(sample) > 1). If so, then the soundscape is 
    peak_normalized and the audio for each event is scaled accordingly. Defaults to ???
peak_normalize : bool
    Always peak normalize the soundscape regardless of clipping. Note that if this is turned
    on, then the loudness of the soundscape will be off of what `ref_db` is set to. Defaults to
    False.

If the soundscape is clipping, then the peak_normalize functionality is used if fix_clipping is
True.

I think a good home for this logic would be in scaper.audio.peak_normalize. The signature might
look like this:

def peak_normalize(soundscape_audio, event_audio_list):
   # figure out scaling factor to peak normalize the soundscape_audio.
   eps = 1e-10
   scale = np.max(np.abs(soundscape_audio))
   # scale the event audio and the soundscape audio:
   soundscape_audio = soundscape_audio / (scale + eps)
   for i, event_audio in enumerate(event_audio_list):
     event_audio_list[i] = event_audio / (scale + eps)
   return soundscape_audio, event_audio_list

We would call this function from core.py.

[justinsalamon]

Based on offline discussion:

• Update API in generate with fix_clipping and peak_normalization. By default these will be... False? We can check for clipping and raise a warning? It feels like this would respect the ref_db?
• Raise warnings when: (1) there's clipping, (2) normalization is applied, (3) if the normalization factor is very small (< 0.05)
• Implement the functionality in audio.py
• Change the ref_db stored in the JAMS annotation to reflect the udpated red_db. Store original red_db somewhere?
• Also update API for generate_from_jams