Programmer Guide/Macro Library/BSeq

File: BSeq.STX, linked to library STX.LIB

See also: Sequences

The class BSeq can create and play sequences and provides an interface to the Programmer_Guide/Shell_Items/Wave/SET_WAVE#sequence wave-item functions.

Create a new Instance of BSeq

Usage

bseq [ attr=value ; ... ]

cobj new bseq [ attr=value ; ... ]

attr=value, ...

initial values for sequence attributes (see member function Set)

Result

An instance of BSeq or an empty string

Description

Create and initialize a sequence instance and assign sequence attributes. To assign the attribute(s) the member function Set is called.

Set Attributes

Usage

bseq_instance set attr=val [ ; ... ]

attr=val

Assign the value val to the attribute attr (see description below)

Result

always 0

Description

Assign sequence attributes. An attribute value is assigned only if it is valid. For some attributes automatic corrections are applied. Multiple attribute assignments separated by semi-colons can be specified. Attribute names and value keywords can be abbreviated.

Supported attributes:

• channel=n → set the number of channels (1 ≤ n ≤ 256)
• envelope=type,ton,toff → set global envelope type (none, linear or cosine) and the on/off time (in ms, ≥ 0).
• factor=a → set global amplitude factor (a ≠ 0)
• srate=frq → set sampling rate in Hz (> 0).

Get Attribute

Usage

bseq_instance get attr

attr

name of the attribute to retrieve (see description below)

Result

value of specified attribute or an empty string

Description

Retrieve a sequence attribute.

Supported attributes:

• channel → get number of channels
• envelope → get global envelope definition (type,ton,toff)
• factor → get global amplitude factor
• srate → get sampling rate
• signals → get number of signal definitions
• table → get signal definition table

value

The value to set the attribute to. See attr for details.

Result:

An empty string.

BSeq Member Functions

The BSeq class has the following member functions. See CObj Member Functions for a list of functions implemented in the parent class.

AMod

Define/undefine an amplitude modulation function for the signal pos. The amplitude modulation is computed as follows:

y(t) = ((1 – fac/2) + m(t).fac/2) . x(t)

with:

y(t)	modulated sequence signal
x(t)	sequence signal
m(t)	modulation function, depends on type, rate and dc or phase
fac	modulation factor (0 <= fac <= 1)

Usage:

inst AMod pos ; type ; rate ; factor ; dc|phase

Parameters:

pos

The signal index (* for the last defined signal).

type

The type of modulation function. The following types are supported:

none|rectangular|triangle|sine

rate

The modulation rate in Hz.

factor

The modulation factor.

dc

The duty cycle (if the type is rectangular or triangle).

phase

The starting phase (if the type is sine).

Result:

0 for success and a non-zero value if failed

Parameters:

attr

The name of the sequence attribute.

value

The value of the sequence attribute.

Result:

0 for success and 1 for error

Note that you can create an instance of the BSeq class with the following syntax:

#inst := BSeq

Copy

Copies the sequence signal to the specified target. To perform the copy function the class BSIGNAL is used.

Usage:

inst Copy mode ; sch ; tset ; tseg ; tch ; tmode ; tname

Parameters:

mode

This parameter is currently not used, but is reserved for future expansions.

sch

The sequence channel list (see CreateWave).

tset

The target audio set.

tseg

The target segment reference, id or expression.

tch

The target channel.

tmode

The target mode. The following values are supported:

insert|replace|mix

tname

The name for the copied signal.

Result:

0 for success and a non-zero value if failed.

CreateSegments

Creates audio segments (ASeg elements) for all defined signals and stores them in the specified DataSet element. Also a segment named Signal.All for the whole sequence signal is created. The segment names are chosen automatically.

Usage:

inst CreateSegments ref

Parameters:

ref

The reference to a DataSet element of type ASequence.

Result:

The number of created segments.

CreateWave

Creates the sequence wave item and prepares it for use. If create succeeds the wave item is returned and can be used for signal processing. Otherwise the error information is written to the log. window and an empty string is returned. If a channel list argument is specified only the requested channels are created. If the definition contains signals of type segment, the sound files are opened automatically before the wave item is created. The returned wave item must be deleted with the member function DeleteWave and not with the command 'delete waveitem'!

Usage:

inst CreateWave [ sch ]

Parameters:

sch

The sequence channel list (blank separated list of channel indices).

Result:

