Using GNUsound


GNUsound can be installed on GNOME 1 or GNOME 2 installations. It should build without problems on the most common GNU/Linux distributions, such as Debian, Red Hat and Fedora.


The following software is required to build and install GNUsound:

The following software is strongly recommended. This software must be installed prior to building GNUsound:

Installing from source

Unpack the source tarball and run the configure script:

$ tar xjf gnusound-version.tar.bz2
$ cd gnusound-version
$ ./configure

The configure script should give a brief summary of the detected environment. If something seems to be missing or wrong, check that you have installed the appropriate -devel packages and check that your PKG_CONFIG_PATH environment variable includes those (possibly non-standard) locations where software has installed .pc files (e.g. /usr/local/lib/pkgconfig).

Remember that

$ ./configure --help

may also provide more information.

If you're satisfied with the configuration, you can build GNUsound:

$ make
$ make modules
$ make install

To uninstall GNUsound, issue the command:

$ make uninstall

GNUsound supports both GNOME 1 and GNOME 2: that is, there are no significant differences in functionality or usability between the GNOME 1 and GNOME 2 versions of GNUsound.

GNUsound will automatically detect whether GNOME 1 or GNOME 2 is installed on the system at configure time. When both are installed, GNUsound will build for GNOME 2. When using GNOME 2, some aspects of GNUsound are a bit slower and the overall feel is heavier. For maximum performance you may want to disable GNOME 2 support. You can do this by providing the --without-gnome2 option to configure.

Installing from binary packages

Several people provide binary packages of GNUsound for a number of distributions. These are available from the GNUsound homepage.

Starting GNUsound

If installation has been successful, there should be a GNUsound icon in your GNOME menus. Alternatively you can start GNUsound from the command line:

$ gnusound

This latter method is actually recommended at this time, because GNUsound's output can help to resolve any issues you may encounter.

Opening a file

You can open audio files through the File→Open menu item, or by specifying them on the GNUsound commandline. GNUsound will automatically determine the filetype and load the file into memory. See File format support for the supported file format plugins. You must have enough memory (RAM + swap) to keep the entire file in memory.

Some audio file formats can support the embedding of auxiliary data (such as loop points and instrument definitions) with the waveform data. GNUsound ignores such information.

Waveform display

GNUsound can display waveform peaks as well as the waveform RMS ("power"). Calculating the RMS slows down waveform drawing, however, so for maximum performance you might want to turn it off in by unchecking Settings→Preferences→View→Show waveform RMS.

You can use View→Zoom In and View→Zoom Out to zoom in and out of the waveform. The mouse wheel can also be used for this purpose. View→Smaller and View→Bigger stretch or compress the waveform vertically.

When GNUsound is not playing or recording, the Play/Record→Scrub Left and Play/Record→Scrub Right scroll the waveform to the left or to the right respectively. The Fast variants do the same, but to a greater degree (the scrub_fast_multiplier preference controls by how much).


Selection Tool

The Selection Tool allows you to select a part of the waveform for further processing.

You can create a selection on a track by clicking, then dragging the mouse pointer over the region that you wish to select. Alternatively, you can hold the SHIFT key and give one of the movement commands in the Select menu.

You can select multiple tracks by holding the CONTROL key while clicking on the tracks that you want to select. If a track is already selected, then this action deselects the given track. Alternatively, you can hold SHIFT and use the Select→Track Up and Select→Track Down commands.

Changes to the selection are undoable. If you make a mistake which causes you to lose an important selection, you can issue the Edit→Undo command to get your selection back.

A handy trick to temporarily save a selection that you don't want to lose while you do some editing elsewhere is to turn the current selection into a loop using Select→Selection To Loop, then do your stuff, and then to select the loop when you're done. Alternatively, you can set cuepoints to demarcate the selection that you want to save, then use Select→Snap to Cuepoints and the Select→Move Left and Select→Move Right commands to get your selection back.

Marker Tool

The Marker Tool allows you to manipulate cuepoints and envelopes.

Cuepoints are like bookmarks. You can use them to mark important points in the sound file. By enabling Select→Snap To Cuepoints you can snap the selection to cuepoints.

Envelopes modify the effect of some processing operations. The precise meaning depends on the operation.


Cuepoints appear as little red triangles with a flagpole and a label attached to them.

You can create cuepoints by using the third mouse button when the Marker tool is active. Alternatively you can create them at any time by issuing Markers→Insert Cuepoint. This command creates a single marker at the cursor position. If there is a selection, then this command creates 2 markers at the left and right positions of the selection.

If the Marker Tool is active, you can move cuepoints by clicking on them and dragging them around. Double clicking on the red triangle brings up a dialog where you can edit things like the cuepoint label.


Envelopes appear as light or dark blue squares (called handles) connected by light or dark blue lines. The light and dark blue colors indicate the primary and auxiliary envelope, respectively.

If the Marker Tool is active, you can create new handles by clicking in the position where you want to create them. Clicking on an envelope handler allows you to drag it around. The second mouse button is used to create and move around the auxiliary envelope.

