Programmer Guide/Shell Items/Wave/SET WAVE

Wave Item
INTRODUCTION	NEW	SET	ATTRIBUTES	MESSAGES	EXAMPLES

The SET WAVE commands are used to manipulate wave items. This includes:

• playback
• recording
• device setup
• sequence definition

See Wave Item Attributes for a list of wave item attributes.

Copying signals

The following commands can be used to copy signal data to and from a wave item. Note that the wave item wave must be associated with a file on disk, otherwise you will get a wave item has no data-stream error (63).

COPY

SET wave COPY targetWave [copybufferbytecount] [/Reverse]

Copy a signal between wave items. Copy the signal of the wave item wave into the soundfile segment addressed by the wave item targetWave. Both wave items must have the same sampling rate and the same number of channels. The length of the source signal must be shorter than or equal to the length of the target signal. The command returns when the signal has been copied. The size of the copy buffer is automatically set but can also be supplied in the command. The option /Reverse can be used to reverse the signal in time.

targetWave

The wave item into which to copy the signal.

copybufferByteCount

The size of the copy buffer. Leave unspecified, for an automatic buffer size.

/Reverse

If specified, the reversed wave signal is copyied to targetWave.

SET wave COPY table [startColumn] [/Write]

Copy data from the table item table to the wave item wave (no option) or vice versa (/Write). The startColumn is the column where the first channel should be written to or read from. The other channels values are assigned to or read from the column startColumn+n-1, where n is the channel number. The number of channels (or columns) which are copied is determined by how many channels the wave item has.

table

The table item to copy data to or from. The columns to be copied must be numerical columns (The table must be an extended or parameter table).

startColumn

The first table column to copy data to or from. This column is associated with channel 1.

/Write

If specified, copy from the wave item to the table.

SET wave COPY output vectorIndex|* [/Write]

Copy data to a value item or SPU. If the option /Write is used, the data is copied from the value item or SPU into the wave item.

output

The name of a value or spu item (e.g. spu.outputName).

vectorIndex

