dktr0 / extramuros

language-neutral shared-buffer networked live coding system

extramuros - language-neutral shared-buffer networked live coding system

See install-osx.md, install-win.md or install-linux.md for installation instructions. See this document for usage.

The big picture: This is software for collaborative live coding. On one machine, you run an extramuros "server". Then, from as many machines as you like, you use a web browser to connect to the server and code into shared text buffers. Finally, and again from as many machines as you like, your run the extramuros "client" code in order to receive code from the server and pipe it to the language interpreter of your choice (SuperCollider, Tidal, etc). Think of the "client" code as a way for machines to listen in on a public stream of code.

The connections between the web browsers, the server, and the client are structured to make it easier to do collaborative live coding across various firewalls, institutional networks, etc. Both the web browser and the client are making "outbound" TCP connections to the server. So long as the server is generally reachable you don't have to worry about the web browsers and clients being firewalled. (Moreover: This type of collaborative live coding is also robust to bandwidth challenges as it generally just involves sending small bits of text back and forth.)

To launch a server (only one person in a collaborative performance group needs to do this) - and assuming extramuros has been cloned/downloaded to your user folder:

cd ~/extramuros
node server.js --password insertFunnyPasswordHere

To verify that the server is running, point your browser to the IP address of the server and port 8000. If the server is not running on your local machine, replace 127.0.0.1 with the actual address of the server in the following (and in all subsequent examples):

http://127.0.0.1:8000

To launch a test client just to verify that you can listen in on the code as people click "eval" in the browser. (note: If you already have a server in one terminal window it is convenient to launch the client in a second terminal window):

cd ~/extramuros
node client.js --server 127.0.0.1

To test, enter some code into the text buffers in the web browser, make sure you have entered the funny password you chose (forgetting to enter the password in the browser window is a common mistake) and click "eval". If everything is working, you should see the code from the browser appear in the terminal where you launched node client.js. By the way, you can terminate the client (or server) by pressing Ctrl-C twice in the relevant terminal window.

If that test worked, you're ready to launch a client piped into a language interpreter. Here's a slightly abstract example of what that would look like:

cd ~/extramuros
node client.js --server 127.0.0.1 | pathToYourFavouriteInterpreter

For SuperCollider, one strategy is to pipe the text to sclang. This is an example using a default SC installation on OSX (and assuming extramuros has been cloned into your user folder). We use the --newlines-to-spaces option so that line breaks in the browser will become spaces in the code sent to SuperCollider, allowing you to stretch expressions over multiple lines. Note that you won't have cmd-period to interrupt your SC synths, so it's helpful to have other ways of stopping/freeing things:

cd /Applications/SuperCollider/SuperCollider.app/Contents/Resources/
node ~/extramuros/client.js --server 127.0.0.1 --newlines-to-spaces | ./sclang

You can also use short options, in which case the last line of the preceding example would be as follows:

node ~/extramuros/client.js -s 127.0.0.1 -n | ./sclang

You can send arbitrary OSC messages to the client and they will arrive at all browsers as calls to JavaScript functions with the same name as the OSC address (i.e. "/amp 0.5" becomes the call amp(0.5);). To activate this function on the client use the osc-port option AND specify the password (anything that sends things to the server needs a password!):

cd ~/extramuros
node client.js --server 127.0.0.1 --osc-port 8000 --password yourFunnyPasswordHere| ./sclang

Another command-line option launches Tidal as a sub-process of the client. Note that the extramuros distribution includes a file .ghci which helps establish a useful working environment for Tidal, and that because of this you should probably be in the extramuros folder when you start the client for Tidal. There are two main options for starting tidal - --tidal if you installed Tidal with stack, --tidalCabal if you installed Tidal with cabal:

cd ~/extramuros
node client.js --server 127.0.0.1 --tidal

cd ~/extramuros
node client.js --server 127.0.0.1 --tidalCabal

In addition to being more convenient than the command-line pipes used above with SuperCollider, this option also allows for feedback from a client to reach the server and thus be displayed in the browser windows:

cd ~/extramuros
node client.js --server 127.0.0.1 --tidal --feedback

To really get cooking with extramuros and Tidal, activate the osc-port option as well. You'll have feedback from the ghci/Tidal interpreter AND the browser will receive JavaScript function calls when Tidal notes/events happen:

cd ~/extramuros
node client.js --server 127.0.0.1 --tidal --feedback --osc-port 8000 --password yourFunnyPassword

