Live coding and synthesis with NodeJS and a browser
Facet is an open-source live coding system for algorithmic music and synthesis. With a code editor in the browser and a pair of NodeJS servers running locally on your machine, Facet can generate and sequence audio, MIDI, OSC, and image data.
Facet runs on MacOS, Linux, and Windows.
brew install sox
should work. If running on Windows: you need to modify your Path environment variable so that SoX can be run from the command line. Ultimately you need to be able to run the command sox
from the command line and verify that it's installed.facet
and NOT facet-main
.npm install
.npm run facet
. This will start the servers that run in the background for generating and patterns and keeping time. If running on Windows: Windows has a firewall by default for local connections (on the same private network), and it needs to be disabled, or you can manually allow the connection via the confirmation dialog from the Windows firewall system when starting up the servers.$('test').sine(100).play();
Move your cursor so it's on the line. Hit [ctrl + enter]
to run the command. The code editor application will always briefly highlights to illustrate what command(s) ran. You should hear a sine wave playing through your browser tab. Hit [ctrl + .]
or [ctrl + /]
(Windows) to stop.Facet commands are based entirely around JavaScript, using a class called a FacetPattern
. In order to produce audio or MIDI output, create an instance of a FacetPattern, and run some methods:
new FacetPattern('example').sine(100).play();
There is a shorthand for creating a new FacetPattern instance:
$('example').sine(100).play();
Some FacetPatterns might contain other FacetPatterns. The most outer-facing one must have a name via the above method $()
, but other FacetPatterns inside the code can use a separate, more concise shorthand, _
:
$('example').sine(100).times(_.sine(100)).play();
There are lots of methods to generate, translate, and orchestrate playback on FacetPattern data:
$('example').sine(100).times(random()).play();
// each time you run ^, the same sine wave at a different volume
Certain operations (e.g. sometimes()
, iter()
, slices()
, mix()
, run()
) allow you to supply functions as arguments:
$('example').iter(16,()=>{this.append(_.randsamp('808').speed(10))}).play();
// stitches together 16 random samples, each playing at 10x normal speed
Below the text editor, there are several UI elements which control the servers running in the background. Moving from left to right:
.bpm()
operation runs, this value is updated automatically)[ctrl + enter]
or [ctrl + r]
. All commands not separated by multiple newlines will run together.[ctrl + ']
. All commands not separated by multiple newlines will be stopped, if they are currently running.[ctrl + ;]
. All commands not separated by multiple newlines will continue to play back as-is, without regenerating.[ctrl + \]
. All commands not separated by multiple newlines will play back once and not regenerate.[ctrl + .]
or [ctrl + /]
[ctrl + ,]
[ctrl + space]
. This will list all available methods including their arguments in a dropdown menu, filtered by the text preceding the cursor position. If only one matching method is found, it will autocomplete that method.[ctrl + f]
When you run the npm run facet
command in the terminal, the following sequence of events occurs:
A server, known as the process manager
, starts up on http://localhost:5831. This server is responsible for managing the startup and shutdown of the two servers listed below:
The transport server
starts up on http://localhost:3211. This server is responsible for handling the timing and playback of audio, MIDI, and OSC events.
The pattern generator
server starts up on http://localhost:1123. This server listens to requests from the text editor UI in the browser located at http://localhost:1124 and interprets those commands into data. If the pattern is intended to be played back as audio, a corresponding .wav file will be stored in the tmp/
subdirectory in the Facet repo. Otherwise, if the pattern is intended for MIDI or OSC output, the data will be posted directly to the transport server.
facet
object.facet
object will pass OSC commands from Facet into your patcher. Use the /route
Max object to route the OSC data in your Max patcher.examples/osc.md
example file for more details on receiving OSC in Max or any other application.Both mousex
and mousey
, as floating-point number representations of your cursor's position in the browser window, are available for use in commands, e.g.:
$('example').sine(100).times(mousey).play(); // cursor y position controls volume every time the code runs
There are 128 notevalues variables, corresponding to divisions of 1 whole note. A whole note is n1
, a half note is n2
, etc... up to n128
.
The variable bpm
(representing the current BPM in the Facet transport when the FacetPattern is generated) is available for use in commands as well.
The variable bars
(representing how many loops have occurred since the time the server was started) is available for use in commands as well. This is especially useful with the modulo % operator, e.g.: bars%4
, which could be either 0, 1, 2, or 3, depending on how many loops have occurred.
You can change the sample rate for the audio generated and played back with Facet by modifying SAMPLE_RATE
in js/config.js
to whatever integer you want.
In Facet commands, you can use the constant SAMPLE_RATE
to refer to the configured sample rate, which is useful when you want to do something for a specific number of seconds. The constant NYQUIST
refers to the Nyquist frequency which is SAMPLE_RATE/2
.
For example: $('example').noise(SAMPLE_RATE).play(); // generate and continually play back exactly 1 second of noise
By default, Facet checks every 10 milliseconds whether it needs to fire any events that produce output, such as playing audio, MIDI, or osc. You can change EVENT_RESOLUTION_MS
in js/config.js
to set a different integer value. Slower speeds (e.g. 20 = 20ms) will produce less tightly-timed events but can help make it possible for Facet to run on computers with less CPU resources, at the expense of slight timing accuracy. Faster speeds (e.g. 4 = 4ms) will produce tighter event scheduling but can overload computers with less CPU resources.
Facet can synthesize and orchestrate the playback of multiple FacetPatterns simultaneously, producing audio, MIDI, or OSC output. By default, patterns will continually regenerate each loop. In order to only regenerate every n loops, use the .every()
method. In order to continue playing a pattern and not regenerate, use the .keep()
method. In order to only play back once, use the .once()
method.
PlaybackFacetPattern
, as the global transport loops through a whole note.PlaybackFacetPattern
should contain floating-point numbers between 0 and 1, corresponding to the relative point in the transport between 0 and 1 when the generated audio should play.pitchSequenceData
is an optional argument that should contain an array of pitch shift values. These values are used to adjust the pitch of the sound at each step of the sequence. The pitch shift values are spread out over the sequence steps, so if there are fewer pitch shift values than sequence steps, the pitch shift values will be repeated.play()
works by superposing copies of the input FacetPattern at all the playback positions, rather than creating discrete events to fire at each playback position. This helps to keep timing tight, as there is only one event that fires per loop to actually play each voice of audio, and it's always at position 0, where it plays the entire superposed pattern.keep()
operation. To stop playback, use the key command [ctrl + .]
or [ctrl + /]
, or press the stop button "■".$('example').randsamp('808').play(); // plays once at beginning of loop
$('example').randsamp('808').play(0.5); // plays once at middle point
$('example').randsamp('808').play(_.noise(4)); // plays once at 4 random positions
.channels()
call. Without a call to .channels()
, it will default to spatially positioning the FacetPattern between channels 1 and 2.PanningFacetPattern
should be between -1 and 1. Values beyond that will be clipped to the -1 - 1 range. A value of -1 will hard-pan the sound to the first active channel that is set via a .channels()
call (or defaulting to stereo). A value of 1 will hard-pan the sound to the last active channel. Values between -1 and 1 will crossfade between all the specified active channels.pan_mode
of 0 means that the panning moves smoothly between channels, e.g., channels adjacent to the selected full-volume channel will have some signal bleeding into them. Switching the pan_mode
to 1 makes the panning work in a discrete manner, where only one channel has a signal in it at any given time, and there is no bleed between channels.$('example').noise(n1).times(_.ramp(1,0,n1)).pan(_.sine(1,n1)).play(); // no channels are specified; defaults to stereo panning
$('example').noise(n1).times(_.ramp(1,0,n1)).channels([1,2,4]).pan(_.sine(1,n1)).play(); // pans the noise smoothly around channels 1, 2, and 4
$('example').noise(n1).times(_.ramp(1,0,n1)).channels([1,2,4]).pan(_.sine(1,n1),1).play(); // hard-pans the noise discretely between channels 1, 2, and 4
.channel()
method (and equivalent channels()
method) allow you to route the output of a FacetPattern onto the specified channel(s) in the channels
input array. NOTE: CPU will also increase as the total number of channels increases.$('example').randsamp('808').channel(1).play(); // first channel only
$('example').randsamp('808').channels([1,3]).play(); // second channel only
$('example').randsamp('808').channel(_.from([9,10,11,12,13,14,15,16]).shuffle().reduce(ri(1,8))).play(); // play on a random number of channels from 9-16
samples/
directory or a sub-directory containing the FacetPattern. If the directory doesn't exist, it will be created..channels()
or with its audio panned between multiple channels via .pan()
, the saved wav file will have that many channels.my/path/here
). For Windows, you will need to use back slashes (e.g my\path\here
)$('example').iter(6,()=>{this.append(_.sine(ri(1,40))).saveas('/myNoiseStuff/' + Date.now()
)}); // creates 6 wav files in the myNoiseStuff directory. Each filename is the UNIX timestamp to preserve order.dir
directory, in alphabetical order, creating a new wav file in the samples/
directory or a sub-directory, as specified in saved_filename
. If the directory doesn't exist, it will be created.samplesBetweenEachFile
argument can be a single number or a FacetPattern. This value specifies the exact number of samples between each file in the output file. If it's a FacetPattern, its values will be continuously cycled through while stitching together all the files in the directory.num_channels
channels (default = 1).my/path/here
). For Windows, you will need to use back slashes (e.g my\path\here
)$('example').stitchdir('mysamples',n1,'myNewStitchedFile'); // stitch together all the wavs in samples/mysamples, with a whole note between each file, creating a new file called MyNewStitchedFile.wav
.stop()
is found in a command, the entire command will be skipped and not executed. This helps to preserve CPU.$('example').noise(n16).play().stop(); // you only hear sound when you remove the stop()
You might need to activate a MIDI driver on your machine in order to send MIDI from Facet to a DAW. If Facet finds no MIDI drivers, the dropdown select UI in the browser will be empty, and if you try the below commands they will produce no output. Google "install MIDI driver {your OS goes here}" for more information.
You need to connect the MIDI device you want to use before starting Facet.
VelocityPattern
and DurationPattern
will automatically scale to match the note pattern. This allows you to modulate MIDI velocity and duration over the course of the whole note.channel
argument by default sends the MIDI out channel 1. It can be set to any channel between 1-16.PositionPattern
argument is optional. When not supplied, the positions will calculate automatically and spread pattern data across the entire whole note, playing the first value in the data at relative position 0, and playing the last value in the data at relative position 1. By supplying a PositionPattern
, you can program when each note should play.$('example').sine(1,32).scale(36,90).round().note();
$('example').sine(1,ri(32,100)).scale(36,ri(52,100)).prob(rf()).nonzero().round().note();
$('example').noise(16).scale(60,80).sort().note(100,125,1,_.ramp(0,0.25,16)); // play all notes during the first 25% of the whole note
Methods for image generation and processing
section further below in the README document.VelocityPattern
and DurationPattern
will automatically scale to match the note pattern. This allows you to modulate MIDI velocity and duration over the course of the whole note.channel
argument by default sends the MIDI out channel 1. It can be set to any channel between 1-16.lowNote
and highNote
arguments define the range of MIDI notes that can be played. By default, this range is from 0 (inclusive) to 127 (inclusive).$('example').silence(2500).circle2d(25,25,25,1).saveimg().note2d(100,125,1,30,80).once(); // saves 50x50 image with a circle in the middle; then plays that circle shape between the MIDI notes 30 and 80
controller_number
for every value in the FacetPattern's data.channel
argument by default sends the MIDI out channel 1. It can be set to any channel between 1-16.$('example').drunk(64,0.1).cc();
chord ( chordTypePattern, inversion_mode = 0 )
chordTypePattern
can be a string, or a FacetPattern, or an array of either. If chordTypePattern
is a FacetPattern, the chord intervals will correspond to the data of the chordTypePattern
FacetPattern.chordTypePattern
is an array with more than one value in it, then the chord type will change dynamically over the course of the loop. For example, a chordTypePattern
of ['major','maj7','minor'] will produce major chords for the first third of the loop, then switch to maj7 chords for the middle third, then switch to minor chords for the last third.chordTypePattern
is a string, it must be from the below list of chord names:maj
/ major
= 0,4,7
min
/ minor
= 0,3,7
fifth
/ 5th
= 0,5
seventh
/ 7th
= 0,4,7,10
major seventh
/ maj7
= 0,4,7,11
minor seventh
/ m7
= 0,3,7,10
diminished
/ dim
= -1,2,5
add2
= 0,2,4,7
add9
= 0,4,7,14
chord_type
is a string, the inversion_mode
can be 0, 1, 2, or 3. This number represents how many of the values in the chord have been inverted and are now below the root.key()
operation after the chord()
operation.$('example').ramp(36,72,32).chord('maj7').add((bars%4)*12).key('F#','major').note(50,100,1);
$('example').noise(16).scale(36,90).chord(_.from([3,5,7,10,11,14,16,20,25])).key('c','major').note(); // 9-note chords mapped onto c major
$('example').noise(8).scale(30,80).chord('maj7').key(['c','f#'], ['major','minor']).note(100,500); // maj7 chords, first in c major, then in f# minor
keyLetterPattern
and keyScalePattern
.keyLetterPattern
values can be a string: "A", "A#", "B", "C", "C#", "D", "D#", "E", "F", "F#", "G", "G#", or an array, or strings: ["A", "D"]
, or a FacetPattern of strings: _.from(['A','D']).dup(3).shuffle()
. When keyLetterPattern
contains multiple values, the key will change dynamically over the course of the loop. So a keyLetterPattern
of ["A", "D", "G"]
will be in the key of A for the first third, then switch to D for the middle third, then switch to G for the last third.keyScalePattern
values can either be a string (see list below), or a FacetPattern containing 1-12 binary numbers (see examples), or an array of strings/FacetPatterns, in which case the values change dynamically over the course of the loop.$('example').randsamp('808').reduce(32).scale(36,51).key('F#', 'bebop').note();
$('example').noise(16).scale(30,80).key('c', _.from([1])).note(); // octave scale, via custom FacetPattern
$('example').noise(16).scale(30,80).key('c', _.from([1,0,0,0,0,0,0,0,0,0,0,0])).note(); // equivalent to the above custom octave scale; the padded zeroes are optional
$('example').noise(16).scale(30,80).key('c', _.from([1,0,0,0,0,0,1])).note(); // octave + perfect fifth scale, via custom FacetPattern
$('example').noise(16).scale(30,80).key(['c','f#'], ['major','minor']).note(); // the first half is c major; the second half is f# major
address
for every value in the FacetPattern's data.OSC_OUTPORT
in js/config.js
to whatever port number you need.address
argument must begin with a backslash: /
.$('example').noise(128).osc('/test');
channel
argument by default sends the MIDI out channel 1. It can be set to any channel between 1-16.$('example').sine(1).size(128).pitchbend();
midifilename
in the midi
directory, with the FacetPattern's data.VelocityPattern
and DurationPattern
will automatically scale to match the note pattern. This allows you to modulate MIDI velocity and duration over the course of the whole note.velocityPattern
expects values between 1 and 100. (This range is set by the midi-writer-js npm package).wraps
parameter controls how many times to wrap the data back around onto itself, allowing for MIDI polyphony. For example, if your FacetPattern has 8 different 128-note patterns appended together in a sequence, a wraps
of 8 would superpose all of those patterns on top of each other, while a wraps
value of 4 would produce four patterns on top of each other, followed by four more patterns on top of each other.tick_mode
is set to a truthy value, the numbers in durationPattern
represent the number of ticks to last, rather than a whole-note divisions. 1 tick = 1/256th note. This allows for durations smaller and larger than the valid duration values for when tick_mode
is set to false.tick_mode
is set to false or excluded from the command, the following values are the only valid durationPattern
argument values:1: whole note
2: half note
d2: dotted half note
dd2: double dotted half note
4: quarter note
4t: quarter triplet note
d4: dotted quarter note
dd4: double dotted quarter note
8: eighth note
8t: eighth triplet note
d8: dotted eighth note
dd8: double dotted eighth note
16: sixteenth note
16t: sixteenth triplet note
32: thirty-second note
64: sixty-fourth note
$('example').noise(64).scale(20,90).key('c major').savemidi(ts(),64,16).once(); // 64 random notes in c major at 64 velocity, each lasting a 16th note
$('example').noise(64).scale(20,90).key('c major').savemidi(ts(),_.noise(64).scale(1,100),4,1,true).once(); // 64 random notes in c major, each with a random velocity between 1 - 100, each lasting 4 ticks
$('example').iter(8,()=>{this.append(_.sine(choose([1,2,3,4])).size(128).scale(ri(30,50),ri(60,90)).key('c major'))}).savemidi(ts(),64,16,8).once(); // 8 sine wave patterns playing notes in c major, superposed on top of each other. try changing the wraps argument to values other than 8
midifilename
in the midi
directory, with the FacetPattern's data, assuming that the data was created using the 2d methods for image generation and processing. All nonzero "pixel" values will be translated into a MIDI note. Go to the methods for image generation and processing section for more details on these methods.VelocityPattern
and DurationPattern
will automatically scale to match the note pattern. This allows you to modulate MIDI velocity and duration over the course of the whole note.velocityPattern
expects values between 1 and 100. (This range is set by the midi-writer-js npm package).min_note
and max_note
values control the range of notes that the corresponding 2d pattern will be generated between.tick_mode
is set to a truthy value, the numbers in durationPattern
represent the number of ticks to last, rather than a whole-note divisions. 1 tick = 1/256th note. This allows for durations smaller and larger than the valid duration values for when tick_mode
is set to false.tick_mode
is set to false or excluded from the command, the following values are the only valid durationPattern
argument values:1: whole note
2: half note
d2: dotted half note
dd2: double dotted half note
4: quarter note
4t: quarter triplet note
d4: dotted quarter note
dd4: double dotted quarter note
8: eighth note
8t: eighth triplet note
d8: dotted eighth note
dd8: double dotted eighth note
16: sixteenth note
16t: sixteenth triplet note
32: thirty-second note
64: sixty-fourth note
$('example').silence(2500).iter(8,()=>{this.tri2d(ri(0,49),ri(0,49),ri(0,49),ri(0,49),ri(0,49),ri(0,49),1,0)}).savemidi2d(ts(), 64, 16).once(); // 8 randomly sized triangles in 2d space, all at velocity 64, 16th note durations
$('example').silence(2500).iter(10,()=>{this.circle2d(ri(10,40), ri(10,40), 10, 1, 0)}).savemidi2d(ts(), 64, 64).once(); // 10 randomly sized circles in 2d space, all at velocity 64, 64th note durations
$('example').bpm(_.from([20,40,80,160,320]).shuffle()); // each loop will be all 5 of these BPM, randomly ordered
modulo_operand
, equals the equals_value
argument. This can be useful when you want to conditionally skip certain commands, only rerunning every n bars.
$('example_0').sine(ri(100,400)).whenmod(4, 0); // regenerates the pattern once every 4 bars
$('example_2').sine(ri(100,400)).whenmod(4, 2); // regenerates the pattern once every 4 bars, but 2 bars away from the above example
keep()
, the FacetPattern will regenerate each loop by default.$('example').sine(ri(10,500)).keep().play();
once()
, the FacetPattern will regenerate and play back each loop by default.$('example').noise(4096).play().once();
n_loops
so the pattern can last any number of loops before regenerating.$('example').randsamp('808').play(_.ramp(0,1,16)).over(ri(1,4)); // random sample played 16 times over 1,2,3 or 4 bars
$('example').drunk(2048,0.01).cc().over(128); // drunk walk over 128 bars, creates a drifty process that you can map onto device paramters to slowly randomize something
This can be useful when you want to access the same pattern across multiple commands.
set ( name )
saves a FacetPattern's data in memory, for reference as a variable in operations. Any FacetPatterns stored via .set()
will only be stored until the server is closed.
if a pattern stored with set()
has more than one piece of data in it, the corresponding variable will be an array. If the pattern has one piece of data in it, the corresponding variable will be a float.
NOTE: when you run the .set()
command for the first time after starting the system, if you're also running commands that reference that variable in the same block, for the first evaluation, the variable will have a value of 0 as it has not fully propagated into the variable storage system.
NOTE: if you want to set more than one variable, you should run all the .set()
methods in a single command, so they do not create a race condition for when they are evaluated.
$('example').tri(100).set('abc').sine(abc).play(); // run it all in one command - just remember the first evaluated sine will have a frequency of 0
$('set_example').noise(32).curve().set('my_var').once(); // first, set the variable here $('example').noise(100).times(my_var).play(); // now, you can use my_var in commands
// multi-variable example // step 1: initialize the patterns by running this with .once() $('p1').noise(64).scale(ri(0,63),ri(64,127)).prob(rf()).sticky(rf(0.9,1)).round().set('p1').once(); $('p2').noise(64).scale(ri(0,63),ri(64,127)).prob(rf()).sticky(rf(0.9,1)).round().set('p2').once(); $('p3').noise(64).scale(ri(0,63),ri(64,127)).prob(rf()).sticky(rf(0.9,1)).round().set('p3').once(); $('p4').noise(64).scale(ri(0,63),ri(64,127)).prob(rf()).sticky(rf(0.9,1)).round().set('p4').once();
// step 2: start the process to continually modify some of the values in the d1-d4 patterns, in one command $('example').from(p1).jam(0.1, 10).wrap(0,127).round().set('p1').from(p2).jam(0.1, 10).wrap(0,127).round().set('p2').from(p3).jam(0.1, 10).wrap(0,127).round().set('p3').from(p4).jam(0.1, 10).wrap(0,127).round().set('p4');
inc ( name, amount_to_add = 1 )
name
by amount_to_add
. This variable can be used in operations.set()
method, when you run the .inc()
command for the first time after starting the system, if you're also running commands that reference that variable in the same block, for the first evaluation, the variable will have a value of 0 as it has not fully propagated into the variable storage system.$('example').inc('abc').iter(abc,()=>{this.sup(_.randsamp('808'),i/iters)}).play(); // more 808 samples each iteration
dec ( name, amount_to_subtract = 1 )
name
by amount_to_add
. This variable can be used in operations.set()
method, when you run the .dec()
command for the first time after starting the system, if you're also running commands that reference that variable in the same block, for the first evaluation, the variable will have a value of 0 as it has not fully propagated into the variable storage system.$('example').from(8).set('abc').sometimes(0.5,()=>{this.dec('abc')}).sometimes(0.5,()=>{this.inc('abc')}).iter(abc,()=>{this.sup(_.randsamp('k'),i/iters)}).play(); // start at 8, sometimes increment & sometimes decrement the total number of 808 samples
bars
. (bars
is a global variable that starts at 0 and increments at the completion of a loop.)values
array, based on bars % modulo
. If the bars
value currently is 9, and the modulo
argument to this method is 4, since 9 % 4 = 1, this method will return the value from the values
array immediately following the number 1.values
array contains an even number of elements. If not, it throws an error.$('example').sine(barmod(4,[0,100,1,150,2,200,3,300])).play(); // when bars % 4 == 0, plays a 100Hz sine. when bars % 4 == 1, plays a 150 Hz sine. when bars % 4 == 2, plays a 200Hz sine. when bars % 4 == 3, plays a 300Hz sine.
$('example').sine(choose([10,200,1000])).play(); // sine wave with either 10, 200, or 1000 cycles
index
in the circle of fifths, starting with C and ending with F.['C', 'G', 'D', 'A', 'E', 'B', 'F#', 'C#', 'G#', 'D#', 'A#', 'F']
.$('example').noise(16).scale(36,90).key(cof(2)).note(); // MIDI notes in D major
$('example').noise(16).scale(36,90).key(cof(ri(0,11))).note(); // MIDI notes in random major key
$('example').sine(choose([10,200,1000])).dup(decide()).play(); // duplicate half the time
hzfrequency
value to its corresponding MIDI note number.$('example').sine(220).times(_.sine(ftom(ri(400,1200)))).play(); // 220Hz sine wave (A) multplied by a chromatically related higher sine wave
milliseconds
value to that many samples, at whatever sample rate the user has configured.$('example').noise(4096).size(ms(5)).play(); // 5ms noise
$('example').noise(4096).size(ms(50)).play(); // 50ms noise
midi_note_number
value to its corresponding frequency in Hz.$('example').sine(mtof(choose([36,38,40,41,43,45,47,48]))).play(); // random sine wave each loop in C major key
midi_note_number
value to its corresponding number of samples.$('example').noise(n4).delay(mtos(choose([36,38,40,41,43,45,47,48]))).delay(mtos(choose([36,38,40,41,43,45,47,48]))).delay(mtos(choose([36,38,40,41,43,45,47,48]))).play(); // noise is delayed by amounts that are harmonic with C major key
min
and max
. If int_mode
= 1, returns an integer. Otherwise, returns a float by default.rf(min,max)
and a random integer: ri(min,max)
.weight
argument allows you to specify an exponential weight for the probability of random values. For instance, rf(0.125,8,3)
will generate half of its values between 0.125 and 1; and the other half will be between 1 and 8. By default, the weighting is linear, i.e. all values between min
and max
have equal probability.$('example').sine(ri(1,1000)).play(); // a sine wave with 1 - 1000 cycles
$('example').sine(100,n1).saveas('mytest'+ts()).once(); // saves a file in the samples directory named like this: mytest1704420621454.wav
$('example').sine(100,n16).play(_.ramp(0,1,12),_.from(just())); // sine waves in ascending just intonation scale
$('example').sine(100,n16).play(_.ramp(0,1,12),_.from(pythagorean())); // sine waves in ascending pythagorean intonation scale
$('example').sine(100,n16).play(_.ramp(0,1,12),_.from(equaltemp())); // sine waves in ascending equal temperament intonation scale
$('example').sine(100,n16).play(_.ramp(0,1,12),_.from(meantone())); // sine waves in ascending meantone intonation scale
$('example').sine(100,n16).play(_.ramp(0,1,12),_.from(edo19())); // sine waves in ascending edo19 intonation scale
$('example').sine(100,n16).play(_.ramp(0,1,12),_.from(edo31())); // sine waves in ascending edo31 intonation scale
key()
method.$('example').noise(32).scale(30,80).sort().key('f#', randscale()).note(); // random scale in f#
When a generator takes a FacetPattern or an array as an argument, it uses that pattern to dynamically change its behavior over time, affecting the output in a more complex way than if a single number were supplied. For example, with the command $('example').sine(440).play();
, the output is a static 440Hz wave. But with the command $('example').sine(_.sine(5).scale(20,2000))).play();
, the frequency of the sine wave is being modulated by a 5 Hz sine wave which is generating values between 20 and 2000. This produces a classic frequency modulation sound, but since you can supply any FacetPattern as an argument, there are lots of sound design possibilities.
frequencyPattern
Hertz, lasting for duration
samples, at the sample rate defined by samplerate
.fade_in_and_out
argument is set to true. This will cause the first 30 milliseconds to be faded in an out, to avoid audible clicks. Using a non-truthy value for fade_in_and_out
will generate the signal without applying any fade.$('example').sine(440,n4).play(); // 440 Hz sine wave for a quarter note
$('example').sine(_.ramp(10,2000,300)).play(); // ramp from 10Hz to 2000 Hz over 300 values
$('example').sine(_.sine(5).scale(20,2000)).play(); // 5Hz frequency modulation with output frequencies oscillating between 20Hz and 2000Hz
frequencyPattern
Hertz, lasting for duration
samples, at the sample rate defined by samplerate
.fade_in_and_out
argument is set to true. This will cause the first 30 milliseconds to be faded in an out, to avoid audible clicks. Using a non-truthy value for fade_in_and_out
will generate the signal without applying any fade.$('example').cosine(440,n4).play(); // 440 Hz cosine wave for a quarter note
$('example').cosine(_.ramp(10,2000,300)).play(); // ramp from 10Hz to 2000 Hz over 300 values
$('example').cosine(_.cosine(5).scale(20,2000)).play(); // 5Hz frequency modulation with output frequencies oscillating between 20Hz and 2000Hz
frequencyPattern
Hertz, lasting for duration
samples, at the sample rate defined by samplerate
.$('example').circle(440,n4).play(); // 440 Hz cosine wave for a quarter note
$('example').noise(n1).times(_.circle(4)).play().once(); // amplitude modulation of noise with a quarter note circular waveform
$('example').noise(n1).ffilter(_.circle(1).invert().size(128).scale(0, NYQUIST/2),_.circle(1).size(128).scale(NYQUIST / 2, NYQUIST)).play().once(); // circular spectral filtering of a whole note of noise
states
parameter is an array where each entry is an object representing a state. Each state object has a name
, a value
that corresponds to a value in this.data
, and a probs
object that defines the transition probabilities to other states.this.data
by transitioning each value to a new state based on the probabilities defined in the states
array. The transition probabilities are normalized so that they add up to 1 for each state.$('example')
.iter(choose([3,4,8]), () => {
this.prepend(_.from(['k*', 'h*', 's*', 'h*', '_', '_','_', '_'])
.markov([{
name: "state1",
value: 'k*',
probs: {
"state1": 0.8,
"state2": 0.5,
"state3": 0.5
}
},
{
name: "state2",
value: 'h*',
probs: {
"state3": 1
}
},
{
name: "state3",
value: 's*',
probs: {
"state1": 1
}
},
{
name: "state4",
value: '_',
probs: {
"state1": 0.5,
"state4": 0.5
}
}
]))
})
.run(() => {
this.seq(this.data)
}).play();
frequencyPattern
Hertz, lasting for duration
samples, at the sample rate defined by samplerate
.fade_in_and_out
argument is set to true. This will cause the first 30 milliseconds to be faded in an out, to avoid audible clicks. Using a non-truthy value for fade_in_and_out
will generate the signal without applying any fade.$('example').phasor(440,n4).play(); // 440 Hz phasor wave for a quarter note
$('example').phasor(_.ramp(10,2000,300)).play(); // ramp from 10Hz to 2000 Hz over 300 values
$('example').phasor(_.phasor(5).scale(20,2000)).play(); // 5Hz frequency modulation with output frequencies oscillating between 20Hz and 2000Hz
frequencyPattern
Hertz, lasting for duration
samples. damping
and feedback
values should be between 0 and 1.fade_in_and_out
argument is set to true. This will cause the first 30 milliseconds to be faded in an out, to avoid audible clicks. Using a non-truthy value for fade_in_and_out
will generate the signal without applying any fade.$('example').pluck(440,n4,rf(),rf()).play(); // different 440 Hz quarter note pluck each time
$('example').pluck(_.ramp(100,2000,300),n1,0,0.99).play(); // ramp from 100Hz to 2000 Hz over 300 values
frequencyPattern
Hertz, with a pulse width defined by pulse_width
, lasting for duration
samples, at the sample rate defined by samplerate
.fade_in_and_out
argument is set to true. This will cause the first 30 milliseconds to be faded in an out, to avoid audible clicks. Using a non-truthy value for fade_in_and_out
will generate the signal without applying any fade.$('example').rect(440,n4,rf()).play(); // 440 Hz rectangle wave for a quarter note, different bandwidth each time
$('example').rect(_.ramp(10,2000,300)).play(); // ramp from 10Hz to 2000 Hz over 300 values
$('example').rect(_.rect(5).scale(20,2000)).play(); // 5Hz frequency modulation with output frequencies oscillating between 20Hz and 2000Hz
frequencyPattern
Hertz, lasting for duration
samples, at the sample rate defined by samplerate
.$('example').square(440,n4).play(); // 440 Hz square wave for a quarter note
$('example').square(_.ramp(10,2000,300)).play(); // ramp from 10Hz to 2000 Hz over 300 values
$('example').square(_.square(5).scale(20,2000)).play(); // 5Hz frequency modulation with output frequencies oscillating between 20Hz and 2000Hz
frequencyPattern
Hertz, lasting for duration
samples, at the sample rate defined by samplerate
.fade_in_and_out
argument is set to true. This will cause the first 30 milliseconds to be faded in an out, to avoid audible clicks. Using a non-truthy value for fade_in_and_out
will generate the signal without applying any fade.$('example').tri(440,n4).play(); // 440 Hz triangle wave for a quarter note
$('example').tri(_.ramp(10,2000,300)).play(); // ramp from 10Hz to 2000 Hz over 300 values
$('example').tri(_.tri(5).scale(20,2000)).play(); // 5Hz frequency modulation with output frequencies oscillating between 20Hz and 2000Hz
integer
. If length
is not present, the output FacetPattern will be the actual length of the binary representation of integer
.$('example').binary(8); // 1000
$('example').binary(490321,13); // 1110111101101: truncated at 13 values
$('example').binary(8,12); // 000000001000: padded with 0s
length
values, starting at starting_value
which is a random value between 0 and 1 by default. intensity
controls how much to add.$('example').drunk(16,0.1); // slight random movement
values
, which must have a total number of entries equal to a multiple of 3. The numbers inside the values
array should be continually ordered in groups of three: from
, to
, size
, just like the ramp()
method. $('example').noise(ms(500)).times(_.envelope([0,1,ms(10),1,0.1,ms(200),0.1,0,ms(290)])).play(); // transient noise burst
pulses
pulses over steps
steps.$('example').sine(100).times(_.euclid(4,8)).play(); // gating a sine wave with a euclidean sequence
files
subdirectory. If no file exists there, it will try to load the file as an absolute path on your hard drive.my/path/here
). For Windows, you will need to use back slashes (e.g my\path\here
)$('example').file('my_image.png').play(); // if my_image.png is in the files directory, this will play the file's raw data. NOTE: this could be very noisy!
$('example').file('/Users/my_username/Desktop/myfile.zip').play(); // example with a supplied absolute file path
$('example').from([1,2,3,4]);
columnsPerSecond
value of 512 means that each second of audio will contain 512 columns of pixels. This value can be larger or smaller, but keep in mind that as this value decreases, the file will take more time to generate. This method can be CPU intensive and works best with smaller image files or larger columnsPerSecond values
.minimumFrequency
and maximumFrequency
values control the range of frequencies that the pixels will map onto.frequencyPattern
argument allows you to remap the rows of pixels with a FacetPattern. It should be scaled between 0 and 1. It will automatically be resized so its data length matches the height of the image in pixels. Lower values in frequencyPattern
will map onto lower frequencies inside the range of minimumFrequency
and maximumFrequency
. Higher values in frequencyPattern
will map onto higher frequencies inside the range of minimumFrequency
and maximumFrequency
.my/path/here
). For Windows, you will need to use back slashes (e.g my\path\here
)$('example').image('/path/to/file/goes/here.png',1024).play(); // each column lasts 1024 samples
length
.$('example').noise(1024).play();
n
prime numbers starting at offset
, skipping skip
prime numbers before including the next one in the list.n
specifies the number of prime numbers to generate.offset
specifies the first number to be included in the list of prime numbers. The default value is 2.skip
specifies the number of prime numbers to skip before including the next one in the list. The default value is 1.$('s').noise(n4).times(_.ramp(1,0,n4)).iter(12,()=>{this.allpass().delay(_.primes(60,1000,ri(20,2000)).data[i]).full()}).full().play(); // generates a quarter note transient burst of noise, then iteratively sends it through delays that are all primes
from
to to
over size
values.$('example').ramp(250,100,1000); // go from 250 to 100 over 1000 values
../files/
)
files
directory into memory. The default directory is ../files/
, but you can supply any directory as an argument.my/path/here
). For Windows, you will need to use back slashes (e.g my\path\here
)$('example').randfile().play(); // random new file converted to audio every time
../samples/
channel_index = 0 )
dir
directory into memory. The default directory is ../samples/
, but you can supply any directory as an argument.channel_index
= 0) but you can specify any channel to load.my/path/here
). For Windows, you will need to use back slashes (e.g my\path\here
)$('example').randsamp('808').reverse().play(); // random backwards sample
samples/
directory into memory. You can also specify any file with an absolute file path. The .wav
can be omitted from filename; in this case .wav
it will be automatically appended to filename. By default, it loads the first channel (channel_index
= 0) but you can specify any channel to load.my/path/here
). For Windows, you will need to use back slashes (e.g my\path\here
)$('example').sample('1234').play(); // if 1234.wav is in the samples directory, you're good to go
$('example').sample('./myfolder/myfile.wav'); // or point to the file with a relative path
length
samples.$('example').silence(n2).append(_.noise(n2)).play(); // first half of loop is silence; second half is noise
length
of continually ascending values in a circular loop between 0 and 1, where each value is degrees
away from the previous value. degrees
can be any number between 0 and 360. By default degrees
is set to 360/length
which produces an output pattern similar to branching leaves, where each value is as far away as possible from the previous value.angle_phase_offset
argument changes where the sequence starts. At its default value of 0, the first value will be 0. You can supply any float between 0 and 1, and the sequence will begin at that value instead.$('example').sine(1).times(_.spiral(1000,ri(1,360))).play(); // an interesting, modulated sine wave
length
with random 1s and 0s.$('example').turing(64); // instant rhythmic triggers
$('example').sine(100).add(-0.3).abs().play(); // a wonky sine
frequency
changes the amount of phase shift introduced by the filter at different frequencies. It will change the phase response of the filter while leaving the magnitude response unchanged.$('example').randsamp('808').iter(12,()=>{this.allpass().delay(ri(1,6000))}).scale(-1,1).play(); // reverb
position
with value
.$('example').turing(16).at(0,1); // the 1st value of the 16-step Turing sequence (i.e. 0% position) is always 1
$('example').turing(16).at(0.5,2); // the 9th value of the 16-step Turing sequence (i.e. 50% position) is always 2
$('example').randsamp('808').times(_.noise(4)).audio().play();
shift
is an optional parameter that specifies the number of bits to rotate. It defaults to 16 if not provided. The value of shift is converted to a non-negative integer and taken modulo 32 before being used.$('example').sine(1000,n2).bitshift(16).play(); // rotates the bits of a 1000Hz sine wave by 16 positions
$('example').from([1,1,3,4]).changed(); // 1 0 1 1
min
and max
range.$('example').from([1,2,3,4]).clip(2,3); // 2 2 3 3
ratio
is a float between 0 and 1 corresponding to n:1 so 0.5 would be 2:1, 0.2 would be 5:1, etc. threshold
is the sample amplitude at which compression kicks in. attackTime
and releaseTime
are expressed as relations to a second, so 0.1 would be 1/10th of a second.$('example').randsamp('808').compress(0.1,0.001,0.01,0.01).play();
$('example').sine(_.ramp(20,2000,1000)).crab().full().play(); // sine wave ramps from 20Hz to 2000Hz both backwards and forwards at the same time
$('example').noise(16).curve(); // not so noisy
$('example').noise(16).curve(0.5, 10); // fewer segments per curve
$('example').noise(16).curve(0.9); // different curve type
$('example').from([0.1,4,3.14]).distavg(); // -2.3133 1.5867 0.7267
num
times.$('example').noise(n16).dup(ri(2,12)).play(); // 16th note of noise repeats between 2 and 12 times each loop
num
times, with amplitude multiplied by feedback
each repeat.$('example').from([1]).echo(5); // 1 0.666 0.4435 0.29540 0.19674 0.13103
$('example').phasor(50).size(n8).echo(7).play(); // echoing out over a whole note
exponent
values larger than 1 will emphasize lower numbers more and more. Values less than 1 will emphasize higher numbers more and more.$('example').sine(_.ramp(100,2000,512).expo(6),n1).play().once(); // experiment with different expo() values to hear the difference
fade_percent
of the beginning and end are faded in/out.$('example').noise(1024).fade().play();
fade_percent
of the beginning is faded in.$('example').noise(20000).fadein().play();
fade_percent
of the beginning is faded out.$('example').noise(20000).fadeout().play();
MIDI_note_scale
.binThreshold
controls how close a bin frequency must be to a MIDI note frequency or its harmonic in order to be kept. For example, if binThreshold
is set to 0.1, then a bin frequency must be within 10% of a MIDI note frequency or its harmonic in order to be kept.maxHarmonic
controls how many integer harmonics of MIDI notes in MIDI_note_scale
to include in the output.$('example').noise(n1).times(_.ramp(1,0,n1)).fkey(_.from([48,50,52,53,55,57,59,60]),0.005,6).play(); // noise spectrally filtered to bins matching C major notes 48,50,52,53,55,57,59,60 and their 6 next harmonics
delaySamples
is the base delay in samples. Controls the delay of the flanging effect.depth
is the maximum amount by which the delay is modulated. Controls the depth of the flanging effect.$('example').sine(100,n1).flange(220,110).play(); // flanged whole note sine wave at 100Hz
maximum
, it returns maximum
minus how far above the value was.$('example').sine(100).flipabove(0.2).play(); // wonky sine
minimum
, it returns minimum
plus how far below the value was.$('example').sine(100).flipbelow(0.2).play(); // inverse wonky sine
attackTime
is the attack time in samples. It controls the speed at which the envelope rises. Its default value is 100ms.releaseTime
is the release time in samples. It controls the speed at which the envelope falls. Its default value is 250ms.$('example').noise(n1).times(_.noise(32).scale(0,1).size(n1).follow(n16,n16)).play(); // controlling the amplitude of a whole note of noise, with 32 samples of noise sent through the envelope follower
pieces
pieces.$('example').sine(100).fracture(10).play(); // the sine has shattered into 10 pieces!
$('example').ramp(1000,250,16).ftom(); // 83, 82, 82, 81, 80, 79, 77, 76, 75, 74, 72, 71, 69, 67, 65, 62
scale(-1,1)
.$('example').noise(n2).times(0.1).loud().play(); // remove loud() to hear the difference
threshold
, after attackSamples
have occurred, will be set to 0, until the values go back above threshold
for releaseSamples
.$('example').sine(50).gate(0.1,20,20).play();
1
for every value in the FacetPattern greater than amt
and 0
for all other values.$('example').from([0.1,0.3,0.5,0.7]).gt(0.6); // 0 0 0 1
1
for every value in the FacetPattern greater than or equal to amt
and 0
for all other values.$('example').from([0.1,0.3,0.5,0.7]).gte(0.5); // 0 0 1 1
$('example').sine(100).interp(0.5,_.randsamp('808')).play(); // 50% sine wave; 50% random sample
minimum
and maximum
values in the FacetPattern, then scales every number to the opposite position, relative to minimum
and maximum
.$('example').from([0,0.1,0.5,0.667,1]).invert(); // 1 0.9 0.5 0.333 0
prob
(float 0-1) sets the likelihood of each value changing. amt
is how much bigger or smaller the changed values can be. If amt
is set to 2, and prob
is set to 0.5 half the values could have any number between 2 and -2 added to them.$('example').drunk(128,0.05).jam(0.1,0.7); // small 128 step random walk with larger deviations from the jam
1
for every value in the FacetPattern less than amt
and 0
for all other values.$('example').from([0.1,0.3,0.5,0.7]).lt(0.6); // 1 1 0 0
1
for every value in the FacetPattern less than or equal to amt
and 0
for all other values.$('example').from(0.1,0.3,0.5,0.7]).lte(0.5); // 1 1 1 0
intensity
, which accepts a float between 0 and 1. If direction
is negative, it returns the FacetPattern in reverse.$('example').noise(n8).log(rf()).play(); // each time a different logarithmic curve on the 8th note of noise
$('example').from([60,55,76,100]).mtof(); // 261.63, 220, 659.26, 2637.02
$('example').noise(n4).comb(_.noise(128).scale(0,127).key('c','major').mtos().sort()).play(); // comb filter delayed by sample values in c major on a quarter note of noise
% amt
calculation for each value in the FacetPattern.$('example').from([1,2,3,4]).modulo(3); // 1 2 0 1
chunks
chunks and mutes prob
percent of them. Note: this is intended for use with FacetPatterns with a large enough amount of data to be played back at audio rate. For a similar effect on smaller FacetPatterns, use prob()
.$('example').randsamp('808').mutechunks(16,0.33).play(); // 33% of 16 audio slices muted
$('example').sine(1).times(4000).normalize(); // the gain is undone!
$('example').sine(1).scale(-10,10).normalize(); // works with negative values
$('example').from([1,2,3,4]).prob(0.5).nonzero(); // if 2 and 4 are set to 0 by prob(0.5), the output of .nonzero() would be 1 1 3 3
$('example').from([0,1,2,3]).palindrome(); // 0 1 2 3 3 2 1 0
expo
, where the values at the beginning can be stretched for a significant portion of the FacetPattern, and the values at the end can be squished together. If direction
is negative, returns the FacetPattern in reverse.$('example').sine(100).pow(6.5).play(); // squished into the end
$('example').sine(100).pow(6.5,-1).play(); // squished at the beginning
prob
(float 0-1) sets the likelihood of each value changing.$('example').from([1,2,3,4]).prob(0.5); // 1 0 3 0 first time it runs
$('example').from([1,2,3,4]).prob(0.5); // 0 0 3 4 second time it runs
$('example').from([1,2,3,4]).prob(0.5); // 0 2 3 4 third time it runs
0
for every step in the FacetPattern whose position is not a multiple of resolution
.$('example').drunk(16,0.5).quantize(4); // 0.5241 0 0 0 0.7420 0 0 0 1.0 0 0 0 0.4268 0 0 0
new_min
(float 0-1) and new_max
(float 0-1).$('example').from([0.1,0.2,0.3,0.4]).range(0.5,1); // 0.3 0.4
start
position (between 0 - 1) and a total length in samples.$('example').sine(n1).log(0.9).rangesamps(rf(0,0.875),n8).play(); // plays a different 8th note from the same de-pitched sine wave every time
$('example').silence(n1).iter(128,()=>{this.sup(_.noise(n64).lpf(_.ramp(250,40,20),50).times(_.ramp(1,0,n64)).rangesamps(rf(),n64).fade(0.1),rf())}).play(); // granular synthesis of 128 synthesized kick drums
chunks
chunks and shuffles the chunks around. The probability
argument controls the percentage of chunks to reorder, and it expects a float between 0 and 1. Note: this is intended for use with FacetPatterns with a large enough amount of data to be played back at audio rate. For a similar effect on smaller FacetPatterns, use shuffle()
or fracture
.$('example').randsamp('808').rechunk(16).play(); // 16 slices from the sample in random order
new_size
. If new_size
is larger than the FacetPattern length, no change.$('example').from([1,2,3,4]).reduce(2); // 1 3
original_value
with new_value
in the FacetPattern.$('example').from([42,0,0,36]).replace(0,-1); // 42,-1,-1,36
coefficients
FacetPattern is multiplied by the baseFrequency
to determine the frequency for that bandpass filter.$('example').noise(n16).times(_.ramp(1,0,n16)).resonate(mtof(36),_.ramp(1,20,20),80).play(); // 16th note transient noise burst, resonating at its first 20 harmonics starting at 65.41 Hz (MIDI note C2, mtof(36))
size
argument should be between 0 and 2 for most use cases but can go up to 10.feedback
argument controls feedback in the reverb algorithm. It should be between 0 and 0.98.$('example').randsamp('808').reverb(rf()).play(); // different reverb size for random sample each loop
$('example').ramp(0,1,128).reverse(); // goes from 1 to 0 over 128 values
$('example').from([0.1,0.5,0.9,1.1]).round(); // 0 1 1 1
nth
value in the FacetPattern.$('example').noise(6).saheach(2); // 0.33173470944031735, 0.33173470944031735, 0.17466890792169742, 0.17466890792169742, 0.5601080880419886, 0.5601080880419886
new_size
samples.$('example').noise(1000).size(n1).play(); // upscaling 1000 samples of noise to be 1 whole note long
new_min
to new_max
, with exponent
allowing for nonlinear transformations.exponent
values larger than 1 will emphasize lower numbers more and more. Values less than 1 will emphasize higher numbers more and more.new_min
and new_max
if the FacetPattern is only 1 value long. since you cannot interpolate where the value would fall in the new range, without a larger FacetPattern to provide initial context of the value's relative position. This operation works better with sequences larger than 3 or 4.$('example').sine(10,100).scale(0,1); // unipolar signal
amt
gets wrapped to values between -1 and 1, since you can't shift more than 100% left or 100% right.$('example').from([1,2,3,4]).shift(-0.5); // 3 4 2 1
prob
argument controls the percentage of data to shuffle. It should be a float between 0 and 1. A prob
of 1 means 100% of the elements will shuffle; a prob
of 0.5 means 50% of the elements will shuffle, etc.$('example').from([1,2,3,4]).shuffle(); // first time: 3 2 1 4
$('example').from([1,2,3,4]).shuffle(); // second time: 1 3 4 2
$('example').spiral(16,random(1,360)).skip(0.95); // new pattern 5% of the time when this command runs
depth
controls how many slew values exist between each value. up_speed
and down_speed
control how long the slew lasts: at 0, the slew has no effect, whereas at 1, the slew occurs over the entire depth
between each FacetPattern value.$('example').from([0,0.5,0.9,0.1]).slew(25,0,1) // the first three numbers will jump immediately because upwards slew is 0. then it will slew from 0.9 to 0.1 over the course of the entire depth range
$('example').noise(64).smooth(); // less noisy
$('example').noise(128).sort(); // ascending values originally from noise
amt
value of 0.5 will play at half speed. An amt
value of 2 will play at double speed.$('example').randsamp('808').speed(0.2); // slow sample
$('example').randsamp('808').speed(1.5); // fast sample
amt
(float 0-1) sets the likelihood of each value being sampled and held.$('example').noise(n4).sticky(0.98); // quarter note of "sticky" noise
num_samples
samples.$('example').sine(1000,n2).stretchto(n1).play(); // 1000Hz sine wave originally a half note long, stretched to a whole note
_number_of_repeats_
identical chunks of data, calculated from the start_pos
and end_pos
values, which represent two relative positions between 0 and 1 in the input FacetPattern's data. After all the repeats have been appended to it, the FacetPattern is resized back to its original length.$('example').sine(100).stutter(16,rf(),rf()).size(n1).play(); // copies a unique sub-section of the same sine wave 16 times
percentage
% values in it.$('example').phasor(1).size(50).subset(0.3); // originally 50 values long, now 0.02 0.08 0.50 0.58 0.62 0.700 0.76 0.78 0.92
length
values long. If length
is longer than the FacetPattern, return the whole FacetPattern.$('example').from([0,1,2,3]).truncate(2); // now 2 values long
$('example').from([0,1,2,3]).truncate(6); // still 4 values long
note
.note
values: "A", "A#", "B", "C", "C#", "D", "D#", "E", "F", "F#", "G", "G#"binThreshold
controls how close a bin frequency must be to the supplied note's harmonics in order to be kept. For example, if binThreshold
is set to 0.1, then a bin frequency must be within 10% of a harmonic in the supplied note
in order to be kept.$('example').noise(n1).tune('c',0.0001).play(); // tuning a whole note of noise to c
$('example').from([1,2,3,0,0.4,2]).unique(); // 1 2 3 0 0.4
prob
(float 0-1) sets the likelihood of each position changing. amt
controls how many steps the values can move. If amt
is set to 10, and prob
is set to 0.5 half the values could move 10 positions to the left or the right.$('example').from([0,1,2,0,1,0.5,2,0]).walk(0.25, 3);
max
so their output continues at min
. If the values are twice greater than max
, their output continues at min
again. Similar for values less than min
, such that they wrap around the min/max thresholds.max
, then the first argument will be used to create the min
and max
, centered around 0. For instance, wrap(0.3) == wrap(-0.3,0.3)
$('example').sine(100).add(-0.1).wrap(0.2,0.5).play();
When a modulator takes a FacetPattern or an array as an argument, it uses that pattern to dynamically change its behavior over time, affecting the output in a more complex way than if a single number were supplied. For example, with the command $('example').noise(16).add(4)
, all 16 output values will be between 4 and 5, because 4 is added to every noise value, and noise values are between 0 and 1 by default. But with the command $('example').noise(16).add(_.ramp(0,4,16))
, the output values will ramp from between 0-1 at the beginning to between 4-5 at the end, since the FacetPattern that is being added is a ramp of values starting at 0 and ending at 4.
match_sizes
is false, the output FacetPattern will be the longer pattern's length, and the "missing" values from the shorter pattern will be set to 0. If match_sizes
is true, both FacetPatterns will be made the same size before the calculations occur.$('example').randsamp('808').add(_.randsamp('808')).play(); // two random samples each loop
cutoffPattern
and q
to the FacetPattern.$('example').noise(n1).bpf(1000,6).times(0.1).play(); // band-passed noise
$('example').noise(n1).bpf(_.sine(4).scale(10,1000)).play(); // 4-cycle LFO modulating the bandpass cutoff between 10 and 1000 Hz
_delaySamplesPattern_
parameter is equal to 10ms by default and specifies the number of samples to delay the input signal. The feedforward
parameter controls the amount of the input signal that is fed directly to the output. The feedback
parameter controls the amount of feedback applied to the delay, allowing the delayed signal to be mixed back into the input.feedback
and feedforward
values are clamped between 0 and 0.98.$('example').noise(n4).comb(ms(10),0.5,0.5).play();
numberOfBitsPattern
controls the bit depth for the output pattern. To hear the effect, the values need to be integers between 1 and 8. Lower values produce more drastic results.downsamplingPattern
controls the fator by which to reduce the sample rate. Values need to be integers greater than 1. Higher values produce more drastic results.$('example').sine(100).crush(2).play(); // redux on the sine wave
$('example').sine(100,n1).crush(_.ramp(8,1,8)).play(); // ramping bit depth on 100Hz sine wave from 8 bits to 1
$('example').sine(100,n1).crush(_.ramp(8,1,8),_.noise(16).scale(1,40)).play(); // ramping bit depth on 100Hz sine wave from 8 bits to 1, and dynamically changing the downsampling amount between 1 and 40 samples
delaySamplesPattern
samples. The feedback
parameter controls the amount of feedback applied to the delay, allowing the delayed signal to be mixed back into the input.feedback
value is 0.975.$('example').randsamp('808').delay(random(1700,10000)).play();
match_sizes
is false, the output FacetPattern will be the longer pattern's length, and the "missing" values from the shorter pattern will be set to 0. If match_sizes
is true, both FacetPatterns will be made the same size before the calculations occur.$('example').sine(1).divide(_.from([0.5,0.25,0.1,1]));
minFreqPattern
and maxFreqPattern
.minFreqPattern
and maxFreqPattern
by sending a truthy value for invertMode.
$('example').noise(n16).ffilter(200,2000).play(); // noise between 200Hz - 2000Hz
gateThresholdPattern
. The magnitudes of each FFT bin are normalized from 0 - 1. A gateThresholdPattern
of 0 will pass every bin, and a gateThresholdPattern
of 1 will mute every bin.gateThresholdPattern
.$('example').noise(n16).fgate(0.7).play(); // try experimenting with different threshold values
lookupPattern
. Similar to ichunk()
but using FFT. The lookupPattern
maps the current spectral bins to new positions. The length of the lookupPattern determines the number of frames in the resynthesized signal.$('example').randsamp('808').flookup(_.ramp(1,0,SAMPLE_RATE)).play().once(); // backwards 808 sample, ramping from relative position 1 to 0
shiftAmountPattern
values lower than 0 will cause the bottom to wrap the top, and the rest of the spectrum moves downwards. shiftAmountPattern
values higher than 0 will cause the top of the spectrum to wrap to the bottom, and the rest of the spectrum moves upwards.$('example').sine(100).fshift(0.04).play(); // try experimenting with different shift values
tiltAmountPattern
should be normalized to values between -1 and 1, where -1 represents a full counter-clockwise rotation and 1 represents a full clockwise rotation.$('example').sample('808/808-Clap03').ftilt(_.ramp(rf(),rf(),100)).play(); // split the clap sample into 100 frequency bands and disperse them randomly in time
numHarmonicsPattern
harmonics to the input signal.$('example').sine(10).harmonics(200).play(); // 10Hz sine wave with 200 harmonics added on top
$('example').sine(10,n1).harmonics(_.ramp(0,200,200)).play(); // ramping up from 0 harmonics on the 10Hz wave to 200 harmonics
cutoffPattern
and q
to the FacetPattern.$('example').noise(n1).hpf(2000,6).times(0.1).play(); // high-passed noise
$('example').noise(n1).hpf(_.sine(4).scale(10000,20000)).play(); // 4-cycle LFO modulating the high pass cutoff between 10000 and 20000 Hz
cutoffPattern
and q
to the FacetPattern.$('example').noise(n1).lpf(1000,6).times(0.1).play(); // low-passed noise
$('example').noise(n1).lpf(_.sine(4).scale(10,2000)).play(); // 4-cycle LFO modulating the high pass cutoff between 10 and 2000 Hz
pitchShiftPattern
values between 0 and 1 will lower the pitch; e.g. a value of 0.5 will shift it down an octave. Values higher than 1 will increase the pitch; e.g. a value of 2 will be an octave higher.$('example').sine(100).shift(rf(0.5,2)); // sometimes lower pitch, sometimes higher pitch
$('example').sine(100).pitch(_.noise(16).scale(0.5,2)).play(); // pitch shifts a 100Hz wave at 16 places, sometimes lower and sometimes higher
shiftAmountPattern
values less than 1 will shorten its overall length; values greater than 1 will increase its length. chunksPerSecondPattern
is the number of chunks that the timestretching algorithm will generate per second. Smaller values will produce more discrete repetitions; larger values will produce more of a bitcrushing, harmonic distortion effect. The largest chunksPerSecondPattern
value is SAMPLE_RATE / (SAMPLE_RATE * 0.002)
, which is 500 a sample rate of 44100.$('example').sine(100,n4).stretch(4).play(); // stretching a quarter note sine wave to last a whole note
$('example').noise(n1).stretch(_.ramp(0.125,4,16)).play().once(); // stretching a whole note of noise over 16 ramped values, starting at 8x faster and ending at 4x slower
match_sizes
is false, the output FacetPattern will be the longer pattern's length, and the "missing" values from the shorter pattern will be set to 0. If match_sizes
is true, both FacetPatterns will be made the same size before the calculations occur.$('example').sine(100).subtract(_.cosine(50)).play();
gainPattern
values will create more intense distortion.$('example').phasor(1,20).times(10).tanh(6); // 0 0.995 0.9999 0.99999996 0.9999999999 0.999999999999 0.9999999999999996 1 1 1 1 1 1 1 1 1 1 1 1 1
$('example').sine(100).tanh(_.ramp(0,100,100)).play(); // ramping tanh distortion up on a 100Hz sine wave
match_sizes
is false, the output FacetPattern will be the longer pattern's length, and the "missing" values from the shorter pattern will be set to 0. If match_sizes
is true, both FacetPatterns will be made the same size before the calculations occur.$('example').sine(50).times(_.sine(50)).play();
match_sizes
is false, the output FacetPattern will be the longer pattern's length, and the "missing" values from the shorter pattern will be set to 0. If match_sizes
is true, both FacetPatterns will be made the same size before the calculations occur.$('example').from([1,0,1,0]).and(_.from([0,1])); // 0 0 1 0
$('example').sine(1).append(_.phasor(1)).append(_.from([1,2,3,4]));
iterations
iterations. The output is a value between 0 and 1, which corresponds to how stable or unstable that particular point is in the complex number plane.$('example').sine(n1).chaos(_.drunk(n1,0.01)).play();
$('example').randsamp('808').convolve(_.randsamp('808')).play(); // convolving random samples
match_sizes
is false, the output FacetPattern will be the longer pattern's length, and the "missing" values from the shorter pattern will be set to 0. If match_sizes
is true, both FacetPatterns will be made the same size before the calculations occur.$('example').sine(1).equals(_.sine(2));
FacetPattern.length
windowed chunks (to avoid audible clicks). Loops through every value of FacetPattern
as a lookup table, determining which ordered chunk of audio from the input sequence it corresponds to, and appends that window to the output buffer.$('example').randsamp('808').ichunk(_.ramp(rf(),rf(),256)).play(); // play 256 slices between two random points of a random sample... timestretching :)
$('example').sine(1).interlace(_.phasor(1,20));
$('example').from([1,2,3,4]).map([11,12,13,14]); // 11 11 11 11
$('example').from([1,2,3,4]).scale(30,34).map(_.from([31,31.5,32,32.5])); // 31 31.5 32.5 32.5
match_sizes
is false, the output FacetPattern will be the longer pattern's length, and the "missing" values from the shorter pattern will be set to 0. If match_sizes
is true, both FacetPatterns will be made the same size before the calculations occur.$('example').from([1,0,1,0]).or(_.from([0,1])); // 1 0 1 1
$('example').noise(1024).sieve(_.sine(10)); // sieving noise with a sine wave into the audio rate :D
position
between 0 and 1.$('example').randsamp('808').splice(_.noise(n16),0.5).play(); // inserts a 16th note of noise halfway through the random sample
startPositionPattern
value can be any value between 0 and 1, or an array, or a FacetPattern. It controls the relative position(s) in the input FacetPattern to begin superposing FacetPattern
. The maxFrameSize
value specifies the farthest sample value from the first FacetPattern, which would be equal to a startPosition
of 1.$('example').silence(n1).sup(_.randsamp('808'),0,n1).sup(_.randsamp('808'),0.5,n1).play(); // superpose two samples at the 0% and 50% points through each loop
carrierPattern
.carrierPattern
.$('example').seq('808/* 808/* 808/* 808/* 808/* 808/* 808/* 808/*').vocode(_.square([220,440,110,110])).play(); // vocode sequence of random 808 sample with simple square wave pattern
For more examples, refer to the examples/this.md
file.
command
.this
(see example).$('example').randsamp('808').mix(0.5,()=>{this.reverse().speed(2).echo(8).speed(10)}).play();
this
(see example).i
, referring to the current iteration number starting at 0, is also available for use in commands.iters
, referring to the total number of iterations, is also available for use in commands.this.original_data
, referring to the original data before any iterations are proessed, is also available for use in commands.$('example').randsamp('808').iter(8,()=>{this.delay(ri(1,2000))}).play(); // 8 delay lines between 1 and 2000 samples
commands
parameter is an array where each entry is a function. Each command
is applied to a copy of the original input data, and the results are combined back together afterwards. The final output is normalized to have the same maximum value as the original input data.$('s').noise(n4).scale(-1,1).allpass(347).allpass(113).allpass(37).parallel([()=>{this.delay(1687,0.999)},()=>{this.delay(1601,0.999)},()=>{this.delay(2053,0.999)},()=>{this.delay(2251,0.999)}]).play().full(); // schroeder reverb on a quarter note of noise
sometimes(1,()=>{})
method. See sometimes()
below for more details.$('example').noise(n1).run(()=>{if(bars%2==0){this.tune('c')}else {this.tune('g')}}).play(); // alternating c and g whole notes made from tuned noise
sequencePattern
across the loop. sequencePattern
can either be a string or a FacetPattern composed of strings.*
at the end of a member of the sequencePattern
string will select a random sample from that directory (see examples)._
in a sequencePattern
specifies to insert silence instead of a sample.commands
will run on each sample as it is superposed onto the output pattern.$('example').seq('kicks/* hats/* snares/003 hats/003').play(); // random kick, random hat, snares/003, hats/003
$('example').seq(_.from(['kicks/003', 'hats*', 'snares/003', 'hats/*']).dup(choose([1, 3, 5, 7])).palindrome().rechunk(8, 0.5), () => {this.log(rf()).delay(ri(n128, n16))}).full().play() // example using commands to proess each sample, and using a FacetPattern as the sequencePattern
;num_slices
slices, and for prob
percent of those slices, runs command
, appending all slices back together. You can refer to the current slice of the algorithm via the reserved word: this
(see example).s
, referring to the current slice number starting at 0, is also available for use in commands.num_slices
, referring to the number of slices, is also available for use in commands.slices()
method applies a very short fadeout on each slice to prevent any clicks that might occur from any code running on each slice. This behavior can be turned off by including a falsy fade_mode
value.$('example').randsamp('808').slices(32,()=>{this.fft().shift(random()).ifft()}).play();
command
only some of the time, at a probability set by prob
.command
must start with the reserved word: this
(see example).$('example').phasor(1).sticky(0.5).scale(40,80).sometimes(0.5,()=>this.reverse());
command
on a subrange of the FacetPattern, specified by min
and max
.min
and max
should be floats between 0 and 1. They are relative values, so a value of 0 means the beginning of the pattern, and a value of 1 means the end of the pattern.command
must start with the reserved word: this
(see example).$('example').tri(200).subrange(0.33,0.66,()=>{this.times(0.25)}).play(); // quieter in the middle third
NOTE: 2D images are expected to have sizes that are a perfect square. This means that the width and height of the produced image are integers. Some methods will produce distorted output or throw errors if you try to run them with patterns that are not perfect squares.
centerX
and centerY
are the x,y coordinates of the center of the circle.radius
controls the radius of the circle.value
is brightness value for the circle normalized between 0 - 1.fillMode
(0 or 1) controls whether the inside of the shape is filled in with value
or ignored. Default is no fill.$('example').silence(1000000).circle2d(100,100,100,1).saveimg('example_circle'); // white circle in a 1000x1000 image
$('example').silence(1000000).circle2d(100,100,100,1,1250,800).saveimg('example_circle',[1,1,1],1250,800); // white circle in a 1250x800 image
delayX
and delayY
are the delay amounts in the x and y directions. Positive values move right/down; negative values move left/up.intensityDecay
is a value between 0 and 1 that controls how much the intensity of the data decays with each delay step. A value of 0.5 means the intensity is halved with each delay step.$('example').silence(1000000).circle2d(500, 500, 250, 1).delay2d(20, 20, 0.85).saveimg('delay2d').once(); // circle echoing down-left
coordinates
parameter is an array of x and y coordinates for the vertices of the polygon. The array length must be divisible by 2.fillValue
parameter is the value used to fill the lines of the polygon.$('example').silence(10000).draw2d([0, 0, 99, 99], 1).saveimg('draw2d').once(); // draw a line from (0, 0) to (99, 99) with a fill value of 1
iterations
parameter determines how many times the algorithm is applied to the pattern.prob
parameter is the probability that a pixel's value will spread to its neighbors.threshold
parameter is a value that a pixel's value is compared to in order to determine whether it should spread. The default value is 0.mode
parameter determines how the threshold is applied. If mode
is 0 (the default), a pixel's value will spread if it is less than the threshold. If mode
is 1, a pixel's value will spread if it is greater than the threshold.$('example').noise(1000000).grow2d(5, 0.5, 0.2, 1).saveimg('grow2d').once(); // apply the growth algorithm to a noise pattern
brightness_data
is a FacetPattern that should be normalized between 0 and 1. It controls how bright the corresponding pixels will be.xCoords
and yCoords
are FacetPatterns that allow the user to control the x,y position of the pixels in brightness_data
.$('example').sine(1).size(10000).scale(0,1).layer2d(_.noise(10000), _.ramp(0,100,128), _.ramp(0,100,128)).saveimg('example').once(); // layers a ramp from 0,0 to 100,100 over a sine wave background
chunks
chunks in 2D space and mutes prob
percent of them.num_chunks
must have an integer square root, e.g. 9, 16, 25, 36.$('example').sine(0.3,1000).scale(0,1).mutechunks2d(36,0.5).saveimg('example').once();
$('example').silence(1000000).iter(128,()=>{this.rect2d(ri(0,1000), ri(0,1000), ri(10,100), ri(10,100), rf())}).palindrome2d().invert().saveimg('palindrome2d',[_.ramp(rf(),rf(),1000000),_.ramp(rf(),rf(),1000000),_.ramp(rf(),rf(),1000000)]); // 128 rectangles in a 2d palindrome
chunks
chunks in 2D space and shuffles the chunks around.num_chunks
must have an integer square root, e.g. 9, 16, 25, 36.$('example').sine(0.3,1000).scale(0,1).rechunk2d(36).saveimg('example').once();
topLeftX
and topLeftY
are the x,y coordinates of the top-left corner of the rectangle.rectWidth
and rectHeight
control the size of the rectangle.value
is brightness value for the rectamgle normalized between 0 - 1.fillMode
(0 or 1) controls whether the inside of the shape is filled in with value
or ignored. Default is no fill.$('example').silence(1000000).rect2d(0,0,100,100,1).saveimg('rect2d'); // 100x100 white square in top-left corner of 1000x1000 image
angle
degrees around a center point, as if it were suspended in 2D space.width
and height
arguments are optional. They default to the square root of the FacetPattern's length. Other values will rotate the data in a different way, around a different center point.$('example').sine(1).scale(0,1).size(512*512).rotate(35).saveimg('example').once(); // rotates a sine wave background 35 degrees
img/
directory or a sub-directory. If a sub-directory is specified in the filepath
argument and it doesn't exist, it will be created.rgbData
argument is optional. Without it, the image will be greyscaled. If rgbData
is included, it should be an array containing three FacetPatterns normalized to between 0 and 1, representing the R, G, and B amounts. The FacetPattern data will be multipled by the three rgbData
patterns to create colored pixels in the image. Values between 0 and 1 will be mapped onto RGB values 0-255. $('example')
// create black background
.silence(512 * 512)
// add the 512 brightest-possible pixels (1s) that will be used to create a circle
.layer2d(_.from(1).size(512),
// the circle x coordinates move from left edge (0) to right edge (512) and back
_.ramp(0, 511, 512)
.palindrome(),
// the circle y coordinates, pt. 1: create a half-circle out of 512 values, defaulting to between 0 and 1
_.circle(1)
.size(512)
// the circle y coordinates, pt. 2: append another half-circle out of 512 values, scaled between -1 and 0 and inverted
.append(_.circle(1)
.size(512)
.scale(-1, 0)
.invert())
// scale the y coordinates so they move between 0 and 511
.scale(0, 511))
.saveimg('circle',
// use 3 random ramps, 1 for each RGB channel, to create a gradient in the circle's pixels
[_.ramp(rf(),rf(),512),_.ramp(rf(),rf(),512),_.ramp(rf(),rf(),512)]
)
.once();
img/
directory named fileName.png
, with the FacetPattern's spectrogram.$('example').noise(n1).ffilter(_.ramp(0,NYQUIST/2),_.ramp(NYQUIST,NYQUIST/2)).savespectrogram('mytri'+Date.now()).once();
xAmt
pixels to the left/right, and by yAmt
pixels up/down.$('example').noise(100*100).prob(0.001).iter(4,()=>{this.mix(0.5,()=>{this.shift2d(0,1)})}).saveimg('shift2d').once(); // slides all the pixels up 4
size
.size
must be between 0 and 1. The new pattern will be a smaller 2D image of the input, surrounded by padding of black pixels (0s).$('example').noise(10000).size2d(0.5).saveimg('size2d'); // 100 x 100 image with a square of noise in the center
num_slices
slices in a 2D grid, and for each slice, runs command
, appending all slices back together. You can refer to the current slice of the algorithm via the reserved word: this
(see example).s
, referring to the current slice number starting at 0, is also available for use in commands.num_slices
, referring to the number of slices, is also available for use in commands.slices2d()
method does not apply any fading on each slice. Each slice is processed exactly as-is.command
is a function that is applied to each slice. The function is converted to a string and any reference to this
is replaced with current_slice
to ensure the function operates on the correct data.num_slices
. This ensures that the slices form a square grid.$('example').noise(1000000).slices2d(36,()=>{this.times(rf())}).saveimg('slices2d').once();;
stretchFactor
parameter determines how much the pattern is stretched horizontally before the IFFT is applied. The default value is 1, which means no stretching. Each row of the pattern is then stretched by the stretchFactor
. This is done by linearly interpolating between each pair of consecutive values in the row.$('example').silence(1000000).iter(16,()=>{this.circle2d(ri(0,999),ri(0,999),ri(0,100),rf())}).spectral().play().full().once(); // 16 circles randomly dispersed and superposed around the audio spectrum
x1
, y1
, x2
, y2
, x3
, and y3
define the triangle's position in the 2d space.value
is brightness value for the triangle normalized between 0 - 1.fillMode
(0 or 1) controls whether the inside of the shape is filled in with value
or ignored. Default is no fill.$('example').silence(1000000).tri2d(ri(0,1000), ri(0,1000), ri(0,1000), ri(0,1000), ri(0,1000), ri(0,1000),1).saveimg('tri2d'); // one random white triangle in a 1000x1000 image
warpX
and warpY
are the x and y coordinates of the warp point.warpIntensity
should be a float between 0 and 1 and controls the intensity of the warp effect.$('example').silence(1000000).circle2d(100, 100, 100, 0.2).delay2d(20, 20, 0.98).iter(4,()=>{this.warp2d(ri(0,999),ri(0,999),rf())}).saveimg('warp2d'); // echoing circles warped to a random position in the 2d space
percentage
should be a float between 0 and 1 and controls the percentage of pixels to move.x
and y
control the maximum distance that a pixel can move. They should be non-negative integers (but random walks occur in both left/right AND up/down),mode
controls the behavior of pixels at the boundary. A value of 0 is "wrap" mode; values move to the other side. A value of 1 is "fold" mode; values get folded back by however many they exeeded the boundary. A value of 2 is "clip" mode; values get stuck at the boundary.$('example').silence(1000000).rect2d(950, 950, 50, 50, 1).walk2d(0.5, 10, 10, 0).saveimg('walk2d'); // white square in bottom corner, 50% random walked by 10px in all 4 directions