API¶

Object for storing and accessing basic information for an audio file.

This object is a wrapper for the pysndfile audio object. It provides additional functionality alongside the ability to open and close audiofiles without deleting their containing object.

Arguments:

• filepath: path to the file to be opened/written to
• mode: mode to open file in. either ‘r’ (read) or ‘w’ (write)
• format: the file format to use when opening a new file for writing. see get_sndfile_formats() for more information.
• channels: the number of audio channels to use.
• samplerate: the samplerate in herts to use.
• name: the sound file object name.

check_mono()¶

Check that the audio file is a mono audio file

check_not_empty()¶

Check that the file contains audio

check_valid(force_mono=False)¶

Test to make sure that the audio file is valid for use. ie mono, not empty

close()¶

Use for closing the associated audio file outside of a with statement

construct_format(*args, **kwargs)¶

construct a format specification for libsndfile from major format string and encoding string

convert_to_mono(overwrite_original=False)¶

Converts stereo audiofiles to mono.

Arguments:

• overwrite_original: If True then the current object will be reloaded as the mono file. Otherwise, the new mono file will be returned as a new AudioFile object.

encoding_str(*args, **kwargs)¶

Return string representation of encoding (e.g. pcm16).

See get_sndfile_encodings() for a list of available encoding strings that are supported by a given sndfile format

error(*args, **kwargs)¶

Report error numbers related to the current sound file.

fade_audio(audio, position, fade_time, mode)¶

Fade the audio in or out linearly from the position specified over the time specified.

Arguments:

• audio: A numpy array of audio to manipulate
• start_position: The starting position to begin the fade from (ms)
• fade_time: The length of the fade (ms)
• mode: choose to fade the audio in or out (string: “in” or “out”)

static gen_default_wav(path, overwrite_existing=False, mode='w', channels=1)¶

Convenience method that creates a wav file with the following spec at the path given:

• Samplerate: 44.1Khz
• Bit rate: 24Bit

static gen_white_noise(length, gain)¶

Generate mono white noise of the number of samples specified.

Arguments:

• length (samples)
• gain (silence 0.0 - full volume 1.0)

static gen_window(window_type, window_size, sym=True)¶

Generates a window function of given size and type Returns a 1D numpy array

sym: Used in the triangle window generation. When True (default), generates a symmetric window, for use in filter design. When False, generates a periodic window, for use in spectral analysis

Available window types:

• hanning
• hamming
• bartlett
• blackman
• kaiser
• triangle

generate_grain_times(grain_length, overlap, save_times=False)¶

Generates an array of start and finish pairs based on overlapping frames at the grain length specified.

Note that only full grains within the size of the sample are returned. incomplete grains found at the end of files are ignored.

Arguments:

• grain_length: length of each grain in seconds.
• overlap: the factor by which grains overlap (integer)

get_channels(*args, **kwargs)¶

Return number of channels of sndfile.

get_format(*args, **kwargs)¶

Return raw format specification from sndfile.

get_frames(*args, **kwargs)¶

Return number of frames in file (number of samples per channel).

get_pysndfile_version(*args, **kwargs)¶

return tuple describing the version of pysndfile

get_samplerate(*args, **kwargs)¶

Return the samplerate of the file.

get_seek_position()¶

Returns the current seeker position in the file

get_sndfile_encodings(*args, **kwargs)¶

Return lists of available encoding for the given sndfile format.

Arguments:

• major: Major sndfile format for the list of available formats. format should be specified as a string, using one of the strings returned by get_sndfile_formats()

get_sndfile_formats(*args, **kwargs)¶

Return lists of available file formats supported by libsndfile and pysndfile.

get_sndfile_version(*args, **kwargs)¶

return a tuple of ints representing the version of the libsdnfile that is used

get_strings(*args, **kwargs)¶

get all stringtypes from the sound file.

see stringtype_name_top_id.keys() for the list of strings that are supported by the libsndfile version you use.

major_format_str(*args, **kwargs)¶

return short string representation of major format.

(e.g. aiff) see get_sndfile_formats() for a complete list of file formats

static mono_arrays_to_stereo(array1, array2)¶

Converts two horizontal numpy arrays to one concatenated verticaly stacked array that can be written to a stereo file.

ms_to_samps(ms)¶

Converts milliseconds to samples based on the sample rate of the audio file

static normalize_audio(audio, maximum=1.0)¶

Normalize array of audio so that the maximum sample value is equal to the maximum provided

normalize_file(overwrite_original=False)¶

