Tutorial 52: Jitter Networking

The jit.net.send object allows us to send uncompressed matrices over the Internet to a jit.net.recv object in a Max patch on a different computer.

The jit.net.send and jit.net.recv objects communicate using the TCP protocol. A discussion of the different types of network transmission protocols is beyond the scope of this Tutorial; it's important to note, however, that TCP is a connection-oriented protocol. Before anything can be sent or received the pair of objects must make a connection to one another. Both objects report any change in their connection status out the dump outlet with a connected message, followed by an argument of 1 when connected or 0 when disconnected.

To form a connection, the jit.net.recv and jit.net.send objects must be set to link to the same port. We can set the port attribute to any positive integer value, but some of the lower numbers are reserved for commonly used network services such as FTP, web browsing, etc. Watch the Max console for error messages when you change ports—no message means the connection is valid. A port in the range above 1024 and below 10000 will probably be safe. If no port is specified, the default for both objects is 7474.

In addition to port number, the jit.net.send object must know the IP address of the computer running the Max patch containing the jit.net.recv object we'd like to send to. A computer may have more than one IP address – the wireless interface and Ethernet port will have different addresses, for example – and, by default, the jit.net.recv object will listen to all of them for a connection request from a jit.net.send suitor. It is possible to specify which interface to use by sending the object an ip message with the specific IP address of the desired interface as an argument.

If we open the sending and receiving patches on the same computer, the objects may immediately form a connection. The toggle boxes connected to the route objects in each patch will be checked if this is the case. By default the jit.net.send object's ip attribute is set to 127.0.0.1, which is the local loopback address. The jit.net.recv object is listening to all addresses by default, including the local loopback, so a connection should be made if the two patches are on the same computer. If you're running the patches on different computers, you can use the mxj net.local object to figure out what IP address the jit.net.send object should be trying to connect with. Note that one can specify an IP address with the ip attribute, or alternatively one can specify a hostname with the host attribute and jit.net.send will attempt to use the Domain Name Service (DNS) to resolve the hostname to an IP address.

In the sending patch, a jit.movie object is sending matrices to a jit.net.send object. Note that the qmetro driving the movie playback triggers the movie frame and then sends the jit.net.send object a getlatency message. This causes a one-way latency estimate to be output from the dump outlet. We can use this estimate of the transmission latency to synchronize events on the two computers, for instance by delaying the processing or display of a matrix on a local computer by the amount of the estimate, at which point the receiving computer should be ready to process the matrix it has received.

In addition to sending matrices, any normal Max message input into the right inlet of jit.net.send will come out the middle outlet of the connected jit.net.recv object. The input order of messages and matrices will be preserved in the receiving patch. In this example, the patcher named dim changes contains a slower qmetro that changes the dimensionality of the movie every half second. These new dimensions are input into the right inlet of the jit.net.send object. When the two integers come out the second outlet of the jit.net.recv object they are used as the arguments of the size message to resize the jit.pwindow object.

The matrices in this tutorial patch are of type char, but jit.net.send and jit.net.recv can handle matrices of any type. For an example that uses float32 matrices, please refer to audio-over-network in the jit-examples/audio folder.

Summary

Using the jit.net.send and jit.net.recv objects, you can send uncompressed Jitter matrices to another computer running Max. You specify a port for the two machines to communicate on, as well as an ip address for the sending machine to use when connecting to the receiving machine.