EarSketch - API

Print Return to index

Table of Contents

 

finish()

Call this function at the end of your EarSketch script. THIS FUNCTION IS REQUIRED.

fitMedia(fileName, trackNumber, startLocation, endLocation)

Adds an audio file to a specified track number.All location parameters can be specified as a floating point number or Tuple.

This function inserts the audio file as many times possible between the specified measure numbers.

If the file is too long to fit in the range it truncates the sound file.

fileNameaudio file to insert
trackNumbertrack number to insert audio file onto
startLocationa floating point or tuple value for the measure, beat, subdivision for where the initial soundfile will be placed
endLocationa floating point or tuple value for the measure, beat, subdivision for the end of the soundfile(s) to be placed
init()

Opens and initializes a new Reaper project. This should be the first function called in all Earsketch scripts. THIS FUNCTION IS REQUIRED.

insertMedia(fileName, trackNumber, trackLocation=None, scaleAudio=True)

Inserts the entire sound file onto a specified track number.

All location arguments can be specified as a floating point number or Tuple.

For example, to specify "Measure 1, Beat 3"

floating point:	trackLocation = 1.5   
tuple:		trackLocation = (1, 3, 1)

The floating point value specifies measure 1, beat 3
The tuple value specifies measure 1, beat 3, sub-division 1
	

Tuple with measure and beat will also work. For example:

trackLocation = (1, 4)
fileNamesound file to insert
trackNumbertrack number to insert sound file onto
trackLocationfloating point number or tuple representing the measure, beat, subdivision
scaleAudioif True, the sound file will be stretched or compressed to match the project's tempo. If False, the sound file will play back at its original speed.

If trackLocation is not supplied, the audio file will be placed at the end of the track.

If scaleAudio is not supplied, the audio will be scaled to match project tempo.

insertMediaSection(fileName, trackNumber, trackLocation, mediaStartLocation=None, mediaEndLocation=None, scaleAudio=True)

Inserts audio file on a specified track number.

All location arguments can be specified as a floating point number or Tuple.

For example:

floating point:	trackLocation = 1.5   
tuple:		trackLocation = (1, 3, 1)

The floating point value specifies measure 1, beat 3
The tuple value specifies measure 1, beat 3, sub-division 1
	

Similarly, a tuple with just measure and beat will also work.

For example:

trackLocation = (1, 4)     -> specifies measure 1, beat 4

The parameters are detailed below.

fileNameaudio file to insert on track
trackNumberwhich track number to insert audio file onto
trackLocationthe location to place the media section (floating point number or tuple)
startLocationspecifies a start location, of the original file, to insert a section of an audio file
endLocationspecifies an end location, of the original file, to insert a section of an audio file
scaleAudioif True, the sound file will be stretched or compressed to match the project's tempo. If False, the sound file will play back at its original speed.

If audioStartLocation is not specified, insertMediaSection() will start from the beginning of the audio file.

If audioEndLocation is not specific, it will finish at the end of the audio file.

If scaleAudio is not specified, the audio file will be scaled to match the project tempo.

makeBeat(fileName, trackNumber, trackLocation, beatString)

The makeBeat() function takes a string and converts it into a beat.

For example, the string "0-00-00-0+++0+0+"" evaluates to:

0 play the clip for one sixteenth of a measure
- rest for one sixteenth
0 play for one sixteenth
0 play for one sixteenth again
- rest for one sixteenth
0 play for one sixteenth
0 play for one sixteenth again
- rest for one sixteenth
0+++ play the clip for four sixteenths (or one quarter)
0+ play for two sixteenths (or one eighth)
0+ play for one eighth again

Additionally, makeBeat() can take a list of audio file constants as the fileName parameter. This means that a single beat string can refer to multiple samples, looking like this:

beat = "001+++1+++221+1+"
  • Numbers indicate position of audio file in a list (0 - based)
  • + indicates continue or stretch the media
  • - indicates 16th rest
  • The media argument can be a list of files or an individual media file.
  • If using only an single media file, all the numbers must be "0"
play()

Tells the Reaper project to start playback.

println(msg)

Prints a line of text to Reaper console.

replaceListElement(inputList, elementToReplace, withElement)

This function takes in a list, and will replace a variable in the list with another variable. This is equivalent to list[index] = newVariable, except instead of using a number/index of the list you can specify an element of the list.

If the elementToReplace variable does not exist in the list, the function returns inputList unchanged.

replaceString(patternString, characterToReplace, withCharacter)

This function replaces a character in the original pattern string with a character specified by the user.

patternStringoriginal string
characterToReplacethe character in the original patternString that will be replaced
reverseList(inputList)

This is a utility function for reversing a list. This will work on any list.

list = [1, 2, 3, 4, 5, 6, 7, 8, 9]

reverseList(list)

list = [9, 8, 7, 6, 5, 4, 3, 2, 1]
    
reverseString(inputString)

