Web-based P2P collaborative editor for live coding music and graphics
- Similar to Etherpad, but focused on code evaluation for livecoding.
- Multiple separate slots for different languages and tools.
- 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, see #29)
- ... any interpreter with a REPL (Python, Ruby, etc.)
- Web Plugins, for languages embedded in editor:
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:
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:
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.
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.
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:munshkrThis 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.
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@latestYou 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@latestThis 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.
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 --secureSharing 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.
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 }'
-
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 sardine REPL must be included to your PATH. It should already be the
case if you followed a regular install.
python: Path to your customsardinePython 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 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.
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
Install all dependencies and build all subpackages with:
npm install
npm run buildThen, to run web server:
cd packages/web
npm run devTo run production build:
npm startThis 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:
flok-web: Web Server for Flokflok-repl: REPL Client for Flokflok-server: Flok server, handles sessions and communication between clients.
@flok-editor/pubsub: Pub/Sub client-server, used for remote code execution and message passing on Flok@flok-editor/session: Flok session package@flok-editor/server-middleware: Server middleware for Flok, handles WebSocket connections and WebRTC signaling@flok-editor/cm-eval: CodeMirror 6 extension for code evaluation@flok-editor/lang-tidal: TidalCycles language support for CodeMirror 6
example-vanilla-js: Example of a Flok-based collaborative editor written in pure JS and Vite
- Include a simplified vanilla JS example
- Use CodeMirror 6
- Best code editor library for the Web
- Latest version (v6) comes with better extensibility and accesability
- Use Yjs for collaborative editor
- Battle-tested and updated
- Now supports CodeMirror 6: y-codemirror.next
- More modular and extensible, similar to CodeMirror extensions, e.g.:
- Line/block-based evaluation:
@flok-editor/cm-eval - TidalCycles pattern and RMS decorators:
@flok-editor/cm-tidalcycles-decorators - TidalCycles autocompletion:
@flok-editor/cm-tidalcycles-autocompletion - Hydra synth autocompletion:
@flok-editor/cm-hydra-autocompletion
- Line/block-based evaluation:
- Better UI for customizing editor and session configuration
- Menu, toast, dialogs
- nice to have Import external JS libraries dynamically, instead of bundling
them with Flok
- Similar to JS playgrounds, like codesandbox.io
- User can have their own set of libraries to be loaded automatically or easily on new sketches
- Connect to local filesystem for files and libraries
username(string): Default user name. Eg:#username=arbortargets(list of strings): If session is empty, configure it with the specified targets by default. Eg:#targets=hydra,strudelc0,c1, ...,c7(string): Default code to load on each document/pane (if available). Code must be encoded in Base64. Eg:#c0=bm9pc2UoKS5vdXQoKQ%253D%253D(decodes tonoise().out()).code(string): An alias ofc0(see above)
readOnly(boolean): Disable editing. If true, it won't ask for a user name when loading.bgOpacity(number): Background opacity. Valid range: [0, 1]noWebEval(list of strings): Disable evaluation of the specified web targets. Useful for embedding Flok in a website, where the website already has its own evaluation mechanism. This still sends messages to parent window. Options:*,[webTarget]. Eg:?noWebEval=hydradisables only Hydra.?noWebEval=*disables all web targets.hideErrors(boolean): Do not show errors for web targets (hydra, strudel, etc)
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.
change: When the session changes. This usually happens at the beginning, when the session is empty, and when the user changes the targets.
{
"event": "change",
"documents": [
{
"id": "1",
"target": "hydra",
"content": "osc().out()"
},
{
"id": "2",
"target": "tidal",
"content": "d1 $ s \"bd\""
}
]
}eval: On evaluation. This happens when the user presses the "Run" button or when the user presses one of the shortcuts for evaluating (e.g.Ctrl+Enter) on the editor. Only the content of the document that was evaluated is sent.
{
"event": "eval",
"id": "2",
"content": "d1 silence",
"user": "munshkr"
}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
Favicon based on "Origami" by Andrejs Kirma, from Noun Project (CC BY 3.0)
![dependabot[bot] avatar](https://avatars.githubusercontent.com/in/29110?v=4 "dependabot[bot]")
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent