Programmer Guide/Macro Library/XWave

This STx-related article may be outdated.

XWave : CObjEx

A wave I/O class for signal processing in scripts.

XWave Construction

Create a new XWAVE instance. The XWAVE references either a segment (aseg), a whole sound file (soundfile) or a wave-item signal (wave). Information and error messages are written to the script console. If no optional arguments are specified, only the instance is created, otherwise the frame-setup is also performed (see member SETFRAME).

Usage:

XWAVE aset ; aseg ; ach [; mode ; length ; shift ; amax ; aref]

XWAVE soundfile [; mode ; length ; shift ; amax ; aref]

XWAVE wave [; mode ; length ; shift ; amax ; aref]

Parameters

aset

An audio set reference.

aseg

A segment ID.

ach

A channel index.

soundfile

The path to a sound file on disk.

wave

The id of a wave item.

mode

Optional argument for frame-setup.

length

Optional argument for frame-setup.

shift

Optional argument for frame-setup.

amax

Optional argument for frame-setup.

aref

Optional argument for frame-setup.

Result:

A new XWAVE instance if successful or an empty string.

Notes:

You can also use "cobj new xwave ..." to create a XWAVE object. You can delete an XWAVE object using "COBJ DELETE xwaveobject" or "xwaveobject DESTROY".

XWave Member Functions

The XWave class implements the following member functions. See CObjEx Member Functions for a list of functions implemented in the parent class.

Next

Usage:

xwave Next

Result:

Returns 1 if the end of the signal is reached, otherwise 0.

Description:

Increment the frame index.

Read

Read one signal frame. Returns a buffer (vector or matrix) containing the signal or an empty string. If a buffer is passed, the signal is stored in this buffer. If read fails or the end of the signal is reached and a buffer is passed, the buffer is deleted. The returned signal is scaled with the factor 'amax' (set during SetFrame).

Usage:

xwave Read next=1 ; buffer=

Parameters:

next

Increment frame index (0=no, 1=yes). If this parameter is not specified the frame index is incremented.

buffer

The signal buffer. If no buffer is specified or the specified buffer is invalid, a new buffer is created.

Result:

Returns a buffer (vector or matrix) containing the signal or an empty string.

ReadQ

Quickly read the next frame.

Usage

xwave ReadQ

Result

A signal vector of the next frame.

SetFrame

Set the I/O frame parameters.

Usage

xwave SetFrame mode ; length ; shift=25% ; amax=1 ; aref=1

Parameters

mode

The I/O mode. Either the first frame starts at the beginning of the signal (left aligned: mode=0) or the first frame is centered around signal beginning (centred: mode=1).

length

The frame length (a time expression).

shift

The frame shift (time expression). shift must be lower or equal to length.

amax

The maximum signal amplitude or one of the following calibration keywords: CALATTR (use the audioset attributes AmpMax and AmpRef) or CALSET (use the calibration set linked to the signal).

aref

The reference signal amplitude (=0dB). This is only used if amax is a number.

Result

Returns the number of frames (>1) or 0 for error.

TBegin

Set the signal begin time in the selected unit. If the unit is not specified, samples is used.

Usage:

xwave TBegin [ samples|s|ms ]

TEnd

Set the signal end time in the selected unit. If the unit is not specified, samples is used.

Usage:

xwave TEnd [ samples|s|ms ]

TLength

Set the signal begin time in the selected unit. If the unit is not specified, samples is used.

Usage:

xwave TLength [ samples|s|ms ]

Play

Play the assigned signal using the PlayWave class.

Usage:

xwave Play

XWave Attribute Functions

The following functions return attribute values from the XWave instance but do not modify the instance.

FRAMELENGTH

Usage:

xwave FRAMELENGTH

Result:

Return the framelength in samples.

FFTLENGTH

Usage:

xwave FFTLENGTH

Result:

Return the next power of 2 of the framelength.

FRAMESHIFT

Usage:

xwave FRAMESHIFT

Result:

Return the frameshift in samples.

FRAMECOUNT

Usage:

xwave FRAMECOUNT

Result:

Return the number of frames.

FRAMEINDEX

Usage:

xwave FRAMEINDEX

Result:

Return the index of the current frame.

AMAX

Usage:

xwave AMAX

Result:

Return the value of the maximum signal amplitude.

AREF

Usage:

xwave AREF

Result:

Return the value of the reference signal amplitude.

SRATE

Usage:

xwave SRATE

Result:

Return the sampling rate in Hz.

SAMPLES

Usage:

xwave SAMPLES

Result:

Return the signal length in samples.

CHANNELS

Usage:

xwave CHANNELS

Result:

Return the number of signal channels.

WAVE

Usage:

xwave WAVE

Result:

Return the internal wave object id.

WAVECOPY

Usage:

xwave WAVECOPY

Result:

Return a virtual wave object linked to the internal wave object.

TITLE

Return the title text (as generated during construction).

Usage:

xwave TITLE

Result:

The text displayed in the title.

TYPE

Usage:

xwave TYPE

Result:

Return the type of signal associated with the instance. The result depends on which method was used to create the instance:

WAVE

FILE; filepath

ASEG;aset;aseg;ach