User manual

From Psychosynth



Thanks to Ben Mullett for the translation.

This document constitutes the user manual for Psychosynth, it is intended to help resolve issues in the use of the Psychosynth software package.

If it is not yet clear to you what this is about, please go to What is Psychosynth?


The method of software installation will depend on the system you are using. There are instructions covering different installation methods in the documentation.

3D Interface

Psychosynth has functions that allow you to graphically manipulate synthesizer elements and their intercommunication. Right now there are two user interfaces, a three-dimensional graphical interface and the command line.

To run the 3D interface enter the command:


Then you should see a window like this:

Main window

At the bottom of the screen are a series of icon buttons that will enable us to deploy different windows to control Psychosynth. In the following order, the buttons are:

  • Object Selector: Selects objects to place on the workspace.
  • Sound Recorder: Records to a file all the sound being generated.
  • Network Sessions: Connects the synthesizer with others across a network.
  • Info Panel: Displays information panels about the program - and some help.
  • Exit: Exit the program.

In the center of the screen is a blue table where Psychosynth objects are placed to create and manipulate sound, as we shall see below.

Now let's see how we might do this in a three-dimensional environment.

The camera

The first thing we must get used to is manipulating the "camera". It might seem that the environment is only 3D eye candy; in practice it it adds important aspects of control over the synthesizer.

3D provides an intuitive means to adjust a Psychosynth object's controls: when zoomed out we can see many objects and easily move them between relatively distant points.

On the other hand it is better to zoom in when we wish to modify an object parameter precisely. Mouse movements will represent shorter distances and thus increase the resolution.

Camera Movements include:

  • Move: To move the camera simply click the left mouse button on the table. The whole environment can be dragged around with the mouse. We can also focus the camera on a point by pressing the shift key while clicking the left button where we want to focus on the table.
  • Rotate: With no object selected we can rotate the camera focus around to a given point by moving the mouse while pressing the left button
  • Zoom: We can zoom the point that we have focused by either using the mouse wheel or by pressing the middle mouse button while moving the mouse forward and backward.

Creating sounds

To create sounds we will be placing some Psychosynth objects on the table. The central spot represents the main audio output, which will normally be our speaker.

To place an object on the table, click on the first icon button at the bottom of the screen. An object selector appears, the buttons are organized by category - allowing us to select and place different synthesis objects.

As the library of objects is growing rapidly there is no documentation yet on individual elements. Fortunately Psychosynth quickly allows you to experiment with the objects - discovering what each one does and how they interact with each other - learning about audio synthesis in a fast, fun and highly intuitive manner.

When you click on one of the selector buttons you'll see a yellow circle that follows the mouse, indicating where the object will be placed. Then when we click on the table the object will appear there. If a sinusoidal oscillator is placed it will automatically connect with the center making a pure tone of 220 Hz.

The situation would then look like this:

Psychosynth making a pure tone.

A connection between two objects will show us the wave being broadcast through it in real time, green if an acoustic signal and yellow if a control signal.

Modifying the sound

Psychosynth objects are connected with each other automatically. Two objects will be connected if they have compatible input and output ports, and if those ports are not already being used for other, shorter connections. Thus we can very quickly and intuitively alter the topology of the synthesizer simply by moving the objects that we want to connect more closely.

To move an object, click the left mouse button and drag it onto the table.

Each object also has a number of parameters. For example, an oscillator object like the one we used earlier has two parameters - frequency and amplitude (or volume). The frequency is the main parameter of this object and we can see the relative value on an indicator that surrounds the subject on the right side.

To modify the main parameter simply move the mouse around the selected object while holding down the right mouse button, which rotates the object.

The other parameter - in this case the scale - is represented by a slider on the other side of the object. To change it click the link to the left of the object and move the slider.

There may be other parameters that are not directly represented on the object, sometimes because they are less important and sometimes because it is not yet decided how to represent them visually. For example, the main parameter of a sampler is the playback speed - the amplitude is 'secondary'. But we can also alter the Tempo independantly - that is, change the playback speed without changing the key - and alter the Pitch - play in a different key without changing the playback speed.

To list all of an object's parameters and to view and modify the numerical values, press the 'e' key to display a parameters window.

An example would be like this window, this time showing a more complex scenario:


To remove an object from the table use the 'Delete' key.

We can also select multiple objects simultaneously which is useful if modifying their main parameters all at once - or deleting them - or perhaps moving them. To select multiple objects, hold down the shift key while selecting. To deselect an object in the group press the control key and click on the object.

Finally, we can temporarily mute a connection by clicking on it. It then turns black and any objects that attach to that connection in the hierarchy from the center will not be updated until we click on that link again.

Recording sound

To record a session just click on the red button that appears in the second position below. A window appears with the file name to which the sound is to be saved - and a start button.

Record window.

We can modify the file name to be created, using any valid route from the current working directory. To start recording, click on Start and once finished, click on Stop.

Network Sessions

To connect multiple synthesizers we need to establish a server computer and create one or more clients.

During a network session all events will be synchronized between connected synthesizers, but they will not be aware of any events that occurred before the connection. Therefore, it is recommended to clear the table before all computers are connected.

The third icon button in the row below the window opens network handling, which has two tabs, 'client' and 'server'. First, we need a server computer, so we go to the 'server' tab. Then we can alter the listening port number - usually the default port is used. When you start the server it will be ready to receive connections and the box in the window displays: 'Server listening'. The same box will show when someone is connected or disconnected - and similar events.

The other computers use the tab 'Client' to connect as clients. There we enter the IP address of the computer server where it says 'Remote host' and the port in 'Remote port'. We can also change the client listening port in 'Local port'. Once we are ready to go, hit the 'start' button.

A message that says 'Connecting…' should appear. Once the connection has been made successfully we will see the message 'Connection accepted', or an error message.


Editing options

The program has various options that we can edit. To do so, we click on the 'Toolbox' icon button in the row below.

These are the options that we will find in each category:


Here we can modify the sound generation options.

Some of these are:

Sample rate: The number of audio samples taken per second. Higher values give higher quality but need more computer power; it is recommended to use the default value. Please note that most sound cards only support a specific set of values.

Buffer size: The number of samples that are computed in one block. Influences the latency directly, which can be calculated as:

latency = buffer_size / sample_rate per second

Almost all sound cards require that this number to be a power of two. Note that a very low number will cause a greater CPU load and potentially cause buffer underruns with annoying clicks at high load, while very high values will slow the transfer to the audio generation system.

Channels: The number of audio channels. By default stereo sound is used.

Output: Choose the output system.

The relative advantages depend on the platform used and the use it will give Psychosynth. Normally, depending on the output system we choose there will be some options available to the chosen output device.


In this section we can change options for the on-screen 3D environment. Specifically:

width and height: The width and height of the window in pixels. fullscreen: Select this for full screen. Note that the apply button does not work on systems using GLX due to problems in the Ogre library version.

FPS: The refresh rate of the screen in samples per second. Higher values consume more CPU power and lower values make the animation jerky.


Here we configure the paths where the program searches for data. For now we can only change where samples are being sought, eg audio files that we can find in the samples section of the objects selector.

Once we have finished altering the list of search paths click 'refresh' to update the list of samples in the objects selector. Note that Psychosynth only uses samples that are in .wav, .au, .aiff or .ogg format.

The command line interface

There is a version of the synthesizer that runs from the command line.

In this version we cannot change the environment directly, but we can use it as a network server, using the option --server or as a client in a network using --client.

We can also hear all the sounds being generated, it is a real synthesizer; only the state of the scenario is not displayed and parameters can only be changed through the network.

For complete information on available command line options use --help.