Languages:

English

Introduction

GNU Psychosynth can be controlled from third party software using the Open Sound Control protocol. It provides to different ways of interacting via OSC, either using a passive stateless interface, or using a stateful protocol that enables multi-peer coordinated sessions. Both 3D user interface and the command line version allow OSC controlling. The later, indeed, is intended to work via OSC mostly. More information on how to enable OSC can be found in the user manual.

The passive interface

The passive interface it is the easier to use, because it relies on no shared state between the controller and Psychosynth. The following messages are available.

• /ps/add cid:i oid:i kind:s

  Adds a new object of kind kind that can be later referenced and manipulated by the identifier tuple (cid oid). The two parts of this identifier can be set arbitrarily, but it can be useful to set the same cd in all objects added by a given client.

  Example: /ps/add 1 5 oscillator

• /ps/delete cid:i oid:i

  Removes object (cid oid) from the sythesis.

  Example: /ps/delete 1 5

• /ps/activate cid:i oid:i

  Activates object (cid oid). Note that deactivated objects do not participate in the dynamic patching and do nothing. Objects are in deactivated state when just added. This allows setting the initial parameters before enabling it.

  Example: /ps/activate 1 5

• /ps/deactivate cid:i oid:i

  Deactivates object (cid oid).

  Example: /ps/deactivate 1 5

• /ps/param cid:i oid:i name:s value:?

  Sets the parameter name in object (cid oid) to value value. The type of the value parameter depends on the kind of paramter. Later in this document a full reference of objects and their parameters and kinds is included.

  Example: /ps/param 1 5 frequency 440.0

The active interface

Note that, while very strightforward, the passive interface is somewhat limited. Specially, it is very hard for several controllers to coordinate, and they must implement ad-hoc mechanism to share their object identifiers.

For this reason, a different interface allows client-server interaction. An important difference is that active clients must be able to receive OSC messages themselves. Many active clients can register on a server. Whenever a client wants to manipulate the synthesis graph, it sends a message using the same syntax than the passive interface. Then, the server broadcasts this message to all registeredd clients. In this way, other clients can keep a synchronised view of the synthesis graph, enabling collaborative sessions.

Clients in the active interface manipulate the graph using the same passive interface, but they should also be able to receive and interpret these. Also, the active interface includes other OSC methods to maintain the connection state:

• /ps/connect

  Message sent from the client to the server when it wills to stablish a section. It is very important that this message is sent with a from address (as when using the lo_send_message_from LibLO function) -- the server will use that address to communicate back to the client.

• /ps/accept cid:i

  Message sent from the server back to the client when a connect method has succeeded. It is very important, to avoid identifier clashes, that when the client calls the /ps/add method, it uses the cid that it received in this accept reply -- the oid can be set arbitrarily.

  Example: /ps/accept 1

• /ps/drop

  Message sent from the client to the server when it wills to end the connection. Also, this may be sent from the server to the client whenever it decides on its own to close the connection -- e.g. the server shut downs, tbe client fails to send alive messages on time, etc.

• /ps/alive

  Message sent periodically from the client to the server and otherwise to indicate that it is alive and wills to keep communicating, even if maybe it is not performing actions regularly. Our default implementation sends alice messages every second and assumes that the client or server is dead if it fails to receive a message from its peer in 30 seconds.

Objects and parameters reference

The add and param take input that are the names of the different kinds of objects and parameters that are available in Psychosynth. Every parameter as a type. The type of the paremeter is mapped to OSC types in here:

• float → f
• int → i
• string → s
• vector2f → a couple of f parameters

Note that if an integer represents a boolean value -- see, for example, the mute parameter -- then 0 is the false/disabled state, and 1 or other non-zero value is the true/enabled state.

Common parameters

All Psychosynth objects have some paramters in common, as listed here.

• position: vector2f. Position of the object in the 2D space.
• radious: float. Not used.
• mute: int. Mutes or unmutes the object.

oscillator

Generates an oscillating audio signal.

• wave: int. The oscillator wave type, as in 0: sinus, 1: square, 2: triangle, 3: sawtooh, 4: moogsaw, 5: exponential.
• modulator: int. What kind of modulation to use when a control signal is connected to it. 0: fm, 1: am, 2: pm.
• frequency: float. The frequency, in hertz.
• amplitude: float. Amplitude of the generated signal.

lfo

Just like the oscillator objects, but generates control signals instead.

audio_noise

Random signal generator.

• type: int. Kind of noise, as in 0: white, 1: pink.
• amplitude: float. Amplitued of the generated signal.

control_noise

Just like the audio_noise objects, but generates control signals instead.

audio_mixer

Combines several audio signals into one output.

• mixop: int. Mixing operation, 0: sum, 1: product.
• amplitude: float. Amplitued of the generated signal.

control_mixer

Just like an audio_mixer but for control signals.

filter

An audio signal filter.

• type: int. Filter kind, as in 0: lowpass, 1: highpass, 2: bandpass CSG, 3: bandpass CZPG, 4: notch, 5: moog.
• cutoff: float. Cutoff frequency of the filter.
• resonance: float. Resonante, in 0 < resonanec < 1.

echo

An echo special effect for audio signals.

• delay: float. Delay of the echo, in seconds.
• feedback: float. Percentage of the signal that is echoed in every replic.

delay

A delay special effect for audio signals.

• delay: float. Delay of the replc signal, in seconds.
• depth: float. Percentage of the signal that is added back.

sampler

An audio file player. Supports files in all formats supported by LibSndFile.

• file: string. File name of the sample. It will be automatically looked up in the sample folders, so only the basename should be set.
• amplitude: float. Volume of the sample file.
• rate: float. Rate at which the file is played.
• tempo: float. Rate of tempo stretching.
• pitch: float. Rate of pitch shifting.

double_sampler

A file player that plays two samples at the same time blending among them as required. It does not support rate or time stretching unlike normal samplers.

• file_one: string. File name of the first sample.
• file_two: string. File name of the second sample.
• amplitude: float. Gain applied to the files.
• blend: float. Blend of both files. 1.0f sounds the first file, 0.0f the second file, and a linear blend of both in the middle.

stepseq

A step sequencer that also sends an envelope to the triggered signal.

• bpm: float. Speed of the sample in beats per minute.
• shape: int. Shape of the envelope, as in 0: square, 1: triangle, 2: forward sawtooh, 3: backwards sawtooth.
• high: float. High trigger value.
• slope: float. 0...1 value indicating how much of the step should the trigger durate.
• num_steps: int. Number of steps.
• step0, step1, step2 ...: int. Toggle the Nth step.