SoundSpace User Guide

Because SoundSpace is in such an early stage of development, the
following guide is meant to be just a quick overview of the application. It assumes
that you are familiar with CSound, and the
space functions developed by Richard Karpen

The guide below covers the major functions of the SoundSpace
front end to space.

Background on Java

Java is a platform independent programing language and runtime
environment. It allows the same programs to be run on mulitple platforms without
needing to recompile the source code. One of it's main advantages is that it also
contains basic graphical user interface (GUI) capabilities. The cost is that performance
is generally poorer then for native programs.

NOTE: SoundSpace is a Java application, not a Java Applet.
There are two basic ways to run Java programs, as an Applet or as an application.
An Applet is a java program written specifically to be run over the Internet,
and is typically run using a Web browser such as Netscape. An application is written
to be run as a normal program, and is typically run from a command prompt. As
of this time there are no plans for writing Applet versions of SoundSpace.

Starting SoundSpace

Please review the system requirements
page before proceeding. On Unix and Windows systems the easiest way to start SoundSpace
is to open a shell or command prompt, enter the directory containing the SoundSpace
classes, and running the command:

java SoundSpace

This command is case sensitive. On Macintosh systems you will need
to double-click on the SoundSpace icon contained in the SoundSpace folder.

Using SoundSpace

SoundSpace currently allows users to create, edit, and save text
files used by the
space extensions of CSound. Space takes a series of points given as a time
in seconds and tenths of seconds and Cartesian (x-y) coordinates and using a source
sound file creates a file that 'moves' along these points over time. This information
is read from a text file. A typical text file may look something like this.

0.0 -2.10 3.00
1.3 -3.10 3.00
8.2 0.00 8.31
...

SoundSpace can edit and display up to eight files or tracks at
one time. It provides a graphical display of these files, along with a set of
tools that allow users to easily edit these files.

Below is a graphic of the SoundSpace application. Each of the
major features is labeled with a green box. A description of each of these features
is given below the graphic.

Menu Items There is currently one menu item, File, which has four selections.
These selections are:

Open Track This opens a properly formated text file,
and loads the information into the current track (see Track Controls below),
overwriting the current information.

Save Track This saves the current track into a text
file.

Clear Track This clears the current track, removing
all the information in the current track.

Quit This exits the SoundSpace application.

Time Canvas The time canvas has three components; the time scrollbar, the
time canvas itself, and the maximum time visible text box.

Time Scrollbar The time scrollbar allows users to control
the current time. The current time is displayed in the time canvas as a partial
grey line. The current time is also displayed above the time canvas, and is given
in seconds and tenths of seconds.

Time CanvasThe time canvas has several functions. The
canvas itself represents the time from 0.0 to the maximum visible time displayed
in the text box above and to the right of the time canvas. It shows the current
time as a pair of small grey lines at the top and bottom of the time canvas. It
displays all the points in the current track based on their time value. These
are normally displayed as a blue vertical line. If the current time is the same
as one of these points, the point is displayed as a red line instead. Along with
displaying the points of the current track, it can also 'capture' a number of
these points by clicking and dragging within the time canvas. These points can
then be moved using the nudge controls (see below). Finally a block of
time can be selected for the draw function (see sound canvas below), by
clicking and dragging an empty section of the time canvas.

Maximum Time visible. This text box allows users to
change the maximum time visible within the time canvas. While tracks may be of
arbitrary length, the time canvas will display only those below the amount shown
in this text box. This value can be changed at any time by clicking into the box
and entering a new time.

Sound Canvas The sound canvas is the main display window. It contains a
graphical representation of each of the tracks. It has three main functions; display
track information, edit track information, and draw points using the draw function.

Display Track Information Each track is viewed as if
from, above, using a Cartesian (x-y) coordinate system. The window is scaled such
that the value '1' represents the distance to the four speakers, and is shown
by a black circle. Users can zoom in or zoom out using the scroll bar found at
the bottom of the sound canvas. The active track is displayed in blue, with the
time and x-y position of each point displayed, and a blue line showing the 'path'
the sound will travel between the points. The sound canvas also displays the other
tracks as grey lines. In the example above, there are three tracks, with track
'1' being the active track. The sound canvas displays the position of the current
time as a red circle. In the above example, the current time is 17.0 seconds.

Edit Track Information The sound canvas can be used
to edit track information. New points are always added at the current time. To
add a new point, or change an existing point, set the current time to the desired
time, use the mouse and click at the desired position. a new point will be created
at that point. If a point already exists in the current track at the current time,
the old point is removed and the new one replaces it.

Draw Points Using the sound canvas, you can also draw
a series of points. First select a block of time using the time canvas, then using
the mouse, click and drag the mouse along the desired trajectory. When the mouse
button is raised, SoundSpace will create a series of points along this trajectory.
(see draw controls below).

Display Controls The display controls are the toggles for
the visibility of the text within the sound canvas. The display control toggles
are labeled Current, Times, and Positions corisponding to the current time, the
time value for each point, and the x-y coordinates for each point. Clicking in
the toggle box changes that value's visibility. The Display Controls are not seen
in the graphic above.

Track Controls The track controls have two functions.
The first is to select which of the eight tracks will be the current one. Only
the current track can be edited. To select the current track, click the button
below the track number you want to be active. The current track button will be
shown in blue. The second function is to hide a track, so that it is no longer
visible in the sound canvas window. In order to hide a track, you need to click
the text for that track, i.e. 'Track 1', 'Track 5', etc. When a track is hidden,
the text and the button below it will be grayed out. To reactivate a track, click
on the grayed track name.

Nudge Controls The nudge controls have several functions.
Surrounding the control panel is a color coded mode box. In the example above
the mode box is red. There are four modes, each with it's own color. Grey means
that nudge controls are inactive. Red means that a single point has been selected,
and that that point can then be nudged up, down, left, or right, and backwards
or forwards in time, by using the six nudge control buttons. Green means that
a group of points have been captured using the time canvas. If the nudge controls
are green, then all the points that have been captured, as indicated in both the
time canvas and sound canvas as green points can be nudged up, down, left, or
right, and backward or forward in time. Cyan indicates that SoundSpace is in draw
mode, and the nudge controls have been disabled.

Point Controls The point controls have two main sections.
the three text boxes for x-position, y-position, and the current time, and the
previous, next, delete, and play buttons that are used to control existing points.
In the example above, the time is 17.0 seconds, the x-position is -1.53, and the
y-position is 0.83. These values can be changed by typing a new value in the text
box and pressing enter. The previous and next buttons will set the current time
to the previous or next point in the current track. The delete button will delete
a point if there is one at the current time. The play button is not yet functional.

Draw Controls The draw controls display the start time,
end time set by the time canvas when using the draw functions. It also displays
the number of points created when drawing a set of points in the sound canvas.
In the example above, the draw function is disabled and the number of points set
to 12. When in use, the start and end time would correspond with the beginning
of the selected block of time in the time canvas, and the end time the end of
the block of time in the time canvas. The number of points can be changed by clicking
in the text box, typing the desired number, and hitting enter.