reduzent/netpd

Collaborative Realtime Networked Music Making Environment (MK II)

is a CRNMME (Collaborative Realtime Networked Music Making Environment) written in Pure Data. It allows many users to have a real time jam sessions with each other, connected over the internet. Users might contribute their own netpdized patches a.k.a. instruments or use pre-existing ones. The set of instruments and the state of each one is synchronized between clients in order to provide identical experience for every connected user.

• Find more detailed information on
  https://netpd.org

• Discuss related matters on
  https://untalk.netpd.org

NOTE:
This repository contains only the netpd framework. The instruments are hosted separately on:
https://github.com/reduzent/netpd-instruments

You may want to clone everything at once by doing:

git clone --recursive https://github.com/reduzent/netpd.git

supported platforms

netpd runs on any platform Pure Data runs on. This includes Linux, macOS, Windows.

For macOS and Windows there are batteries-included standalone apps available that should get you going quickly.

prerequisites

Before runnning netpd you need to install Pure Data (Pd) (>= 0.52.0) from here. You also need to install a few additional libraries. They can be installed from Pd through the menu Help -> Find externals. The following libraries need to be searched and installed:

• iemlib
• iemnet
• osc
• slip

NOTE: pd-l2ork is not supported (and support is not planned) because it has some incompatibilities with Pure Data.

intro

• Open netpd/main.pd with Pd.
  chat automatically connects to the server and you can now chat with other users currently online.
  Click list to get a list all connnected users.

• Click the unpatch button in chat to launch the unpatch instrument manager. If there is already a session going on, the instruments used in the ongoing session are automatically loaded (they are first downloaded from other users, if necessary).

• Load instruments into the current session by clicking on any of the instrument names in the upper scroll list.
  Alternatively, just type the name of the instrument (without the extension .pd) into the input box and hit enter.

• Show an instrument's GUI by clicking on its name in unpatch's lower section. You can now manipulate the instrument's parameters. Any changes are instantaneously synchronized between clients. Anyone can manipulate anything, so please be cautious and considerate when joining an ongoing session.

If you're lucky, someone is online and might help you get started. This is the easiest and fastest way to get accustomed to all the instruments and how they interact with each other. Of course, you can explore the instruments on your own as well. Maybe start with master and sine.

server

For online jams, netpd needs to connect to a netpd-server. A public netpd-server is running at netpd.org on port 3025. This is the default server in netpd's configuration. The netpd-server software is available here:
https://github.com/reduzent/netpd-server.

copyright

2008-2022, Roman Haefeli [email protected]
Published under the GNU Public License (GPL-2)

netpd's Issues

unpatch: slow loading of remote sessions

On macOS and Windows, syncing from a peer can take quite some amount of time - up to a few minutes, depending on the size of the session, the number of instruments and effects used in the session, respectively. The issue is less pronounced on Linux, it seems.

unpatch: ask for permission before downloading instruments

It's practice of netpd that a higher version of an instrument or abstraction overwrites a lower version when loaded. As yet, this happens without asking for permission and without notice. Before downloading a newer version, unpatch should notify the user and provide a way to deny a download. Maybe there could be a configuration setting for setting a general rule:

• always download
• ask each time
• never download

unpatch: use drop-down menu for available instruments

This could replace the load button that opens a file browser. The file browser is bad UX since one can only load instruments from the instruments directory, so there is no advantage in the ability to browser around. Rather, it adds confusion.

unpatch: patches are modified during transmission

Some objects in patches contain information about box width. The lines in patches containing box width information are broken up into two lines.

This:

#X floatatom 26 77 5 0 0 0 - - -, f 5;

is converted to:

#X floatatom 26 77 5 0 0 0 - - -;
#X f 5;

netpd-pref-get: Message triggered by internal [loadbang] is sent to outlet

This is an anti-pattern for abstractions, as their [loadbang] fires before their parent, causing messages to be passed around before the parent or other abstractions in the parent are initialized. In this case, this was discovered when [netpd-resolve] was added and received a path before it was initialized.

add latency measurement tool for more precise latency compensation

Also, the jack latency calculation doesn't apply anymore. Since recently, Pd actually has a settable ring-buffer for the JACK back-end. The latency calculation should take that into account.

unpatch: dsp is turned off and on many times when an instrument is loaded

Ideally, it would turn off dsp before loading the instrument and turn dsp back on after it has been loaded. Many cycles are like to take more (CPU) time.

Debug output from loading sine:

