• Stars
    star
    259
  • Rank 157,669 (Top 4 %)
  • Language
    TypeScript
  • License
    GNU General Publi...
  • Created over 5 years ago
  • Updated 2 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

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

Flok

build status gitter chat

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/

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.

Sardine

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.

Extra options
  • python: Path to your custom fishery Python REPL. Use this if you need to target a specific install of Sardine (Python version, different path, etc).

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. 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

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

More Repositories

1

tilt

Live coding bytebeat-style language for the web
JavaScript
34
star
2

picopico

🎧 ATtiny85-based chiptune player
JavaScript
29
star
3

hydra-superdirt

A Hydra extension for handling SuperDirt RMS events (envelope follower)
JavaScript
28
star
4

muxy

RTMP-based streaming muxer for online events
Python
27
star
5

browserglue

Exposes multiple OSC connections to the browser through WebSockets
TypeScript
26
star
6

fmtribe

🎵 OPL2/3 synth/drum machine/thingie focused on live jamming for DOS.
C
23
star
7

ppmck

Music Markup Language (MML) compiler for NES - fork of ppmck (version 9a ex11.3 am1)
C
18
star
8

freeling-analyzer-ruby

Ruby wrapper for FreeLing's analyzer tool
Ruby
17
star
9

hydra-p5

A simpler P5 intergration for Hydra
JavaScript
15
star
10

easing-ruby

A Ruby implementation of the well-known Robert Penner's easing functions
Ruby
15
star
11

nsfp

A command-line player of Nintendo NES/Famicom music files (.nsf/.nsfe)
C++
11
star
12

AbjadScore.sc

Render Abjad scores (Lilypond) using SuperCollider Patterns
LilyPond
9
star
13

nes-serial

NES serial communication through input controller with Arduino
Assembly
8
star
14

Marea.sc

Some kind of TidalCycles implementation for SuperCollider
SuperCollider
7
star
15

nesasm

NESASM3, a NES assembler
C
7
star
16

6502asm.js

A 6502 assembler written in Javascript
JavaScript
6
star
17

geoproc

Process geospatial imagery with ease
Python
6
star
18

SuperDirtMIDI.sc

Adds more MIDI in capabilities to SuperDirt
SuperCollider
6
star
19

georuby-pip

GeoRuby extension for asking whether a given point lies inside a polygon
Ruby
6
star
20

layout-analysis

Document layout analysis tools
Ruby
6
star
21

p5-gen-player

P5-based MIDI note visualizer for Martin Grieco's performance (2022-12-05)
JavaScript
6
star
22

freeling-ruby

Ruby bindings for FreeLing, an open source NLP tool suite.
C
5
star
23

arduino

My Arduino sketchbook repository
C++
5
star
24

emscripten-fs-example

An example project for porting a command-line C program to a JavaScript library using Emscripten
C
5
star
25

sinatra-mobile-adsense

Sinatra extension that provides a helper for showing Google Adsense for Mobile.
Ruby
5
star
26

gakuon

🎼 A Music Macro Language (MML) compiler for the Commodore 64 SID chip
JavaScript
5
star
27

SuperDirtMod

SuperDirt extension for parameter modulation of currently running synth nodes
SuperCollider
4
star
28

temposyncd

Reliable music tempo synchronization over the network
Go
4
star
29

shmup-gb

An ugly "shoot'em up" for Gameboy, written with GBDK
C
4
star
30

flok-gui

Cross-platform GUI application for using Flok for collaborative live coding
JavaScript
4
star
31

ejs-brunch

Adds EJS template compilation support to Brunch
JavaScript
4
star
32

vim-tidal-re

(Improved) Vim plugin for TidalCycles
Vim Script
3
star
33

SampleBank.sc

A simple sample bank for managing buffers in SuperCollider
SuperCollider
3
star
34

ripple-ofx

OpenGL editor for Tidal
C++
3
star
35

lug

Small Ruby logger for debugging libraries and applications
Ruby
3
star
36

exploro

Experimental NLP analyzer with PoS tagging and Named-Entity Recognition and Classification on documents
CSS
3
star
37

nobounds

SuperCollider
3
star
38

katmai

*Dropped* A pretty much useless x86 microkernel + bootloader with some basic services and drivers. For learning purposes.
C
3
star
39

siddump

An utility that executes .SID file player code and outputs SID chip register & note data
C
3
star
40

threejs-3d-sound-sandbox

ThreeJS example of 3D sound simulation using PositionalAudio and extra filters
JavaScript
3
star
41

sequel-mysql_json

Sequel extension and plugin that adds support for MySQL JSON columns
Ruby
3
star
42

sid.js

SID chip synthesizer emulator for Javascript
JavaScript
3
star
43

hydra-gists

Gallery of Hydra snippets, based on GitHub Gist
JavaScript
3
star
44

supervisor-capistrano

Supervisor integration for Capistrano
Ruby
2
star
45

trenes-ba

Estadísticas sobre el servicio de trenes Mitre / Sarmiento
Ruby
2
star
46

wisper-sequel

A Sequel plugin for broadcasting model hooks as Wisper events.
Ruby
2
star
47

poser

Estimate pose from a webcam and detect motion changes to trigger WebSocket/OSC messages.
JavaScript
2
star
48

shelter-py

Another cross-platform ASCII/ANSI art drawing tool
Python
2
star
49

opentidal

Web based TidalCycles repository and AI code generator
Python
1
star
50

spuriOS

SpuriOS ~ the best x86 monolithic kernel you'll ever know (probably not)
C
1
star
51

hasteroids

Asteroids clone in Haskell and OpenGL
Haskell
1
star
52

rampi

Rampi is a REPL for Rampcode, a bytebeat interpreter for Puredata
Ruby
1
star
53

dominio-publico

Calculadora de Dominio Público en Argentina
JavaScript
1
star
54

dots

Homesick compatible dotfiles repository
Lua
1
star
55

marea

Yet another musical pattern language based on TidalCycles for building higher-level musical patterns.
Ruby
1
star
56

votalo-botalo

Votalo o Botalo: Parlamento 2.0 (proyecto de #HackatonMza)
JavaScript
1
star
57

ld26

LD48 ~ minimalism: "hexfree"
Ruby
1
star
58

strudel-starter

JavaScript
1
star
59

c64-stuff

Code samples of different C64 techniques and effects
Assembly
1
star
60

pso-slides

Beamer slides for a talk about "Virtual Memory Primitives for User Programs" (spanish)
1
star
61

baransa

Baransa is a forward proxy written in Ruby that balances load and limits request per endpoint
Ruby
1
star
62

rawmidi-ruby

Ruby FFI binding for ALSA RawMIDI
C
1
star
63

FlokQuark

Allows you to use SuperCollider with Flok
SuperCollider
1
star
64

isw1-20181c

Smalltalk
1
star
65

temposync-sc

TempoSync quark for Supercollider
SuperCollider
1
star
66

gakuon-editor

Visual editor for Gakuon, an MML compiler for the C64 SID chip
TypeScript
1
star