If output is an array, output[vectorIndex] is used. If output is a vector, vectorIndex is ignored (you can use an asterisk

/Write

If specified, data is copied from output into the wave item.

///////////////////////////////////////////////////////////////////////////////
//
//  Macro:          waveitemcopy
//  Description:    A Macro to copy one sound file to another demonstrating
//                  the SET wave COPY command
//  Parameters:     none
//  Author:         Jonnie White
//  History:        2006-06-27  created
//  Notes:          This is a very simple macro. The difference between the
//                  lengths or sampling rates of the two soundfiles is not
//                  taken into consideration.
//
//                  If you have any suggestions or corrections, please get
//                  in touch with Jonnie White
//
///////////////////////////////////////////////////////////////////////////////
[macro waveitemcopy]
    // source and target soundfiles for copying
    #target := butil filedialog open ; Select the target soundfile ; * ; wav=soundfile
    #source := butil filedialog open ; Select the source soundfile ; * ; wav=soundfile
    if '$#target' == '' || '$#source' == '' then
        em -1 ; Please rerun the macro and select both source and target soundfiles.
    end
    
    // open soundfile and create corresponding wave item
    bsf 'open $#target ; write'//write!!!
    if '$result' != 0 em $result ; Failed to open the target $#target
    readvar CSFH #sr #channel #samples #
    #targetWave := new wave * '0_$#samples' $#channel
    if '$#targetWave[?]' != 'wave' em $rc ; Failed to create target wave item
    // play target wave
    PlayWave $#targetWave

    // open source soundfile and create corresponding wave item
    bsf 'open $#source ; read'
    if '$result' != 0 em $result ; Failed to open the source $#source
    readvar CSFH #sr #channel #samples #
    #sourceWave := new wave * '0_$#samples' $#channel
    if '$#sourceWave[?]' != 'wave' em $rc ; Failed to create wave item
    // play source wave
    PlayWave $#sourceWave
    
    // get source wave as a table
    #tSource := $#sourceWave[!signal]
    if '$#tSource[?]' != 'table' em $rc ; Failed to get source signal as table.

    // copy source to target
    $#targetWave copy $#tSource 0

    // play modified target (should sound like the source)
    PlayWave $#targetWave

    // clean up items
    delete $#targetWave $#sourceWave $#tSource
    // close soundfiles
    bsf close '$#source'
    bsf close '$#target'
exit

Use WAVE Items in Numerical Expressions (EVAL)

The signal stored in (addressed by) a wave item can be used directly as vector or matrix in numerical expressions of the command EVAL. How to use wave items in numerical exprssions is described in the section numerical objects.

A very simple way, to copy a signal, is shown in the following example.

$#targetWave[!signal,*] := eval $#sourceWave[!signal,*] 

The following example shows, how wave items can be used for signal processing in the command EVAL.

// compute rms values with time constant 125ms, use 50% window overlap
// input:  wave item #wave containing a mono signal
// result: rms vector #rms in dB
#rms := new table * * x /p             // create numeric table for rms values (vector)
#wlen := eval $#wave[!srate] * 0.125   // set window length to 125ms
for #p := 0 to $#p+$#wlen <= $#wave[!length] step #p := int $#p + $#wlen/2
    $#rms * '$(eval ($#wave[!signal,1,$#p,$#wlen] ^ 2) / $#wlen)'
end
$#rms := eval lin2log($#rms, 1, 10)

Playback and Recording

The following subcommands can be used for playback and recording.

PLAY

SET wave PLAY [ samples count begin end timeritem [ gain ][ mTable [ mField=0 ]]] [ /1|2|3|4 ] [ /Reverse ]

Start playing the signal of wave-item wave. The arguments samples and count are used in the play-function for I/O-buffer allocation. The sample values begin and end can be used to play only the selected part of the signal. If the option /Reverse is specified, the signal is played backwards (end -> begin). For wave-out devices using digital-to-audio converters (DACs) with a higher sample resolution than normal adapters, the options /2, /3 or /4 select the number of bytes per sample.

The argument timeritem is the name of a value item (with a configured and stopped timer). If specified, it is used as a timer running synchronously with the playback process. Note that if you do not use a timer, you may need to use another method to pause macro execution until the sound file has finished playing (e.g. messages or dialog box).

The parameters mTable and mField can be used to map specific wave channels to specific soundcard device channels. If these parameters is not specified, the soundcard's channels are automatically mapped 1=1, 2=2, 3=3. If the soundcard has more channels than the wave item, these extra channels are not mapped. A wave-item channel can be mapped to more than one device channel. A device channel can only be mapped to once. If mapping is used, then only mapped channels are played. If an entry contains an invalid device or or wave-item channel value, the entry is ignored.

samples

The number of samples in a playback buffer. If an asterisk is specified, the default buffer length is used.

count

The number of buffers to use for playback.

begin

The sample to start playing from.

end

The sample to stop playing at.

timeritem

A value item configured as a timer and stopped.

gain

The linear gain value to use for playback. If an asterisk is specified or the parameter is not specified, the value is not changed.

mTable

A shell-table with entries mapping wave-item channels to wave-device channels. The table must have at least two consecutive numerical fields (mapField, mapField+1). The field mapField must contain the wave-item channel index (1 - nWaveChannels) and the field mapField+1 must contain the wave-device channel index (1 - nDeviceChannels). Each table entry can map one channel.

mField

The zero-based index or id of the mTable field containing the wave-item channel index. The default is the first field (0).

/1|2|3|4

Use this option to specify the number of bytes to use per sample.

/Reverse

Play the signal backwards.

See also

• macro ShowItem → use the general item-data display macro for playback showitem mywaveitem ; myplaydialogtitle
• class PlayWave → this class implements a dialog for the playback of any kind of signal object
• class XWave → a class for accessing signals e.g. for dsp algorithms; implements a simple playback function

RECORD

SET wave RECORD [samples count begin end timeritem [mTable [mField=0]]] [/1|2|3|4]

Start recording the signal into the soundfile segment addressed by the wave item wave. See PLAY for a description of the arguments and options.

If the map parameters are used, then only mapped channels are recorded. One device channel can be mapped to more than one wave-item channel whilst one wave-item channel can only have one device channel mapped to it.

STOP

SET wave STOP

Stop playback/recording immediately.

The real-time I/O process (play or record) is started immediately. While it is running, RUN messages containing information about the current I/O position are sent to the shell. The I/O position is increment by the sample value according to the specified buffer size. When the I/O process is stopped or finished, a STOP message is sent. If a timeritem was supplied in the command, its timer is started synchronously with the real-time I/O process and can be used to get position information or playback time independent of the buffer size. If the selected format used for I/O (/2|3|4) differs from the format of the wave item, the signal is converted from the wave item format before it is written (RECORD) or to the wave item format after it is read (PLAY).A very simple way to play/record (short signals) is using a wave item of type ADC or DAC and the wave copy command.

DEVICE

SET wave DEVICE [input output] [/Initialize [/Asio] ]

Specify the recording (input) and playback (output) device to be used by STx real-time I/O functions. Valid values for input and output are an index of a device listed in the device-mapping-list (see wave item attributes), the value '*' (do not change assignment) or the keyword AUTO (use default device selected by the system). STx no longer initializes all I/O devices on startup. You have to initialize the device with the option /Initialize. ASIO devices are not initialized unless the option /Asio is specified. The command no longer supports ADAT.

The assigned settings are used by all real-time functions and all shells!;wavein

The zero-based index of the wave-in device to use, an asterisk if the current device setting should be kept or AUTO if the system's default device should be used.

waveout

The zero-based index of the wave-out device to use, an asterisk if the current device setting should be kept or AUTO if the system's default device should be used.

/Initialize

Initialize the device.

/Asio

Initialize the ASIO interface of the device.

The number of wave items which can record or playback at the same time is dependant on the type of device and the Windows operating system. ASIO devices can have an unlimited number of wave items attached to them. During playback or recording, all wave items must, however, use the same device. MME under Windows 2000 supports one playback and one recording wave item per device. MME under Windows XP supports one playback and multiple recording wave items per device. All wave items must have the same sampling rate. Another way to play signals from different sources synchronously is to use a wave-item of type sequence (see NEW WAVE).

Sequences

Sequences are useful for generating, filtering and concaternating signals. A sequence can contain different signals in each channel.

These functions create and modify or filter sequence signals. A sequence wave object is created with the NEW wave command and the option /Q. Once you have finished defining and filtering your sequence signal, use the SET sequence END command to generate the wave signal.

Filtering a Sequence

Modify and filter a sequence with the following commands. These functions can only be applied to sequence wave objects.

Envelope

SET sequence ENVELOPE t1 a1 [t2 a2 ]... [/Linear|Cosine]

Define an amplitude envelope for the last added signal. The envelope is defined by the cue points ti/ai and the function type /Linear (default) or /Cosine (rising/falling half-wave) that is used to connect the cue points. If no cue point is defined at the begin and/or end of the signal, a cue-point with amplitude 0 is automatically added. The time values ti are offsets to the begin (>= 0) or end (<0) of the signal and can be specified in samples (ti), seconds (tis), milliseconds (tims) or percentage of the signal duration (ti%). The amplitude ai is the amplification factor at time ti. The number of cue points is unlimited.

Filter

SET sequence FILTER fmin fmax o r d [/Invert] [/Butterworth|Chebychev|Elliptic]

Define an infinite impulse response (IIR) filter for the last added signal. The filter is defined by its passband frequencies (fmin to fmax in Hz), the filter order o (>=2), the passband ripple r in dB and the stopband damping factor d in dB. The option /Invert can be used to invert the frequency response (e.g. to create bandstop/notch filters). The type of the filter is selected with the options /Butterworth, /Chebychev or /Elliptic (default).

SET sequence FILTER table cf m gf gmode gval gtyp /Speech

Define a speech filter. For this filter the same algorithm as for the speech synthesis is used, but the last defined signal is used as source signal instead of the synthesizers internal generators. For a description of the filter arguments see 'SET sequence SIGNAL ... LPSYN ...'. The length of one filter frame is set to:

framelength = signal_samples / table_entries.

Modulation (AM/FM)

SET sequence AMOD fac rate [par] [/Sine|Rectangle|Triangle]

SET sequence FMOD bw rate [par] [/Sine|Rectangle|Triangle]

Apply an amplitude and/or frequency modulation (or AM & FM simultaneously) to the last added signal. The modulation function can be a sine wave (default; frequency rate, initial phase par), a rectangle or a triangle (frequency rate, duty cycle par).

fac	modulation factor (0..1)
bw	frequency modulation bandwidth (Hz)
rate	modulation rate (Hz)
par	Triangle, 0..1)

