gamut 0.1.2

Granular Audio Musaicing Toolkit for Python

GAMuT: Granular Audio Musaicing Toolkit

---

Description

GAMuT is a high-level, user-friendly granular audio musaicing toolkit implemented in Python.

---

Installation

To install gamut, run the pip install gamut command in the terminal.

---

Main functions

• build_corpus(): Takes a folder directory, or an audio file directory, or a list of directories to audio files, and returns a dict object (i.e. the corpus). The output can be saved as a .gamut file with the dict_to_gamut() function, for later use in get_audio_recipe().

  • Arguments:
    • input_dir (str or list): Input audio file/folder directory, or list of audio file directories, from which to build a corpus.
    • max_duration (int): maximum duration to analyze for all samples in input_dir. (Default: None)
    • n_mfcc (int): number of MFCC bands. (Default: 13)
    • hop_length (int): gap between subsequent frames, in samples. (Default: 512)
    • frame_length (int): size of analysis window, in samples. (Default: 1024)
    • kd (int): maximum number of bands to use for data query tree. (Default: None)
  • Returns (dict): corpus dictionary object.

• get_audio_recipe(): Takes an audio sample directory/path (i.e. the target) and a dict object (i.e. the corpus), and returns another dict object containing the instructions to rebuild the target using grains from the corpus. The output can be saved as a .gamut file with the dict_to_gamut() function, for later use in cook_recipe().

  • Arguments:
    • target_path (str): directory of target sound file.
    • corpus_dict (dict): dictionary object containing corpus.
    • max_duration (int): maximum duration to analyze for target sound file. (Default: None)
    • hop_length (int): gap between subsequent frames, in samples. (Default: 512)
    • frame_length(int): size of analysis window, in samples. (Default: 1024)
    • kn: number of best matches (KNN) to include in recipe. (Default: 8)
  • Returns (dict): target recipe dictionary object.

• cook_recipe(): Takes a dict object (i.e. the recipe), and returns an array of audio samples, intended to be written as an audio file.

  • Arguments:
    • recipe_dict (dict): directory object containing audio recipe.
    • grain_dur (int, float or list): fixed value or envelope break points for grain duration, in seconds. (Default: 0.1)
    • stretch_factor (int, float or list): fixed value or envelope break points for strech factor (i.e. speed). (Default: 1)
    • onset_var (int, float or list): fixed value or envelope break points for grain onset variation, in seconds. (Default: 0)
    • target_mix (int, float or list)*: fixed value or envelope break points for wet/dry mix, in the range of 0.0 to 1.0. (Default: 0)
    • pan_width (int, float or list): fixed value or envelope break points for panning width, in the range of 0.0 to 1.0. (Default: 0.5)
    • kn (int): maximum number of best matches to choose from for each grain. (Default: 8)
    • n_chans (int): number of output channels. (Default: 2)
    • envelope (str or list): list of envelope break points, or string specifying window types. (Default: 'hann')
    • sr (int): sampling rate of output. (Default: None) - frame_length_res (int): window size quantization unit. Larger windows increase efficiency at the expense of resolution in grain duration. (Default: 512)
  • Returns (ndarray): numpy array of audio samples.

Additionally, the following functions are included to read and write audio and .gamut[1] files:

• dict_to_gamut(): writes dict object into a .gamut file. This function is a simple wrapper of np.save().
  • Arguments:
    • dict (dict): dictionary containing corpus or recipe data.
    • output_dir (str): output directory for .gamut file.
  • Returns (void)
• dict_from_gamut(): reads a .gamut file as a dict object. This function is a simple wrapper of np.load().
  • Arguments:
    • output_dir (str): input directory for .gamut file.
  • Returns (dict): dictionary containing corpus or recipe data.
• write_audio(): writes a ndarray as audio. This function is a simple wrapper of sf.write().

[1]: .gamut is a custom binary data format used for storing GAMuT corpora and recipe data. This file is simply a renaming of Numpy's .npy file extension.

---

Examples

• Basic: generates corpus, recipe, and audio in a single script — not recommended.

# imports
from gamut import gamut

# set target sound
target = './soundfile.wav'

# set corpus folder containing audio samples
audio_files = './audio_folder'

 # build corpus
corpus = gamut.build_corpus(audio_files)

 # make target recipe
recipe = gamut.get_audio_recipe(target, corpus)

# cook target recipe
output = gamut.cook_recipe(recipe)

# write output into audio file
gamut.write_audio('./output.wav',output)

• Build corpus: Builds and writes .gamut corpus into file for future reuse.

# imports
from gamut import gamut

# set path to audio folder
audio_folder = '/Users/felipe-tovar-henao/Documents/Sample collections/Violin_notes'

# build corpus from folder
my_corpus = gamut.build_corpus(folder_dir=audio_folder)

# set corpus output path
outfile_path = '/Users/felipe-tovar-henao/Desktop/Violin_notes_corpus'

# write corpus into disk
gamut.dict_to_gamut(dict=my_corpus, outpath=outfile_path)

• Make recipe: Makes and writes .gamut recipe into file for future reuse.

# imports
from gamut import gamut

# path of audio target
target_path = '/Users/felipe-tovar-henao/Documents/target_samples/dialogo_44.1Hz.wav'

# gamut corpus path
corpus_path = '/Users/felipe-tovar-henao/Desktop/Violin_notes_corpus'

# load corpus
corpus = gamut.dict_from_gamut(corpus_path)

# build audio recipe
target_recipe = gamut.get_audio_recipe(target_path=target_path, corpus_dict=corpus)

# set recipe output path
outfile_path = '/Users/felipe-tovar-henao/Desktop/MyRecipe.gamut'

# write recipe into disk
gamut.dict_to_gamut(dict=target_recipe, outpath=outfile_path)

• Cook recipe: Generates and writes audio file (.wav, .aif. or .aif) gamut from recipe.

# imports
from gamut import gamut

# audio recipe path
recipe_path = '/Users/felipe-tovar-henao/Desktop/MyRecipe.gamut'

# load corpus
recipe = gamut.dict_from_gamut(recipe_path)

# cooking settings
envelope = [0, 1, 0.5, 0.1, 0] # grain amplitude envelope (type: str, int, float or list -- if str, use scipy.signal.windows types)
grain_dur = [0.05, 0.25] # grain duration (type: int, float, or list)
sr = 44100 # output sampling rate (type: int)
pan_width = [0.1, 0.9] # spread of panning across channels (0.0-1.0) (type: int, float or list)
target_mix = [0, 0.5] # dry/wet mix of input target (0.0-1.0) (type: int, float, or list)

# cook audio recipe
audio_array = gamut.cook_recipe(recipe_dict=recipe,
                        grain_dur=grain_dur,
                        target_mix=target_mix,
                        pan_width=pan_width,
                        envelope=envelope,
                        sr=sr)

# set audio output path
outfile_path = '/Users/felipe-tovar-henao/Desktop/MyAudioMosaicing.wav'

# write audio into disk
gamut.write_audio(path=outfile_path,
            ndarray=audio_array,
            sr=sr,
            bit_depth=24)