DSP_ON_OFF: 0
DSP_ON_OFF: 1
DSP_ON_OFF: 0
DSP_ON_OFF: 1
DSP_ON_OFF: 0
DSP_ON_OFF: 1
DSP_ON_OFF: 0
DSP_ON_OFF: 1

unpatch: notification about newer remote version is broken

There is code that looks like it implements notifications if a newer version of an instrument or abstraction is found, but it doesn't work.

missing external in prerequisites list?

While starting up netpd for the first time with vanilla Pd (0.50.2) I got the following error:

dir
... couldn't create
[tcpclient]: unable to connect to stream socket
connect: Unknown error (10049)

After some searching around it became apparent that the [dir] object comes with the ELSE library, which isn't mentioned in the prerequisites list. I saw other people run into this problem as well, did we miss something or is this indeed missing from the list?

But I'm excited that it's working now! Thanks a lot for netpd :)

unpatch: better document /commands

What does /dev on do again? It does protect unpatch from other clients opening/closing instruments. Why is it called dev then?

netpd_text: add missing methods

Since netpd_text was written, [text] added more subclasses. Other methods are still missing. These should be implemented:

• insert
• write
• read
• clear

read netpd-preferences from user's home directory

Currently, the netpd-preferences are written to and read from the netpd directory. For a better separation of application and configuration, the preferences should be read from a file relative to the user's home directory, maybe simply ~/.netpd-preferences.cnf. The preferences in the netpd folder should only be used as fallback. This also has the advantage that netpd can replaced/upgraded without losing the preferences.

unpatch: dynamic-dsp-off doesn't work

When loading an instrument, the DSP is not turned off during loading, even when dynamic-dsp-off is set in the preferences.

loading instruments or effects cause long during redraw of data structures

When loading an effect or an instrument, it often triggers a redraw of GUI elements (datastructure scalars, to be precise), which can take up to many seconds, depending on session size, the number of loaded instruments, respectively.

The issue is related to how Pd's changed template detection works. An issue was on opened on the pure-data repo.

report missing externals

There is no clear feedback whether all required externals have been loaded correctly. Sometimes missing externals lead to kinds of failures that mask the original problem. A check that would clearly identify and report back missing externals would be greatly helpful.

text entry in chat and unpatch may cause unwanted repeats

Since Pd 0.52 the behavior of the symbol box has changed such that multiple hits on the enter key repeat the last input typed into the symbol box. This may trigger to write the same message in chat multiple times or to load the same instrument multiple times in unpatch.

chat: make it side-effect free

As a general design pattern, patches employing dynamic patching, should take care that they stay free of any side-effects. If the dynamic patching happens in the main patch and the patch is saved, artefacts from dynamic patching are saved with the patch. Thus, dynamic patching should happen in dedicated container abstractions.

Chat creates an instance of unpatch in itself. This should happen in a container abstractions.

broken links in README.md

At least these don't work:

https://www.netpd.org/Chat
https://www.netpd.org/Unpatch
https://www.netpd.org/sine
https://www.netpd.org/master
https://www.netpd.org/Server
https://www.netpd.org/Instruments

how to ensure consistency

Since recently netpd asks the user if a certain instrument or abstraction should be upgraded if remote loaded a newer version (or if there is no local version at all). While this prohibits unknown code to be loaded silently, which certainly is desired from a security point of view, it brings its own set of problems. If a download/upgrade is refused by the local user, consistency among peers break since local and remote do not have the same versions of instruments or abstractions thereof loaded. This is fine for the local user because they decided to break consistency. However, unpatch of the local user should not advertise itself as ready for other peers because it cannot deliver the newest available version used in the current session. unpatch should have a mechanism to prevent itself from advertising itself to other peers as soon as one or more downloads/upgrades have been refused.

unpatch: restore support for old text-based file format

Actually, support is supposed to already exist, but it is not working.

Warn when connection to server is terminated without user interaction

Not all internet connections are stable and sometimes it happens that a TCP connection is terminated without either of both endpoints initiating the termination. Such situation have resulted in diverging session where one party was having their isolated session without noticing. This is a really annoying problem.

Although it cannot be avoided, it be detected, at least. chat plays a bing sound whenever a connection starts or stops. However, that sound might not be heard during a session. Better would be displaying a pop-up dialog with a warning message.

netpd works both ways, either connected to a server, or locally. However, when a server session is interrupted involuntarily, netpd probably should just not automatically switch to local mode, but block any messages instead.

unpatch: show sync progress

