Programmer Guide/Macro Library/BSeq

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

Parent class: CObj

See also: Sequences

The class BSeq can create and play sequences and provides an interface to the sequence wave-item functions.

Create BSeq Instance

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. In the descriptions of the member functions the first argument bseq_instance is an instance of the class BSeq created by this function.

Configuration and Dialogs

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

Dialog for Attributes

Usage

bseq_instance dialogsetup

Result

returns 0 if the dialog was closed with the Ok button, and 1 if the Cancel button was pressed

Description

Shows a dialog where all attributes of the sequence instance can be changed. If the dialog is closed with Ok, the changes are saved.

Define Sequence Signals

Add Signal

Usage

bseq_instance signal ch ; base ; time ; sigtype ; sigpars

ch

sequence channel number (1, 2, ..), 0 or * for all channels

base

defines the base (origin) for the signal begin time; possible values are absolut, begin and end

time

the offset time to the selected base (origin) in seconds

sigtype ; sigpars

set the type and parameters of the new signal (see below)

Result

0 for success and a non-zero value if failed

Description

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 it is set to absolute, time is an absolute time (0 = begin 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.

sigtype	sigpars	signal
pause	d	A zero signal (pause) 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).
rectangle	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 (= 1..n): 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.

Notes

• Gaps are filled with zero (pause). This means, all regions of a sequence, where no signal is assigned are implicit set to pause.
• Signals which are overlapping in time are mixed (added).
• The member functions envelope, filter, fmod and amod can be used to apply special processing to a defined signal.

Dialog to Add / Edit Signals

Usage

bseq_instance dialogedit pos

pos

the index of the signal; * for the last defined signal

Result

none (void)

Description

A dialog is displayed, where new signals can be difined and existing signals can be modified or deleted. In the dialog also the envelope, filter and modulation functions for a signal can be configured.

Delete Signal

Usage

bseq_instance delete pos

pos

the index of the signal; * for the last defined signal

Result

always 0

Description

Delete the specified signal defintion from the sequence.

Assign Envelope

Usage

bseq_instance envelope pos ; type ; t1 a1 t2 a2 ...

pos

the signal index; * for last defined signal

type

the type of envelope. The types none (no envelope), linear and cosine are supported

tX aX

the envelope points; each point is defined by a time tX (in seconds) and an amplitude factor aX.

Result

0 for success and a non-zero value if failed

Description

Define 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 &lt 0). If no point at the begin/end of the signal is defined a begin/end point with amplitude 0 is automatically added (→ the signal starts/ends with zero amplitude).
If the argument type is set to none the envelope function for the signal pos is cleared.

Assign Filter

Usage

bseq_instance filter pos ; type ; f1 ; f2 ; inv ; order ; damp ; ripple

pos

the signal index; * for last defined signal

type

the type of filter. The filter types none (no filter), elliptic, butterworth and chebychev are supported

f1, f2: the frequency band in Hz

inv

if set to yes (or 1) the frequency response is inverted, otherwise (no or 0) not.

order

the filter order; this must be must an integer greater than 1 (default=5)

damp

the stopband damping in dB; damp ≥ 10 (default=60)

ripple

the passband ripple in dB; 0 < ripple ≤ 10 (default=1)

Result

0 for success and a non-zero value if failed

Description

Define 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 passband/stopband of the filter (see below). The parameters order, damp and ripple define the damping, the passband linearity and the slopes.).
If the argument type is set to none the filter for the signal pos is cleared.

Filter types (with: fmax = half sampling rate):

• f1 = 0, f2 > 0, inv = 0 → lowpass
• f1 > 0, f2 = fmax, inv = 0 → highpass
• 0 < f1 < f2 < fmax, inv = 0 → bandpass
• 0 < f1 < f2 < fmax, inv = 1 → bandstop (notch)

Assign Frq-Modulation

Usage

bseq_instance fmod pos ; none

bseq_instance fmod pos ; sine ; rate ; bw ; p

bseq_instance fmod pos ; rectangle | triangle ; rate ; bw ; dc

bseq_instance fmod pos ; sweep ; w ; k

pos

the signal index; * for last defined signal

rate, bw: modulation rate and bandwidth in Hz

p: starting phase of sine modulation in rad (default=0)

dc: duty cycle factor rectangle and triangle modulation (0 < dc < 1, default=0.5)

w, k: width (w, in Hz) and exponent (k, ≥ 0) for sweep function

Result

0 for success and a non-zero value if failed

Description

Define a frequency modulation or a sweep function for the signal pos. Modulating frequency makes only sense for periodic signal generators (e.g. rectangle, triangle or tone).
If the keyword none is used, the frq-modulation for the signal pos is cleared.

Computation of frequency modulation:

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

• f: the frequency assigned to the signal generator (carrier)
• bw: the modulation bandwidth in Hz (> 0)
• m(t): the modulation function (depends on selected function type, rate and p | dc)
• f(t): modulated frequency at time t

Computation of sweep function:

linear sweep if k = 0: f(t) = f + w . t / d

exponential sweep if k > 0: f(t) = f + w . (t / d)^k

