flok

Flok

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

Features

Usage

Keybindings

Some keybindings may differ depending on the language/target you choose, and the operating system

Keybinding Function
alt/option enter Evaluate all
ctrl/cmd enter Evaluate block, Evaluate selection
shift enter Evaluate line
ctrl/cmd/option/alt . Silence (output depends on language)
cmd/ctrl shift h Show/Hide editor panels
cmd/ctrl x Cut selected text
cmd/ctrl c Copy selected text
cmd/ctrl v Paste cut/copied text
cmd/ctrl z/u Undo edit
cmd/ctrl shift z/u Redo edit
cmd/ctrl } add indentation
cmd/ctrl { remove indentation
cmd/ctrl f search and replace

On Mac:

ctrl e jump to end of the line
ctrl a jump to the beginning of the line
ctrl t move character one step right
ctrl y delete selected text
ctrl o insert linebreak
ctrl d delete character on the right of cursor
ctrl h backspace character on the left of cursor
ctrl l select whole line after cursor
ctrl v jump to bottom end
ctrl b move cursor to the left
ctrl n move cursor down

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.

This is a list of known public servers:

Create a session

When you enter a Flok server, you will be shown an empty session with a single slot, with a target selected (usually hydra). You can either change the target by clicking on the target selector at the top-left corner of the slot, or add more slots by clicking on the Command button (at the top-right corner of the screen), and then clicking on Add Pane, or Configure.

A target is the language or tool that Flok will communicate to create sound or images within the web page, or through flok-repl.

If you clicked on Configure, 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:

You will also be asked to enter a nickname. This is the name that will be shown to other users under your cursor, when you write code. You can change it any time by clicking on the Change Username inside the Command menu.

Now, just copy the URL and share it with your friends! They will be able to join the session and write code with you :-)

If you are using any target that requires a REPL, you will need to start it separately. See the Connect REPLs to Flok section below.

Connect REPLs to Flok

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

Just click on the REPLs button at the top-right corner of the screen, and copy the command shown there. It will look something like this:

npx flok-repl@latest -H wss://next.flok.cc \
  -s mammoth-tan-roundworm-17a5d501 \
  -t tidal \
  -T user:munshkr

This command will automatically try to download and install flok-repl and start it, connecting it to your session. If you have multiple different targets with REPLs, the command will start one process for each target from the same command.

Local server

In case you want to use Flok without 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:

npx flok-web@latest

You can also install both web and repl packages beforehand (e.g. if you already know you won’t have internet access on the venue) with:

npm install -g flok-web@latest flok-repl@latest

This will download and install the latest Flok web version and start a server.

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 LAN IP. flok-web will try to guess your local IP in your LAN, and show it on the console, but it might not always work.

Secure mode (https)

In some cases, it’s needed to run Flok in secure mode, using https. This is needed for some browsers, like Chrome, to allow access to the microphone and camera (which might be needed for some targets, like Hydra). You can easily run Flok in secure mode by passing the --secure parameter:

npx flok-web@latest --secure

Note about remote users (not LAN)

Sharing your local server to other users in the Internet is a bit more complicated, and it depends on your router and network configuration. You will need to configure your router to forward the port 3000 to your computer, and then share your public IP with your friends. You can find your public IP by visiting https://whatismyipaddress.com/. Also make sure to check your firewall settings, to allow incoming connections to port 3000. It’s possible that some of your remote friends won’t be able to connect to your local server, because of their own network configuration.

Supported REPL targets

Dummy

The “dummy” target is a REPL target that forwards messages to an OSC server. It does not have any syntax highlighting and can be used for any purpose you like. This is useful if you want to use a language that is not yet supported in Flok, and can receive OSC messages.

Use flok-repl with the -t dummy parameter.

By default, it will send OSC messages to port 3001. Code evaluations are sent as a string (including all line breaks, whitespaces, etc.) to the OSC address /flok. If you use the panic shortcut key, you will receive the OSC message /flok silence, which you can use to stop all your audio/visual processes.

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

Sardine

Use flok-repl with the -t sardine parameter. In order to make it work, the sardine REPL must be included to your PATH. It should already be the case if you followed a regular install.

Extra options

FoxDot

Use flok-repl with the -t foxdot parameter.

Extra options

Renardo

Renardo is a new maintained fork of FoxDot with new features.

Use flok-repl with the -t renardo parameter.

Extra options

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

Hydra

Hydra is a video synth and coding environment, inspired in analog video synthesis, that runs directly in the browser and 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.

You can also use p5.js within a hydra target, like you would in the official Hydra editor.

P() function

The P() function allows you to use strudel mini-patterns in Hydra. It uses the same timing information as Strudel itself, so it will be synchronized with the audio.

Note: It will only work, if strudel is already initialized, because that will load the modules we need. Note: You can not use any strudel functions on the pattern. Note: Currently we do not have mini-highlighting for Hydra panes.

useStrudelCanvas(source)

Will initialise the given source (s0, s1, etc) to use the strudel canvas as a source. Will also hide the strudel canvas, so it will not overlap.

Note: Strudel will have to be initialized, otherwise this will not work.

fft() function

The fft() function is a special function that allows you to get the FFT data from web targets.

Note: Only Strudel is supported at the moment.

You can disable the FFT visualizer in the display settings. This might help with performance.

fft(index: number,
    buckets: number = 8,
    options?: { min?: number; max?: number, scale?: number, analyzerId?: string }): number

Parameters:

Example:

solid(() => fft(0, 1), 0)
  .mask(shape(5, 0.05))
  .rotate(() => 50 * fft(0, 40)); // we need to supply a function
// for the parameter, for it to update automaticaly.

Caveat: Because of how we setup the analyze node on Strudel, every Strudel pane needs a re-eval after the Hydra code decides that we need to get the fft data. This does not happen automatically, manual re-eval is necessary.

Mercury

Mercury is a minimal and human readable language for livecoding of algorithmic electronic music. Below is a link to steps for connecting Flok to either the Mercury Playground (browser based) or the Max8 version of the livecoding environment:

Follow the step-by-step guide here

Bug reports are welcome in the issues. If the issue is more Mercury than Flok related please report here

Development

Basic setup

Install all dependencies and build all subpackages with:

npm install
npm run build

Then, to run web server:

cd packages/web
npm run dev

To run production build:

npm start

To run the repl while developing go to:

cd packages/repl/

npm exec -- flok-repl -H ws://localhost:3000 -s <session> -t <target> -T user:<name>

Packages overview

This repository is a monorepo, with multiple modular packages. Each package has its own README with more information. Here is a brief overview of the packages:

App packages

Lib packages

Examples

Design constraints (v1.0)

Hash parameters

Query parameters

Window messages

Flok will post messages to the parent window on specific events. This is useful for embedding Flok in a website, where the website can handle the evaluation of the code.

Events

{
  "event": "change",
  "documents": [
    {
      "id": "1",
      "target": "hydra",
      "content": "osc().out()"
    },
    {
      "id": "2",
      "target": "tidal",
      "content": "d1 $ s \"bd\""
    }
  ]
}

{
  "event": "eval",
  "id": "2",
  "content": "d1 silence",
  "user": "munshkr"
}

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.

Punctual is licensed under GPL 3+. Refer to LICENSE.

Favicon based on “Origami” by Andrejs Kirma, from Noun Project (CC BY 3.0)

This site is open source. Improve this page.