Web-based P2P collaborative editor for live coding music and graphics
New version v1.0 in the works. Visit branch flok-next for more info!
Check out the new version (still WIP!) online here: https://next.flok.cc/
- 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.):
- TidalCycles
- SuperCollider (sclang)
- FoxDot
- Mercury
- Sardine
- SonicPi (not implemented yet)
- ... any interpreter with a REPL (Python, Ruby, etc.)
- Web Plugins, for languages embedded in editor:
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.
Right now, the easiest way to use Flok is to install the repl and web
packages.
npm install -g flok-repl flok-webIf 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.
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):
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 withsclangand the last 2 withhydra.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! :-)
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-52932de15a5dIf 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.
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-webYour 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-52932de15a5dYour 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-52932de15a5dUse 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 }'
-
bootScript: Path to a custom initialization script. -
useStack: Usesstack exec -- ghciinstead of plainghci. Use this if you installed Tidal using Stack. -
ghci: Use a specific Ghci command instead of plainghci. This overridesuseStackoption, if used too.
Use flok-repl with the -t sardine parameter. In order to make it work,
the fishery REPL must be included to your PATH. It should already be the
case if you followed a regular install.
python: Path to your customfisheryPython REPL. Use this if you need to target a specific install of Sardine (Python version, different path, etc).
Use flok-repl with the -t foxdot parameter.
python: Path to Python binary. Use this if you need to use a custom Python version.
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.
-
As of today
sclangdoes not currently work on Windows, you will have to useremote_sclang. -
remote_sclangneeds 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. -
sclangcan't use any GUI object (like Scopes, Proxy mixers, etc.). You will need to useremote_sclang+ SC IDE for this.
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 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
After unpacking or cloning, from the directory of the repository run:
yarnThis 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.
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.
This project is licensed under GPL 3+. Refer to LICENSE.txt