Once for making debugging easier, but also for giving users more feedback about loading progress, unpatch should visually reflect whether it is waiting to be synced, sync is in progress, or sync has already finished. The same applies to each instrument. Unpatch already knows about sync progress of instruments, so it is only a matter of exposing it.

unpatch: broadcast session from file

Currently, a session recalled from a file is only loaded in the local unpatch. For other clients to synchronize, they need to stop and start unpatch to get the session state. Originally, this was considered the "safer" way, but it is too easy to end up in an inconsistent state when multiple people have different sets loaded.

pd 0.51-1 - netpd text glitches

With the latest version of pd 0.51-1 installed (on mac) netpd has gone a bit glitchy in the text boxes of the chat and unpatch - slashes '' appearing at every space.

unstep: missing gui elements?

I've never seen the gui of unstep somewhere else but I assume that there are faders missing which assign to the tabs "drive", "attack" and "decay" (see screenshot below). The pd terminal doesn't indicate any missing libraries, though...

ditch else library

[file] from Pd 0.52 covers what [dir] from else can do. No other objects from else have been used.

Manage message order in dynamically created objects

Currently, it is not possible to create an mx effect that is capable of loading other effects due to message order. Dynamically created abstractions fire first when using the same [send]/[receive] as already existing abstractions. In a scenario, where a dynamically loaded abstraction creates other abstractions dynamically, we want the order of state saving messages to be top->down, not bottom->up, otherwise the children receive their state before they are created at state loading time.

In order for nested dynamic creation to work with state management, a mechanism to influence order is needed.

chat: spaces in printed messages are escaped with backslashes

That's a regression in Pd. There was already an issue posted on the Pd issue tracker.

check samplerate

Since netpd is capable of using audio samples and live audio, using the same samplerate on all peers is crucial. Instead of implement complex samplerate negotiations, it should probably simply be fixed to a pre-defined value. I tend to go for 44100 Hz.

Windows and macOS builds turn DSP off sometimes

There are reports of people losing audio in the middle of a session. To get audio back, DSP needs to be toggled off and on.

loading saved sets crashes Pd when not online

As reported by beem, loading sets while being offline crashes Pd almost always.

netpd.exe is detected as Trojan

Hi, I tried to install netpd from the website and Windows Security is telling me netpd.exe contains a trojan.

This is what VirusTotal founds
https://www.virustotal.com/gui/file/0a82883131c395272dfe6e24083b512834b262186abc26179b4d072b9d3dd297/detection

chat: typing messages with double-quotes messes up chat window

and Tcl errors in the Pd window. Is it a bug in a recent Pd version?

netpd-nb-until: number of bangs generated is off by one

sending 4 emits only three bangs, for instance

random crashes on RPi

Hi, I've installed netpd on a raspberry pi 2 and it works well for some minutes, but then it suddenly crashes the whole pd instance. I can't figure out why or when this happens. Sometimes it plays for about 10 minutes without any issues. Sometimes it crashes almost directly after I started it.

Consistent use of term "instruments" in documentation

In a lot of places, "instruments" are still called "netpd-patches".

unpatch: mark singletons gray, also when loaded by sync

When opening unpatch and it syncs to an already ongoing session, instruments with the singleton property do not turn grey in the instrument selector list.

ditch binfile

[file] from Pd 0.52 can do what [binfile] can do.

update template to reflect all netpd_ abstractions

It's probably the best place to illustrate how to use them.

netload patch in offline mode

please support net-loading patches in offline mode

expose `DEBUG_PROTO` feature through better means

netpd has a built-in feature to print incoming or outgoing or both messages for debugging purposes. This feature is now enabled by sending 0, 1, 2, 3 to the global send DEBUG_PROTO. The name is awkard, not related to netpd and probably not unique.

restoring saved state fails when not having the instruments

When joining a running session, it doesn't matter whether the local client already has the instruments as they are downloaded from peers. When loading saved state, however, not having one or more instruments results in many errors. Unpatch could check for availability and abort with a message to the user instead of miserably failing.

pd crash with "Pd: signal 6"

Pd crashes with "Pd: signal 6" as soon as I change the tempo in the master patch.
Tried with jack and Alsa output.
using pd 0.50.0 on xubuntu 18.04.4

unpatch: command `/new <instrument>` is broken

When entering the following into unpatch's input box:

/new test

an error is printed on the Pd console:

error: $1: argument number out of range
ERROR: unpatch: no such patch:

configurable abs and patches directory

make abs and patches directory configurable so you can git submodule netpd and work with abs and patches directory that live outside of netpd.