Normalizes the entire file

open()¶

Use for opening the associated audio file outside of a with statement

read_frames(*args, **kwargs)¶

Read the given number of frames and fill numpy array.

Arguments

• nframes: <int>
• number of frames to read (default = -1 -> read all).
• dtype: <numpy dtype>
• dtype of the returned array containing read data (see note).

Notes: One column per channel.

read_grain(*args, **kwargs)¶

Read a grain of audio from the file. if grain ends after the end of the file, the grain can be padded with zeros using the padding argument.

Audio object seeker is not changed

Arguments:

• start_index: the index in samples to read from.
• grain_size: The size of the grain (in samples) to read
• padding: if the end of the audio file is reaches, the grain will be padded with additional zeros.

rename_file(*args, **kwargs)¶

Renames the audio file associated with the object to the name specified as an argument

Arguments:

• filename: the new path of the audio file.

replace_audiofile(replacement_filename)¶

Replace the current audiofile and audiofile object with the file specified.

rewind(*args, **kwargs)¶

Rewind read/write/read and write position given by mode to start of file.

samps_to_ms(samps)¶

Convert samples to milliseconds based on the sample rate of the audio file

samps_to_secs(samps)¶

Converts samples to seconds based on the sample rate of the audio file

secs_to_samps(seconds)¶

Converts seconds to samples based on the sample rate of the audio file

seek(*args, **kwargs)¶

Seek into audio file: similar to python seek function, but taking only audio data into account.

Arguments

• offset: <int> the number of frames (eg two samples for stereo files) to move relatively to position set by whence.
• whence: <int> only 0 (beginning), 1 (current) and 2 (end of the file) are valid.
• mode: <string> If set to ‘rw’, both read and write pointers are updated. If ‘r’ is given, only read pointer is updated, if ‘w’, only the write one is (this may of course make sense only if you open the file in a certain mode).

Returns offset: int the number of frames from the beginning of the file

Notes: Offset relative to audio data: meta-data are ignored. if an invalid seek is given (beyond or before the file), an IOError is raised; note that this is different from the seek method of a File object.

seekable(*args, **kwargs)¶

Return true for soundfiles that support seeking.

set_auto_clipping(*args, **kwargs)¶

Enable auto clipping when reading/writing samples from/to sndfile.

auto clipping is enabled by default. auto clipping is required by libsndfile to properly handle scaling between sndfiles with pcm encoding and float representation of the samples in numpy. When auto clipping is set to on reading pcm data into a float vector and writing it back with libsndfile will reproduce the original samples. If auto clipping is off, samples will be changed slightly as soon as the amplitude is close to the sample range because libsndfile applies slightly different scaling factors during read and write.

set_string(*args, **kwargs)¶

Set one of the stringtypes to the string given as argument.

If you try to write a stringtype that is not supported by the library a RuntimeError will be raised

strError(*args, **kwargs)¶

Report error strings related to the current sound file.

switch_mode(mode)¶

Switch audiofile to mode specified.

This allows for convenient reading and writing of audiofiles without direct closing and opening of the underlying pysndfile object.

writeSync(*args, **kwargs)¶

Call the operating system’s function to force the writing of all file cache buffers to disk. No effect if file is open as read

write_frames(*args, **kwargs)¶

write 1 or 2 dimensional array into sndfile.

Arguments:

• input: <numpy array>

containing data to write.

Notes:

One column per channel.

updates the write pointer.

if the input type is float, and the file encoding is an integer type, you should make sure the input data are normalized normalized data (that is in the range [-1..1] - which will corresponds to the maximum range allowed by the integer bitwidth).

Generates and stores analysis information for an audio file.

Arguments:

• (All AudioFile arguments)
• db_dir: if the object is part of a database, this is the path to the root of the database.
• config: The config module used for configuration settings. See examples for further details.
• data_file: the path to the HDF5 file used to store analyses for this audio file.
• reanalyse: bool for whether to overwrite any previously created analyses for this audio file.
• available_analyses: a list of strings for each analyses to be generated. ie. [‘f0’, ‘rms’]

analysis_data_grains(times, analysis, *args, **kwargs)¶

retrieve data for analysis within start and end time pairs in the format specified.

Arguments:

• times: an array of start and end times to retrieve analysis from (np.array)
• analysis: analysis string specifying analysis to retrieve

create_analysis()¶

Generate all analyses that have been set in the self.available_analyses member.

create_analysis_group(analysis_file)¶

Create HDF5 group for object to store analyses for this audio file.