Now in the web browser, enter some code, make sure you have entered the correct password, and click "eval". Not only should you see the evaluated code in the terminal - hopefully you will also hear it's effect!

There are a number of keyboard short cuts:

• Shift-Enter: evaluate code through the server (i.e. Tidal or SuperCollider code)
• Ctrl-Shift-Enter: evaluate JavaScript code on all browsers
• Ctrl-Enter: evaluate JavaScript code on only this browser
• Ctrl-Shift-C: clear the JavaScript canvas on all browsers
• Alt-C: clear the JavaScript canvas on this browser only
• Ctrl-Shift-R: restart animation if it has crashed, on all browsers
• Alt-R: restart animation it it has crashed, on this browser only

For more information about JavaScript visuals/animation in extramuros, see the document visualizationexamples.md.

All of this is rough, unfriendly and probably even mistaken in some cases. So let's all help make it better!...

-d0kt0r0 (aka David Ogborn)

PS: thanks to the following people for contributing to extramuros in various ways (additions, fixes, testing, championing, etc): Holger Ballweg, Alexandra Cárdenas, Ian Jarvis, Alex McLean, Ashley Sagar, Eldad Tsabary, Scott Wilson and anyone else who should be named here (submit a pull request...)

extramuros's Issues

Issue with installation

I have followed the instruction to install extramuros, but the system is not able to complete it. these are the errors as reported in the prompt.
Does anyone can help me?
C:\Windows\System32\extramuros>npm install
npm WARN package.json [email protected] No repository field.
npm WARN package.json [email protected] No license field.
/

[email protected] install C:\Windows\System32\extramuros\node_modules\zmq
node-gyp rebuild

C:\Windows\System32\extramuros\node_modules\zmq>if not defined npm_config_node_gyp (node "C:\Program Files\nodejs\node_modules\npm\bin\node-gyp-bin....\node_modules\node-gyp\bin\node-gyp.js" rebuild ) else (node "" rebuild )
gyp: binding.gyp not found (cwd: C:\Windows\System32\extramuros\node_modules\zmq) while trying to load binding.gyp
gyp ERR! configure error
gyp ERR! stack Error: gyp failed with exit code: 1
gyp ERR! stack at ChildProcess.onCpExit (C:\Program Files\nodejs\node_modules\npm\node_modules\node-gyp\lib\configure.js:305:16)
gyp ERR! stack at emitTwo (events.js:87:13)
gyp ERR! stack at ChildProcess.emit (events.js:172:7)
gyp ERR! stack at Process.ChildProcess._handle.onexit (internal/child_process.js:200:12)
gyp ERR! System Windows_NT 10.0.14393
gyp ERR! command "C:\Program Files\nodejs\node.exe" "C:\Program Files\nodejs\node_modules\npm\node_modules\node-gyp\bin\node-gyp.js" "rebuild"
gyp ERR! cwd C:\Windows\System32\extramuros\node_modules\zmq
gyp ERR! node -v v4.6.0
gyp ERR! node-gyp -v v3.4.0
gyp ERR! not ok
npm ERR! Windows_NT 10.0.14393
npm ERR! argv "C:\Program Files\nodejs\node.exe" "C:\Program Files\nodejs\node_modules\npm\bin\npm-cli.js" "install"
npm ERR! node v4.6.0
npm ERR! npm v2.15.9
npm ERR! code ELIFECYCLE

npm ERR! [email protected] install: node-gyp rebuild
npm ERR! Exit status 1
npm ERR!
npm ERR! Failed at the [email protected] install script 'node-gyp rebuild'.
npm ERR! This is most likely a problem with the zmq package,
npm ERR! not with npm itself.
npm ERR! Tell the author that this fails on your system:
npm ERR! node-gyp rebuild
npm ERR! You can get information on how to open an issue for this project with:
npm ERR! npm bugs zmq
npm ERR! Or if that isn't available, you can get their info via:
npm ERR!
npm ERR! npm owner ls zmq
npm ERR! There is likely additional logging output above.

npm ERR! Please include the following file with any support request:
npm ERR! C:\Windows\System32\extramuros\npm-debug.log

using Foxdot

Is there a simple way to use foxdot with extramuros? I thought it supported it, but I don't see foxdot mentioned in this repository or its issues.

Linux install instructions

Probably won't work on Ubuntu 14 or 16 since nodejs-legacy and npm are not the way to install node anymore