The name of the created sequence wave item or empty string if creation fails.

Delete

Delete the signal pos from the sequence.

Usage:

inst Delete pos

Parameters:

pos

The signal index (* for the last defined signal).

Result:

Always 0.

DeleteWave

Deletes the sequence wave item created with CreateWave and closes all sound files opened during creation.

Result:

Always 0.

Destruct

Remove sequence and sequence wave item (if created).

Result:

none

DialogEdit

Displays a dialog to add, modify and delete signal definitions.

Result:

none

DialogSetup

Displays a dialog to change the sequence attributes.

Result:

0 for OK and 1 for cancel.

Envelope

Define/undefine an envelope function for the signal pos. An envelope is defined by the function type and a set of points, each one defined with a time and an amplitude value (tX and aX). The time values can be specified as an offset from the beginning (tX > 0) or from the end (tX < 0). If an amplitude is defined, the signal starts and ends with a zero amplitude.

Usage:

inst Envelope pos ; type ; t1 a1 t2 a2 ...

Parameters:

pos

The signal index (* for last defined signal).

type

The type of envelope. The following values are supported:

none|linear|cosine

tX,aX

The envelope points (tX = time in seconds, aX = linear amplitude).

result:

0 for success and a non-zero value if failed

Filter

Define or undefine a filter for the signal pos. The filter applied to the signal is an IIR filter of the specified type. The arguments f1, f2 and inv define the frequency band and filter type:

f1 = 0, f2 > 0, inv = 0 // lowpass f1 > 0, f2 = samplingrate / 2, inv = 0 // highpass 0 < f1 < f2 < samplingrate / 2, inv = 0 // bandpass 0 < f1 < f2 < samplingrate / 2, inv = 1 // bandstop

The parameters order, damp and ripple are used for the coefficient computation.

Usage:

inst Filter pos ; type ; f1 ; f2 ; inv ; order ; damp ; ripple

Parameters:

pos

The signal index (* for the last defined signal).

type

The type of filter. The following values are supported:

none|elliptic|butterworth|chebychev

f1,f2

The frequency band.

inv

Invert - yes|no, 0|1

order

The filter order must be an integer greater than 1. The default is 5.

damp

The stopband damping in dB must be a number less than -9 or greater than 9. The default is 60.

ripple

The passband ripple in dB must be a number between -10 and 10. The default is 1.

Result:

0 for success and a non-zero value if failed.

FMod

Define or undefine a frequency modulation function for the signal pos. A frequency modulation can only be defined for signal generators which generates a periodic signal (e.g. rectangle, triangle or tone). The frequency modulation is computed as follows:

f(t) = f + bw/2.m(t)

with:

fc	the fundamental frequency of the generator (carrier)
f(t)	modulated frequency
m(t)	modulation function, depends on type, rate and dc or phase
bw	modulation bandwidth in Hz (>0)

Usage:

inst FMod pos ; type ; rate ; bw ; dc ; phase

Parameters:

pos

The signal index (* for the last defined signal).

type

The type of modulation function. The following values are supported:

none|rectangle|triangle|sine

rate

The modulation rate in Hz.

bw

The modulation bandwidth in Hz.

dc

The duty cycle (if type is rectangle or triangle).

phase

The starting phase (if type is sine).

Result:

0 for success and a non-zero value if failed

Define or undefine an frequency sweep function for the signal pos. A sweep can only defined for signal generators which generates a periodic signal (e.g. rectangle, triangle or tone). The sweep is computed as follows:

for exp = 0: f(t) = f + width . t / d for exp > 0: f(t) = f + width . (t / d)exp

with:

fc	fundamental frequency of the generator (carrier)
f(t)	modulated frequency
width	sweep width in Hz (any number)
exp	sweep function exponent
d	signal duration

Usage:

inst FMod pos ; SWEEP ; width ; exp

Parameters:

pos

See above

width

The sweep width in Hz (positive and negative values are allowed).

exp

The sweep function exponent (>= 0).

Result:

0 for success and a non-zero value if failed.

Get

Get an attribute value. Any valid Set attribute name can be used as the attribute name. In addition the keyword SIGNALS (gets the number of defined sequence signals) and the keyword TABLE (get signal definition table) can be used.

Usage:

inst Get attr

Parameters:

attr

The name of the attribute.

Result:

The value of the attribute or empty string.

Load

