CARTAH - Center for Advanced Research Technology in the Arts and Humanities
  SoundSpace | Requirements | Guide | Files

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.

We welcome comments about this project. Just email Mark Haslam