🌕 Mercury Live Coding Environment

A minimal and human-readable language for the live coding of algorithmic electronic audiovisual performances.

🙏 Support Mercury by becoming a Patron

💬 Join the Discord Community!

🚀 Start coding with the latest version:

📋 Table of Contents

• 📟 Mercury?
• 🎮 What can I do with Mercury?
• 🔭 Who is it for?
• 👩‍💻 Code together with others!
• 🚀 Let's get started!
  • Quick Start
  • Tutorial
  • Documentation
  • Troubleshooting
  • System Requirements
  • Sounds in Mercury
• 🔎 Read more
• 👾 Hear what others made
• 🤓 I like to help
• 🔋 Powered By
• 🙏 Thanks
• ✨ Inspiration
• 📄 Licenses

📟 About

Mercury is a minimal and human-readable language for the live coding of algorithmic electronic music.

All elements of the language are designed around making code more accessible and less obfuscating for the audience. This motivation stretches down to the coding style itself which uses clear descriptive names for functions and a clear syntax. Furthermore the editor is restricted to 30 lines of code, keeping all code always visible. Mercury provides the performer with an extensive library of algorithms to generate or transform numbersequences that can modulate parameters, such as melody and rhythm, over time. The environment produces sound in conjunction with visuals. Besides looking at the code, the audience is also looking at the visuals that are reactive to the sound or generated by the sound.

It is named after te planet Mercury. Mercury rules the creation and expression of our mental processes. The planet implores us to express ourselves. Mercury is about a quick wit, quick thinking. It lets us move from one thing to the next.

Mercury is programmed in the Cycling'74 Max8 node-based creative coding environment, as an abstracted layer on the Max/MSP audio engine and with the use of Node4Max for parsing, lexing and generative algorithms and Jitter/OpenGL for the visuals and the responsive texteditor.

Mercury uses the Total Serialism NodeJS package available on npmjs.com. This package contains an extensive library of algorithmic composition methods.

🎮 Features Overview

Quick access to playback of samples and change timing and tempo of samples or synthesizers

set tempo 89

new sample kick_909 time(1/4)
new sample hat_909 time(3/16)

Make rhythmic patterns with sequences of numbers and probabilities

ring loBeat [1 0 0 1 0.5]
ring hiBeat [0 1 0.2 0]

new sample tabla_lo time(1/8) play(loBeat)
new sample tabla_hi time(1/8) play(hiBeat)

Generate psuedorandom melodic content for a synthesizer in a range and set a scale

set scale minor d
set randomSeed 31415

ring melody random(16 0 24)

new synth saw note(melody) time(1/16) shape(4 100)

Design sounds with various effects

new sample chimes time(2) speed(-0.25) fx(reverb 0.3 15) fx(drive 10) fx(lfo 1/8 sine)

Easily give multiple instruments the same effects

new sample chimes time(2)
new sample harp_down time(3)
new sample gong_lo time(5)

set all fx(lfo 1/16) fx(delay) fx(reverb 0.5 11)

Generate sequences algorithmically to compose complex structures and choose from an extensive library of algorithms to work with

set scale minor a 

ring rhythm euclidean(32 13)

ring melody spread(5 0 24)
ring melody palinedrome(melody)
ring melody clone(melody 0 5 7 3)
ring melody lace(melody melody)

new synth triangle note(melody 1) shape(1 80) play(rhythm)

Control external midi devices or send midi to other applications and use clock sync

set midi getPorts
//=> prints the available devices to the console
new midi "Your Awesome Midi Device" time(1/4) note(7 1) length(100) sync(on)

Control other environments via OSC-messages

ring params [0.25 0.5 0.75]

new emitter osc address(yourDevice) theParam(params) time(1/4)

// emits => /yourDevice/theParam 0.25
//          /yourDevice/theParam 0.5
//          /yourDevice/theParam 0.75
//          /yourDevice/theParam 0.25
//          etc...

Easily control parameters in Mercury via external OSC-messages

new synth triangle fx(reverb /extOSC/verbAmount) fx(filter low /extOSC/cutoff 0.4) time(1) shape(1 1000)

AND MANY MORE (TO COME...)

🔭 Vision / Goals

• Provide creatives with a quick and hands-on coding environment/language to expres, communicate and improvise livecoded works.
• Use the environment as a teaching environment for:
  • introduction to (electronic) music
  • algorithmic composition
  • sequencing and pattern generating
  • sound design
  • creative coding and live coding
• Provide creatives with an hands-on language to create realtime processes
  • code sound and music
  • code visuals and let them react to sound
• Provide creatives with an extensive library of algorithmic composition techniques
  • released as a seperate Node Package titled Total-Serialism
  • included in the Mercury environment through Node4Max
• Provide creatives with a multi-purpose non-linear-sequencer
  • use OSC to communicate with other platforms
  • use MIDI to communicate with other environments and devices
• Provide creatives with an easy sampler/synthesizer for sounddesign and composition
  • use external OSC to control parameters in the sampler/synthesis
  • use external MIDI devices and messages to play the sampler/synthesizers (coming soon...)
• Release a stand-alone application for MacOS and Windows, making installing and workflow easier (coming soon...)
• Collaborate in Mercury via the browser and code music together
• Extending the Mercury users-community and including extensions on the environment in the master-branch

⭐️ watch and star this repo to keep up-to-date with the latest changes whenever they're made

👩‍💻👨‍💻 Collaborative Coding

It is now possible to code together in Mercury using the amazing Flok live coding environment in the browser.