Problems setting up extramuros - not sure if its a tidal problem...

Hello, I'm still trying to get extramuros working, but I'm not sure I've got it linking up to tidal properly. I'm running ubuntu 14.10. I think everything is installed correctly as I can use tidal via emacs. and the extramuros server appears to be working.

I start the server using

cd ~/extramuros
node server.js --password wibble

Then I start the client:

node client.js --server 127.0.0.1 --tidal --feedback --osc-port 8000 --password wibble

I open the browser window and enter the password, then try some tidal code in the first window:

d1 $ interlace (sound  "bd sn kurt") (every 3 rev $ sound  "bd sn:2")

This gives me the following error in the notification window:

<interactive>:2:1: Not in scope: `d1'

<interactive>:2:6:
    Not in scope: `interlace'
    Perhaps you meant `interact' (imported from Prelude)

<interactive>:2:17:
    Not in scope: `sound'
    Perhaps you meant `round' (imported from Prelude)

<interactive>:2:39: Not in scope: `every'

<interactive>:2:47:
    Not in scope: `rev'
    Perhaps you meant `rem' (imported from Prelude)

<interactive>:2:53:
    Not in scope: `sound'
    Perhaps you meant `round' (imported from Prelude)
Prelude> Prelude> 

..which looks to me like a tidal problem. I've also tried this by starting dirt before the above but I get the same error.

I'd be grateful if you could tell me what you think the problem might be. I'm thinking that the client isn't hooking up to tidal properly, but I don't know how to fix it

thanks,

Simon

Instructions fail with TidalCycles on Debian

Hey, thanks for this project! Sadly I wasn't able to sucessfully connect with TidalCycles on Debian:

Setup

• Machine:

$ uname -a
Linux PLN-THINK-DEB 4.9.0-12-amd64 #1 SMP Debian 4.9.210-1 (2020-01-20) x86_64 GNU/Linux

$ lsb_release -a                                                                                                            
No LSB modules are available.
Distributor ID:	Debian
Description:	Debian GNU/Linux 9.12 (stretch)
Release:	9.12
Codename:	stretch

• Installed with git clone then npm install -g extramuros (NPM v6.14.2).

Problem

