audiomate.utils¶
Audio¶
-
audiomate.utils.audio.
process_buffer
(buffer, n_channels)[source]¶ Merge the read blocks and resample if necessary.
Parameters: - buffer (list) – A list of blocks of samples.
- n_channels (int) – The number of channels of the input data.
Returns: The samples
Return type: np.array
-
audiomate.utils.audio.
read_blocks
(file_path, start=0.0, end=inf, buffer_size=5760000)[source]¶ Read an audio file block after block. The blocks are yielded one by one.
Parameters: - file_path (str) – Path to the file to read.
- start (float) – Start in seconds to read from.
- end (float) – End in seconds to read to.
inf
means to the end of the file. - buffer_size (int) – Number of samples to load into memory at once and return as a single block. The exact number of loaded samples depends on the block-size of the audioread library. So it can be of x higher, where the x is typically 1024 or 4096.
Returns: A generator yielding the samples for every block.
Return type: Generator
-
audiomate.utils.audio.
read_frames
(file_path, frame_size, hop_size, start=0.0, end=inf, buffer_size=5760000)[source]¶ Read an audio file frame by frame. The frames are yielded one after another.
Parameters: - file_path (str) – Path to the file to read.
- frame_size (int) – The number of samples per frame.
- hop_size (int) – The number of samples between two frames.
- start (float) – Start in seconds to read from.
- end (float) – End in seconds to read to.
inf
means to the end of the file. - buffer_size (int) – Number of samples to load into memory at once and return as a single block. The exact number of loaded samples depends on the block-size of the audioread library. So it can be of x higher, where the x is typically 1024 or 4096.
Returns: A generator yielding a tuple for every frame. The first item is the frame and the second a boolean indicating if it is the last frame.
Return type: Generator
-
audiomate.utils.audio.
write_wav
(path, samples, sr=16000)[source]¶ Write to given samples to a wav file. The samples are expected to be floating point numbers in the range of -1.0 to 1.0.
Parameters: - path (str) – The path to write the wav to.
- samples (np.array) – A float array .
- sr (int) – The sampling rate.
Audioread¶
Wrapping opening function of audioread library. This is used to cache the available backends. If backend evaluation is done on every call it is very inefficient.
JSON File¶
This module contains functions for reading and writing json files.
Naming¶
This module contains functions for working with names. For example to generate identifiers or find an identifier which not already exists in a given list.
-
audiomate.utils.naming.
generate_name
(length=15, not_in=None)[source]¶ Generates a random string of lowercase letters with the given length.
Parameters: - length (int) – Length of the string to output.
- not_in (list) – Only return a string not in the given iterator.
Returns: A new name thats not in the given list.
Return type: str
-
audiomate.utils.naming.
index_name_if_in_list
(name, name_list, suffix='', prefix='')[source]¶ Find a unique name by adding an index to the name so it is unique within the given list.
Parameters: - name (str) – Name
- name_list (iterable) – List of names that the new name must differ from.
- suffix (str) – The suffix to append after the index.
- prefix (str) – The prefix to append in front of the index.
Returns: A unique name within the given list.
Return type: str
Text¶
This module contains any functions for working with text/strings/punctuation.
-
audiomate.utils.text.
remove_punctuation
(text, exceptions=None)[source]¶ Return a string with punctuation removed.
Parameters: - text (str) – The text to remove punctuation from.
- exceptions (list) – List of symbols to keep in the given text.
Returns: The input text without the punctuation.
Return type: str
-
audiomate.utils.text.
starts_with_prefix_in_list
(text, prefixes)[source]¶ Return True if the given string starts with one of the prefixes in the given list, otherwise return False.
Parameters: - text (str) – Text to check for prefixes.
- prefixes (list) – List of prefixes to check for.
Returns: - True if the given text starts with any of the given prefixes,
False otherwise.
Return type: bool
Text File¶
The textfile module contains functions for reading and writing textfiles.
-
audiomate.utils.textfile.
read_key_value_lines
(path, separator=' ', default_value='')[source]¶ Reads lines of a text file with two columns as key/value dictionary.
Parameters: - path (str) – Path to the file.
- separator (str) – Separator that is used to split key and value.
- default_value (str) – If no value is given this value is used.
Returns: A dictionary with first column as key and second as value.
Return type: dict
-
audiomate.utils.textfile.
read_separated_lines
(path, separator=' ', max_columns=-1, keep_empty=False)[source]¶ Reads a text file where each line represents a record with some separated columns.
Parameters: - path (str) – Path to the file to read.
- separator (str) – Separator that is used to split the columns.
- max_columns (int) – Number of max columns (if the separator occurs within the last column).
- keep_empty (bool) – If True empty columns are returned as well.
Returns: A list containing a list for each line read.
Return type: list
-
audiomate.utils.textfile.
read_separated_lines_generator
(path, separator=' ', max_columns=-1, ignore_lines_starting_with=None, keep_empty=False)[source]¶ Creates a generator through all lines of a file and returns the splitted line.
Parameters: - path (str) – Path to the file.
- separator (str) – Separator that is used to split the columns.
- max_columns (int) – Number of max columns (if the separator occurs within the last column).
- ignore_lines_starting_with (list) – Lines starting with a string in this list will be ignored.
- keep_empty (bool) – If True empty columns are returned as well.
-
audiomate.utils.textfile.
read_separated_lines_with_first_key
(path: str, separator: str = ' ', max_columns: int = -1, keep_empty: bool = False)[source]¶ Reads the separated lines of a file and return a dictionary with the first column as keys, value is a list with the rest of the columns.
Parameters: - path (str) – Path to the file to read.
- separator (str) – Separator that is used to split the columns.
- max_columns (str) – Number of max columns (if the separator occurs within the last column).
- keep_empty (bool) – If True empty columns are returned as well.
Returns: Dictionary with list of column values and first column value as key.
Return type: dict
-
audiomate.utils.textfile.
write_separated_lines
(path, values, separator=' ', sort_by_column=0)[source]¶ Writes list or dict to file line by line. Dict can have list as value then they written separated on the line.
Parameters: - path (str) – Path to write file to.
- values (dict, list) – A dictionary or a list to write to the file.
- separator (str) – Separator to use between columns.
- sort_by_column (int) – if >= 0, sorts the list by the given index, if its 0 or 1 and its a dictionary it sorts it by either the key (0) or value (1). By default 0, meaning sorted by the first column or the key.
Units¶
This module contains functions for handling different units. Especially it provides function to convert from one to another unit (e.g. seconds -> sample-indexn).
-
class
audiomate.utils.units.
FrameSettings
(frame_size, hop_size)[source]¶ This class provides functions for handling conversions/calculations between time, samples and frames.
- By default the framing is done as follows:
- The first frame starts at sample 0
- The end of the last frame is higher than the last sample.
- The end of the last frame is smaller than the last sample + hop_size
Parameters: - frame_size (int) – Number of samples used per frame.
- hop_size (int) – Number of samples between two frames.
-
frame_to_sample
(frame_index)[source]¶ Return a tuple containing the indices of the sample which are the first sample and the end (exclusive) of the frame with the given index.
-
frame_to_seconds
(frame_index, sr)[source]¶ Return a tuple containing the start and end of the frame in seconds.
-
num_frames
(num_samples)[source]¶ Return the number of frames that will be used for a signal with the length of
num_samples
.
-
sample_to_frame_range
(sample_index)[source]¶ Return a tuple containing the indices of the first frame containing the sample with the given index and the last frame (exclusive, doesn’t contain the sample anymore).
-
time_range_to_frame_range
(start, end, sr)[source]¶ Calculate the frames containing samples from the given time range in seconds.
Parameters: - start (float) – Start time in seconds.
- end (float) – End time in seconds.
- sr (int) – The sampling rate to use for time-to-sample conversion.
Returns: A tuple containing the start and end (exclusive) frame indices.
Return type: tuple
-
audiomate.utils.units.
parse_storage_size
(storage_size)[source]¶ Parses an expression that represents an amount of storage/memory and returns the number of bytes it represents.
Parameters: storage_size (str) – Size in bytes. The units k
(kibibytes),m
(mebibytes) andg
(gibibytes) are supported, i.e. apartition_size
of1g
equates \(2^{30}\) bytes.Returns: Number of bytes. Return type: int
-
audiomate.utils.units.
sample_to_seconds
(sample, sampling_rate=16000)[source]¶ Convert a sample index to seconds based on the given sampling rate.
Parameters: - sample (int) – The index of the sample (0 based).
- sampling_rate (int) – The sampling rate to use for conversion.
Returns: The time in seconds.
Return type: float
- Example::
>>> sample_to_seconds(20800, sampling_rate=16000) 1.3
-
audiomate.utils.units.
seconds_to_sample
(seconds, sampling_rate=16000)[source]¶ Convert a value in seconds to a sample index based on the given sampling rate.
Parameters: - seconds (float) – The value in seconds.
- sampling_rate (int) – The sampling rate to use for conversion.
Returns: The sample index (0-based).
Return type: int
- Example::
>>> seconds_to_sample(1.3, sampling_rate=16000) 20800
Misc¶
-
audiomate.utils.misc.
length_of_overlap
(first_start, first_end, second_start, second_end)[source]¶ Find the length of the overlapping part of two segments.
Parameters: - first_start (float) – Start of the first segment.
- first_end (float) – End of the first segment.
- second_start (float) – Start of the second segment.
- second_end (float) – End of the second segment.
Returns: The amount of overlap or 0 if they don’t overlap at all.
Return type: float