AM:

FM:

mf	modulation function; see description of signals TONE (with n=1), RECTANGLE and TRIANGLE
sf	signal function (carrier); for FMOD, sf must be a signal generator with a frequency argument

SET sequence FMOD df k /sWeep

Linear or exponential frequency sweep (chirp).

df	sweep width, can be set to a positive or negative value
k	exponent (if >0)

SET sequence AMOD table tfield vfield vref /Linear|DB

SET sequence FMOD table tfield vfield vref /Hz|KHz|Cents

In addition to the standard AM/FM functions a table lookup method is available, which uses a table item to define the amplitude envelope (AM) or frequency contour. Each entry of table defines the relative position (ti = table[i,tfield]) and the value (vi = table[i,vfield]; amplitude factor or frequency offset) of a point of the modulation function. The values between the points are interpolated. The time values must be specified in ascending order and are mapped to the length of the modulated signal. The relative time values are mapped to absolute sample positions of the sequence signal with following method: signalsamples . (ti – t0) / (tn-1 – t0)

table	name of table item
tfield	id of time field (t0 .. tn-1), if set to * the time values are set to ti=i
vfield	id of value field (v0 .. vn-1)
vref	reference value or factor

AM:	/Linear	linear amplitudes	ai = vref . vi
	/DB	amplitudes in dB	ai = vref . log10(vi/20)