Envelopes have no effect in themselves. They serve only to control the effect of some other operation.

Therefore the exact effect of an envelope depends on the selected operation; some operations don't have any parameters, and the envelopes will have no effect. For other operations, the primary envelope usually controls the first parameter, and the auxiliary envelope controls the second parameter. For yet other operations, it may be possible to explicitly assign a parameter to one of the two envelopes.

It is possible to temporarily disable envelopes by issuing the View→Show Envelopes command. The envelopes will then become invisible and they will no longer affect any tools that you use.

Pencil Tool

The Pencil Tool allows you to perform sample-accurate waveform manipulation.

When the Pencil Tool is active, you can click and drag inside the waveform to change its shape. If you zoom in closely enough, it's possible to manipulate individual samples.

While the Pencil Tool is very useful to correct a few wayward samples, or even to achieve some interesting effects, the Pencil Tool's resolution is limited to the amplitude display resolution (which is controlled by View→Smaller and View→Bigger). Since the maximum amplitude display resolution is 256, this means that samples touched by the Pencil Tool have an 8 bit resolution at best (i.e. at the highest amplitude display resolution). For individual samples or purposefully intended effects this is no big deal. But if you were to use the Pencil Tool to visually duplicate the waveform from a 24 bit recording, you would end up with what is effectively an 8 bit recording.

Mixer Tool

The Mixer Tool allows you to easily mix some audio onto a track. FIXME: more docs

Move Tool

The Move Tool allows you to reorder tracks. You can choose to move the audio data for a track, the mixer settings, or the markers, or any combination of these.


GNUsound can playback as many tracks as your hardware can handle. You can specify the number of output channels to use in the Settings→Preferences→Playback/Record. Every track can be mixed onto as many output channels as desired, using the mixer level controls (the rainbow colored horizontal bars to the left of each audio track).

GNUsound does not usually perform any implicit transformations of the audio format during playback[1]; it just tries to open the audio device with the same parameters as the audio file (number of bits, sample rate) and starts playback. An error will occur (or in some rare cases garbled noise will be played back) if the device cannot handle those parameters.

GNUsound does not attenuate mixed signals or check for output clipping: it is your responsibility to make sure you don't mix two channels too loudly.


GNUsound can record as many tracks simultaneously as your hardware will bear. You do this by selecting the tracks you wish to record on and issuing the Record command.

There is no relation between which tracks are selected and which input channels are actually recorded except for the number of channels: that is, if you select tracks 1 and 3 and then start to record, track 1 will receive the first input channel, and track 3 will receive the second input channel.

There is currently no way to explicitly control which input channels GNUsound records from. GNUsound will always incrementally assign the available input channels to the selected tracks. If there is one selected track, GNUsound records from the first available input channel, if there are two selected tracks, GNUsound records from the first two input channels, etcetera.

Saving files

You can save your work by issuing the File→Save command. Note that GNUsound does not preserve auxiliary info (such as loop points or instrument definitions) that may be embedded in an audio file. If you open a file containing such information and subsequently save it, overwriting the original, this information will be lost.

Envelopes, cuepoints and other GNUsound specific data are saved in a filename.usx file, in a fairly self-explanatory text format.


Another way to save files is through the File→Mixdown command. Mixdown "plays back" to disk, that is, it will write a file to disk which is virtually identical to the data written to the audio device. You just have to specify which output channels to mix down.

The purpose of this function is to reduce a large number of tracks to a smaller number, which is useful if you need to do a large amount of layering.

Memory management

GNUsound currently stores all its data, including clipboard and undo buffers, in memory. Ultimately some logic will be implemented to offload portions of that to disk, but for the time being you have to be a little considerate to prevent GNUsound from swallowing all available memory. One tool to help with that is under the Debug menu, where you can find the option Destroy Undo. This destroys all undo's, thus releasing all memory in use by the undo buffers. Of course you should only use this option when you don't need those undo's.


While a lot of effort has been expended on making GNUsound resilient in the face of adversity, all complex programs have bugs and GNUsound is no exception. Even if GNUsound itself was completely bugfree, there could still be bugs in the third party software that GNUsound relies on. So a lot of effort has also been expended on keeping your data safe when something does happen.

If GNUsound crashes it will try to save the waveform data in open and modified buffers to a file with the extension .crashed.wav. To do this it uses a very simple and robust set of functions which minimize the interaction with the (probably corrupted) environment. This emergency code stands a good chance of salvaging your data when the fallout from the crash is relatively localized. In other cases it might be impossible to salvage anything.

Due to the minimal nature of the emergency code, document settings (such as mixer settings, selection and loop points, envelopes, cuepoints, and grid settings) are never saved in the event of a crash.

If GNUsound crashes, please report it. Diagnostics which may be helpful in tracking down the problem are written to the file ~/.gnusound/gnusound.log.

[1] Although this depends on the selected audio driver; for example, the JACK driver will always convert audio data to the floating point format required by JACK.