Bump ws from 8.14.2 to 8.17.1 in /ToposServer

Bumps [ws](https://github.com/websockets/ws) from 8.14.2 to 8.17.1.
- [Release notes](https://github.com/websockets/ws/releases)
- [Commits](https://github.com/websockets/ws/compare/8.14.2...8.17.1)

---
updated-dependencies:
- dependency-name: ws
  dependency-type: direct:production
...

Signed-off-by: dependabot[bot] <support@github.com>

.github/workflows/deploy.yml

@@ -47,9 +47,6 @@ jobs:
         with:
           path: "main"
 
-      - name: Copy favicon folder
-        run: cp -r main/favicon ./dist/
-
       - name: Deploy to GitHub Pages
         uses: peaceiris/actions-gh-pages@v3
         with:

README.md

@@ -1,9 +1,9 @@
 # Topos: A Web-Based Algorithmic Sequencer
 
 <p align="center"> | 
-  <a href="https://discord.gg/aPgV7mSFZh">Discord</a> | 
-  <a href="https://raphaelforment.fr/">BuboBubo</a> | 
-  <a href="about:blank">Amiika</a> | 
+  <a href="https://discord.gg/aPgV7mSFZh">Discord</a> |
+  <a href="https://raphaelforment.fr/">BuboBubo</a> |
+  <a href="https://github.com/amiika">Amiika</a> |
   <a href="https://toplap.org/">About Live Coding</a> |
   <br><br>
   <h2 align="center"><b>Contributors</b></h2>
@@ -12,42 +12,60 @@
     <img src="https://contrib.rocks/image?repo=bubobubobubobubo/Topos" />
     </a>
   </p>
+  <p align="center">
+  <a href='https://ko-fi.com/I2I2RSBHF' target='_blank'><img height='36' style='border:0px;height:36px;' src='https://storage.ko-fi.com/cdn/kofi3.png?v=3' border='0' alt='Buy Me a Coffee at ko-fi.com' /></a>
+  </p>
 </p>
 
-Topos is a web-based live coding environment. It lives [here](https://topos.live). Documentation is directly embedded in the application itself. Topos is an emulation and extension of the [Monome Teletype](https://monome.org/docs/teletype/) that gradually evolved into something a bit more personal.
+---
 
-![Screenshot](https://github.com/Bubobubobubobubo/Topos/blob/main/img/topos_gif.gif)
+Topos is a web based live coding environment designed to be installation-free, independant and fun. Topos is loosely based on the [Monome Teletype](https://monome.org/docs/teletype/). The application follows the same operating principle, but adapts it to the rich multimedia context offered by web browsers. Topos is capable of many things:
+
+- it is a generative/algorithmic music sequencer made for **improvisation** and **composition** alike
+- it is a synthesizer capable of _additive_, _substractive_, _FM_ and _wavetable
+  synthesis_, backed up by a [powerful web based audio engine](https://www.npmjs.com/package/superdough)
+- it can also generate video thanks to [Hydra](https://hydra.ojack.xyz/), 
+  oscilloscopes, frequency visualizers and image/canvas sequencing capabilities
+- it can be used to sequence other MIDI and OSC devices (the latter using a **NodeJS** script)
+- it is made to be used without the need of installing anything, always ready at
+  [https://topos.live](https://topos.live)
+
+---
+
+![Screenshot](https://github.com/Bubobubobubobubo/Topos/blob/main/src/assets/topos_gif.gif)
 
 ## Disclaimer
 
-**Topos** is a fairly young project developed by two part time hobbyists :) Do not expect stable features and/or user support in the initial development stage. Contributors and curious people are welcome! The software is working quite well and we are continuously striving to improve it.
+**Topos** is still a young and experimental project developed by two hobbyists :) Contributions are welcome! We wish to be as inclusive and welcoming as possible to your ideas and suggestions! The software is working quite well and we are continuously striving to improve it. Note that most features are rather experimental and that we don't really have any classical training in web development.
 
-## Installation (for devs and contributors)
+## Local Installation (for devs and contributors)
 
 To run the application, you will need to install [Node.js](https://nodejs.org/en/) and [Yarn](https://yarnpkg.com/en/). Then, clone the repository and run:
 
 - `yarn install`
 - `yarn run dev`
 
-To build the application for production, you will need to install [Node.js](https://nodejs.org/en/) and [Yarn](https://yarnpkg.com/en/). Then, clone the repository and run:
+You are good to go. The application will update itself automatically with every change to the codebase. To test the production version of the applicationn, you will need to install [Node.js](https://nodejs.org/en/) and [Yarn](https://yarnpkg.com/en/). Then, clone the repository and run:
 
 - `yarn run build`
 - `yarn run start`
 
-Always run a build before committing to check for compiler errors. The automatic deployment on the `main` branch will not accept compiler errors!
+If the build passes, you can be sure that it will also pass our **CI** pipeline that deploys the application to [https://topos.live](https://topos.live). Always run a build before committing to check for compiler errors. The automatic deployment on the `main` branch will not accept compiler errors!
 
-To build a standalone browser application using [Tauri](https://tauri.app/), you will need to have [Node.js](https://nodejs.org/en/), [Yarn](https://yarnpkg.com/en/) and [Rust](https://www.rust-lang.org/) installed. Then, clone the repository and run:
+## Tauri version
+
+Topos can also be compiled as a standalone application using [Tauri](https://tauri.app/). You will need [Node.js](https://nodejs.org/en/), [Yarn](https://yarnpkg.com/en/) and [Rust](https://www.rust-lang.org/) to be installed on your computer. Then, clone the repository and run:
 
 - `yarn tauri build`
 - `yarn tauri dev`
 
-The `tauri` version is only here to quickstart future developments but nothing has been done yet.
+The `tauri` version has never been fleshed out. It's a template for later developments if Topos ever wants to escape from the web :)
 
 ## Docker
 
-### Run the application
+To run the **Docker** version, run the following command:
 
-`docker run -p 8001:80 yassinsiouda/topos:latest`
+`docker run -p 8001:80 bubobubobubo/topos:latest`
 
 ### Build and run the prod image
 
@@ -55,8 +73,7 @@ The `tauri` version is only here to quickstart future developments but nothing
 
 ### Build and run the dev image
 
-**First installation**
-First you need to map node_modules to your local machine for your ide intellisense to work properly
+First you need to map `node_modules` to your local machine for your IDE IntelliSense to work properly :
 
 ```bash
 docker compose --profile dev up -d
@@ -64,8 +81,21 @@ docker cp topos-dev:/app/node_modules .
 docker compose --profile dev down
 ```
 
-**Then**
+then run the following command:
 
 ```bash
 docker compose --profile dev up
 ```
+
+Note that a Docker version of Topos is automatically generated everytime a commit is done on the `main` branch.
+
+## Credits
+
+- Felix Roos for the [SuperDough](https://www.npmjs.com/package/superdough) audio engine.
+- Frank Force for the [ZzFX](https://github.com/KilledByAPixel/ZzFX) synthesizer.
+- Kristoffer Ekstrand for the [AKWF](https://www.adventurekid.se/akrt/waveforms/adventure-kid-waveforms/) waveforms.
+- Ryan Kirkbride for some of the audio samples in the [Dough-Fox](https://github.com/Bubobubobubobubo/Dough-Fox) sample pack, taken from [here](https://github.com/Qirky/FoxDot/tree/master/FoxDot/snd).
+- Adel Faure for the [JGS](https://adelfaure.net/https://adelfaure.net/) font.
+- Raphaël Bastide for the [Steps Mono](https://github.com/raphaelbastide/steps-mono/) font.
+
+Many thanks to all the contributors and folks who tried the software already :)

ToposServer/OSCtoTopos.js

@@ -0,0 +1,36 @@
+const WebSocket = require("ws");
+const osc = require("osc");
+
+const cleanIncomingOSC = (oscMsg) => {
+  let data = oscMsg.args;
+  // Remove information about type of data
+  data = data.map((item) => {
+    return item.value;
+  });
+  return { data: data, address: oscMsg.address };
+};
+
+// ==============================================
+// Receiving and forwarding OSC UDP messages
+// Create an osc.js UDP Port listening on port 57121.
+console.log("> OSC Input: 127.0.0.1:30000");
+const wss = new WebSocket.Server({ port: 3001 });
+var udpPort = new osc.UDPPort({
+  localAddress: "0.0.0.0",
+  localPort: 30000,
+  metadata: true,
+});
+udpPort.on("message", function (oscMsg, timeTag, info) {
+  console.log(
+    `> Incoming OSC to ${oscMsg.address}:`,
+    oscMsg.args.map((item) => {
+      return item.value;
+    }),
+  );
+  wss.clients.forEach((client) => {
+    if (client.readyState === WebSocket.OPEN) {
+      client.send(JSON.stringify(cleanIncomingOSC(oscMsg)));
+    }
+  });
+});
+udpPort.open();

ToposServer/ToposToOSC.js

@@ -0,0 +1,83 @@
+const WebSocket = require("ws");
+const osc = require("osc");
+
+// Listening to WebSocket messages
+const wss = new WebSocket.Server({ port: 3000 });
+
+// Setting up for message broadcasting
+wss.on("connection", function (ws) {
+  console.log("> Client connected");
+  ws.on("message", function (data) {
+    try {
+      const message = JSON.parse(data);
+      sendOscMessage(
+        formatAndTypeMessage(message),
+        message.address,
+        message.port,
+      );
+      console.log(
+        `> Message sent to ${message.address}:${message.port}: ${JSON.stringify(
+          message.args,
+        )}`,
+      );
+    } catch (error) {
+      console.error("> Error processing message:", error);
+    }
+  });
+});
+
+wss.on("error", function (error) {
+  console.error("> Server error:", error);
+});
+
+wss.on("close", function () {
+  // Close the websocket server
+  wss.close();
+  console.log("> Closing websocket server");
+});
+
+let udpPort = new osc.UDPPort({
+  localAddress: "0.0.0.0",
+  localPort: 3000,
+  metadata: true,
+  remoteAddress: "0.0.0.0",
+  remotePort: 57120,
+});
+udpPort.on("error", function (error) {
+  console.error("> UDP Port error:", error);
+});
+udpPort.on("ready", function () {
+  //console.log(`> UDP Receive: ${udpPort.options.localPort}`);
+  console.log("> WebSocket server: 127.0.0.1:3000");
+});
+
+udpPort.open();
+
+function sendOscMessage(message, address, port) {
+  try {
+    udpPort.options.remotePort = port;
+    message.address = address;
+    udpPort.send(message);
+  } catch (error) {
+    console.error("> Error sending OSC message:", error);
+  }
+}
+
+const formatAndTypeMessage = (message) => {
+  let newMessage = {};
+  delete message.args["address"];
+  delete message.args["port"];
+  newMessage.address = message.address;
+  newMessage.timestamp = osc.timeTag(message.timetag);
+
+  args = [...Object.entries(message.args)].flat().map((arg) => {
+    if (typeof arg === "string") return { type: "s", value: arg };
+    if (typeof arg === "number") return { type: "f", value: arg };
+    if (typeof arg === "boolean")
+      return value ? { type: "s", value: 1 } : { type: "s", value: 0 };
+  });
+
+  newMessage.args = args;
+
+  return newMessage;
+};

ToposServer/banner.js

@@ -0,0 +1,14 @@
+var pjson = require("./package.json");
+let banner = `
+┏┳┓         ┏┓┏┓┏┓
+ ┃ ┏┓┏┓┏┓┏  ┃┃┗┓┃ 
+ ┻ ┗┛┣┛┗┛┛  ┗┛┗┛┗┛
+     ┛            
+             ${pjson.version}\n`;
+function greet() {
+  console.log(banner);
+}
+
+module.exports = {
+  greet: greet,
+};

ToposServer/package-lock.json

@@ -0,0 +1,332 @@
+{
+  "name": "topos-server",
+  "version": "0.0.1",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "name": "topos-server",
+      "version": "0.0.1",
+      "license": "GPL-3.0-or-later",
+      "dependencies": {
+        "osc": "^2.4.4",
+        "ws": "^8.17.1"
+      }
+    },
+    "node_modules/@serialport/binding-mock": {
+      "version": "10.2.2",
+      "resolved": "https://registry.npmjs.org/@serialport/binding-mock/-/binding-mock-10.2.2.tgz",
+      "integrity": "sha512-HAFzGhk9OuFMpuor7aT5G1ChPgn5qSsklTFOTUX72Rl6p0xwcSVsRtG/xaGp6bxpN7fI9D/S8THLBWbBgS6ldw==",
+      "optional": true,
+      "dependencies": {
+        "@serialport/bindings-interface": "^1.2.1",
+        "debug": "^4.3.3"
+      },
+      "engines": {
+        "node": ">=12.0.0"
+      }
+    },
+    "node_modules/@serialport/bindings-cpp": {
+      "version": "10.8.0",
+      "resolved": "https://registry.npmjs.org/@serialport/bindings-cpp/-/bindings-cpp-10.8.0.tgz",
+      "integrity": "sha512-OMQNJz5kJblbmZN5UgJXLwi2XNtVLxSKmq5VyWuXQVsUIJD4l9UGHnLPqM5LD9u3HPZgDI5w7iYN7gxkQNZJUw==",
+      "hasInstallScript": true,
+      "optional": true,
+      "dependencies": {
+        "@serialport/bindings-interface": "1.2.2",
+        "@serialport/parser-readline": "^10.2.1",
+        "debug": "^4.3.2",
+        "node-addon-api": "^5.0.0",
+        "node-gyp-build": "^4.3.0"
+      },
+      "engines": {
+        "node": ">=12.17.0 <13.0 || >=14.0.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/serialport/donate"
+      }
+    },
+    "node_modules/@serialport/bindings-interface": {
+      "version": "1.2.2",
+      "resolved": "https://registry.npmjs.org/@serialport/bindings-interface/-/bindings-interface-1.2.2.tgz",
+      "integrity": "sha512-CJaUd5bLvtM9c5dmO9rPBHPXTa9R2UwpkJ0wdh9JCYcbrPWsKz+ErvR0hBLeo7NPeiFdjFO4sonRljiw4d2XiA==",
+      "optional": true,
+      "engines": {
+        "node": "^12.22 || ^14.13 || >=16"
+      }
+    },
+    "node_modules/@serialport/parser-byte-length": {
+      "version": "10.5.0",
+      "resolved": "https://registry.npmjs.org/@serialport/parser-byte-length/-/parser-byte-length-10.5.0.tgz",
+      "integrity": "sha512-eHhr4lHKboq1OagyaXAqkemQ1XyoqbLQC8XJbvccm95o476TmEdW5d7AElwZV28kWprPW68ZXdGF2VXCkJgS2w==",
+      "optional": true,
+      "engines": {
+        "node": ">=12.0.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/serialport/donate"
+      }
+    },
+    "node_modules/@serialport/parser-cctalk": {
+      "version": "10.5.0",
+      "resolved": "https://registry.npmjs.org/@serialport/parser-cctalk/-/parser-cctalk-10.5.0.tgz",
+      "integrity": "sha512-Iwsdr03xmCKAiibLSr7b3w6ZUTBNiS+PwbDQXdKU/clutXjuoex83XvsOtYVcNZmwJlVNhAUbkG+FJzWwIa4DA==",
+      "optional": true,
+      "engines": {
+        "node": ">=12.0.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/serialport/donate"
+      }
+    },
+    "node_modules/@serialport/parser-delimiter": {
+      "version": "10.5.0",
+      "resolved": "https://registry.npmjs.org/@serialport/parser-delimiter/-/parser-delimiter-10.5.0.tgz",
+      "integrity": "sha512-/uR/yT3jmrcwnl2FJU/2ySvwgo5+XpksDUR4NF/nwTS5i3CcuKS+FKi/tLzy1k8F+rCx5JzpiK+koqPqOUWArA==",
+      "optional": true,
+      "engines": {
+        "node": ">=12.0.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/serialport/donate"
+      }
+    },
+    "node_modules/@serialport/parser-inter-byte-timeout": {
+      "version": "10.5.0",
+      "resolved": "https://registry.npmjs.org/@serialport/parser-inter-byte-timeout/-/parser-inter-byte-timeout-10.5.0.tgz",
+      "integrity": "sha512-WPvVlSx98HmmUF9jjK6y9mMp3Wnv6JQA0cUxLeZBgS74TibOuYG3fuUxUWGJALgAXotOYMxfXSezJ/vSnQrkhQ==",
+      "optional": true,
+      "engines": {
+        "node": ">=12.0.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/serialport/donate"
+      }
+    },
+    "node_modules/@serialport/parser-packet-length": {
+      "version": "10.5.0",
+      "resolved": "https://registry.npmjs.org/@serialport/parser-packet-length/-/parser-packet-length-10.5.0.tgz",
+      "integrity": "sha512-jkpC/8w4/gUBRa2Teyn7URv1D7T//0lGj27/4u9AojpDVXsR6dtdcTG7b7dNirXDlOrSLvvN7aS5/GNaRlEByw==",
+      "optional": true,
+      "engines": {
+        "node": ">=8.6.0"
+      }
+    },
+    "node_modules/@serialport/parser-readline": {
+      "version": "10.5.0",
+      "resolved": "https://registry.npmjs.org/@serialport/parser-readline/-/parser-readline-10.5.0.tgz",
+      "integrity": "sha512-0aXJknodcl94W9zSjvU+sLdXiyEG2rqjQmvBWZCr8wJZjWEtv3RgrnYiWq4i2OTOyC8C/oPK8ZjpBjQptRsoJQ==",
+      "optional": true,
+      "dependencies": {
+        "@serialport/parser-delimiter": "10.5.0"
+      },
+      "engines": {
+        "node": ">=12.0.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/serialport/donate"
+      }
+    },
+    "node_modules/@serialport/parser-ready": {
+      "version": "10.5.0",
+      "resolved": "https://registry.npmjs.org/@serialport/parser-ready/-/parser-ready-10.5.0.tgz",
+      "integrity": "sha512-QIf65LTvUoxqWWHBpgYOL+soldLIIyD1bwuWelukem2yDZVWwEjR288cLQ558BgYxH4U+jLAQahhqoyN1I7BaA==",
+      "optional": true,
+      "engines": {
+        "node": ">=12.0.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/serialport/donate"
+      }
+    },
+    "node_modules/@serialport/parser-regex": {
+      "version": "10.5.0",
+      "resolved": "https://registry.npmjs.org/@serialport/parser-regex/-/parser-regex-10.5.0.tgz",
+      "integrity": "sha512-9jnr9+PCxRoLjtGs7uxwsFqvho+rxuJlW6ZWSB7oqfzshEZWXtTJgJRgac/RuLft4hRlrmRz5XU40i3uoL4HKw==",
+      "optional": true,
+      "engines": {
+        "node": ">=12.0.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/serialport/donate"
+      }
+    },
+    "node_modules/@serialport/parser-slip-encoder": {
+      "version": "10.5.0",
+      "resolved": "https://registry.npmjs.org/@serialport/parser-slip-encoder/-/parser-slip-encoder-10.5.0.tgz",
+      "integrity": "sha512-wP8m+uXQdkWSa//3n+VvfjLthlabwd9NiG6kegf0fYweLWio8j4pJRL7t9eTh2Lbc7zdxuO0r8ducFzO0m8CQw==",
+      "optional": true,
+      "engines": {
+        "node": ">=12.0.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/serialport/donate"
+      }
+    },
+    "node_modules/@serialport/parser-spacepacket": {
+      "version": "10.5.0",
+      "resolved": "https://registry.npmjs.org/@serialport/parser-spacepacket/-/parser-spacepacket-10.5.0.tgz",
+      "integrity": "sha512-BEZ/HAEMwOd8xfuJSeI/823IR/jtnThovh7ils90rXD4DPL1ZmrP4abAIEktwe42RobZjIPfA4PaVfyO0Fjfhg==",
+      "optional": true,
+      "engines": {
+        "node": ">=12.0.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/serialport/donate"
+      }
+    },
+    "node_modules/@serialport/stream": {
+      "version": "10.5.0",
+      "resolved": "https://registry.npmjs.org/@serialport/stream/-/stream-10.5.0.tgz",
+      "integrity": "sha512-gbcUdvq9Kyv2HsnywS7QjnEB28g+6OGB5Z8TLP7X+UPpoMIWoUsoQIq5Kt0ZTgMoWn3JGM2lqwTsSHF+1qhniA==",
+      "optional": true,
+      "dependencies": {
+        "@serialport/bindings-interface": "1.2.2",
+        "debug": "^4.3.2"
+      },
+      "engines": {
+        "node": ">=12.0.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/serialport/donate"
+      }
+    },
+    "node_modules/debug": {
+      "version": "4.3.4",
+      "resolved": "https://registry.npmjs.org/debug/-/debug-4.3.4.tgz",
+      "integrity": "sha512-PRWFHuSU3eDtQJPvnNY7Jcket1j0t5OuOsFzPPzsekD52Zl8qUfFIPEiswXqIvHWGVHOgX+7G/vCNNhehwxfkQ==",
+      "optional": true,
+      "dependencies": {
+        "ms": "2.1.2"
+      },
+      "engines": {
+        "node": ">=6.0"
+      },
+      "peerDependenciesMeta": {
+        "supports-color": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/long": {
+      "version": "4.0.0",
+      "resolved": "https://registry.npmjs.org/long/-/long-4.0.0.tgz",
+      "integrity": "sha512-XsP+KhQif4bjX1kbuSiySJFNAehNxgLb6hPRGJ9QsUr8ajHkuXGdrHmFUTUUXhDwVX2R5bY4JNZEwbUiMhV+MA=="
+    },
+    "node_modules/ms": {
+      "version": "2.1.2",
+      "resolved": "https://registry.npmjs.org/ms/-/ms-2.1.2.tgz",
+      "integrity": "sha512-sGkPx+VjMtmA6MX27oA4FBFELFCZZ4S4XqeGOXCv68tT+jb3vk/RyaKWP0PTKyWtmLSM0b+adUTEvbs1PEaH2w==",
+      "optional": true
+    },
+    "node_modules/node-addon-api": {
+      "version": "5.1.0",
+      "resolved": "https://registry.npmjs.org/node-addon-api/-/node-addon-api-5.1.0.tgz",
+      "integrity": "sha512-eh0GgfEkpnoWDq+VY8OyvYhFEzBk6jIYbRKdIlyTiAXIVJ8PyBaKb0rp7oDtoddbdoHWhq8wwr+XZ81F1rpNdA==",
+      "optional": true
+    },
+    "node_modules/node-gyp-build": {
+      "version": "4.7.0",
+      "resolved": "https://registry.npmjs.org/node-gyp-build/-/node-gyp-build-4.7.0.tgz",
+      "integrity": "sha512-PbZERfeFdrHQOOXiAKOY0VPbykZy90ndPKk0d+CFDegTKmWp1VgOTz2xACVbr1BjCWxrQp68CXtvNsveFhqDJg==",
+      "optional": true,
+      "bin": {
+        "node-gyp-build": "bin.js",
+        "node-gyp-build-optional": "optional.js",
+        "node-gyp-build-test": "build-test.js"
+      }
+    },
+    "node_modules/osc": {
+      "version": "2.4.4",
+      "resolved": "https://registry.npmjs.org/osc/-/osc-2.4.4.tgz",
+      "integrity": "sha512-YJr2bUCQMc9BIaq1LXgqYpt5Ii7wNy2n0e0BkQiCSziMNrrsYHhH5OlExNBgCrQsum60EgXZ32lFsvR4aUf+ew==",
+      "dependencies": {
+        "long": "4.0.0",
+        "slip": "1.0.2",
+        "wolfy87-eventemitter": "5.2.9",
+        "ws": "8.13.0"
+      },
+      "optionalDependencies": {
+        "serialport": "10.5.0"
+      }
+    },
+    "node_modules/osc/node_modules/ws": {
+      "version": "8.13.0",
+      "resolved": "https://registry.npmjs.org/ws/-/ws-8.13.0.tgz",
+      "integrity": "sha512-x9vcZYTrFPC7aSIbj7sRCYo7L/Xb8Iy+pW0ng0wt2vCJv7M9HOMy0UoN3rr+IFC7hb7vXoqS+P9ktyLLLhO+LA==",
+      "engines": {
+        "node": ">=10.0.0"
+      },
+      "peerDependencies": {
+        "bufferutil": "^4.0.1",
+        "utf-8-validate": ">=5.0.2"
+      },
+      "peerDependenciesMeta": {
+        "bufferutil": {
+          "optional": true
+        },
+        "utf-8-validate": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/serialport": {
+      "version": "10.5.0",
+      "resolved": "https://registry.npmjs.org/serialport/-/serialport-10.5.0.tgz",
+      "integrity": "sha512-7OYLDsu5i6bbv3lU81pGy076xe0JwpK6b49G6RjNvGibstUqQkI+I3/X491yBGtf4gaqUdOgoU1/5KZ/XxL4dw==",
+      "optional": true,
+      "dependencies": {
+        "@serialport/binding-mock": "10.2.2",
+        "@serialport/bindings-cpp": "10.8.0",
+        "@serialport/parser-byte-length": "10.5.0",
+        "@serialport/parser-cctalk": "10.5.0",
+        "@serialport/parser-delimiter": "10.5.0",
+        "@serialport/parser-inter-byte-timeout": "10.5.0",
+        "@serialport/parser-packet-length": "10.5.0",
+        "@serialport/parser-readline": "10.5.0",
+        "@serialport/parser-ready": "10.5.0",
+        "@serialport/parser-regex": "10.5.0",
+        "@serialport/parser-slip-encoder": "10.5.0",
+        "@serialport/parser-spacepacket": "10.5.0",
+        "@serialport/stream": "10.5.0",
+        "debug": "^4.3.3"
+      },
+      "engines": {
+        "node": ">=12.0.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/serialport/donate"
+      }
+    },
+    "node_modules/slip": {
+      "version": "1.0.2",
+      "resolved": "https://registry.npmjs.org/slip/-/slip-1.0.2.tgz",
+      "integrity": "sha512-XrcHe3NAcyD3wO+O4I13RcS4/3AF+S9RvGNj9JhJeS02HyImwD2E3QWLrmn9hBfL+fB6yapagwxRkeyYzhk98g=="
+    },
+    "node_modules/wolfy87-eventemitter": {
+      "version": "5.2.9",
+      "resolved": "https://registry.npmjs.org/wolfy87-eventemitter/-/wolfy87-eventemitter-5.2.9.tgz",
+      "integrity": "sha512-P+6vtWyuDw+MB01X7UeF8TaHBvbCovf4HPEMF/SV7BdDc1SMTiBy13SRD71lQh4ExFTG1d/WNzDGDCyOKSMblw=="
+    },
+    "node_modules/ws": {
+      "version": "8.17.1",
+      "resolved": "https://registry.npmjs.org/ws/-/ws-8.17.1.tgz",
+      "integrity": "sha512-6XQFvXTkbfUOZOKKILFG1PDK2NDQs4azKQl26T0YS5CxqWLgXajbPZ+h4gZekJyRqFU8pvnbAbbs/3TgRPy+GQ==",
+      "engines": {
+        "node": ">=10.0.0"
+      },
+      "peerDependencies": {
+        "bufferutil": "^4.0.1",
+        "utf-8-validate": ">=5.0.2"
+      },
+      "peerDependenciesMeta": {
+        "bufferutil": {
+          "optional": true
+        },
+        "utf-8-validate": {
+          "optional": true
+        }
+      }
+    }
+  }
+}

ToposServer/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "topos-server",
+  "version": "0.0.1",
+  "description": "Topos OSC Server",
+  "main": "index.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "author": "Raphaël Forment",
+  "license": "GPL-3.0-or-later",
+  "dependencies": {
+    "osc": "^2.4.4",
+    "ws": "^8.17.1"
+  }
+}

ToposServer/server.js

@@ -0,0 +1,8 @@
+const WebSocket = require("ws");
+const osc = require("osc");
+
+require("./banner").greet();
+// Topos to OSC
+require("./ToposToOSC");
+// OSC to Topos
+require("./OSCtoTopos");

favicon/site.webmanifest

@@ -1,19 +0,0 @@
-{
-  "name": "",
-  "short_name": "",
-  "icons": [
-    {
-      "src": "/android-chrome-192x192.png",
-      "sizes": "192x192",
-      "type": "image/png"
-    },
-    {
-      "src": "/android-chrome-512x512.png",
-      "sizes": "512x512",
-      "type": "image/png"
-    }
-  ],
-  "theme_color": "#ffffff",
-  "background_color": "#ffffff",
-  "display": "standalone"
-}

index.html

@@ -1,25 +1,24 @@
-<!doctype html>
+  <!doctype html>
 <html lang="en">
   <head>
-    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <meta name="description" content="Topos is a live coding environment inspired by the Monome Teletype.">
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
     <title>Topos</title>
+    <meta name="description" content="Topos is a live coding environment inspired by the Monome Teletype.">
     <meta charset="UTF-8" />
-    <link rel="apple-touch-icon" sizes="180x180" href="favicon/apple-touch-icon.png">
-    <link rel="icon" type="image/png" sizes="32x32" href="favicon/favicon-32x32.png">
-    <link rel="icon" type="image/png" sizes="16x16" href="favicon/favicon-16x16.png">
+    <link rel="icon" href="/favicon/favicon.ico" sizes="48x48" ><!-- REVISED (Aug 11, 2023)! -->
+    <link rel="icon" href="/favicon/favicon.svg" sizes="any" type="image/svg+xml"><!-- REVISED (Aug 11, 2023)! -->
+    <link rel="apple-touch-icon" href="/favicon/apple-touch-icon.png"/>
+    <link rel="manifest" href="/manifest.webmanifest" />
     <link rel="mask-icon" href="favicon/safari-pinned-tab.svg" color="#5bbad5">
     <meta name="msapplication-TileColor" content="#da532c">
     <meta name="theme-color" content="#ffffff">
-    <link rel="stylesheet" href="/src/output.css" />
     <link rel="stylesheet" href='/fonts/index.css' >
+    <link rel="stylesheet" href="/src/output.css" />
     <script src="https://unpkg.com/hydra-synth"></script>
   </head>
   <style>
-
     body {
       font-family: "Arial";
-      background-color: #111827;
 			overflow: hidden;
 			position: fixed;
 			width: 100vw;
@@ -28,10 +27,21 @@
       padding: 0;
     }
 
-    .fluid-bg-transition {
+    .fluid-transition {
       transition: background-color 0.05s ease-in-out;
     }
 
+    .hydracanvas {
+      position: fixed; /* ignore margins */
+      top: 0px;
+      left: 0px;
+      width: 100%; /* fill screen */
+      height: 100%;
+      background-size: cover;
+      overflow-y: hidden;
+      z-index: -5; /* place behind everything else */
+      display: block;
+    }
 
     .fullscreencanvas {
       position: fixed; /* ignore margins */
@@ -66,60 +76,89 @@
 			z-index: 0;
     }
 
+    .bar_button {
+      @apply mx-2 px-2 py-2 flex inline rounded-lg bg-background text-foreground  hover:bg-foreground hover:text-background
+    }
+
+    .side_button {
+      @apply px-2 py-2 bg-background text-foreground rounded-lg hover:bg-foreground hover:text-background
+    }
+
+    .subtitle {
+      @apply bg-selection_foreground text-sm lg:text-xl border-b py-4 text-foreground
+    }
+    
+    .tab_panel {
+      @apply inline-block lg:px-4 px-8 py-1 text-brightwhite
+    }
+
+    .doc_header {
+      @apply pl-2 pr-2 lg:text-xl text-sm py-1 my-1 rounded-lg text-white hover:text-brightwhite hover:bg-brightblack
+    }
+
+    .doc_subheader {
+      @apply pl-2 pr-2 lg:text-xl text-sm ml-6 py-1 my-1 rounded-lg text-white hover:text-brightwhite hover:bg-brightblack
+    }
+
+
   </style>
-  <body id="all" class="z-0 bg-neutral-800 overflow-y-hidden">
 
+  <body id="all" class="z-0 overflow-y-hidden bg-black">
 		<!-- The header is hidden on smaller devices -->
-    <header class="py-0 block text-white bg-neutral-900">
-      <div id="topbar" class="mx-auto flex flex-wrap pl-2 py-1 flex-row items-center">
-        <a class="flex title-font font-medium items-center text-black mb-0">
-          <img id="topos-logo" src="topos_frog.svg" class="w-12 h-12 text-black p-2 bg-white rounded-full" alt="Topos Frog Logo" />
-         <input id="universe-viewer" class="hidden bg-transparent xl:block ml-4 text-2xl text-white placeholder-white" id="renamer" type="text" placeholder="Topos">
-
+    <header class="py-0 block">
+      <div id="topbar" class="mx-auto flex flex-wrap pl-2 py-1 flex-row items-center bg-background">
+        <a class="flex title-font font-medium items-center mb-0">
+          <img id="topos-logo" src="topos_frog.svg" class="w-12 h-12 text-selection_foreground p-2 rounded-full bg-foreground" alt="Topos Frog Logo"/>
+         <input id="universe-viewer" class="hidden transparent xl:block ml-4 text-2xl bg-background text-brightwhite placeholder-brightwhite" id="renamer" type="text" placeholder="Topos">
         </a>
         <nav class="py-2 flex flex-wrap items-center text-base absolute right-0">
-         <a title="Play button (Ctrl+P)" id="play-button-1" class="flex flex-row mr-2 hover:bg-gray-800 px-2 py-2 rounded-lg">
+         <!-- Play Button -->
+         <a title="Play button (Ctrl+P)" id="play-button-1" class="bar_button">
 							<svg id="play-icon" class="w-7 h-7" fill="currentColor" viewBox="0 0 14 16">
 								<path d="M0 .984v14.032a1 1 0 0 0 1.506.845l12.006-7.016a.974.974 0 0 0 0-1.69L1.506.139A1 1 0 0 0 0 .984Z"/>
 							</svg>
-							<svg id="pause-icon" class="hidden w-7 h-7 text-white" aria-hidden="true" xmlns="http://www.w3.org/2000/svg" fill="currentColor" viewBox="0 0 20 20">
+							<svg id="pause-icon" class="hidden w-7 h-7" aria-hidden="true" xmlns="http://www.w3.org/2000/svg" fill="currentColor" viewBox="0 0 20 20">
     <path d="M10 .5a9.5 9.5 0 1 0 9.5 9.5A9.51 9.51 0 0 0 10 .5ZM9 13a1 1 0 0 1-2 0V7a1 1 0 0 1 2 0v6Zm4 0a1 1 0 0 1-2 0V7a1 1 0 0 1 2 0v6Z"/>
   </svg>
-							<p id="play-label" class="hidden lg:block text-xl pl-2 text-white inline-block">Play</p>
+							<p id="play-label" class="hidden lg:block text-xl pl-2 inline-block">Play</p>
           </a>
-          <a title="Stop button (Ctrl+R)" id="stop-button-1" class="flex flex-row mr-2 hover:bg-gray-800 px-2 py-2 rounded-lg">
-						<svg class="w-7 h-7 text-white" aria-hidden="true" xmlns="http://www.w3.org/2000/svg" fill="currentColor" viewBox="0 0 20 20">
+
+          <!-- Stop button -->
+          <a title="Stop button (Ctrl+R)" id="stop-button-1" class="bar_button">
+						<svg class="w-7 h-7 " aria-hidden="true" xmlns="http://www.w3.org/2000/svg" fill="currentColor" viewBox="0 0 20 20">
   <path d="M10 .5a9.5 9.5 0 1 0 9.5 9.5A9.51 9.51 0 0 0 10 .5Z"/>
-  <rect x="6.5" y="6.5" width="7" height="7" fill="black" rx="1" ry="1"/>
+  <rect x="6.5" y="6.5" width="7" height="7" fill="selection_background" rx="1" ry="1"/>
 </svg>
-						<p class="hidden lg:block text-xl pl-2 text-white inline-block">Stop</p>
+						<p class="hidden lg:block text-xl pl-2 inline-block">Stop</p>
           </a>
-          <a title="Eval button (Ctrl+Enter)" id="eval-button-1" class="flex flex-row mr-2 hover:text-gray-900 hover:bg-gray-800 px-2 py-2 rounded-lg">
-						<svg class="w-7 h-7 text-white" aria-hidden="true" xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 18 20">
+
+          <!-- Eval button -->
+          <a title="Eval button (Ctrl+Enter)" id="eval-button-1" class="bar_button">
+						<svg class="w-7 h-7 " aria-hidden="true" xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 18 20">
     <path stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M16 1v5h-5M2 19v-5h5m10-4a8 8 0 0 1-14.947 3.97M1 10a8 8 0 0 1 14.947-3.97"/>
   </svg>
-					<p class="hidden lg:block text-xl pl-2 text-white inline-block">Eval</p>
+					<p class="hidden lg:block text-xl pl-2 inline-block">Eval</p>
           </a>
 
-          <a title="Clear button" id="clear-button-1" class="flex flex-row mr-2 hover:text-gray-900 hover:bg-gray-800 px-2 py-2 rounded-lg">
-						<svg class="w-7 h-7 text-white" aria-hidden="true" xmlns="http://www.w3.org/2000/svg" fill="currentColor" viewBox="0 0 18 20">
+          <a title="Clear button" id="clear-button-1" class="bar_button">
+						<svg class="w-7 h-7 " aria-hidden="true" xmlns="http://www.w3.org/2000/svg" fill="currentColor" viewBox="0 0 18 20">
     <path d="M17 4h-4V2a2 2 0 0 0-2-2H7a2 2 0 0 0-2 2v2H1a1 1 0 0 0 0 2h1v12a2 2 0 0 0 2 2h10a2 2 0 0 0 2-2V6h1a1 1 0 1 0 0-2ZM7 2h4v2H7V2Zm1 14a1 1 0 1 1-2 0V8a1 1 0 0 1 2 0v8Zm4 0a1 1 0 0 1-2 0V8a1 1 0 0 1 2 0v8Z"/>
   </svg>
-						<p class="hidden lg:block text-xl pl-2 text-white inline-block">Clear</p>
+						<p class="hidden lg:block text-xl pl-2 inline-block">Clear</p>
           </a>
 
-          <a title="Share button" id="share-button" class="flex flex-row mr-2 hover:text-gray-900 hover:bg-gray-800 px-2 py-2 rounded-lg">
-						<svg class="w-7 h-7 text-white" aria-hidden="true" xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 19 19">
+          <a title="Share button" id="share-button" class="bar_button">
+						<svg class="w-7 h-7 " aria-hidden="true" xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 19 19">
     <path stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M11.013 7.962a3.519 3.519 0 0 0-4.975 0l-3.554 3.554a3.518 3.518 0 0 0 4.975 4.975l.461-.46m-.461-4.515a3.518 3.518 0 0 0 4.975 0l3.553-3.554a3.518 3.518 0 0 0-4.974-4.975L10.3 3.7"/>
   </svg>
-						<p class="hidden lg:block text-xl pl-2 text-white inline-block">Share</p>
+						<p class="hidden lg:block text-xl pl-2 inline-block">Share</p>
           </a>
 
-          <a title="Open Documentation (Ctrl+D)" id="doc-button-1" class="flex flex-row hover:text-gray-900 hover:bg-gray-800 px-2 py-2 rounded-lg">
-						<svg class="w-7 h-7 text-white" aria-hidden="true" xmlns="http://www.w3.org/2000/svg" fill="currentColor" viewBox="0 0 20 20">
+          <a title="Open Documentation (Ctrl+D)" id="doc-button-1" class="bar_button">
+						<svg class="w-7 h-7 " aria-hidden="true" xmlns="http://www.w3.org/2000/svg" fill="currentColor" viewBox="0 0 20 20">
     <path d="M10 .5a9.5 9.5 0 1 0 9.5 9.5A9.51 9.51 0 0 0 10 .5ZM9.5 4a1.5 1.5 0 1 1 0 3 1.5 1.5 0 0 1 0-3ZM12 15H8a1 1 0 0 1 0-2h1v-3H8a1 1 0 0 1 0-2h2a1 1 0 0 1 1 1v4h1a1 1 0 0 1 0 2Z"/>
   </svg>
-						<p class="hidden lg:block text-xl pl-2 text-white inline-block">Docs</p>
+						<p class="hidden lg:block text-xl pl-2 inline-block">Docs</p>
           </a>
  
         </nav>
@@ -128,121 +167,135 @@
     </header>
 
     <div id="documentation" class="hidden">
-      <div id="documentation-page" class="flex flex-row bg-transparent">
-        <aside class="w-1/8 flex-shrink-0 h-screen overflow-y-auto p-1 lg:p-6 bg-neutral-900 text-white">
-          <nav class="text-xl sm:text-sm overflow-y-scroll mb-24">
-            <details class="" open=true>
+      <div id="documentation-page" class="flex flex-row transparent">
+        <aside class="w-1/8 flex-shrink-0 h-screen overflow-y-auto p-1 lg:p-6 bg-background">
+          <nav class="text-xl sm:text-sm overflow-y-scroll mb-24 bg-background">
+            <details class="" open>
               <summary class="font-semibold lg:text-xl text-orange-300">Basics</summary>
               <div class="flex flex-col">
-                <p rel="noopener noreferrer" id="docs_introduction" class="pl-2 pr-2 lg:text-xl text-sm hover:bg-neutral-800 py-1 my-1 rounded-lg">Welcome </p>
-                <p rel="noopener noreferrer" id="docs_interface" class="pl-2 pr-2 lg:text-xl text-sm hover:bg-neutral-800 py-1 my-1 rounded-lg">Interface</p>
-                <p rel="noopener noreferrer" id="docs_interaction" class="pl-2 pr-2 lg:text-xl text-sm hover:bg-neutral-800 py-1 my-1 rounded-lg">Interaction</p>
-                <p rel="noopener noreferrer" id="docs_shortcuts" class="pl-2 pr-2 lg:text-xl text-sm hover:bg-neutral-800 py-1 my-1 rounded-lg">Keyboard</p>
-                <p rel="noopener noreferrer" id="docs_mouse" class="pl-2 pr-2 lg:text-xl text-sm hover:bg-neutral-800 py-1 my-1 rounded-lg">Mouse</p>
-                <p rel="noopener noreferrer" id="docs_code" class="pl-2 pr-2 lg:text-xl text-sm hover:bg-neutral-800 py-1 my-1 rounded-lg">Coding</p>
+                <p rel="noopener noreferrer" id="docs_introduction" class="doc_header">Welcome </p>
+                <p rel="noopener noreferrer" id="docs_atelier" class="doc_header">Atelier (FR)</p>
+                <p rel="noopener noreferrer" id="docs_interface" class="doc_header">Interface</p>
+                <p rel="noopener noreferrer" id="docs_interaction" class="doc_header">Interaction</p>
+                <p rel="noopener noreferrer" id="docs_shortcuts" class="doc_header">Keyboard</p>
+                <p rel="noopener noreferrer" id="docs_mouse" class="doc_header">Mouse</p>
+                <p rel="noopener noreferrer" id="docs_code" class="doc_header">Coding</p>
 							</div>
 						</details>
-            <details class="space-y-2" open=true>
+            <details class="space-y-2" open>
               <summary class="font-semibold lg:text-xl pb-1 pt-1 text-orange-300">Learning</summary>
               <div class="flex flex-col">
-
                 <!-- Time -->
-                <details class="space-y-2" open=false>
-                  <summary class="ml-2 lg:text-xl pb-1 pt-1 text-white">Time</summary>
+                <details class="space-y-2">
+                  <summary class="ml-2 lg:text-xl pb-1 pt-1 doc_header">Time</summary>
                   <div class="flex flex-col">
-                    <p rel="noopener noreferrer" id="docs_time" class="ml-8 pr-2 lg:text-xl text-sm hover:bg-neutral-800 py-1 my-1 rounded-lg">Dealing with time</p>
-                    <p rel="noopener noreferrer" id="docs_linear" class="ml-8 pr-2 lg:text-xl text-sm hover:bg-neutral-800 py-1 my-1 rounded-lg">Time & Transport</p>
-                    <p rel="noopener noreferrer" id="docs_cyclic" class="ml-8 pr-2 lg:text-xl text-sm hover:bg-neutral-800 py-1 my-1 rounded-lg">Time & Cycles</p>
-                    <p rel="noopener noreferrer" id="docs_longform" class="ml-8 pr-2 lg:text-xl text-sm hover:bg-neutral-800 py-1 my-1 rounded-lg">Time & Structure</p>
-                  </div>
-                </details>
-
-                <!-- Samples -->
-                <details class="space-y-2" open=false>
-                  <summary class="ml-2 lg:text-xl pb-1 pt-1 text-white">Audio Engine</summary>
-                  <div class="flex flex-col">
-                    <p rel="noopener noreferrer" id="docs_audio_basics" class="ml-8 pr-2 lg:text-xl text-sm hover:bg-neutral-800 py-1 my-1 rounded-lg">Playing a sound</p>
-                    <p rel="noopener noreferrer" id="docs_amplitude" class="ml-8 pr-2 lg:text-xl text-sm hover:bg-neutral-800 py-1 my-1 rounded-lg">Amplitude</p>
-                    <p rel="noopener noreferrer" id="docs_sampler" class="ml-8 pr-2 lg:text-xl text-sm hover:bg-neutral-800 py-1 my-1 rounded-lg">Sampler</p>
-                    <p rel="noopener noreferrer" id="docs_synths" class="ml-8 pr-2 lg:text-xl text-sm hover:bg-neutral-800 py-1 my-1 rounded-lg">Synths</p>
-                    <p rel="noopener noreferrer" id="docs_reverb_delay" class="ml-8 pr-2 lg:text-xl text-sm hover:bg-neutral-800 py-1 my-1 rounded-lg">Effects</p>
+                    <p rel="noopener noreferrer" id="docs_time" class="doc_subheader">Dealing with time</p>
+                    <p rel="noopener noreferrer" id="docs_linear" class="doc_subheader">Time & Transport</p>
+                    <p rel="noopener noreferrer" id="docs_cyclic" class="doc_subheader">Time & Cycles</p>
+                    <p rel="noopener noreferrer" id="docs_longform" class="doc_subheader">Time & Structure</p>
                   </div>
                 </details>
 
                 <!-- Audio Engine -->
-                <details class="space-y-2" open=false>
-                  <summary class="ml-2 lg:text-xl pb-1 pt-1 text-white">Samples</summary>
+                <details class="space-y-2">
+                  <summary class="ml-2 lg:text-xl pb-1 pt-1 doc_header">Audio Engine</summary>
                   <div class="flex flex-col">
-                    <p rel="noopener noreferrer" id="docs_sample_list" class="ml-8 pr-2 lg:text-xl text-sm hover:bg-neutral-800 py-1 my-1 rounded-lg">List of samples</p>
-                    <p rel="noopener noreferrer" id="docs_loading_samples" class="ml-8 pr-2 lg:text-xl text-sm hover:bg-neutral-800 py-1 my-1 rounded-lg">Loading Samples</p>
+                    <p rel="noopener noreferrer" id="docs_audio_basics" class="doc_subheader">Playing a sound</p>
+                    <p rel="noopener noreferrer" id="docs_amplitude" class="doc_subheader">Amplitude</p>
+                    <p rel="noopener noreferrer" id="docs_sampler" class="doc_subheader">Sampler</p>
+                    <p rel="noopener noreferrer" id="docs_synths" class="doc_subheader">Synths</p>
+                    <p rel="noopener noreferrer" id="docs_filters" class="doc_subheader">Filters</p>
+                    <p rel="noopener noreferrer" id="docs_effects" class="doc_subheader">Effects</p>
                   </div>
                 </details>
 
-                <p rel="noopener noreferrer" id="docs_patterns" class="pl-2 pr-2 lg:text-xl text-sm hover:bg-neutral-800 py-1 my-1 rounded-lg">Patterns</p>
-                <p rel="noopener noreferrer" id="docs_midi" class="pl-2 pr-2 lg:text-xl text-sm hover:bg-neutral-800 py-1 my-1 rounded-lg">MIDI</p>
+                <!-- Samples -->
+                <details class="space-y-2">
+                  <summary class="ml-2 lg:text-xl pb-1 pt-1 doc_header ">Samples</summary>
+                  <div class="flex flex-col">
+                    <p rel="noopener noreferrer" id="docs_sample_list" class="doc_subheader">List of samples</p>
+                    <p rel="noopener noreferrer" id="docs_loading_samples" class="doc_subheader">External samples</p>
+                  </div>
+                </details>
+                <p rel="noopener noreferrer" id="docs_midi" class="doc_header">MIDI</p>
+                <p rel="noopener noreferrer" id="docs_osc" class="doc_header">OSC</p>
 							</div>
 						</details>
-            <details class="space-y-2" open=true>
+            <details class="space-y-2" open>
               <summary class="font-semibold lg:text-xl pb-1 pt-1 text-orange-300">Patterns</summary>
               <div class="flex flex-col">
-                
-                <p rel="noopener noreferrer" id="docs_variables" class="pl-2 pr-2 lg:text-xl text-sm hover:bg-neutral-800 py-1 my-1 rounded-lg">Global Variables</p>
-                <p rel="noopener noreferrer" id="docs_lfos" class="pl-2 pr-2 lg:text-xl text-sm hover:bg-neutral-800 py-1 my-1 rounded-lg">Low Freq Oscs.</p>
-                <p rel="noopener noreferrer" id="docs_probabilities" class="pl-2 pr-2 lg:text-xl text-sm hover:bg-neutral-800 py-1 my-1 rounded-lg">Probabilities</p>
-                <p rel="noopener noreferrer" id="docs_chaining" class="pl-2 pr-2 lg:text-xl text-sm hover:bg-neutral-800 py-1 my-1 rounded-lg">Chaining</p>
-                <p rel="noopener noreferrer" id="docs_functions" class="pl-2 pr-2 lg:text-xl text-sm hover:bg-neutral-800 py-1 my-1 rounded-lg">Functions</p>
-                <p rel="noopener noreferrer" id="docs_ziffers" class="pl-2 pr-2 lg:text-xl text-sm hover:bg-neutral-800 py-1 my-1 rounded-lg">Ziffers</p>
-								<!--
-                <p rel="noopener noreferrer" id="docs_reference" class="pl-2 pr-2 lg:text-xl text-sm hover:bg-neutral-800 py-1 my-1 rounded-lg">Reference</p>
-								-->
+
+                <p rel="noopener noreferrer" id="docs_patterns" class="pl-2 pr-2 lg:text-xl text-sm hover:neutral-800 py-1 my-1 rounded-lg doc_header">Array patterns</p>
+                <!-- Ziffers -->
+                <details class="space-y-2">
+                  <summary class="doc_header">Ziffers</summary>
+                  <div class="flex flex-col">
+                    <p rel="noopener noreferrer" id="docs_ziffers_basics" class="doc_subheader">Basics</p>
+                    <p rel="noopener noreferrer" id="docs_ziffers_scales" class="doc_subheader">Scales</p>
+                    <p rel="noopener noreferrer" id="docs_ziffers_rhythm" class="doc_subheader">Rhythm</p>
+                    <p rel="noopener noreferrer" id="docs_ziffers_algorithmic" class="doc_subheader">Algorithmic</p>
+                    <p rel="noopener noreferrer" id="docs_ziffers_tonnetz" class="doc_subheader">Tonnetz</p>
+                    <p rel="noopener noreferrer" id="docs_ziffers_syncing" class="doc_subheader">Syncing</p>
+                  </div>
+                </details>
+                <p rel="noopener noreferrer" id="docs_variables" class="doc_header">Global Variables</p>
+                <p rel="noopener noreferrer" id="docs_lfos" class="doc_header">Low Freq Oscs.</p>
+                <p rel="noopener noreferrer" id="docs_probabilities" class="doc_header">Probabilities</p>
+                <p rel="noopener noreferrer" id="docs_chaining" class="doc_header">Chaining</p>
+                <p rel="noopener noreferrer" id="docs_functions" class="doc_header">Functions</p>
+                <p rel="noopener noreferrer" id="docs_generators" class="doc_header">Generators</p>
               </div>
             </details>
-            <details class="space-y-2" open=true>
-              <summary class="font-semibold lg:text-xl text-orange-300">More</summary>
+            <details class="space-y-2" open>
+              <summary class="font-semibold lg:text-xl doc_header">More</summary>
               <div class="flex flex-col">
-                <a rel="noopener noreferrer" id="docs_synchronisation" class="pl-2 pr-2 lg:text-xl text-sm hover:bg-neutral-800 py-1 my-1 rounded-lg">Synchronisation</a>
-                <a rel="noopener noreferrer" id="docs_oscilloscope" class="pl-2 pr-2 lg:text-xl text-sm hover:bg-neutral-800 py-1 my-1 rounded-lg">Oscilloscope</a>
-                <a rel="noopener noreferrer" id="docs_bonus" class="pl-2 pr-2 lg:text-xl text-sm hover:bg-neutral-800 py-1 my-1 rounded-lg">Bonus/Trivia</a>
-                <a rel="noopener noreferrer" id="docs_about" class="pl-2 pr-2 lg:text-xl text-sm hover:bg-neutral-800 py-1 my-1 rounded-lg">About Topos</a>
+                <a rel="noopener noreferrer" id="docs_synchronisation" class="doc_subheader">Synchronisation</a>
+                <a rel="noopener noreferrer" id="docs_oscilloscope" class="doc_subheader">Oscilloscope</a>
+                <a rel="noopener noreferrer" id="docs_visualization" class="doc_header">Visualization</a>
+                <a rel="noopener noreferrer" id="docs_bonus" class="doc_header">Bonus/Trivia</a>
+                <a rel="noopener noreferrer" id="docs_about" class="doc_header">About Topos</a>
               </div>
             </details>
-            <details class="" open=true>
+            <details class="" open>
               <summary class="font-semibold lg:text-xl text-orange-300">Community</summary>
                 <form action="https://github.com/Bubobubobubobubo/topos">
-                  <input rel="noopener noreferrer" id="docs_introduction" class="pl-2 pr-2 lg:text-xl text-sm hover:bg-neutral-800 py-1 my-1 rounded-lg" type="submit" value="GitHub" />
+                  <input rel="noopener noreferrer" id="github_link" class="doc_header" type="submit" value="GitHub" />
                 </form>
                 <form action="https://discord.gg/6T67DqBNNT">
-                  <input rel="noopener noreferrer" id="docs_introduction" class="pl-2 pr-2 lg:text-xl text-sm hover:bg-neutral-800 py-1 my-1 rounded-lg" type="submit" value="Discord" />
+                  <input rel="noopener noreferrer" id="discord_link" class="doc_header" type="submit" value="Discord" />
+                </form>
+                <form action="https://ko-fi.com/raphaelbubo">
+                  <input rel="noopener noreferrer" id="support_link" class="doc_header" type="submit" value="Support" />
                 </form>
             </details>
          </nav>
         </aside>
-        <div id="documentation-content" class="w-full flex-grow-1 h-screen overflow-y-scroll lg:px-12 mx-2 my-2 break-words pb-32 bg-transparent"></div>
+        <div id="documentation-content" class="w-full flex-grow-1 h-screen overflow-y-scroll lg:px-12 mx-2 my-2 break-words pb-32 transparent"></div>
         </div>
       </div>
     </div>
 
     <div id="app">
       <!-- This modal is used for switching between buffers -->
-      <div id="modal-buffers" class="invisible bg-gray-900 bg-opacity-50 flex justify-center items-center absolute top-0 right-0 bottom-0 left-0">
-        <div id="start-button" class="lg:px-16 px-4 lg:pt-4 lg:pb-4 pt-2 pb-2 rounded-md text-center bg-white">
-					<p class="text-semibold lg:text-2xl text-sm pb-4">Known universes</p>
+      <div id="modal-buffers" class="invisible flex justify-center items-center absolute top-0 right-0 bottom-0 left-0">
+        <div id="start-button" class="lg:px-16 px-4 lg:pt-4 lg:pb-4 pt-2 pb-2 rounded-md text-center bg-foreground">
+					<p class="text-semibold lg:text-2xl text-sm pb-4 text-selection_foreground">Known universes</p>
 					<p id="existing-universes" class="text-normal lg:h-auto h-48 overflow-y-auto mb-2"></p>
           <div id="disclaimer" class="pb-4">
           <form id="universe-creator">
-            <label for="search" class="mb-2 text-sm font-medium text-gray-900 sr-only text-white">Search</label>
+            <label for="search" class="mb-2 text-sm font-medium sr-only ">Search</label>
             <div class="relative">
             <div class="absolute inset-y-0 left-0 flex items-center pl-3 pointer-events-none">
-            <svg class="w-4 h-4 text-gray-500 text-gray-400" aria-hidden="true" xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 20 20">
+            <svg class="w-4 h-4" aria-hidden="true" xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 20 20">
                 <path stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="m19 19-4-4m0-7A7 7 0 1 1 1 8a7 7 0 0 1 14 0Z"/>
             </svg>
         </div>
-                <input name="universe" minlength="2" autocomplete="off" type="text" id="buffer-search" class="block w-full p-4 pl-10 text-sm border border-neutral-800 outline-0 rounded-lg bg-neutral-800 text-white" placeholder="Buffer..." required>
-                <button id="load-universe-button" class="text-black absolute right-2.5 bottom-2.5 bg-white hover:bg-white focus:outline-none font-medium rounded-lg text-sm px-4 py-2">Go</button>
+                <input name="universe" minlength="2" autocomplete="off" type="text" id="buffer-search" class="block w-full p-4 pl-10 text-sm border border-neutral-800 outline-0 rounded-lg neutral-800 " placeholder="Buffer..." required>
+                <button id="load-universe-button" class="bg-background text-selection_background absolute right-2.5 bottom-2.5 focus:outline-none font-medium rounded-lg text-sm px-4 py-2">Go</button>
             </div>
           </form>
-              <div class="mt-2 flex space-x-6 border-t border-gray-200 rounded-b dark:border-gray-600 border-spacing-y-4">
-                <button id="close-universes-button" data-modal-hide="defaultModal" type="button" class="mt-2 hover:bg-neutral-700 bg-neutral-800 text-white focus:ring-4  font-medium rounded-lg text-sm px-5 py-2.5 text-center">Close</button>
+              <div class="mt-2 flex space-x-6 border-t  rounded-b  border-spacing-y-4">
+                <button id="close-universes-button" data-modal-hide="defaultModal" type="button" class="mt-2 focus:ring-4 font-medium rounded-lg text-sm px-5 py-2.5 text-center bg-background text-selection_background">Close</button>
               </div>
 
           </div>
@@ -251,29 +304,26 @@
 
       <!-- This modal is used for settings -->
       <div id="modal-settings" class="invisible flex
-              absolute lg:justify-center lg:items-center 
+              absolute lg:justify-center lg:items-center
               lg:overflow-y-auto lg:overflow-x-auto
               overflow-y-scroll owerflow-x-scroll
               md:top-0 md:bottom-0 h-screen w-full"
       >
         <div class="grid w-full grid-col-3">
-          <div class="bg-white rounded-lg lg:mx-48 mx-0 lg:space-y-8 space-y-4 lg:px-8">
-          <h1 class="lg:mt-12 mt-6 font-semibold rounded-lg
-                     bg-gray-800 justify-center lg:text-center lg:pl-0 pl-8 text-white mx-4
-                     text-sm lg:text-xl border-b border-gray-300 py-4">Topos Application Settings</h1>
+          <div class="white rounded-lg lg:mx-48 mx-0 lg:space-y-8 space-y-4 lg:px-8 bg-foreground">
+          <h1 class="lg:mt-12 mt-6 font-semibold rounded-lg justify-center lg:text-center lg:pl-0 pl-8 mx-4 subtitle">Topos Application Settings</h1>
             <div class="flex lg:flex-row flex-col mr-4 ml-4">
             <!-- Font Size Selection -->
-              <div class="bg-gray-200 rounded-lg ml-0 lg:w-1/3 w-full pt-2 pb-1 mb-2">
-                <p class="font-bold lg:text-xl text-sm ml-4 lg:pb-4 pb-2 underline underline-offset-4">Font Settings</p>
+              <div class="rounded-lg ml-0 lg:w-1/3 w-full pt-2 pb-1 mb-2 bg-selection_foreground">
+                <p class="font-bold lg:text-xl text-sm ml-4 lg:pb-4 pb-2 underline underline-offset-4 text-selection_background">Theme Settings</p>
                 <div class="mb-6 mx-4 font-semibold">
-                  <label for="default-input" class="block mb-2 ml-1 font-normal sd:text-sm">Size:</label>
-                  <input type="text" id="font-size-input" type="number" class="bg-gray-50 border border-gray-300 text-gray-900 
-                  text-sm rounded-lg focus:ring-blue-500 focus:border-blue-500 block w-full p-2.5 dark:bg-gray-700 
-                  dark:border-gray-600 dark:placeholder-gray-400 dark:text-white dark:focus:ring-blue-500 dark:focus:border-blue-500">
+                  <label for="default-input" class="block mb-2 ml-1 font-normal sd:text-sm text-foreground">Size:</label>
+                  <input type="text" id="font-size-input" type="number" class="border
+                  text-sm rounded-lg  focus:border-blue-500 block w-full p-2.5 focus:border-blue-500">
                 </div>
-                <label for="font" class="block ml-5 mb-2 font-medium sd:text-sm">Font:</label>
-                  <select id="font-family" class="bg-gray-50 ml-4 border border-gray-300 mb-2
-                  text-gray-900 text-sm rounded-lg focus:ring-blue-500 focus:border-blue-500 block  p-2.5 dark:bg-gray-700 dark:border-gray-600 dark:placeholder-gray-400 dark:text-white">
+                <label for="font" class="block ml-5 mb-2 font-medium sd:text-sm text-foreground">Font:</label>
+                  <select id="font-family" class=" ml-4 border mb-2
+                  text-sm rounded-lg  focus:border-blue-500 block  p-2.5">
                     <option value="IBM Plex Mono">IBM Plex Mono</option>
                     <option value="Jet Brains">Jet Brains</option>
                     <option value="Courier">Courier</option>
@@ -285,186 +335,201 @@
                     <option value="Steps Mono">Steps Mono</option>
                     <option value="Steps Mono Thin">Steps Mono Thin</option>
                   </select>
+              <div class="rounded-lg ml-0 lg:w-1/3 w-full pt-2 pb-1 mb-2">
+                <label for="theme" class="block ml-5 mb-2 font-medium sd:text-sm text-foreground">Theme:</label>
+                  <select id="theme-selector" class="ml-4 border mb-2
+                  text-sm rounded-lg block  p-2.5">
+                  </select>
+                  <div id="theme-previewer"></div>
+              </div>
               </div>
               <!-- Editor mode selection -->
-            <div class="bg-gray-200 rounded-lg lg:ml-4 lg:w-1/3 w-full pt-2 pb-1 mb-2">
-              <p class="font-bold lg:text-xl text-sm ml-4 pb-4 underline underline-offset-4">Editor options</p>
+            <div class="rounded-lg lg:ml-4 lg:w-1/3 w-full pt-2 pb-1 mb-2 bg-selection_foreground">
+              <p class="font-bold lg:text-xl text-sm ml-4 pb-4 underline underline-offset-4 text-selection_background">Editor options</p>
               <!-- Checkboxes  -->
   					  <div class="pr-4">
 							  <div  class="flex items-center mb-4 ml-5">
-            	    <input id="vim-mode" type="checkbox" value="" class="w-4 h-4 text-blue-600 bg-gray-100 border-gray-300 rounded focus:ring-blue-500 dark:focus:ring-blue-600 dark:ring-offset-gray-800 focus:ring-2 dark:bg-gray-700 dark:border-gray-600">
-             	    <label for="default-checkbox" class="ml-2 text-sm font-medium text-dark">Vim Mode</label>
+            	    <input id="vim-mode" type="checkbox" value="" class="w-4 h-4 text-blue-600 rounded focus:ring-blue-600">
+             	    <label for="default-checkbox" class="ml-2 text-sm font-medium text-selection_background">Vim Mode</label>
              	  </div>
 							  <div class="flex items-center mb-4 ml-5">
-             	    <input id="show-line-numbers" type="checkbox" value="" class="w-4 h-4 text-blue-600 bg-gray-100 border-gray-300 rounded focus:ring-blue-500 dark:focus:ring-blue-600 dark:ring-offset-gray-800 focus:ring-2 dark:bg-gray-700 dark:border-gray-600">
-             	    <label for="default-checkbox" class="ml-2 text-sm font-medium text-dark">Show Line Numbers</label>
+             	    <input id="show-line-numbers" type="checkbox" value="" class="w-4 h-4 text-blue-600 rounded  focus:ring-blue-600 focus:ring-2">
+             	    <label for="default-checkbox" class="ml-2 text-sm font-medium text-foreground">Show Line Numbers</label>
              	  </div>
              	  <div class="flex items-center mb-4 ml-5">
-             	    <input id="show-time-position" type="checkbox" value="" class="w-4 h-4 text-blue-600 bg-gray-100 border-gray-300 rounded focus:ring-blue-500 dark:focus:ring-blue-600 dark:ring-offset-gray-800 focus:ring-2 dark:bg-gray-700 dark:border-gray-600">
-             	    <label for="default-checkbox" class="ml-2 text-sm font-medium text-dark">Show Time Position</label>
+             	    <input id="show-time-position" type="checkbox" value="" class="w-4 h-4 text-blue-600 rounded focus:ring-blue-600 focus:ring-2">
+             	    <label for="default-checkbox" class="ml-2 text-sm font-medium text-foreground">Show Time Position</label>
              	  </div>
              	  <div class="flex items-center mb-4 ml-5">
-             	    <input id="show-tips" type="checkbox" value="" class="w-4 h-4 text-blue-600 bg-gray-100 border-gray-300 rounded focus:ring-blue-500 dark:focus:ring-blue-600 dark:ring-offset-gray-800 focus:ring-2 dark:bg-gray-700 dark:border-gray-600">
-             	    <label for="default-checkbox" class="ml-2 text-sm font-medium text-dark">Show Hovering Tips</label>
+             	    <input id="show-tips" type="checkbox" value="" class="w-4 h-4 text-blue-600 rounded  focus:ring-blue-600 focus:ring-2">
+             	    <label for="default-checkbox" class="ml-2 text-sm font-medium text-foreground">Show Hovering Tips</label>
              	  </div>
              	  <div class="flex items-center mb-4 ml-5">
-             	    <input id="show-completions" type="checkbox" value="" class="w-4 h-4 text-blue-600 bg-gray-100 border-gray-300 rounded focus:ring-blue-500 dark:focus:ring-blue-600 dark:ring-offset-gray-800 focus:ring-2 dark:bg-gray-700 dark:border-gray-600">
-             	    <label for="default-checkbox" class="ml-2 text-sm font-medium text-dark">Show Completions</label>
+             	    <input id="show-completions" type="checkbox" value="" class="w-4 h-4 text-blue-600 rounded focus:ring-blue-600 focus:ring-2">
+             	    <label for="default-checkbox" class="ml-2 text-sm font-medium text-foreground">Show Completions</label>
              	  </div>
+                <!--
              	  <div class="flex items-center mb-4 ml-5">
-             	    <input id="load-demo-songs" type="checkbox" value="" class="w-4 h-4 text-blue-600 bg-gray-100 border-gray-300 rounded focus:ring-blue-500 dark:focus:ring-blue-600 dark:ring-offset-gray-800 focus:ring-2 dark:bg-gray-700 dark:border-gray-600">
-             	    <label for="default-checkbox" class="ml-2 text-sm font-medium text-dark">Load Demo Song</label>
+             	    <input id="load-demo-songs" type="checkbox" value="" class="w-4 h-4 text-blue-600 rounded focus:ring-blue-600">
+             	    <label for="default-checkbox" class="ml-2 text-sm font-medium text-foreground">Load Demo Song</label>
              	  </div>
+                -->
 						  </div>
             </div>
 
-            <div class="bg-gray-200 rounded-lg lg:ml-4 lg:w-1/3 w-full pt-2 pb-1 mb-2">
-              <p class="font-bold lg:text-xl text-sm ml-4 pb-4 underline underline-offset-4">File Management</p>
+            <div class="rounded-lg lg:ml-4 lg:w-1/3 w-full pt-2 pb-1 mb-2 bg-selection_foreground">
+              <p class="font-bold lg:text-xl text-sm ml-4 pb-4 underline underline-offset-4 text-selection_background">File Management</p>
               <div class="flex flex-col space-y-2 pb-2">
-                <button id="download-universes" class="bg-gray-800 hover:bg-gray-900 text-white font-bold lg:py-4 lg:px-2 px-1 py-2 rounded-lg inline-flex items-center mx-4">
+                <button id="download-universes" class="bg-brightwhite font-bold lg:py-4 lg:px-2 px-1 py-2 rounded-lg inline-flex items-center mx-4 text-selection_background">
                   <svg class="fill-current w-4 h-6 mr-2" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 20 20"><path d="M13 8V2H7v6H2l8 8 8-8h-5zM0 18h20v2H0v-2z"/></svg>
-                  <span>Download universes</span>
+                  <span class="text-selection_foreground">Download universes</span>
                 </button>
-                <button id="upload-universes" class="bg-gray-800 hover:bg-gray-900 text-white font-bold lg:py-4 lg:px-2 px-1 py-2 rounded-lg inline-flex items-center mx-4">
+                <button id="upload-universes" class="bg-brightwhite font-bold lg:py-4 lg:px-2 px-1 py-2 rounded-lg inline-flex items-center mx-4 text-selection_background">
                   <svg class="rotate-180 fill-current w-4 h-6 mr-2" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 20 20"><path d="M13 8V2H7v6H2l8 8 8-8h-5zM0 18h20v2H0v-2z"/></svg>
-                  <span>Upload universes</span>
+                  <span class="text-selection_foreground">Upload universes</span>
                 </button>
-                <button id="destroy-universes" class="bg-red-800 hover:bg-red-900 text-white font-bold lg:px-2 px-1 py-2 rounded-lg inline-flex items-center mx-4">
+                <button id="destroy-universes" class="bg-brightwhite font-bold lg:px-2 px-1 py-2 rounded-lg inline-flex items-center mx-4">
                   <svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke-width="1.5" stroke="currentColor" class="w-4 h-6 mr-2">
                   <path stroke-linecap="round" stroke-linejoin="round" d="M12 9v3.75m-9.303 3.376c-.866 1.5.217 3.374 1.948 3.374h14.71c1.73 0 2.813-1.874 1.948-3.374L13.949 3.378c-.866-1.5-3.032-1.5-3.898 0L2.697 16.126zM12 15.75h.007v.008H12v-.008z" />
                   </svg>
-                  <span>Destroy universes</span>
+                  <span class="text-selection_foreground">Destroy universes</span>
                 </button>
+                <!-- Upload audio samples -->
+                <p class="font-bold lg:text-xl text-sm ml-4 pb-2 pt-2 underline underline-offset-4 text-selection_background">Audio samples</p>
+
+                <label class="bg-brightwhite font-bold lg:py-4 lg:px-2 px-1 py-2 rounded-lg inline-flex items-center mx-4 text-selection_background">
+                  <svg class="rotate-180 fill-current w-4 h-6 mr-2" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 20 20"><path d="M13 8V2H7v6H2l8 8 8-8h-5zM0 18h20v2H0v-2z"/></svg>
+                  <input id="upload-samples" type="file" class="hidden" accept="file" webkitdirectory directory multiple>
+                  <span id="sample-indicator" class="text-selection_foreground">Import samples</span>
+                </label>
               </div>
             </div>
           </div>
 
             <!-- Midi settings -->
-            <div id="midi-settings-container" class="bg-gray-200 rounded-lg flex lg:flex-row flex-col mx-4 my-4 pt-4">
+            <div id="midi-settings-container" class="rounded-lg flex lg:flex-row flex-col mx-4 my-4 pt-4 bg-color bg-selection_foreground">
             <div class="lg:flex lg:flex-row w-fit">
-            <p class="font-bold lg:text-xl text-sm ml-4 pb-4 underline underline-offset-4">MIDI I/O Settings</p>
+            <p class="font-bold lg:text-xl text-sm ml-4 pb-4 underline underline-offset-4 text-selection_background">MIDI I/O Settings</p>
               <div class="flex items-center mb-4 ml-6">
-                <label for="default-checkbox" class="ml-2 text-sm font-medium text-dark">MIDI Clock:&nbsp;</label>
-                <select id="midi-clock-input" class="w-32 h-8 text-sm font-medium text-black bg-gray-100 border-gray-300 rounded focus:ring-blue-500 dark:focus:ring-blue-600 dark:ring-offset-gray-800 focus:ring-2">
+                <label for="default-checkbox" class="ml-2 text-sm font-medium text-foreground">MIDI Clock:&nbsp;</label>
+                <select id="midi-clock-input" class="w-32 h-8 text-sm font-medium text-black rounded focus:ring-blue-600">
                   <option value="-1">Internal</option>
                 </select>
               </div>
               <div class="lg:flex block items-center mb-4 ml-6">
-                <label for="default-checkbox" class="ml-2 text-sm font-medium text-dark">Clock PPQN:&nbsp;</label>
-                <select id="midi-clock-ppqn-input" class="w-32 h-8 text-sm font-medium text-black bg-gray-100 border-gray-300 rounded focus:ring-blue-500 dark:focus:ring-blue-600 dark:ring-offset-gray-800 focus:ring-2">
+                <label for="default-checkbox" class="ml-2 mr-2 text-sm font-medium text-foreground">Clock PPQN:&nbsp;</label>
+                <select id="midi-clock-ppqn-input" class="w-32 h-8 text-sm font-medium text-black rounded focus:ring-blue-600">
                   <option value="24">24</option>
                   <option value="48">48</option>
                 </select>
               </div>
               <div class="lg:flex block items-center mb-4 ml-6">
-                  <input id="send-midi-clock" type="checkbox" value="" class="lg:w-8 lg:h-8 h-4 w-4 text-blue-600 bg-gray-100 border-gray-300 rounded focus:ring-blue-500 dark:focus:ring-blue-600 dark:ring-offset-gray-800 focus:ring-2 dark:bg-gray-700 dark:border-gray-600">
-                  <label for="default-checkbox" class="ml-2 text-sm font-medium text-dark">Send MIDI Clock</label>
+                  <input id="send-midi-clock" type="checkbox" value="" class="lg:w-8 lg:h-8 h-4 w-4 text-blue-600 rounded  focus:ring-blue-600 focus:ring-2">
+                  <label for="default-checkbox" class="ml-2 text-sm font-medium text-foreground">Send MIDI Clock</label>
               </div>
             </div>
             <div class="lg:flex block flex-row">
               <div class="flex items-center mb-4 ml-6">
-                <label for="default-checkbox" class="ml-2 text-sm font-medium text-dark">MIDI input:&nbsp;</label>
-                <select id="default-midi-input" class="w-32 h-8 text-sm font-medium text-black bg-gray-100 border-gray-300 rounded focus:ring-blue-500 dark:focus:ring-blue-600 dark:ring-offset-gray-800 focus:ring-2">
+                <label for="default-checkbox" class="ml-2 mr-2 text-sm font-medium text-foreground">MIDI input:&nbsp;</label>
+                <select id="default-midi-input" class="w-32 h-8 text-sm font-medium text-black rounded  focus:ring-blue-600 focus:ring-2">
                   <option value="-1">None</option>
                 </select>
               </div>
               <div class="lg:flex block items-center mb-4 ml-6">
-                <input id="midi-channels-scripts" type="checkbox" value="" class="lg:w-8 lg:h-8 h-4 w-4 text-blue-600 bg-gray-100 border-gray-300 rounded focus:ring-blue-500 dark:focus:ring-blue-600 dark:ring-offset-gray-800 focus:ring-2 dark:bg-gray-700 dark:border-gray-600">
-                <label for="default-checkbox" class="ml-2 text-sm font-medium text-dark">Route channels to scripts</label>
+                <input id="midi-channels-scripts" type="checkbox" value="" class="lg:w-8 lg:h-8 h-4 w-4 text-blue-600 rounded focus:ring-blue-600">
+                <label for="default-checkbox" class="ml-2 text-sm font-medium text-foreground">Route channels to scripts</label>
               </div>
             </div>
           </div>
 
           <!-- Audio nudge slider -->
-          <div id="midi-settings-container" class="bg-gray-200 rounded-lg flex flex-col mx-4 my-4 pt-4 pb-2">
-            <p class="font-bold lg:text-xl text-sm ml-4 pb-4 underline underline-offset-4">Audio/Event Nudging</p>
-            <div class="flex flex-column pb-2">
-              <p class="pt-0.5 ml-4">Clock:</p>
+          <div id="midi-settings-container" class="rounded-lg flex flex-col mx-4 my-4 pt-4 pb-2 bg-selection_foreground">
+            <p class="font-bold lg:text-xl text-sm ml-4 pb-4 underline underline-offset-4 text-selection_background">Audio/Event Nudging</p> <div class="flex flex-column pb-2">
+              <p class="pt-0.5 ml-4 text-foreground">Clock:</p>
               <input
                 type="range" id="audio_nudge"
                 name="audiorangeInput"
                 min="-200" max="200"
                 value="0"
-                class="w-full ml-4"
+                class="w-full ml-4 text-red"
                 oninput="nudgenumber.value=audio_nudge.value"
               >
               <output 
                 name="nudgenumber" 
                 id="nudgenumber" 
                 for="audiorangeInput" 
-                class="bg-gray-500 rounded-lg ml-2 mr-4 px-4 py-1 text-white"
+                class="rounded-lg ml-2 mr-4 px-4 py-1 text-foreground"
               >0</output>
             </div>
 
             <div class="flex flex-column">
 
-              <p class="pt-0.5 ml-4">Audio:</p>
+              <p class="pt-0.5 ml-4 text-foreground">Audio:</p>
               <input
                 type="range" id="dough_nudge"
                 name="doughrangeInput"
                 min="0" max="100"
                 value="0"
-                class="w-full ml-4"
+                class="w-full ml-4 text-foreground"
                 oninput="doughnumber.value=dough_nudge.value"
               >
               <output 
                 name="doughnumber" 
                 id="doughnumber" 
                 for="doughrangeInput" 
-                class="bg-gray-500 rounded-lg ml-2 mr-4 px-4 py-1 text-white"
+                class="rounded-lg ml-2 mr-4 px-4 py-1 text-foreground"
               >0</output>
             </div>
 
           </div>
 
-          <div class="flex space-x-6 border-t border-gray-200 rounded-b dark:border-gray-600 mx-4 border-spacing-y-4 pb-36 lg:pb-0">
+          <div class="flex space-x-6 border-t rounded-b mx-4 border-spacing-y-4 pb-36 lg:pb-0">
             <button id="close-settings-button" data-modal-hide="defaultModal" type="button" class="
-            hover:bg-gray-700 bg-gray-800 mt-4 mb-4 text-white focus:ring-4
-            font-medium rounded-lg text-sm px-5 py-2.5 text-center">OK</button>
+            hover:bg-background bg-background mt-4 mb-4 focus:ring-4
+            font-medium rounded-lg text-sm px-5 py-2.5 text-center text-selection_background">OK</button>
           </div>
         </div>
       </div>
     </div>
 
       <div class="flex flex-row max-h-fit">
-
 				<!-- This is a lateral bar that will inherit the header buttons if the window is too small. -->
         <aside id="sidebar" class="
 					flex flex-col items-center w-14
 					h-screen py-2 border-r 
 					rtl:border-l max-h-fit
-					rtl:border-r-0 bg-neutral-900
-					dark:border-neutral-700 border-none"
+					rtl:border-r-0 bg-background
+					border-neutral-700 border-none"
 				>
         <nav class="flex flex-col space-y-6">
-            <a title="Local Scripts (Ctrl + L)" id="local-button" class="pl-2 p-1.5 focus:outline-nones transition-colors duration-200 rounded-lg text-white hover:bg-gray-800">
-							<svg class="w-8 h-8 text-white" aria-hidden="true" xmlns="http://www.w3.org/2000/svg" fill="currentColor" viewBox="0 0 18 18">
+            <a title="Local Scripts (Ctrl + L)" id="local-button" class="side_button">
+							<svg class="w-8 h-8 " aria-hidden="true" xmlns="http://www.w3.org/2000/svg" fill="currentColor" viewBox="0 0 18 18">
     <path d="M18 5H0v11a2 2 0 0 0 2 2h14a2 2 0 0 0 2-2V5Zm-7.258-2L9.092.8a2.009 2.009 0 0 0-1.6-.8H2.049a2 2 0 0 0-2 2v1h10.693Z"/>
   </svg>
                      </svg>
             </a>
           
-            <a title="Global Script (Ctrl + G)" id="global-button" class="pl-2 p-1.5 text-white focus:outline-nones transition-colors duration-200 rounded-lg hover:bg-gray-800">
-							<svg class="w-8 h-8 text-white" aria-hidden="true" xmlns="http://www.w3.org/2000/svg" fill="currentColor" viewBox="0 0 18 16">
+            <a title="Global Script (Ctrl + G)" id="global-button" class="side_button">
+							<svg class="w-8 h-8 " aria-hidden="true" xmlns="http://www.w3.org/2000/svg" fill="currentColor" viewBox="0 0 18 16">
     <path d="M14.316.051A1 1 0 0 0 13 1v8.473A4.49 4.49 0 0 0 11 9c-2.206 0-4 1.525-4 3.4s1.794 3.4 4 3.4 4-1.526 4-3.4a2.945 2.945 0 0 0-.067-.566c.041-.107.064-.22.067-.334V2.763A2.974 2.974 0 0 1 16 5a1 1 0 0 0 2 0C18 1.322 14.467.1 14.316.051ZM10 3H1a1 1 0 0 1 0-2h9a1 1 0 1 1 0 2Z"/>
     <path d="M10 7H1a1 1 0 0 1 0-2h9a1 1 0 1 1 0 2Zm-5 4H1a1 1 0 0 1 0-2h4a1 1 0 1 1 0 2Z"/>
   </svg>
                    </a>
           
-            <a title="Initialisation Script (Ctrl + I)" id="init-button" class="pl-2 p-1.5 focus:outline-nones transition-colors duration-200 rounded-lg text-white hover:bg-gray-800">
-							<svg class="w-8 h-8 text-white" aria-hidden="true" xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 10 14">
+            <a title="Initialisation Script (Ctrl + I)" id="init-button" class="side_button">
+							<svg class="w-8 h-8 " aria-hidden="true" xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 10 14">
     <path stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M5 1v12m0 0 4-4m-4 4L1 9"/>
   </svg>
                    </a>
 
-            <a title="Project notes (Ctrl + N)" id="note-button" class="pl-2 p-1.5 text-white focus:outline-nones transition-colors duration-200 rounded-lg text-white hover:bg-gray-800">
-							<svg class="w-8 h-8 text-white" aria-hidden="true" xmlns="http://www.w3.org/2000/svg" fill="currentColor" viewBox="0 0 20 20">
+            <a title="Project notes (Ctrl + N)" id="note-button" class="side_button">
+							<svg class="w-8 h-8 " aria-hidden="true" xmlns="http://www.w3.org/2000/svg" fill="currentColor" viewBox="0 0 20 20">
     <path d="m13.835 7.578-.005.007-7.137 7.137 2.139 2.138 7.143-7.142-2.14-2.14Zm-10.696 3.59 2.139 2.14 7.138-7.137.007-.005-2.141-2.141-7.143 7.143Zm1.433 4.261L2 12.852.051 18.684a1 1 0 0 0 1.265 1.264L7.147 18l-2.575-2.571Zm14.249-14.25a4.03 4.03 0 0 0-5.693 0L11.7 2.611 17.389 8.3l1.432-1.432a4.029 4.029 0 0 0 0-5.689Z"/>
   </svg>
 			      </a>
 
-            <a title="Application Settings" id="settings-button" class="pl-2 p-1.5 text-white focus:outline-nones transition-colors duration-200 rounded-lg text-white hover:bg-gray-800">
-							<svg class="w-8 h-8 text-white" aria-hidden="true" xmlns="http://www.w3.org/2000/svg" fill="currentColor" viewBox="0 0 20 20">
+            <a title="Application Settings" id="settings-button" class="side_button">
+							<svg class="w-8 h-8 " aria-hidden="true" xmlns="http://www.w3.org/2000/svg" fill="currentColor" viewBox="0 0 20 20">
                 <svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke-width="1.5" stroke="currentColor" class="w-6 h-6">
                   <path stroke-linecap="round" stroke-linejoin="round" d="M10.343 3.94c.09-.542.56-.94 1.11-.94h1.093c.55 0 1.02.398 1.11.94l.149.894c.07.424.384.764.78.93.398.164.855.142 1.205-.108l.737-.527a1.125 1.125 0 011.45.12l.773.774c.39.389.44 1.002.12 1.45l-.527.737c-.25.35-.272.806-.107 1.204.165.397.505.71.93.78l.893.15c.543.09.94.56.94 1.109v1.094c0 .55-.397 1.02-.94 1.11l-.893.149c-.425.07-.765.383-.93.78-.165.398-.143.854.107 1.204l.527.738c.32.447.269 1.06-.12 1.45l-.774.773a1.125 1.125 0 01-1.449.12l-.738-.527c-.35-.25-.806-.272-1.203-.107-.397.165-.71.505-.781.929l-.149.894c-.09.542-.56.94-1.11.94h-1.094c-.55 0-1.019-.398-1.11-.94l-.148-.894c-.071-.424-.384-.764-.781-.93-.398-.164-.854-.142-1.204.108l-.738.527c-.447.32-1.06.269-1.45-.12l-.773-.774a1.125 1.125 0 01-.12-1.45l.527-.737c.25-.35.273-.806.108-1.204-.165-.397-.505-.71-.93-.78l-.894-.15c-.542-.09-.94-.56-.94-1.109v-1.094c0-.55.398-1.02.94-1.11l.894-.149c.424-.07.765-.383.93-.78.165-.398.143-.854-.107-1.204l-.527-.738a1.125 1.125 0 01.12-1.45l.773-.773a1.125 1.125 0 011.45-.12l.737.527c.35.25.807.272 1.204.107.397-.165.71-.505.78-.929l.15-.894z" />
                   <path stroke-linecap="round" stroke-linejoin="round" d="M15 12a3 3 0 11-6 0 3 3 0 016 0z" />
@@ -478,55 +543,55 @@
 
         <!-- Tabs for local files -->
         <div class="min-w-screen flex grow flex-col">
-          <ul id="local-script-tabs" class=" flex text-xl font-medium text-center text-white bg-neutral-900 space-x-1 lg:space-x-8">
+          <ul id="local-script-tabs" class=" flex text-xl font-medium text-center bg-background space-x-1 lg:space-x-8">
             <li class="pl-5">
-                <a title="Local Script 1 (F1)" id="tab-1" class="bg-orange-300 inline-block lg:px-4 px-2 py-1 text-white hover:bg-gray-800">1</a>
+                <a title="Local Script 1 (F1)" id="tab-1" class="tab_panel">1</a>
             </li>
             <li class="">
-                <a title="Local Script 2 (F2)" id="tab-2" class="inline-block lg:px-4 px-2 py-1 hover:bg-gray-800">2</a>
+                <a title="Local Script 2 (F2)" id="tab-2" class="tab_panel">2</a>
             </li>
             <li class="">
-                <a title="Local Script 3 (F3)" id="tab-3" class="inline-block lg:px-4 px-2 py-1 hover:bg-gray-800">3</a>
+                <a title="Local Script 3 (F3)" id="tab-3" class="tab_panel">3</a>
             </li>
             <li class="">
-                <a title="Local Script 4 (F4)" id="tab-4" class="inline-block lg:px-4 px-2 py-1 hover:bg-gray-800">4</a>
+                <a title="Local Script 4 (F4)" id="tab-4" class="tab_panel">4</a>
             </li>
             <li class="">
-                <a title="Local Script 5 (F5)" id="tab-5" class="inline-block lg:px-4 px-2 py-1 hover:bg-gray-800">5</a>
+                <a title="Local Script 5 (F5)" id="tab-5" class="tab_panel">5</a>
             </li>
             <li class="">
-                <a title="Local Script 6 (F6)" id="tab-6" class="inline-block lg:px-4 px-2 py-1 hover:bg-gray-800">6</a>
+                <a title="Local Script 6 (F6)" id="tab-6" class="tab_panel">6</a>
             </li>
             <li class="">
-                <a title="Local Script 7 (F7)" id="tab-7" class="inline-block lg:px-4 px-2 py-1 hover:bg-gray-800">7</a>
+                <a title="Local Script 7 (F7)" id="tab-7" class="tab_panel">7</a>
             </li>
             <li class="">
-                <a title="Local Script 8 (F8)" id="tab-8" class="inline-block lg:px-4 px-2 py-1 hover:bg-gray-800">8</a>
+                <a title="Local Script 8 (F8)" id="tab-8" class="tab_panel">8</a>
             </li>
             <li class="">
-                <a title="Local Script 9 (F9)" id="tab-9" class="inline-block lg:px-4 px-2 py-1 hover:bg-gray-800">9</a>
+                <a title="Local Script 9 (F9)" id="tab-9" class="tab_panel">9</a>
             </li>
- 
          </ul>
          <!-- Here comes the editor itself -->
           <div id="editor" class="relative flex flex-row h-screen overflow-y-hidden">
-            <canvas id="hydra-bg" class="fullscreencanvas"></canvas>
             <canvas id="scope" class="fullscreencanvas"></canvas>
             <canvas id="feedback" class="fullscreencanvas"></canvas>
+            <canvas id="drawings" class="fullscreencanvas"></canvas>
+            <canvas id="hydra-bg" class="hydracanvas"></canvas>
 					</div>
-          <p id="error_line" class="hidden text-red-400 w-screen bg-neutral-900 font-mono absolute bottom-0 pl-2 py-2">Hello kids</p>
+          <p id="error_line" class="hidden w-screen bg-background font-mono absolute bottom-0 pl-2 py-2">Hello kids</p>
         </div>
       </div>
       <script type="module" src="/src/main.ts"></script>
 
       <template id="ui-known-universe-item-template">
         <!-- A known universe button in "opening" interface -->
-        <li class="hover:fill-black hover:bg-white py-2 hover:text-black flex justify-between px-4">
+        <li class="py-2 px-4 flex justify-between text-brightwhite hover:bg-selection_background hover:text-selection_foreground">
           <button class="universe-name load-universe" title="Load this universe">Universe Name</button>
           <button class="delete-universe" title="Delete this universe">🗑</button>
         </li>
       </template>
   </body>
-	<p id="timeviewer" class="rounded-lg px-2 py-2 font-bold bg-white cursor-textpointer-events-none select-none text-black text-sm absolute bottom-2 right-2"></p>
-	<p id="fillviewer" class="invisible rounded-lg px-2 py-2 font-bold bg-white cursor-textpointer-events-none select-none text-black text-sm absolute right-2 bottom-12">/////// Fill ///////</p>
+	<p id="timeviewer" class="rounded-lg px-2 py-2 font-bold  cursor-textpointer-events-none select-none text-sm absolute bottom-2 right-2 bg-foreground text-background"></p>
+	<p id="fillviewer" class="invisible rounded-lg px-2 py-2 font-bold cursor-textpointer-events-none select-none text-sm absolute right-2 bottom-12 bg-foreground text-background">/////// Fill ///////</p>
 </html>

manifest.webmanifest

@@ -1,24 +0,0 @@
-{
-  "name": "Topos",
-  "short_name": "Topos",
-  "description": "Live coding environment",
-  "theme_color": "#ffffff",
-  "background_color": "#ffffff",
-  "display": "standalone",
-  "scope": "/",
-  "start_url": "/",
-  "icons": [
-    {
-      "src": "./favicon/android-chrome-192x192.png",
-      "sizes": "192x192",
-      "type": "image/png",
-      "purpose": "any maskable"
-    },
-    {
-      "src": "./favicon/android-chrome-512x512.png",
-      "sizes": "512x512",
-      "type": "image/png",
-      "purpose": "any maskable"
-    }
-  ]
-}

package.json

@@ -14,7 +14,7 @@
     "typescript": "^5.2.2",
     "vite": "^4.4.5",
     "vite-plugin-compression": "^0.5.1",
-    "vite-plugin-pwa": "^0.16.7"
+    "vite-plugin-pwa": "^0.17.4"
   },
   "dependencies": {
     "@codemirror/lang-javascript": "^6.1.9",
@@ -30,19 +30,21 @@
     "autoprefixer": "^10.4.14",
     "codemirror": "^6.0.1",
     "fflate": "^0.8.0",
+    "highlight.js": "^11.9.0",
     "jisg": "^0.9.7",
     "lru-cache": "^10.0.1",
     "marked": "^7.0.3",
+    "osc": "^2.4.4",
     "postcss": "^8.4.27",
     "showdown": "^2.1.0",
     "showdown-highlight": "^3.1.0",
-    "superdough": "^0.9.11",
+    "superdough": "^0.9.12",
     "tailwind-highlightjs": "^2.0.1",
     "tailwindcss": "^3.3.3",
     "tone": "^14.8.49",
     "unique-names-generator": "^4.7.1",
     "vite-plugin-markdown": "^2.1.0",
-    "zifferjs": "^0.0.44",
+    "zifferjs": "^0.0.62",
     "zyklus": "^0.1.4",
     "zzfx": "^1.2.0"
   }

public/favicon/favicon.svg

@@ -0,0 +1,46 @@
+<?xml version="1.0" standalone="no"?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 20010904//EN"
+ "http://www.w3.org/TR/2001/REC-SVG-20010904/DTD/svg10.dtd">
+<svg version="1.0" xmlns="http://www.w3.org/2000/svg"
+ width="48.000000pt" height="48.000000pt" viewBox="0 0 48.000000 48.000000"
+ preserveAspectRatio="xMidYMid meet">
+
+<g transform="translate(0.000000,48.000000) scale(0.100000,-0.100000)"
+fill="#000000" stroke="none">
+<path d="M163 470 c-13 -5 -23 -12 -23 -15 0 -3 46 -5 102 -5 80 0 99 3 90 12
+-15 15 -139 21 -169 8z"/>
+<path d="M91 391 c-16 -16 -19 -32 -18 -84 1 -53 -2 -69 -18 -87 -15 -16 -20
+-38 -22 -83 0 -33 2 -56 5 -50 9 13 44 13 39 -1 -2 -6 -18 -11 -34 -11 -39 0
+-50 -10 -33 -30 8 -10 30 -15 60 -15 26 0 64 -7 83 -15 43 -18 125 -20 164 -3
+15 6 57 14 93 17 73 7 87 24 51 60 -12 12 -21 17 -21 13 0 -4 5 -13 12 -20 8
+-8 8 -12 1 -12 -18 0 -25 34 -9 45 10 7 12 16 6 25 -5 8 -7 24 -4 35 3 13 -2
+28 -15 39 -12 11 -21 27 -21 36 0 9 -5 21 -11 27 -8 8 -8 17 0 31 17 32 13 56
+-12 80 -31 29 -63 28 -91 -3 -16 -17 -34 -25 -56 -25 -22 0 -40 8 -56 25 -28
+30 -67 32 -93 6z m89 -16 c19 -23 5 -29 -24 -10 -16 10 -33 14 -47 10 -14 -5
+-19 -4 -15 4 10 16 72 13 86 -4z m211 -7 c12 -22 11 -22 -8 -5 -25 21 -41 22
+-65 0 -22 -19 -36 -10 -18 12 20 24 77 19 91 -7z m-264 -30 c-3 -7 -5 -2 -5
+12 0 14 2 19 5 13 2 -7 2 -19 0 -25z m229 -5 c-11 -11 -19 6 -11 24 8 17 8 17
+12 0 3 -10 2 -21 -1 -24z m-80 -8 c4 -8 10 -12 15 -9 5 3 9 0 9 -6 0 -14 60
+-40 77 -33 7 3 13 -2 13 -11 0 -13 -6 -15 -27 -9 -36 9 -210 9 -245 0 -22 -6
+-28 -4 -28 9 0 8 6 14 13 11 6 -2 25 2 40 10 15 8 32 11 37 8 6 -4 7 1 3 11
+-4 12 -3 15 5 10 7 -4 15 -1 18 8 8 21 63 21 70 1z m83 -91 c10 -9 -37 -33
+-77 -39 -55 -8 -117 2 -155 26 l-30 18 54 4 c56 4 201 -2 208 -9z m-286 -30
+c-15 -7 21 -44 42 -44 8 0 15 -4 15 -10 0 -16 -33 -11 -59 9 -25 19 -24 52 1
+50 9 0 10 -2 1 -5z m355 -21 c2 -14 -4 -23 -17 -28 -12 -3 -21 -13 -21 -21 0
+-19 -16 -18 -24 1 -5 15 -31 16 -53 2 -8 -5 -13 -4 -13 2 0 6 5 12 10 12 6 1
+15 3 20 4 6 1 18 3 28 4 25 1 66 37 52 44 -6 3 -5 4 2 3 7 -1 14 -12 16 -23z
+m-255 -37 c4 -10 1 -13 -9 -9 -7 3 -14 9 -14 14 0 14 17 10 23 -5z m42 -6 c3
+-5 1 -10 -4 -10 -6 0 -11 5 -11 10 0 6 2 10 4 10 3 0 8 -4 11 -10z m35 0 c0
+-5 -4 -10 -10 -10 -5 0 -10 5 -10 10 0 6 5 10 10 10 6 0 10 -4 10 -10z m-170
+-10 c0 -5 -5 -10 -11 -10 -5 0 -7 5 -4 10 3 6 8 10 11 10 2 0 4 -4 4 -10z
+m215 -39 c-6 -5 -25 10 -25 20 0 5 6 4 14 -3 8 -7 12 -15 11 -17z m45 8 c0
+-14 -16 -11 -29 5 -10 12 -8 13 8 9 12 -3 21 -9 21 -14z m-220 1 c0 -5 -5 -10
+-11 -10 -5 0 -7 5 -4 10 3 6 8 10 11 10 2 0 4 -4 4 -10z m40 0 c0 -5 -4 -10
+-10 -10 -5 0 -10 5 -10 10 0 6 5 10 10 10 6 0 10 -4 10 -10z m215 0 c3 -5 2
+-10 -4 -10 -5 0 -13 5 -16 10 -3 6 -2 10 4 10 5 0 13 -4 16 -10z m43 -10 c7
+-11 10 -20 6 -20 -7 0 -34 27 -34 34 0 13 16 5 28 -14z m-160 -17 c-10 -2 -26
+-2 -35 0 -10 3 -2 5 17 5 19 0 27 -2 18 -5z m99 1 c-3 -3 -12 -4 -19 -1 -8 3
+-5 6 6 6 11 1 17 -2 13 -5z m40 0 c-3 -3 -12 -4 -19 -1 -8 3 -5 6 6 6 11 1 17
+-2 13 -5z"/>
+</g>
+</svg>

public/manifest.webmanifest

@@ -0,0 +1,37 @@
+{
+  "name": "Topos",
+  "short_name": "Topos",
+  "icons": [
+    {
+      "src": "favicon/android-chrome-192x192.png",
+      "sizes": "192x192",
+      "type": "image/png"
+    },
+    {
+      "src": "favicon/android-chrome-512x512.png",
+      "sizes": "512x512",
+      "type": "image/png"
+    }
+  ],
+  "display": "standalone",
+  "start_url": "/",
+  "scope": "/",
+  "theme_color": "#ffffff",
+  "background_color": "#ffffff",
+  "description": "Topos is a web based live coding platform",
+  "screenshots": [
+    {
+      "src": "favicon/screenshot_miniature.png",
+      "sizes": "640x320",
+      "type": "image/gif",
+      "form_factor": "wide",
+      "label": "Topos application"
+    },
+    {
+      "src": "favicon/topos_code.png",
+      "sizes": "1280x768",
+      "type": "image/gif",
+      "label": "Topos code"
+    }
+  ]
+}

src/Clock.ts

@@ -1,11 +1,7 @@
+// @ts-ignore
+import { TransportNode } from "./TransportNode";
+import TransportProcessor from "./TransportProcessor?worker&url";
 import { Editor } from "./main";
-import { tryEvaluate } from "./Evaluator";
-// @ts-ignore
-import { getAudioContext } from "superdough";
-// @ts-ignore
-import "zyklus";
-const zeroPad = (num: number, places: number) =>
-  String(num).padStart(places, "0");
 
 export interface TimePosition {
   /**
@@ -22,29 +18,35 @@ export interface TimePosition {
 
 export class Clock {
   /**
+   * The Clock Class is responsible for keeping track of the current time.
+   * It is also responsible for starting and stopping the Clock TransportNode.
    *
-   * @param app - main application instance
-   * @param clock - zyklus clock
-   * @param ctx - current AudioContext used by app
-   * @param bpm - current beats per minute value
-   * @param time_signature - time signature
-   * @param time_position - current time position
-   * @param ppqn - pulses per quarter note
-   * @param tick - current tick since origin
+   * @param app - The main application instance
+   * @param ctx - The current AudioContext used by app
+   * @param transportNode - The TransportNode helper
+   * @param bpm - The current beats per minute value
+   * @param time_signature - The time signature
+   * @param time_position - The current time position
+   * @param ppqn - The pulses per quarter note
+   * @param tick - The current tick since origin
    * @param running - Is the clock running?
+   * @param lastPauseTime - The last time the clock was paused
+   * @param lastPlayPressTime - The last time the clock was started
+   * @param totalPauseTime - The total time the clock has been paused / stopped
    */
 
-  private _bpm: number;
-  private _ppqn: number;
-  clock: any;
   ctx: AudioContext;
   logicalTime: number;
+  transportNode: TransportNode | null;
+  private _bpm: number;
   time_signature: number[];
   time_position: TimePosition;
+  private _ppqn: number;
   tick: number;
   running: boolean;
-  timeviewer: HTMLElement;
-  deadline: number;
+  lastPauseTime: number;
+  lastPlayPressTime: number;
+  totalPauseTime: number;
 
   constructor(
     public app: Editor,
@@ -56,58 +58,31 @@ export class Clock {
     this.tick = 0;
     this._bpm = 120;
     this._ppqn = 48;
+    this.transportNode = null;
     this.ctx = ctx;
     this.running = true;
-    this.deadline = 0;
-    this.timeviewer = document.getElementById("timeviewer")!;
-    this.clock = getAudioContext().createClock(
-      this.clockCallback,
-      this.pulse_duration,
-    );
+    this.lastPauseTime = 0;
+    this.lastPlayPressTime = 0;
+    this.totalPauseTime = 0;
+    ctx.audioWorklet
+      .addModule(TransportProcessor)
+      .then((e) => {
+        this.transportNode = new TransportNode(ctx, {}, this.app);
+        this.transportNode.connect(ctx.destination);
+        return e;
+      })
+      .catch((e) => {
+        console.log("Error loading TransportProcessor.js:", e);
+      });
   }
 
-  // @ts-ignore
-  clockCallback = (time: number, duration: number, tick: number) => {
-    /**
-     * Callback function for the zyklus clock. Updates the clock info and sends a 
-     * MIDI clock message if the setting is enabled. Also evaluates the global buffer.
-     * 
-     * @param time - precise AudioContext time when the tick should happen
-     * @param duration -  seconds between each tick
-     * @param tick - count of the current tick
-     */
-    let deadline = time - getAudioContext().currentTime;
-    this.deadline = deadline;
-    this.tick = tick;
-    if (this.app.clock.running) {
-      if (this.app.settings.send_clock) {
-        this.app.api.MidiConnection.sendMidiClock();
-      }
-      const futureTimeStamp = this.app.clock.convertTicksToTimeposition(
-        this.app.clock.tick,
-      );
-      this.app.clock.time_position = futureTimeStamp;
-      if (futureTimeStamp.pulse % this.app.clock.ppqn == 0) {
-        this.timeviewer.innerHTML = `${zeroPad(futureTimeStamp.bar, 2)}:${futureTimeStamp.beat + 1
-          } / ${this.app.clock.bpm}`;
-      }
-      if (this.app.exampleIsPlaying) {
-        tryEvaluate(this.app, this.app.example_buffer);
-      } else {
-        tryEvaluate(this.app, this.app.global_buffer);
-      }
-    }
-
-    // Implement TransportNode clock callback and update clock info with it
-  };
-
   convertTicksToTimeposition(ticks: number): TimePosition {
     /**
-     * Converts ticks to a time position. 
-     * 
-     * @param ticks - ticks to convert
-     * @returns TimePosition
+     * Converts ticks to a TimePosition object.
+     * @param ticks The number of ticks to convert.
+     * @returns The TimePosition object representing the converted ticks.
      */
+
     const beatsPerBar = this.app.clock.time_signature[0];
     const ppqnPosition = ticks % this.app.clock.ppqn;
     const beatNumber = Math.floor(ticks / this.app.clock.ppqn);
@@ -118,9 +93,10 @@ export class Clock {
 
   get ticks_before_new_bar(): number {
     /**
-     * Calculates the number of ticks before the next bar.
-     * 
-     * @returns number - ticks before the next bar
+     * This function returns the number of ticks separating the current moment
+     * from the beginning of the next bar.
+     *
+     * @returns number of ticks until next bar
      */
     const ticskMissingFromBeat = this.ppqn - this.time_position.pulse;
     const beatsMissingFromBar = this.beats_per_bar - this.time_position.beat;
@@ -129,9 +105,10 @@ export class Clock {
 
   get next_beat_in_ticks(): number {
     /**
-     * Calculates the number of ticks before the next beat.
-     * 
-     * @returns number - ticks before the next beat
+     * This function returns the number of ticks separating the current moment
+     * from the beginning of the next beat.
+     *
+     * @returns number of ticks until next beat
      */
     return this.app.clock.pulses_since_origin + this.time_position.pulse;
   }
@@ -139,8 +116,6 @@ export class Clock {
   get beats_per_bar(): number {
     /**
      * Returns the number of beats per bar.
-     * 
-     * @returns number - beats per bar
      */
     return this.time_signature[0];
   }
@@ -148,8 +123,8 @@ export class Clock {
   get beats_since_origin(): number {
     /**
      * Returns the number of beats since the origin.
-     * 
-     * @returns number - beats since the origin
+     *
+     * @returns number of beats since origin
      */
     return Math.floor(this.tick / this.ppqn);
   }
@@ -157,8 +132,8 @@ export class Clock {
   get pulses_since_origin(): number {
     /**
      * Returns the number of pulses since the origin.
-     * 
-     * @returns number - pulses since the origin
+     *
+     * @returns number of pulses since origin
      */
     return this.tick;
   }
@@ -166,112 +141,119 @@ export class Clock {
   get pulse_duration(): number {
     /**
      * Returns the duration of a pulse in seconds.
-     * @returns number - duration of a pulse in seconds
      */
     return 60 / this.bpm / this.ppqn;
   }
 
   public pulse_duration_at_bpm(bpm: number = this.bpm): number {
     /**
-     * Returns the duration of a pulse in seconds at a given bpm.
-     * 
-     * @param bpm - bpm to calculate the pulse duration for
-     * @returns number - duration of a pulse in seconds
+     * Returns the duration of a pulse in seconds at a specific bpm.
      */
     return 60 / bpm / this.ppqn;
   }
 
   get bpm(): number {
-    /**
-     * Returns the current bpm.
-     * @returns number - current bpm
-     */
     return this._bpm;
   }
 
-  get tickDuration(): number {
-    /**
-     * Returns the duration of a tick in seconds.
-     * @returns number - duration of a tick in seconds
-     */
-    return 1 / this.ppqn;
+  set nudge(nudge: number) {
+    this.transportNode?.setNudge(nudge);
   }
 
   set bpm(bpm: number) {
-    /**
-     * Sets the bpm.
-     * @param bpm - bpm to set
-     */
     if (bpm > 0 && this._bpm !== bpm) {
+      this.transportNode?.setBPM(bpm);
       this._bpm = bpm;
-      this.clock.setDuration(() => (this.tickDuration * 60) / this.bpm);
+      this.logicalTime = this.realTime;
     }
   }
 
   get ppqn(): number {
-    /**
-     * Returns the current ppqn.
-     * @returns number - current ppqn
-     */
     return this._ppqn;
   }
 
+  get realTime(): number {
+    return this.app.audioContext.currentTime - this.totalPauseTime;
+  }
+
+  get deviation(): number {
+    return Math.abs(this.logicalTime - this.realTime);
+  }
+
   set ppqn(ppqn: number) {
-    /**
-     * Sets the ppqn.
-     * @param ppqn - ppqn to set
-     * @returns number - current ppqn
-     */
     if (ppqn > 0 && this._ppqn !== ppqn) {
       this._ppqn = ppqn;
+      this.transportNode?.setPPQN(ppqn);
+      this.logicalTime = this.realTime;
     }
   }
 
+  public incrementTick(bpm: number) {
+    this.tick++;
+    this.logicalTime += this.pulse_duration_at_bpm(bpm);
+  }
+
   public nextTickFrom(time: number, nudge: number): number {
+    /**
+     * Compute the time remaining before the next clock tick.
+     * @param time - audio context currentTime
+     * @param nudge - nudge in the future (in seconds)
+     * @returns remainingTime
+     */
     const pulseDuration = this.pulse_duration;
     const nudgedTime = time + nudge;
     const nextTickTime = Math.ceil(nudgedTime / pulseDuration) * pulseDuration;
     const remainingTime = nextTickTime - nudgedTime;
+
     return remainingTime;
   }
 
   public convertPulseToSecond(n: number): number {
+    /**
+     * Converts a pulse to a second.
+     */
     return n * this.pulse_duration;
   }
 
   public start(): void {
     /**
-     * Start the clock
-     * 
+     * Starts the TransportNode (starts the clock).
+     *
      * @remark also sends a MIDI message if a port is declared
      */
     this.app.audioContext.resume();
     this.running = true;
     this.app.api.MidiConnection.sendStartMessage();
-    this.clock.start();
+    this.lastPlayPressTime = this.app.audioContext.currentTime;
+    this.totalPauseTime += this.lastPlayPressTime - this.lastPauseTime;
+    this.transportNode?.start();
   }
 
   public pause(): void {
     /**
-     * Pause the clock.
-     * 
+     * Pauses the TransportNode (pauses the clock).
+     *
      * @remark also sends a MIDI message if a port is declared
      */
     this.running = false;
+    this.transportNode?.pause();
     this.app.api.MidiConnection.sendStopMessage();
-    this.clock.pause();
+    this.lastPauseTime = this.app.audioContext.currentTime;
+    this.logicalTime = this.realTime;
   }
 
   public stop(): void {
     /**
-     * Stops the clock.
+     * Stops the TransportNode (stops the clock).
      *
      * @remark also sends a MIDI message if a port is declared
      */
     this.running = false;
     this.tick = 0;
+    this.lastPauseTime = this.app.audioContext.currentTime;
+    this.logicalTime = this.realTime;
     this.time_position = { bar: 0, beat: 0, pulse: 0 };
     this.app.api.MidiConnection.sendStopMessage();
-    this.clock.stop();
+    this.transportNode?.stop();
   }
-}
+}

src/Documentation.ts

@@ -1,13 +1,14 @@
 import { type Editor } from "./main";
 // Basics
 import { introduction } from "./documentation/basics/welcome";
-import { loading_samples } from "./documentation/samples/loading_samples";
-import { amplitude } from "./documentation/audio_engine/amplitude";
-import { reverb } from "./documentation/audio_engine/reverb_delay";
-import { sampler } from "./documentation/audio_engine/sampler";
-import { sample_banks } from "./documentation/samples/sample_banks";
-import { audio_basics } from "./documentation/audio_engine/audio_basics";
-import { sample_list } from "./documentation/samples/sample_list";
+import { atelier } from "./documentation/basics/atelier";
+import { loading_samples } from "./documentation/learning/samples/loading_samples";
+import { amplitude } from "./documentation/learning/audio_engine/amplitude";
+import { effects } from "./documentation/learning/audio_engine/effects";
+import { sampler } from "./documentation/learning/audio_engine/sampler";
+import { sample_banks } from "./documentation/learning/samples/sample_banks";
+import { audio_basics } from "./documentation/learning/audio_engine/audio_basics";
+import { sample_list } from "./documentation/learning/samples/sample_list";
 import { software_interface } from "./documentation/basics/interface";
 import { shortcuts } from "./documentation/basics/keyboard";
 import { code } from "./documentation/basics/code";
@@ -17,30 +18,38 @@ import { oscilloscope } from "./documentation/more/oscilloscope";
 import { synchronisation } from "./documentation/more/synchronisation";
 import { about } from "./documentation/more/about";
 import { bonus } from "./documentation/more/bonus";
-import { chaining } from "./documentation/chaining";
-import { interaction } from "./documentation/interaction";
-import { time } from "./documentation/time/time";
-import { linear_time } from "./documentation/time/linear_time";
-import { cyclical_time } from "./documentation/time/cyclical_time";
-import { long_forms } from "./documentation/long_forms";
-import { midi } from "./documentation/midi";
-import { sound } from "./documentation/engine";
-import { patterns } from "./documentation/patterns";
-import { functions } from "./documentation/functions";
-import { variables } from "./documentation/variables";
-import { probabilities } from "./documentation/probabilities";
-import { lfos } from "./documentation/lfos";
-import { ziffers } from "./documentation/ziffers";
-import { synths } from "./documentation/synths";
-
+import { visualization } from "./documentation/more/visualization";
+import { chaining } from "./documentation/patterns/chaining";
+import { interaction } from "./documentation/basics/interaction";
+import { time } from "./documentation/learning/time/time";
+import { linear_time } from "./documentation/learning/time/linear_time";
+import { cyclical_time } from "./documentation/learning/time/cyclical_time";
+import { long_forms } from "./documentation/learning/time/long_forms";
+import { midi } from "./documentation/learning/midi";
+import { osc } from "./documentation/learning/osc";
+import { patterns } from "./documentation/patterns/patterns";
+import { functions } from "./documentation/patterns/functions";
+import { generators } from "./documentation/patterns/generators";
+import { variables } from "./documentation/patterns/variables";
+import { probabilities } from "./documentation/patterns/probabilities";
+import { lfos } from "./documentation/patterns/lfos";
+import { ziffers_basics } from "./documentation/patterns/ziffers/ziffers_basics";
+import { ziffers_scales } from "./documentation/patterns/ziffers/ziffers_scales";
+import { ziffers_rhythm } from "./documentation/patterns/ziffers/ziffers_rhythm";
+import { ziffers_algorithmic } from "./documentation/patterns/ziffers/ziffers_algorithmic";
+import { ziffers_tonnetz } from "./documentation/patterns/ziffers/ziffers_tonnetz";
+import { ziffers_syncing } from "./documentation/patterns/ziffers/ziffers_syncing";
+import { synths } from "./documentation/learning/audio_engine/synths";
 // Setting up the Markdown converter with syntax highlighting
 import showdown from "showdown";
 import showdownHighlight from "showdown-highlight";
+import "highlight.js/styles/atom-one-dark-reasonable.min.css";
 import { createDocumentationStyle } from "./DomElements";
+import { filters } from "./documentation/learning/audio_engine/filters";
 showdown.setFlavor("github");
 
 export const key_shortcut = (shortcut: string): string => {
-  return `<kbd class="lg:px-2 lg:py-1.5 px-1 py-1 lg:text-sm text-xs font-semibold text-gray-800 bg-gray-100 border border-gray-200 rounded-lg dark:bg-gray-600 dark:text-gray-100 dark:border-gray-500">${shortcut}</kbd>`;
+  return `<kbd class="lg:px-2 lg:py-1.5 px-1 py-1 lg:text-sm text-xs font-semibold text-brightwhite bg-brightblack border border-black rounded-lg">${shortcut}</kbd>`;
 };
 
 export const makeExampleFactory = (application: Editor): Function => {
@@ -56,19 +65,59 @@ export const makeExampleFactory = (application: Editor): Function => {
     return `
 <details ${open ? "open" : ""}>
   <summary >${description}
-    <button class="ml-4 py-1 align-top text-base px-4 hover:bg-green-700 bg-emerald-600 inline-block" onclick="app.api._playDocExample(app.api.codeExamples['${codeId}'])">▶️ Play</button>
-    <button class="py-1 text-base px-4 hover:bg-neutral-600 bg-neutral-500 inline-block " onclick="app.api._stopDocExample()">&#x23f8;&#xFE0F; Pause</button>
-    <button class="py-1 text-base px-4 hover:bg-neutral-900 bg-neutral-800 inline-block " onclick="navigator.clipboard.writeText(app.api.codeExamples['${codeId}'])">📎 Copy</button>
+    <button class="ml-4 py-1 align-top text-base px-4 hover:bg-brightgreen bg-green inline-block text-selection_foreground" onclick="app.api._playDocExample(app.api.codeExamples['${codeId}'])">▶️ Play</button>
+    <button class="py-1 text-base px-4 hover:brightyellow bg-yellow text-selection_foreground inline-block" onclick="app.api._stopDocExample()">&#x23f8;&#xFE0F; Pause</button>
+    <button class="py-1 text-base px-4 hover:bg-brightmagenta bg-magenta text-selection_foreground inline-block" onclick="navigator.clipboard.writeText(app.api.codeExamples['${codeId}'])">📎 Copy</button>
   </summary>
-  \`\`\`javascript
-  ${code}
-  \`\`\`
+  <pre><code class="hljs language-javascript">${code.trim()}</code></pre>
 </details>
 `;
   };
   return make_example;
 };
 
+export const documentation_pages = [
+  "introduction",
+  "atelier",
+  "sampler",
+  "amplitude",
+  "audio_basics",
+  "filters",
+  "effects",
+  "interface",
+  "interaction",
+  "code",
+  "time",
+  "linear",
+  "cyclic",
+  "longform",
+  "synths",
+  "chaining",
+  "patterns",
+  "ziffers_basics",
+  "ziffers_scales",
+  "ziffers_rhythm",
+  "ziffers_algorithmic",
+  "ziffers_tonnetz",
+  "ziffers_syncing",
+  "midi",
+  "osc",
+  "functions",
+  "generators",
+  "lfos",
+  "probabilities",
+  "variables",
+  "synchronisation",
+  "mouse",
+  "shortcuts",
+  "about",
+  "bonus",
+  "oscilloscope",
+  "sample_list",
+  "loading_samples",
+  "visualization"
+];
+
 export const documentation_factory = (application: Editor) => {
   /**
    * Creates the documentation for the given application.
@@ -79,6 +128,7 @@ export const documentation_factory = (application: Editor) => {
 
   return {
     introduction: introduction(application),
+    atelier: atelier(application),
     interface: software_interface(application),
     interaction: interaction(application),
     code: code(application),
@@ -86,25 +136,33 @@ export const documentation_factory = (application: Editor) => {
     linear: linear_time(application),
     cyclic: cyclical_time(application),
     longform: long_forms(application),
-    sound: sound(application),
     synths: synths(application),
+    filters: filters(application),
     chaining: chaining(application),
     patterns: patterns(application),
-    ziffers: ziffers(application),
+    ziffers_basics: ziffers_basics(application),
+    ziffers_scales: ziffers_scales(application),
+    ziffers_algorithmic: ziffers_algorithmic(application),
+    ziffers_rhythm: ziffers_rhythm(application),
+    ziffers_tonnetz: ziffers_tonnetz(application),
+    ziffers_syncing: ziffers_syncing(application),
     midi: midi(application),
+    osc: osc(application),
     lfos: lfos(application),
     variables: variables(application),
     probabilities: probabilities(application),
     functions: functions(application),
+    generators: generators(application),
     shortcuts: shortcuts(application),
     amplitude: amplitude(application),
-    reverb_delay: reverb(application),
+    effects: effects(application),
     sampler: sampler(application),
     mouse: mouse(application),
     oscilloscope: oscilloscope(application),
     audio_basics: audio_basics(application),
     synchronisation: synchronisation(application),
     bonus: bonus(application),
+    visualization: visualization(application),
     sample_list: sample_list(application),
     sample_banks: sample_banks(application),
     loading_samples: loading_samples(application),
@@ -126,13 +184,17 @@ export const showDocumentation = (app: Editor) => {
     document.getElementById("documentation")?.classList.remove("hidden");
     // Load and convert Markdown content from the documentation file
     let style = createDocumentationStyle(app);
-    let bindings = Object.keys(style).map((key) => ({
-      type: "output",
-      regex: new RegExp(`<${key}([^>]*)>`, "g"),
-      //@ts-ignore
-      replace: (match, p1) => `<${key} class="${style[key]}" ${p1}>`,
-    }));
-    updateDocumentationContent(app, bindings);
+
+    function update_and_assign(callback: Function) {
+      let bindings = Object.keys(style).map((key) => ({
+        type: "output",
+        regex: new RegExp(`<${key}([^>]*)>`, "g"),
+        //@ts-ignore
+        replace: (match, p1) => `<${key} class="${style[key]}" ${p1}>`,
+      }));
+      callback(bindings)
+    }
+    update_and_assign((e: Object) => updateDocumentationContent(app, e));
   }
 };
 
@@ -153,15 +215,34 @@ export const updateDocumentationContent = (app: Editor, bindings: any) => {
    * @param app - The editor application.
    * @param bindings - Additional bindings for the showdown converter.
    */
+  let loading_message: string = "<h1 class='border-4 py-2 px-2 mx-48 mt-48 text-center text-2xl text-brightwhite'>Loading! <b class='text-red'>Clic to refresh!</b></h1>";
   const converter = new showdown.Converter({
     emoji: true,
     moreStyling: true,
     backslashEscapesHTMLTags: true,
-    extensions: [showdownHighlight({ auto_detection: true }), ...bindings],
+    extensions: [showdownHighlight({
+      pre: true,
+      auto_detection: false
+    }), ...bindings],
   });
-  const converted_markdown = converter.makeHtml(
-    app.docs[app.currentDocumentationPane],
-  );
-  document.getElementById("documentation-content")!.innerHTML =
-    converted_markdown;
-};
+
+  if (Object.keys(app.docs).length === 0) {
+    app.docs = documentation_factory(app);
+  }
+
+  function _update_and_assign(callback: Function) {
+    const converted_markdown = converter.makeHtml(
+      app.docs[app.currentDocumentationPane],
+    );
+    callback(converted_markdown)
+  }
+  _update_and_assign((e: string) => {
+    let display_content = e === undefined ? loading_message : e;
+    document.getElementById("documentation-content")!.innerHTML = display_content;
+  })
+  if (document.getElementById("documentation-content")!.innerHTML.replace(/"/g, "'") == loading_message.replace(/"/g, "'")) {
+    setTimeout(() => {
+      updateDocumentationContent(app, bindings);
+    }, 100);
+  }
+}

src/DomElements.ts

@@ -18,6 +18,8 @@ export const singleElements = {
   load_universe_button: "load-universe-button",
   download_universe_button: "download-universes",
   upload_universe_button: "upload-universes",
+  upload_samples_button: "upload-samples",
+  sample_indicator: "sample-indicator",
   destroy_universes_button: "destroy-universes",
   documentation_button: "doc-button-1",
   eval_button: "eval-button-1",
@@ -43,6 +45,8 @@ export const singleElements = {
   midi_clock_checkbox: "send-midi-clock",
   midi_channels_scripts: "midi-channels-scripts",
   midi_clock_ppqn: "midi-clock-ppqn-input",
+  theme_selector: "theme-selector",
+  theme_previewer: "theme-previewer",
   load_demo_songs: "load-demo-songs",
   normal_mode_button: "normal-mode",
   vim_mode_button: "vim-mode",
@@ -52,6 +56,7 @@ export const singleElements = {
   error_line: "error_line",
   hydra_canvas: "hydra-bg",
   feedback: "feedback",
+  drawings: "drawings",
   scope: "scope",
 };
 
@@ -70,30 +75,30 @@ export const createDocumentationStyle = (app: Editor) => {
    */
 
   return {
-    h1: "text-white lg:text-4xl text-xl lg:ml-4 lg:mx-4 mx-2 lg:my-4 my-2 lg:mb-4 mb-4 border-b-4 pt-4 pb-3 px-2",
-    h2: "text-white lg:text-3xl text-xl lg:ml-4 lg:mx-4 mx-2 lg:my-4 my-2 lg:mb-4 mb-4 border-b-2 pt-12 pb-3 px-2",
-    h3: "text-white lg:text-2xl text-xl lg:ml-4 lg:mx-4 mx-2 lg:my-4 my-2 border-l-2 border-b-2 lg:mb-4 mb-4 pb-2 px-2 lg:mt-16",
+    h1: "text-brightwhite lg:text-4xl text-xl lg:ml-4 lg:mx-4 mx-2 lg:my-4 my-2 lg:mb-4 mb-4 border-b-4 pt-4 pb-3 px-2",
+    h2: "text-brightwhite lg:text-3xl text-xl lg:ml-4 lg:mx-4 mx-2 lg:my-4 my-2 lg:mb-4 mb-4 border-b-2 pt-12 pb-3 px-2",
+    h3: "text-brightwhite lg:text-2xl text-xl lg:ml-4 lg:mx-4 mx-2 lg:my-4 my-2 border-l-2 border-b-2 lg:mb-4 mb-4 pb-2 px-2 lg:mt-16",
     ul: "text-underline ml-12",
     li: "list-disc lg:text-2xl text-base text-white lg:mx-4 mx-2 my-4 my-2 leading-normal",
     p: "lg:text-2xl text-base text-white lg:mx-6 mx-2 my-4 leading-normal",
     warning:
-      "animate-pulse lg:text-2xl font-bold text-rose-600 lg:mx-6 mx-2 my-4 leading-normal",
-    a: "lg:text-2xl text-base text-orange-300",
+      "animate-pulse lg:text-2xl font-bold text-brightred lg:mx-6 mx-2 my-4 leading-normal",
+    a: "lg:text-2xl text-base text-brightred",
     code: `lg:my-4 sm:my-1 text-base lg:text-xl block whitespace-pre overflow-x-hidden`,
     icode:
-      "lg:my-1 my-1 lg:text-xl sm:text-xs text-white font-mono bg-neutral-600",
-    ic: "lg:my-1 my-1 lg:text-xl sm:text-xs text-white font-mono bg-neutral-600",
-    blockquote: "text-neutral-200 border-l-4 border-neutral-500 pl-4 my-4 mx-4",
+      "lg:my-1 my-1 lg:text-xl sm:text-xs text-brightwhite font-mono bg-brightblack",
+    ic: "lg:my-1 my-1 lg:text-xl sm:text-xs text-brightwhite font-mono bg-brightblack",
+    blockquote: "text-brightwhite border-l-4 border-white pl-4 my-4 mx-4",
     details:
-      "lg:mx-20 py-2 px-6 lg:text-2xl text-white border-l-8 box-border bg-neutral-900",
+      "lg:mx-20 py-2 px-6 lg:text-2xl text-white border-l-8 box-border bg-selection_foreground",
     summary: "font-semibold text-xl",
     table:
       "justify-center lg:my-12 my-2 lg:mx-12 mx-2 lg:text-2xl text-base w-full text-left text-white border-collapse",
     thead:
-      "text-xs text-gray-700 uppercase bg-gray-50 dark:bg-gray-700 dark:text-gray-400",
+      "text-xs text-gray-700 uppercase",
     th: "",
     td: "",
     tr: "",
-    box: "border bg-red-500",
+    box: "border bg-red",
   };
 };

src/EditorSetup.ts

@@ -1,5 +1,6 @@
 import { Prec } from "@codemirror/state";
 import { indentWithTab } from "@codemirror/commands";
+import { tags as t } from "@lezer/highlight";
 import {
   keymap,
   lineNumbers,
@@ -7,8 +8,6 @@ import {
   drawSelection,
   highlightActiveLine,
   dropCursor,
-  // rectangularSelection,
-  // crosshairCursor,
   highlightActiveLineGutter,
 } from "@codemirror/view";
 import { Extension, EditorState } from "@codemirror/state";
@@ -18,9 +17,10 @@ import {
   syntaxHighlighting,
   indentOnInput,
   bracketMatching,
+  HighlightStyle,
 } from "@codemirror/language";
 import { defaultKeymap, historyKeymap, history } from "@codemirror/commands";
-import { searchKeymap, highlightSelectionMatches } from "@codemirror/search";
+import { highlightSelectionMatches } from "@codemirror/search";
 import {
   autocompletion,
   closeBrackets,
@@ -30,12 +30,232 @@ import { lintKeymap } from "@codemirror/lint";
 import { Compartment } from "@codemirror/state";
 import { Editor } from "./main";
 import { EditorView } from "codemirror";
-import { toposTheme } from "./themes/toposTheme";
 import { javascript } from "@codemirror/lang-javascript";
 import { inlineHoveringTips } from "./documentation/inlineHelp";
 import { toposCompletions, soundCompletions } from "./documentation/inlineHelp";
 import { javascriptLanguage } from "@codemirror/lang-javascript";
 
+export const getCodeMirrorTheme = (theme: { [key: string]: string }): Extension => {
+  // @ts-ignore
+  const black = theme["black"],
+    red = theme["red"],
+    green = theme["green"],
+    yellow = theme["yellow"],
+    blue = theme["blue"],
+    magenta = theme["magenta"],
+    cyan = theme["cyan"],
+    white = theme["white"],
+    // @ts-ignore
+    brightblack = theme["brightblack"],
+    // @ts-ignore
+    brightred = theme["brightred"],
+    brightgreen = theme["brightgreen"],
+    // @ts-ignore
+    brightyellow = theme["brightyellow"],
+    // @ts-ignore
+    brightblue = theme["brightblue"],
+    // @ts-ignore
+    brightmagenta = theme["brightmagenta"],
+    // @ts-ignore
+    brightcyan = theme["brightcyan"],
+    brightwhite = theme["brightwhite"],
+    background = theme["background"],
+    selection_foreground = theme["selection_foreground"],
+    cursor = theme["cursor"],
+    foreground = theme["foreground"],
+    selection_background = theme["selection_background"];
+  const toposTheme = EditorView.theme({
+    "&": {
+      color: background,
+      backgroundColor: "transparent",
+      fontSize: "24px",
+      fontFamily: "IBM Plex Mono",
+    },
+    ".cm-content": {
+      caretColor: cursor,
+      fontFamily: "IBM Plex Mono",
+    },
+    ".cm-line": {
+      color: `${brightwhite}`,
+    },
+    ".cm-cursor, .cm-dropCursor": {
+      borderLeftColor: cursor,
+    },
+    "&.cm-focused .cm-selectionBackground, .cm-selectionBackground, .cm-content ::selection":
+    {
+      backgroundColor: brightwhite,
+      border: `1px solid ${brightwhite}`,
+    },
+    ".cm-panels": {
+      backgroundColor: selection_background,
+      color: red,
+    },
+    ".cm-panels.cm-panels-top": { borderBottom: "2px solid black" },
+    ".cm-panels.cm-panels-bottom": { borderTop: "2px solid black" },
+    ".cm-search.cm-panel": { backgroundColor: "transparent" },
+    ".cm-searchMatch": {
+      outline: `1px solid ${magenta}`,
+    },
+    ".cm-searchMatch.cm-searchMatch-selected": {
+      backgroundColor: red,
+    },
+    ".cm-activeLine": {
+      backgroundColor: `rgba(${(parseInt(selection_background.slice(1, 3), 16))}, ${(parseInt(selection_background.slice(3, 5), 16))}, ${(parseInt(selection_background.slice(5, 7), 16))}, 0.25)`,
+    },
+    ".cm-selectionMatch": {
+      backgroundColor: `rgba(${(parseInt(selection_background.slice(1, 3), 16))}, ${(parseInt(selection_background.slice(3, 5), 16))}, ${(parseInt(selection_background.slice(5, 7), 16))}, 0.25)`,
+      outline: `1px solid ${brightwhite}`,
+    },
+    "&.cm-focused .cm-matchingBracket": {
+      color: `rgba(${(parseInt(selection_background.slice(1, 3), 16))}, ${(parseInt(selection_background.slice(3, 5), 16))}, ${(parseInt(selection_background.slice(5, 7), 16))}, 0.25)`,
+    },
+    "&.cm-focused .cm-nonmatchingBracket": {
+      color: yellow,
+    },
+
+    ".cm-gutters": {
+      //backgroundColor: base00,
+      backgroundColor: "transparent",
+      color: foreground,
+    },
+    ".cm-activeLineGutter": {
+      backgroundColor: selection_background,
+      color: selection_foreground,
+    },
+
+    ".cm-foldPlaceholder": {
+      border: "none",
+      color: `${brightwhite}`,
+    },
+    ".cm-tooltip": {
+      border: "none",
+      backgroundColor: background,
+    },
+    ".cm-tooltip .cm-tooltip-arrow:before": {},
+    ".cm-tooltip .cm-tooltip-arrow:after": {
+      borderTopColor: background,
+      borderBottomColor: background,
+    },
+    ".cm-tooltip-autocomplete": {
+      "& > ul > li[aria-selected]": {
+        backgroundColor: background,
+        color: brightwhite,
+      },
+    },
+  },
+    { dark: true },
+  );
+
+  let toposHighlightStyle = HighlightStyle.define([
+    { tag: t.paren, color: brightwhite },
+    { tag: [t.propertyName, t.punctuation, t.variableName], color: brightwhite },
+    { tag: t.keyword, color: yellow },
+    { tag: [t.name, t.deleted, t.character, t.macroName], color: red, },
+    { tag: [t.function(t.variableName)], color: blue },
+    { tag: [t.labelName], color: brightwhite },
+    { tag: [t.color, t.constant(t.name), t.standard(t.name)], color: cyan, },
+    { tag: [t.definition(t.name), t.separator], color: brightwhite },
+    { tag: [t.brace], color: white },
+    { tag: [t.annotation], color: blue, },
+    { tag: [t.number, t.changed, t.annotation, t.modifier, t.self, t.namespace], color: yellow, },
+    { tag: [t.typeName, t.className], color: magenta, },
+    { tag: [t.operator, t.operatorKeyword], color: blue, },
+    { tag: [t.tagName], color: blue, },
+    { tag: [t.squareBracket], color: blue, },
+    { tag: [t.angleBracket], color: blue, },
+    { tag: [t.attributeName], color: red, },
+    { tag: [t.regexp], color: brightgreen, },
+    { tag: [t.quote], color: green, },
+    { tag: [t.string], color: green },
+    {
+      tag: t.link,
+      color: green,
+      textDecoration: "underline",
+      textUnderlinePosition: "under",
+    },
+    {
+      tag: [t.url, t.escape, t.special(t.string)],
+      color: green,
+    },
+    { tag: [t.meta], color: brightwhite },
+    { tag: [t.comment], color: brightwhite, fontStyle: "italic" },
+    { tag: t.monospace, color: brightwhite },
+    { tag: t.strong, fontWeight: "bold", color: white },
+    { tag: t.emphasis, fontStyle: "italic", color: white },
+    { tag: t.strikethrough, textDecoration: "line-through" },
+    { tag: t.heading, fontWeight: "bold", color: white },
+    { tag: t.heading1, fontWeight: "bold", color: white },
+    {
+      tag: [t.heading2, t.heading3, t.heading4],
+      fontWeight: "bold",
+      color: yellow,
+    },
+    {
+      tag: [t.heading5, t.heading6],
+      color: red,
+    },
+    { tag: [t.atom, t.bool, t.special(t.variableName)], color: green },
+    {
+      tag: [t.processingInstruction, t.inserted],
+      color: green,
+    },
+    {
+      tag: [t.contentSeparator],
+      color: green,
+    },
+    {
+      tag: [t.content],
+      color: brightwhite
+    },
+    {
+      tag: t.invalid,
+      color: red,
+      borderBottom: `1px dotted ${red}`
+    },
+    {
+      tag: t.null,
+      color: brightwhite,
+    }
+  ]);
+  return [toposTheme, syntaxHighlighting(toposHighlightStyle),
+  ]
+}
+
+const debugTheme = EditorView.theme({
+  ".cm-line span": {
+    position: "relative",
+  },
+  ".cm-line span:hover::after": {
+    position: "absolute",
+    bottom: "100%",
+    left: 0,
+    background: "black",
+    color: "white",
+    border: "solid 2px",
+    borderRadius: "5px",
+    content: "var(--tags)",
+    width: `max-content`,
+    padding: "1px 4px",
+    zIndex: 10,
+    pointerEvents: "none",
+  },
+});
+
+const debugHighlightStyle = HighlightStyle.define(
+  // @ts-ignore
+  Object.entries(t).map(([key, value]) => {
+    return { tag: value, "--tags": `"tag.${key}"` };
+  })
+);
+const debug = [debugTheme, syntaxHighlighting(debugHighlightStyle)];
+
+export const switchToDebugTheme = (app: Editor) => {
+  app.view.dispatch({
+    effects: app.themeCompartment.reconfigure(debug),
+  });
+}
+
+
 export const jsCompletions = javascriptLanguage.data.of({
   autocomplete: toposCompletions,
 });
@@ -59,7 +279,7 @@ export const editorSetup: Extension = (() => [
   highlightActiveLine(),
   highlightSelectionMatches(),
   keymap.of([
-    ...searchKeymap,
+    // ...searchKeymap,
     ...closeBracketsKeymap,
     ...defaultKeymap,
     ...historyKeymap,
@@ -70,6 +290,7 @@ export const editorSetup: Extension = (() => [
 export const installEditor = (app: Editor) => {
   app.vimModeCompartment = new Compartment();
   app.hoveringCompartment = new Compartment();
+  app.themeCompartment = new Compartment();
   app.completionsCompartment = new Compartment();
   app.withLineNumbers = new Compartment();
   app.chosenLanguage = new Compartment();
@@ -99,7 +320,10 @@ export const installEditor = (app: Editor) => {
       app.settings.completions ? [jsCompletions, toposSoundCompletions] : [],
     ),
     editorSetup,
-    toposTheme,
+    app.themeCompartment.of(
+      getCodeMirrorTheme(app.getColorScheme("Tomorrow Night Burns")),
+      // debug
+    ),
     app.chosenLanguage.of(javascript()),
   ];
   app.dynamicPlugins = new Compartment();

src/Evaluator.ts

@@ -81,6 +81,7 @@ export const tryEvaluate = async (
         );
         addFunctionToCache(candidateCode, newFunction);
       } else {
+        application.api.logOnce("Compilation error!");
         await evaluate(application, code, timeout);
       }
     }

src/FileManagement.ts

@@ -1,6 +1,6 @@
 // import { tutorial_universe } from "./universes/tutorial";
 import { gzipSync, decompressSync, strFromU8 } from "fflate";
-import { examples } from "./examples/excerpts";
+// import { examples } from "./examples/excerpts";
 import { type Editor } from "./main";
 import { uniqueNamesGenerator, colors, animals } from "unique-names-generator";
 import { tryEvaluate } from "./Evaluator";
@@ -63,7 +63,7 @@ export interface Settings {
   selected_universe: string;
   line_numbers: boolean;
   time_position: boolean;
-  load_demo_songs: boolean;
+  // load_demo_songs: boolean;
   tips: boolean;
   completions: boolean;
   send_clock: boolean;
@@ -136,7 +136,7 @@ export class AppSettings {
    */
 
   public vimMode: boolean = false;
-  public theme: string = "toposTheme";
+  public theme: string = "Everblush";
   public font: string = "IBM Plex Mono";
   public font_size: number = 24;
   public universes: Universes;
@@ -150,7 +150,7 @@ export class AppSettings {
   public midi_clock_input: string | undefined = undefined;
   public default_midi_input: string | undefined = undefined;
   public midi_clock_ppqn: number = 24;
-  public load_demo_songs: boolean = true;
+  // public load_demo_songs: boolean = true;
 
   constructor() {
     const settingsFromStorage = JSON.parse(
@@ -174,7 +174,7 @@ export class AppSettings {
       this.midi_clock_input = settingsFromStorage.midi_clock_input;
       this.midi_clock_ppqn = settingsFromStorage.midi_clock_ppqn || 24;
       this.default_midi_input = settingsFromStorage.default_midi_input;
-      this.load_demo_songs = settingsFromStorage.load_demo_songs;
+      // this.load_demo_songs = settingsFromStorage.load_demo_songs;
     } else {
       this.universes = template_universes;
     }
@@ -204,7 +204,7 @@ export class AppSettings {
       midi_clock_input: this.midi_clock_input,
       midi_clock_ppqn: this.midi_clock_ppqn,
       default_midi_input: this.default_midi_input,
-      load_demo_songs: this.load_demo_songs,
+      // load_demo_songs: this.load_demo_songs,
     };
   }
 
@@ -232,7 +232,7 @@ export class AppSettings {
     this.midi_clock_input = settings.midi_clock_input;
     this.midi_clock_ppqn = settings.midi_clock_ppqn;
     this.default_midi_input = settings.default_midi_input;
-    this.load_demo_songs = settings.load_demo_songs;
+    // this.load_demo_songs = settings.load_demo_songs;
     localStorage.setItem("topos", JSON.stringify(this.data));
   }
 }
@@ -245,23 +245,22 @@ export const initializeSelectedUniverse = (app: Editor): void => {
    * @param app - The main application
    * @returns void
    */
-  if (app.settings.load_demo_songs) {
-    let random_example = examples[Math.floor(Math.random() * examples.length)];
-    app.selected_universe = "Demo";
+  // if (app.settings.load_demo_songs) {
+  //   let random_example = examples[Math.floor(Math.random() * examples.length)];
+  //   app.selected_universe = "Demo";
+  //   app.universes[app.selected_universe] = structuredClone(template_universe);
+  //   app.universes[app.selected_universe].global.committed = random_example;
+  //   app.universes[app.selected_universe].global.candidate = random_example;
+  // } else {
+  try {
+    app.selected_universe = app.settings.selected_universe;
+    if (app.universes[app.selected_universe] === undefined)
+      app.universes[app.selected_universe] =
+        structuredClone(template_universe);
+  } catch (error) {
+    app.settings.selected_universe = "Welcome";
+    app.selected_universe = app.settings.selected_universe;
     app.universes[app.selected_universe] = structuredClone(template_universe);
-    app.universes[app.selected_universe].global.committed = random_example;
-    app.universes[app.selected_universe].global.candidate = random_example;
-  } else {
-    try {
-      app.selected_universe = app.settings.selected_universe;
-      if (app.universes[app.selected_universe] === undefined)
-        app.universes[app.selected_universe] =
-          structuredClone(template_universe);
-    } catch (error) {
-      app.settings.selected_universe = "Welcome";
-      app.selected_universe = app.settings.selected_universe;
-      app.universes[app.selected_universe] = structuredClone(template_universe);
-    }
   }
   (
     app.interface.universe_viewer as HTMLInputElement

src/IO/OSC.ts

@@ -0,0 +1,62 @@
+export interface OSCMessage {
+  address: string;
+  port: number;
+  args: object;
+  timetag: number;
+}
+
+// Send/receive messages from websocket
+export let outputSocket = new WebSocket("ws://localhost:3000");
+export let inputSocket = new WebSocket("ws://localhost:3001");
+
+export let oscMessages: any[] = [];
+inputSocket.addEventListener("message", (event) => {
+  let data = JSON.parse(event.data);
+  if (oscMessages.length >= 1000) {
+    oscMessages.shift();
+  }
+  oscMessages.push(data);
+});
+
+// @ts-ignore
+outputSocket.onopen = function (event) {
+  console.log("Connected to WebSocket Server");
+  // Send an OSC-like message
+  outputSocket.send(
+    JSON.stringify({
+      address: "/successful_connexion",
+      port: 3000,
+      args: {},
+    }),
+  );
+
+  outputSocket.onerror = function (error) {
+    console.log("Websocket Error:", error);
+  };
+
+  outputSocket.onmessage = function (event) {
+    console.log("Received: ", event.data);
+  };
+};
+
+export function sendToServer(message: OSCMessage) {
+  if (outputSocket.readyState === WebSocket.OPEN) {
+    outputSocket.send(JSON.stringify(message));
+  } else {
+    console.log("WebSocket is not open. Attempting to reconnect...");
+    if (
+      outputSocket.readyState === WebSocket.CONNECTING ||
+      outputSocket.readyState === WebSocket.OPEN
+    ) {
+      outputSocket.close();
+    }
+
+    // Create a new WebSocket connection
+    outputSocket = new WebSocket("ws://localhost:3000");
+
+    // Send the message once the socket is open
+    outputSocket.onopen = () => {
+      outputSocket.send(JSON.stringify(message));
+    };
+  }
+}

src/IO/SampleLoading.ts

@@ -0,0 +1,155 @@
+/**
+ * This code is taken from https://github.com/tidalcycles/strudel/pull/839. The logic is written by
+ * daslyfe (Jade Rose Rowland). I have tweaked it a bit to fit the needs of this project (TypeScript),
+ * etc... Many thanks for this piece of code! This code is initially part of the Strudel project:
+ * https://github.com/tidalcycles/strudel.
+ */
+
+// @ts-ignore
+import { registerSound, onTriggerSample } from "superdough";
+
+export const isAudioFile = (filename: string) => ['wav', 'mp3'].includes(filename.split('.').slice(-1)[0]);
+
+interface samplesDBConfig {
+  dbName: string,
+  table: string,
+  columns: string[],
+  version: number
+}
+
+export const samplesDBConfig = {
+  dbName: 'samples',
+  table: 'usersamples',
+  columns: ['data_url', 'title'],
+  version: 1
+}
+
+async function bufferToDataUrl(buf: Buffer) {
+  return new Promise((resolve) => {
+    var blob = new Blob([buf], { type: 'application/octet-binary' });
+    var reader = new FileReader();
+    reader.onload = function(event: Event) {
+      // @ts-ignore
+      resolve(event.target.result);
+    };
+    reader.readAsDataURL(blob);
+  });
+}
+
+const processFilesForIDB = async (files: FileList) => {
+  return await Promise.all(
+    Array.from(files)
+      .map(async (s: File) => {
+        const title = s.name;
+        if (!isAudioFile(title)) {
+          return;
+        }
+        //create obscured url to file system that can be fetched
+        const sUrl = URL.createObjectURL(s);
+        //fetch the sound and turn it into a buffer array
+        const buf = await fetch(sUrl).then((res) => res.arrayBuffer());
+        //create a url blob containing all of the buffer data
+        // @ts-ignore
+        // TODO: conversion to do here, remove ts-ignore
+        const base64 = await bufferToDataUrl(buf);
+        return {
+          title,
+          blob: base64,
+          id: s.webkitRelativePath,
+        };
+      })
+      .filter(Boolean),
+  ).catch((error) => {
+    console.log('Something went wrong while processing uploaded files', error);
+  });
+};
+
+
+export const registerSamplesFromDB = (config: samplesDBConfig, onComplete = () => { }) => {
+  openDB(config, (objectStore: IDBObjectStore) => {
+    let query = objectStore.getAll();
+    query.onsuccess = (event: Event) => {
+      // @ts-ignore
+      const soundFiles = event.target.result;
+      if (!soundFiles?.length) {
+        return;
+      }
+      const sounds = new Map();
+      [...soundFiles]
+        .sort((a, b) => a.title.localeCompare(b.title, undefined, { numeric: true, sensitivity: 'base' }))
+        .forEach((soundFile) => {
+          const title = soundFile.title;
+          if (!isAudioFile(title)) {
+            return;
+          }
+          const splitRelativePath = soundFile.id?.split('/');
+          const parentDirectory = splitRelativePath[splitRelativePath.length - 2];
+          const soundPath = soundFile.blob;
+          const soundPaths = sounds.get(parentDirectory) ?? new Set();
+          soundPaths.add(soundPath);
+          sounds.set(parentDirectory, soundPaths);
+        });
+
+      sounds.forEach((soundPaths, key) => {
+        const value = Array.from(soundPaths);
+        // @ts-ignore
+        registerSound(key, (t, hapValue, onended) => onTriggerSample(t, hapValue, onended, value), {
+          type: 'sample',
+          samples: value,
+          baseUrl: undefined,
+          prebake: false,
+          tag: "user",
+        });
+      });
+      onComplete();
+    };
+  });
+};
+
+export const openDB = (config: samplesDBConfig, onOpened: Function) => {
+  const { dbName, version, table, columns } = config
+
+  if (!('indexedDB' in window)) {
+    console.log('This browser doesn\'t support IndexedDB')
+    return
+  }
+  const dbOpen = indexedDB.open(dbName, version);
+
+
+  dbOpen.onupgradeneeded = (_event) => {
+    const db = dbOpen.result;
+    const objectStore = db.createObjectStore(table, { keyPath: 'id', autoIncrement: false });
+    columns.forEach((c: any) => {
+      objectStore.createIndex(c, c, { unique: false });
+    });
+  };
+  dbOpen.onerror = function(err: Event) {
+    console.log('Error opening DB: ', (err.target as IDBOpenDBRequest).error);
+  }
+  dbOpen.onsuccess = function(_event: Event) {
+    const db = dbOpen.result;
+    db.onversionchange = function() {
+      db.close();
+      alert("Database is outdated, please reload the page.")
+    };
+    const writeTransaction = db.transaction([table], 'readwrite'),
+      objectStore = writeTransaction.objectStore(table);
+    // Writing in the database here!
+    onOpened(objectStore)
+  }
+}
+
+export const uploadSamplesToDB = async (config: samplesDBConfig, files: FileList) => {
+  await processFilesForIDB(files).then((files) => {
+    const onOpened = (objectStore: IDBObjectStore, _db: IDBDatabase) => {
+      // @ts-ignore
+      files.forEach((file: File) => {
+        if (file == null) {
+          return;
+        }
+        objectStore.put(file);
+      });
+    };
+    openDB(config, onOpened);
+  });
+};

src/InterfaceLogic.ts

@@ -1,8 +1,10 @@
 import { EditorView } from "codemirror";
 import { vim } from "@replit/codemirror-vim";
 import { type Editor } from "./main";
+import colors from "./colors.json";
 import {
   documentation_factory,
+  documentation_pages,
   hideDocumentation,
   showDocumentation,
   updateDocumentationContent,
@@ -22,18 +24,11 @@ import { tryEvaluate } from "./Evaluator";
 import { inlineHoveringTips } from "./documentation/inlineHelp";
 import { lineNumbers } from "@codemirror/view";
 import { jsCompletions } from "./EditorSetup";
-import { createDocumentationStyle } from "./DomElements";
 import { saveState } from "./WindowBehavior";
+import { registerSamplesFromDB, samplesDBConfig, uploadSamplesToDB } from "./IO/SampleLoading";
 
 export const installInterfaceLogic = (app: Editor) => {
   // Initialize style
-  const documentationStyle = createDocumentationStyle(app);
-  const bindings = Object.keys(documentationStyle).map((key) => ({
-    type: "output",
-    regex: new RegExp(`<${key}([^>]*)>`, "g"),
-    //@ts-ignore
-    replace: (match, p1) => `<${key} class="${documentationStyle[key]}" ${p1}>`,
-  }));
 
   (app.interface.line_numbers_checkbox as HTMLInputElement).checked =
     app.settings.line_numbers;
@@ -49,17 +44,19 @@ export const installInterfaceLogic = (app: Editor) => {
     app.settings.midi_channels_scripts;
   (app.interface.midi_clock_ppqn as HTMLInputElement).value =
     app.settings.midi_clock_ppqn.toString();
-  (app.interface.load_demo_songs as HTMLInputElement).checked =
-    app.settings.load_demo_songs;
+  // (app.interface.load_demo_songs as HTMLInputElement).checked =
+  //   app.settings.load_demo_songs;
 
   const tabs = document.querySelectorAll('[id^="tab-"]');
   // Iterate over the tabs with an index
   for (let i = 0; i < tabs.length; i++) {
     tabs[i].addEventListener("click", (event) => {
       // Updating the CSS accordingly
-      tabs[i].classList.add("bg-orange-300");
+      tabs[i].classList.add("bg-foreground");
+      tabs[i].classList.add("text-selection_foreground");
       for (let j = 0; j < tabs.length; j++) {
-        if (j != i) tabs[j].classList.remove("bg-orange-300");
+        if (j != i) tabs[j].classList.remove("bg-foreground");
+        if (j != i) tabs[j].classList.remove("text-selection_foreground");
       }
       app.currentFile().candidate = app.view.state.doc.toString();
 
@@ -156,6 +153,21 @@ export const installInterfaceLogic = (app: Editor) => {
     );
   });
 
+  app.interface.upload_samples_button.addEventListener("input", async (event) => {
+    let fileInput = event.target as HTMLInputElement;
+    if (!fileInput.files?.length) {
+      return;
+    }
+    app.interface.sample_indicator.innerText = "Loading...";
+    app.interface.sample_indicator.classList.add("animate-pulse");
+    await uploadSamplesToDB(samplesDBConfig, fileInput.files).then(() => {
+        registerSamplesFromDB(samplesDBConfig, () => {
+          app.interface.sample_indicator.innerText = "Import samples";
+          app.interface.sample_indicator.classList.remove("animate-pulse");
+        });
+    });
+  });
+
   app.interface.upload_universe_button.addEventListener("click", () => {
     const fileInput = document.createElement("input");
     fileInput.type = "file";
@@ -289,6 +301,18 @@ export const installInterfaceLogic = (app: Editor) => {
     });
   });
 
+  app.interface.theme_selector.addEventListener("change", () => {
+    app.settings.theme = (app.interface.theme_selector as HTMLSelectElement).value;
+    app.readTheme(app.settings.theme);
+    // @ts-ignore
+    let selected_theme = colors[app.settings.theme as string];
+    let theme_preview = "";
+    for (const [key, _] of Object.entries(selected_theme)) {
+      theme_preview += `<p class="inline text-${key} bg-${key}">█</div>`;
+    }
+    app.interface.theme_previewer.innerHTML = theme_preview;
+  });
+
   app.interface.settings_button.addEventListener("click", () => {
     // Populate the font selector
     const fontFamilySelect = document.getElementById(
@@ -298,6 +322,26 @@ export const installInterfaceLogic = (app: Editor) => {
       fontFamilySelect.value = app.settings.font;
     }
 
+    app.interface.theme_selector.innerHTML = "";
+    let all_themes = Object.keys(colors);
+    all_themes.sort((a, b) => {
+      return a.toLowerCase().localeCompare(b.toLowerCase());
+    });
+    app.interface.theme_selector.innerHTML = all_themes.map((color) => {
+      return `<option value="${color}">${color}</option>`
+    }).join("");
+    // Set the selected theme in the selector to app.settings.theme
+    // @ts-ignore
+    app.interface.theme_selector.value = app.settings.theme;
+
+    // @ts-ignore
+    let selected_theme = colors[app.settings.theme as string];
+    let theme_preview = "<div class='ml-6'>";
+    for (const [key, _] of Object.entries(selected_theme)) {
+      theme_preview += `<p class="inline text-${key} bg-${key}">█</p>`;
+    }
+    theme_preview += "</div>";
+    app.interface.theme_previewer.innerHTML = theme_preview;
     // Populate the font family selector
     const doughNudgeRange = app.interface.dough_nudge_range as HTMLInputElement;
     doughNudgeRange.value = app.dough_nudge.toString();
@@ -329,8 +373,8 @@ export const installInterfaceLogic = (app: Editor) => {
     midiChannelsScripts.checked = app.settings.midi_channels_scripts;
     const midiClockPpqn = app.interface.midi_clock_ppqn as HTMLInputElement;
     midiClockPpqn.value = app.settings.midi_clock_ppqn.toString();
-    const loadDemoSongs = app.interface.load_demo_songs as HTMLInputElement;
-    loadDemoSongs.checked = app.settings.load_demo_songs;
+    // const loadDemoSongs = app.interface.load_demo_songs as HTMLInputElement;
+    // loadDemoSongs.checked = app.settings.load_demo_songs;
     const vimModeCheckbox = app.interface.vim_mode_checkbox as HTMLInputElement;
     vimModeCheckbox.checked = app.settings.vimMode;
 
@@ -458,12 +502,12 @@ export const installInterfaceLogic = (app: Editor) => {
     app.settings.midi_clock_ppqn = value;
   });
 
-  app.interface.load_demo_songs.addEventListener("change", () => {
-    let checked = (app.interface.load_demo_songs as HTMLInputElement).checked
-      ? true
-      : false;
-    app.settings.load_demo_songs = checked;
-  });
+  // app.interface.load_demo_songs.addEventListener("change", () => {
+  //   let checked = (app.interface.load_demo_songs as HTMLInputElement).checked
+  //     ? true
+  //     : false;
+  //   app.settings.load_demo_songs = checked;
+  // });
 
   app.interface.universe_creator.addEventListener("submit", (event) => {
     event.preventDefault();
@@ -486,51 +530,29 @@ export const installInterfaceLogic = (app: Editor) => {
 
   tryEvaluate(app, app.universes[app.selected_universe.toString()].init);
 
-  [
-    "introduction",
-    "sampler",
-    "amplitude",
-    "audio_basics",
-    "reverb_delay",
-    "interface",
-    "interaction",
-    "code",
-    "time",
-    "linear",
-    "cyclic",
-    "longform",
-    // "sound",
-    "synths",
-    "chaining",
-    "patterns",
-    "ziffers",
-    "midi",
-    "functions",
-    "lfos",
-    "probabilities",
-    "variables",
-    "synchronisation",
-    "mouse",
-    "shortcuts",
-    "about",
-    "bonus",
-    "oscilloscope",
-    "sample_list",
-    "loading_samples",
-  ].forEach((e) => {
+  documentation_pages.forEach((e) => {
     let name = `docs_` + e;
-    document.getElementById(name)!.addEventListener("click", async () => {
-      if (name !== "docs_samples") {
+
+    // Check if the element exists
+    let element = document.getElementById(name);
+    if (element) {
+      element.addEventListener("click", async () => {
+        // Clear query params & set id as hash paremeter for uri
+        window.history.replaceState({}, "", window.location.pathname);
+        window.location.hash = e;
+        app.docs = documentation_factory(app);
         app.currentDocumentationPane = e;
-        updateDocumentationContent(app, bindings);
-      } else {
-        console.log("Loading samples!");
-        await loadSamples().then(() => {
-          app.docs = documentation_factory(app);
-          app.currentDocumentationPane = e;
-          updateDocumentationContent(app, bindings);
-        });
-      }
-    });
+        if (name !== "docs_sample_list") {
+          updateDocumentationContent(app, app.bindings);
+        } else {
+          console.log("Loading samples!");
+          await loadSamples().then(() => {
+            updateDocumentationContent(app, app.bindings);
+          });
+        }
+      });
+    } else {
+      console.log("Could not find element " + name);
+    }
   });
-};
+};

src/KeyActions.ts

@@ -105,6 +105,18 @@ export const registerOnKeyDown = (app: Editor) => {
     if (event.key === "Enter" && event.shiftKey && event.ctrlKey) {
       event.preventDefault();
       app.currentFile().candidate = app.view.state.doc.toString();
+      app.api.onceEvaluator = true;
+      app.api.forceEvaluator = true;
+      tryEvaluate(app, app.currentFile());
+      app.flashBackground("#404040", 200);
+    }
+
+    // Force eval with clearing cache
+    if (event.ctrlKey && event.shiftKey && (event.key === "Backspace" || event.key === "Delete")) {
+      event.preventDefault();
+      app.api.clearPatternCache();
+      app.currentFile().candidate = app.view.state.doc.toString();
+      app.api.forceEvaluator = true;
       tryEvaluate(app, app.currentFile());
       app.flashBackground("#404040", 200);
     }

src/TransportNode.js

@@ -0,0 +1,65 @@
+import { tryEvaluate } from "./Evaluator";
+const zeroPad = (num, places) => String(num).padStart(places, "0");
+
+export class TransportNode extends AudioWorkletNode {
+  constructor(context, options, application) {
+    super(context, "transport", options);
+    this.app = application;
+    this.port.addEventListener("message", this.handleMessage);
+    this.port.start();
+    this.timeviewer = document.getElementById("timeviewer");
+  }
+
+  /** @type {(this: MessagePort, ev: MessageEvent<any>) => any} */
+  handleMessage = (message) => {
+    if(message.data) {
+      if (message.data.type === "bang") {
+        if(this.app.clock.running) {
+          if (this.app.settings.send_clock) {
+            this.app.api.MidiConnection.sendMidiClock();
+          }
+          const futureTimeStamp = this.app.clock.convertTicksToTimeposition(
+            this.app.clock.tick
+          );
+          this.app.clock.time_position = futureTimeStamp;
+          this.timeviewer.innerHTML = `${zeroPad(futureTimeStamp.bar, 2)}:${futureTimeStamp.beat + 1
+            }:${zeroPad(futureTimeStamp.pulse, 2)} / ${this.app.clock.bpm}`;
+          if (this.app.exampleIsPlaying) {
+            tryEvaluate(this.app, this.app.example_buffer);
+          } else {
+            tryEvaluate(this.app, this.app.global_buffer);
+          }
+          this.app.clock.incrementTick(message.data.bpm);
+        }
+      }
+    }
+  };
+
+  start() {
+    this.port.postMessage({ type: "start" });
+  }
+
+  pause() {
+    this.port.postMessage({ type: "pause" });
+  }
+
+  resume() {
+    this.port.postMessage({ type: "resume" });
+  }
+
+  setBPM(bpm) {
+    this.port.postMessage({ type: "bpm", value: bpm });
+  }
+
+  setPPQN(ppqn) {
+    this.port.postMessage({ type: "ppqn", value: ppqn });
+  }
+
+  setNudge(nudge) {
+    this.port.postMessage({ type: "nudge", value: nudge });
+  }
+
+  stop() {
+    this.port.postMessage({type: "stop" });
+  }
+}

src/TransportProcessor.js

@@ -0,0 +1,47 @@
+class TransportProcessor extends AudioWorkletProcessor {
+    constructor(options) {
+      super(options);
+      this.port.addEventListener("message", this.handleMessage);
+      this.port.start();
+      this.nudge = 0;
+      this.started = false;
+      this.bpm = 120;
+      this.ppqn = 48;
+      this.currentPulsePosition = 0;
+    }
+  
+    handleMessage = (message) => {
+      if (message.data && message.data.type === "ping") {
+        this.port.postMessage(message.data);
+      } else if (message.data.type === "start") {
+        this.started = true;
+      } else if (message.data.type === "pause") {
+        this.started = false;
+      } else if (message.data.type === "stop") {
+        this.started = false;
+      } else if (message.data.type === "bpm") {
+        this.bpm = message.data.value;
+        this.currentPulsePosition = currentTime;
+      } else if (message.data.type === "ppqn") {
+        this.ppqn = message.data.value;
+        this.currentPulsePosition = currentTime;
+      } else if (message.data.type === "nudge") {
+        this.nudge = message.data.value;
+      }
+    };
+  
+    process(inputs, outputs, parameters) {
+      if (this.started) {
+        const adjustedCurrentTime = currentTime + this.nudge / 100;
+        const beatNumber = adjustedCurrentTime / (60 / this.bpm);
+        const currentPulsePosition = Math.ceil(beatNumber * this.ppqn);
+        if (currentPulsePosition > this.currentPulsePosition) {
+          this.currentPulsePosition = currentPulsePosition;
+          this.port.postMessage({ type: "bang", bpm: this.bpm });
+        }
+      }
+      return true;
+    }
+  }
+  
+  registerProcessor("transport", TransportProcessor);

src/Utils/Generic.ts

@@ -69,6 +69,15 @@ export function arrayOfObjectsToObjectWithArrays<T extends Record<string, any>>(
   );
 }
 
+export function maybeAtomic<T>(value: T): T | T[] {
+  /*
+    * Returns first value of array if array of length 1, otherwise returns value
+    * @param {any} value - Value to check
+    * @returns {any} Value or array
+    */
+  return Array.isArray(value) && value.length === 1 ? value[0] : value;
+}
+
 export function filterObject(
   obj: Record<string, any>,
   filter: string[],
@@ -85,3 +94,17 @@ export function filterObject(
     Object.entries(obj).filter(([key]) => filter.includes(key)),
   );
 }
+
+export const maybeToNumber = (something: any): number | any => {
+  // If something is BigInt
+  if (typeof something === "bigint") {
+    return Number(something);
+  } else {
+    return something;
+  }
+}
+
+export const GeneratorType = (function*(){yield undefined;}).constructor;
+export const GeneratorIteratorType = (function*(){yield undefined;}).prototype.constructor;
+export const isGenerator = (v:any) => Object.prototype.toString.call(v) === '[object Generator]';
+export const isGeneratorFunction = (v:any) => Object.prototype.toString.call(v) === '[object GeneratorFunction]';

src/Visuals/CanvasVisuals.ts

@@ -0,0 +1,593 @@
+export type ShapeObject = {
+  x: number;
+  y: number;
+  x1: number;
+  y1: number;
+  x2: number;
+  y2: number;
+  radius: number;
+  width: number;
+  height: number;
+  fillStyle: string;
+  secondary: string;
+  strokeStyle: string;
+  rotation: number;
+  points: number;
+  outerRadius: number;
+  eyeSize: number;
+  happiness: number;
+  slices: number;
+  gap: number;
+  font: string;
+  fontSize: number;
+  text: string;
+  filter: string;
+  url: string;
+  curve: number;
+  curves: number;
+  stroke: string;
+  eaten: number;
+  hole: number;
+};
+
+export const drawBackground = (
+  canvas: HTMLCanvasElement,
+  color: string | number,
+  ...gb: number[]
+): void => {
+  /**
+   * Set background color of the canvas.
+   * @param color - The color to set. String or 3 numbers representing RGB values.
+   */
+  const ctx = canvas.getContext("2d")!;
+  if (typeof color === "number") color = `rgb(${color},${gb[0]},${gb[1]})`;
+  ctx.fillStyle = color;
+  ctx.fillRect(0, 0, canvas.width, canvas.height);
+};
+
+export const createLinearGradient = (
+  canvas: HTMLCanvasElement,
+  x1: number,
+  y1: number,
+  x2: number,
+  y2: number,
+  ...stops: (number | string)[]
+): CanvasGradient => {
+  const ctx = canvas.getContext("2d")!;
+  const gradient = ctx.createLinearGradient(x1, y1, x2, y2);
+  // Parse pairs of values from stops
+  for (let i = 0; i < stops.length; i += 2) {
+    let color = stops[i + 1];
+    if (typeof color === "number")
+      color = `rgb(${color},${stops[i + 2]},${stops[i + 3]})`;
+    gradient.addColorStop(stops[i] as number, color);
+  }
+  return gradient;
+};
+
+export const createRadialGradient = (
+  canvas: HTMLCanvasElement,
+  x1: number,
+  y1: number,
+  r1: number,
+  x2: number,
+  y2: number,
+  r2: number,
+  ...stops: (number | string)[]
+) => {
+  /**
+   * Set radial gradient on the canvas.
+   * @param x1 - The x-coordinate of the start circle
+   * @param y1 - The y-coordinate of the start circle
+   * @param r1 - The radius of the start circle
+   * @param x2 - The x-coordinate of the end circle
+   * @param y2 - The y-coordinate of the end circle
+   * @param r2 - The radius of the end circle
+   * @param stops - The stops to set. Pairs of numbers representing the position and color of the stop.
+   */
+  const ctx = canvas.getContext("2d")!;
+  const gradient = ctx.createRadialGradient(x1, y1, r1, x2, y2, r2);
+  for (let i = 0; i < stops.length; i += 2) {
+    let color = stops[i + 1];
+    if (typeof color === "number")
+      color = `rgb(${color},${stops[i + 2]},${stops[i + 3]})`;
+    gradient.addColorStop(stops[i] as number, color);
+  }
+  return gradient;
+};
+
+export const createConicGradient = (
+  canvas: HTMLCanvasElement,
+  x: number,
+  y: number,
+  angle: number,
+  ...stops: (number | string)[]
+) => {
+  /**
+   * Set conic gradient on the canvas.
+   * @param x - The x-coordinate of the center of the gradient
+   * @param y - The y-coordinate of the center of the gradient
+   * @param angle - The angle of the gradient, in radians
+   * @param stops - The stops to set. Pairs of numbers representing the position and color of the stop.
+   */
+  const ctx = canvas.getContext("2d")!;
+  const gradient = ctx.createConicGradient(x, y, angle);
+  for (let i = 0; i < stops.length; i += 2) {
+    let color = stops[i + 1];
+    if (typeof color === "number")
+      color = `rgb(${color},${stops[i + 2]},${stops[i + 3]})`;
+    gradient.addColorStop(stops[i] as number, color);
+  }
+  return gradient;
+};
+
+export const drawGradientImage = (
+  canvas: HTMLCanvasElement,
+  time: number = 666
+) => {
+  /* TODO: This works but is really resource heavy. Should do method for requestAnimationFrame? */
+  const context = canvas.getContext("2d")!;
+  const { width, height } = context.canvas;
+  const imageData = context.getImageData(0, 0, width, height);
+
+  for (let p = 0; p < imageData.data.length; p += 4) {
+    const i = p / 4;
+    const x = i % width;
+    const y = (i / width) >>> 0;
+
+    const red = 64 + (128 * x) / width + 64 * Math.sin(time / 1000);
+    const green = 64 + (128 * y) / height + 64 * Math.cos(time / 1000);
+    const blue = 128;
+
+    imageData.data[p + 0] = red;
+    imageData.data[p + 1] = green;
+    imageData.data[p + 2] = blue;
+    imageData.data[p + 3] = 255;
+  }
+
+  context.putImageData(imageData, 0, 0);
+  return true;
+};
+
+export const drawBalloid = (
+  canvas: HTMLCanvasElement,
+  curves: number,
+  radius: number,
+  curve: number,
+  fillStyle: string,
+  secondary: string,
+  x: number,
+  y: number
+): void => {
+  const ctx = canvas.getContext("2d")!;
+
+  // Draw the shape using quadratic Bézier curves
+  ctx.beginPath();
+  ctx.fillStyle = fillStyle;
+
+  if (curves === 0) {
+    // Draw a circle if curves = 0
+    ctx.arc(x, y, radius, 0, 2 * Math.PI);
+    ctx.closePath();
+    ctx.fill();
+  } else if (curves === 1) {
+    // Draw a single curve (ellipse) if curves = 1
+    ctx.ellipse(x, y, radius * 0.8, radius * curve * 0.7, 0, 0, 2 * Math.PI);
+    ctx.closePath();
+    ctx.fill();
+  } else if (curves === 2) {
+    // Draw a shape with two symmetric curves starting from the top and meeting at the bottom
+    ctx.moveTo(x, y - radius);
+
+    // First curve
+    ctx.quadraticCurveTo(x + radius * curve, y, x, y + radius);
+
+    // Second symmetric curve
+    ctx.quadraticCurveTo(x - radius * curve, y, x, y - radius);
+
+    ctx.closePath();
+    ctx.fill();
+  } else {
+    // Draw the curved shape with the specified number of curves
+    ctx.moveTo(x, y - radius);
+    let points = [];
+    for (let i = 0; i < curves; i++) {
+      const startAngle = (i / curves) * 2 * Math.PI;
+      const endAngle = startAngle + (2 * Math.PI) / curves;
+
+      const controlX =
+        x + radius * curve * Math.cos(startAngle + Math.PI / curves);
+      const controlY =
+        y + radius * curve * Math.sin(startAngle + Math.PI / curves);
+      points.push([
+        x + radius * Math.cos(startAngle),
+        y + radius * Math.sin(startAngle),
+      ]);
+      ctx.moveTo(
+        x + radius * Math.cos(startAngle),
+        y + radius * Math.sin(startAngle)
+      );
+      ctx.quadraticCurveTo(
+        controlX,
+        controlY,
+        x + radius * Math.cos(endAngle),
+        y + radius * Math.sin(endAngle)
+      );
+    }
+    ctx.closePath();
+    ctx.closePath();
+    ctx.fill();
+
+    ctx.beginPath();
+    ctx.fillStyle = secondary;
+    // Form the shape from points with straight lines and fill it
+    ctx.moveTo(points[0][0], points[0][1]);
+    for (let point of points) ctx.lineTo(point[0], point[1]);
+    // Close and fill
+
+    ctx.closePath();
+    ctx.fill();
+  }
+};
+
+export const drawEquilateral = (
+  canvas: HTMLCanvasElement,
+  radius: number,
+  fillStyle: string,
+  rotation: number,
+  x: number,
+  y: number
+): void => {
+  const ctx = canvas.getContext("2d")!;
+  ctx.save();
+  ctx.translate(x, y);
+  ctx.rotate((rotation * Math.PI) / 180);
+  ctx.beginPath();
+  ctx.moveTo(0, -radius);
+  ctx.lineTo(radius, radius);
+  ctx.lineTo(-radius, radius);
+  ctx.closePath();
+  ctx.fillStyle = fillStyle;
+  ctx.fill();
+  ctx.restore();
+};
+
+export const drawTriangular = (
+  canvas: HTMLCanvasElement,
+  width: number,
+  height: number,
+  fillStyle: string,
+  rotation: number,
+  x: number,
+  y: number
+): void => {
+  const ctx = canvas.getContext("2d")!;
+  ctx.save();
+  ctx.translate(x, y);
+  ctx.rotate((rotation * Math.PI) / 180);
+  ctx.beginPath();
+  ctx.moveTo(0, -height);
+  ctx.lineTo(width, height);
+  ctx.lineTo(-width, height);
+  ctx.closePath();
+  ctx.fillStyle = fillStyle;
+  ctx.fill();
+  ctx.restore();
+};
+
+export const drawBall = (
+  canvas: HTMLCanvasElement,
+  radius: number,
+  fillStyle: string,
+  x: number,
+  y: number
+): void => {
+  const ctx = canvas.getContext("2d")!;
+  ctx.beginPath();
+  ctx.arc(x, y, radius, 0, 2 * Math.PI);
+  ctx.fillStyle = fillStyle;
+  ctx.fill();
+  ctx.closePath();
+};
+
+export const drawDonut = (
+  canvas: HTMLCanvasElement,
+  slices: number,
+  eaten: number,
+  radius: number,
+  hole: number,
+  fillStyle: string,
+  secondary: string,
+  stroke: string,
+  rotation: number,
+  x: number,
+  y: number
+): void => {
+  const ctx = canvas.getContext("2d")!;
+  ctx.save();
+  ctx.translate(x, y);
+  ctx.rotate((rotation * Math.PI) / 180);
+
+  if (slices < 2) {
+    ctx.beginPath();
+    ctx.arc(0, 0, radius, 0, 2 * Math.PI);
+    ctx.closePath();
+    ctx.fillStyle = slices < 1 ? secondary : fillStyle;
+    ctx.fill();
+
+    ctx.beginPath();
+    ctx.arc(0, 0, hole, 0, 2 * Math.PI);
+    ctx.closePath();
+    ctx.fillStyle = secondary;
+    ctx.fill();
+
+    ctx.restore();
+  }
+
+  // Draw slices as arcs
+  const totalSlices = slices;
+  const sliceAngle = (2 * Math.PI) / totalSlices;
+  for (let i = 0; i < totalSlices; i++) {
+    const startAngle = i * sliceAngle;
+    const endAngle = (i + 1) * sliceAngle;
+
+    // Calculate the position of the outer arc
+    const outerStartX = hole * Math.cos(startAngle);
+    const outerStartY = hole * Math.sin(startAngle);
+
+    ctx.beginPath();
+    ctx.moveTo(outerStartX, outerStartY);
+    ctx.arc(0, 0, radius, startAngle, endAngle);
+    ctx.arc(0, 0, hole, endAngle, startAngle, true);
+    ctx.closePath();
+
+    // Fill and stroke the slices with the specified fill style
+    if (i < slices - eaten) {
+      // Regular slices are white
+      ctx.fillStyle = fillStyle;
+    } else {
+      // Missing slices are black
+      ctx.fillStyle = secondary;
+    }
+    ctx.lineWidth = 2;
+    ctx.fill();
+    ctx.strokeStyle = stroke;
+    ctx.stroke();
+  }
+
+  ctx.restore();
+};
+
+export const drawPie = (
+  canvas: HTMLCanvasElement,
+  slices: number,
+  eaten: number,
+  radius: number,
+  fillStyle: string,
+  secondary: string,
+  stroke: string,
+  rotation: number,
+  x: number,
+  y: number
+): void => {
+  const ctx = canvas.getContext("2d")!;
+  ctx.save();
+  ctx.translate(x, y);
+  ctx.rotate((rotation * Math.PI) / 180);
+
+  if (slices < 2) {
+    ctx.beginPath();
+    ctx.arc(0, 0, radius, 0, 2 * Math.PI);
+    ctx.closePath();
+    ctx.fillStyle = slices < 1 ? secondary : fillStyle;
+    ctx.fill();
+    ctx.restore();
+  }
+
+  // Draw slices as arcs
+  const totalSlices = slices;
+  const sliceAngle = (2 * Math.PI) / totalSlices;
+  for (let i = 0; i < totalSlices; i++) {
+    const startAngle = i * sliceAngle;
+    const endAngle = (i + 1) * sliceAngle;
+    ctx.beginPath();
+    ctx.moveTo(0, 0);
+    ctx.arc(0, 0, radius, startAngle, endAngle);
+    ctx.lineTo(0, 0); // Connect to center
+    ctx.closePath();
+
+    // Fill and stroke the slices with the specified fill style
+    if (i < slices - eaten) {
+      // Regular slices are white
+      ctx.fillStyle = fillStyle;
+    } else {
+      // Missing slices are black
+      ctx.fillStyle = secondary;
+    }
+    ctx.lineWidth = 2;
+    ctx.fill();
+    ctx.strokeStyle = stroke;
+    ctx.stroke();
+  }
+
+  ctx.restore();
+};
+
+export const drawStar = (
+  canvas: HTMLCanvasElement,
+  points: number,
+  radius: number,
+  fillStyle: string,
+  rotation: number,
+  outerRadius: number,
+  x: number,
+  y: number
+): void => {
+  if (points < 1) return drawBall(canvas, radius, fillStyle, x, y);
+  if (points == 1) return drawEquilateral(canvas, radius, fillStyle, 0, x, y);
+  const ctx = canvas.getContext("2d")!;
+  ctx.save();
+  ctx.translate(x, y);
+  ctx.rotate((rotation * Math.PI) / 180);
+  ctx.beginPath();
+  ctx.moveTo(0, -radius);
+  for (let i = 0; i < points; i++) {
+    ctx.rotate(Math.PI / points);
+    ctx.lineTo(0, -(radius * outerRadius));
+    ctx.rotate(Math.PI / points);
+    ctx.lineTo(0, -radius);
+  }
+  ctx.closePath();
+  ctx.fillStyle = fillStyle;
+  ctx.fill();
+  ctx.restore();
+};
+
+export const drawStroke = (
+  canvas: HTMLCanvasElement,
+  width: number,
+  strokeStyle: string,
+  rotation: number = 0,
+  x1: number,
+  y1: number,
+  x2: number,
+  y2: number
+): void => {
+  const ctx = canvas.getContext("2d")!;
+  ctx.save();
+  ctx.translate(x1, y1);
+  ctx.rotate((rotation * Math.PI) / 180);
+  ctx.beginPath();
+  ctx.moveTo(0, 0);
+  ctx.lineTo(x2 - x1, y2 - y1);
+  ctx.lineWidth = width;
+  ctx.strokeStyle = strokeStyle;
+  ctx.stroke();
+  ctx.restore();
+};
+
+export const drawBox = (
+  canvas: HTMLCanvasElement,
+  width: number,
+  height: number,
+  fillStyle: string,
+  rotation: number,
+  x: number,
+  y: number
+): void => {
+  const ctx = canvas.getContext("2d")!;
+  ctx.save();
+  ctx.translate(x, y);
+  ctx.rotate((rotation * Math.PI) / 180);
+  ctx.fillStyle = fillStyle;
+  ctx.fillRect(0, 0, width, height);
+  ctx.restore();
+};
+
+export const drawSmiley = (
+  canvas: HTMLCanvasElement,
+  happiness: number,
+  radius: number,
+  eyeSize: number,
+  fillStyle: string,
+  rotation: number,
+  x: number,
+  y: number
+): void => {
+  const ctx = canvas.getContext("2d")!;
+  // Map the rotation value to an angle within the range of -PI to PI
+  const rotationAngle = (rotation / 100) * Math.PI;
+  ctx.save();
+  ctx.translate(x, y);
+  ctx.rotate(rotationAngle);
+
+  // Draw face
+  ctx.beginPath();
+  ctx.arc(0, 0, radius, 0, 2 * Math.PI);
+  ctx.fillStyle = fillStyle;
+  ctx.fill();
+  ctx.lineWidth = radius / 20;
+  ctx.strokeStyle = "black";
+  ctx.stroke();
+
+  // Draw eyes
+  const eyeY = -radius / 5;
+  const eyeXOffset = radius / 2.5;
+  const eyeRadiusX = radius / 8;
+  const eyeRadiusY = (eyeSize * radius) / 10;
+
+  ctx.beginPath();
+  ctx.ellipse(-eyeXOffset, eyeY, eyeRadiusX, eyeRadiusY, 0, 0, 2 * Math.PI);
+  ctx.fillStyle = "black";
+  ctx.fill();
+
+  ctx.beginPath();
+  ctx.ellipse(eyeXOffset, eyeY, eyeRadiusX, eyeRadiusY, 0, 0, 2 * Math.PI);
+  ctx.fillStyle = "black";
+  ctx.fill();
+
+  // Draw mouth with happiness number -1.0 to 1.0. 0.0 Should be a straight line.
+  const mouthY = radius / 2;
+  const mouthLength = radius * 0.9;
+  const smileFactor = 0.25; // Adjust for the smile curvature
+
+  let controlPointX = 0;
+  let controlPointY = 0;
+
+  if (happiness >= 0) {
+    controlPointY = mouthY + (happiness * smileFactor * radius) / 2;
+  } else {
+    controlPointY = mouthY + (happiness * smileFactor * radius) / 2;
+  }
+
+  ctx.beginPath();
+  ctx.moveTo(-mouthLength / 2, mouthY);
+  ctx.quadraticCurveTo(controlPointX, controlPointY, mouthLength / 2, mouthY);
+  ctx.lineWidth = 10;
+  ctx.strokeStyle = "black";
+  ctx.stroke();
+  ctx.restore();
+};
+
+export const drawText = (
+  canvas: HTMLCanvasElement,
+  text: string,
+  fontSize: number,
+  rotation: number,
+  font: string,
+  x: number,
+  y: number,
+  fillStyle: string,
+  filter: string
+): void => {
+  const ctx = canvas.getContext("2d")!;
+  ctx.save();
+  ctx.translate(x, y);
+  ctx.rotate((rotation * Math.PI) / 180);
+  ctx.filter = filter;
+  ctx.font = `${fontSize}px ${font}`;
+  ctx.fillStyle = fillStyle;
+  ctx.fillText(text, 0, 0);
+  ctx.restore();
+};
+
+export const drawImage = (
+  canvas: HTMLCanvasElement,
+  url: string,
+  width: number,
+  height: number,
+  rotation: number,
+  x: number,
+  y: number,
+  filter: string = "none"
+): void => {
+  const ctx = canvas.getContext("2d")!;
+  ctx.save();
+  ctx.translate(x, y);
+  ctx.rotate((rotation * Math.PI) / 180);
+  ctx.filter = filter;
+  const image = new Image();
+  image.src = url;
+  ctx.drawImage(image, -width / 2, -height / 2, width, height);
+  ctx.restore();
+};

src/WindowBehavior.ts

@@ -1,4 +1,5 @@
 import { type Editor } from "./main";
+import { outputSocket, inputSocket } from "./IO/OSC";
 
 const handleResize = (canvas: HTMLCanvasElement) => {
   if (!canvas) return;
@@ -26,6 +27,9 @@ export const saveBeforeExit = (app: Editor): null => {
   app.currentFile().candidate = app.view.state.doc.toString();
   app.currentFile().committed = app.view.state.doc.toString();
   app.settings.saveApplicationToLocalStorage(app.universes, app.settings);
+  // Close the websocket
+  inputSocket.close();
+  outputSocket.close();
   return null;
 };
 
@@ -40,6 +44,9 @@ export const installWindowBehaviors = (
   window.addEventListener("resize", () =>
     handleResize(app.interface.feedback as HTMLCanvasElement),
   );
+  window.addEventListener("resize", () =>
+  handleResize(app.interface.drawings as HTMLCanvasElement),
+);
   window.addEventListener("beforeunload", (event) => {
     event.preventDefault();
     saveBeforeExit(app);

src/assets/favicon.svg

@@ -0,0 +1,46 @@
+<?xml version="1.0" standalone="no"?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 20010904//EN"
+ "http://www.w3.org/TR/2001/REC-SVG-20010904/DTD/svg10.dtd">
+<svg version="1.0" xmlns="http://www.w3.org/2000/svg"
+ width="48.000000pt" height="48.000000pt" viewBox="0 0 48.000000 48.000000"
+ preserveAspectRatio="xMidYMid meet">
+
+<g transform="translate(0.000000,48.000000) scale(0.100000,-0.100000)"
+fill="#000000" stroke="none">
+<path d="M163 470 c-13 -5 -23 -12 -23 -15 0 -3 46 -5 102 -5 80 0 99 3 90 12
+-15 15 -139 21 -169 8z"/>
+<path d="M91 391 c-16 -16 -19 -32 -18 -84 1 -53 -2 -69 -18 -87 -15 -16 -20
+-38 -22 -83 0 -33 2 -56 5 -50 9 13 44 13 39 -1 -2 -6 -18 -11 -34 -11 -39 0
+-50 -10 -33 -30 8 -10 30 -15 60 -15 26 0 64 -7 83 -15 43 -18 125 -20 164 -3
+15 6 57 14 93 17 73 7 87 24 51 60 -12 12 -21 17 -21 13 0 -4 5 -13 12 -20 8
+-8 8 -12 1 -12 -18 0 -25 34 -9 45 10 7 12 16 6 25 -5 8 -7 24 -4 35 3 13 -2
+28 -15 39 -12 11 -21 27 -21 36 0 9 -5 21 -11 27 -8 8 -8 17 0 31 17 32 13 56
+-12 80 -31 29 -63 28 -91 -3 -16 -17 -34 -25 -56 -25 -22 0 -40 8 -56 25 -28
+30 -67 32 -93 6z m89 -16 c19 -23 5 -29 -24 -10 -16 10 -33 14 -47 10 -14 -5
+-19 -4 -15 4 10 16 72 13 86 -4z m211 -7 c12 -22 11 -22 -8 -5 -25 21 -41 22
+-65 0 -22 -19 -36 -10 -18 12 20 24 77 19 91 -7z m-264 -30 c-3 -7 -5 -2 -5
+12 0 14 2 19 5 13 2 -7 2 -19 0 -25z m229 -5 c-11 -11 -19 6 -11 24 8 17 8 17
+12 0 3 -10 2 -21 -1 -24z m-80 -8 c4 -8 10 -12 15 -9 5 3 9 0 9 -6 0 -14 60
+-40 77 -33 7 3 13 -2 13 -11 0 -13 -6 -15 -27 -9 -36 9 -210 9 -245 0 -22 -6
+-28 -4 -28 9 0 8 6 14 13 11 6 -2 25 2 40 10 15 8 32 11 37 8 6 -4 7 1 3 11
+-4 12 -3 15 5 10 7 -4 15 -1 18 8 8 21 63 21 70 1z m83 -91 c10 -9 -37 -33
+-77 -39 -55 -8 -117 2 -155 26 l-30 18 54 4 c56 4 201 -2 208 -9z m-286 -30
+c-15 -7 21 -44 42 -44 8 0 15 -4 15 -10 0 -16 -33 -11 -59 9 -25 19 -24 52 1
+50 9 0 10 -2 1 -5z m355 -21 c2 -14 -4 -23 -17 -28 -12 -3 -21 -13 -21 -21 0
+-19 -16 -18 -24 1 -5 15 -31 16 -53 2 -8 -5 -13 -4 -13 2 0 6 5 12 10 12 6 1
+15 3 20 4 6 1 18 3 28 4 25 1 66 37 52 44 -6 3 -5 4 2 3 7 -1 14 -12 16 -23z
+m-255 -37 c4 -10 1 -13 -9 -9 -7 3 -14 9 -14 14 0 14 17 10 23 -5z m42 -6 c3
+-5 1 -10 -4 -10 -6 0 -11 5 -11 10 0 6 2 10 4 10 3 0 8 -4 11 -10z m35 0 c0
+-5 -4 -10 -10 -10 -5 0 -10 5 -10 10 0 6 5 10 10 10 6 0 10 -4 10 -10z m-170
+-10 c0 -5 -5 -10 -11 -10 -5 0 -7 5 -4 10 3 6 8 10 11 10 2 0 4 -4 4 -10z
+m215 -39 c-6 -5 -25 10 -25 20 0 5 6 4 14 -3 8 -7 12 -15 11 -17z m45 8 c0
+-14 -16 -11 -29 5 -10 12 -8 13 8 9 12 -3 21 -9 21 -14z m-220 1 c0 -5 -5 -10
+-11 -10 -5 0 -7 5 -4 10 3 6 8 10 11 10 2 0 4 -4 4 -10z m40 0 c0 -5 -4 -10
+-10 -10 -5 0 -10 5 -10 10 0 6 5 10 10 10 6 0 10 -4 10 -10z m215 0 c3 -5 2
+-10 -4 -10 -5 0 -13 5 -16 10 -3 6 -2 10 4 10 5 0 13 -4 16 -10z m43 -10 c7
+-11 10 -20 6 -20 -7 0 -34 27 -34 34 0 13 16 5 28 -14z m-160 -17 c-10 -2 -26
+-2 -35 0 -10 3 -2 5 17 5 19 0 27 -2 18 -5z m99 1 c-3 -3 -12 -4 -19 -1 -8 3
+-5 6 6 6 11 1 17 -2 13 -5z m40 0 c-3 -3 -12 -4 -19 -1 -8 3 -5 6 6 6 11 1 17
+-2 13 -5z"/>
+</g>
+</svg>

src/assets/safari-pinned-tab.svg

@@ -0,0 +1,15 @@
+<?xml version="1.0" standalone="no"?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 20010904//EN"
+ "http://www.w3.org/TR/2001/REC-SVG-20010904/DTD/svg10.dtd">
+<svg version="1.0" xmlns="http://www.w3.org/2000/svg"
+ width="850.000000pt" height="850.000000pt" viewBox="0 0 850.000000 850.000000"
+ preserveAspectRatio="xMidYMid meet">
+<metadata>
+Created by potrace 1.14, written by Peter Selinger 2001-2017
+</metadata>
+<g transform="translate(0.000000,850.000000) scale(0.100000,-0.100000)"
+fill="#000000" stroke="none">
+<path d="M0 4250 l0 -3770 4250 0 4250 0 0 3770 0 3770 -4250 0 -4250 0 0
+-3770z"/>
+</g>
+</svg>

src/classes/AbstractEvents.ts

@@ -7,6 +7,9 @@ import {
   safeScale,
 } from "zifferjs";
 import { SkipEvent } from "./SkipEvent";
+import { SoundParams } from "./SoundEvent";
+import { centsToSemitones, edoToSemitones, ratiosToSemitones } from "zifferjs/src/scale";
+import { safeMod } from "zifferjs/src/utils";
 
 export type EventOperation<T> = (instance: T, ...args: any[]) => void;
 
@@ -208,9 +211,14 @@ export class AbstractEvent {
      * @param func - The function to be applied to the Event
      * @returns The transformed Event
      */
-    return this.modify(func);
+    return this.modify(func).update();
   };
 
+  mod = (value: number): AbstractEvent => {
+    this.values.originalPitch = safeMod(this.values.originalPitch, value);
+    return this.update();
+  }
+
   noteLength = (
     value: number | number[],
     ...kwargs: number[]
@@ -222,18 +230,60 @@ export class AbstractEvent {
       value = Array.isArray(value) ? value.concat(kwargs) : [value, ...kwargs];
     }
     if (Array.isArray(value)) {
-      this.values["noteLength"] = value;
       this.values.dur = value.map((v) =>
         this.app.clock.convertPulseToSecond(v * 4 * this.app.clock.ppqn),
       );
     } else {
-      this.values["noteLength"] = value;
       this.values.dur = this.app.clock.convertPulseToSecond(
         value * 4 * this.app.clock.ppqn,
       );
     }
+    if(this.current) {
+      value = Array.isArray(value) ? value[this.index%value.length] : value;
+      this.current.duration = value;
+    }
     return this;
   };
+
+  protected processSound = (
+    sound: string | string[] | SoundParams | SoundParams[],
+  ): SoundParams => {
+    if (Array.isArray(sound) && typeof sound[0] === "string") {
+      const s: string[] = [];
+      const n: number[] = [];
+      sound.forEach((str) => {
+        const parts = (str as string).split(":");
+        s.push(parts[0]);
+        if (parts[1]) {
+          n.push(parseInt(parts[1]));
+        }
+      });
+      return {
+        s,
+        n: n.length > 0 ? n : undefined,
+        dur: this.app.clock.convertPulseToSecond(this.app.clock.ppqn),
+      };
+    } else if (typeof sound === "object") {
+      const validatedObj: SoundParams = {
+        dur: this.app.clock.convertPulseToSecond(this.app.clock.ppqn),
+        ...(sound as Partial<SoundParams>),
+      };
+      return validatedObj;
+    } else {
+      if (sound.includes(":")) {
+        const vals = sound.split(":");
+        const s = vals[0];
+        const n = parseInt(vals[1]);
+        return {
+          s,
+          n,
+          dur: this.app.clock.convertPulseToSecond(this.app.clock.ppqn),
+        };
+      } else {
+        return { s: sound, dur: 0.5 };
+      }
+    }
+  };
 }
 
 export abstract class AudibleEvent extends AbstractEvent {
@@ -251,8 +301,9 @@ export abstract class AudibleEvent extends AbstractEvent {
       value = Array.isArray(value) ? value.concat(kwargs) : [value, ...kwargs];
     }
     this.values["pitch"] = value;
-    if (this.values.key && this.values.parsedScale) this.update();
-    return this;
+    this.values["originalPitch"] = value;
+    this.defaultPitchKeyScale();
+    return this.update();
   };
 
   pc = this.pitch;
@@ -266,13 +317,15 @@ export abstract class AudibleEvent extends AbstractEvent {
     if (kwargs.length > 0) {
       value = Array.isArray(value) ? value.concat(kwargs) : [value, ...kwargs];
     }
-    this.values["octave"] = value;
+    this.values["paramOctave"] = value;
     if (
       this.values.key &&
       (this.values.pitch || this.values.pitch === 0) &&
       this.values.parsedScale
-    )
-      this.update();
+    ) {
+      return this.update();
+    }
+
     return this;
   };
 
@@ -289,11 +342,19 @@ export abstract class AudibleEvent extends AbstractEvent {
     if (
       (this.values.pitch || this.values.pitch === 0) &&
       this.values.parsedScale
-    )
-      this.update();
+    ) {
+      return this.update();
+    }
+
     return this;
   };
 
+  defaultPitchKeyScale() {
+    if (!this.values.key) this.values.key = 60;
+    if (!(this.values.pitch || this.values.pitch === 0)) this.values.pitch = 0;
+    if (!this.values.parsedScale) this.values.parsedScale = safeScale("major");
+  }
+
   scale = (
     value: string | number | (number | string)[],
     ...kwargs: (string | number)[]
@@ -311,12 +372,38 @@ export abstract class AudibleEvent extends AbstractEvent {
     } else if (Array.isArray(value)) {
       this.values.parsedScale = value.map((v) => safeScale(v));
     }
-    if (this.values.key && (this.values.pitch || this.values.pitch === 0)) {
-      this.update();
-    }
-    return this;
+    this.defaultPitchKeyScale();
+    return this.update();
   };
 
+  semitones(values: number|number[], ...rest: number[]) {
+    const scaleValues = typeof values === "number" ? [values, ...rest] : values;
+    this.values.parsedScale = safeScale(scaleValues);
+    this.defaultPitchKeyScale();
+    return this.update();
+  }
+  steps = this.semitones;
+
+  cents(values: number|number[], ...rest: number[]) {
+    const scaleValues = typeof values === "number" ? [values, ...rest] : values;
+    this.values.parsedScale = safeScale(centsToSemitones(scaleValues));
+    this.defaultPitchKeyScale();
+    return this.update();
+  }
+
+  ratios(values: number|number[], ...rest: number[]) {
+    const scaleValues = typeof values === "number" ? [values, ...rest] : values;
+    this.values.parsedScale = safeScale(ratiosToSemitones(scaleValues));
+    this.defaultPitchKeyScale();
+    return this.update();
+  }
+
+  edo(value: number, intervals: string|number[] = new Array(value).fill(1)) {
+    this.values.parsedScale = edoToSemitones(value, intervals);
+    this.defaultPitchKeyScale();
+    return this.update();
+  } 
+
   protected updateValue<T>(key: string, value: T | T[] | null): this {
     if (value == null) return this;
     this.values[key] = value;
@@ -348,6 +435,7 @@ export abstract class AudibleEvent extends AbstractEvent {
   };
 
   public invert = (howMany: number = 0) => {
+    if(howMany === 0) return this;
     if (this.values.note) {
       let notes = [...this.values.note];
       notes = howMany < 0 ? [...notes].reverse() : notes;
@@ -360,6 +448,35 @@ export abstract class AudibleEvent extends AbstractEvent {
     }
   };
 
+  public log = (key: string|string[], ...args: string[]) => {
+    /*
+     * Log values from values using log()
+     *
+     * @param key - The key(s) to log
+     * @returns this and logs the values
+     */
+    if (typeof key === "string") {
+      if(args && args.length > 0) {
+        this.app.api.log([key, ...args].map((k) => this.values[k]));
+      } else {
+         this.app.api.log(this.values[key]);
+      }
+    } else {
+      this.app.api.log([...key, ...args].map((k) => this.values[k]));
+    }
+    return this;
+  }
+
+  public draw = (lambda: Function) => {
+    lambda(this.values, (this.app.interface.drawings as HTMLCanvasElement).getContext("2d"));
+    return this;
+  }
+
+  public clear = () => {
+    this.app.api.clear();
+    return this;
+  }
+
   freq = (value: number | number[], ...kwargs: number[]): this => {
     /*
      * This function is used to set the frequency of the Event.
@@ -395,7 +512,22 @@ export abstract class AudibleEvent extends AbstractEvent {
     return this;
   };
 
-  update = (): void => {
+  update = (): this => {
     // Overwrite in subclasses
+    return this;
   };
+
+  cue = (functionName: string|Function): this => {
+    this.app.api.cue(functionName);
+    return this;
+  }
+
+  runChain = (): this => {
+    // chainAll is defined using all() in the API
+    if("chainAll" in this && typeof this.chainAll === "function") {
+      this.values = this.chainAll().values;
+    }
+    return this;
+  }
+
 }

src/classes/MidiEvent.ts

@@ -1,11 +1,12 @@
 import { AudibleEvent } from "./AbstractEvents";
 import { type Editor } from "../main";
 import { MidiConnection } from "../IO/MidiConnection";
-import { noteFromPc } from "zifferjs";
+import { resolvePitchClass } from "zifferjs";
 import {
   filterObject,
   arrayOfObjectsToObjectWithArrays,
   objectWithArraysToArrayOfObjects,
+  maybeAtomic,
 } from "../Utils/Generic";
 
 export type MidiParams = {
@@ -66,8 +67,7 @@ export class MidiEvent extends AudibleEvent {
       return funcResult;
     } else {
       func(this.values);
-      this.update();
-      return this;
+      return this.update();
     }
   };
 
@@ -83,37 +83,39 @@ export class MidiEvent extends AudibleEvent {
     return this;
   };
 
-  update = (): void => {
-    // Get key, pitch, parsedScale and octave from this.values object
+  update = (): this => {
     const filteredValues = filterObject(this.values, [
       "key",
       "pitch",
+      "originalPitch",
       "parsedScale",
-      "octave",
+      "addedOctave"
     ]);
 
     const events = objectWithArraysToArrayOfObjects(filteredValues, [
       "parsedScale",
     ]);
 
-    events.forEach((event) => {
-      const [note, bend] = noteFromPc(
-        (event.key as number) || "C4",
-        (event.pitch as number) || 0,
-        (event.parsedScale as number[]) || event.scale || "MAJOR",
-        (event.octave as number) || 0,
+    events.forEach((soundEvent) => {
+      const resolvedPitchClass = resolvePitchClass(
+        (soundEvent.key || "C4"),
+        (soundEvent.originalPitch || soundEvent.pitch || 0),
+        (soundEvent.parsedScale || soundEvent.scale || "MAJOR"),
+        (soundEvent.addedOctave || 0)
       );
-      event.note = note;
-      if (bend) event.bend = bend;
+      soundEvent.note = resolvedPitchClass.note;
+      soundEvent.pitch = resolvedPitchClass.pitch;
+      soundEvent.octave = resolvedPitchClass.octave;
     });
 
     const newArrays = arrayOfObjectsToObjectWithArrays(events) as MidiParams;
-
-    this.values.note = newArrays.note;
-    if (newArrays.bend) this.values.bend = newArrays.bend;
+    
+    this.values.note = maybeAtomic(newArrays.note);
+    if (newArrays.bend) this.values.bend = maybeAtomic(newArrays.bend);
+    return this;
   };
 
-  out = (): void => {
+  out = (outChannel?: number|number[]): void => {
     function play(event: MidiEvent, params: MidiParams): void {
       const channel = params.channel ? params.channel : 0;
       const velocity = params.velocity ? params.velocity : 100;
@@ -139,6 +141,9 @@ export class MidiEvent extends AudibleEvent {
       );
     }
 
+    this.runChain();
+    if(outChannel) this.channel(outChannel);
+
     const events = objectWithArraysToArrayOfObjects(this.values, [
       "parsedScale",
     ]) as MidiParams[];

src/classes/SoundEvent.ts

@@ -1,11 +1,13 @@
 import { type Editor } from "../main";
 import { AudibleEvent } from "./AbstractEvents";
+import { sendToServer, type OSCMessage } from "../IO/OSC";
 import {
   filterObject,
   arrayOfObjectsToObjectWithArrays,
   objectWithArraysToArrayOfObjects,
+  maybeAtomic,
 } from "../Utils/Generic";
-import { midiToFreq, noteFromPc } from "zifferjs";
+import { midiToFreq, resolvePitchClass } from "zifferjs";
 
 import {
   superdough,
@@ -21,10 +23,13 @@ export type SoundParams = {
   note?: number | number[];
   freq?: number | number[];
   pitch?: number | number[];
+  originalPitch?: number | number[];
   key?: string;
   scale?: string;
   parsedScale?: number[];
   octave?: number | number[];
+  addedOctave?: number | number[];
+  pitchOctave?: number | number[];
 };
 
 export class SoundEvent extends AudibleEvent {
@@ -36,12 +41,28 @@ export class SoundEvent extends AudibleEvent {
     zrand: ["zrand", "zr"],
     curve: ["curve"],
     bank: ["bank"],
+    drumMachine: function(self: SoundEvent, a: number) {
+      let machines = ["AJKPercusyn", "AkaiLinn", "AkaiMPC60", "AkaiXR10", "AlesisHR16", "AlesisSR16", "BossDR110", "BossDR220", "BossDR55",
+        "BossDR550", "BossDR660", "CasioRZ1", "CasioSK1", "CasioVL1", "DoepferMS404", "EmuDrumulator", "EmuModular", "EmuSP12",
+        "KorgDDM110", "KorgKPR77", "KorgKR55", "KorgKRZ", "KorgM1", "KorgMinipops", "KorgPoly800", "KorgT3", "Linn9000",
+        "LinnDrum", "LinnLM1", "LinnLM2", "MFB512", "MPC1000", "MoogConcertMateMG1", "OberheimDMX", "RhodesPolaris",
+        "RhythmAce", "RolandCompurhythm1000", "RolandCompurhythm78", "RolandCompurhythm8000", "RolandD110", "RolandD70", "RolandDDR30",
+        "RolandJD990", "RolandMC202", "RolandMC303", "RolandMT32", "RolandR8", "RolandS50", "RolandSH09", "RolandSystem100", "RolandTR505",
+        "RolandTR606", "RolandTR626", "RolandTR707", "RolandTR727", "RolandTR808", "RolandTR909", "SakataDPM48", "SequentialCircuitsDrumtracks",
+        "SequentialCircuitsTom", "SergeModular", "SimmonsSDS400", "SimmonsSDS5", "SoundmastersR88", "UnivoxMicroRhythmer12", "ViscoSpaceDrum",
+        "XdrumLM8953", "YamahaRM50", "YamahaRX21", "YamahaRX5", "YamahaRY30", "YamahaTG33"];
+      self.updateValue("bank", machines[a % machines.length]);
+      return self;
+    },
     slide: ["slide", "sld"],
     deltaSlide: ["deltaSlide", "dslide"],
     pitchJump: ["pitchJump", "pj"],
     pitchJumpTime: ["pitchJumpTime", "pjt"],
     lfo: ["lfo"],
     znoise: ["znoise"],
+    address: ["address", "add"],
+    port: ["port"],
+    density: ["density"],
     noise: ["noise"],
     zmod: ["zmod"],
     zcrush: ["zcrush"],
@@ -63,7 +84,7 @@ export class SoundEvent extends AudibleEvent {
     phaserDepth: ["phaserDepth", "phasdepth"],
     phaserSweep: ["phaserSweep", "phassweep"],
     phaserCenter: ["phaserCenter", "phascenter"],
-    fmadsr: function (
+    fmadsr: function(
       self: SoundEvent,
       a: number,
       d: number,
@@ -76,7 +97,7 @@ export class SoundEvent extends AudibleEvent {
       self.updateValue("fmrelease", r);
       return self;
     },
-    fmad: function (self: SoundEvent, a: number, d: number) {
+    fmad: function(self: SoundEvent, a: number, d: number) {
       self.updateValue("fmattack", a);
       self.updateValue("fmdecay", d);
       return self;
@@ -87,7 +108,7 @@ export class SoundEvent extends AudibleEvent {
     decay: ["decay", "dec"],
     sustain: ["sustain", "sus"],
     release: ["release", "rel"],
-    adsr: function (
+    adsr: function(
       self: SoundEvent,
       a: number,
       d: number,
@@ -100,18 +121,18 @@ export class SoundEvent extends AudibleEvent {
       self.updateValue("release", r);
       return self;
     },
-    ad: function (self: SoundEvent, a: number, d: number) {
+    ad: function(self: SoundEvent, a: number, d: number) {
       self.updateValue("attack", a);
       self.updateValue("decay", d);
       self.updateValue("sustain", 0.0);
       self.updateValue("release", 0.0);
       return self;
     },
-    scope: function (self: SoundEvent) {
+    scope: function(self: SoundEvent) {
       self.updateValue("analyze", true);
       return self;
     },
-    debug: function (self: SoundEvent, callback?: Function) {
+    debug: function(self: SoundEvent, callback?: Function) {
       self.updateValue("debug", true);
       if (callback) {
         self.updateValue("debugFunction", callback);
@@ -123,27 +144,33 @@ export class SoundEvent extends AudibleEvent {
     lpdecay: ["lpdecay", "lpd"],
     lpsustain: ["lpsustain", "lps"],
     lprelease: ["lprelease", "lpr"],
-    cutoff: function (self: SoundEvent, value: number, resonance?: number) {
+    cutoff: function(self: SoundEvent, value: number, resonance?: number) {
       self.updateValue("cutoff", value);
       if (resonance) {
         self.updateValue("resonance", resonance);
       }
       return self;
     },
-    lpf: function (self: SoundEvent, value: number, resonance?: number) {
+    lpf: function(self: SoundEvent, value: number, resonance?: number) {
       self.updateValue("cutoff", value);
       if (resonance) {
         self.updateValue("resonance", resonance);
       }
       return self;
     },
-    resonance: function (self: SoundEvent, value: number) {
+    resonance: function(self: SoundEvent, value: number) {
       if (value >= 0 && value <= 1) {
         self.updateValue("resonance", 50 * value);
       }
       return self;
     },
-    lpadsr: function (
+    lpq: function(self: SoundEvent, value: number) {
+      if (value >= 0 && value <= 1) {
+        self.updateValue("resonance", 50 * value);
+      }
+      return self;
+    },
+    lpadsr: function(
       self: SoundEvent,
       depth: number,
       a: number,
@@ -158,7 +185,7 @@ export class SoundEvent extends AudibleEvent {
       self.updateValue("lprelease", r);
       return self;
     },
-    lpad: function (self: SoundEvent, depth: number, a: number, d: number) {
+    lpad: function(self: SoundEvent, depth: number, a: number, d: number) {
       self.updateValue("lpenv", depth);
       self.updateValue("lpattack", a);
       self.updateValue("lpdecay", d);
@@ -171,25 +198,25 @@ export class SoundEvent extends AudibleEvent {
     hpdecay: ["hpdecay", "hpd"],
     hpsustain: ["hpsustain", "hpsus"],
     hprelease: ["hprelease", "hpr"],
-    hcutoff: function (self: SoundEvent, value: number, resonance?: number) {
+    hcutoff: function(self: SoundEvent, value: number, resonance?: number) {
       self.updateValue("hcutoff", value);
       if (resonance) {
         self.updateValue("hresonance", resonance);
       }
       return self;
     },
-    hpf: function (self: SoundEvent, value: number, resonance?: number) {
+    hpf: function(self: SoundEvent, value: number, resonance?: number) {
       self.updateValue("hcutoff", value);
       if (resonance) {
-        self.updateValue("hresonance", resonance);
+        self.updateValue("hresonance", resonance * 50);
       }
       return self;
     },
-    hpq: function (self: SoundEvent, value: number) {
-      self.updateValue("hresonance", value);
+    hpq: function(self: SoundEvent, value: number) {
+      self.updateValue("hresonance", value * 50);
       return self;
     },
-    hpadsr: function (
+    hpadsr: function(
       self: SoundEvent,
       depth: number,
       a: number,
@@ -204,7 +231,7 @@ export class SoundEvent extends AudibleEvent {
       self.updateValue("hprelease", r);
       return self;
     },
-    hpad: function (self: SoundEvent, depth: number, a: number, d: number) {
+    hpad: function(self: SoundEvent, depth: number, a: number, d: number) {
       self.updateValue("hpenv", depth);
       self.updateValue("hpattack", a);
       self.updateValue("hpdecay", d);
@@ -217,22 +244,25 @@ export class SoundEvent extends AudibleEvent {
     bpdecay: ["bpdecay", "bpd"],
     bpsustain: ["bpsustain", "bps"],
     bprelease: ["bprelease", "bpr"],
-    bandf: function (self: SoundEvent, value: number, resonance?: number) {
+    bandf: function(self: SoundEvent, value: number, resonance?: number) {
       self.updateValue("bandf", value);
       if (resonance) {
         self.updateValue("bandq", resonance);
       }
       return self;
     },
-    bpf: function (self: SoundEvent, value: number, resonance?: number) {
+    bpf: function(self: SoundEvent, value: number, resonance?: number) {
       self.updateValue("bandf", value);
       if (resonance) {
-        self.updateValue("bandq", resonance);
+        self.updateValue("bandq", resonance * 50);
       }
       return self;
     },
-    bandq: ["bandq", "bpq"],
-    bpadsr: function (
+    bpq: function(self: SoundEvent, value: number) {
+      self.updateValue("bandq", value * 50);
+      return self;
+    },
+    bpadsr: function(
       self: SoundEvent,
       depth: number,
       a: number,
@@ -247,7 +277,7 @@ export class SoundEvent extends AudibleEvent {
       self.updateValue("bprelease", r);
       return self;
     },
-    bpad: function (self: SoundEvent, depth: number, a: number, d: number) {
+    bpad: function(self: SoundEvent, depth: number, a: number, d: number) {
       self.updateValue("bpenv", depth);
       self.updateValue("bpattack", a);
       self.updateValue("bpdecay", d);
@@ -257,7 +287,7 @@ export class SoundEvent extends AudibleEvent {
     },
     vib: ["vib"],
     vibmod: ["vibmod"],
-    fm: function (self: SoundEvent, value: number | string) {
+    fm: function(self: SoundEvent, value: number | string) {
       if (typeof value === "number") {
         self.values["fmi"] = value;
       } else {
@@ -273,11 +303,11 @@ export class SoundEvent extends AudibleEvent {
     begin: ["begin"],
     end: ["end"],
     gain: ["gain"],
-    dbgain: function (self: SoundEvent, value: number) {
+    dbgain: function(self: SoundEvent, value: number) {
       self.updateValue("gain", Math.min(Math.pow(10, value / 20), 10));
       return self;
     },
-    db: function (self: SoundEvent, value: number) {
+    db: function(self: SoundEvent, value: number) {
       self.updateValue("gain", Math.min(Math.pow(10, value / 20), 10));
       return self;
     },
@@ -300,32 +330,32 @@ export class SoundEvent extends AudibleEvent {
     roomlp: ["roomlp", "rlp"],
     roomdim: ["roomdim", "rdim"],
     sound: ["s", "sound"],
-    size: function (self: SoundEvent, value: number) {
+    size: function(self: SoundEvent, value: number) {
       self.updateValue("roomsize", value);
       return self;
     },
-    sz: function (self: SoundEvent, value: number) {
+    sz: function(self: SoundEvent, value: number) {
       self.updateValue("roomsize", value);
       return self;
     },
-    comp: ["compressor", "cmp"],
-    ratio: function (self: SoundEvent, value: number) {
+    comp: ["comp", "compressor", "cmp"],
+    ratio: function(self: SoundEvent, value: number) {
       self.updateValue("compressorRatio", value);
       return self;
     },
-    knee: function (self: SoundEvent, value: number) {
+    knee: function(self: SoundEvent, value: number) {
       self.updateValue("compressorKnee", value);
       return self;
     },
-    compAttack: function (self: SoundEvent, value: number) {
+    compAttack: function(self: SoundEvent, value: number) {
       self.updateValue("compressorAttack", value);
       return self;
     },
-    compRelease: function (self: SoundEvent, value: number) {
+    compRelease: function(self: SoundEvent, value: number) {
       self.updateValue("compressorRelease", value);
       return self;
     },
-    stretch: function (self: SoundEvent, beat: number) {
+    stretch: function(self: SoundEvent, beat: number) {
       self.updateValue("unit", "c");
       self.updateValue("speed", 1 / beat);
       self.updateValue("cut", beat);
@@ -366,46 +396,6 @@ export class SoundEvent extends AudibleEvent {
     this.values = this.processSound(sound);
   }
 
-  private processSound = (
-    sound: string | string[] | SoundParams | SoundParams[],
-  ): SoundParams => {
-    if (Array.isArray(sound) && typeof sound[0] === "string") {
-      const s: string[] = [];
-      const n: number[] = [];
-      sound.forEach((str) => {
-        const parts = (str as string).split(":");
-        s.push(parts[0]);
-        if (parts[1]) {
-          n.push(parseInt(parts[1]));
-        }
-      });
-      return {
-        s,
-        n: n.length > 0 ? n : undefined,
-        dur: this.app.clock.convertPulseToSecond(this.app.clock.ppqn),
-      };
-    } else if (typeof sound === "object") {
-      const validatedObj: SoundParams = {
-        dur: this.app.clock.convertPulseToSecond(this.app.clock.ppqn),
-        ...(sound as Partial<SoundParams>),
-      };
-      return validatedObj;
-    } else {
-      if (sound.includes(":")) {
-        const vals = sound.split(":");
-        const s = vals[0];
-        const n = parseInt(vals[1]);
-        return {
-          s,
-          n,
-          dur: this.app.clock.convertPulseToSecond(this.app.clock.ppqn),
-        };
-      } else {
-        return { s: sound, dur: 0.5 };
-      }
-    }
-  };
-
   // ================================================================================
   // AbstactEvent overrides
   // ================================================================================
@@ -415,39 +405,48 @@ export class SoundEvent extends AudibleEvent {
     if (funcResult instanceof Object) return funcResult;
     else {
       func(this.values);
-      this.update();
-      return this;
+      return this.update();
     }
   };
 
-  update = (): void => {
+  update = (): this => {
     const filteredValues = filterObject(this.values, [
       "key",
       "pitch",
+      "originalPitch",
       "parsedScale",
+      "addedOctave",
       "octave",
+      "paramOctave"
     ]);
     const events = objectWithArraysToArrayOfObjects(filteredValues, [
       "parsedScale",
     ]);
-    events.forEach((event) => {
-      const [note, _] = noteFromPc(
-        (event.key as number) || "C4",
-        (event.pitch as number) || 0,
-        (event.parsedScale as number[]) || event.scale || "MAJOR",
-        (event.octave as number) || 0,
+    events.forEach((soundEvent) => {
+      const resolvedPitchClass = resolvePitchClass(
+        (soundEvent.key || "C4"),
+        (soundEvent.originalPitch || soundEvent.pitch || 0),
+        (soundEvent.parsedScale || soundEvent.scale || "MAJOR"),
+        (soundEvent.paramOctave || 0) + (soundEvent.addedOctave || 0)
       );
-      event.note = note;
-      event.freq = midiToFreq(note);
+      soundEvent.note = resolvedPitchClass.note;
+      soundEvent.freq = midiToFreq(resolvedPitchClass.note);
+      soundEvent.pitch = resolvedPitchClass.pitch;
+      soundEvent.octave = resolvedPitchClass.octave;
     });
 
     const newArrays = arrayOfObjectsToObjectWithArrays(events) as SoundParams;
 
-    this.values.note = newArrays.note;
-    this.values.freq = newArrays.freq;
+    this.values.note = maybeAtomic(newArrays.note);
+    this.values.freq = maybeAtomic(newArrays.freq);
+    this.values.pitch = maybeAtomic(newArrays.pitch);
+    this.values.octave = maybeAtomic(newArrays.octave);
+    this.values.pitchOctave = maybeAtomic(newArrays.pitchOctave);
+    return this;
   };
 
   out = (orbit?: number | number[]): void => {
+    this.runChain();
     if (orbit) this.values["orbit"] = orbit;
     const events = objectWithArraysToArrayOfObjects(this.values, [
       "parsedScale",
@@ -462,14 +461,36 @@ export class SoundEvent extends AudibleEvent {
       if (filteredEvent.freq) {
         delete filteredEvent.note;
       }
-      if (this.values["debug"]) {
-        if (this.values["debugFunction"]) {
-          this.values["debugFunction"](filteredEvent);
-        } else {
-          console.log(filteredEvent);
-        }
+      superdough(
+        filteredEvent,
+        this.nudge - this.app.clock.deviation,
+        filteredEvent.dur
+      );
+    }
+  };
+
+  osc = (orbit?: number | number[]): void => {
+    if (orbit) this.values["orbit"] = orbit;
+    const events = objectWithArraysToArrayOfObjects(this.values, [
+      "parsedScale",
+    ]);
+    for (const event of events) {
+      const filteredEvent = event;
+
+      let oscAddress = "address" in event ? event.address : "/topos";
+      oscAddress = oscAddress?.startsWith("/") ? oscAddress : "/" + oscAddress;
+
+      let oscPort = "port" in event ? event.port : 57120;
+
+      if (filteredEvent.freq) {
+        delete filteredEvent.note;
       }
-      superdough(filteredEvent, this.app.clock.deadline, filteredEvent.dur);
+      sendToServer({
+        address: oscAddress,
+        port: oscPort,
+        args: event,
+        timetag: Math.round(Date.now() + (this.nudge - this.app.clock.deviation)),
+      } as OSCMessage);
     }
   };
 }

src/classes/ZPlayer.ts

@@ -5,8 +5,9 @@ import { SkipEvent } from "./SkipEvent";
 import { SoundEvent, SoundParams } from "./SoundEvent";
 import { MidiEvent, MidiParams } from "./MidiEvent";
 import { RestEvent } from "./RestEvent";
-import { arrayOfObjectsToObjectWithArrays } from "../Utils/Generic";
+import { arrayOfObjectsToObjectWithArrays, isGenerator } from "../Utils/Generic";
 import { TonnetzSpaces } from "zifferjs/src/tonnetz";
+import { safeMod } from "zifferjs/src/utils";
 
 export type InputOptions = { [key: string]: string | number };
 
@@ -17,6 +18,7 @@ export class Player extends AbstractEvent {
   startCallTime: number = 0;
   lastCallTime: number = 0;
   waitTime = 0;
+  cueName: string|undefined = undefined;
   played: boolean = false;
   current!: Pitch | Chord | ZRest;
   retro: boolean = false;
@@ -30,6 +32,7 @@ export class Player extends AbstractEvent {
     options: InputOptions,
     public app: Editor,
     zid: string = "",
+    waitTime: number = 0,
   ) {
     super(app);
     this.options = options;
@@ -39,13 +42,34 @@ export class Player extends AbstractEvent {
     } else if (typeof input === "number") {
       this.input = input;
       this.ziffers = Ziffers.fromNumber(input, options);
-    } else {
+    } else if (isGenerator(input)) {
       this.ziffers = Ziffers.fromGenerator(input, options);
       this.input = this.ziffers.input;
+    } else {
+      throw new Error("Invalid input");
     }
+    if(waitTime) this.waitTime = waitTime;
     this.zid = zid;
   }
 
+  updatePattern(input: string, options: InputOptions): boolean {
+    const oldIndex = this.ziffers.index;
+    const newPattern = new Ziffers(input, options);
+    if(newPattern.values.length > 0) {
+      this.ziffers = newPattern;
+      this.ziffers.update();
+      this.ziffers.index = oldIndex;
+      this.input = input;
+      this.options = options;
+      return true;
+    }
+    return false;
+  }
+
+  isValid() {
+    return this.ziffers.values.length > 0;
+  }
+
   reset() {
     this.initCallTime = 0;
     this.startCallTime = 0;
@@ -125,11 +149,13 @@ export class Player extends AbstractEvent {
 
     const patternIsStarting =
       this.notStarted() &&
-      (this.pulse() === 0 || this.origin() >= this.nextBeatInTicks()) &&
-      this.origin() >= this.waitTime;
+      this.waitTime >= 0 &&
+      this.origin() >= this.waitTime &&
+      (this.pulse() === 0 || this.origin() >= this.nextBeatInTicks());
 
     const timeToPlayNext =
       this.current &&
+      this.waitTime >= 0 &&
       this.pulseToSecond(this.origin()) >=
         this.pulseToSecond(this.lastCallTime) +
           this.pulseToSecond(this.current.duration * 4 * this.app.clock.ppqn) &&
@@ -155,40 +181,64 @@ export class Player extends AbstractEvent {
     return areWeThereYet;
   };
 
-  sound(name?: string) {
+  checkCue() {
+    if(this.ziffers.atLast()) {
+      if(this.cueName && this.app.api.cueTimes[this.cueName]) {
+        delete this.app.api.cueTimes[this.cueName];
+        this.cueName = undefined;
+        this.waitTime = -1;
+      }
+    }
+  }
+
+  sound(name?: string | string[] | SoundParams | SoundParams[]) {
     if (this.areWeThereYet()) {
+      this.checkCue();
       const event = this.next() as Pitch | Chord | ZRest;
       const noteLengthInSeconds = this.app.clock.convertPulseToSecond(
         event.duration * 4 * this.app.clock.ppqn,
       );
       if (event instanceof Pitch) {
-        const obj = event.getExisting(
+        let obj = event.getExisting(
           "freq",
           "note",
           "pitch",
+          "originalPitch",
           "key",
           "scale",
           "octave",
+          "pitchOctave",
+          "addedOctave",
           "parsedScale",
         ) as SoundParams;
+        
         if (event.sound) name = event.sound as string;
+        if(name) obj = {...obj, ...this.processSound(name)};
+        else obj.s = "sine";
+
         if (event.soundIndex) obj.n = event.soundIndex as number;
         obj.dur = noteLengthInSeconds;
-        return new SoundEvent(obj, this.app).sound(name || "sine");
+        return new SoundEvent(obj, this.app);
       } else if (event instanceof Chord) {
         const pitches = event.pitches.map((p) => {
           return p.getExisting(
             "freq",
             "note",
             "pitch",
+            "originalPitch",
             "key",
             "scale",
             "octave",
+            "pitchOctave",
+            "addedOctave",
             "parsedScale",
           );
         }) as SoundParams[];
-        const add = { dur: noteLengthInSeconds } as SoundParams;
-        if (name) add.s = name;
+
+        let add = { dur: noteLengthInSeconds} as SoundParams;
+        if(name) add = {...add, ...this.processSound(name)};
+        else add.s = "sine";
+
         let sound = arrayOfObjectsToObjectWithArrays(
           pitches,
           add,
@@ -204,14 +254,18 @@ export class Player extends AbstractEvent {
 
   midi(value: number | undefined = undefined) {
     if (this.areWeThereYet()) {
+      this.checkCue();
       const event = this.next() as Pitch | Chord | ZRest;
       const obj = event.getExisting(
         "note",
         "pitch",
+        "originalPitch",
         "bend",
         "key",
         "scale",
         "octave",
+        "pitchOctave",
+        "addedOctave",
         "parsedScale",
       ) as MidiParams;
       if (event instanceof Pitch) {
@@ -230,11 +284,34 @@ export class Player extends AbstractEvent {
     }
   }
 
-  scale(name: string) {
+  scale(name: string|number[]) {
     if (this.atTheBeginning()) this.ziffers.scale(name);
     return this;
   }
 
+  semitones(values: number|number[], ...rest: number[]) {
+    values = typeof values === "number" ? [values, ...rest] : values;
+    if (this.atTheBeginning()) this.ziffers.semitones(values);
+    return this;
+  }
+
+  cents(values: number|number[], ...rest: number[]) {
+    values = typeof values === "number" ? [values, ...rest] : values;
+    if (this.atTheBeginning()) this.ziffers.cents(values);
+    return this;
+  }
+
+  ratios(values: number|number[], ...rest: number[]) {
+    values = typeof values === "number" ? [values, ...rest] : values;
+    if (this.atTheBeginning()) this.ziffers.ratios(values);
+    return this;
+  }
+
+  edo(value: number, scale: string|number[] = new Array(value).fill(1)) {
+    if (this.atTheBeginning()) this.ziffers.edo(value, scale);
+    return this;
+  }
+
   key(name: string) {
     if (this.atTheBeginning()) this.ziffers.key(name);
     return this;
@@ -261,18 +338,92 @@ export class Player extends AbstractEvent {
     return this;
   }
 
-  octaCycle(tonnetz: TonnetzSpaces = [3, 4, 5]) {
-    if (this.atTheBeginning()) this.ziffers.octaCycle(tonnetz);
+  octaCycle(tonnetz: TonnetzSpaces = [3, 4, 5], repeats: number = 4, components: number = 1) {
+    if (this.atTheBeginning()) this.ziffers.octaCycle(tonnetz, repeats, components);
     return this;
   }
 
-  hexaCycle(tonnetz: TonnetzSpaces = [3, 4, 5]) {
-    if (this.atTheBeginning()) this.ziffers.hexaCycle(tonnetz);
+  hexaCycle(tonnetz: TonnetzSpaces = [3, 4, 5], repeats: number = 3, components: number = 1) {
+    if (this.atTheBeginning()) this.ziffers.hexaCycle(tonnetz, repeats, components);
     return this;
   }
 
-  enneaCycle(tonnetz: TonnetzSpaces = [3, 4, 5]) {
-    if (this.atTheBeginning()) this.ziffers.enneaCycle(tonnetz);
+  enneaCycle(tonnetz: TonnetzSpaces = [3, 4, 5], repeats: number = 3, components: number = 1) {
+    if (this.atTheBeginning()) this.ziffers.enneaCycle(tonnetz, repeats, components);
+    return this;
+  }
+
+  cubeDance(tonnetz: TonnetzSpaces = [3, 4, 5], repeats: number = 3) {
+    if (this.atTheBeginning()) this.ziffers.cubeDance(tonnetz, repeats);
+    return this;
+  }
+
+  powerTowers(tonnetz: TonnetzSpaces = [3, 4, 5], repeats: number = 3) {
+    if (this.atTheBeginning()) this.ziffers.powerTowers(tonnetz, repeats);
+    return this;
+  }
+  powerTower = this.powerTowers;
+
+  octaTower(tonnetz: TonnetzSpaces = [3, 4, 5], repeats: number = 3, components: number = 1) {
+    if (this.atTheBeginning()) this.ziffers.octaTower(tonnetz, repeats, components);
+    return this;
+  }
+  octaTowers = this.octaTower;
+
+  boretzRegions(tonnetz: TonnetzSpaces = [3, 4, 5]) {
+    if (this.atTheBeginning()) this.ziffers.boretzRegions(tonnetz);
+    return this;
+  }
+  boretz = this.boretzRegions;
+
+  weitzmannRegions(tonnetz: TonnetzSpaces = [3, 4, 5]) {
+    if (this.atTheBeginning()) this.ziffers.weitzmannRegions(tonnetz);
+    return this;
+  }
+  weitzmann = this.weitzmannRegions;
+
+  shuffle() {
+    if (this.atTheBeginning()) this.ziffers.shuffle();
+    return this;
+  }
+
+  deal(amount: number = this.ziffers.values.length) {
+    if (this.atTheBeginning()) this.ziffers.deal(amount);
+    return this;
+  }
+
+  from(value: number) {
+    if (this.atTheBeginning()) this.ziffers.from(value);
+    return this;
+  }
+
+  to(value: number) {
+    if (this.atTheBeginning()) this.ziffers.to(value);
+    return this;
+  }
+
+  between(value: number, value2: number) {
+    if (this.atTheBeginning()) this.ziffers.between(value, value2+1);
+    return this;
+  }
+
+  at(value: number, ...rest: number[]) {
+    if (this.atTheBeginning()) this.ziffers.at(value, ...rest);
+    return this;
+  }
+
+  keep() {
+    this.ziffers.setRedo(0);
+    return this;
+  }
+
+  repeat(amount: number) {
+    this.ziffers.setRedo(amount < 0 ? 0 : amount);
+    return this;
+  }
+
+  every(amount: number) {
+    if (this.atTheBeginning()) this.ziffers.every(amount);
     return this;
   }
 
@@ -288,6 +439,12 @@ export class Player extends AbstractEvent {
 
   lead = () => this.voiceleading();
 
+  arpeggio(indexes: string|number[], ...rest: number[]) {
+    if(typeof indexes === "number") indexes = [indexes, ...rest];
+    if (this.atTheBeginning()) this.ziffers.arpeggio(indexes);
+    return this;
+  }
+
   invert = (n: number) => {
     if (this.atTheBeginning()) {
       this.ziffers.invert(n);
@@ -300,25 +457,71 @@ export class Player extends AbstractEvent {
     return this;
   }
 
-  wait(value: number | Function) {
+  rotate(amount: number = 1) {
+    if (this.atTheBeginning()) {
+      this.ziffers.rotate(amount+safeMod(this.ziffers.cycleIndex,this.ziffers.evaluated.length));
+    }
+    return this;
+  }
+
+  listen(value: string) {
+    if(typeof value === "string") {
+      const cueTime = this.app.api.cueTimes[value];
+      this.cueName = value;
+      if(cueTime && this.app.clock.pulses_since_origin <= cueTime) {
+        this.waitTime = cueTime;
+      } else {
+          this.waitTime = -1;
+      }
+      return this;
+    }
+  }
+
+  wait(value: number | string | Function) {
+
+    if(typeof value === "string") {
+      const cueTime = this.app.api.cueTimes[value];
+      this.cueName = value;
+      if(cueTime && this.app.clock.pulses_since_origin <= cueTime) {
+        this.waitTime = cueTime;
+      } else if(this.atTheBeginning()){
+          this.waitTime = -1;
+      }
+      return this;
+    }
+
     if (this.atTheBeginning()) {
       if (typeof value === "function") {
         const refPat = this.app.api.patternCache.get(value.name) as Player;
         if (refPat) this.waitTime = refPat.nextEndTime();
         return this;
+      } else if(typeof value === "number") {
+        this.waitTime =
+          this.origin() + Math.ceil(value * 4 * this.app.clock.ppqn);
+        return this;
       }
-      this.waitTime =
-        this.origin() + Math.ceil(value * 4 * this.app.clock.ppqn);
     }
+
     return this;
   }
 
-  sync(value: string | Function) {
+  sync(value: string | Function, manualSync: boolean = true) {
+    if(typeof value === "string" && manualSync) {
+      if(manualSync) {
+        const cueTime = this.app.api.cueTimes[value];
+        if(cueTime) {
+          this.waitTime = cueTime;
+        } else {
+          this.waitTime = -1;
+        }
+      }
+      return this;
+    }
     if (this.atTheBeginning() && this.notStarted()) {
       const origin = this.app.clock.pulses_since_origin;
-      const syncId = typeof value === "function" ? value.name : value;
       if (origin > 0) {
-        const syncPattern = this.app.api.patternCache.get(syncId) as Player;
+        const syncName = typeof value === "function" ? value.name : value;
+        const syncPattern = this.app.api.patternCache.get(syncName) as Player;
         if (syncPattern) {
           const syncPatternDuration = syncPattern.ziffers.duration;
           const syncPatternStart = syncPattern.startCallTime;
@@ -330,6 +533,13 @@ export class Player extends AbstractEvent {
     return this;
   }
 
+  log(key: string, ...args: string[]) {
+    this.app.api.log(this.ziffers.evaluated.map((p) => {
+      return Object.values(p.getExisting(...[key,...args]));
+    }).join(" "));
+    return this;
+  }
+
   out = (): void => {
     // TODO?
   };

src/documentation/basics/atelier.ts

@@ -0,0 +1,193 @@
+import { type Editor } from "../../main";
+import { makeExampleFactory } from "../../Documentation";
+
+export const atelier = (application: Editor): string => {
+  const makeExample = makeExampleFactory(application);
+  return `
+# Atelier (06 mars 2024)
+
+Bonjour tout le monde ! Nous sommes :
+
+- [Rémi Georges](https://remigeorges.fr) : musicien, réalisateur en informatique musicale.
+- [Agathe Herrou](https://www.youtube.com/@th4music) : musicienne, chercheuse.
+- [Raphaël Forment](https://raphaelforment.fr) : musicien, doctorant.
+
+Nous pratiquons le [live coding](https://livecoding.fr). Nous utilisons notre ordinateur comme un instrument de musique, nous programmons de la musique devant notre public. Nous pouvons faire plein de choses comme :
+
+- créer des instruments de musique, des synthétiseurs, des boîtes à rythme.
+- jouer des échantillons, charger des images, des vidéos, créer des animations.
+- contrôler d'autres instruments, jouer avec d'autres musiciens.
+
+Topos est un instrument de musique. On peut l'utiliser depuis n'importe quel ordinateur, sans avoir à installer quoi que ce soit. Nous l'avons fabriqué pour que tout le monde puisse jouer facilement de la musique.
+
+
+## Découverte
+
+<br>
+
+${makeExample(
+    "Percussions", `
+tempo(120) // Changer le tempo
+beat(1)::sound('kick').out()
+beat(2)::sound('snare').out()
+beat(.5)::sound('hh').out()
+`, true,)}
+
+<br>
+
+- Qu'est-ce qu'il se passe si je change un nombre ?
+- Qu'est-ce qu'il se passe si je change un nom ? 
+  - Essayez par exemple <ic>"sid"</ic> ou <ic>"trump"</ic>.
+- Qu'est-ce qu'il se passe si j'enlève <ic>.out()</ic> ?
+- Est-il possible de jouer un rythme très rapide ou très lent ?
+
+
+### Ajout d'une basse
+
+<br>
+
+${makeExample(
+      "Une basse", `
+// Aucun changement dans le code
+beat(1)::sound('kick').out()
+beat(2)::sound('snare').out()
+beat(.5)::sound('hh').out()
+
+// Une nouvelle partie
+beat([0.25,0.5].beat(1))::sound("pluck")
+  .note([40,45].beat(2)).out()
+`, true,)}
+
+<br>
+
+- Qu'est-ce que le son <ic>"pluck"</ic> ?
+
+- Que signifie <ic>.note([40,45].beat(2))</ic> ?
+
+- Que se passe-t-il si je change la valeur dans <ic>.beat(2)</ic> ?
+
+- Que se passe-t-il lorsque j'ajoute de nouveaux nombres dans <ic>[40, 45]</ic> ?
+
+### Ajout d'une mélodie
+
+<br>
+
+${makeExample(
+        "Le morceau complet", `
+// Aucun changement dans le code
+beat(1)::sound('kick').out()
+beat(2)::sound('snare').out()
+beat(.5)::sound('hh').out()
+beat([0.25,0.5].beat(1))::sound("pluck")
+  .note([40,45].beat(2)).out()
+
+// Nouvelle partie mélodique
+beat([0.25,0.5].beat())::sound("pluck")
+  .note([0,7,5,8,2,9,0].scale("Major",60).beat(1))
+  .vib(8).vibmod(1/4)
+  .delay(0.5).room(1.5).size(0.5)
+  .out()
+`, true,)}
+
+<br>
+
+Ici, on ajoute une nouvelle mélodie mais il s'agit aussi d'un nouvel instrument. C'est pour cela que le code est plus long. Quand on fait du <em>live coding</em>, on code tout en même temps : notes, rythmes, mélodies, sons. C'est beaucoup de choses ! C'est pour cela que le code est court, on essaie de tout taper très vite en jouant !
+
+- Que signifie selon vous <ic>vib</ic>, <ic>delay</ic>, <ic>room</ic> ou <ic>size</ic> ?
+
+- Que se passe-t-il si je change les valeurs dans <ic>vib</ic>, <ic>delay</ic>, <ic>room</ic> ou <ic>size</ic> ?
+
+<br>
+
+**Exercices :**
+
+- Transformer <ic>vib(8)</ic> en <ic>vib([2,4,8].beat(1))</ic>.
+- Transformer <ic>"pluck"</ic> en <ic>["pluck", "clap"].beat(1)</ic>.
+
+Vous pouvez aussi utiliser la fonction <ic>rhythm</ic> pour jouer rapidement des rythmes.
+
+${makeExample(
+          "Rythmes rythmes rythmes", `
+rhythm(0.5, 3, 8)::sound('bd').out()
+rhythm(0.5, 3, 8)::sound('clap').out()
+rhythm(0.5, 6, 8)::sound('hat').out()
+rhythm(0.25, 6, 8)::sound('hat')
+  .vel(0.3).speed(2).out()
+rhythm(0.5, 2, 8)::sound('sd').out()
+`, true)};
+
+## Créer un instrument
+
+<br>
+
+Nous allons créer un nouvel instrument à partir d'un son de base. Voici un premier son :
+
+${makeExample("Notre son de base", `beat(2)::sound('sine').note(50).ad(0, .5).out()`, true)}
+
+<br>
+
+Ce son est assez ennuyeux. Nous allons ajouter quelques paramètres :
+
+${makeExample("Beaucoup mieux !", `beat(2)::sound('sine').note(50).fmi(2).fmh(2).ad(0, .5).out()`, true)}
+
+<br>
+
+Nous allons aussi ajouter quelques effets intéressants :
+
+${makeExample("Ajout d'un écho", `beat(2)::sound('sine').note(50)
+  .fmi(2).fmh(2).ad(1/16, 1.5)
+  .delay(0.5).delayt(0.75).out()`,
+            true)}
+
+<br>
+
+Nous pouvons utiliser plusieurs techniques pour rendre le son plus dynamique :
+- générer des valeurs aléatoires pour les paramètres
+- utiliser des générateurs de valeurs (comme <ic>usine</ic>)
+- utiliser la souris ou un autre contrôleur pour changer les valeurs en temps réel
+
+${makeExample("Plus dynamique encore", `
+beat(2)::sound('sine').note([50,55,57,62,66, 69, 74].mouseX())
+  .fmi(usine(1/4)).fmh([1,2,0.5].beat())
+  .ad(1/16, 1.5).delay(0.5).delayt(0.75)
+  .out()`, true)}
+
+<br>
+
+Un exemple final, le plus complexe jusqu'à présent :
+
+${makeExample("Un instrument de musique complet", `
+beat(2)::sound('triangle')
+  .note([50,55,57,62,66, 69, 74].mouseX())
+  .fmi(usine(1/4)).fmh([1,2,0.5].beat())
+  .ad(1/16, 1.5).delay(0.5).delayt(0.75)
+  .room(0.5).size(8).lpf(usine(1/3)*4000).out()`, true)}
+
+## Compléments
+
+${makeExample("Quelques échantillons", `
+ab ade ades2 ades3 ades4 alex alphabet amencutup armora arp arpy auto
+baa baa2 bass bass0 bass1 bass2 bass3 bassdm bassfoo battles bd bend
+bev bin birds birds3 bleep blip blue bottle breaks125 breaks152
+breaks157 breaks165 breath bubble can casio cb cc chin circus clak
+click clubkick co coins control cosmicg cp cr crow d db diphone
+diphone2 dist dork2 dorkbot dr dr2 dr55 dr_few drum drumtraks e east
+electro1 em2 erk f feel feelfx fest fire flick fm foo future gab
+gabba gabbaloud gabbalouder glasstap glitch glitch2 gretsch gtr h
+hand hardcore hardkick haw hc hh hh27 hit hmm ho hoover house ht if
+ifdrums incoming industrial insect invaders jazz jungbass jungle juno
+jvbass kicklinn koy kurt latibro led less lighter linnhats lt made
+made2 mash mash2 metal miniyeah monsterb moog mouth mp3 msg mt mute
+newnotes noise noise2 notes numbers oc off outdoor pad padlong pebbles
+perc peri pluck popkick print proc procshort psr rave rave2 ravemono
+realclaps reverbkick rm rs sax sd seawolf sequential sf sheffield
+short sid sine sitar sn space speakspell speech speechless speedupdown
+stab stomp subroc3d sugar sundance tabla tabla2 tablex tacscan tech
+techno tink tok toys trump ul ulgab uxay v voodoo wind wobble world
+xmas yeah`, true)}
+
+
+`
+};
+
+

src/documentation/basics/code.ts

@@ -5,27 +5,27 @@ export const code = (application: Editor): string => {
   const makeExample = makeExampleFactory(application);
   return `
 # Code
-	
+
 Topos scripts are using the [JavaScript](https://en.wikipedia.org/wiki/JavaScript) syntax. This is the language used to write pretty much anything in a web browser. JavaScript is easy to learn, and even faster to learn if you are already familiar with other programming languages. Here are some good resources if you want to learn more about it:
-	
-- [MDN (Mozilla Web Docs)](https://developer.mozilla.org/): it covers pretty much anything and is considered to be a reliable source to learn how the web currently works. Any web developer knows about it. 
-	
+
+- [MDN (Mozilla Web Docs)](https://developer.mozilla.org/): it covers pretty much anything and is considered to be a reliable source to learn how the web currently works. Any web developer knows about it.
+
 - [Learn JS in Y Minutes](https://learnxinyminutes.com/docs/javascript/): a good tour of the language. Can be useful as a refresher.
-	
+
 - [The Modern JavaScript Tutorial](https://javascript.info/): another well known source to learn the language.
-	
-**You do not need to have any prior knowledge of programming** to use Topos**.
-	
+
+**You do not need to have any prior knowledge of programming to use Topos**.
+
 # How is the code evaluated?
-	
+
 The code you enter in any of the scripts is evaluated in strict mode. This tells your browser that the code you run can be optimized quite agressively. We need this because by default, **the global script is evaluated 48 times per beat**. It also means that you can crash at the speed of light :smile:. There are some things to keep in mind:
-	
+
 - **about variables:** the state of your variables is not kept between iterations. If you write <ic>let a = 2</ic> and remove that value from your script, **it will crash**! Variable and state is not preserved between each run of the script. There are other ways to deal with variables and to share variables between scripts! Some variables like **iterators** can keep their state between iterations because they are saved **with the file itself**. There is also **global variables**.
 - **about errors and printing:** your code will crash! Don't worry, we do our best to make it crash in the most gracious way possible. Most errors are caught and displayed in the interface. For weirder bugs, open the dev console with ${key_shortcut(
     "Ctrl + Shift + I",
-  )}. You cannot directly use <ic>console.log('hello, world')</ic> in the interface but you can use <ic>log(message)</ic> to print a one line message. You will have to open the console as well to see your messages being printed there!
+  )}. You cannot directly use <ic>console.log('hello, world')</ic> in the interface but you can use <ic>log(message)</ic> to print a one line message. You will have to open the console as well to see your messages being printed there! You can also use <ic>logOnce(message)</ic> to print a message only once (or everytime you press Ctrl+Shift+Backspace).
 - **about new syntax:** sometimes, we had some fun with JavaScript's syntax in order to make it easier/faster to write on stage. <ic>&&</ic> can also be written <ic>::</ic> or <ic>-></ic> because it is faster to type or better for the eyes!
-	
+
 # Common idioms
 
 There are some techniques to keep code short and tidy. Don't try to write the shortest possible code! Use shortcuts when it makes sense. Take a look at the following examples:
@@ -38,8 +38,8 @@ beat(.75) :: snd('linnhats').n([1,4,5].beat()).out()
 beat(1) :: snd('bd').out()
 //if (true) && log('very true')
 // These two lines are the same:
-// beat(1) && snd('bd').out() 
-//// beat(1) :: snd('bd').out() 
+// beat(1) && snd('bd').out()
+//// beat(1) :: snd('bd').out()
 
 `,
   true,
@@ -67,7 +67,7 @@ beat(4) ? snd('kick').out() : beat(2) :: snd('snare').out()
 )}
 
 # About crashes and bugs
-	
+
 Things will crash! It's part of the show! You will learn progressively to avoid mistakes and to write safer code. Do not hesitate to kill the page or to stop the transport if you feel overwhelmed by an algorithm blowing up. There is no safeguard to stop you from doing most things. This is to ensure that you have all the available possible room to write bespoke code and experiment with your ideas through code.
 
 ${makeExample(

src/documentation/basics/interaction.ts

@@ -1,5 +1,5 @@
-import { type Editor } from "../main";
-import { makeExampleFactory } from "../Documentation";
+import { type Editor } from "../../main";
+import { makeExampleFactory } from "../../Documentation";
 
 // @ts-ignore
 export const interaction = (application: Editor): string => {
@@ -20,57 +20,57 @@ MIDI input can be enabled in the settings panel. Once you have done that, you ca
 * <ic>active_notes(channel?: number)</ic>: returns array of the active notes / pressed keys as an array of MIDI note numbers (0-127). Returns undefined if no notes are active.
 
 ${makeExample(
-  "Play active notes as chords",
-  `
+    "Play active notes as chords",
+    `
   beat(1) && active_notes() && sound('sine').chord(active_notes()).out()
   `,
-  true,
-)}
+    true,
+  )}
 
 ${makeExample(
-  "Play active notes as arpeggios",
-  `
+    "Play active notes as arpeggios",
+    `
   beat(0.25) && active_notes() && sound('juno').note(
     active_notes().beat(0.5)+[12,24].beat(0.25)
   ).cutoff(300 + usine(1/4) * 2000).out()
   `,
-  false,
-)}
+    false,
+  )}
 
 
 * <ic>sticky_notes(channel?: number)</ic>: returns array of the last pressed keys as an array of MIDI note numbers (0-127). Notes are added and removed from the list with the "Note on"-event. Returns undefined if no keys have been pressed.
 
 ${makeExample(
-  "Play continous arpeggio with sticky notes",
-  `
+    "Play continous arpeggio with sticky notes",
+    `
   beat(0.25) && sticky_notes() && sound('arp')
   .note(sticky_notes().palindrome().beat(0.25)).out()
   `,
-  true,
-)}
+    true,
+  )}
 
 * <ic>last_note(channel?: number)</ic>: returns the last note that has been received. Returns 60 if no other notes have been received.
 
 ${makeExample(
-  "Play last note",
-  `
+    "Play last note",
+    `
   beat(0.5) && sound('sawtooth').note(last_note())
   .vib([1, 3, 5].beat(1))
   .vibmod([1,3,2,4].beat(2)).out()
   `,
-  false,
-)}
+    false,
+  )}
 
 * <ic>buffer()</ic>: return true if there are notes in the buffer.
 * <ic>buffer_note(channel?: number)</ic>: returns last unread note that has been received. Note is fetched and removed from start of the buffer once this is called. Returns undefined if no notes have been received.
 
 ${makeExample(
-  "Play buffered note",
-  `
+    "Play buffered note",
+    `
   beat(1) && buffer() && sound('sine').note(buffer_note()).out()
   `,
-  false,
-)}
+    false,
+  )}
 
 
 
@@ -80,33 +80,33 @@ ${makeExample(
 Midi CC messages can be used to control any value in Topos. MIDI input can be defined in Settings and last received CC message can be used to control any numeric value within Topos.
 
 Currently supported methods for CC input are:
-* <ic>last_cc(control: number, channel?: number)</ic>: Returns last received CC value for given control number (and optional channel). By default last CC value is last value from ANY channel or 64 if no CC messages have been received.
+* <ic>ccIn(control: number, channel?: number)</ic>: Returns last received CC value for given control number (and optional channel). By default last CC value is last value from ANY channel or 64 if no CC messages have been received.
 
 ${makeExample(
-  "Play notes with cc",
-  `
-  beat(0.5) && sound('arp').note(last_cc(74)).out()
+    "Play notes with cc",
+    `
+  beat(0.5) && sound('arp').note(ccin(74)).out()
   `,
-  true,
-)}
+    true,
+  )}
 
 ${makeExample(
-  "Control everything with CCs",
-  `
+    "Control everything with CCs",
+    `
   beat(0.5) :: sound('sine')
-  .freq(last_cc(75)*3)
-  .cutoff(last_cc(76)*2*usine())
+  .freq(ccIn(75)*3)
+  .cutoff(ccIn(76)*2*usine())
   .sustain(1.0)
   .out()
 
-beat(last_cc(74)/127*.5) :: sound('sine')
-  .freq(last_cc(75)*6)
-  .cutoff(last_cc(76)*3*usine())
-  .sustain(last_cc(74)/127*.25)
+beat(ccIn(74)/127*.5) :: sound('sine')
+  .freq(ccIn(75)*6)
+  .cutoff(ccIn(76)*3*usine())
+  .sustain(ccIn(74)/127*.25)
   .out()
   `,
-  false,
-)}
+    false,
+  )}
 
 
 ## Run scripts with MIDI
@@ -126,10 +126,10 @@ Topos can output scales to external keyboards lighted keys using the following f
 - <ic>show_scale(key: string, scale: string|int, channel?: number, port?: string|number, soundOff?: boolean): void</ic>: sends the scale as midi on messages to specified port and channel to light the keys of external keyboard. If soundOff is true, all sound off message will be sent after every note on message. This can be useful with some keyboards not supporting external channel for lightning or routing for the midi in to suppress the sound from incoming note on messages.
 
 ${makeExample(
-  "Show scale on external keyboard",
-  `show_scale("F","aeolian",0,4)`,
-  true,
-)}
+    "Show scale on external keyboard",
+    `show_scale("F","aeolian",0,4)`,
+    true,
+  )}
 
 ${makeExample("Hide scale", `hide_scale("F","aeolian",0,4)`, true)}
 

src/documentation/basics/keyboard.ts

@@ -49,6 +49,9 @@ Topos is made to be controlled entirely with a keyboard. It is recommanded to st
 |Force Eval|${key_shortcut(
     "Ctrl + Shift + Enter",
   )}|Force evaluation of the current script|
+  |Clear cache & Eval|${key_shortcut(
+    "Ctrl + Shift + Backspace (Delete)",
+  )}|Clears cache and forces evaluation to update cached scripts|
 	
 ### Special
 

src/documentation/basics/welcome.ts

@@ -12,30 +12,30 @@ Welcome to the **Topos** documentation. You can jump here anytime by pressing ${
   )}.  Press again to make the documentation disappear. Contributions are much appreciated! The documentation [lives here](https://github.com/Bubobubobubobubo/topos/tree/main/src/documentation).
 
 ${makeExample(
-  "Welcome! Eval to get started",
-  examples[Math.floor(Math.random() * examples.length)],
-  true,
-)}
+    "Welcome! Eval to get started",
+    examples[Math.floor(Math.random() * examples.length)],
+    true,
+  )}
 	
 # What is Topos?
 	
 Topos is an _algorithmic_ sequencer. Topos is also a _live coding_ environment. To sum it up, think: "_making music in real time through code_". Code used as an expressive medium for musical improvisation! Topos uses small algorithms to represent musical sequences and processes.
 	
 ${makeExample(
-  "Small algorithms for direct musical expression",
-  `
+    "Small algorithms for direct musical expression",
+    `
 rhythm(.5, 4, 8) :: sound('drum').out()
 rhythm(.25, [5, 7].beat(2), 8) :: sound(['hc', 'fikea', 'hat'].pick(1))
   .lpf([500, 4000+usine(1/2)*2000]).pan(r(0, 1)).ad(0, [1, .5])
   .db(-ir(1,8)).speed([1,[0.5, 2].pick()]).room(0.5).size(3).o(4).out()
 beat([2,0.5].dur(13.5, 0.5))::snd('fsoftsnare')
   .n(0).speed([1, 0.5]).o(4).out()`,
-  false,
-)}
+    false,
+  )}
 
 ${makeExample(
-  "Computer music should be immediate and intuitive",
-  `
+    "Computer music should be immediate and intuitive",
+    `
 let chord_prog = [0, 0, 5].bar() // Chord progression
 beat(.25)::snd('sine')
   .note(chord_prog + [60, 64, 67, 71].mouseX() 
@@ -47,26 +47,29 @@ beat(.25)::snd('sine')
   .delay(0.5).delayt(0.25).delayfb(0.7) // Delay
   .room(0.5).size(8) // Reverb
   .out()`,
-  false,
-)}
+    false,
+  )}
 
 ${makeExample(
-  "Making the web less dreadful, one beep at at time",
-  `
+    "Making the web less dreadful, one beep at at time",
+    `
 beat(.5) :: sound('sid').n($(2))
   .room(1).speed([1,2].pick()).out()
 beat(.25) :: sound('sid').note(
   [34, 36, 41].beat(.25) + [[0,-24].pick(),12].beat())
   .room(0.9).size(0.9).n(4).out()`,
-  false,
-)}
+    false,
+  )}
 	
 Topos is deeply inspired by the [Monome Teletype](https://monome.org/). The Teletype is/was an open source hardware module for Eurorack synthesizers. While the Teletype was initially born as an hardware module, Topos aims to be a web-browser based cousin of it! It is a sequencer, a scriptable interface, a companion for algorithmic music-making. Topos wishes to fullfill the same goal as the Teletype, keeping the same spirit alive on the web. It is free, open-source, and made to be shared and used by everyone.  Learn more about live coding on [livecoding.fr](https://livecoding.fr).
 
-## Demo Songs
+## Alternative documentation source (.pdf)
+
+You can also find a .pdf version listing the principal commands and functions [here](https://github.com/Bubobubobubobubo/topos/blob/main/src/documentation/basics/TOPOS_COMMANDS.pdf). This document has been generated by Chris Collis. It recaps the main sections of this documentation and can be a good companion while learning Topos.
+
+## Support
+
+<p>You can <a href='https://ko-fi.com/I2I2RSBHF' target='_blank'><img height='36' style='display: inline; border:0px;height:36px;' src='https://storage.ko-fi.com/cdn/kofi3.png?v=3' border='0' alt='Buy Me a Coffee at ko-fi.com' /></a> to support the development :) </p>
 
-Reloading the application will get you one random song example to study every time. Press ${key_shortcut(
-    "F5",
-  )} and listen to them all! The demo songs are also used a bit everywhere in the documentation to illustrate some of the working principles :).
 `;
 };

src/documentation/engine.ts

@@ -1,91 +0,0 @@
-import { type Editor } from "../main";
-import { makeExampleFactory } from "../Documentation";
-
-export const sound = (application: Editor): string => {
-  const makeExample = makeExampleFactory(application);
-  return `
-
-
-## Sample Controls
-
-There are some basic controls over the playback of each sample. This allows you to get into more serious sampling if you take the time to really work with your audio materials.
-	
-| Method  | Alias | Description                                            |
-|---------|-------|--------------------------------------------------------|
-| <ic>n</ic>       |       | Select a sample in the current folder (from <ic>0</ic> to infinity)                 |
-| <ic>begin</ic>   |       | Beginning of the sample playback (between <ic>0</ic> and <ic>1</ic>)     |
-| <ic>end</ic>     |       | End of the sample (between <ic>0</ic> and <ic>1</ic>)                    |
-| <ic>loopBegin</ic> |     | Beginning of the loop section (between <ic>0</ic> and <ic>1</ic>)        |
-| <ic>loopEnd</ic> |     | End of the loop section (between <ic>0</ic> and <ic>1</ic>)        |
-| <ic>loop</ic>    |       | Whether to loop or not the audio sample          |
-| <ic>stretch</ic>    |       | Stretches the audio playback rate of a sample over <ic>n</ic> beats          |
-| <ic>speed</ic>   |       | Playback speed (<ic>2</ic> = twice as fast)         |
-| <ic>cut</ic>     |       | Set with <ic>0</ic> or <ic>1</ic>. Will cut the sample as soon as another sample is played on the same bus |
-| <ic>clip</ic>    |       | Multiply the duration of the sample with the given number |
-| <ic>pan</ic>     |       | Stereo position of the audio playback (<ic>0</ic> = left, <ic>1</ic> = right)|
-	
-${makeExample(
-  "Complex sampling duties",
-  `
-// Using some of the modifiers described above :)
-beat(.5)::snd('pad').begin(0.2)
-  .speed([1, 0.9, 0.8].beat(4))
-  .n(2).pan(usine(.5))
-  .end(rand(0.3,0.8))
-  .room(0.8).size(0.5)
-  .clip(1).out()
-	`,
-  true,
-)};
-	
-${makeExample(
-  "Playing an amen break",
-  `
-// Note that stretch has the same value as beat
-beat(4) :: sound('amen1').n(11).stretch(4).out()
-beat(1) :: sound('kick').shape(0.35).out()`,
-  true,
-)};
-
-	
-## Filters
-	
-There are three basic filters: a _lowpass_, _highpass_ and _bandpass_ filters with rather soft slope. Each of them can take up to two arguments. You can also use only the _cutoff_ frequency and the resonance will stay to its default nominal value. You will learn more about the usage of filters in the synths page!
-	
-| Method     | Alias | Description                             |
-|------------|-------|-----------------------------------------|
-| <ic>cutoff</ic>     | lpf   | Cutoff frequency of the lowpass filter  |
-| <ic>resonance</ic>  | lpq   | Resonance of the lowpass filter         |
-| <ic>hcutoff</ic>    | hpf   | Cutoff frequency of the highpass filter |
-| <ic>hresonance</ic> | hpq   | Resonance of the highpass filter        |
-| <ic>bandf</ic>      | bpf   | Cutoff frequency of the bandpass filter |
-| <ic>bandq</ic>      | bpq   | Resonance of the bandpass filter        |
-| <ic>vowel</ic> |       | Formant filter with (vocal quality)     |
-
-${makeExample(
-  "Filter sweep using a low frequency oscillator",
-  `
-beat(.5) && snd('sawtooth')
-  .cutoff([2000,500].pick() + usine(.5) * 4000)
-  .resonance(0.9).freq([100,150].pick())
-  .out()
-	`,
-  true,
-)};
-	
-	
-## Compression
-
-This effect is leveraging the basic WebAudio compressor. More information can be found about it on the [DynamicsCompressorNode](https://developer.mozilla.org/en-US/docs/Web/API/DynamicsCompressorNode?retiredLocale=de#instance_properties) page. This can be come quite complex :)
-
-| Method     | Alias     | Description                     |
-|------------|-----------|---------------------------------|
-| <ic>comp</ic>     | cmp | Compressor threshold value (dB) over which compressor operates |
-| <ic>ratio</ic>     | rt | Compressor ratio: input amount in dB needed for 1dB change in the output   |
-| <ic>knee</ic>     | kn | dB value defining the range over which the signal transitions to compressed section |
-| <ic>compAttack</ic>     | cmpa | In seconds, time to decrease the gain by 10db |
-| <ic>compRelease</ic>     | cmpr | In seconds, time to increase the gain by 10db |
-
-
-`;
-};

src/documentation/inlineHelp.ts

@@ -733,8 +733,8 @@ const completionDatabase: CompletionDatabase = {
   midi: {
     name: "midi",
     category: "midi",
-    description: "Send a MIDI message",
-    example: "midi(144, 60, 100)",
+    description: "Send a MIDI message (note, velocity, channel)",
+    example: "midi(144, 60, 1)",
   },
   control_change: {
     name: "control_change",
@@ -742,6 +742,12 @@ const completionDatabase: CompletionDatabase = {
     description: "Send a MIDI control change message",
     example: "control_change({control: 1, value: 60, channel: 10})",
   },
+  cc: {
+    name: "cc",
+    category: "midi",
+    description: "Send a MIDI control change message",
+    example: "cc({control: 1, value: 60, channel: 10})",
+  },
   program_change: {
     name: "program_change",
     category: "midi",
@@ -782,7 +788,7 @@ const completionDatabase: CompletionDatabase = {
     name: "counter",
     category: "patterns",
     description: "Counter/iterator",
-    example: "counter('my_counter_, 20, 1)",
+    example: "counter('my_counter', 20, 1)",
   },
   drunk: {
     name: "drunk",
@@ -808,11 +814,17 @@ const completionDatabase: CompletionDatabase = {
     description: "Wraps (or not) of the drunk walk (boolean)",
     example: "drunk_wrap(true)",
   },
-  v: {
-    name: "v",
+  global: {
+    name: "global",
     category: "variable",
     description: "Global Variable setter or getter",
-    example: "v('my_var', 10) // Sets global variable 'my_var' to 10",
+    example: "global.my_var = 10; // Sets global variable 'my_var' to 10",
+  },
+  g: {
+    name: "g",
+    category: "variable",
+    description: "Global Variable setter or getter",
+    example: "g.my_var = 10; // Sets global variable 'my_var' to 10",
   },
   delete_variable: {
     name: "delete_variable",
@@ -898,12 +910,6 @@ const completionDatabase: CompletionDatabase = {
     description: "Detects if the Alt key is pressed",
     example: "fill() ? 1 : 0.5",
   },
-  comp: {
-    name: "comp",
-    category: "synthesis",
-    description: "Compressor threshold (dB)",
-    example: "sound('sine').comp(-4).out()",
-  },
   ratio: {
     name: "ratio",
     category: "synthesis",
@@ -959,12 +965,12 @@ export const inlineHoveringTips = hoverTooltip(
         let completion =
           completionDatabase[text.slice(start - from, end - from)] || {};
         let divContent = `
-      <h1 class="text-orange-300 text-base pb-1">${completion.name} [<em class="text-white">${completion.category}</em>]</h1>
+      <h1 class="text-brightwhite text-base pb-1">${completion.name} [<em class="text-white">${completion.category}</em>]</h1>
       <p class="text-base pl-4">${completion.description}</p>
       <pre class="-mt-2"><code class="pl-4 text-base">${completion.example}</code></pre></div>
       `;
         let dom = document.createElement("div");
-        dom.classList.add("px-4", "py-2", "bg-neutral-700", "rounded-lg");
+        dom.classList.add("px-4", "py-2", "bg-background", "rounded-lg");
         dom.innerHTML = divContent;
         return { dom };
       },
@@ -984,7 +990,7 @@ export const toposCompletions = (context: CompletionContext) => {
         info: () => {
           let div = document.createElement("div");
           div.innerHTML = `
-      <h1 class="text-orange-300 text-base pb-1">${completionDatabase[key].name} [<em class="text-white">${completionDatabase[key].category}</em>]</h1>
+      <h1 class="text-brightwhite text-base pb-1">${completionDatabase[key].name} [<em class="text-white">${completionDatabase[key].category}</em>]</h1>
       <p class="text-base pl-4">${completionDatabase[key].description}</p>
       <div class="overflow-hidden overflow-scroll rounded px-2 ml-4 mt-2 bg-neutral-800"><code class="text-sm">${completionDatabase[key].example}</code></div>
       `;

src/documentation/learning/audio_engine/amplitude.ts

@@ -1,5 +1,5 @@
-import { type Editor } from "../../main";
-import { makeExampleFactory } from "../../Documentation";
+import { type Editor } from "../../../main";
+import { makeExampleFactory } from "../../../Documentation";
 
 export const amplitude = (application: Editor): string => {
   // @ts-ignore
@@ -33,42 +33,43 @@ beat(.5)::snd('cp').vel($(1)%10 / 10).out()`,
 | <ic>decay</ic>   | dec   | Decay value (time to decay to sustain level)  |
 | <ic>sustain</ic> | sus   | Sustain value (gain when sound is held)       |
 | <ic>release</ic> | rel   | Release value (time for the sound to die off) |
+| <ic>adsr</ic>    |       | Shortcut that combines all the parameters together |
 	
 Note that the **sustain** value is not a duration but an amplitude value (how loud). The other values are the time for each stage to take place. Here is a fairly complete example using the <ic>sawtooth</ic> basic waveform.
 	
 ${makeExample(
   "Simple synthesizer",
   `
-let smooth = (sound) => {
-  return sound.cutoff(r(100,500))
-       .lpadsr(usaw(1/8) * 8, 0.05, .125, 0, 0)
-       .gain(r(0.25, 0.4)).adsr(0, r(.2,.4), r(0,0.5), 0)
-       .room(0.9).size(2).o(2).vib(r(2,8)).vibmod(0.125)
-}
-beat(.25)::smooth(sound('sawtooth')
-  .note([50,57,55,60].beat(1))).out();
-beat(.25)::smooth(sound('sawtooth')
-  .note([50,57,55,60].add(12).beat(1.5))).out();
+register("smooth", x => x.cutoff(r(100,500))
+  .lpadsr(usaw(1/8) * 8, 0.05, .125, 0, 0)
+  .gain(r(0.25, 0.4)).adsr(0, r(.2,.4), r(0,0.5), 0)
+  .room(0.9).size(2).o(2).vib(r(2,8)).vibmod(0.125))
+beat(.25)::sound('sawtooth')
+.note([50,57,55,60].beat(1))
+.smooth().out();
+beat(.25)::sound('sawtooth')
+.note([50,57,55,60].add(12).beat(1.5))
+.smooth().out();
 	`,
   true,
 )};
-	
+
 Sometimes, using a full ADSR envelope is a bit overkill. There are other simpler controls to manipulate the envelope like the <ic>.ad</ic> method:
 
 
 ${makeExample(
   "Replacing .adsr by .ad",
   `
-let smooth = (sound) => {
-  return sound.cutoff(r(100,500))
-       .lpadsr(usaw(1/8) * 8, 0.05, .125, 0, 0)
-       .gain(r(0.25, 0.4)).ad(0, .25)
-       .room(0.9).size(2).o(2).vib(r(2,8)).vibmod(0.125)
-}
-beat(.25)::smooth(sound('sawtooth')
-  .note([50,57,55,60].beat(1))).out();
-beat(.25)::smooth(sound('sawtooth')
-  .note([50,57,55,60].add(12).beat(1.5))).out();
+register("smooth", x => x.cutoff(r(100,500))
+  .lpadsr(usaw(1/8) * 8, 0.05, .125, 0, 0)
+  .gain(r(0.25, 0.4)).ad(0, 0.25)
+  .room(0.9).size(2).o(2).vib(r(2,8)).vibmod(0.125))
+beat(.25)::sound('sawtooth')
+.note([50,57,55,60].beat(1))
+.smooth().out();
+beat(.25)::sound('sawtooth')
+.note([50,57,55,60].add(12).beat(1.5))
+.smooth().out();
 	`,
   true,
 )};

src/documentation/learning/audio_engine/audio_basics.ts

@@ -1,5 +1,5 @@
-import { type Editor } from "../../main";
-import { makeExampleFactory } from "../../Documentation";
+import { type Editor } from "../../../main";
+import { makeExampleFactory } from "../../../Documentation";
 
 export const audio_basics = (application: Editor): string => {
   // @ts-ignore

src/documentation/learning/audio_engine/distortion.ts

@@ -1,5 +1,5 @@
-import { type Editor } from "../../main";
-import { makeExampleFactory } from "../../Documentation";
+import { type Editor } from "../../../main";
+import { makeExampleFactory } from "../../../Documentation";
 
 export const distortion = (application: Editor): string => {
   // @ts-ignore

src/documentation/learning/audio_engine/effects.ts

@@ -1,7 +1,7 @@
-import { type Editor } from "../../main";
-import { makeExampleFactory } from "../../Documentation";
+import { type Editor } from "../../../main";
+import { makeExampleFactory } from "../../../Documentation";
 
-export const reverb = (application: Editor): string => {
+export const effects = (application: Editor): string => {
   // @ts-ignore
   const makeExample = makeExampleFactory(application);
   return `
@@ -90,5 +90,34 @@ beat(.5)::snd('pad').crush([16, 8, 4].beat(2)).clip(.5).out()
 	`,
   true,
 )};
+
+## Vibrato
+
+You can also add some amount of vibrato to the sound using the <ic>vib</ic> and <ic>vibmod</ic> methods. These can turn any oscillator into something more lively and/or into a sound effect when used with a high amount of modulation.
+
+${makeExample(
+  "Different vibrato settings",
+  `
+tempo(140);
+beat(1) :: sound('triangle')
+  .freq(400).release(0.2)
+  .vib([1/2, 1, 2, 4].beat())
+  .vibmod([1,2,4,8].beat(2))
+  .out()`,
+  true,
+)}
+
+## Compression
+
+This effect is leveraging the basic WebAudio compressor. More information can be found about it on the [DynamicsCompressorNode](https://developer.mozilla.org/en-US/docs/Web/API/DynamicsCompressorNode?retiredLocale=de#instance_properties) page. This can be come quite complex :)
+
+| Method     | Alias     | Description                     |
+|------------|-----------|---------------------------------|
+| <ic>comp</ic>     | cmp | Compressor threshold value (dB) over which compressor operates |
+| <ic>ratio</ic>     | rt | Compressor ratio: input amount in dB needed for 1dB change in the output   |
+| <ic>knee</ic>     | kn | dB value defining the range over which the signal transitions to compressed section |
+| <ic>compAttack</ic>     | cmpa | In seconds, time to decrease the gain by 10db |
+| <ic>compRelease</ic>     | cmpr | In seconds, time to increase the gain by 10db |
+
 `;
 };

src/documentation/learning/audio_engine/filters.ts

@@ -0,0 +1,145 @@
+import { type Editor } from "../../../main";
+import { makeExampleFactory } from "../../../Documentation";
+
+export const filters = (application: Editor): string => {
+  const makeExample = makeExampleFactory(application);
+  return `
+# Filters
+
+Filters can be applied to both synthesizers and samples. They are used to shape the sound by removing or emphasizing certain frequencies. They are also used to create movement in the sound by modulating the cutoff frequency of the filter over time. 
+
+- **lowpass filter**: filters the high frequencies, keeping the low frequencies.
+- **highpass filter**: filtering the low frequencies, keeping the high frequencies.
+- **bandpass filter**: filters the low and high frequencies around a frequency band, keeping what's in the middle.
+
+${makeExample(
+  "Filtering the high frequencies of an oscillator",
+  `beat(.5) :: sound('sawtooth').cutoff(50 + usine(1/8) * 2000).out()`,
+  true,
+)}
+
+These filters all come with their own set of parameters. Note that we are describing the parameters of the three different filter types here. Choose the right parameters depending on the filter type you are using:
+
+
+### Lowpass filter
+
+| Method     | Alias     | Description                     |
+|------------|-----------|---------------------------------|
+| <ic>cutoff</ic>     | <ic>lpf</ic>       | cutoff frequency of the lowpass filter |
+| <ic>resonance</ic>  | <ic>lpq</ic>       | resonance of the lowpass filter (0-1) |
+
+${makeExample(
+  "Filtering a bass",
+  `beat(.5) :: sound('jvbass').lpf([250,1000,8000].beat()).out()`,
+  true,
+)}
+
+### Highpass filter
+
+| Method     | Alias     | Description                     |
+|------------|-----------|---------------------------------|
+| <ic>hcutoff</ic>     | <ic>hpf</ic>       | cutoff frequency of the highpass filter |
+| <ic>hresonance</ic>  | <ic>hpq</ic>       | resonance of the highpass filter (0-1) |
+
+${makeExample(
+  "Filtering a noise source",
+  `beat(.5) :: sound('gtr').hpf([250,1000, 2000, 3000, 4000].beat()).end(0.5).out()`,
+  true,
+)}
+
+### Bandpass filter
+
+| Method     | Alias     | Description                     |
+|------------|-----------|---------------------------------|
+| <ic>bandf</ic>      | <ic>bpf</ic>       | cutoff frequency of the bandpass filter |
+| <ic>bandq</ic>      | <ic>bpq</ic>       | resonance of the bandpass filter (0-1) |
+
+${makeExample(
+  "Sweeping the filter on the same guitar sample",
+  `beat(.5) :: sound('gtr').bandf(100 + usine(1/8) * 4000).end(0.5).out()`,
+  true,
+)}
+
+Alternatively, <ic>lpf</ic>, <ic>hpf</ic> and <ic>bpf</ic> can take a second argument, the **resonance**.
+
+## Filter order (type)
+
+You can also use the <ic>ftype</ic> method to change the filter type (order). There are two types by default, <ic>12db</ic> for a gentle slope or <ic>24db</ic> for a really steep filtering slope. The <ic>24db</ic> type is particularly useful for substractive synthesis if you are trying to emulate some of the Moog or Prophet sounds:
+
+- <ic>ftype(type: string)</ic>: sets the filter type (order), either <ic>12db</ic> or <ic>24db</ic>.
+
+${makeExample(
+  "Filtering a bass",
+  `beat(.5) :: sound('jvbass').ftype(['12db', '24db'].beat(4)).lpf([250,1000,8000].beat()).out()`,
+  true,
+)}
+
+## Filter envelopes
+
+The examples we have studied so far are static. They filter the sound around a fixed cutoff frequency. To make the sound more interesting, you can use the ADSR filter envelopes to shape the filter cutoff frequency over time. You will always find amplitude and filter envelopes on most commercial synthesizers. This is done using the following methods:
+
+### Lowpass envelope
+
+| Method     | Alias     | Description                     |
+|------------|-----------|---------------------------------|
+| <ic>lpenv</ic>      | <ic>lpe</ic>       | lowpass frequency modulation amount (negative or positive) |
+| <ic>lpattack</ic>   | <ic>lpa</ic>       | attack of the lowpass filter    |
+| <ic>lpdecay</ic>    | <ic>lpd</ic>       | decay of the lowpass filter     |
+| <ic>lpsustain</ic>  | <ic>lps</ic>       | sustain of the lowpass filter   |
+| <ic>lprelease</ic>  | <ic>lpr</ic>       | release of the lowpass filter   |
+| <ic>lpadsr</ic>     |                    | (**takes five arguments**) set all the parameters  |
+
+
+${makeExample(
+  "Filtering a sawtooth wave dynamically",
+  `beat(.5) :: sound('sawtooth').note([48,60].beat())
+  .cutoff(5000).lpa([0.05, 0.25, 0.5].beat(2))
+  .lpenv(-8).lpq(10).out()`,
+  true,
+)}
+
+### Highpass envelope
+
+| Method     | Alias     | Description                     |
+|------------|-----------|---------------------------------|
+| <ic>hpenv</ic>      | <ic>hpe</ic>       | highpass frequency modulation amount (negative or positive) |
+| <ic>hpattack</ic>   | <ic>hpa</ic>       | attack of the highpass filter    |
+| <ic>hpdecay</ic>    | <ic>hpd</ic>       | decay of the highpass filter     |
+| <ic>hpsustain</ic>  | <ic>hps</ic>       | sustain of the highpass filter   |
+| <ic>hprelease</ic>  | <ic>hpr</ic>       | release of the highpass filter   |
+| <ic>hpadsr</ic>     |           | (**takes five arguments**) set all the parameters  |
+
+
+${makeExample(
+  "Let's use another filter using the same example",
+  `beat(.5) :: sound('sawtooth').note([48,60].beat())
+  .hcutoff(1000).hpa([0.05, 0.25, 0.5].beat(2))
+  .hpenv(8).hpq(10).out()`,
+  true,
+)}
+
+### Bandpass envelope
+
+| Method     | Alias     | Description                     |
+|------------|-----------|---------------------------------|
+| <ic>bpenv</ic>      | <ic>bpe</ic>       | bandpass frequency modulation amount (negative or positive) |
+| <ic>bpattack</ic>   | <ic>bpa</ic>       | attack of the bandpass filter    |
+| <ic>bpdecay</ic>    | <ic>bpd</ic>       | decay of the bandpass filter     |
+| <ic>bpsustain</ic>  | <ic>bps</ic>       | sustain of the bandpass filter   |
+| <ic>bprelease</ic>  | <ic>bpr</ic>       | release of the bandpass filter   |
+| <ic>bpadsr</ic>     |           | (**takes five arguments**) set all the parameters  |
+
+
+${makeExample(
+  "And the bandpass filter, just for fun",
+  `beat(.5) :: sound('sawtooth').note([48,60].beat())
+  .bandf([500,1000,2000].beat(2))
+  .bpa([0.25, 0.125, 0.5].beat(2) * 4)
+  .bpenv(-4).release(2).out()
+  `,
+  true,
+)}
+
+
+`;
+};

src/documentation/learning/audio_engine/sampler.ts

@@ -1,5 +1,5 @@
-import { type Editor } from "../../main";
-import { makeExampleFactory } from "../../Documentation";
+import { type Editor } from "../../../main";
+import { makeExampleFactory } from "../../../Documentation";
 
 export const sampler = (application: Editor): string => {
   // @ts-ignore

src/documentation/learning/audio_engine/synths.ts

@@ -1,5 +1,5 @@
-import { type Editor } from "../main";
-import { makeExampleFactory } from "../Documentation";
+import { type Editor } from "../../../main";
+import { makeExampleFactory } from "../../../Documentation";
 
 export const synths = (application: Editor): string => {
   const makeExample = makeExampleFactory(application);
@@ -13,35 +13,36 @@ Topos comes by default with a forever-increasing number of synthesis capabilitie
 The <ic>sound</ic> function can take the name of a synthesizer or waveform as first argument. This has for effect to turn the sampler we all know and love into a synthesizer. <ic>sine</ic>, <ic>sawtooth</ic>,<ic>triangle</ic>, <ic>square</ic> are the names used to select classic oscillator waveforms. Note that you can also make use of filters and envelopes to shape the sound to your liking.
 
 ${makeExample(
-  "Listening to the different waveforms from the sweetest to the harshest",
-  `
+    "Listening to the different waveforms from the sweetest to the harshest",
+    `
 beat(.5) && snd(['sine', 'triangle', 'sawtooth', 'square'].beat()).freq(100).out()
 `,
-  true,
-)}
+    true,
+  )}
 
 Note that you can also use noise if you do not want to use a periodic oscillator:
 
-
 ${makeExample(
-  "Listening to the different types of noise",
-  `
-beat(.5) && snd(['brown', 'pink', 'white'].beat()).adsr(0,.1,0,0).out()
+    "Listening to the different types of noise",
+    `
+beat(.5) && snd(['brown', 'pink', 'white', 'crackle'].beat()).adsr(0,.1,0,0).out()
 `,
-  true,
-)}
+    true,
+  )}
+
+The <ic>crackle</ic> type can be controlled using the <ic>density</ic> parameter.
 
 Two functions are primarily used to control the frequency of the synthesizer:
 - <ic>freq(hz: number)</ic>: sets the frequency of the oscillator.
 - <ic>note(note: number|string)</ic>: sets the MIDI note of the oscillator (MIDI note converted to hertz).
 
 ${makeExample(
-  "Selecting a pitch",
-  `
+    "Selecting a pitch",
+    `
 beat(.5) && snd('triangle').freq([100,200,400].beat(2)).out()
 `,
-  true,
-)}
+    true,
+  )}
 
   ${makeExample(
     "Selecting a note",
@@ -56,72 +57,40 @@ Chords can also played using different parameters:
 - <ic>chord(string||number[]|...number)</ic>: parses and sets notes for the chord
 
 ${makeExample(
-  "Playing a named chord",
-  `
+    "Playing a named chord",
+    `
     beat(1) && snd('triangle').chord(["C","Em7","Fmaj7","Emin"].beat(2)).adsr(0,.2).out()
 `,
-  true,
-)}  
+    true,
+  )}  
 
 ${makeExample(
-  "Playing a chord from a list of notes and doing inversions",
-  `
+    "Playing a chord from a list of notes and doing inversions",
+    `
     beat(.5) && snd('triangle').chord(60,64,67,72).invert([1,-3,4,-5].pick()).adsr(0,.2).out()
 `,
-  true,
-)}  
+    true,
+  )}
 
-## Vibrato
-
-You can also add some amount of vibrato to the sound using the <ic>vib</ic> and <ic>vibmod</ic> methods. These can turn any oscillator into something more lively and/or into a sound effect when used with a high amount of modulation.
-
-${makeExample(
-  "Different vibrato settings",
-  `
-tempo(140);
-beat(1) :: sound('triangle')
-  .freq(400).release(0.2)
-  .vib([1/2, 1, 2, 4].beat())
-  .vibmod([1,2,4,8].beat(2))
-  .out()`,
-  true,
-)}
-
-## Noise
-
-A certain amount of brown noise can be added by using the <ic>.noise</ic> key:
-
-${makeExample(
-  "Different vibrato settings",
-  `
-tempo(140);
-beat(1) :: sound('triangle')
-  .freq(400).release(0.2)
-  .noise([0.2,0.4,0.5].bar())
-  .vib([1/2, 1, 2, 4].beat())
-  .vibmod([1,2,4,8].beat(2))
-  .out()`,
-  true,
-)}
-
-
-## Controlling the amplitude
+# Controlling amplitude
 
 Controlling the amplitude and duration of the sound can be done using various techniques. The most important thing to learn is probably how set the amplitude (volume) of your synthesizer:
 - <ic>gain(gain: number)</ic>: sets the gain of the oscillator.
 - <ic>velocity(velocity: number)</ic>: sets the velocity of the oscillator (velocity is a multiple of gain).
 
 ${makeExample(
-  "Setting the gain",
-  `beat(0.25) :: sound('sawtooth').gain([0.0, 1/8, 1/4, 1/2, 1].beat(0.5)).out()`,
-  true,
-)}
+    "Setting the gain",
+    `beat(0.25) :: sound('sawtooth').gain([0.0, 1/8, 1/4, 1/2, 1].beat(0.5)).out()`,
+    true,
+  )}
 
 ${makeExample(
-  "Setting the velocity",
-  `beat(0.25) :: sound('sawtooth').velocity([0.0, 1/8, 1/4, 1/2, 1].beat(0.5)).out()`,
-  true,
-)}
+    "Setting the velocity",
+    `beat(0.25) :: sound('sawtooth').velocity([0.0, 1/8, 1/4, 1/2, 1].beat(0.5)).out()`,
+    true,
+  )}
+
+## Envelopes
 
 <div class="mt-4 mb-4 lg:grid lg:grid-cols-4 lg:gap-4">
   <img class="col-span-1 lg:ml-12 bg-gray-100 rounded-lg px-2 py-2", src="https://upload.wikimedia.org/wikipedia/commons/thumb/e/ef/ADSR_Envelope_Graph.svg/1280px-ADSR_Envelope_Graph.svg.png" width="400" />
@@ -134,143 +103,83 @@ ${makeExample(
 - <ic>release(release: number)</ic> / <ic>rel(rel: number)</ic>: sets the release time of the envelope.
 
 ${makeExample(
-  "Using decay and sustain to set the ADSR envelope",
-  `
+    "Using decay and sustain to set the ADSR envelope",
+    `
 beat(0.5) :: sound('wt_piano')
   .cutoff(1000 + usine() * 4000)
   .freq(100).decay(.2)
   .sustain([0.1,0.5].beat(4))
   .out()`,
-  true,
-)}
+    true,
+  )}
 
 This ADSR envelope design is important to know because it is used for other aspects of the synthesis engine such as the filters that we are now going to talk about. But wait, I've kept the best for the end. The <ic>adsr()</ic> combines all the parameters together. It is a shortcut for setting the ADSR envelope:
 
 - <ic>adsr(attack: number, decay: number, sustain: number, release: number)</ic>: sets the ADSR envelope.
 
 ${makeExample(
-  "Replacing the previous example with the adsr() method",
-  `
+    "Replacing the previous example with the adsr() method",
+    `
 beat(0.5) :: sound('wt_piano')
   .cutoff(1000 + usine() * 4000)
   .freq(100)
   .adsr(0, .2, [0.1,0.5].beat(4), 0)
   .out()
 `,
-  true,
-)}
+    true,
+  )}
 
 - <ic>ad(attack: number, decay: number)</ic>: sets the attack and decay phases, setting sustain and release to <ic>0</ic>.
 
 ${makeExample(
-  "Two segment envelope",
-  `
+    "Two segment envelope",
+    `
 beat(0.5) :: sound('wt_piano')
   .cutoff(1000 + usine() * 4000)
   .freq(100)
   .ad(0, .2)
   .out()
 `,
-  true,
-)}
+    true,
+  )}
 
 ## Substractive synthesis using filters
 
 The most basic synthesis technique used since the 1970s is called substractive synthesis. This technique is based on the use of rich sound sources (oscillators) as a base to build rich and moving timbres. Because rich sources contain a lot of different harmonics, you might want to filter some of them to obtain the timbre you are looking for. To do so, Topos comes with a set of basic filters that can be used to shape the sound exactly to your liking. There are three filter types by defaut, with more to be added in the future:
 
-- **lowpass filter**: filters the high frequencies, keeping the low frequencies.
-- **highpass filter**: filtering the low frequencies, keeping the high frequencies.
-- **bandpass filter**: filters the low and high frequencies around a frequency band, keeping what's in the middle.
+See the Filters page for details on lowpass, highpass and bandpass filters. I also encourage you to study these simple examples to get more familiar with the construction of basic substractive synthesizers:
 
 ${makeExample(
-  "Filtering the high frequencies of an oscillator",
-  `beat(.5) :: sound('sawtooth').cutoff(50 + usine(1/8) * 2000).out()`,
-  true,
-)}
-
-These filters all come with their own set of parameters. Note that we are describing the parameters of the three different filter types here. Choose the right parameters depending on the filter type you are using:
-
-
-### Lowpass filter
-
-| Method     | Alias     | Description                     |
-|------------|-----------|---------------------------------|
-| <ic>cutoff</ic>     | <ic>lpf</ic>       | cutoff frequency of the lowpass filter |
-| <ic>resonance</ic>  | <ic>lpq</ic>       | resonance of the lowpass filter (0-1) |
+    "Filtering the high frequencies of an oscillator",
+    `beat(.5) :: sound('sawtooth').cutoff(50 + usine(1/8) * 2000).out()`,
+    true,
+  )}
 
 ${makeExample(
-  "Filtering a bass",
-  `beat(.5) :: sound('jvbass').lpf([250,1000,8000].beat()).out()`,
-  true,
-)}
-
-### Highpass filter
-
-| Method     | Alias     | Description                     |
-|------------|-----------|---------------------------------|
-| <ic>hcutoff</ic>     | <ic>hpf</ic>       | cutoff frequency of the highpass filter |
-| <ic>hresonance</ic>  | <ic>hpq</ic>       | resonance of the highpass filter (0-1) |
-
-${makeExample(
-  "Filtering a noise source",
-  `beat(.5) :: sound('gtr').hpf([250,1000, 2000, 3000, 4000].beat()).end(0.5).out()`,
-  true,
-)}
-
-### Bandpass filter
-
-| Method     | Alias     | Description                     |
-|------------|-----------|---------------------------------|
-| <ic>bandf</ic>      | <ic>bpf</ic>       | cutoff frequency of the bandpass filter |
-| <ic>bandq</ic>      | <ic>bpq</ic>       | resonance of the bandpass filter (0-1) |
-
-${makeExample(
-  "Sweeping the filter on the same guitar sample",
-  `beat(.5) :: sound('gtr').bandf(100 + usine(1/8) * 4000).end(0.5).out()`,
-  true,
-)}
-
-Alternatively, <ic>lpf</ic>, <ic>hpf</ic> and <ic>bpf</ic> can take a second argument, the **resonance**.
-
-## Filter order (type)
-
-You can also use the <ic>ftype</ic> method to change the filter type (order). There are two types by default, <ic>12db</ic> for a gentle slope or <ic>24db</ic> for a really steep filtering slope. The <ic>24db</ic> type is particularly useful for substractive synthesis if you are trying to emulate some of the Moog or Prophet sounds:
-
-- <ic>ftype(type: string)</ic>: sets the filter type (order), either <ic>12db</ic> or <ic>24db</ic>.
-
-${makeExample(
-  "Filtering a bass",
-  `beat(.5) :: sound('jvbass').ftype(['12db', '24db'].beat(4)).lpf([250,1000,8000].beat()).out()`,
-  true,
-)}
-
-I also encourage you to study these simple examples to get more familiar with the construction of basic substractive synthesizers:
-
-${makeExample(
-  "Simple synthesizer voice with filter",
-  `
+    "Simple synthesizer voice with filter",
+    `
 beat(.5) && snd('sawtooth')
   .cutoff([2000,500].pick() + usine(.5) * 4000)
   .resonance(0.2).freq([100,150].pick())
   .out()
 	`,
-  true,
-)}
+    true,
+  )}
 
 ${makeExample(
-  "Blessed by the square wave",
-  `
+    "Blessed by the square wave",
+    `
 beat(4) :: [100,101].forEach((freq) => sound('square').freq(freq).sustain(0.1).out())
 beat(.5) :: [100,101].forEach((freq) => sound('square').freq(freq*2).sustain(0.01).out())
 beat([.5, .75, 2].beat()) :: [100,101].forEach((freq) => sound('square')
   .freq(freq*4 + usquare(2) * 200).sustain(0.125).out())
 beat(.25) :: sound('square').freq(100*[1,2,4,8].beat()).sustain(0.1).out()`,
-  false,
-)}
+    false,
+  )}
 
 ${makeExample(
-  "Ghost carillon (move your mouse!)",
-  `
+    "Ghost carillon (move your mouse!)",
+    `
 beat(1/8)::sound('sine')
   .velocity(rand(0.0, 1.0))
   .delay(0.75).delayt(.5)
@@ -279,83 +188,33 @@ beat(1/8)::sound('sine')
   .freq(mouseX())
 	.gain(0.25)
   .out()`,
-  false,
-)}
+    false,
+  )}
 
-## Filter envelopes
-
-The examples we have studied so far are static. They filter the sound around a fixed cutoff frequency. To make the sound more interesting, you can use the ADSR filter envelopes to shape the filter cutoff frequency over time. You will always find amplitude and filter envelopes on most commercial synthesizers. This is done using the following methods:
-
-### Lowpass envelope
-
-| Method     | Alias     | Description                     |
-|------------|-----------|---------------------------------|
-| <ic>lpenv</ic>      | <ic>lpe</ic>       | lowpass frequency modulation amount (negative or positive) |
-| <ic>lpattack</ic>   | <ic>lpa</ic>       | attack of the lowpass filter    |
-| <ic>lpdecay</ic>    | <ic>lpd</ic>       | decay of the lowpass filter     |
-| <ic>lpsustain</ic>  | <ic>lps</ic>       | sustain of the lowpass filter   |
-| <ic>lprelease</ic>  | <ic>lpr</ic>       | release of the lowpass filter   |
-| <ic>lpadsr</ic>     |                    | (**takes five arguments**) set all the parameters  |
+## Noise
 
+A certain amount of brown noise can be added by using the <ic>.noise</ic> key:
 
 ${makeExample(
-  "Filtering a sawtooth wave dynamically",
-  `beat(.5) :: sound('sawtooth').note([48,60].beat())
-  .cutoff(5000).lpa([0.05, 0.25, 0.5].beat(2))
-  .lpenv(-8).lpq(10).out()`,
-  true,
-)}
-
-### Highpass envelope
-
-| Method     | Alias     | Description                     |
-|------------|-----------|---------------------------------|
-| <ic>hpenv</ic>      | <ic>hpe</ic>       | highpass frequency modulation amount (negative or positive) |
-| <ic>hpattack</ic>   | <ic>hpa</ic>       | attack of the highpass filter    |
-| <ic>hpdecay</ic>    | <ic>hpd</ic>       | decay of the highpass filter     |
-| <ic>hpsustain</ic>  | <ic>hps</ic>       | sustain of the highpass filter   |
-| <ic>hprelease</ic>  | <ic>hpr</ic>       | release of the highpass filter   |
-| <ic>hpadsr</ic>     |           | (**takes five arguments**) set all the parameters  |
-
-
-${makeExample(
-  "Let's use another filter using the same example",
-  `beat(.5) :: sound('sawtooth').note([48,60].beat())
-  .hcutoff(1000).hpa([0.05, 0.25, 0.5].beat(2))
-  .hpenv(8).hpq(10).out()`,
-  true,
-)}
-
-### Bandpass envelope
-
-| Method     | Alias     | Description                     |
-|------------|-----------|---------------------------------|
-| <ic>bpenv</ic>      | <ic>bpe</ic>       | bandpass frequency modulation amount (negative or positive) |
-| <ic>bpattack</ic>   | <ic>bpa</ic>       | attack of the bandpass filter    |
-| <ic>bpdecay</ic>    | <ic>bpd</ic>       | decay of the bandpass filter     |
-| <ic>bpsustain</ic>  | <ic>bps</ic>       | sustain of the bandpass filter   |
-| <ic>bprelease</ic>  | <ic>bpr</ic>       | release of the bandpass filter   |
-| <ic>bpadsr</ic>     |           | (**takes five arguments**) set all the parameters  |
-
-
-${makeExample(
-  "And the bandpass filter, just for fun",
-  `beat(.5) :: sound('sawtooth').note([48,60].beat())
-  .bandf([500,1000,2000].beat(2))
-  .bpa([0.25, 0.125, 0.5].beat(2) * 4)
-  .bpenv(-4).release(2).out()
-  `,
-  true,
-)}
-
+    "Different vibrato settings",
+    `
+tempo(140);
+beat(1) :: sound('triangle')
+  .freq(400).release(0.2)
+  .noise([0.2,0.4,0.5].bar())
+  .vib([1/2, 1, 2, 4].beat())
+  .vibmod([1,2,4,8].beat(2))
+  .out()`,
+    true,
+  )}
 
 ## Wavetable synthesis
 
 Topos can also do wavetable synthesis. Wavetable synthesis allows you to use any sound file as a source to build an oscillator. By default, Topos comes with more than 1000 waveforms thanks to the awesome [AKWF](https://www.adventurekid.se/akrt/waveforms/adventure-kid-waveforms/) pack made by Kristoffer Ekstrand. Any sample name that contains <ic>wt_</ic> as a prefix will be interpreted by the sampler as a wavetable and thus as an oscillator. See for yourself:
 
 ${makeExample(
-  "Acidity test",
-  `
+    "Acidity test",
+    `
 beat(.25) :: sound('wt_symetric:8').note([50,55,57,60].beat(.25) - [12,0]
   .pick()).ftype('12db').adsr(0.05/4, 1/16, 0.25/4, 0)
   .cutoff(1500 + usine(1/8) * 5000).lpadsr(16, 0.2, 0.2, 0.125/2, 0)
@@ -363,15 +222,15 @@ beat(.25) :: sound('wt_symetric:8').note([50,55,57,60].beat(.25) - [12,0]
 beat(1) :: sound('kick').n(4).out()
 beat(2) :: sound('snare').out()
 beat(.5) :: sound('hh').out()`,
-  true,
-)}
+    true,
+  )}
 	
 
 Let's explore the galaxy of possible waveforms. It can be hard to explore them all, there is a **lot** of them:
 
 ${makeExample(
-  "Let's explore some wavetables",
-  `
+    "Let's explore some wavetables",
+    `
 // Exploring a vast galaxy of waveforms
 let collection = [
   'wt_sinharm', 'wt_linear', 'wt_bw_sawrounded',
@@ -381,8 +240,8 @@ beat(2) :: v('selec', irand(1, 100))
 beat(2) :: v('swave', collection.pick())
 beat(0.5) :: sound(v('swave')).n(v('selec')).out()
 `,
-  true,
-)}
+    true,
+  )}
 
 You can work with them just like with any other waveform. Having so many of them makes them also very useful for generating sound effects, percussive, sounds, etc...
 	
@@ -397,8 +256,8 @@ Another really useful technique to know about is FM synthesis, FM standing for _
 There is also an additional parameter, <ic>fm</ic> that combines <ic>fmi</ic> and <ic>fmh</ic> using strings: <ic>fm('2:4')</ic>. Think of it as a static shortcut for getting some timbres more quickly.
 
 ${makeExample(
-  "80s nostalgia",
-  `
+    "80s nostalgia",
+    `
 beat([.5, 1].beat(8)) && snd('triangle').adsr(0.02, 0.5, 0.5, 0.25)
   .fmi(2).fmh(1.5).note([60,55, 60, 63].beat() - 12)
   .pan(noise()).out()
@@ -407,23 +266,23 @@ beat(.25) && snd('triangle').adsr(0.02, 0.1, 0.1, 0.1)
   .pan(noise()).note([60,55, 60, 63].beat() + [0, 7].pick()).out()
 beat(2) :: sound('cp').room(1).sz(1).out()
 	`,
-  true,
-)}
+    true,
+  )}
 
 ${makeExample(
-  "Giving some love to ugly inharmonic sounds",
-  `
+    "Giving some love to ugly inharmonic sounds",
+    `
 beat([.5, .25].bar()) :: sound('sine').fm('2.2183:3.18293').sustain(0.05).out()
 beat([4].bar()) :: sound('sine').fm('5.2183:4.5').sustain(0.05).out()
 beat(.5) :: sound('sine')
   .fmh([1, 1.75].beat())
   .fmi($(1) % 30).orbit(2).room(0.5).out()`,
-  true,
-)}
+    true,
+  )}
 
 ${makeExample(
-  "Peace and serenity through FM synthesis",
-  `
+    "Peace and serenity through FM synthesis",
+    `
 beat(0.25) :: sound('sine')
   .note([60, 67, 70, 72, 77].beat() - [0,12].bar())
   .attack(0.2).release(0.5).gain(0.25)
@@ -432,8 +291,8 @@ beat(0.25) :: sound('sine')
   .cutoff(1500).delay(0.5).delayt(0.125)
   .delayfb(0.8).fmh(Math.floor(usine(.5) * 4))
   .out()`,
-  true,
-)}
+    true,
+  )}
 
 **Note:** you can also set the _modulation index_ and the _harmonic ratio_ with the <ic>fm</ic> argument. You will have to feed both as a string: <ic>fm('2:4')</ic>. If you only feed one number, only the _modulation index_ will be updated.
 
@@ -444,8 +303,8 @@ There is also a more advanced set of parameters you can use to control the envel
 - <ic>fmrelease</ic> / <ic>fmrel</ic>: release time of the modulator envelope.
 
 ${makeExample(
-  "FM Synthesis with envelope control",
-  `
+    "FM Synthesis with envelope control",
+    `
 beat(.5) :: sound('sine')
   .note([50,53,55,57].beat(.5) - 12)
   .fmi(0.5 + usine(.25) * 1.5)
@@ -453,8 +312,8 @@ beat(.5) :: sound('sine')
   .fmwave('triangle')
   .fmsus(0).fmdec(0.2).out()
   `,
-  true,
-)}
+    true,
+  )}
 
 ## ZzFX
 
@@ -463,15 +322,15 @@ beat(.5) :: sound('sine')
 ZZfX can be triggered by picking a default ZZfX waveform in the following list: <ic>z_sine</ic>, <ic>z_triangle</ic>, <ic>z_sawtooth</ic>, <ic>z_tan</ic>, <ic>z_noise</ic>.
 
 ${makeExample(
-  "Picking a waveform",
-  `
+    "Picking a waveform",
+    `
 beat(.5) :: sound(['z_sine', 'z_triangle', 'z_sawtooth', 'z_tan', 'z_noise'].beat()).out()
 `,
-  true,
-)}
+    true,
+  )}
 ${makeExample(
-  "Minimalist chiptune",
-  `
+    "Minimalist chiptune",
+    `
 beat(.5) :: sound('z_triangle')
   .note([60, 67, 72, 63, 65, 70].beat(.5))
   .zrand(0).curve([1,2,3,4].beat(1))
@@ -481,8 +340,8 @@ beat(.5) :: sound('z_triangle')
   .room(0.5).size(0.9)
   .pitchJumpTime(0.01).out() 
 `,
-  true,
-)}
+    true,
+  )}
 
 It comes with a set of parameters that can be used to tweak the sound. Don't underestimate this synth! It is very powerful for generating anything ranging from chaotic noise sources to lush pads:
 
@@ -508,8 +367,8 @@ It comes with a set of parameters that can be used to tweak the sound. Don't und
 |<ic>duration</ic>|| Total sound duration (overrides envelope) |
 
 ${makeExample(
-  "Chaotic Noise source",
-  `
+    "Chaotic Noise source",
+    `
 beat(.25) :: sound('z_tan')
   .note(40).noise(rand(0.0, 1.0))
   .pitchJump(84).pitchJumpTime(rand(0.0, 1.0))
@@ -519,21 +378,21 @@ beat(.25) :: sound('z_tan')
   .sustain(0).decay([0.2, 0.1].pick())
   .out() 
 `,
-  true,
-)}
+    true,
+  )}
 ${makeExample(
-  "What is happening to me?",
-  `
+    "What is happening to me?",
+    `
 beat(1) :: snd('zzfx').zzfx([
   [4.77,,25,,.15,.2,3,.21,,2.4,,,,,,,.23,.35],
   [1.12,,97,.11,.16,.01,4,.77,,,30,.17,,,-1.9,,.01,.67,.2]
   ].beat()).out()
 `,
-  false,
-)}
+    false,
+  )}
 ${makeExample(
-  "Les voitures dans le futur",
-  `
+    "Les voitures dans le futur",
+    `
 beat(1) :: sound(['z_triangle', 'z_sine'].pick())
   .note([60,63,72,75].pick()).tremolo(16)
   .zmod([0, 1/2, 1/8].div(2).pick())
@@ -541,23 +400,25 @@ beat(1) :: sound(['z_triangle', 'z_sine'].pick())
   .room(0.9).size(0.9)
   .delayt(0.75).delayfb(0.5).out()
 `,
-  false,
-)}
+    false,
+  )}
 
 Note that you can also design sounds [on this website](https://killedbyapixel.github.io/ZzFX/) and copy the generated code in Topos. To do so, please use the <ic>zzfx</ic> method with the generated array:
 ${makeExample(
-  "Designing a sound on the ZzFX website",
-  `
+    "Designing a sound on the ZzFX website",
+    `
  
 beat(2) :: sound('zzfx').zzfx([3.62,,452,.16,.1,.21,,2.5,,,403,.05,.29,,,,.17,.34,.22,.68]).out()
 `,
-  true,
-)}
+    true,
+  )}
 
 # Speech synthesis
 
 Topos can also speak using the [Web Speech API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Speech_API). There are two ways to use speech synthesis:
 
+Speech synthesis API can crash your browser if you use it too much. To avoid crashing the calls should be limited using methods like beat() or run it only once using once().
+
 - <ic>speak(text: string, lang: string, voice: number, rate: number, pitch: number, volume: number)</ic>
   - <ic>text</ic>: the text you would like to synthesize (_e.g_ <ic>"Wow, Topos can speak!"</ic>).
   - <ic>lang</ic>: language code, for example <ic>en</ic> for English, <ic>fr</ic> for French or with the country code for example British English <ic>en-GB</ic>. See supported values from the [list](https://cloud.google.com/speech-to-text/docs/speech-to-text-supported-languages).
@@ -567,48 +428,48 @@ Topos can also speak using the [Web Speech API](https://developer.mozilla.org/en
   - <ic>volume(number)</ic>: speaking volume, from <ic>0.0</ic> to <ic>1.0</ic>.
 
 ${makeExample(
-  "Hello world!",
-  `
-beat(4) :: speak("Hello world!")
+    "Hello world!",
+    `
+once() && speak("Hello world!")
   `,
-  true,
-)}
+    true,
+  )}
 
 ${makeExample(
-  "Let's hear people talking about Topos",
-  `
-beat(2) :: speak("Topos!","fr",irand(0,5))
+    "Let's hear people talking about Topos",
+    `
+beat(2) && speak("Topos!","fr",irand(0,5))
   `,
-  true,
-)}
+    true,
+  )}
 
 
 You can also use speech by chaining methods to a string:
 
 ${makeExample(
-  "Foobaba is the real deal",
-  `
-  onbeat(4) :: "Foobaba".voice(irand(0,10)).speak()
+    "Foobaba is the real deal",
+    `
+  onbeat(4) && "Foobaba".voice(irand(0,10)).speak()
   `,
-  true,
-)}
+    true,
+  )}
 
 ${makeExample(
-  "Building string and chaining",
-  `
+    "Building string and chaining",
+    `
   const subject = ["coder","user","loser"].pick()
   const verb = ["is", "was", "isnt"].pick()
   const object = ["happy","sad","tired"].pick()
   const sentence = subject+" "+verb+" "+" "+object
     
-  beat(6) :: sentence.pitch(0).rate(0).voice([0,2].pick()).speak()
+  beat(6) && sentence.pitch(0).rate(0).voice([0,2].pick()).speak()
   `,
-  true,
-)}
+    true,
+  )}
 
 ${makeExample(
-  "Live coded poetry with array and string chaining",
-  `
+    "Live coded poetry with array and string chaining",
+    `
   tempo(70)
 
   const croissant = [
@@ -617,13 +478,13 @@ ${makeExample(
     "Flamboyant", "Cosmique", "Croissant!"
   ];
   
-  onbeat(4) :: croissant.bar()
+  onbeat(4) && croissant.bar()
       .lang("fr")
       .volume(rand(0.2,2.0))
       .rate(rand(.4,.6))
       .speak();
   `,
-  true,
-)}
+    true,
+  )}
 `;
 };

src/documentation/learning/midi.ts

@@ -1,5 +1,5 @@
-import { type Editor } from "../main";
-import { makeExampleFactory, key_shortcut } from "../Documentation";
+import { type Editor } from "../../main";
+import { makeExampleFactory, key_shortcut } from "../../Documentation";
 
 export const midi = (application: Editor): string => {
   const makeExample = makeExampleFactory(application);

src/documentation/learning/osc.ts

@@ -0,0 +1,75 @@
+import { type Editor } from "../../main";
+import { makeExampleFactory } from "../../Documentation";
+
+export const osc = (application: Editor): string => {
+  // @ts-ignore
+  const makeExample = makeExampleFactory(application);
+  return `
+# Open Sound Control
+
+Topos is a sandboxed web application. It cannot speak with your computer directly or only through a secure connexion. You can use the [Open Sound Control](https://en.wikipedia.org/wiki/Open_Sound_Control) protocol to send and receive data from your computer. This protocol is used by many softwares and hardware devices. You can use it to control your favorite DAW, your favorite synthesizer, your favorite robot, or anything really! To use **OSC** with Topos, you will need to download the <ic>ToposServer</ic> by [following this link](https://github.com/Bubobubobubobubo/Topos). You can download everything as a zip file or clone the project if you know what you are doing. Here is a quick guide to get you started:
+
+- 1) Download <ic>Topos</ic> and navigate to the <ic>ToposServer</ic> folder.
+- 2) Install the dependencies using <ic>npm install</ic>. Start the server using <ic>npm start</ic>.
+- 3) Open the <ic>Topos</ic> application in your web browser (server first, then application).
+
+The <ic>ToposServer</ic> server is used both for **OSC** _input_ and _output_.
+
+## Input
+
+Send an **OSC** message to the server from another application or device at the address <ic>localhost:30000</ic>. Topos will store the last 1000 messages in a queue. You can access this queue using the <ic>getOsc()</ic> function.
+
+### Unfiltered messages
+
+You can access the last 1000 messages using the <ic>getOsc()</ic> function without any argument. This is raw data, you will need to parse it yourself:
+
+${makeExample(
+  "Reading the last OSC messages",
+  `
+beat(1)::getOsc()
+// 0 : {data: Array(2), address: '/lala'}
+// 1 : {data: Array(2), address: '/lala'}
+// 2 : {data: Array(2), address: '/lala'}`,
+  true,
+)}
+
+### Filtered messages
+
+The <ic>getOsc()</ic> can receive an address filter as an argument. This will return only the messages that match the filter:
+
+${makeExample(
+  "Reading the last OSC messages (filtered)",
+  `
+beat(1)::getOsc("/lala")
+// 0 : (2) [89, 'bob']
+// 1 : (2) [84, 'bob']
+// 2 : (2) [82, 'bob']
+         `,
+  true,
+)}
+
+## Output
+
+Once the server is loaded, you are ready to send an **OSC** message:
+
+${makeExample(
+  "Sending a simple OSC message",
+  `
+beat(1)::sound('cp').speed(2).vel(0.5).osc()
+    `,
+  true,
+)}
+
+This is a simple **OSC** message that will inherit all the properties of the sound. You can also send customized OSC messages using the <ic>osc()</ic> function:
+
+${makeExample(
+  "Sending a customized OSC message",
+  `
+// osc(address, port, ...message)
+osc('/my/osc/address', 5000, 1, 2, 3)
+    `,
+  true,
+)}
+
+`;
+};

src/documentation/learning/samples/loading_samples.ts

@@ -1,5 +1,5 @@
-import { type Editor } from "../../main";
-import { makeExampleFactory } from "../../Documentation";
+import { type Editor } from "../../../main";
+import { makeExampleFactory } from "../../../Documentation";
 
 export const loading_samples = (application: Editor): string => {
   // @ts-ignore

src/documentation/learning/samples/sample_banks.ts

@@ -1,5 +1,5 @@
-import { type Editor } from "../../main";
-import { makeExampleFactory } from "../../Documentation";
+import { type Editor } from "../../../main";
+import { makeExampleFactory } from "../../../Documentation";
 
 export const sample_banks = (application: Editor): string => {
   // @ts-ignore

src/documentation/learning/samples/sample_list.ts

@@ -1,5 +1,5 @@
-import { type Editor } from "../../main";
-import { makeExampleFactory } from "../../Documentation";
+import { type Editor } from "../../../main";
+import { makeExampleFactory } from "../../../Documentation";
 
 export const samples_to_markdown = (
   application: Editor,
@@ -32,7 +32,7 @@ export const samples_to_markdown = (
 
     markdownList += `
 <button 
-	class="hover:bg-neutral-500 inline px-4 py-2 bg-neutral-700 text-orange-300 text-xl"
+	class="hover:bg-foreground inline px-4 py-2 bg-black text-brightwhite hover:text-background text-xl"
 	onclick="app.api._playDocExampleOnce(app.api.codeExamples['${codeId}'])"
 >
 ${keys[i]}
@@ -65,44 +65,80 @@ On this page, you will find an exhaustive list of all the samples currently load
 A very large collection of wavetables for wavetable synthesis. This collection has been released by Kristoffer Ekstrand: [AKWF Waveforms](https://www.adventurekid.se/akrt/waveforms/adventure-kid-waveforms/). Every sound sample that starts with <ic>wt_</ic> will be looped. Look at this demo:
 
 ${makeExample(
-  "Wavetable synthesis made easy :)",
-  `
+    "Wavetable synthesis made easy :)",
+    `
 beat(0.5)::sound('wt_stereo').n([0, 1].pick()).ad(0, .25).out()
 `,
-  true,
-)}
+    true,
+  )}
 
 
 Pick one folder and spend some time exploring it. There is a lot of different waveforms.
 
-<div class="lg:pl-6 lg:pr-6 w-fit rounded-lg bg-neutral-600 mx-6 mt-2 my-6 px-2 py-2 max-h-96 flex flex-row flex-wrap gap-x-2 gap-y-2 overflow-y-scroll">
+<div class="lg:pl-6 lg:pr-6 w-fit rounded-lg bg-background mx-6 mt-2 my-6 px-2 py-2 max-h-96 flex flex-row flex-wrap gap-x-2 gap-y-2 overflow-y-scroll">
 ${samples_to_markdown(application, "Waveforms")}
 </div>
 
 ## Drum machines sample pack
 
-A set of 72 classic drum machines created by **Geikha**: [Geikha Drum Machines](https://github.com/geikha/tidal-drum-machines). To use them efficiently, it is best to use the <ic>.bank()</ic> parameter like so:
+A set of 72 classic drum machines created by **Geikha**: [Geikha Drum Machines](https://github.com/geikha/tidal-drum-machines). To use them efficiently, it is best 
+to use the <ic>.bank()</ic> parameter like so:
 
 ${makeExample(
-  "Using a classic drum machine",
-  `
+    "Using a classic drum machine",
+    `
 beat(0.5)::sound(['bd', 'cp'].pick()).bank("AkaiLinn").out()
 `,
-  true,
-)}
+    true,
+  )}
 
 Here is the complete list of available machines:
 
 
-<div class="lg:pl-6 lg:pr-6 w-fit rounded-lg bg-neutral-600 mx-6 mt-2 my-6 px-2 py-2 max-h-96 flex flex-row flex-wrap gap-x-2 gap-y-2 overflow-y-scroll">
+<div class="lg:pl-6 lg:pr-6 w-fit rounded-lg bg-background mx-6 mt-2 my-6 px-2 py-2 max-h-96 flex flex-row flex-wrap gap-x-2 gap-y-2 overflow-y-scroll">
 ${samples_to_markdown(application, "Machines")}
 </div>
 
+In practice, using them will lead you to write short two letters long sample names, each one for a different piece of the kit:
+
+| Kit Piece | Short name     |
+|-----------|----------------|
+|
+| **Bass/kick drum** | <ic>bd</ic> |
+| **Snare drum**     | <ic>sd</ic> |
+| **Rimshot** | <ic>rim</ic> |
+| **Clap** | <ic>cp</ic> |
+| **Closed hi-hat** | <ic>hh</ic> |
+| **Open hi-hat** | <ic>oh</ic> |
+| **Crash** | <ic>cr</ic> |
+| **Ride** | <ic>rd</ic> |
+| **Shakers (and maracas, cabasas, etc)** | <ic>sh</ic> |
+| **High tom** | <ic>ht</ic> |
+| **Medium tom** | <ic>mt</ic> |
+| **Low tom** | <ic>lt</ic> |
+| **Cowbell** | <ic>cb</ic> |
+| **Tambourine** | <ic>tb</ic> |
+| **Other percussions** | <ic>perc</ic> |
+| **Miscellaneous samples** | <ic>misc</ic> |
+| **Effects** | <ic>fx</ic> |
+
+Note that there is also a <ic>drumMachine</ic> function that allows you to play a random drum machine without even typing the name.
+It takes a single argument, a number, that will pick a machine for you in the list:
+
+${makeExample(
+    "Using a classic drum machine",
+    `
+beat(1/2)::sound(['bd', 'cp'].pick()).drumMachine(1).out()
+`,
+    true,
+  )}
+
+
 ## FoxDot sample pack
 
 The default sample pack used by Ryan Kirkbride's [FoxDot](https://github.com/Qirky/FoxDot). It is a nice curated sample pack that covers all the basic sounds you could want.
 
-<div class="lg:pl-6 lg:pr-6 w-fit rounded-lg bg-neutral-600 mx-6 mt-2 my-6 px-2 py-2 max-h-96 flex flex-row flex-wrap gap-x-2 gap-y-2 overflow-y-scroll">
+<div class="lg:pl-6 lg:pr-6 w-fit rounded-lg bg-background mx-6 mt-2 my-6 px-2 py-2 max-h-96 flex flex-row flex-wrap gap-x-2 gap-y-2 overflow-y-scroll">
 ${samples_to_markdown(application, "FoxDot")}
 </div>
 
@@ -110,7 +146,7 @@ ${samples_to_markdown(application, "FoxDot")}
 
 This set of audio samples is taken from [this wonderful collection](https://archive.org/details/AmigaSoundtrackerSamplePacksst-xx) of **Ultimate Tracker Amiga samples**. They were initially made by Karsten Obarski. These files were processed: pitched down one octave, gain down 6db. The audio has been processed with [SoX](https://github.com/chirlu/sox). The script used to do so is also included in this repository.
 
-<div class="lg:pl-6 lg:pr-6 w-fit rounded-lg bg-neutral-600 mx-6 mt-2 my-6 px-2 py-2 max-h-96 flex flex-row flex-wrap gap-x-2 gap-y-2 overflow-y-scroll">
+<div class="lg:pl-6 lg:pr-6 w-fit rounded-lg bg-background mx-6 mt-2 my-6 px-2 py-2 max-h-96 flex flex-row flex-wrap gap-x-2 gap-y-2 overflow-y-scroll">
 ${samples_to_markdown(application, "Amiga")}
 </div>
 
@@ -119,16 +155,16 @@ ${samples_to_markdown(application, "Amiga")}
 A collection of many different amen breaks. Use <ic>.stretch()</ic> to play with these:
 
 ${makeExample(
-  "Stretching an amen break",
-  `
+    "Stretching an amen break",
+    `
 beat(4)::sound('amen1').stretch(4).out()
 `,
-  true,
-)}
+    true,
+  )}
 
 The stretch should be adapted based on the length of each amen break.
 
-<div class="lg:pl-6 lg:pr-6 w-fit rounded-lg bg-neutral-600 mx-6 mt-2 my-6 px-2 py-2 max-h-96 flex flex-row flex-wrap gap-x-2 gap-y-2 overflow-y-scroll">
+<div class="lg:pl-6 lg:pr-6 w-fit rounded-lg bg-background mx-6 mt-2 my-6 px-2 py-2 max-h-96 flex flex-row flex-wrap gap-x-2 gap-y-2 overflow-y-scroll">
 ${samples_to_markdown(application, "Amen")}
 </div>
 
@@ -137,7 +173,7 @@ ${samples_to_markdown(application, "Amen")}
 Many live coders are expecting to find the Tidal sample library wherever they go, so here it is :)
 
 
-<div class="lg:pl-6 lg:pr-6 w-fit rounded-lg bg-neutral-600 mx-6 mt-2 my-6 px-2 py-2 max-h-96 flex flex-row flex-wrap gap-x-2 gap-y-2 overflow-y-scroll">
+<div class="lg:pl-6 lg:pr-6 w-fit rounded-lg bg-background mx-6 mt-2 my-6 px-2 py-2 max-h-96 flex flex-row flex-wrap gap-x-2 gap-y-2 overflow-y-scroll">
 ${samples_to_markdown(application, "Tidal")}
 </div>
 
@@ -145,8 +181,16 @@ ${samples_to_markdown(application, "Tidal")}
 
 This sample pack is only one folder full of french phonems! It sounds super nice.
 
-<div class="lg:pl-6 lg:pr-6 w-fit rounded-lg bg-neutral-600 mx-6 mt-2 my-6 px-2 py-2 max-h-96 flex flex-row flex-wrap gap-x-2 gap-y-2 overflow-y-scroll">
+<div class="lg:pl-6 lg:pr-6 w-fit rounded-lg bg-background mx-6 mt-2 my-6 px-2 py-2 max-h-96 flex flex-row flex-wrap gap-x-2 gap-y-2 overflow-y-scroll">
 ${samples_to_markdown(application, "Juliette")}
 </div>
+
+## Your samples
+
+These samples are the one you have loaded for the duration of the session using the <ic>Import Samples</ic> button in the configuration menu.
+
+<div class="lg:pl-6 lg:pr-6 w-fit rounded-lg bg-background mx-6 mt-2 my-6 px-2 py-2 max-h-96 flex flex-row flex-wrap gap-x-2 gap-y-2 overflow-y-scroll">
+${samples_to_markdown(application, "user")}
+</div>
 `;
 };

src/documentation/learning/time/cyclical_time.ts

@@ -1,5 +1,5 @@
-import { type Editor } from "../../main";
-import { makeExampleFactory } from "../../Documentation";
+import { type Editor } from "../../../main";
+import { makeExampleFactory } from "../../../Documentation";
 
 export const cyclical_time = (app: Editor): string => {
   // @ts-ignore

src/documentation/learning/time/linear_time.ts

@@ -1,5 +1,5 @@
-import { type Editor } from "../../main";
-import { makeExampleFactory } from "../../Documentation";
+import { type Editor } from "../../../main";
+import { makeExampleFactory } from "../../../Documentation";
 import pulses from "./pulses.svg";
 
 export const linear_time = (app: Editor): string => {

src/documentation/learning/time/long_forms.ts

@@ -1,5 +1,5 @@
-import { type Editor } from "../main";
-import { makeExampleFactory } from "../Documentation";
+import { type Editor } from "../../../main";
+import { makeExampleFactory } from "../../../Documentation";
 
 export const long_forms = (app: Editor): string => {
   // @ts-ignore

src/documentation/learning/time/time.ts

@@ -1,5 +1,5 @@
-import { makeExampleFactory } from "../../Documentation";
-import { type Editor } from "../../main";
+import { makeExampleFactory } from "../../../Documentation";
+import { type Editor } from "../../../main";
 import times from "./times.svg";
 
 export const time = (application: Editor): string => {

src/documentation/lfos.ts

@@ -1,59 +0,0 @@
-import { type Editor } from "../main";
-import { makeExampleFactory } from "../Documentation";
-
-export const lfos = (application: Editor): string => {
-  const makeExample = makeExampleFactory(application);
-  return `
-# Low Frequency Oscillators
-
-Low Frequency Oscillators (_LFOs_) are an important piece in any digital audio workstation or synthesizer. Topos implements some basic waveforms you can play with to automatically modulate your paremeters. 
-	
-- <ic>sine(freq: number = 1, times: number = 1, offset: number= 0): number</ic>: returns a sinusoïdal oscillation between <ic>-1</ic> and <ic>1</ic>.
-  - <ic>freq</ic> : frequency in hertz.
-  - <ic>times</ic> : output value multiplier.
-  - <ic>offset</ic>: linear offset.
-- <ic>usine(freq: number = 1, times: number = 1, offset: number= 0): number</ic>: returns a sinusoïdal oscillation between <ic>0</ic> and <ic>1</ic>. The <ic>u</ic> stands for _unipolar_.
-	
-${makeExample(
-  "Modulating the speed of a sample player using a sine LFO",
-  `beat(.25) && snd('cp').speed(1 + usine(0.25) * 2).out()`,
-  true,
-)};
-
-- <ic>triangle(freq: number = 1, times: number = 1, offset: number= 0): number</ic>: returns a triangle oscillation between <ic>-1</ic> and <ic>1</ic>.
-- <ic>utriangle(freq: number = 1, times: number = 1, offset: number= 0): number</ic>: returns a triangle oscillation between <ic>0</ic> and <ic>1</ic>. The <ic>u</ic> stands for _unipolar_.
-
-${makeExample(
-  "Modulating the speed of a sample player using a triangle LFO",
-  `beat(.25) && snd('cp').speed(1 + utriangle(0.25) * 2).out()`,
-  true,
-)}
-	
-- <ic>saw(freq: number = 1, times: number = 1, offset: number= 0): number</ic>: returns a sawtooth-like oscillation between <ic>-1</ic> and <ic>1</ic>.
-- <ic>usaw(freq: number = 1, times: number = 1, offset: number= 0): number</ic>: returns a sawtooth-like oscillation between <ic>0</ic> and <ic>1</ic>. The <ic>u</ic> stands for _unipolar_.
-
-${makeExample(
-  "Modulating the speed of a sample player using a saw LFO",
-  `beat(.25) && snd('cp').speed(1 + usaw(0.25) * 2).out()`,
-  true,
-)}
-	
-- <ic>square(freq: number = 1, times: number = 1, offset: number= 0, duty: number = .5): number</ic>: returns a square wave oscillation between <ic>-1</ic> and <ic>1</ic>. You can also control the duty cycle using the <ic>duty</ic> parameter.
-- <ic>usquare(freq: number = 1, times: number = 1, offset: number= 0, duty: number = .5): number</ic>: returns a square wave oscillation between <ic>0</ic> and <ic>1</ic>. The <ic>u</ic> stands for _unipolar_. You can also control the duty cycle using the <ic>duty</ic> parameter.
-	
-${makeExample(
-  "Modulating the speed of a sample player using a square LFO",
-  `beat(.25) && snd('cp').speed(1 + usquare(0.25, 0, 0.25) * 2).out()`,
-  true,
-)};
-	
-- <ic>noise(times: number = 1)</ic>: returns a random value between -1 and 1.
-	
-${makeExample(
-  "Modulating the speed of a sample player using noise",
-  `beat(.25) && snd('cp').speed(1 + noise() * 2).out()`,
-  true,
-)};
-
-`;
-};

src/documentation/more/about.ts

@@ -14,6 +14,21 @@ Topos is an experimental web based algorithmic sequencer programmed by **BuboBub
 
 Topos is a free and open-source software distributed under [GPL-3.0](https://github.com/Bubobubobubobubo/Topos/blob/main/LICENSE) licence. We welcome all contributions and ideas. You can find the source code on [GitHub](https://github.com/Bubobubobubobubo/topos). You can also join us on [Discord](https://discord.gg/dnUTPbu6bN) to discuss about the project and live coding in general.
 	 
+## Support the project
+
+You can support the project by making a small donation on [Kofi](https://ko-fi.com/Manage/).
+
+<div style="display: flex; justify-content: center;">
+  <iframe
+    id='kofiframe'
+    src='https://ko-fi.com/raphaelbubo/?hidefeed=true&widget=true&embed=true&preview=true' 
+    style='border:none;width:40%;padding:4px;background:#f9f9f9;' 
+    height='590'
+    title='raphaelbubo'>
+  </iframe>
+</div>
+
+
 ## Credits
 
 - Felix Roos for the [SuperDough](https://www.npmjs.com/package/superdough) audio engine.

src/documentation/more/bonus.ts

@@ -9,6 +9,24 @@ export const bonus = (application: Editor): string => {
 
 Some features have been included as a bonus. These features are often about patterning over things that are not directly related to sound: pictures, video, etc.
 
+## Editor theme configuration
+
+The editor theme can be changed using the <ic>theme</ic> and <ic>randomTheme</ic> functions. The following example will use a random color scheme for every beat:
+
+${makeExample(
+  "Random theme on each beat",
+  `
+beat(1)::randomTheme()
+`, true)}
+
+You can also pick a theme using the <ic>theme</ic> function with a string as only argument:
+
+${makeExample(
+  "Picking a theme",
+  `
+beat(1)::theme("Batman")
+`, true)}
+
 ## Hydra Visual Live Coding
 
 <div class="mx-12 bg-neutral-600 rounded-lg flex flex-col items-center justify-center">

src/documentation/more/visualization.ts

@@ -0,0 +1,227 @@
+import { type Editor } from "../../main";
+import { key_shortcut, makeExampleFactory } from "../../Documentation";
+
+export const visualization = (application: Editor): string => {
+  const makeExample = makeExampleFactory(application);
+
+  return `
+# Vizualisation
+
+While Topos is mainly being developed as a live coding environment for algorithmic music composition, it also includes some features for live code visualizations. This section will introduce you to these features.
+
+## Hydra Visual Live Coding
+
+<div class="mx-12 bg-neutral-600 rounded-lg flex flex-col items-center justify-center">
+<warning>⚠️ This feature can generate flashing images that could trigger photosensitivity or epileptic seizures. ⚠️ </warning>
+</div>
+
+[Hydra](https://hydra.ojack.xyz/?sketch_id=mahalia_1) is a popular live-codable video synthesizer developed by [Olivia Jack](https://ojack.xyz/) and other contributors. It follows an analog synthesizer patching metaphor to encourage live coding complex shaders. Being very easy to use, extremely powerful and also very rewarding to use, Hydra has become a popular choice for adding visuals into a live code performance.
+
+${makeExample(
+  "Hydra integration",
+  `beat(4) :: hydra.osc(3, 0.5, 2).out()`,
+  false,
+)}
+
+Close the documentation to see the effect: ${key_shortcut(
+    "Ctrl+D",
+  )}! **Boom, all shiny!**
+
+Be careful not to call <ic>hydra</ic> too often as it can impact performances. You can use any rhythmical function like <ic>beat()</ic> function to limit the number of function calls. You can write any Topos code like <ic>[1,2,3].beat()</ic> to bring some life and movement in your Hydra sketches.
+
+Stopping **Hydra** is simple:
+
+${makeExample(
+  "Stopping Hydra",
+  `
+beat(4) :: stop_hydra()     // this one
+beat(4) :: hydra.hush() // or this one
+`,
+  false,
+)}
+
+### Changing the resolution
+
+You can change Hydra resolution using this simple method:
+
+${makeExample(
+  "Changing Hydra resolution",
+  `hydra.setResolution(1024, 768)`,
+  false,
+)}
+
+### Hydra documentation
+
+I won't teach Hydra. You can find some great resources directly on the [Hydra website](https://hydra.ojack.xyz/):
+  - [Hydra interactive documentation](https://hydra.ojack.xyz/docs/)
+  - [List of Hydra Functions](https://hydra.ojack.xyz/api/)
+  - [Source code on GitHub](https://github.com/hydra-synth/hydra)
+
+### The Hydra namespace
+
+In comparison with the basic Hydra editor, please note that you have to prefix all Hydra functions with <ic>hydra.</ic> to avoid conflicts with Topos functions. For example, <ic>osc()</ic> becomes <ic>hydra.osc()</ic>.
+
+${makeExample("Hydra namespace", `hydra.voronoi(20).out()`, true)}
+
+## GIF player
+
+Topos embeds a small <ic>.gif</ic> picture player with a small API. GIFs are automatically fading out after the given duration. Look at the following example:
+
+${makeExample(
+  "Playing many gifs",
+  `
+beat(0.25)::gif({
+  url:v('gif')[$(1)%6], // Any URL will do!
+  opacity: r(0.5, 1), // Opacity (0-1)
+  size:"300px", // CSS size property
+  center:false, // Centering on the screen?
+  filter:'none', // CSS Filter
+  dur: 2, // In beats (Topos unit)
+  rotation: ir(1, 360), // Rotation (in degrees)
+  posX: ir(1,1200), // CSS Horizontal Position
+  posY: ir(1, 800), // CSS Vertical Position
+`,
+  false,
+)}
+
+## Canvas live coding
+
+Documentation in progress! Copy the example and run it separately (Showing visualization examples in the documentation not implemented yet).
+
+Canvas live coding is a feature that allows you to draw musical events to the canvas. Canvas can be used to create complex visualizations. The feature is based on the <a href="https://developer.mozilla.org/en-US/docs/Web/API/Canvas_API" target="_blank">Canvas API</a> and the <a href="https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D" target="_blank">CanvasRenderingContext2D</a> interface. The feature is still in development and more functions will be added in the future.
+
+In addition to the standard Canvas API, Topos also includes some pre-defined shapes for convenience. See the Shapes section below for more info.
+
+* <ic>draw(f: Function)</ic> - Draws to a canvas with the given function.
+
+${makeExample(
+  "Drawing to canvas",
+  `
+beat(0.5) && clear() && draw(context => {
+    context.fillStyle = 'red';
+
+    // Begin the path for the heart shape
+    context.beginPath();
+    const x = wc();
+    const y = hc();
+    context.fillStyle = 'red';
+
+    // Begin the path for the heart shape
+    context.beginPath();
+
+    context.moveTo(x + 125, y + 50);
+    context.bezierCurveTo(x + 75, y, x, y + 75, x + 125, y + 175);
+    context.bezierCurveTo(x + 250, y + 75, x + 175, y, x + 125, y + 50);
+
+    // Fill the heart with red color
+    context.fill();
+})
+`,
+  false,
+)}
+
+${makeExample(
+"Using draw with events and shapes",
+`
+beat(0.25) && sound("bass1:5").pitch(rI(1,6)).draw(x => {
+donut(x.pitch)
+}).out()
+`,
+false,
+)}  
+
+
+${makeExample(
+"Using draw with ziffers and shapes",
+`
+z1("1/8 (0 2 1 4)+(2 1)").sound("sine").ad(0.05,.25).clear()
+.draw(x => {
+pie({slices:7,eaten:(7-x.pitch-1),fillStyle:"green", rotate: 250})
+}).log("pitch").out()
+`,
+false,
+)}
+
+* <ic<image(url, x, y, width, height, rotation)</ic> - Draws an image to a canvas.
+
+${makeExample(
+    "Image to canvas",
+    `
+    beat(0.5) && clear() && image("http://localhost:8000/topos_frog.svg",200,200+epulse()%15)
+    `,
+    false,
+    )}
+
+* <ic>clear()</ic> - Clears the canvas.
+* <ic>background(fill: string)</ic> - Sets the background color, image or gradient.
+* <ic>w()</ic> - Returns the canvas width.
+* <ic>h()</ic> - Returns the canvas height.
+* <ic>wc()</ic> - Returns the center of the canvas width.
+* <ic>hc()</ic> - Returns the center of the canvas height.
+
+### Text to canvas
+
+Text can be drawn to canvas using the <ic>drawText()</ic> function. The function can take any unicode characters including emojis. The function can also be used to draw random characters from a given unicode range. Different filters can also be applied using the **filter** parameter. See filter in <a href="https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/filter" target="_blank">canvas documentation</a> for more info.
+
+* <ic>drawText(text, fontSize, rotation, font, x, y)</ic> - Draws text to a canvas.
+
+${makeExample(
+"Writing to canvas",
+`
+beat(0.5) && clear() && drawText("Hello world!", 100, 0, "Arial", 100, 100)
+`,
+false,
+)}
+
+* <ic>randomChar(number, min, max)</ic> - Returns a number of random characters from given unicode range.
+
+${makeExample(
+"Drawing random characters to canvas",
+`
+beat(0.5) && clear() && drawText(randomChar(10,1000,2000),30)
+`,
+false,
+)}
+
+* <ic>emoji(size)</ic> - Returns a random emojis as text.
+
+* <ic>animals(size)</ic> - Returns a random animal emojis as text.
+
+* <ic>food(size)</ic> - Returns a random food emojis as text.
+
+${makeExample(
+    "Drawing food emojis to canvas",
+    `
+beat(0.5) && clear() && drawText({x: 10, y: epulse()%700, text: food(50)})
+`,
+    false,
+    )}
+
+* <ic>expression(size)</ic> - Returns a random expression emojis as text.
+
+### Shapes
+
+In addition to supporting drawing to canvas directly, Topos also include some pre-defined shapes for convenience. Every shape can be defined by either by inputting one object as parameter or by inputting the parameters separately.
+
+The predefined shapes are:
+
+* <ic>smiley(happiness, radius, eyes, fill, rotate, x, y)</ic>
+* <ic>ball(radius,fill,x,y)</ic>
+* <ic>box(width, height, fill, rotate)</ic>
+* <ic>pointy(width, height, fill, rotate, x, y)</ic>
+* <ic>equilateral(radius, fill, rotate, x, y)</ic>
+* <ic>star(points, radius, fill rotate, outerRadius, x, y</ic>
+* <ic>pie(slices, eaten, radius, fill, secondary, stroke, rotate, x, y</ic>
+* <ic>donut(slices, eaten, radius, hole, fill, secondary, stroke, rotate, x, y</ic>
+* <ic>balloid(petals, radius, curve, fill, secondary, x, y)</ic>
+* <ic>stroke(width, stroke, rotate, x1, y1, x2, y2)</ic>
+
+### Gradients
+
+* <ic>linearGradient(x1, y1, x2, y2, ...stops)</ic> - Creates a <a href="https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/createLinearGradient">linear gradient</a>.
+* <ic>radialGradient(x1, y1, r1, x2, y2, r2, ...stops)</ic> - Creates a <a href="https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/createRadialGradient">radial gradient</a>.
+* <ic>conicGradient(x, y, angle, ...stops)</ic> - Creates a <a href="https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/createConicGradient">conic gradient</a>.
+
+
+`;
+};

src/documentation/patterns/chaining.ts

@@ -1,5 +1,5 @@
-import { makeExampleFactory } from "../Documentation";
-import { type Editor } from "../main";
+import { makeExampleFactory } from "../../Documentation";
+import { type Editor } from "../../main";
 
 export const chaining = (application: Editor): string => {
   const makeExample = makeExampleFactory(application);
@@ -37,7 +37,7 @@ beat(1)::sound('fhh').juxrev().out()
 This is an extremely powerful construct. For example, you can use it to create synthesizer presets and reuse them later on. You can also define parameters for your registered functions. For example:
 
 ${makeExample(
-  "Re-creating a classic Tidal function",
+  "Creating synth presets",
   `
 // Registering a specific synth architecture
 register('sub', (n,x=4,y=80)=>n.ad(0, .25)
@@ -54,6 +54,45 @@ rhythm(.25, [6, 8].beat(), 12)::sound('sine')
   true,
 )}
 
+## Registering chain for all events
+
+The chain can also be registered automatically for all events. This is useful if you want to add a specific effect to all your events.
+
+${makeExample(
+"Registering chain to all events at once",
+`
+z0("h 9 ^ <7 5 3 1>")
+  .sound("sine")
+  .out()
+
+z1("0 4 3 2")
+  .sound("sine")
+  .out()
+
+all(x=>x.room(1).delay(rI(0,0.5)))
+`,
+true,
+)}
+
+## Logging values from the chain
+
+You can use the <ic>log()</ic> function to print values from the current event. This can be useful to debug your code. Useful parameters to log could be **note**, **pitch**, **dur**, **octave** etc...
+
+${makeExample(
+  "Logging values from the chain",
+  `
+  beat(1) :: sound("sine").pitch(rI(1,6)).log("note").out()
+  `,
+  true,
+)}
+
+${makeExample(
+  "Logging values from ziffers pattern",
+  `
+  z1("0 3 2 5").scale("rocritonic").sound("sine").log("pitch","note","key").out()
+  `,
+  true,
+)}
 
 ## Conditional chaining
 
@@ -101,8 +140,6 @@ There is a growing collection of probability and chance methods you can use:
 | <ic>almostAlways</ic> | With a 98.5% probability. | <ic>.almostAlways(s => s.note(70))</ic> |
 | <ic>always</ic>       | Always transforms the Event.  | <ic>.always(s => s.note(71))</ic> |
 
-
-
 ### MIDI Chaining
 
 The conditional chaining also applies to MIDI. Values can also be incremented using <ic>+=</ic> notation.

src/documentation/patterns/functions.ts

@@ -1,5 +1,5 @@
-import { type Editor } from "../main";
-import { makeExampleFactory } from "../Documentation";
+import { type Editor } from "../../main";
+import { makeExampleFactory } from "../../Documentation";
 
 export const functions = (application: Editor): string => {
   const makeExample = makeExampleFactory(application);
@@ -37,6 +37,25 @@ beat(1) :: script(1, 3, 5)
 - <ic>mean(...values: number[]): number</ic>: returns the arithmetic mean of a list of numbers.
 - <ic>limit(value: number, min: number, max: number): number</ic>: Limits a value between a minimum and a maximum. 
 	
+### Scaling functions
+
+There are some very useful scaling methods taken from **SuperCollider**. You can call these on any number:
+
+- <ic>.linlin(inMin: number, inMax: number, outMin: number, outMax: number)</ic>: scale linearly from one range to another.
+- <ic>.linexp(inMin: number, inMax: number, outMin: number, outMax: number)</ic>: scale a linear range to an exponential range.
+- <ic>.explin(inMin: number, inMax: number, outMin: number, outMax: number)</ic>: scale an exponential range to a linear range.
+- <ic>.expexp(inMin: number, inMax: number, outMin: number, outMax: number)</ic>: scale an exponential range to another exponential range.
+- <ic>.lincurve(inMin: number, inMax: number, outMin: number, outMax: number, curve: number)</ic>: scale a number from one range to another following a specific curve.
+  - <ic>curve: number</ic>: <ic>0</ic> is linear,  <ic>< 0</ic> is concave, negatively curved, <ic>> 0</ic> is convex, positively curved
+
+${makeExample(
+  "Scaling an LFO",
+  `usine(1/2).linlin(0, 1, 0, 100)`,
+  true,
+)}
+
+
+
 ## Delay functions
 	
 - <ic>delay(ms: number, func: Function): void</ic>: Delays the execution of a function by a given number of milliseconds.

src/documentation/patterns/generators.ts

@@ -0,0 +1,173 @@
+import { type Editor } from "../../main";
+import { makeExampleFactory } from "../../Documentation";
+
+export const generators = (application: Editor): string => {
+  const makeExample = makeExampleFactory(application);
+  return `
+# Generator functions
+
+JavaScript <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Generator" target="_blank">generators</a> are powerful functions for generating value sequences. They can be used to generate melodies, rhythms or control parameters.
+
+In Topos generator functions should be called using the <ic>cache(key, function)</ic> function to store the current state of the generator. This function takes two arguments: the name for the cache and the generator instance.
+
+Once the generator is cached the values will be returned from the named cache even if the generator function is modified. To clear the current cache and to re-evaluate the modified generator use the **Shift+Ctrl+Backspace** shortcut. Alternatively you can cache the modified generator using a different name.
+
+The resulted values can be played using either <ic>pitch()</ic> or <ic>freq()</ic> or as Ziffers patterns. When playing the values using <ic>pitch()</ic> different scales and chained methods can be used to alter the result, for example <ic>mod(value: number)</ic> to limit the integer range or <ic>scale(name: string)</ic> etc. to change the resulting note.
+
+${makeExample(
+"Simple looping generator function",
+`
+function* simple() {
+    let x = 0;
+    while (x < 12) {
+        yield x+x;
+        x+=1;
+    }
+}
+
+beat(.25) && sound("triangle").pitch(cache("simple",simple())).scale("minor").out()
+`,
+true,
+)};
+
+${makeExample(
+"Infinite frequency generator",
+`
+    function* poly(x=0) {
+     while (true) {
+        const s = Math.tan(x/10)+Math.sin(x/20);
+        yield 2 * Math.pow(s, 3) - 6 * Math.pow(s, 2) + 5 * s + 200;
+        x++;
+     }
+    }
+
+    beat(.125) && sound("triangle").freq(cache("mathyshit",poly())).out()
+`,
+true,
+)};
+
+When you want to dance with a dynamical system in controlled musical chaos, Topos is waiting for you:
+
+${makeExample(
+  "Truly scale free chaos inspired by Lorentz attractor",
+  `
+  function* strange(x = 0.1, y = 0, z = 0, rho = 28, beta = 8 / 3, zeta = 10) {
+    while (true) {
+      const dx = 10 * (y - x);
+      const dy = x * (rho - z) - y;
+      const dz = x * y - beta * z;
+
+      x += dx * 0.01;
+      y += dy * 0.01;
+      z += dz * 0.01;
+
+      const value = 300 + 30 * (Math.sin(x) + Math.tan(y) + Math.cos(z))
+      yield value;
+    }
+  }
+
+  beat(0.25) :: sound("triangle")
+    .freq(cache("stranger",strange(3,5,2)))
+    .adsr(.15,.1,.1,.1)
+    .log("freq").out()
+  `,
+  true,
+)};
+
+${makeExample(
+    "Henon and his discrete music",
+    `
+  function* henonMap(x = 0, y = 0, a = 1.4, b = 0.3) {
+    while (true) {
+      const newX = 1 - a * x ** 2 + y;
+      const newY = b * x;
+      const fusionPoint = newX + newY
+      yield fusionPoint * 300;
+      [x, y] = [newX, newY]
+    }
+  }
+
+  beat(0.25) :: sound("sawtooth")
+    .semitones(1,1,2,2,2,1,2,1)
+    .freq(cache("Hénon Synth", henonMap()))
+    .adsr(0, 0.1, 0.1, 0.5).out()
+
+  z0('1 {-2}').octave(-2).sound('bd').out()
+  z1('e. 1 s 3!2 e 3!2 s 9 8 1')
+    .sound('dr').gain(0.3).octave(-5).out()
+    `,
+    true,
+  )};
+
+${makeExample(
+  "1970s fractal dream",
+  `
+  function* rossler(x = 0.1, y = 0.1, z = 0.1, a = 0.2, b = 0.2, c = 5.7) {
+    while (true) {
+      const dx = - y - z;
+      const dy = x + (a * y);
+      const dz = b + (x * z) - (c * z);
+
+      x += dx * 0.01;
+      y += dy * 0.01;
+      z += dz * 0.01;
+
+      const value = 250 * (Math.cosh(x*z) + Math.sinh(y*z))
+      yield value % 120 + 100;
+    }
+  }
+
+  beat(0.25) :: sound("triangle")
+    .freq(cache("Rössler attractor", rossler(3,4,1)))
+    .adsr(0,.1,.1,.1)
+    .log("freq").out()
+  `,
+  true,
+)};
+
+
+## OEIS integer sequences
+
+To find some inspiration - or to enter into the void - one can visit <a href="https://oeis.org/" target="_blank">The On-Line Encyclopedia of Integer Sequences (OEIS)</a> to find some interesting integer sequences.
+
+Many of the sequences are implemented by <a href="https://github.com/acerix/jisg/tree/main/src/oeis" target="_blank">JISG</a> (Javascript Integer Sequence Generators) project. Those sequences can be referenced directly with the identifiers using the cache function.
+
+One of these implemented generators is the Inventory sequence <a href="https://github.com/acerix/jisg/blob/main/src/oeis/A342585.ts" target="_blank">A342585</a> made famous by <a href="https://www.youtube.com/watch?v=rBU9E-ZOZAI" target="_blank">Neil Sloane</a>.
+
+${makeExample(
+    "Inventory sequence",
+    `
+    rhythm(0.5,[8,7,5,6].bar(4),9) :: sound("triangle")
+    .pitch(cache("Inventory",A342585))
+    .mod(11).scale("minor")
+    .adsr(.25,.05,.5,.5)
+    .room(2.0).size(0.5)
+    .gain(1).out()
+    `,
+    true,
+    )};
+
+## Using generators with Ziffers
+
+Alternatively generators can be used with Ziffers to generate longer patterns. In this case the generator function should be passed as an argument to the ziffers function. Ziffers patterns are cached separately so there is no need for using **cache()** function. Ziffers expects values from the generators to be integers or strings in ziffers syntax.
+
+${makeExample(
+    "Ziffers patterns using a generator functions",
+`
+function* poly(x) {
+    while (true) {
+      yield 64 * Math.pow(x, 6) - 480 * Math.pow(x, 4) + 720 * Math.pow(x, 2);
+      x++;
+    }
+  }
+
+z0(poly(1)).noteLength(0.5).semitones(2,2,3,2,2,2).sound("sine").out()
+z1(poly(8)).noteLength(0.25).semitones(2,1,2,1,2,2).sound("sine").out()
+z2(poly(-3)).noteLength(1.0).semitones(2,2,2,1,3,2).sound("sine").out()
+`,
+    true,
+  )};
+
+
+`
+};

src/documentation/patterns/lfos.ts

@@ -0,0 +1,59 @@
+import { type Editor } from "../../main";
+import { makeExampleFactory } from "../../Documentation";
+
+export const lfos = (application: Editor): string => {
+  const makeExample = makeExampleFactory(application);
+  return `
+# Low Frequency Oscillators
+
+Low Frequency Oscillators (_LFOs_) are an important piece in any digital audio workstation or synthesizer. Topos implements some basic waveforms you can play with to automatically modulate your paremeters. 
+	
+- <ic>sine(freq: number = 1, phase: number = 0): number</ic>: returns a sinusoïdal oscillation between <ic>-1</ic> and <ic>1</ic>.
+  - <ic>freq</ic> : frequency in hertz.
+  - <ic>phase</ic> : phase amount (adds or substract from current time point).
+- <ic>usine(freq: number = 1, phase: number = 0): number</ic>: returns a sinusoïdal oscillation between <ic>0</ic> and <ic>1</ic>. The <ic>u</ic> stands for _unipolar_.
+	
+${makeExample(
+  "Modulating the speed of a sample player using a sine LFO",
+  `beat(.25) && snd('cp').speed(1 + usine(0.25) * 2).out()`,
+  true,
+)};
+
+- <ic>triangle(freq: number = 1, phase: number = 0): number</ic>: returns a triangle oscillation between <ic>-1</ic> and <ic>1</ic>.
+- <ic>utriangle(freq: number = 1, phase: number = 0): number</ic>: returns a triangle oscillation between <ic>0</ic> and <ic>1</ic>. The <ic>u</ic> stands for _unipolar_.
+
+${makeExample(
+  "Modulating the speed of a sample player using a triangle LFO",
+  `beat(.25) && snd('cp').speed(1 + utriangle(0.25) * 2).out()`,
+  true,
+)}
+	
+- <ic>saw(freq: number = 1, phase: number = 0): number</ic>: returns a sawtooth-like oscillation between <ic>-1</ic> and <ic>1</ic>.
+- <ic>usaw(freq: number = 1, phase: number = 0): number</ic>: returns a sawtooth-like oscillation between <ic>0</ic> and <ic>1</ic>. The <ic>u</ic> stands for _unipolar_.
+
+${makeExample(
+  "Modulating the speed of a sample player using a saw LFO",
+  `beat(.25) && snd('cp').speed(1 + usaw(0.25) * 2).out()`,
+  true,
+)}
+	
+- <ic>square(freq: number = 1, duty: number = .5): number</ic>: returns a square wave oscillation between <ic>-1</ic> and <ic>1</ic>. You can also control the duty cycle using the <ic>duty</ic> parameter.
+- <ic>usquare(freq: number = 1, duty: number = .5): number</ic>: returns a square wave oscillation between <ic>0</ic> and <ic>1</ic>. The <ic>u</ic> stands for _unipolar_. You can also control the duty cycle using the <ic>duty</ic> parameter.
+	
+${makeExample(
+  "Modulating the speed of a sample player using a square LFO",
+  `beat(.25) && snd('cp').speed(1 + usquare(0.25, 0, 0.25) * 2).out()`,
+  true,
+)};
+	
+- <ic>noise(times: number = 1)</ic>: returns a random value between -1 and 1.
+- <ic>unoise(times: number = 1)</ic>: returns a random value between 0 and 1.
+	
+${makeExample(
+  "Modulating the speed of a sample player using noise",
+  `beat(.25) && snd('cp').speed(1 + noise() * 2).out()`,
+  true,
+)};
+
+`;
+};

src/documentation/patterns/patterns.ts

@@ -1,10 +1,10 @@
-import { type Editor } from "../main";
-import { makeExampleFactory } from "../Documentation";
+import { type Editor } from "../../main";
+import { makeExampleFactory } from "../../Documentation";
 
 export const patterns = (application: Editor): string => {
   const makeExample = makeExampleFactory(application);
   return `
-# Patterns
+# Array patterns
 
 **Topos** is using arrays as a way to make dynamic patterns of data (rhythms, melodies, etc). 
 It means that the following:
@@ -120,8 +120,39 @@ beat(1)::sound(['kick', 'fsnare'].dur(3, 1))
   true,
 )}
 
-## Manipulating notes and scales
+${makeExample(
+  "Patterning with ternary statements",
+  `
+  const dada = flipbar(2) ? [0,[3,5,-1].bar(3),2,3] : [9,8,9,6]
+beat(0.5) :: sound('wt_hvoice:3')
+  .pitch(dada.beat(0.5))
+  .scale("88.0")
+  .adsr(0.05, 0.05, 0, 0)
+  .cutoff(500 + usine(1/8) * 5000)
+  .room(1.5)
+  .resonance(0.25)
+  .out()
+beat(1) :: sound('kick').n(4).out()
+onbeat([0.5,0.8].beat(1),2) :: sound('snare').out()
+onbeat(0.5,0.8,1,1.5,2,2.5,3,4) :: sound('hh').out()
+`,
+  true,
+)}
 
+## Iteration using a counter
+
+- <ic>counter(name,limit?,step?)</ic>: return the next value on the list based on counter value. The limit is optional and defaults to the length of the list. The step is optional and defaults to 1. Setting / changing limit will reset the counter.
+- <ic>$(name,limit?,step?)</ic>: shorter alias for the counter.
+
+${makeExample(
+  "Using counter to iterate over a list",
+  `
+  beat(0.5) :: sound("bd").gain(line(0,1,0.01).$("ramp")).out()
+  `,
+  true,
+)}
+
+## Manipulating notes and scales
 
 - <ic>pitch()</ic>: convert a list of integers to pitch classes
 
@@ -136,7 +167,62 @@ beat(0.25) :: snd('sine')
   true,
 )}
 
-  - <ic>scale(scale: string, base note: number)</ic>: Map each element of the list to the closest note of the slected scale. [0, 2, 3, 5 ].scale("major", 50) returns [50, 52, <ic>54</ic>, 55]. You can use western scale names like (Major, Minor, Minor pentatonic ...) or [zeitler](https://ianring.com/musictheory/scales/traditions/zeitler) scale names. Alternatively you can also use the integers as used by Ian Ring in his [study of scales](https://ianring.com/musictheory/scales/).
+- <ic>semitones(number[], ...args?)</ic>: Create scale from semitone intervals.
+
+${makeExample(
+  "Play pitches from scale created from semitone intervals",
+  `
+  beat(1) :: sound('gtr').pitch([0, 4, 3, 2].beat()).key(64)
+  .semitones(1, 1, 3, 1, 1, 2, 3).out()
+`,
+  true,
+)}
+
+- <ic>cents(number[], ...args?)</ic>: Create scale from cent intervals.
+
+${makeExample(
+  "Play pitches from scale created from cent intervals",
+  `
+  rhythm([0.5,0.25].beat(1),14,16) :: sound('pluck')
+  .stretch(iR(1,5)).pitch(iR(0,6)).key(57)
+.cents(120,270,540,670,785,950,1215).out()
+`,
+  true,
+)}
+
+- <ic>ratios(number[], ...args?)</ic>: Create scale from ratios.
+
+${makeExample(
+  "Play pitches from scale created from ratios",
+  `
+  rhythm([0.5,0.25].beat(0.25),5,7) :: sound('east:3')
+  .pitch([0,1,2,3,4,5,6,7,8,9,10,11].beat(0.25)).key(67)
+.ratios(2/11,4/11,6/11,8/11,10/11,11/11).out()
+`,
+  true,
+)}
+
+- <ic>edo(number, scale?: string|number[])</ic>: Create scale from equal divisions of the octave. Creates chromatic scale by default.
+
+${makeExample(
+  "Play pitches from scale created from equal divisions of the octave",
+  `
+  z0("e bd bd <bd bd [bd bd] [bd bd bd bd]>").sound().out()
+flipbar(1) :: rhythm(.25,14,16) :: sound("ST10:30").stretch(3).gain(0.5)
+.pitch([0,10,r(20,40),r(100,200),r(-200,200),r(200,300),200,r(3,666)].beat([1.0,0.5,0.25].bar(6)))
+    .octave(r(-6,6))
+    .edo(666,"rocritonic")
+    .out()
+rhythm(2.0,26,32) :: sound("ST20").n([22,5,24,34,31,5,11,19].pick()).stretch(rI(1,6))
+.pitch(rI(127,300))
+    .edo(666)
+    .out()
+`,
+  true,
+)}
+
+
+- <ic>scale(scale: string, base note: number)</ic>: Map each element of the list to the closest note of the slected scale. [0, 2, 3, 5 ].scale("major", 50) returns [50, 52, <ic>54</ic>, 55]. You can use western scale names like (Major, Minor, Minor pentatonic ...) or [zeitler](https://ianring.com/musictheory/scales/traditions/zeitler) scale names. Alternatively you can also use the integers as used by Ian Ring in his [study of scales](https://ianring.com/musictheory/scales/).
 
 ${makeExample(
   "Mapping the note array to the E3 major scale",

src/documentation/patterns/probabilities.ts

@@ -1,5 +1,5 @@
-import { type Editor } from "../main";
-import { makeExampleFactory } from "../Documentation";
+import { type Editor } from "../../main";
+import { makeExampleFactory } from "../../Documentation";
 
 export const probabilities = (application: Editor): string => {
   const makeExample = makeExampleFactory(application);
@@ -54,6 +54,7 @@ By default chance operators will be evaluated 48 times within a beat. You can ch
 - <ic>frequently(beats?: number)</ic>: returns true 90% of the time in given number of beats
 - <ic>almostAlways(beats?: number)</ic>: returns true 99% of the time in given number of beats
 - <ic>always(beats?: number)</ic>: returns true. Can be handy when switching between different probabilities
+- <ic>once()</ic>: returns true once, then false until the code is force evaluated (Shift+Ctrl+Enter)
 	
 Examples:
 

src/documentation/patterns/variables.ts

@@ -1,5 +1,5 @@
-import { type Editor } from "../main";
-import { makeExampleFactory } from "../Documentation";
+import { type Editor } from "../../main";
+import { makeExampleFactory } from "../../Documentation";
 
 export const variables = (application: Editor): string => {
   const makeExample = makeExampleFactory(application);
@@ -7,20 +7,15 @@ export const variables = (application: Editor): string => {
 
 # Variables
 
-By default, each script is independant from each other. Scripts live in their own bubble and you cannot get or set variables affecting a script from any other script.
+By default, each script is independant from each other. The variables defined in **script 1** are not available in **script 2**, etc. Moreover, they are overriden everytime the file is evaluated. It means that you cannot store any state or share information. However, you can use global variables to make that possible.
 
-**However**, everybody knows that global variables are cool and should be used everywhere. Global variables are an incredibely powerful tool to radically alter a composition in a few lines of code.
+There is a <ic>global</ic> object that you can use to store and retrieve information. It is a simple key/value store. You can store any type of data in it:
 	
-- <ic>variable(a: number | string, b?: any)</ic>: if only one argument is provided, the value of the variable will be returned through its name, denoted by the first argument. If a second argument is used, it will be saved as a global variable under the name of the first argument.
-	- <ic>delete_variable(name: string)</ic>: deletes a global variable from storage.
-	- <ic>clear_variables()</ic>: clear **ALL** variables. **This is a destructive operation**!
-	
-**Note:** since this example is running in the documentation, we cannot take advantage of the multiple scripts paradigm. Try to send a variable from the global file to the local file n°6.
-
 ${makeExample(
   "Setting a global variable",
   `
-v('my_cool_variable', 2)
+// This is script n°3
+global.my_variable = 2
 `,
   true,
 )}
@@ -28,15 +23,16 @@ v('my_cool_variable', 2)
 ${makeExample(
   "Getting that variable back and printing!",
   `
-// Note that we just use one argument
-log(v('my_cool_variable'))
+// This is script n°4
+log(global.my_variable)
 `,
-  false,
+  true,
 )}
 
+Now your scripts can share information with each other!
 
 ## Counter and iterators
-	
+
 You will often need to use iterators and/or counters to index over data structures (getting a note from a list of notes, etc...). There are functions ready to be used for this. Each script also comes with its own iterator that you can access using the <ic>i</ic> variable. **Note:** the script iteration count is **not** resetted between sessions. It will continue to increase the more you play, even if you just picked up an old project.
 	
 - <ic>counter(name: number | string, limit?: number, step?: number)</ic>: reads the value of the counter <ic>name</ic>. You can also call this function using the dollar symbol: <ic>$</ic>.

src/documentation/patterns/ziffers/ziffers_algorithmic.ts

@@ -0,0 +1,97 @@
+import { type Editor } from "../../../main";
+import { makeExampleFactory } from "../../../Documentation";
+
+export const ziffers_algorithmic = (application: Editor): string => {
+  const makeExample = makeExampleFactory(application);
+  return `
+# Algorithmic operations
+
+  Ziffers provides shorthands for **many** numeric and algorithimic operations such as evaluating random numbers and creating sequences using list operations:
+  
+  * **List operations:** Element-wise operation (_e.g._ <ic>(3 2 1)+(2 5)</ic>) using the <ic>+</ic> operator. All the arithmetic operators are supported.
+  
+  ${makeExample(
+    "Element-wise operations for melodic generation",
+    `
+  z1("1/8 _ 0 (0 1 3)+(1 2) 0 (2 3 5)-(1 2)").sound('sine')
+    .scale('pentatonic').fmi([0.25,0.5].beat(2)).fmh([2,4].beat(2))
+    .room(0.9).size(0.9).sustain(0.1).delay(0.125)
+    .delayfb(0.25).out();
+  `,
+    true,
+  )}
+
+  ${makeExample(
+    "List operations",
+    `
+    z1('q (0 3 1 5)+(2 5) e (0 5 2)*(2 1) (0 5 2)%(2 3)')
+    .sound('sine')
+    .room(.5).size(1.0).adsr(.15,.15,.25,.1)
+    .scale("Bebop major")
+    .out()
+  `,
+    true,
+  )}
+  
+  * **Random numbers:** <ic>(4,6)</ic> Random number between 4 and 6
+  
+  ${makeExample(
+    "Random numbers, true computer music at last!",
+    `
+  z1("s _ (0,8) 0 0 (0,5) 0 0").sound('sine')
+    .adsr(0, .1, 0, 0).scale('minor')
+    .fmdec(0.25).fmi(2).fmh([0.5, 0.25].beat(2))
+    .room(0.9).size(0.5).sustain(0.1) .delay(0.5)
+    .delay(0.125).delayfb(0.25).out();
+  beat(.5) :: snd(['kick', 'hat'].beat(.5)).out()
+  `,
+    true,
+  )}
+  
+## Variables
+
+  * <ic>A=(0 2 3 (1,4))</ic> Assign pre-evaluated list to a variable
+  * <ic>B~(0 2 3 (1,4))</ic> Assign list with operations to a variable
+
+  ${makeExample(
+    "Assign lists to variables",
+    `
+z1("s A=(0 (1,4)) B~(2 (3,8)) A B A B A")
+  .scale("modimic")
+  .sound("triangle")
+  .adsr(0.01,0.15,0.25,0)
+  .gain(0.5)
+  .out()
+  `,
+    true,
+  )}
+
+  ${makeExample(
+    "Combine variables into lists and do operations",
+    `
+    z1("s A=(0 3) B=(3 8) C=(((A+B)+A)*B) D=(C-B) A A+C D")
+    .sound("sawtooth")
+    .ad(0.05,1.0)
+    .gain(0.5)
+    .out()    
+  `,
+    true,
+  )}
+
+## Generative functions
+
+  * <ic>at(index: number, ...args?: number[])</ic> Get event(s) at given index
+  * <ic>repeat(amount: number)</ic> Repeat the generated pattern without re-evaluating random patterns
+  * <ic>keep()</ic> Keep the generated pattern without re-evaluating random patterns. Same as repeat(0).
+  * <ic>shuffle()</ic> Shuffle the pattern
+  * <ic>deal(amount: number): Shuffle the generated pattern and deal given number of elements
+  * <ic>retrograde()</ic> Reverse the generated pattern
+  * <ic>invert()</ic> Invert the generated pattern
+  * <ic>rotate(amount: number)</ic> Rotate the generated pattern by given amount
+  * <ic>between(start: number, end: number)</ic> Select a range of elements from the generated pattern
+  * <ic>from(start: number)</ic> Select a range of elements from the start index to the end of the pattern
+  * <ic>to(end: number)</ic> Select a range of elements from the beginning of the pattern to the end index
+  * <ic>every(amount: number)</ic> Select every n-th element from the pattern
+
+`;
+};

src/documentation/patterns/ziffers/ziffers_basics.ts

@@ -0,0 +1,300 @@
+import { type Editor } from "../../../main";
+import { makeExampleFactory } from "../../../Documentation";
+
+export const ziffers_basics = (application: Editor): string => {
+  const makeExample = makeExampleFactory(application);
+  return `
+# Ziffers
+	
+Ziffers is a **musical number based notation** tuned for _live coding_. It is a very powerful and flexible notation for describing musical patterns in very few characters. Number based musical notation has a long history and has been used for centuries as a shorthand technique for music notation. Amiika has written [papers](https://zenodo.org/record/7841945) and other documents describing his system. It is currently implemented for many live coding platforms including [Sardine](https://sardine.raphaelforment.fr) (Raphaël Forment) and [Sonic Pi](https://sonic-pi.net/) (Sam Aaron). Ziffers can be used for:
+
+- composing melodies using using **classical music notation and concepts**.
+- exploring **generative / aleatoric / stochastic** melodies and applying them to sounds and synths.
+- embracing a different mindset and approach to time and **patterning**.
+
+${makeExample(
+  "Super Fancy Ziffers example",
+  `
+z1('1/8 024!3 035 024 0124').sound('wt_stereo')
+  .adsr(0, .4, 0.5, .4).gain(0.1)
+  .lpadsr(4, 0, .2, 0, 0)
+  .cutoff(5000 + usine(1/2) * 2000)
+  .n([1,2,4].beat(4)).out()
+z2('<1/8 1/16> __ 0 <(^) (^ ^)> (0,8)').sound('wt_stereo')
+  .adsr(0, .5, 0.5, .4).gain(0.2)
+  .lpadsr(4, 0, .2, 0, 0).n(14)
+  .cutoff(200 + usine(1/2) * 4000)
+  .n([1,2,4].beat(4)).o(2).room(0.9).out()
+let osci = 1500 + usine(1/2) * 2000;
+z3('can can:2').sound().gain(1).cutoff(osci).out()
+z4('1/4 kick kick snare kick').sound().gain(1).cutoff(osci).out()
+`,
+  true,
+)}
+
+## Evaluation
+
+Evaluation of live coded Ziffers patterns can be done in 3 different ways. Normal evaluation using <ic>Ctrl+Enter</ic> updates the pattern after the current cycle is finished. Evaluation using <ic>Ctrl+Shift+Enter</ic> updates the pattern immediately keeping the current position, which enables to modify future events even within the current cycle. Evaluation using <ic>Ctrl+Shift+Backspace</ic> resets the current pattern and starts from the beginning immediately.
+
+## Notation
+
+The basic Ziffer notation is entirely written in JavaScript strings (_e.g_ <ic>"0 1 2"</ic>). It consists mostly of numbers and letters. The whitespace character is used as a separator. Instead of note names, Ziffer is using numbers to represent musical pitch and letters to represent musical durations. Alternatively, _floating point numbers_ can also be used to represent durations.
+
+| Syntax        | Symbol | Description            |
+|------------   |--------|------------------------|
+| **Pitches**   | <ic>0-9</ic> <ic>{10 11 21}</ic> | Numbers or escaped numbers in curly brackets |
+| **Duration**  | <ic>0.25</ic>, <ic>0.5</ic> | Floating point numbers can also be used as durations |
+| **Duration**  | <ic>1/4</ic>, <ic>1/16</ic> | Fractions can be used as durations |
+| **Subdivision** | <ic>[1 [2 3]]</ic> | Durations can be subdivided using square brackets |
+| **Cycles**    | <ic>1 <2 4></ic> | Cycle values within the pattern |
+| **Octave**    | <ic>^ _</ic> | <ic>^</ic> for octave up and <ic>_</ic> for octave down |
+| **Accidentals** | <ic># b</ic> | Sharp and flats, just like with regular music notation :smile: |
+| **Rest**      |  <ic>r</ic> | Rest / silences |
+| **Repeat**    | <ic>!1-9</ic> | Repeat the item 1 to 9 times  |
+| **Chords**    | <ic>[1-9]+ / [iv]+ / [AG]+name</ic> | Multiple pitches grouped together, roman numerals or named chords |
+| **Samples**   | <ic>[a-z0-9_]+</ic> | Samples can be used pitched or unpitched | 
+| **Index/Channel** | <ic>[a-z0-9]+:[0-9]*</ic> | Samples or midi channel can be changed using a colon |
+
+**Note:** Some features are experimental and some are still unsupported. For full / prior syntax see article about <a href="https://zenodo.org/record/7841945" target="_blank">Ziffers</a>.
+
+${makeExample(
+  "Pitches from 0 to 9",
+  `
+z1('0.25 0 1 2 3 4 5 6 7 8 9').sound('wt_stereo')
+  .adsr(0, .1, 0, 0).out()`,
+  true,
+)}
+
+${makeExample(
+  "Escaped pitches using curly brackets",
+  `z1('_ _ 0 {9 10 11} 4 {12 13 14}')
+  .sound('wt_05').pan(r(0,1))
+  .cutoff(usaw(1/2) * 4000)
+  .room(0.9).size(0.9).out()`,
+  false,
+)}
+
+${makeExample(
+  "Durations using fractions and floating point numbers",
+  `
+z1('1/8 0 2 4 0 2 4 1/4 0 3 5 0.25 _ 0 7 0 7')
+  .sound('square').delay(0.5).delayt(1/8)
+  .adsr(0, .1, 0, 0).delayfb(0.45).out()
+`,
+  false,
+)}
+
+${makeExample(
+  "Disco was invented thanks to Ziffers",
+  `
+z1('e _ _ 0 ^ 0 _ 0 ^ 0').sound('jvbass').out()
+beat(1)::snd('bd').out(); beat(2)::snd('sd').out()
+beat(3) :: snd('cp').room(0.5).size(0.5).orbit(2).out()
+`,
+  false,
+)}
+
+${makeExample(
+  "Accidentals and rests for nice melodies",
+  `
+z1('^ 1/8 0 1 b2 3 4 _ 4 b5 4 3 b2 1 0')
+  .scale('major').sound('triangle')
+  .cutoff(500).lpadsr(5, 0, 1/12, 0, 0)
+  .fmi(0.5).fmh(2).delay(0.5).delayt(1/3)
+  .adsr(0, .1, 0, 0).out()
+`,
+  false,
+)}
+
+${makeExample(
+  "Repeat items n-times",
+  `
+z1('1/8 _ _ 0!4 3!4 4!4 3!4')
+  .scale('major').sound('wt_oboe')
+  .shape(0.2).sustain(0.1).out()
+z2('1/8 _ 0!4 5!4 4!2 7!2')
+  .scale('major').sound('wt_oboe')
+  .shape(0.2).sustain(0.1).out()
+`,
+  false,
+)}
+
+${makeExample(
+  "Subdivided durations",
+  `
+z1('w [0 [5 [3 7]]] h [0 4]')
+  .scale('major').sound('sine')
+  .fmi(usine(.5)).fmh(2).out()
+`,
+  false,
+)}
+
+## Rests
+
+${makeExample(
+  "Rest and octaves",
+  `
+z1('q 0 ^ e0 r _ 0 _ r 4 ^4 4')
+.sound('sine').scale("godian").out()
+`,
+  true,
+)}
+
+${makeExample(
+  "Rests with durations",
+  `
+ z1('q 0 4 e^r 3 e3 0.5^r h4 1/4^r e 5 r 0.125^r 0')
+ .sound('sine').scale("aeryptian").out()
+ `,
+  true,
+)}
+
+## Chords
+
+  Chords can be build by grouping pitches or using roman numeral notation, or by using named chords.
+  
+  ${makeExample(
+    "Chords from pitches",
+    `
+  z1('1.0 024 045 058 046 014')
+    .sound('sine').adsr(0.5, 1, 0, 0)
+    .room(0.5).size(0.9)
+    .scale("minor").out()
+  `,
+  true
+  )}
+  
+  ${makeExample(
+    "Chords from roman numerals",
+    `
+  z1('2/4 i vi ii v')
+    .sound('triangle').adsr(0.2, 0.3, 0, 0)
+    .room(0.5).size(0.9).scale("major").out()
+  `,
+  true
+  )}
+  
+  ${makeExample(
+    "Named chords with repeats",
+    `
+  z1('0.25 Bmaj7!2 D7!2 _ Gmaj7!2 Bb7!2 ^ Ebmaj7!2')
+    .sound('square').room(0.5).cutoff(500)
+    .lpadsr(4, 0, .4, 0, 0).size(0.9)
+    .scale("major").out()
+  `,
+  true
+  )}
+  
+  ${makeExample(
+    "Transposing chords",
+    `
+  z1('q Amin!2').key(["A2", "E2"].beat(4))
+    .sound('sawtooth').cutoff(500)
+    .lpadsr(2, 0, .5, 0, 0, 0).out()`,
+  )}
+  
+  ${makeExample(
+    "Chord inversions with roman numerals",
+    `
+  z1('i i v%-4 v%-2 vi%-5 vi%-3 iv%-2 iv%-1')
+    .sound('triangle').adsr(1/16, 1/5, 0.1, 0)
+    .delay(0.5).delayt([1/8, 1/4].beat(4))
+    .delayfb(0.5).out()
+  beat(4) :: sound('breaks165').stretch(4).out()
+  `,
+  )}
+  
+  ${makeExample(
+    "Chord inversion with named chords",
+    `
+  z1('1/4 Cmin!3 Fmin!3 Fmin%-1 Fmin%-2 Fmin%-1')
+    .sound("sine").bpf(500 + usine(1/4) * 2000)
+    .out()
+  `,
+  )}
+  
+  ${makeExample(
+    "Programmatic inversions",
+    `
+  z1('1/6 i v 1/3 vi iv').invert([1,-1,-2,0].beat(4))
+    .sound("sawtooth").cutoff(1000)
+    .lpadsr(2, 0, .2, 0, 0).out()
+    `,
+  )}
+
+## Arpeggios
+
+Chords can be arpeggiated using the @-character within the ziffers notation or by using <ic>arpeggio</ic> method.
+
+${makeExample(
+  "Arpeggio using the mini-notation",
+  `
+  z1("(i v vi%-3 iv%-2)@(s 0 2 0 1 2 1 0 2)")
+  .sound("sine").out()
+  `,
+)}
+
+${makeExample(
+  "Arpeggio from named chords with durations",
+  `
+z1("_ Gm7 ^ C9 D7 Gm7")
+  .arpeggio("e 0 2 q 3 e 1 2")
+  .sound("sine").out()
+  `,
+)}
+
+${makeExample(
+  "Arpeggio from roman chords with inversions",
+  `
+  z1("i v%-1 vi%-1 iv%-2")
+    .arpeggio(0,2,1,2)
+    .noteLength(0.125)
+    .sound("sine").out()
+  `,
+)}
+
+## Chaining
+	
+- Basic notation
+	
+${makeExample(
+  "Simple method chaining",
+  `
+z1('0 1 2 3').key('G3')
+  .scale('minor').sound('sine').out()
+`,
+  true,
+)}
+
+${makeExample(
+  "More complex chaining",
+  `
+z1('0 1 2 3 4').key('G3').scale('minor').sound('sine').often(n => n.pitch+=3).rarely(s => s.delay(0.5)).out()
+`,
+  true,
+)}
+
+${makeExample(
+  "Alternative way for inputting options",
+  `
+z1('0 3 2 4',{key: 'D3', scale: 'minor pentatonic'}).sound('sine').out()
+`,
+  true,
+)}
+
+## String prototypes
+
+You can also use string prototypes as an alternative syntax for creating Ziffers patterns
+
+${makeExample(
+  "String prototypes",
+  `
+  "q 0 e 5 2 6 2 q 3".z0().sound('sine').out()
+  "q 2 7 8 6".z1().octave(-1).sound('sine').out()
+  "q 2 7 8 6".z2({key: "C2", scale: "aeolian"}).sound('sine').scale("minor").out()
+`,
+  true,
+)}  
+
+`;
+};

src/documentation/patterns/ziffers/ziffers_rhythm.ts

@@ -0,0 +1,157 @@
+import { type Editor } from "../../../main";
+import { makeExampleFactory } from "../../../Documentation";
+
+export const ziffers_rhythm = (application: Editor): string => {
+  const makeExample = makeExampleFactory(application);
+  return `
+# Rhythm
+
+Ziffers combines rhythmic and melodic notation into a single pattern language. This means that you can use the same pattern to describe both the rhythm and the melody of a musical phrase similarly to the way it is done in traditional music notation.
+
+${makeExample(
+  "Duration chars",
+  `
+  z1('q 0 0 4 4 5 5 h4 q 3 3 2 2 1 1 h0').sound('sine').out()
+`,
+  true,
+)}
+
+${makeExample(
+  "Fraction durations",
+  `
+  z1('1/4 0 0 4 4 5 5 2/4 4 1/4 3 3 2 2 1 1 2/4 0')
+  .sound('sine').out()
+`,
+  true,
+)}
+
+${makeExample(
+  "Decimal durations",
+  `
+z1('0.25 5 1 2 6 0.125 3 8 0.5 4 1.0 0')
+.sound('sine').scale("galian").out()
+`,
+  true,
+)}
+
+## List of all duration characters
+
+Ziffers maps the following duration characters to the corresponding note lengths.
+
+|	Character	|	Fraction | Duration |	Name (US)	|	Name (UK)	|
+| ----- | ----- | ------- | ----- |
+| m..   | 14/1  | 14.0    | Double dotted maxima | Double dotted Large
+| m.    | 12/1  | 12.0    | Dotted maxima | Dotted Large |
+|	m	    |	8/1   | 8.0	    |	Maxima	|	Large	|
+| l..   | 7/1   | 7.0     | Double dotted long note | Double dotted longa |
+| l.    | 6/1   | 6.0     | Long dotted note | Longa dotted |
+|	l	    |	4/1   | 4.0	    |	Long	|	Longa |
+| d..   | 7/2   | 3.5     | Double dotted long note | Double dotted breve |
+| d.    | 3/3   | 3.0     | Dotted whole note | Double breve |
+|	n     |	8/3   | 2.6666	|	Triplet Long	|	Triplet longa	|
+|	d	    |	2/1   | 2.0	    |	Double whole note	|	Breve	|
+| w..   | 7/4   | 1.75    | Double dotted whole note | Double dotted breve |
+| w.    | 3/2   | 1.5     | Dotted whole note | Dotted breve |
+|	k	    |	4/3   | 1.3333  |	Triplet double whole  |	Triplet breve	|
+|	w	    |	1/1   | 1.0	    |	Whole note	|	Semibreve	|
+| h..   | 7/8   | 0.875   | Double dotted half note | Double dotted minim |
+| h.    | 3/4   | 0.75    | Dotted half note | Dotted minim |
+|	c     |	2/3   | 0.6666	|	Triplet whole	|	Triplet semibreve	|
+|	h	    |	1/2   | 0.5	    |	Half note 	|	Minim	|
+|	p     |	1/3   | 0.3333	|	Triplet half	|	Triplet minim	|
+| q..   | 7/16  | 0.4375  | Double dotted quarter note | Double dotted crotchet |
+| q.    | 3/8   | 0.375   | Dotted quarter note | Dotted crotchet |
+|	q	    |	1/4   | 0.25  	|	Quarter note	|	Crotchet	|
+| e..   | 7/32  | 0.2187  | Double dotted 8th | Double dotted quaver |
+| e.    | 3/16  | 0.1875  | Dotted 8th | Dotted quaver |
+|	g     |	1/6   | 0.1666	|	Triplet quarter	|	Triplet crochet 	|
+|	e	    |	1/8   | 0.125	  |	8th note	|	Quaver	|
+| s..   | 7/64  | 0.1093  | Double dotted 16th | Double dotted semiquaver |
+|	a     |	1/12  | 0.0833	|	Triplet 8th	|	Triplet quaver	|
+| s.    | 3/32  | 0.0937  | Dotted 16th | Dotted semiquaver |
+|	s	    |	1/16  | 0.0625	|	16th note	|	Semiquaver	|
+| t..   | 7/128 | 0.0546  | Double dotted 32th | Double dotted demisemiquaver |
+| t.    | 3/64  | 0.0468  | Dotted 32th | Dotted demisemiquaver |
+|	f     |	1/24  | 0.0416	|	Triplet 16th	|	Triplet semiquaver	|
+|	t	    |	1/32  | 0.0312	|	32th note	|	Demisemiquaver	|
+| u..   | 7/256 | 0.0273  | Double dotted 64th | Double dotted hemidemisemiquaver |
+| u.    | 3/128 | 0.0234  | Dotted 64th | Dotted hemidemisemiquaver |
+|	x     |	1/48  | 0.0208	|	Triplet 32th	|	Triplet demi-semiquaver	|
+|	u	    |	1/64  | 0.0156	|	64th note	|	Hemidemisemiquaver	|
+| o..   | 7/512 | 0.0136  | Double dotted 128th note | Double dotted semihemidemisemiquaver |
+| y     |	1/96  | 0.0104	|	Triplet 64th	|	Triplet hemidemisemiquaver	|
+| o.    | 3/256 | 0.0117  | Dotted 128th note | Dotted semihemidemisemiquaver |
+|	o	    |	1/128 | 0.0078	|	128th note	|	Semihemidemisemiquaver	|
+|	j     |	1/192 | 0.0052	|	Triplet 128th | Triplet semihemidemisemiquaver	|
+|	z	    |	0/1   | 0.0	    |	No length	|	No length	|
+
+## Samples
+
+Samples can be patterned using the sample names or using <c>@</c>-operator for assigning sample to a pitch. Sample index can be changed using the <c>:</c> operator.
+
+${makeExample(
+  "Sampled drums",
+  `
+  z1('bd [hh hh]').octave(-2).sound('sine').out()
+  `,
+  true,
+)}
+
+${makeExample(
+  "More complex pattern",
+  `
+  z1('bd [hh <hh <cp cp:2>>]').octave(-2).sound('sine').out()
+  `,
+  true,
+)}
+
+${makeExample(
+  "Pitched samples",
+  `
+  z1('0@sax 3@sax 2@sax 6@sax')
+    .octave(-1).sound()
+    .adsr(0.25,0.125,0.125,0.25).out()
+  `,
+  true,
+)}
+
+${makeExample(
+  "Pitched samples from list operation",
+  `
+  z1('e (0 3 -1 4)+(-1 0 2 1)@sine')
+  .key('G4')
+  .scale('110 220 320 450')
+  .sound().out()
+  `,
+  true,
+)}
+
+${makeExample(
+  "Pitched samples with list notation",
+  `
+  z1('e (0 2 6 3 5 -2)@sax (0 2 6 3 5 -2)@arp')
+    .octave(-1).sound()
+    .adsr(0.25,0.125,0.125,0.25).out()
+  `,
+  true,
+)}
+
+${makeExample(
+  "Sample indices",
+  `
+  z1('e 1:2 4:3 6:2')
+  .octave(-1).sound("east").out()
+  `,
+  true,
+)}
+
+${makeExample(
+  "Pitched samples with sample indices",
+  `
+z1('_e 1@east:2 4@bd:3 6@arp:2 9@baa').sound().out()
+`,
+  true,
+)}
+
+`;
+};

src/documentation/patterns/ziffers/ziffers_scales.ts

@@ -0,0 +1,101 @@
+import { type Editor } from "../../../main";
+import { makeExampleFactory } from "../../../Documentation";
+
+export const ziffers_scales = (application: Editor): string => {
+  const makeExample = makeExampleFactory(application);
+  return `
+# Scales
+
+  Ziffers supports all the keys and scales. Keys can be defined by using [scientific pitch notation](https://en.wikipedia.org/wiki/Scientific_pitch_notation), for example <ic>F3</ic>. Western style (1490 scales) can be with scale names named after greek modes and extended by <a href="https://allthescales.org/intro.php" target="_blank">William Zeitler</a>. You will never really run out of scales to play with using Ziffers. Here is a short list of some possible scales that you can play with:
+  
+  | Scale name | Intervals              |
+  |------------|------------------------|
+  | Lydian     | <ic>2221221</ic> |
+  | Mixolydian | <ic>2212212</ic> |
+  | Aeolian    | <ic>2122122</ic> |
+  | Locrian    | <ic>1221222</ic> |
+  | Ionian     | <ic>2212221</ic> |
+  | Dorian     | <ic>2122212</ic> |
+  | Phrygian   | <ic>1222122</ic> |
+  | Soryllic   | <ic>11122122</ic>|
+  | Modimic    | <ic>412122</ic>  |
+  | Ionalian   | <ic>1312122</ic> |
+  | ... | And it goes on for   <a href="https://ianring.com/musictheory/scales/traditions/zeitler" target="_blank">**1490** scales (See full list here)</a>. |
+  
+  ${makeExample(
+    "What the hell is the Modimic scale?",
+    `
+  z1("s (0,8) 0 0 (0,5) 0 0").sound('sine')
+    .scale('modimic').fmi(2).fmh(2).room(0.5)
+      .size(0.5).sustain(0.1) .delay(0.5)
+      .delay(0.125).delayfb(0.25).out();
+  beat(.5) :: snd(['kick', 'hat'].beat(.5)).out()
+  `,
+    true,
+  )}
+
+  You can also use more traditional <a href="https://ianring.com/musictheory/scales/traditions/western" target="_blank">western names</a>:
+  
+  | Scale name | Intervals              |
+  |------------|------------------------|
+  | Major      | <ic>2212221</ic> |
+  | Minor      | <ic>2122122</ic> |
+  | Minor pentatonic   | <ic>32232</ic>  |
+  | Harmonic minor     | <ic>2122131</ic>|
+  | Harmonic major     | <ic>2212131</ic>|
+  | Melodic minor      | <ic>2122221</ic>|
+  | Melodic major      | <ic>2212122</ic>|
+  | Whole              | <ic>222222</ic> |
+  | Blues minor        | <ic>321132</ic> |
+  | Blues major        | <ic>211323</ic> |
+  
+  ${makeExample(
+    "Let's fall back to a classic blues minor scale",
+    `
+  z1("s (0,8) 0 0 (0,5) 0 0").sound('sine')
+    .scale('blues minor').fmi(2).fmh(2).room(0.5)
+      .size(0.5).sustain(0.25).delay(0.25)
+      .delay(0.25).delayfb(0.5).out();
+  beat(1, 1.75) :: snd(['kick', 'hat'].beat(1)).out()
+  `,
+    true,
+  )}
+  
+  Microtonal scales can be defined using <a href="https://www.huygens-fokker.org/scala/scl_format.html" target="_blank">Scala format</a> or by extended notation defined by Sevish <a href="https://sevish.com/scaleworkshop/" target="_blank">Scale workshop</a>, for example:
+  
+  - **Young:** 106. 198. 306.2 400.1 502. 604. 697.9 806.1 898.1 1004.1 1102. 1200.
+  - **Wendy carlos:** 17/16 9/8 6/5 5/4 4/3 11/8 3/2 13/8 5/3 7/4 15/8 2/1
+  
+  
+  ${makeExample(
+    "Wendy Carlos, here we go!",
+    `
+  z1("s ^ (0,8) 0 0 _ (0,5) 0 0").sound('sine')
+    .scale('17/16 9/8 6/5 5/4 4/3 11/8 3/2 13/8 5/3 7/4 15/8 2/1').fmi(2).fmh(2).room(0.5)
+      .size(0.5).sustain(0.15).delay(0.1)
+      .delay(0.25).delayfb(0.5).out();
+  beat(1, 1.75) :: snd(['kick', 'hat'].beat(1)).out()
+  `,
+    true,
+  )}
+
+${makeExample(
+  "Werckmeister scale in Scala format",
+  `
+  const werckmeister = "107.82 203.91 311.72 401.955 503.91 605.865 701.955 809.775 900. 1007.82 1103.91 1200."
+
+  z0('s (0,3) ^ 0 3 ^ 0 (3,6) 0 _ (3,5) 0 _ 3 ^ 0 (3,5) ^ 0 6 0 _ 3 0')
+    .key('C3')
+    .scale(werckmeister)
+    .sound('sine')
+    .fmi(1 + usine(0.5) * irand(1,10))
+    .cutoff(100 + usine(.5) * 100) 
+    .out()
+  
+  onbeat(1,1.5,3) :: sound('bd').cutoff(100 + usine(.25) * 1000).out()
+`,
+  true,
+)}
+
+`;
+};