Loads the signal definitions from child element ASequenceSignals of the specified DataSet element. The signal definition table is cleared before the element is loaded.

Usage:

inst Load ref

Parameters:

ref

The reference to a DataSet element containing a sequence signal definition element with tag ASequenceSignals.

Result:

0 for success and a non-zero value if failed.

Play

Plays the sequence. The class PlayWave is used for playback.

Usage:

inst Play dialog [; sch ]

Parameters:

dialog

Display a play dialog or play without a dialog. The following values are supported:

0 - do not display a dialog

1 - display a dialog

sch

The sequence channel list (see CreateWave).

Result:

0 for success and a non-zero value if failed

Save

Stores the signal definitions in the child element ASequenceSignals of the specified DataSet element.

Usage:

inst Save ref

Parameters:

ref

The reference to a DataSet element.

Result:

0 for success and a non-zero value if failed.

Signal

Define a new sequence signal and add it to the sequence definition. If ch is set to 0 or * the new signal is added to each sequence channel, otherwise it is added only to the specified channel. The timebase base selects how the time value time is used. If base is set to absolute, time is an absolute value relative to the beginning of the signal. If base is set to begin or end, time is an offset to the beginning or end of the previous signal. The signal itself is defined by sigtype and sigpars.

Usage:

inst Signal ch ; base ; time ; sigtype ; sigpars

Parameters:

ch

The sequence channel (0 or * for all channels).

base

The time base. The following values are supported:

absolute

begin

end

time

time value in seconds

sigtype

The type of signal. The following values are supported:

PAUSE | VALUE | NOISE | RECTANGLE | TRIANGLE | TONE | SEGMENT

sigpars

The parameters for the specified signal type.

PAUSE ; d

A zero signal with a duration of d seconds.

VALUE ; d ; v

A constant signal (dc) with a duration of d seconds and an amplitude v.

NOISE ; d ; a

A linear distributed noise with a duration of d seconds and an amplitude a.

RECTANGLE ; d ; a ; f ; q

A rectangle function with a duration of d seconds, an amplitude a, a frequency f Hz and a duty cycle q (0 < q < 1).

TRIANGLE ; d ; a ; f ; q

A triangle function with a duration of d seconds, an amplitude a, a frequency f Hz and a duty cycle q (0 < q < 1).

TONE ; d ; a ; f ; p ; n ; da ; df

A sine wave or a harmonic tone with a duration of d seconds, an amplitude a, a frequency f Hz and a phase p rad. If the number of harmonics n is greater than one, the values da (def.=1) and df (def.=f) are used to compute the amplitude and frequency of component i (i = 1..n) as follows:

ai = a . dai-1

fi = df + f.(i-1)

SEGMENT ; aset ; aseg ; ach ; a

Adds the signal of segment aseg and channel ach of audio set aset to the sequence. If ach is set to 0 or * all channels are added to the sequence (1 -> ch, 2 -> ch+1, ...). The value a is used as amplification factor.

Result:

0 for success and a non-zero value if failed

Test

Test the sequence definition. Returns 0 if the definitions are valid and the sequence wave item can be created. For a description of the channel index arguments see function CreateWave.

Usage:

inst Test [ sch ]

Parameters:

sch

The sequence channel list (see CreateWave).

Result:

0 for success and a non-zero value if failed.

Examples

//{{3.8 3219}{2007.08.14  15.05.47} - automatically created version information - do not change or delete this line}
///////////////////////////////////////////////////////////////////////////////
//
//  Macro:          bseq_examples
//  Description:    Playback a sine tone at 1000Hz using the BSeq class.
//  Parameters:     none
//  Return:         0 on success
//  Author:         Jonnie White
//  History:        2007-08-14  created
//  File:           bseq_examples.sts
//
///////////////////////////////////////////////////////////////////////////////
[Macro bseq_example]

// create a BSeq instance
#bseq := BSeq
if '$#bseq[?]' != 'instance' em -1 ; $#mac::Error - failed to create a BSeq instance
// define a 100s sine tone at 1000Hz
$#bseq Signal * ; begin ; 0 ; tone ; 100 ; 1 ; 1000 ; 0
if '$result' != 0 em $result ; $#mac::Error - sequence Signal call failed
// play the tone using the playback dialog
$#bseq play 1
if '$result' != 0 em $result ; $#mac::Error - playback failed
// destroy the instance
$#bseq destroy

exit 1 int 0