Skip to main content

Global Settings

A global setting is a parameter that applies to the entire Mercury environment and all the instruments that are created within it. The global settings are adjust with the set keyword.

For detailed explanation of the syntax see: Syntax and set under Actions.

set <setting-name> value1 value2 ... value-n
note

Some settings are different between Mercury4Max and the MercuryPlayground

tempo​

Change the global tempo in Beats Per Minute (BPM), counted in quarter-notes. The second argument sets a ramptime in milliseconds or fraction to gradually change the tempo over the provided amount of time.

arguments

  • Number+ -> The BPM as a positive number
  • Number/Fraction -> The ramptime (optional/experimental, default=0)
set tempo 128

set tempo 80 5000
warning

The tempo ramp change is experimental and may lag/glitch depending on the code you have

scale​

Set the scale in a 12-TET system for which all the played notes will be mapped to. An optional second argument sets the tone-center (or root) for the scale. The default scale and root is chromatic c.

arguments

  • Name -> the scale name (default=chromatic)
  • Name -> the root (optional, default=c)
set scale major D#

set scale minor_harmonic Eb
warning

The scale names can differ slightly between Mercury4Max and the MercuryPlayground

Currently available scales are:

"chromatic" :            [0, 1, 2, 3, 4, 5, 6, 7, 8, 9,  10, 11],
"major" :                [0, 0, 2, 2, 4, 5, 5, 7, 7, 9,  9,  11],
"minor" :                [0, 0, 2, 3, 3, 5, 7, 7, 8, 8,  10, 10],
"minor_melodic" :        [0, 0, 2, 3, 3, 5, 7, 7, 9, 9,  11, 11],
"minor_harmonic" :       [0, 0, 2, 3, 3, 5, 7, 7, 8, 8,  11, 11],
"dorian" :               [0, 0, 2, 3, 3, 5, 5, 7, 7, 9,  10, 10],
"phrygian" :             [0, 1, 1, 3, 3, 5, 7, 7, 8, 8,  10, 10],
"lydian" :               [0, 0, 2, 4, 4, 6, 6, 7, 7, 9,  11, 11],
"myxolydian" :           [0, 0, 2, 4, 4, 5, 5, 7, 7, 9,  10, 10],
"locrian" :              [0, 1, 1, 3, 3, 5, 6, 6, 8, 8,  10, 10],
"hungarian" :            [0, 0, 2, 3, 3, 6, 6, 7, 8, 8,  11, 11],
"gypsy" :                [0, 1, 1, 4, 4, 5, 5, 7, 8, 8,  11, 11],
"major_neapolitan" :     [0, 1, 1, 3, 3, 5, 7, 7, 8, 8,  11, 11],
"minor_neapolitan" :     [0, 1, 1, 3, 3, 5, 7, 7, 9, 9,  11, 11],
"hexatonic" :            [0, 0, 2, 2, 4, 4, 6, 6, 8, 8,  10, 10],
"hexatonic_blues" :      [0, 0, 2, 2, 4, 4, 6, 6, 7, 7,  10, 10],
"hexatonic_prometheus" : [0, 0, 2, 2, 4, 4, 6, 6, 9, 9,  10, 10],
"major_pentatonic" :     [0, 0, 2, 2, 4, 4, 7, 7, 7, 9,  9,  9],
"minor_pentatonic" :     [0, 0, 3, 3, 3, 5, 5, 7, 7, 10, 10, 10]

The naming convention and offsets for the roots are:

-6 gb Gb ges Ges
-5 g  G
-4 g# G# gis Gis
-4 ab Ab as  As
-3 a  A
-2 a# A# ais Ais
-2 bb Bb bes Bes
-1 b  B 
-1 cb Cb ces Ces
+0  b# B# bis Bis
+0  c  C
+1  c# C# cis Cis
+1  db Db des Des
+2  d  D
+3  d# D# dis Dis
+3  eb Eb es  Es
+4  e  E
+4  fb Fb fes Fes
+5  e# E# eis Eis
+6  f  F

scalar​

Mercury4Max only

A scalar transposition. All the current notes are shifted up or down a certain amount of semitones but also remap the notes to the set scale. This is different from transposing the scales because it preserves the original scale.

arguments

  • Int -> scalar to shift notes by (default=0)
set scalar 2

randomSeed​

Set the random seed as an integer for the psuedo-random number generators used in all list-functions across the environment. There is no such thing as true randomness, the random numbers are generated by a deterministic process. Once you know the "seed" that initializes this process, you can reproduce the output of the algorithm over and over. Setting the randomSeed to a fixed integer will make sure random values keep the same sequence every time you re-evaluate the code. A value of 0 sets to unpredictable seeding (which is the default).