• Having installed Tidal with Cabal, I tried the --tidalCabal`` option: Tidal starts successfully, but seems to fail on the definition of functions like anticipate`:

Command

node client.js --server 127.0.0.1 --tidalCabal --feedback                                                                                                                                         

Stack trace

extramuros: connecting to ws://127.0.0.1:8000...
extramuros: connected to ws://127.0.0.1:8000
Tidal/GHCI initialized
GHCi, version 8.0.1: http://www.haskell.org/ghc/  :? for help

Prel
ude> 
Prel
ude> 
Some flags have not been recognized: prompt-cont, 

Liste
ning for controls on 127.0.0.1:6010
Control listen failed. Perhaps ther
e's already another tidal instance listening on that port?



<in
teractive>:17:29: error:
    • Couldn't match type
 ‘Bool’ with ‘Pattern ControlMa
p’
      Expected type: ControlP
attern
        Actual type: Bool
  
  • In the second argument of ‘streamOnce’, namely 
‘False’
      In the expression: stream
Once tidal False
      In 
an equation for ‘once’: once = 
streamOnce tidal False


<
interactive>:18:29: error:

    • Couldn't match 
type ‘Bool’ with ‘Patt
ern ControlMap’
      Expected 
type: ControlPattern
     
   Actual type: Bool
    • In the second argument of 
‘streamOnce’, namely ‘True’
     
 In the expression: streamOnce tidal Tr
ue
      In an equation for ‘asap’:
 asap = streamOnce tid
al True


<
interactive>:22:14: error:

    Variable not in scope:
 asap :: ControlPattern -> c


<
interactive>:23:33: error:
    • Couldn't m
atch expected type ‘Bool’

                  with actual type 
‘Time -> [Contro
lPattern] -> ControlPattern’

    • Probable cause: ‘xfadeIn’ is applied to too few arguments
   
   In the second argument of ‘transition’, namely ‘(
xfadeIn 4)’
      In the expression: tra
nsition tidal (xfadeIn 4)
 i
      In an equation for ‘xfade’:

          xfade i = transiti
on tidal (xfadeIn 4) i



<interactive>:24:37: error:

    • C
ouldn't match expected type 
‘Bool’
                  with actual
 type ‘Time -> [ControlPatt
ern] -> ControlPattern’
 
   • Probable cause: ‘xfadeIn’ is applied to too few arguments
     
 In the second argument of ‘transition’, namely ‘(
xfadeIn t)’
      In the expression: tra
nsition tidal (xfadeIn t
) i
      In an equation for ‘xfadeIn
’:
          xfadeIn i t = 
transition tidal (xfadeIn
 t) i



<interactive>:25:37: error:

    • C
ouldn't match expected 
type ‘Bool’
                  with 
actual type ‘Time -> [Con
trolPattern] -> ControlPa
ttern’
    • Probable cause: ‘histpa
n’ is applied to too few arguments
      In the second argument of ‘transi
tion’, namely ‘(histpan t)’
  
    In the expression: transition tidal
 (histpan t) i
      In an
 equation for ‘histpan’:
          his
tpan i t = transition ti
dal (histpan t) i



<interactive>:26:34: error:

    
• Couldn't match expe
cted type ‘Bool’
                  w
ith actual type ‘Time ->
 [ControlPattern] -> Cont
rolPattern’
    • Probable cause: ‘wai
t’ is applied to too few arguments
      In the second argument of ‘trans
ition’, namely ‘(wait t)’
    
  In the expression: transition tidal 
(wait t) i
      In an equation for 
‘wait’: wait i t = t
ransition tidal (wait t) 
i



<interactive>:27:37: error:

    • Co
uldn't match expected t
ype ‘Bool’
                  with 
actual type ‘Time -> [C
ontrolPattern] -> Control
Pattern’
    • Probable cause: ‘waitT’ is applied to too few arguments

      In the second argument of ‘transitio
n’, namely ‘(waitT f t)’
      In the expression: transition tidal (waitT f t) i
 
     In an equation for ‘waitT’:
        
  waitT i f t = tran
sition tidal (waitT 
f t) i



<interactive>:28:32: error:

    • Co
uldn't match expect
ed type ‘Bool’
                
  with actual type
 ‘Time -> [ControlPa
ttern] -> ControlPat
tern’
    • Probable cause: ‘jum
p’ is applied to too few arguments
      In the second argument of ‘t
ransition’, namely ‘(jump
)’
      In the expression: transi
tion tidal (jump) 
i
      In an equation for ‘jump
’: jump i = tran
sition tidal (jump)
 i


<
interactive>:29:36: error:

    • Could
n't match expected ty
pe ‘Bool’
                  with
 actual type ‘Time
 -> [ControlPattern] ->
 ControlPattern’
 
   • Probable cause: ‘jumpIn’ is applied to too few arguments
  
    In the second argument of ‘transit
ion’, namely ‘(jumpIn t)’

      In the expression: transitio
n tidal (jumpIn t) i

      In an equation for ‘jumpI
n’:
          jumpIn 
i t = transition tid
al (jumpIn t) i



<interactive>:30:37: error:

    • Couldn
't match expected 
type ‘Bool’
                 
 with actual type 
‘Time -> [Control
Pattern] -> Contro
lPattern’
    • Probable cause:
 ‘jumpIn'’ is applied to too few arguments
   
   In the second argument of ‘trans
ition’, namely ‘(
jumpIn' t)’
     
 In the expression: transitio
n tidal (jumpIn' 
t) i
      In an 
equation for ‘jumpIn'’:

          jumpIn' i
 t = transition t
idal (jumpIn' t)
 i


<
interactive>:31:37: error:
    • Couldn't match expected 
type ‘Bool’
                  with actual t
ype ‘Time -> [Contr
olPattern] -> Contro
lPattern’
    • Probable cause:
 ‘jumpMod’ is applied to too few arguments
     
 In the second argument of ‘transition
’, namely ‘(jumpMod t
)’
      In the expression: trans
ition tidal (jumpM
od t) i
      In an 
equation for ‘jumpMod’:
        
  jumpMod i t = t
ransition tidal (jumpM
od t) i



<interactive>:32:51: error:

    
• Couldn't match expe
cted type ‘Bool’
                
  with actual type ‘T
ime -> [ControlPattern
] -> ControlPattern’
 
   • Probable cause: ‘mortal’ is applied to too few arguments
  
    In the second argument of ‘transition’
, namely
        ‘(mortal lifesp
an release)’
      In the expression:
 transition tidal (mo
rtal lifespan release
) i
      In an equation for ‘mor
tal’:
          mortal i
 lifespan release
          
  = transition tidal 
(mortal lifespan rel
ease) i



<interactive>:33:39
: error:

    • Couldn't ma
tch expected type ‘Boo
l’
                  with actual
 type ‘Time -> [Cont
rolPattern] -> Contro
lPattern’
    • Probable cause: ‘i
nterpolate’ is applied to too few arguments
      In the
 second argument of ‘transition’
, namely ‘(interpolat
e)’
      In the expression:
 transition tida
l (interpolate) 
i
      In an equation for 
‘interpolate
’:

          interp
olate i = tran
sition tidal 
(interpolate) i




<interactive>:34:43: error:
    • Couldn't match expected type ‘Bo
ol’
                  with actual type ‘Tim
e -> [ControlPattern]
 -> ControlPattern’
 
   • Probable cause: ‘inter
polateIn’ is applied to too few arguments
     
 In the second argument of ‘transition
’, namely ‘(inte
rpolateIn t)’
     
 In the expression: transition tidal
 (interpolateIn t) i

      In an equation for ‘interp
olateIn’:
          inte
rpolateIn i t = tra
nsition tidal (inter
polateIn t) i



<interactive>:35:34: 
error:

    • Co
uldn't match expec
ted type ‘Bool’

                  with actua
l type ‘Time -> [
Pattern a0] -> Pat
tern a0’
    • Probable cause:
 ‘clutch’ is applied to too few arguments
     
 In the second argument of ‘transi
tion’, namely ‘(clutch)
’
      In the expression: tran
sition tidal (clu
tch) i
      In an 
equation for ‘clutch’: 
clutch i = trans
ition tidal (clut
ch) i



<interactive>:36
:38: error:

    • Could
n't match expecte
d type ‘Bool’

                  with actual t
ype ‘Time -> [Pat
tern a0] -> Patter
n a0’
    • Probable cause: ‘c
lutchIn’ is applied to too few arguments
      
In the second argument of ‘transition
’, namely ‘(clutchIn t
)’
      In the expression: tr
ansition tidal (c
lutchIn t) i
    
  In an equation for ‘clutchIn
’:
          clutchIn
 i t = transition
 tidal (clutchIn
 t) i



<interactive>:37
:38: error:

    • Couldn
't match expected
 type ‘Bool’
        
          with actual ty
pe ‘Time -> [Cont
rolPattern] -> Con
trolPattern’
    
• Probable cause: ‘anticipate’ 
is applied to too few arguments
      In the second argument of ‘tra
nsition’, namely ‘(anti
cipate)’
      In the expression:
 transition tidal 
(anticipate) i
  
    In an equation for ‘antici
pate’:
         
 anticipa
te i = 
transition ti
dal (anticipa
te) i



<interactive>:
38:42: error:


    • Couldn't match expected type ‘Bool’
                  with actual type ‘Time ->
 [ControlPattern] -> ControlPattern’
    • 
Probable cause: ‘anticipateIn’ 
is applied to too few arguments
      In the second 
argument of ‘transitio
n’, namely ‘(ant
icipateIn t)
’
      In the expression:
 transition 
tidal (antic
ipateIn t) i

      In an
 equation for ‘anticipa
teIn’:
        
  anticipate
In i t = tr
ansition 
tidal (anti
cipateIn t) 
i

Investigation

• Client & Server sucessfully communicate:

{"type":"eval","code":"d1 $ s \"bd\""}
extramuros: broadcast to 2 clients
{"type":"eval","code":"d1 $ s \"bd\""}
extramuros: broadcast to 2 clients
{"type":"eval","code":"d2 $ s \"hh(4,7)\"\n"}

-----

extramuros: connecting to ws://127.0.0.1:8000...
extramuros: connected to ws://127.0.0.1:8000

• When running directly with | sclang, it seems to work:

SuperDirt: listening to Tidal on port 57120
sc3> (var syn, sound;syn = SynthDef.new("example2", {arg freq = 440, amp = 0.2;Out.ar(0, SinOsc.ar(freq,mul: amp));});syn.load(s);)
(var syn, sound;syn = SynthDef.new("example2", {arg freq = 440, amp = 0.2;Out.ar(0, SinOsc.ar(freq,mul: amp));});syn.load(s);)
-> a SynthDef

Any idea what could cause these issues? Thanks for your help!