DOCSEARCHbyAlgolia
Submit Docs

Mercury Live Coding Environment

website·Indexed 29 days ago

https://tmhglnd.github.io/mercury

A free, open-source, and beginner-friendly live coding environment for algorithmic electronic music. Mercury provides a minimal language for manipulating musical lists, numbers, and sounds, featuring tools for sequencing, synthesis, and MIDI/OSC triggers. It is available via MercuryPlayground and Mercury4Max, offering capabilities for collaborative coding, external editor integration, and custom synth extension.

Tokens
28.5K
Snippets
223
Records
274
Agent score
75%

What's inside Mercury

  1. Overview of the Mercury live coding language

    Mercury is a free, open-source, and beginner-friendly programming language designed for the live coding of algorithmic electronic music performances. It emphasizes human-readability and accessibility for both the performer and the audience, using descriptive function names and simple syntax. While primarily focused on sound generation, it can also output MIDI or OSC to control external devices, software, or visuals.

  2. Overview of Mercury live coding capabilities

    Mercury is a hands-on coding environment and language designed for livecoding works, electronic music education, and real-time process control. Key capabilities include:

    • Music & Sound: Algorithmic composition, sequencing, pattern generation, and sound design using a built-in sampler/synthesizer.
    • Visuals: Coding visuals that can react to sound.
    • Integration: Controlling external software and hardware via OSC and MIDI messages.
    • Deployment & Collaboration: The software runs directly in the browser and supports real-time collaborative coding via Flok.
    • Algorithmic Composition: Access to an extensive library of techniques, available as a separate package called total-serialism.

  3. Understand Mercury code evaluation

    Mercury code is evaluated as an entire page, processed per line from top to bottom. This ensures the code is a direct reflection of the system state. To prevent specific snippets from being evaluated and heard, use comments (//) or store the code in a separate file.

  4. Theoretical foundations of Mercury musical algorithms

    Mercury's functionality is based on several music theory and mathematical concepts:

    • Serialism & Total Serialism: Approaches musical parameters (pitch, duration, velocity) as individual series of values. It utilizes the twelve-tone technique, allowing transformations like reverse/retrograde, inverse, and transpose.
    • Euclidean Rhythms: Based on Godfried Toussaint's work on the Euclidean Algorithm to generate traditional musical rhythms.
    • Clave Rhythms: Based on mathematical analysis of African, Brazilian, and Cuban clave rhythms.
    • Integer Sequences: Uses mathematical functions (e.g., Fibonacci) and modulo operations (e.g., Pisano periods) for algorithmic composition, inspired by Iannis Xenakis's 'Symbolic Music'.
    • Hexadecimal Beats: Rhythmic generation inspired by representing patterns as binary/hexadecimal numbers.
    • Infinity Series: Based on Per Nørgård's work, creating endlessly self-similar musical material similar to fractal geometry.
    • Collatz Conjecture: Used to create organic graphs by treating even-odd numbers as rotations in line angles.

  5. Understand Mercury list behavior and sequencing

    In Mercury, a list is a series of values used to adjust instrument states over time (Serialism). Each instrument has an internal counter that increments when an event is triggered. When a list is passed as an argument to an instrument function, the instrument uses its current counter as an index to look up a value from the list. Lists are circular; once the index exceeds the list length, it wraps back to the beginning.

  6. Understand Mercury's sequencing and list logic

    Mercury is based on the concept of Total Serialism, where musical parameters (pitch, rhythm, dynamics) are expressed as a series of values called a list.

    Each instrument in Mercury has an internal counter (step-sequencer) that increments whenever an event is triggered based on the time() interval. When a list is passed as an argument to an instrument function, the instrument uses its current counter as an index to look up a value from the list. These lists are circular; once the index exceeds the number of values in the list, it wraps back to the beginning.

  8. Trigger instruments externally via MIDI

    To bypass Mercury's internal transport and trigger an instrument based on MIDI input, set the first argument of time() to 'free' and provide an OSC address (like /velocity) as the second argument. The instrument will trigger whenever the value at that address is greater than 0.
    new synth sine note('/note') time('free' '/velocity')

  9. Configure Visual Setup in Mercury4Max

    The Visual Setup menu controls the editor window output:

    • Aspect Ratio: Choose from various presets (e.g., 16:9, 4:3, 1:1).
    • Resolution: Sets the window height in pixels; width is calculated based on aspect ratio.
    • Visual Resolution: Allows rendering visuals at a lower resolution than the UI text for better performance on machines without dedicated GPUs.
    • Window Size: Adjusts the UI window size. Use ESC to toggle fullscreen.
    • Screens: Multiplier for width to stretch visuals across multiple monitors.
    • Sync to Refreshrate: Syncs framerate to display. If disabled, you can manually set the FPS.
    • Syphon output (Mac only): Outputs the visual window as a texture for software like OBS.

  10. Play audio samples in Mercury

    To play a sample in Mercury, use the new sample command followed by the sample name. Instruments in Mercury loop automatically by default. You can add multiple instruments by placing each command on a new line. To 'mute' an instrument without deleting the code, use the // comment syntax.
    new sample kick_house
new sample hat_min
new sample snare_808

// This line is muted
// new sample hat_min

  11. Use the loop instrument for time-stretched samples

    The loop instrument is a variation of the sample instrument with stretch(1) enabled by default, causing all loaded samples to stretch to exactly 1 full bar. It supports all standard instrument functions available to the sample instrument.
    new loop <sample-name>

  12. Use the polySample instrument for overlapping samples

    The polySample instrument allows overlapping sample playback, useful for chords. It uses the same 2D-list logic for note() and the same steal() behavior as polySynth.
    set tempo 100
set scale dorian eb
list notes shuffle(spread(24))
new polySample piano_e time(1/16) note(notes 1) shape(1 1/2) steal(off) tune(64)