man Pages(6): Demos

soundtool(6)

NAME

soundtool- audio waveform display demo

SYNOPSIS

/usr/demo/SOUND/bin/soundtool

DISCLAIMER

This program is furnished on an AS IS basis as a demonstration of audio applications programming.

DESCRIPTION

soundtool is an XView demonstration program that allows recording, playing, and simple editing of audio data. The display consists of six regions: a play/record control panel, a function control panel, an oscilloscope, a display control panel, a waveform display panel, and a pop-up audio status panel.

Play/Record Control Panel

Play/Stop: Clicking this button plays the currently selected region of data. While data is playing this button becomes a Stop button. If audio output is busy when Play is started, this button displays Waiting. When the device is available, the button switches to Stop and audio output begins. Clicking on the Waiting button resets the tool to the idle state.
Record/Stop: Clicking this button starts the recording of data from the audio input port that is wired to the 8-pin mini-DIN connector on the back of the workstation. While recording is in progress, this button becomes a Stop button. If audio input is busy when Record is selected, an alert pops up and the tool resets to the idle state. A maximum of 5 minutes may be recorded at a time.
Pause: Clicking this button while playing or recording suspends the current operation. The button becomes a Resume button that may be selected to continue the suspended operation.
Describe: Clicking this button brings up the ``Audio Status Panel''. If the panel was already visible, clicking this button removes it.
Quit: Clicking this button causes soundtool to exit.
Play Volume: This slider adjusts the playback volume. Volume levels between 0 and 100 may be selected, where 0 represents infinite attenuation and 100 is maximum gain.
Record Volume: This slider adjusts the recording level in the range 0 to 100.
Output To: This selector switches the audio output port between the built-in speaker and the external headphone jack.
Looping: When Looping is disabled, the current data region (i.e., the data between the two markers in the waveform display) is played once. If Looping is enabled, the selected data will be played endlessly until the Stop button is pressed.

Function Control Panel

Load

Clicking Load will read in the audio file specified by the Directory and File fields. If the named file does not contain a valid audio header, the raw data is copied into the buffer and an alert is displayed. Clicking the Store button at that point will rewrite the file with the proper audio file header.

Arbitrarily large audio files may be loaded. However, system swap space resources may be depleted (one minute of audio data consumes roughly .5 Mbyte of swap space).

Store

Clicking Store will write the selected data region into the file specified by the Directory and File fields. If the named file exists, an alert will request confirmation of the operation.

Append

Clicking Append will append the selected data region to the file specified by the Directory and File fields. The named file must contain a valid audio file header.

Directory

The Directory field specifies a directory path in which to look for audio files.

File

The File field designates the file to be loaded from, stored to, or appended to. Holding down the right mouse button on this field presents a menu of audio files in the currently designated directory. All files that contain a valid audio file header, or whose names have the suffix .au or .snd, are listed.

Oscilloscope

: When the program is in the idle state and the cursor is in the waveform display panel, the oscilloscope acts as a magnifying glass, displaying the region of the audio waveform that is currently under the cursor. When the program is playing or recording, the oscilloscope displays the data that is currently being transferred. Note that there is a small time lag in the display of recorded data, due to the fact that the audio device driver buffers input data and delivers it to the application in discrete segments.

Display Control Panel

Zoom

The Zoom slider adjusts the compression factor used in the display of the waveform. The upper compression limit is chosen so that the entire waveform will fit in the waveform display panel. [The lower limit is restricted by the ability to manipulate large scrolling regions in XView.] Adjustment of the Zoom slider ordinarily results in data compression or expansion around the center of the currently displayed waveform. If the waveform display contains one or both data selection markers, an attempt is made to keep at least a portion of the selected data region in the window.

The magnified waveform presented in the oscilloscope display is unaffected by the Zoom value. However, cursor movement over the waveform reflects the current compression; i.e., lower Zoom values result in finer granularity of mouse movement.

Waveform Display Panel

The waveform display shows all or part of the current waveform, depending on the current Zoom value. Scrolling of the waveform may be achieved either by using the scrollbar or by dragging the waveform to the right or left while holding the middle mouse button down. Note that scrolling is disabled when the entire waveform is being displayed (i.e., when the Zoom value is at its maximum).

In some cases, it is desirable to identify a subset of the waveform. For instance, the Play, Store, and Append functions operate on a selected region, rather than the entire waveform. The currently selected region of interest is delimited by dashed vertical lines. A new region may be selected by clicking the left or right mouse button and dragging it across the desired region of interest. Alternatively, a single click on the left (or right) mouse buttons adjusts the start (or end) point.

Audio Status Panel

: This panel is displayed (or removed) when the Describe button is pressed. It contains fields that describe the data in the buffer.
Sample Rate: This field displays the sampling frequency, in samples per second.
Channels: This field denotes the number of interleaved channels of audio data.
Precision: This field identifies the encoding precision, in bits per sample.
Encoding: This field displays the encoding format.
Total Length: This field shows the length of the entire data buffer, in the form hh:mm:ss.dd.
Selection: This field identifies the start and end times of the currently selected region of interest.
Info String: When an audio file is loaded, the first 80 characters of the information field of the audio header are displayed in this field. This string may be edited, though the new information is only written out when the Store operation is performed.

BUGS

Currently, soundtool is capable of displaying only 8-bit mu-law encoded data (as in the Greek letter mu).

Audio files should be mapped in order to reduce the swap space requirements. The limit on recording length should also be removed.

There are problems with scrollbars that operate on very large canvases. This constraint is the reason for the lower limit on zooming. Also, there are some problems with the display of very large audio files with a low zoom factor.

Region selections made over the waveform display panel work best when the click and drag paradigm is used. Adjusting the start or end points by a single click is susceptible to error; i.e., if the mouse moves slightly between the button down and up events, the result will be a very small selection.