Audio¶
Audio¶
audio.py: Utilities for dealing with audio files
-
class
opensoundscape.audio.
Audio
(samples, sample_rate, resample_type='kaiser_fast', max_duration=None)¶ Container for audio samples
Initializing an Audio object directly requires the specification of the sample rate. Use Audio.from_file or Audio.from_bytesio with sample_rate=None to use a native sampling rate.
Parameters: - samples (np.array) – The audio samples
- sample_rate (integer) – The sampling rate for the audio samples
- resample_type (str) – The resampling method to use [default: “kaiser_fast”]
- max_duration (None or integer) – The maximum duration allowed for the audio file [default: None]
Returns: An initialized Audio object
-
bandpass
(low_f, high_f, order)¶ Bandpass audio signal frequencies
Uses a phase-preserving algorithm (scipy.signal’s butter and solfiltfilt)
Parameters: - low_f – low frequency cutoff (-3 dB) in Hz of bandpass filter
- high_f – high frequency cutoff (-3 dB) in Hz of bandpass filter
- order – butterworth filter order (integer) ~= steepness of cutoff
-
duration
()¶ Return duration of Audio
Returns: The duration of the Audio Return type: duration (float)
-
extend
(length)¶ Extend audio file by looping it
Parameters: length – the final length in seconds of the extended file Returns: a new Audio object of the desired length
-
classmethod
from_bytesio
(bytesio, sample_rate=None, max_duration=None, resample_type='kaiser_fast')¶ Read from bytesio object
Read an Audio object from a BytesIO object. This is primarily used for passing Audio over HTTP.
Parameters: - bytesio – Contents of WAV file as BytesIO
- sample_rate – The final sampling rate of Audio object [default: None]
- max_duration – The maximum duration of the audio file [default: None]
- resample_type – The librosa method to do resampling [default: “kaiser_fast”]
Returns: An initialized Audio object
-
classmethod
from_file
(path, sample_rate=None, resample_type='kaiser_fast', max_duration=None)¶ Load audio from files
Deal with the various possible input types to load an audio file and generate a spectrogram
Parameters: - path (str, Path) – path to an audio file
- sample_rate (int, None) – resample audio with value and resample_type, if None use source sample_rate (default: None)
- resample_type – method used to resample_type (default: kaiser_fast)
- max_duration – the maximum length of an input file, None is no maximum (default: None)
Returns: attributes samples and sample_rate
Return type:
-
resample
(sample_rate, resample_type=None)¶ Resample Audio object
Parameters: - sample_rate (scalar) – the new sample rate
- resample_type (str) – resampling algorithm to use [default: None (uses self.resample_type of instance)]
Returns: a new Audio object of the desired sample rate
-
save
(path)¶ Save Audio to file
Parameters: path – destination for output
-
spectrum
()¶ Create frequency spectrum from an Audio object using fft
Parameters: self – Returns: fft, frequencies
-
split
(clip_duration, clip_overlap=0, final_clip=None)¶ Split Audio into clips
The Audio object is split into clips of a specified duration and overlap
Parameters: - clip_duration (float) – The duration in seconds of the clips
- clip_overlap (float) – The overlap of the clips in seconds [default: 0]
- final_clip (str) –
Behavior if final_clip is less than clip_duration seconds long. [default: None] By default, ignores final clip entirely. Possible options (any other input will ignore the final clip entirely),
- ”remainder”: Include the remainder of the Audio (clip will not have clip_duration length)
- ”full”: Increase the overlap to yield a clip with clip_duration length
- ”extend”: Similar to remainder but extend (repeat) the clip to reach clip_duration length
Returns: [“audio”, “begin_time”, “end_time”]
Return type: A list of dictionaries with keys
-
time_to_sample
(time)¶ Given a time, convert it to the corresponding sample
Parameters: time – The time to multiply with the sample_rate Returns: The rounded sample Return type: sample
-
trim
(start_time, end_time)¶ Trim Audio object in time
Parameters: - start_time – time in seconds for start of extracted clip
- end_time – time in seconds for end of extracted clip
Returns: a new Audio object containing samples from start_time to end_time
-
exception
opensoundscape.audio.
OpsoLoadAudioInputError
¶ Custom exception indicating we can’t load input
-
exception
opensoundscape.audio.
OpsoLoadAudioInputTooLong
¶ Custom exception indicating length of audio is too long
-
opensoundscape.audio.
split_and_save
(audio, destination, prefix, clip_duration, clip_overlap=0, final_clip=None, dry_run=False)¶ Split audio into clips and save them to a folder
Parameters: - audio – The input Audio to split
- destination – A folder to write clips to
- prefix – A name to prepend to the written clips
- clip_duration – The duration of each clip in seconds
- clip_overlap – The overlap of each clip in seconds [default: 0]
- final_clip (str) –
Behavior if final_clip is less than clip_duration seconds long. [default: None] By default, ignores final clip entirely. Possible options (any other input will ignore the final clip entirely),
- ”remainder”: Include the remainder of the Audio (clip will not have clip_duration length)
- ”full”: Increase the overlap to yield a clip with clip_duration length
- ”extend”: Similar to remainder but extend (repeat) the clip to reach clip_duration length
- dry_run (bool) – If True, skip writing audio and just return clip DataFrame [default: False]
Returns: pandas.DataFrame containing begin and end times for each clip from the source audio
Audio Tools¶
audio_tools.py: set of tools that filter or modify audio files or sample arrays (not Audio objects)
-
opensoundscape.audio_tools.
bandpass_filter
(signal, low_f, high_f, sample_rate, order=9)¶ perform a butterworth bandpass filter on a discrete time signal using scipy.signal’s butter and solfiltfilt (phase-preserving version of sosfilt)
Parameters: - signal – discrete time signal (audio samples, list of float)
- low_f – -3db point (?) for highpass filter (Hz)
- high_f – -3db point (?) for highpass filter (Hz)
- sample_rate – samples per second (Hz)
- order=9 – higher values -> steeper dropoff
Returns: filtered time signal
-
opensoundscape.audio_tools.
butter_bandpass
(low_f, high_f, sample_rate, order=9)¶ generate coefficients for bandpass_filter()
Parameters: - low_f – low frequency of butterworth bandpass filter
- high_f – high frequency of butterworth bandpass filter
- sample_rate – audio sample rate
- order=9 – order of butterworth filter
Returns: set of coefficients used in sosfiltfilt()
-
opensoundscape.audio_tools.
clipping_detector
(samples, threshold=0.6)¶ count the number of samples above a threshold value
Parameters: - samples – a time series of float values
- threshold=0.6 – minimum value of sample to count as clipping
Returns: number of samples exceeding threshold
-
opensoundscape.audio_tools.
convolve_file
(in_file, out_file, ir_file, input_gain=1.0)¶ apply an impulse_response to a file using ffmpeg’s afir convolution
ir_file is an audio file containing a short burst of noise recorded in a space whose acoustics are to be recreated
this makes the files ‘sound as if’ it were recorded in the location that the impulse response (ir_file) was recorded
Parameters: - in_file – path to an audio file to process
- out_file – path to save output to
- ir_file – path to impulse response file
- input_gain=1.0 – ratio for in_file sound’s amplitude in (0,1)
Returns: os response of ffmpeg command
-
opensoundscape.audio_tools.
mixdown_with_delays
(files_to_mix, destination, delays=None, levels=None, duration='first', verbose=0, create_txt_file=False)¶ use ffmpeg to mixdown a set of audio files, each starting at a specified time (padding beginnings with zeros)
Parameters: - files_to_mix – list of audio file paths
- destination – path to save mixdown to
- delays=None – list of delays (how many seconds of zero-padding to add at beginning of each file)
- levels=None – optionally provide a list of relative levels (amplitudes) for each input
- duration='first' – ffmpeg option for duration of output file: match duration of ‘longest’,’shortest’,or ‘first’ input file
- verbose=0 – if >0, prints ffmpeg command and doesn’t suppress ffmpeg output (command line output is returned from this function)
- create_txt_file=False – if True, also creates a second output file which lists all files that were included in the mixdown
Returns: ffmpeg command line output
-
opensoundscape.audio_tools.
silence_filter
(filename, smoothing_factor=10, window_len_samples=256, overlap_len_samples=128, threshold=None)¶ Identify whether a file is silent (0) or not (1)
Load samples from an mp3 file and identify whether or not it is likely to be silent. Silence is determined by finding the energy in windowed regions of these samples, and normalizing the detected energy by the average energy level in the recording.
If any windowed region has energy above the threshold, returns a 0; else returns 1.
Parameters: - filename (str) – file to inspect
- smoothing_factor (int) – modifier to window_len_samples
- window_len_samples – number of samples per window segment
- overlap_len_samples – number of samples to overlap each window segment
- threshold – threshold value (experimentally determined)
Returns: 0 if file contains no significant energy over bakcground 1 if file contains significant energy over bakcground
If threshold is None: returns net_energy over background noise
-
opensoundscape.audio_tools.
window_energy
(samples, window_len_samples=256, overlap_len_samples=128)¶ Calculate audio energy with a sliding window
Calculate the energy in an array of audio samples
Parameters: - samples (np.ndarray) – array of audio samples loaded using librosa.load
- window_len_samples – samples per window
- overlap_len_samples – number of samples shared between consecutive windows
Returns: list of energy level (float) for each window