/flok

Web-based P2P collaborative editor for live coding sounds and images

Primary LanguageTypeScriptGNU General Public License v3.0GPL-3.0

Flok

build status gitter chat

Web-based P2P collaborative editor for live coding music and graphics

Work in progress

Features

  • Similar to Etherpad, but focused on code evaluation for livecoding.
  • REPL plugins: allows user to locally evaluate code from interpreters (like Haskell, Ruby, Python, etc.):
  • Web Plugins, for languages embedded in editor:

Requirements

Flok is written in TypeScript and Nodejs. You will need to have installed Node versions 10+. The LTS version (currently 14) is recommended.

Go here to download Node.

Install

Right now, the easiest way to use Flok is to install the repl and web packages.

npm install -g flok-repl flok-web

If this command fails with permission errors (known issue on some Debian/Ubuntu installs), you should follow this guide.

In the future there will also be a single portable GUI application that will contain everything, but for now you'll have to use the terminal.

Usage

Public server

WARNING - Please Read: Using a public server can be dangerous as anyone can execute code on your computer via Flok, so please make sure you only share your session URL to trusted users and friends when you use a public server. I will not be held responsible for any damaged caused by Flok. You have been warned. There is an issue assigned to mitigate this security problem.

This is a list of known public servers (up-to-date):

Create a session

When you enter a Flok server, you will be prompted to enter a list of targets. A target is the language or tool that Flok will communicate to create sound through flok-repl.

Enter the name of the targets, separated with commas. You can use a target multiple times and Flok will create that many number of slots to write code. Currently the maximum number of slots is 8.

Examples:

  • tidal,foxdot,hydra: 3 slots, with tidal, foxdot and hydra respectively.
  • sclang,sclang,sclang,hydra,hydra: 5 slots total, the first 3 with sclang and the last 2 with hydra.
  • mercury, hydra: 2 slots total, one with Mercury and one with Hydra.

Now click on Create session.

You will now be shown a token and asked for a nickname. Save the token, as you will need it next for starting the REPL. Optionally copy the repl-code to easily paste in the terminal and hook up your repl. Enter your nickname and click on Join.

You are ready to start writing. Share the URL to your friends so they can join the session! :-)

Connect REPLs to Flok

The last step is to start flok-repl, to connect Flok with your REPLs.

You will need to specify the server (prefixing with wss://) where you created the session (or where you were invited to), the session token and the kind of REPL you want to start.

For example, if your session token is 1a0c2df3-5931-46dd-9c7c-52932de15a5d, to start a tidal REPL, run the following:

flok-repl -H wss://flok-hub.herokuapp.com -t tidal -s 1a0c2df3-5931-46dd-9c7c-52932de15a5d

If you need to start multiple REPLs, you will need to run them on separate terminals as currently flok-repl supports only one REPL at a time.

Local server

In case you don't have an Internet connection and/or you don't want to play Flok on a public server, you can easily start a local Flok server.

To start the server, simply run:

flok-web

Your local server will be available on http://localhost:3000 from your computer. To share the URL with your friends, change localhost with your local IP. See how to find your local and external IP address.

Follow the instructions on Remote server - Create a session section above.

When starting the REPL, make sure to use ws://, not wss://, because currently the local server runs only on http, not https.

Using the same example as in the previous section:

flok-repl -h ws://localhost:3000 -t tidal -s 1a0c2df3-5931-46dd-9c7c-52932de15a5d

Your friends would need to use your local IP. Suppose your IP is 192.168.0.5, then they should run:

flok-repl -h ws://192.168.0.5:3000 -t tidal -s 1a0c2df3-5931-46dd-9c7c-52932de15a5d

Supported REPL targets

TidalCycles

Use flok-repl with the -t tidal parameter.

You can specify custom options with the --extra parameter, by passing a JSON object, like this:

--extra '{ "bootScript": "/path/to/my/boot.hs", "useStack": true }'

Extra options

  • bootScript: Path to a custom initialization script.

  • useStack: Uses stack exec -- ghci instead of plain ghci. Use this if you installed Tidal using Stack.

  • ghci: Use a specific Ghci command instead of plain ghci. This overrides useStack option, if used too.

FoxDot

Use flok-repl with the -t foxdot parameter.

Extra options
  • python: Path to Python binary. Use this if you need to use a custom Python version.

SuperCollider

In the case of SuperCollider, there are two types of REPLs: sclang and remote_sclang. The first one tries to run a sclang process and interact with it, while the second one uses FlokQuark to communicate with SC. Read more for installing and using it.

sclang vs. remote_sclang

  • As of today sclang does not currently work on Windows, you will have to use remote_sclang.

  • remote_sclang needs SC IDE to be running, and you need FlokQuark installed and running there.

  • If you use remote_sclang, you won't see Post messages from Flok, because FlokQuark does not currently capture Post messages and errors. It is recommended to deattach the Post window and have it visible while using Flok.

  • sclang can't use any GUI object (like Scopes, Proxy mixers, etc.). You will need to use remote_sclang + SC IDE for this.

Hydra

Hydra is already included in the web App. You don't need to install anything as it runs on the browser. Just use the hydra target to execute Hydra code.

If you want to use the screen capturing feature, you will need to install a specific Chrome extension for Flok, that gives permissions to capture the desktop screen from within the current public servers.

Read more on how to install the extension.

Mercury

Mercury is a minimal and human readable language for livecoding of algorithmic electronic music. Follow these steps to connect Flok to the Mercury livecoding environment:

First make sure you have installed Mercury and flok-repl properly.

  1. Install Mercury via the quick start quide.
  2. Install the flok-repl globally with npm install -g flok-repl.

Now follow these steps for a succesful setup.

  1. Setup Flok with target mercury and click Create session.
  2. Copy the flok-repl -H xxx -s xxx -t mercury command to run in the terminal at step 4.
  3. Join the Flok with your nickname.
  4. Run the copied flok-repl command in the terminal. Or manually set it up with argument -t mercury.
  5. Enable Audio and optionally Visuals in Mercury to hear sound.

Now start typing some code! 🎵

  • Ctrl/Alt + Return to evaluate
  • Ctrl/Alt + . to silence

Flok will send the entire code via OSC messaging to port 4880. Mercury should be listening to this port automatically. Bug reports are welcome in the issues. If the issue is more Mercury than Flok related please report here

Development

After unpacking or cloning, from the directory of the repository run:

yarn

This will install dependencies from all packages, and prepare (build) packages.

If you have Node 13+, you might have an error about an incompatible package (meyda). Try running yarn --ignore-engines to skip that check. You can also config yarn to ignore this automatically from now on, by running yarn config set ignore-engines true.

web, repl and core packages are stored on the packages/ directory, and there is a root packaged managed by Lerna.

Lerna allows us to manage interdependant packages easily. In the case of Flok, the core package is used both by web and repl, and even though they have flok-core dependency on their package.json, Lerna creates symbolic links to the local core package automatically. It also makes it easy to publish new versions by bumping them together.

To bump a new version on all packages and release them together, run yarn release.

Acknowledgments

Contributing

Bug reports and pull requests are welcome on GitHub at the issues page. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

License

This project is licensed under GPL 3+. Refer to LICENSE.txt