< Previous | Contents | Manuals Home | Boris FX | Next >

Talking to SynthEyes

SyPy's python code talks to a component of SynthEyes called the "listener," which is similar to a small web server built into SynthEyes. It listens for commands from SyPy, and executes them as they are received.

Python calls up the listener via an internet-style port, though since it is a local connection, no external internet access is required. Note: connecting to a SynthEyes process on a different machine is not permitted or possible.

The port number is 16 bits, ranging from 0 to 65535, though per the IANA standard, private ports such as these should be in the 49152 to 65535 range. A "pin" code is also required to provide some defense against any hostile remote browser script trying to talk to any running SynthEyes instance. The pin code is typically a dozen random alphanumeric characters. When SynthEyes is started, it can be told to listen for commands on one or more specific ports via the command line, or it can be told to pick a port at random within a specific range, as set on the preferences.

IMPORTANT : The listener is not so much a security hole as an insecurity superhighway. Any application on your machine---for example a Javascript in a browser window---can commandeer a running SynthEyes instance, even if it does not know the port number to start with (a scan will take only a few seconds). Once controlling SynthEyes, it can cause that instance to do arbitrary damage to your machine, overwriting files or potentially causing arbitrary binary code execution. Customers are responsible for securing their networks against such threats; if that cannot be done, do not activate the Listener.

If you are creating a workflow where your external Python-based application will launch SynthEyes, the SyPy interface needs to supply the port and pin on the command line to SynthEyes, so that the new SynthEyes instance will know where to listen for commands from the (correct) python application. SyPy will create that port and pin automatically if you do not supply them.

You can open a new SynthEyes and prepare to talk to it with (use SyPy3 for python 3):

import SyPy

hlev = SyPy.SyLevel() hlev.OpenSynthEyes()

If Python has been started with appropriate "-port NNNN -pin PINCODE" arguments, those will be used. Or, you can supply them directly to the OpenSynthEyes call with hlev.OpenSynthEyes(port, pin). If no other information is available, SyPy will use a randomly- chosen port in the range configured in syconfig.py, and a randomly-selected pin code.

If you are writing python scripts that are started from the SynthEyes Scripts menu, or that talk to an already-running SynthEyes, you can talk to an existing SynthEyes instance, with

hlev.OpenExisting(port, pin)

In this case, you will need to know the port number and pin string that the SynthEyes instance was started with. SyPy will pull them from the Python command line if none are supplied in the

call. Do not allow SyPy to create a random port and pin to talk to an existing SynthEyes, since the SynthEyes instance will not be listening for that particular random combination.

Hint: the SynthEyes listener can listen on multiple ports, and have multiple connections open simultaneously on each port. So multiple apps and scripts can all talk to the same SynthEyes instance simultaneously (check out the section on Consistency Control below).

A SynthEyes started and being controlled from an external app can start its own local python script and/or python-based user-interface also. Can you say F...L...E...X...I...B...L...E?

< Previous | Contents | Manuals Home | Boris FX | Next >