FM:	/Hz	frequencies in Hz	fi = vref . vi
	/KHz	frequencies in kHz	fi = vref . vi
	/Cent	frequencies in Cent	fi = vref . 2vi/1200

The functions ENVELOPE, AMOD, FMOD and FILTER are always applied to the last added signal of the sequence!Frequency modulation (FMOD) can only be applied to periodical signals generated by function generators (TONE, RECTANGLE, TRIANGLE and TABLE (type 2)).A sequence can contain different signals in each channel.If the signals of a sequence are partly or fully overlapped, they are mixed (add) or multiplied. If different operations (mix and multiply) for overlapping signals are used, first the signals with operation "add" (default) are generated and mixed and than multiplied with the signals with operation "multiply" (option /Multiply). At least one signal with operation "add" must be defined, otherwise the result will always be a zero signal.Accessing the signal of a sequence more than once may lead to different results (signal outputs) because the function generators, filters and modulators are 'causal systems' which cannot be repositioned in time. To avoid this problem use the option /Evaluate when closing the configuration section or use a temporary soundfile to save the signal before processing. If all signals are soundfile segments, multiple access is possible.The application STx implements a simple user-interface to create, edit and process (analyse, play, ...) sequences. The development of a graphical sequence editor is planned. In the script language the macro package BSEQ implements a high-level programming interface for sequences. The latest features (table AM/FM, table lookup synthesis and speech synthesis/filter) are not integrated in the user interface and not supported by BSEQ.

Define Sequence Signals

These functions can only be applied to sequence wave objects.

SIGNAL

SET sequence SIGNAL base time channel type parameters [/Multiply /Normalize]

Place a signal in a sequence wave item and define the signal source or signal generator.

base	BEGIN|END)
time	end of last added signal (base=BEGIN|END) in samples
channel	* for all channels
type, parameters	signal type and parameters (see list below)
/Normalize	normalize signal amplitudes (depends on signal type, see list below)
/Multiply	multiply the signal with overlapping signals, default: add (mix)

Segment

SET sequence SIGNAL base time channel SEGMENT seg ch [gain] [/R]

The signal stored in segment seg and channel ch of the current soundfile is placed in the sequence. If seg is not specified or set to '*', the whole soundfile is added. The argument gain is an optional attenuation factor. The option /Reverse can be used to address the segment time reversed.

Wave Item

SET sequence SIGNAL base time channel WAVE item [gain]

The signal stored in the wave-item item is placed in the sequence. Any type of wave-item can be used except for the sequence wave itself. The argument gain is an optional attenuation factor.

Pause

SET sequence SIGNAL base time channel PAUSE dur