arguments

  • Int+ -> the seed for the psudeorandom number generators (default=0)
set randomSeed 31415
set randomSeed 1618
Mercury4Max

The seed can only be set once in Mercury4Max every time you evaluate. The last value will take effect for all list functions.

set randomSeed 31415 
// ^^^ will be overwritten by 1618 before random() call
list randomValues random(10 0 100)
// ^^^ the random() will use the seed from below
set randomSeed 1618
// ^^^ 1618 overwrites 31415
MercuryPlayground

The seed can be reconfigured between lines of code

set randomSeed 31415 
// ^^^ will not be overwritten
list randomValues random(10 0 100)
// ^^^ the random() uses the seed 31415
set randomSeed 1618
// ^^^ a new seed is set for other functions below

volume​

Set the global volume in floating-point amplitude for all instruments across the entire environment. Additional ramptime in milliseconds or fraction can be provided to create fade-in/fade-out or smooth transitions.

arguments

  • Float -> attenuate the total volume of all instruments (default=1)
  • Divison/Int+ -> ramptime in milliseconds or fractions (optional, default=0)
set volume 0.5 5000
set volume 0.4 2/1

highPass​

Set the global highPass filter cutoff in Hz for all instruments across the entire environment. Additional ramptime in milliseconds can be provided to create smooth transitions from one value to another. The default value is 5 Hz to remove DC offsets.

arguments

  • Float+ -> cutoff frequenzy in Hertz
  • Divison/Int+ -> ramptime in milliseconds or fraction (optional, default=5)
set highPass 900 5000
set highPass 800 2/1

Alias: hipass

lowPass​

Set the global low-pass filter cutoff in Hz for all instruments across the entire environment. Additional ramptime in milliseconds can be provided to create smooth transitions from one value to another. The default value is 18000 Hz.

arguments

  • Float+ -> cutoff frequenzy in Hertz
  • Divison/Int+ -> ramptime in milliseconds or fraction (optional, default=1)
set lowPass 900 5000
set lowPass 800 2/1

Alias: lopass

beatRepeat​

Mercury4Max only

A beatrepeating effect (sometimes called stutter) that continuously repeats a section of the entire sound that was last played. The repating interval is determined in fractions (1/4, 3/16, etc). It immediately starts repeating at the moment of evaluating the code, so timing is key! You can switch to a different section of the beatrepeat recording with optionally adding a second argument. Maximum recording length is 8 seconds (2x 4/4 bars at 60bpm, 1x 4/4 bar at 120bpm).

arguments

  • Fraction -> beatrepeat time interval in fraction
  • Fraction -> beatrepeat offset time in fraction
set beatRepeat 1/4

Alias: stutter

osc​

Mercury4Max only

Set the ip-address, in-port and out-port number for the network to transmit OSC-messages using UDP. Default settings are 8000 (in-port), 9000 (out-port), localhost (127.0.0.1) (ip).

arguments

  • Int+ -> receiving port (default=8000)
  • Int+ -> sending port (default=9000)
  • Name -> ip-address in the form of xxx.xxx.xxx.xxx or localhost (default=localhost)
// set everything to default
set osc default

// apply in-port, out-port and server-ip in one line
set osc 8000 9000 127.0.0.1

// apply settings separately
set osc ip 127.0.0.1
set osc in 8000
set osc out 9000

midi​

Mercury4Max only

With the midi object you can get the available devices (ports) that you can use to send midi notes to with a new midi instrument.

set midi getPorts
// prints the available ports to the console

midiClock​

Mercury4Max only

Output midiClock sync messages to sync an external device to the tempo of Mercury. The device name can have spaces. Use the getports argument to automatically open the console and view the different portnames. Use the off message or silence or alt + . to stop the syncing and send a stop message.

arguments

  • Name -> getPorts, the midi portname or off (default=off)
set midiClock getPorts
// returns the port names in console and automatically opens the console

set midiClock midiPortName
// turn the clock on and 
// outputs clock-sync to midiport of that name

set midiClock off
// turn the clock off (default)

click​

Mercury4Max only

Enable a clicktrack/metronome sound to allow you to easily play along with the music. You can adjust the interval for the low pitch separately from the interval of the accent. The accent sounds an octave higher. You can also adjust the channel output for the click so you can hear it separately from the main output. Reset the settings with default.

arguments

  • Name -> on, off or default (default=off)
set click on
// turn the click on/off (default=off)

set click freq 1000
// set the base frequency for the click (default=900)

set click length 0.9
// adjust the length of the tone (default=0.65)

set click time 1/8
// set the base interval for the low pitch (default=1/4)

set click accent 1/2
// set the accent interval for the high pitch (default=1/1)