• f: the frequency assigned to the signal generator (carrier)
• d: the duration assigned to the signal generator
• w: the sweep width (in Hz, ≠ 0)
• k: the sweep exponent (≥ 0)
• f(t): sweep frequency at time t

Assign Amp-Modulation

Usage

bseq_instance amod pos ; none

bseq_instance amod pos ; sine ; rate ; k ; p

bseq_instance amod pos ; rectangle | triangle ; rate ; k ; dc

pos

the signal index; * for last defined signal

rate: modulation rate in Hz

k: modulation factor (0 ≤ k ≤ 1)

p: starting phase of sine modulation in rad (default=0)

dc: duty cycle factor rectangle and triangle modulation (0 < dc < 1, default=0.5)

Result

0 for success and a non-zero value if failed

Description

Define a amplitude modulation for the signal pos. Amplitude modulating can be applied to any kind of signal.
If the keyword none is used, the amp-modulation for the signal pos is cleared.

Computation of amplitude modulation:

x_AM(t) = x(t) . ((1 – k/2) + m(t) . k/2)

• x(t): the signal
• x_AM(t): the modulated signal
• k: modulation factor (0 ≤ k ≤ 1)
• m(t): the modulation function (depends on selected function type, rate and p | dc)

Using the Sequence

Create Wave Item

Usage

bseq_instance createwave [ sch ; multi ]

sch

the sequence channel list (blank separated list of channel indices)

multi

set this option to 1 (or yes) if the sequence should be created for random signal access

Result

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

Description

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 sch is specified only the requested channels are used, otherwise all channels are used. Normally the sequence wave item is create for sequential signal access. If a random signal access is necessary, the argument multi must be set to 1 or yes.

Notes:

• If the definition contains signals of type segment, the sound files are opened automatically before the wave item is created.
• If the global envelope is enabled (see [#Set_Attributes|set envelope=...), the envelopes of individual signal definitions are ignored
• The returned wave item must be deleted with the member function deletewave and not with the normal delete command.
• The wave item is also stored in the member variable &wave.
• This function is called by the members test, #play and copy. Don't call one of these members, while working with the returned wave item.

Delete Wave Item

Usage

bseq_instance deletewave

Result

always 0

Description

This function deletes the internal sequence wave item, which was created by the last call to member createwave. It also closes all sound files which were opened during the creation of the wave item. After the execution of this function the wave item returned by createwave is invalid and can not be used for further actions.

Notes:

• This function is called by the members test, #play and copy. Don't call one of these members, while working with the sequence wave item.

Test Definition

Usage

bseq_instance test [ sch ]

sch

the sequence channel list → see createwave for details

Result

0 for success and 1 for error

Description

Test if all configuration values and signal definitions are valid and the sequence wave item can be created.

Play Signal

Usage

bseq_instance play [ dlg ; sch ]

dlg

set this option to 1 (or yes) if a play dialog should be displayed and to 0 (or no) if not

sch

the sequence channel list → see createwave for details

Result

0 for success and 1 for error

Description

Playback of the sequence signal. For the playback a temporary instance of the class playwave is used.

Copy Signal

Usage

bseq_instance copy mode ; sch ; taset ; taseg ; tach ; tmode ; tname

mode

this parameter is currently not used, but is reserved for future expansions

sch

the sequence channel list → see createwave for details

taset

the target audio set (iref), should point to a sound file (AFile)

taseg

the target segment (iref, id or expression)

tach

the (1st) target channel

tmode

the target mode; the following values are supported:

• insert → insert into target
• replace → replace (overwrite) target
• mix → mix (add) sequence signal to target

tname

the name (segment id) for the copied signal

Result

0 for success and 1 for error

Description

Copies the sequence signal to the specified target. The target audio set should be a sound file.

Note: This function uses the undocumented class BSignal to perform the copy process. This class implements also the standard signal processing tools which are available in the GUI of the STx main application.

Project Document Functions

In the STx project document sequences are elements of type ASequence (sub-type of ASet). ASequence elements have the standard attributes SR (sampling rate), CH (number of channels) and ID (unique set id) and contain the signal definitions (child element ASequenceSignals, once, see save / load) and the segment definitions (ASeg child elements, one / segment, createsegments). The member functions do not attach (lock) and detach the project document, this must be done by the caller.

Create Segments

Usage

bseq_instance createsegments ref

ref

a reference (iref) to a sequence element in the project document

Result

the number of created segments

Description

The functions creates an audio segment (ASeg element) for each defined signal. Also a segment named Signal.All for the whole sequence signal is created. The segment names are chosen automatically.

Save & Load

Usage

bseq_instance save ; ref

bseq_instance load ; ref

ref

a reference (iref) to a sequence element in the project document

Result

0 for success and a non-zero value if failed

Description

Loads/saves the signal definitions from/to the specified element of the current project. The following data of a sequence are saved/loaded:

• sampling rate (attribute SR=srate) and number of channels (attribute CH=channels) as attributes of the element ref
• all signal defintions including envelope, filter and modulation defintions as content (data) of the child element ASequenceSignals of the element ref

Example

The example script bseq_example.sts is part of the installed example script package (directory: stx-root\scripts\examples

// play a 1000Hz sine tone using the BSeq class

[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