Add a zero signal (pause) with duration dur (in samples) to the sequence. Note: zero signals are placed automatically between non-overlapping signal regions. The type PAUSE can be used, to append a zero signal to the end of the sequence.

Constant (DC)

SET sequence SIGNAL base time channel VALUE dur dc

Add a signal with all sample values identical to dc and a duration of dur samples to the sequence.

Noise

SET sequence SIGNAL base time channel NOISE dur gain

Place a white noise with duration dur samples in the sequence. To generate the signal, a random number generator with linear distribution in the interval (-gain, gain) is used.

Rectangle

SET sequence SIGNAL base time channel RECTANGLE dur a f [d]

Generate a rectangle-waveform with frequency f (Hz), amplitude a, dutycycle d (0<d<1) and a duration of dur samples.

Triangle

SET sequence SIGNAL base time channel TRIANGLE dur a f [d]

Generate a triangle-waveform with frequency f (Hz), amplitude a, dutycycle d (0<d<1) and a duration of dur samples.

Tone

SET sequence SIGNAL base time channel TONE dur a f [p n da df] [/N]

Generate a sine wave or a harmonic tone (with additive synthesis) a frequency f (Hz), amplitude a, phase p (def.=0 rad), n components (def.=1) and a duration of dur samples. The arguments df (def. = 0Hz) and da (def.=1) can be used for frequency shifting and to generate components with different amplitudes. With the option /N (normalize) the amplitude a is divided by the number of components n.

Lookup

SET sequence SIGNAL base time channel TABLE tab dur a tid ft f0 [/N]

SET sequence SIGNAL base time channel TABLE val dur a vid ft f0 [/N]

The table tab (numeric field tid) contains samples of one period of a signal with frequency ft. A table lookup algorithm (with linear interpolation) is used to generate a tone (consisting of frequency modulated table-periods) with the frequency f0. This means, the signal-period stored in tab is re-sampled with a frequency of f0/ft. Alternatively, a value item can be used to define the signal period instead of a table.

tab, tid	name of table item (tab) and id of field (tid) containing wave-table samples
val, vid	OUTPUT) containing wave-table samples
dur	duration of the signal in samples
a	gain factor
ft	frequency of signal period stored in table
f0	frequency of generated signal

Speech Synthesis

SET sequence SIGNAL base time channel LPSYN table fdur cf m ff fmode fval gf gmode gval gtyp styp

Generate synthetic speech using a LPC synthesizer. The reflection coefficients (rci; i=0..m-1), gain (g) and fundamental frequency (f0) values are stored in a table. Each entry contains the synthesis parameters for one frame.

table	table item with synthesis parameters
fdur	duration of one synthesis frame; to reproduce the original timing, use the frame distance of the analysis
cf	id of 1st coefficient field; field cf+i [Right Arrow] rci
m	number of coefficients
ff	id of field containing f0 values or –1 if f0 is not supplied
fmode,fval	'NORMAL' f0 track is not modified; fval is not used 'CONSTANT' fval is constant f0 value in Hz 'FACTOR' fval is linear f0 scaling factorIf no f0 field is supplied, fmode is ignored and fval is used as constant f0 value.
gf	id of field containing gain values or –1 if gain is not supplied
gmode, gval	'NORMAL' gain is not modified; gval is not used 'CONSTANT' gval is used as constant gain value 'FACTOR' gval is used as gain scaling factor 'NORMALIZE' gain track is normalized to value gval If no gain field is supplied (gf=-1 or not defined), gmode is ignored and gval is used as constant gain value.
gtyp	'LINEAR' gain values are linear 'ENERGY' gain values are an energy (e.g. the error energy alpha of the lpc analysis)
styp	'PULSE' voice source is a unit pulse 'WAVETABLE' voice source is internal wave table (filtered pulse)

END

SET sequence END [/Evaluate]

This command must be executed as the last statement of a sequence definition. It closes the definition part and prepares the sequence for signal generation. After this command, the signals of the sequence cannot be modified and no new signals can be added! If the option /Evaluate is specified, the signal is generated and stored in a virtual wave buffer. This can be used if the signal should be read out more than once (to avoid recursion/repositioning problems of filters, generators and modulators) or to minimize computation time during access. The option /Evaluate may lead to problems if the signal is very long (depends on the availability of virtual memory).