• Start coding together here

💻 Install

• 📖 I need some help installing
• 🚀 I'm an experienced computer user
• 💻 Is my computer powerful enough?

OR

• 🤓 I'll just download and figure it out myself

$ cd ~/Documents/Max\ 8/Projects
$ git clone http://github.com/tmhglnd/mercury
$ cd mercury
$ open mercury_ide/mercury_ide.maxproj

⚠ Troubleshooting

It could be that you are having issues with Mercury. Please follow the steps below:

• Open the Troubleshooting

📖 Documentation

Full explanation of all the possibilities in Mercury:

• Open the documentation

💻 System Requirements

These system requirements are recommended to install and run Max and Mercury on your computer. Lower specs may work but it's not guaranteed. A dedicated Graphics Card (GPU) is also recommended to run the visual side of Mercury smoothly (the text-editor runs on the graphics card as well).

OS	CPU	RAM
Mac OSX 10.13 (at least 10.11.6+)	Intel i5 processor	8 GB
Windows 10 (7 or 8 may work)	Intel i5 or AMD mult-core processor	8 GB

🎵 Sounds

Many sounds in Mercury are downloaded from freesound.org and are licensed with Creative Commons Attribution or Creative Commons 0 licenses. If not downloaded from freesound it is made sure that the license allows to redistribute the sounds via the Mercury environment and that you can use them in your projects. A list of all the available sounds and the original sample can be found here:

• List of sounds and credits

🔍 Further reading

• Mercury homepage
• Paper in ICLC 2019
• Total Serialism Library

👾 Made with Mercury

• Made something with Mercury? Please add a URL here and send a pull request! 😎
• T.mo - Liber Abaci (Mercury Coding Sessions)
• Roald van Dillewijn - Smashing Temparateness (Mercury Coding Sessions)
• Rafa & Timo - "Hello, off-world!" (Mercury Coding Sessions)
• Guillem Góngora Moral - Transcription #1 (Mercury Coding Sessions)
• Anne Veinberg - CodeKlavier meets Mercury (Mercury Coding Sessions)
• Nick Levantis - Wake Up
• Rafa & Timo - "Hello, off-world!" (Live at NMF)
• Roald van Dillewijn - Mercury & DigiLog
• Sasj & Timo - Amalgam (Live at Github Sattelite 2020)
• Anne Veinberg - CodeKlaver & Mercury Extension Tryout
• Timo - Live at NerdLab VR 2020
• T.mo - Live at Eulerroom Equinox 2020
• T.mo - Live at Algo:Ritmi 2020
• T.mo - Live at NLCL Meetup STEIM

📝 Contribute

Contributions to the Mercury environment are much appreciated in whatever form they come! You can contribute in any of the following ways:

• Add suggestions, bugs or feature-requests to the issues
• Make additions or changes to the Documentation, Tutorials, Examples and any other text in this repository
• Adjust the source code or make bugfixes and add features by forking and sending a pull request (see the Guidelines)

In order to make changes to various types of source code files you will need the following:

• patchers - Requires Max8 environment and license to edit/modify/save the patchers of this project.
• JS code - Requires a standard code-editor (eg. VSCode or Atom) to edit/modify/save the JS code.
• GenExpr Code - Requires a standard code-editor (eg. VSCode or Atom) to edit/modify/save the GenExpr code.

Guidelines

In order to receive your contribution please follow these steps:

1. Fork this repository (click fork in the top right)
2. Clone the repository to your computer git clone https://github.com/<this-is-you>/<forked-repo>.git
3. Branch the Fork git checkout -b <name-your-branch>
4. Make any changes/additions to the code or docs
5. Add, commit and push your changes git add . git commit -a git push origin <your-branch-name>
6. Go to your forked repo in the browser and click compare & pull request, then create pull request
7. Please add a comment to clearify what you did and why

All steps with examples and images

🔋 Powered By

• Mercury has been granted funding from Creative Industries Fund NL
• Mercury has been granted in-kind funding from Creative Coding Utrecht

🙏 Thanks

• Roald van Dillewijn for working together on osc and midi functionalities combined with his Digilog modified guitar-pedals
• Guillem Gongora Moral for using Mercury as a composition tool and sharing valuable feedback in the process
• Anne Veinberg for working with Mercury and a Mercury extensions for the CodeKlavier project
• Rafaele Maria Andrade for collaboration on networked performance between Mercury and Knurl
• Repo banner image by Annebel Bunt
• Live performance image by Zuzanna Zgierska

✨ Inspiration

During the development of Mercury (both the playground and the full version) I've found inspiration in many other live coding environments, practices and other platforms. Some of these are:

• Hydra - Live coding visual synthesizer by Olivia Jack
• Sema - Live coding language design platform combined with Machine Learning
• MIMIC Project - a web platform for the artistic exploration of musical machine learning and machine listening.
• Tidal - Live coding of patterns
• Sonic Pi - The live coding synth for everyone
• Tone.js - Webaudio framework for programming synths and sequencers
• Nearley - Parsing toolkit

📄 Licenses

• Main Source - The GNU GPL v.3 License (c) Timo Hoogland 2019
• Sound Files - Individually licensed, listed under media/README.md
• Documentation - The CC BY-SA 4.0 License (c) Timo Hoogland 2019
• Examples - The CC BY-SA 4.0 License (c) Timo Hoogland 2019
• Max8 - Proprietary Software, Max (c) 1990-2019 Cycling'74 / IRCAM All rights reserved

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.