This is a utility function for reversing a string. It will work for any string, but it should be used in conjunction with makeBeat() beat patterns. This function returns a reversed version of the string used for the input.

pattern = "0+0+0-0+++0+++00"

reverseString(pattern)

pattern = "00+++0+++0-0+0+0"
    
rhythmEffects(trackNumber, effectType, effectParameter, valueList, rhythmString)

Uses makeBeat() style strings to set effects envelopes. Takes string input for rhythm that refers to values in a list.

To create rhythmic effects:

  • '0, 1, 2, 3, 4, 5, 6, 7, 8 ,9' correspond to indexes in lists of value effects
  • '+' to extend length of effect value
trackNumberselects a track
effectTypeis an effect
effectParameteris the specific type of effect
valueListis a list containing numerical values that set effects points
measureis where you want the effect to start
rhythmStringis the string denoting which values you want from valueList.
You may use “0, 1, 2, 3, 4, 5, 6, 7, 8, 9” to draw from the list.
“+” indicates extending the block of time for the envelope
“-” will ramp between defined effect values

For example:

	
distortValues = [0, 20, 40]
distortBeat = "1+++0+++2+++0+++"
rhythmEffects(1, DISTORTION, DISTO_GAIN, distortValues, 1, distortBeat)
	
selectRandomFile(folder, extension='.wav')

Selects a random file from a specified folder. There's an optional argument for specifying the type of file extension to select.

setEffect(trackNumber, effectType, effectParameter=None, effectStartValue=None, effectStartLocation=1, effectEndValue=None, effectEndLocation=None)

This function applies an effect to a specified track number.

trackNumbertrack number that has the effect
effectTypeeffect constant variable. (listed below)
effectParameterone of the constant variables associated with an effect
effectStartValuevalue of effect at beginning of effect
effectStartLocationfloating point location of the effectStartValue
effectEndValuevalue of effect at end of effect
effectEndLocationfloating point location of the effectEndValue

Effect and parameter constants (all constants are capitalized):

DELAY

Delays a signal by a specified amount of time. Parameters :

  • DELAY_TIME = delay time in ms (Range 0.0 - 4000.0)
  • DELAY_MIX = delay effect wet mix (Range 0.0 to 1.0)

Example implementation:

fitMedia(AFRO_LATIN_GUITAR2_4M, 1, 1, 5)
setEffect(1, DELAY, DELAY_TIME, 0, 1, 30, 4)
			
FILTER

A resonant lowpass filter. Parameters :

  • FILTER_FREQ = frequency in Hz (Range 20.0 to 20000.0)
  • FILTER_MIXM = filter effect wet mix (Range 0.0 to 1.0)

Example implementation:

fitMedia(AFRO_LATIN_GUITAR2_4M, 1, 1, 5)
setEffect(1, FILTER, FILTER_FREQ, 0, 1, 200, 4)
			
DISTORTION

Guitar distortion. Parameters :

  • DISTO_GAIN = gain in dB (Range 0.0 to 50.0)
  • DISTO_MIX = distortion effect wet mix (Range 0.0 to 1.0)

Example implementation:

fitMedia(AFRO_LATIN_GUITAR2_4M, 1, 1, 5)
setEffect(1, DISTO, DISTO_GAIN, 0, 1, 50, 4)
			
PITCHSHIFT

Pitch shifter. Parameters :

  • PITCHSHIFT_SHIFT = pitchshift in semitones (Range -12 to 12)
  • PITCHSHIFT_MIX = pitchshifter effect wet mix (Range 0.0 to 1.0)

Example implementation:

fitMedia(AFRO_LATIN_GUITAR2_4M, 1, 1, 5)
setEffect(1, PITCHSHIFT, PITCHSHIFT_SHIFT, 0, 1, 12, 4)
VOL_PAN

Volume/panning. Parameters :

  • VOL_PAN_VOL = volume in dB (Range -60.0 to 12.0)
  • VOL_PAN_PAN = panning (-100.0 = Left, 100.0 = Right)

Example implementation:

fitMedia(AFRO_LATIN_GUITAR2_4M, 1, 1, 5)
setEffect(1, VOL_PAN, VOL_PAN_VOL, -60, 1, 12, 4)
			

Note : For Wet mix argument for all effects, 0.0 indicates 0%, 1.0 indicates 100%

setTempo(tempo)

Sets the tempo for the project in beats per minute.

shuffleList(inputList)

This is a utility function for doing a naive 'shuffling' a list.

The function takes the inputList variable and returns a 'shuffled' version of it.

for example:

list = [1, 2, 3, 4, 5, 6, 7, 8, 9]

shuffleList(list)

list = [4, 5, 2, 7, 1, 6, 3, 9, 8]
    
shuffleString(inputString)

This is a utility function for doing a naive 'shuffling' a string pattern.

The function takes the patternString variable and returns a 'shuffled' version of it, without taking sustain or rests into consideration.

for example:

pattern = "11111+++11111+++"

shuffleString(pattern)

pattern = "11+1111+11+1+11+"