set click gain 0.8
// adjust the volume of the click sound (default=0.75)

set click out 3 4
// set the output channel(s) for the click, can be mono or stereo (default=1 2)

set click default
// reset all attributes to the default settings

crossFade

Mercury Playground only

Set the crossfade for the engine to fade from the previous running code to the newly evaluated code in x-amount of milliseconds or fractions. This feature is only applicable to the MercuryPlayground browser version because it works differently under the hood than the Max version.

arguments

  • Fraction/Int+ -> crossfade time in milliseconds or fraction (default=250)
set crossFade 1000
set crossFade 2/1

samples

Mercury Playground only

With set samples you can load samples in the playback buffer so they can be used with the sample, loop and polySample instruments. There are multiple ways to add samples, for example using a url from a freesound.org preview file, or by using a soundfile from a raw github content link.

set samples can only be called once in the code-file, so it is important to add all the sounds you want in that single line. This can lead to a very long line of code, so there are some ways to work around this. For example it is possible to input a .json file that consists of name:url pairs for the soundfiles.

tip

You don't have to load the samples every time you evaluate, once at the beginning of a session is enough. So after loading you can comment the line and the samples are available until you refresh/restart the browser.

Below you can read various use-case scenarios:

single soundfile​

freesound​

Load a single soundfile from for example freesound.org. Go to the site and find the file you like, right-click on the file and click 'inspect' (in chromium browser). Search for the cdn.freesound.org/previews url in the html, this is the soundfile that needs to be copy-pasted. By default the name of the soundfile will be the name you use in the code.

// only evaluate set samples once, when loading is done you can comment the line
set samples 'https://cdn.freesound.org/previews/145/145778_2101444-lq.mp3'

new sample '145778_2101444-lq' time(1/4)

You can load a single soundfile and also adjust the name by creating a list. The first item in the list is the name you want to give the sample. The second item in the list is the url to the file.

// only evaluate set samples once, when loading is done you can comment the line
set samples [ psykick 'https://cdn.freesound.org/previews/145/145778_2101444-lq.mp3' ]

new sample psykick time(1/4)

github​

Load a single soundfile from a source like github by locating the file in the repository. For example the url looks like this: https://github.com/tmhglnd/mercury/blob/master/mercury_ide/media/samples/drums/kick/kick_house.wav. Now construct a new url starting with https://raw.githubusercontent.com/ then past the user/repository/branch after this but remove the /blob! For example the result should look like this: https://raw.githubusercontent.com/tmhglnd/mercury/master/mercury_ide/media/samples/drums/kick/kick_house.wav

set samples [ housekick 'https://raw.githubusercontent.com/tmhglnd/mercury/master/mercury_ide/media/samples/drums/kick/kick_house.wav' ]

new sample housekick time(1/4)

multiple soundfiles​

lists​

There are two ways to load a larger collection of samples. The first option is by creating variables of lists that store the name and url combination. Then in one single set samples line you can add all the names of the lists

list s1 [ snare_short 'https://cdn.freesound.org/previews/671/671221_3797507-lq.mp3' ]
list s2 [ psykick 'https://cdn.freesound.org/previews/145/145778_2101444-lq.mp3' ]
list s3 [ hat_short 'https://cdn.freesound.org/previews/222/222058_1676145-lq.mp3' ]
set samples s1 s2 s3

new sample psykick time(1/4)
new sample snare_short time(1/16) play(euclid(7 3)) gain(0.5)
new sample hat_short time(1/4 1/8) gain(1.3)

json​

The second option is creating a .json file. This file can be stored on the computer or on for example github. The json file is structured in the following way: { "sample-name" : "url-to-file" }. When clicking add sounds the json file can be selected instead of a soundfile and it will be used to load the samples.

{
    "snare_short" : "https://cdn.freesound.org/previews/671/671221_3797507-lq.mp3",
    "psykick" : "https://cdn.freesound.org/previews/145/145778_2101444-lq.mp3",
    "hat_short" : "https://cdn.freesound.org/previews/222/222058_1676145-lq.mp3"
}
set samples <url-to-raw-json-file>

new sample psykick time(1/4)
new sample snare_short time(1/16) play(euclid(7 3)) gain(0.5)
new sample hat_short time(1/4 1/8) gain(1.3)

base​

If the base url is the same for all the sample files, for example when loading samples via freesound, you can add a "_base" : key, followed by the part of the url that is the same for all the samples. Make sure you include the last / so the complete url is correct.

{
    "snare_short" : "671/671221_3797507-lq.mp3",
    "psykick" : "145/145778_2101444-lq.mp3",
    "hat_short" : "222/222058_1676145-lq.mp3",
    "_base" : "https://cdn.freesound.org/previews/"
}