Other useful non-specific functionality

Utils module covers functions that are useful for soundpy but are not directly related to sound data.

soundpy.utils.path_or_samples(input_value)

Checks whether input_value is a path or sample data. Does not check path validity.

This is useful for functions that take both pathways to audio as well as pre-loaded audio data.

Parameters

input_value (str, pathlib.PosixPath, or tuple [size= ( (samples,), sr)] or np.ndarray [size = (samples, )]) –

Returns

‘path’ or ‘samples’

Return type

str

Examples

>>> import numpy as np
>>> # create some example samples and sample rate
>>> samples = np.array([1,2,3,2,1,0])
>>> sr = 5
>>> path_or_samples( (samples, sr) )
'samples'
>>> # expects both audio samples and sr
>>> path_or_samples(samples)
TypeError: The input for `path_or_samples` expected a str, pathlib.PosixPath, or tuple with samples and sample rate, not type <class 'numpy.ndarray'>
>>> # create example string pathway
>>> path_or_samples('my_audio.wav')
'path'
>>> # create pathlib.PosixPath object
>>> import pathlib
>>> path_or_samples(pathlib.Path('my_audio.wav')
'path'

soundpy.utils.get_default_args(func)

References

stackoverflow answer by mgilson: link: https://stackoverflow.com/a/12627202 license: https://creativecommons.org/licenses/by-sa/3.0/

soundpy.utils.match_dtype(array1, array2)

Match the dtype of the second array to the first.

Parameters

• array1 (np.ndarray) – The numpy array with the dataype to be adjusted and returned.

• array2 (np.ndarray) – The numpy array with the orginal or desired datatype.

Returns

array1 – The array1 with the dtype of array2

Return type

np.ndarray

soundpy.utils.get_date()

Get a string containing month, day, hour, minute, second and millisecond.

This is useful for creating a unique filename.

Parameters

None –

Returns

time_str – A string containing the date and time.

Return type

str

Examples

>>> date = get_date()
>>> date
'6m18d1h16m32s295ms'

soundpy.utils.check_dir(directory, make=True, append=True)

Checks if directory exists and creates it if indicated.

Parameters

• directory (str or pathlib.PosixPath) – The directory of interest

• make (bool) – Whether or not the directory should be created or just checked to ensure it exists. (default True)

• append (bool) – If True, if a directory with the same name exists, new items will be saved into the old directory. Otherwise, an error will be raised. (default True)

Returns

directory – If a directory could be created or confirmed to exist, the directory path will be returned. Otherwise Errors will be raised.

Return type

pathlib.PosixPath

soundpy.utils.create_nested_dirs(directory)

Creates directory even if several parent directories don’t exist.

Parameters

directory (str, pathlib.PosixPath) – The directory to be created.

Returns

directory – If successful, the directory path that has been created.

Return type

pathlib.PosixPath

Examples

>>> # First an unsucessful creation of nested directory
>>> import os
>>> new_dir = './testdir/testdir/testdir/'
>>> os.mkdir(new_dir)
FileNotFoundError: [Errno 2] No such file or directory: './testdir/testdir/testdir/'
>>> # try again with create_nested_dirs()
>>> directory = create_nested_dirs(new_dir)
>>> directory
PosixPath('testdir/testdir/testdir')

soundpy.utils.string2pathlib(pathway_string)

Turns string path into pathlib.PosixPath object.

This is useful when working with pathways from varying operating systems. Windows, Linux, and Mac have different ways of organizing pathways and pathlib turns strings from these different versions into a pathlib object that can be understood by the software regardless of the system. (At least I hope so..)

Parameters

pathway_string (str or pathlib.PosixPath) – The pathway to be turned into a pathlib object, if need be.

Returns

pathway_string – The pathway as a pathlib object.

Return type

pathlib.PosixPath

Examples

>>> pathway = 'folder/way2go.txt'
>>> pathlib_pathway = string2pathlib(pathway)
>>> pathlib_pathway
PosixPath('folder/way2go.txt')

soundpy.utils.restore_dictvalue(value_string)

Takes dict value and converts it to its original type.

When loading a dictionary from a .csv file, the values are strings. This function handles integers, floats, tuples, and some strings. It also has been suited to handle a list of audio files or list of pathlib.PosixPath objects.

Warning: no extensive testing has been completed for this function. It might not handle all value types as expected.

Parameters

value_string (str) – The dictionary value that was converted into a string object .

Returns

value_original_type – The value converted back to its original type.

Return type

list, int, tuple, string, float, etc.

:raises ValueError : If passed a nested list of pathlib.PosixPath objects.:

Examples

>>> input_string = "[PosixPath('data/audio/vacuum/vacuum1.wav')]"
>>> type(input_string)
<class 'str'>
>>> typelist = string2list(input_string)
>>> typelist
[PosixPath('data/audio/vacuum/vacuum1.wav')]
>>> type(typelist)
<class 'list'>
>>> # Get type of the object
>>> type(typelist[0])
pathlib.PosixPath
>>> # Example with a list of tuples, i.e. label and audio file pairs:
>>> input_string = "[(2, PosixPath('data/audio/vacuum/vacuum1.wav')), '+        '(1, PosixPath('data/audio/vacuum/vacuum2.wav'))]"
>>> labelaudio_pairs = string2list(input_string)
>>> labelaudio_pairs
[(2, PosixPath('data/audio/vacuum/vacuum1.wav')),
(1, PosixPath('data/audio/vacuum/vacuum2.wav'))]
>>> type(labelaudio_pairs)
list
>>> type(labelaudio_pairs[0])
tuple
>>> type(labelaudio_pairs[0][0])
int
>>> type(labelaudio_pairs[0][1])
pathlib.PosixPath

soundpy.utils.adjust_time_units(time_sec)

Turns seconds into relevant time units.

This is useful if measuring time of a process and that process takes longer than a couple minutes.

Parameters

time_sec (int, float) – The amount of time measured in seconds.

Returns

• total_time (int, float) – The total amount of time

• units (str) – The unites of total_time: ‘seconds’, ‘minutes’, or ‘hours’.

Examples

>>> adjust_time_units(5)
(5, 'seconds')
>>> adjust_time_units(500)
(8.333333333333334, 'minutes')
>>> adjust_time_units(5000)
(1.3888888888888888, 'hours')

soundpy.utils.print_progress(iteration, total_iterations, task=None)

Prints the status of a process based on iteration number.

Assumes the iteration starts at 0 rather than 1.

Parameters

• iteration (int) – The iteration of the current process.

• total_iterations (int) – The total iterations to be completed.

• task (str, optional) – The relevant task of the process.

Returns

Return type

sys.stdout.flush()

Examples

>>> print_progress(4, 10)
50% through current task
>>> print_progress(4, 10, task = 'testing')
50% through testing

soundpy.utils.check_extraction_variables(sr=None, feature_type=None, win_size_ms=None, percent_overlap=None)

Checks to ensure extraction variables are compatible.

Parameters

• sr (int) – The sample rate of audio.

• feature_type (str) – The type of feature to be extracted: ‘fbank’, ‘stft’, ‘powspec’, ‘mfcc’, ‘signal’.

• win_size_ms (int, float) – The window size to process audio samples.

• percent_overlap (int, float) – The percent windows should overlap.

Returns

Return type

None

Raises

ValueError – If any of the Parameters aren’t compatible.

Examples

>>> check_extraction_variables(sr=48000, feature_type='signal', win_size_ms=25,percent_overlap=0.5)
>>> check_extraction_variables(sr='48000', feature_type='sig',win_size_ms='25',percent_overlap='0.5')
ValueError: Sampling rate (sr) must be of type int, not 48000 of type <class 'str'>.

soundpy.utils.check_noisy_clean_match(noisyfilename, cleanfilename)

Checks if the clean filename is inside of the noisy filename.

This may be helpful to check that two audiofile datasets (a noisy and clean dataset) are aligned.

soundpy.utils.audiofile_length_match(filename1, filename2)

Checks that two audiofiles have the same length.

This may be useful if you have clean and noisy audiofiles that should be the same length.

Parameters

• filename1 (str or pathlib.PosixPath) – The path to first audio file.

• filename2 (str or pathlib.PosixPath) – The path to second audio file.

Returns

bool

Return type

True if they match, False if not.

Warning

UserWarning

If the sample rate of the audio files don’t match.

UserWarning

If the length of the files don’t match.

soundpy.utils.save_dict(filename, dict2save, overwrite=False)

Saves dictionary as csv file to indicated path and filename.

Ensures pathlib objects turned to strings. Warning: not thoroughly tested.

Parameters

• filename (str) – The path and name to save the dictionary under. If ‘.csv’ extension is not given, it is added.

• dict2save (dict) – The dictionary that is to be saved

• overwrite (bool, optional) – Whether or not the saved dictionary should overwrite a preexisting file (default False)

Returns

path – The path where the dictionary was saved

Return type

pathlib.PosixPath

soundpy.utils.load_dict(csv_path)

Loads a dictionary from csv file. Expands csv limit if too large.

Increasing the csv limit helps if loading dicitonaries with very long audio file path lists. For example, see soundpy.datasets.audio2datasets function.