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. Some audio examples of audio musaicing made with GAMuT can be found here.
Installation
To install gamut
, simply run the pip install gamut
command in the terminal.
Documentation
Broadly speaking, the audio musaicing pipeline with GAMuT is the following:
- build a corpus from one or more sound files.
- get an audio musaicing recipe from the corpus, given a target sound file.
- cook the audio musaicing recipe and write it into sound file.
To do this, a small collection of functions are included:
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()
.- Required arguments:
input_dir
(str
orlist
): Input audio file/folder directory, or list of audio file directories, from which to build a corpus.
- Optional arguments:
max_duration
(int
): maximum duration to analyze for all sound files ininput_dir
. If set toNone
, all sound files are analyzed in full. (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 MFCC bands to use for data query tree. If set toNone
, a number is internally chosen based on the number of data samples.(Default: None)
- Returns (
dict
): corpus dictionary object.
- Required 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()
.- Required arguments:
target_path
(str
): directory of target sound file.corpus_dict
(dict
): dictionary object containing corpus.
- Optional arguments:
max_duration
(int
): maximum duration to analyze for target sound file. If set toNone
, the sound file is analyzed in full.(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.
- Required 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.- Required arguments:
recipe_dict
(dict
): directory object containing audio recipe.
- Optional arguments:
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 (i.e. speed). (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_depth
(int
,float
orlist
): fixed value or envelope break points for panning depth (>= 0). (Default: 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. If set toNone
, the target's sampling rate is used. (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.
- Required 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 ofnumpy.save()
.- Required arguments:
dict
(dict
): dictionary containing corpus or recipe data.output_dir
(str
): output directory for.gamut
file.
- Returns (
NoneType
): None
- Required arguments:
dict_from_gamut()
: reads a.gamut
file as adict
object. This function is a simple wrapper ofnumpy.load()
.- Required arguments:
output_dir
(str
): input directory for.gamut
file.
- Returns (
dict
): dictionary containing corpus or recipe data.
- Required arguments:
write_audio()
: writes anndarray
as audio. This function is a simple wrapper ofsoundfile.write()
.- Required arguments:
output_dir
(str
): output directory of audio file. Output file format must be.wav
,.aif
, or.aiff
.ndarray
(ndarray
): numpy array containing audio samples.
- Optional arguments:
sr
(int
): audio sampling rate of output file. (Default: 44100)bit_depth
(int
): audio bit rate of output file. (Default: 24)
- Returns (
NoneType
): None
- Required arguments:
play_audio()
: plays back anndarray
as audio. This function is a simple wrapper ofsounddevice.write()
.- Required arguments:
ndarray
(ndarray
): numpy array containing audio samples.
- Optional arguments:
sr
(int
): audio sampling rate. (Default: 44100)
- Returns (
NoneType
): None
- Required arguments:
[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 — very slow, not recommended.
# imports
from gamut import gamut
# set target sound
target = './my_soundfile.wav'
# set corpus folder containing audio samples
audio_files = './my_audio_folder/'
# build corpus
corpus = gamut.build_corpus(audio_files)
# make target recipe
recipe = gamut.get_audio_recipe(target, corpus)
# cook target recipe
audio_array = gamut.cook_recipe(recipe)
# write output into audio file
gamut.write_audio('./output.wav', audio_array)
# plays back audio file
gamut.play_audio(audio_array)
- Build corpus: Builds and writes
.gamut
corpus into file for future reuse.
# imports
from gamut import gamut
# set path to audio folder
audio_files = './my_audio_folder/'
# build corpus from folder
my_corpus = gamut.build_corpus(folder_dir=audio_files)
# set corpus output path
outfile_path = './my_corpus.gamut'
# 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 = './my_target_sound.wav'
# gamut corpus path
corpus_path = './my_corpus.gamut'
# 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 = './my_recipe.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
) from.gamut
recipe.
# imports
from gamut import gamut
# audio recipe path
recipe_path = './my_recipe.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_depth = [1, 40] # depth of panning across channels (>= 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_depth=pan_depth,
envelope=envelope,
sr=sr)
# set audio output path
outfile_path = './output.wav'
# write audio into disk
gamut.write_audio(path=outfile_path,
ndarray=audio_array,
sr=sr,
bit_depth=24)
# plays back audio file
gamut.play_audio(audio_array)
License
ISC License Copyright (c) 2022, Felipe Tovar-Henao
Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.
THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
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.