Audio file analyses are organized in groups per audio file. This function creates a group in the analysis HDF5 file with the name of the audio file. Analyses of this file are stored in analysis sub-groups.

A class for encapsulating a database of AnalysedAudioFile objects.

Arguments:

• audio_dir: directory containing audio files to be used as the database
• db_dir: directory to be used/created for storage of analysis data and storage/linking of audio files.
• analysis_list: the list of analysis strings for analyses to be used in the database.

add_file(file_object)¶

Add an AnalysedAudioFile object to the database

analyse_database(subdir_paths, reanalyse)¶

create selected analyses for audio files in the database.

Parameters:

• subdir_paths: a dictionary containing paths to the ‘audio’ directory and ‘data’ directory of the database.
• reanalyse: If previous analyses are found this can be set to True to overwrite them.

create_subdirs()¶

Generate database folder structure at the self.db_dir location

If the folder structure already exists this will be used, else a new structure will be generated.

load_database(reanalyse=False)¶

Create/Read from a pre-existing database

organize_audio(subdir_paths, symlink=True)¶

Moves/symlinks any audio from the audio directory specified to the database.

Parameters:

• subdir_paths: A dictionary of ‘audio’ and ‘data’ sub directories of the database.
• symlink: If true, symbolic links will be used for audio files rather than copying. This allows audio files to stay in there original locations.

Database comparison object.

Used to compare and match entries in two AnalysedAudioFile databases.

brute_force_matcher(grain_size, overlap)¶

Searches for matches to each grain by brute force comparison

calculate_db_inds(match_indexes, source_sample_indexes)¶

Generate the database sample index and grain index for each match based on their indexes generated from the concatenated matching

Output array will be a 3 dimensional array with an axis for each target grain, a dimension for each match of said grain and a dimension containing database sample index and the sample’s grain index.

count_grains(database, grain_length, overlap)¶

Calculate the number of grains in the database

distance_calc(data1, data2)¶

Calculates the euclidean distance between two arrays of data.

Distance is calculated with special handeling of Nan values, if they exist in the data. A Nan value matched to another Nan value is classed as a perfect match. a Nan matched to any other value is calculated as the furthest match + 10%

match(match_function, grain_size=None, overlap=None)¶

Find the closest match to each object in database 1 in database 2 using the matching function specified.

swap_databases()¶

Convenience method to swap databases, changing the source database into the target and vice-versa

An object used for synthesizing output based on grain matching.

enforce_intensity(grain, source_sample, source_grain_ind, target_sample, target_grain_ind)¶

Scales the amplitude of the grain by the difference between it’s intensity and the intensity of the grain specified.

This method will fail if either AnalysedAudioFile object does not have any intensity analyses.

enforce_pitch(grain, source_sample, source_grain_ind, target_sample, target_grain_ind)¶

Shifts the pitch of the grain by the difference between it’s f0 and the f0 of the grain specified.

This method will fail if either AnalysedAudioFile object does not have an f0 analysis.

swap_databases()¶

Convenience method to swap databases, changing the source database into the target and vice-versa

synthesize(grain_size=None, overlap=None)¶

Synthesized output from the match data in the output database to create audio in the output database.

Basic descriptor class to build analyses on.

The Analysis base class works as an interface between child descriptor objects and the HDF5 storage file. This is designed to seperate descriptor generation from data IO, allowing for quick development of new descriptor classes. The base Analysis class has methods for retreiving analyses from file and saving data created by analysis objects to file. It also has basic formatting methods used to return data in the required format for processed such as descriptor comparisons.

In order to create a new descriptor, the hdf5_dataset_formatter method will need to be overwritten by the child class to generate and store the descriptor’s output in the appropriate manner. Examples of this can be seen through the currently implemented descriptors.

analysis_formatter(frames, selection, format)¶

Calculate the average analysis value of the grain using the match format specified.

create_analysis(*args, **kwargs)¶

Create the analysis and save to the HDF5 file.

analysis_function: The function used to create the analysis. returned data will be stored in the HDF5 file.

get_analysis_grains(start, end)¶

Retrieve analysis frames for period specified in start and end times. arrays of start and end time pairs will produce an array of equivelant size containing frames for these times.

hdf5_dataset_formatter(analysis_method, *args, **kwargs)¶

Note: This is a generic formatter designed as a template to be overwritten by a descriptor sub-class.

Formats the output from the analysis method to save to the HDF5 file.

Places data and attributes in 2 dictionaries to be stored in the HDF5 file.