Granular Audio Musaicing Toolkit for Python
Project description
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 adict
object (i.e. the corpus). The output can be saved as a.gamut
file with thedict_to_gamut()
function, for later use inget_audio_recipe()
.- Arguments:
input_dir
(str
orlist
): 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 ininput_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.
- Arguments:
-
get_audio_recipe()
: Takes an audio sample directory/path (i.e. the target) and adict
object (i.e. the corpus), and returns anotherdict
object containing the instructions to rebuild the target using grains from the corpus. The output can be saved as a.gamut
file with thedict_to_gamut()
function, for later use incook_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.
- Arguments:
-
cook_recipe()
: Takes adict
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
orlist
): fixed value or envelope break points for grain duration, in seconds. (Default: 0.1)stretch_factor
(int
,float
orlist
): fixed value or envelope break points for strech factor, in seconds. (Default: 1)onset_var
(int
,float
orlist
): fixed value or envelope break points for grain onset variation, in seconds. (Default: 0)target_mix
(int
,float
orlist
)*: 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
orlist
): 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
orlist
): 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.
- Arguments:
Additionally, the following functions are included to read and write audio and .gamut
[1] files:
dict_to_gamut()
: writesdict
object into a.gamut
file. This function is a simple wrapper ofnp.save()
.- Arguments:
dict
(dict
): dictionary containing corpus or recipe data.output_dir
(str
): output directory for.gamut
file.
- Returns (
void
)
- Arguments:
dict_from_gamut()
: reads a.gamut
file as adict
object. This function is a simple wrapper ofnp.load()
.- Arguments:
output_dir
(str
): input directory for.gamut
file.
- Returns (
dict
): dictionary containing corpus or recipe data.
- Arguments:
write_audio()
: writes andarray
as audio. This function is a simple wrapper ofsf.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)
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.