Programmer Guide/Macro Library/BSeq: Difference between revisions

From STX Wiki
Jump to navigationJump to search
No edit summary
 
(20 intermediate revisions by the same user not shown)
Line 1: Line 1:
{{DISPLAYTITLE:{{SUBPAGENAME}} - Signal Sequence}}
{{DISPLAYTITLE:{{SUBPAGENAME}} - Signal Sequence}}
:'''File''': BSeq.STX, linked to library STX.LIB
:'''File''': BSeq.STX, linked to library STX.LIB
:'''Parent class''': [[Programmer Guide/Macro Library/COBJ|CObj]]
:'''See also''': [[Programmer_Guide/Shell_Items/Wave/SET_WAVE#Sequences|Sequences]]
:'''See also''': [[Programmer_Guide/Shell_Items/Wave/SET_WAVE#Sequences|Sequences]]


The class <code>BSeq</code> can create and play sequences and provides an interface to the [[Programmer_Guide/Shell_Items/Wave/SET_WAVE#sequence wave-item]] functions.  
The class <code>BSeq</code> can create and play sequences and provides an interface to the [[Programmer_Guide/Shell_Items/Wave/SET_WAVE#Sequences|sequence wave-item]] functions.  


==Create a new Instance of BSeq==
==Create BSeq Instance==
;Usage:  
;Usage:  
:<code>bseq [ <var>attr</var>=<var>value</var> ; ... ]</code>
:<code>bseq [ <var>attr</var>=<var>value</var> ; ... ]</code>
:<code>cobj new bseq [ <var>attr</var>=<var>value</var> ; ... ]</code>
:<code>cobj new bseq [ <var>attr</var>=<var>value</var> ; ... ]</code>
:;<var>attr</var>=<var>value</var>, ...: initial values for sequence attributes (see member function [[/Set_Attributes|Set]])
:;<var>attr</var>=<var>value</var>, ...: initial values for sequence attributes (see member function [[#Set_Attributes|Set]])
;Result: An instance of BSeq or an empty string
;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_Attributes|Set]] is called.
;Description: Create and initialize a sequence instance and assign sequence attributes. To assign the attribute(s) the member function [[#Set_Attributes|Set]] is called. In the descriptions of the member functions the first argument <var>bseq_instance</var> is an instance of the class BSeq created by this function.


==Set Attributes==
==Configuration and Dialogs==
 
===Set Attributes===


;Usage: <code><var>bseq_instance</var> set <var>attr</var>=<var>val</var> [ ; ... ]</code>
;Usage: <code><var>bseq_instance</var> set <var>attr</var>=<var>val</var> [ ; ... ]</code>
Line 19: Line 22:
;Result: always '''0'''
;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.  
;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:
 
Supported attributes:
:* <code>channel=</code><var>n</var> &rarr; set the number of channels (1 &le; <var>n</var> &le; 256)
:* <code>channel=</code><var>n</var> &rarr; set the number of channels (1 &le; <var>n</var> &le; 256)
:* <code>envelope=<var>type,ton,toff</var></code> &rarr; set global envelope type ('''none''', '''linear''' or '''cosine''') and the on/off time (in ms, &ge; 0).
:* <code>envelope=<var>type,ton,toff</var></code> &rarr; set global envelope type ('''none''', '''linear''' or '''cosine''') and the on/off time (in ms, &ge; 0).
Line 27: Line 28:
:* <code>srate=<var>frq</var></code> &rarr; set sampling rate in Hz (&gt; 0).
:* <code>srate=<var>frq</var></code> &rarr; set sampling rate in Hz (&gt; 0).


==Get Attribute==
===Get Attribute===
;Usage: <code><var>bseq_instance</var> get <var>attr</var></code>
;Usage: <code><var>bseq_instance</var> get <var>attr</var></code>
:;<var>attr</var>: name of the attribute to retrieve (see description below)
:;<var>attr</var>: name of the attribute to retrieve (see description below)
;Result: value of specified attribute or an empty string
;Result: value of specified attribute or an empty string
;Description: Retrieve a sequence attribute.
;Description: Retrieve a sequence attribute.
 
;Supported attributes:
 
Supported attributes:
:* <code>channel</code> &rarr; get number of channels
:* <code>channel</code> &rarr; get number of channels
:* <code>envelope</code> &rarr; get global envelope definition (<var>type,ton,toff</var>)
:* <code>envelope</code> &rarr; get global envelope definition (<var>type,ton,toff</var>)
Line 42: Line 41:
:* <code>table</code> &rarr; get signal definition table
:* <code>table</code> &rarr; get signal definition table


===Dialog for Attributes===
;Usage: <code><var>bseq_instance</var> dialogsetup</code>
;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: <code><var>bseq_instance</var> signal <var>ch ; base ; time ; sigtype ; sigpars</var></code>
:;<var>ch</var>: sequence channel number (1, 2, ..), '''0''' or '''*''' for all channels
:;<var>base</var>: defines the base (origin) for the signal begin time; possible values are '''absolut''', '''begin''' and '''end'''
:;<var>time</var>: the offset time to the selected base (origin) in seconds
:;<var>sigtype ; sigpars</var>: 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 <var>ch</var> 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 <var>base</var> selects how the time value <var>time</var> is used. If it is set to '''absolute''', <var>time</var> is an absolute time (0 = begin of the signal). If <var>base</var> is set to '''begin''' or '''end''', <var>time</var> is an offset to the beginning or end of the previous signal. The signal itself is defined by <var>sigtype</var> and <var>sigpars</var>.


;<var>value</var>
{|class="einrahmen"
 
! <var>sigtype</var> !! <var>sigpars</var> !! signal
:The value to set the attribute to. See <var>attr</var> for details.
 
=====Result:=====
 
An empty string.
 
 
 
 
 
 
====BSeq Member Functions====
 
The <code>BSeq</code> 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)
| '''pause''' || <var>d</var>
|modulated sequence signal
| A zero signal (pause) with a duration of <var>d</var> seconds.
|-
|-
|x(t)
| '''value''' || <var>d ; v</var>
|sequence signal
| A constant signal (dc) with a duration of <var>d</var> seconds and an amplitude <var>v</var>.
|-
|-
|m(t)
| '''noise''' || <var>d ; a</var>
|modulation function, depends on type, rate and dc or phase
| A linear distributed noise with a duration of <var>d</var> seconds and an amplitude <var>a</var>.
|-
|-
|fac
| '''rectangle''' || <var>d ; a ; f ; q</var>  
|modulation factor (0 <= fac <= 1)
| A rectangle function with a duration of <var>d</var> seconds, an amplitude <var>a</var>, a frequency <var>f</var> Hz and a duty cycle <var>q</var> (0 &lt; <var>q</var> &lt; 1).
|}
 
=====Usage:=====
 
<code>inst AMod <var>pos</var> ; <var>type</var> ; <var>rate</var> ; <var>factor</var> ; <var>dc</var>|<var>phase</var></code>
 
=====Parameters:=====
 
;<var>pos</var>
 
:The signal index (* for the last defined signal).
 
;<var>type</var>
 
:The type of modulation function. The following types are supported:
 
:<code>none</code>|<code>rectangular</code>|<code>triangle</code>|<code>sine</code>
 
;<var>rate</var>
 
:The modulation rate in Hz.
 
;<var>factor</var>
 
:The modulation factor.
 
;<var>dc</var>
 
:The duty cycle (if the <var>type</var> is <code>rectangular</code> or <code>triangle</code>).
 
;<var>phase</var>
 
:The starting phase (if the <var>type</var> is <code>sine</code>).
 
=====Result:=====
 
<code>0</code> for success and a non-zero value if failed
 
=====Parameters:=====
 
;<var>attr</var>
 
:The name of the sequence attribute.
 
;<var>value</var>
 
:The value of the sequence attribute.
 
=====Result:=====
 
0 for success and 1 for error
 
Note that you can create an instance of the <code>BSeq</code> class with the following syntax:
 
<code>#inst := BSeq</code>
 
===Copy===
 
Copies the sequence signal to the specified target. To perform the copy function the class [[Programmer Guide/Class Library/BSignal|BSIGNAL]] is used.
 
=====Usage:=====
 
<code><var>inst</var> Copy <var>mode</var> ; <var>sch</var> ; <var>tset</var> ; <var>tseg</var> ; <var>tch</var> ; <var>tmode</var> ; <var>tname</var></code>
 
=====Parameters:=====
 
;<var>mode</var>
 
:This parameter is currently not used, but is reserved for future expansions.
 
;<var>sch</var>
 
:The sequence channel list (see <code>CreateWave</code>).
 
;<var>tset</var>
 
:The target audio set.
 
;<var>tseg</var>
 
:The target segment reference, id or expression.
 
;<var>tch</var>
 
:The target channel.
 
;<var>tmode</var>
 
:The target mode. The following values are supported:
 
:<code>insert</code>|<code>replace</code>|<code>mix</code>
 
;<var>tname</var>
 
:The name for the copied signal.
 
=====Result:=====
 
<code>0</code> for success and a non-zero value if failed.
 
===CreateSegments===
 
Creates audio segments (<code>ASeg</code> elements) for all defined signals and stores them in the specified DataSet element. Also a segment named <code>Signal.All</code> for the whole sequence signal is created. The segment names are chosen automatically.
 
=====Usage:=====
 
<code><var>inst</var> CreateSegments <var>ref</var></code>
 
=====Parameters:=====
 
;<var>ref</var>
 
:The reference to a DataSet element of type <code>ASequence</code>.
 
=====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 <code>DeleteWave</code> and not with the command '<code>delete waveitem</code>'!
 
=====Usage:=====
 
<code><var>inst</var> CreateWave [ <var>sch</var> ]</code>
 
=====Parameters:=====
 
;<var>sch</var>
 
: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:=====
 
<code><var>inst</var> Delete <var>pos</var></code>
 
=====Parameters:=====
 
;<var>pos</var>
 
:The signal index (<code>*</code> for the last defined signal).
 
=====Result:=====
 
Always <code>0</code>.
 
===DeleteWave===
 
Deletes the sequence wave item created with <code>CreateWave</code> and closes all sound files opened during creation.
 
=====Result:=====
 
Always <code>0</code>.
 
===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:=====
 
<code>0</code> for OK and <code>1</code> for cancel.
 
===Envelope===
 
Define/undefine an envelope function for the signal <var>pos</var>. An envelope is defined by the function <var>type</var> and a set of points, each one defined with a time and an amplitude value (<var>tX</var> and <var>aX</var>). The time values can be specified as an offset from the beginning (<var>tX</var> > <code>0</code>) or from the end (<var>tX</var> < <code>0</code>). If an amplitude is defined, the signal starts and ends with a zero amplitude.
 
=====Usage:=====
 
<code><var>inst</var> Envelope <var>pos</var> ; <var>type</var> ; <var>t1</var> <var>a1</var> <var>t2</var> <var>a2</var> ...</code>
 
=====Parameters:=====
 
;<var>pos</var>
 
:The signal index (<code>*</code> for last defined signal).
 
;<var>type</var>
 
:The type of envelope. The following values are supported:
 
:<code>none</code>|<code>linear</code>|<code>cosine</code>
 
;<var>tX,aX</var>
 
:The envelope points (<var>tX</var> = time in seconds, <var>aX</var> = linear amplitude).
 
=====result:=====
 
0 for success and a non-zero value if failed
 
===Filter===
 
Define or undefine a filter for the signal <var>pos</var>. The filter applied to the signal is an IIR filter of the specified type. The arguments <var>f1</var>, <var>f2</var> and <var>inv</var> 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 <var>order</var>, <var>damp</var> and <var>ripple</var> are used for the coefficient computation.
 
=====Usage:=====
 
<code><var>inst</var> Filter <var>pos</var> ; <var>type</var> ; <var>f1</var> ; <var>f2</var> ; <var>inv</var> ; <var>order</var> ; <var>damp</var> ; <var>ripple</var></code>
 
=====Parameters:=====
 
;<var>pos</var>
 
:The signal index (<code>*</code> for the last defined signal).
 
;<var>type</var>
 
:The type of filter. The following values are supported:
 
:<code>none</code>|<code>elliptic</code>|<code>butterworth</code>|<code>chebychev</code>
 
;<var>f1,f2</var>
 
:The frequency band.
 
;<var>inv</var>
 
:Invert - <code>yes</code>|<code>no</code>, <code>0</code>|<code>1</code>
 
;<var>order</var>
 
:The filter order must be an integer greater than <code>1</code>. The default is <code>5</code>.
 
;<var>damp</var>
 
:The stopband damping in dB must be a number less than <code>-9</code> or greater than <code>9</code>. The default is <code>60</code>.
 
;<var>ripple</var>
 
:The passband ripple in dB must be a number between <code>-10</code> and <code>10</code>. The default is <code>1</code>.
 
=====Result:=====
 
<code>0</code> for success and a non-zero value if failed.
 
===FMod===
 
Define or undefine a frequency modulation function for the signal <var>pos</var>. 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)
| '''rectangle''' || <var>d ; a ; f ; q</var>
|modulation function, depends on type, rate and dc or phase
| A triangle function with a duration of <var>d</var> seconds, an amplitude <var>a</var>, a frequency <var>f</var> Hz and a duty cycle <var>q</var> (0 &lt; <var>q</var> &lt; 1).
|-
|-
|bw
| '''tone''' || <var>d ; a ; f ; p ; n ; da ; df</var> || A sine wave or a harmonic tone with a duration of <var>d</var> seconds, an amplitude <var>a</var>, a frequency <var>f</var> Hz and a phase <var>p</var> rad. If the number of harmonics <var>n</var> is greater than one, the values <var>da</var> (def.=1) and <var>df</var> (def.=<var>f</var>) are used to compute the amplitude and frequency of component ''i'' (= 1..<var>n</var>):<br/>a''i'' = <var>a</var> . <var>da</var><sup>''i-1''</sup>;  f''i'' = <var>df</var> + <var>f</var> . (''i''-1)
|modulation bandwidth in Hz (>0)
|-
| '''segment''' || <var>aset ; aseg ; ach ; a</var>
| Adds the signal of segment <var>aseg</var> and channel <var>ach</var> of audio set <var>aset</var> to the sequence. If <var>ach</var> is set to <code>0</code> or <code>*</code> all channels are added to the sequence (1 -> <var>ch</var>, 2 -> <var>ch</var>+1, ...). The value <var>a</var> is used as amplification factor.
|}
|}


=====Usage:=====
;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 [[#Assign_Envelope|envelope]], [[#Assign_Envelope|filter]], [[#Assign_Frq-Modulation|fmod]] and [[#Assign_Amp-Modulation|amod]] can be used to apply special processing to a defined signal.


<code>inst FMod <var>pos</var> ; <var>type</var> ; <var>rate</var> ; <var>bw</var> ; <var>dc</var> ; <var>phase</var></code>
===Dialog to Add / Edit Signals===
;Usage:<code><var>bseq_instance</var> dialogedit <var>pos</var></code>
:;<var>pos</var>: 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.


=====Parameters:=====
===Delete Signal===
;Usage:<code><var>bseq_instance</var> delete <var>pos</var></code>
:;<var>pos</var>: the index of the signal; '''*''' for the last defined signal
;Result: always '''0'''
;Description: Delete the specified signal defintion from the sequence.


;<var>pos</var>
===Assign Envelope===
;Usage:<code><var>bseq_instance</var> envelope <var>pos ; type ; t1 a1 t2 a2 ...</var></code>
:;<var>pos</var>: the signal index; '''*''' for last defined signal
:;<var>type</var>: the type of envelope. The types '''none''' (no envelope), '''linear''' and '''cosine''' are supported
:;<var>tX aX</var>: the envelope points; each point is defined by a time <var>tX</var> (in seconds) and an amplitude factor <var>aX</var>.
;Result: '''0''' for success and a non-zero value if failed
;Description: Define an envelope function for the signal <var>pos</var>. An envelope is defined by the function <var>type</var> and a set of points, each one defined with a time and an amplitude value (<var>tX</var> and <var>aX</var>). The time values can be specified as an offset from the beginning (<var>tX</var> &gt; <code>0</code>) or from the end (<var>tX</var> &lt <code>0</code>). If no point at the begin/end of the signal is defined a begin/end  point with amplitude '''0''' is automatically added (&rarr; the signal starts/ends with zero amplitude).<br/>If the argument <var>type</var> is set to '''none''' the envelope function for the signal <var>pos</var> is cleared.


:The signal index (<code>*</code> for the last defined signal).
===Assign Filter===
;Usage: <code><var>bseq_instance</var> filter <var>pos ; type ; f1 ; f2 ; inv ; order ; damp ; ripple</var></code>
:;<var>pos</var>: the signal index; '''*''' for last defined signal
:;<var>type</var>: the type of filter. The filter types '''none''' (no filter), '''elliptic''', '''butterworth''' and '''chebychev''' are supported
:;<var>f1, f2: the frequency band in Hz
:;<var>inv</var>: if set to '''yes''' (or '''1''') the frequency response is inverted, otherwise ('''no''' or '''0''') not.
:;<var>order</var>: the filter order; this must be must an integer greater than '''1''' (default=5)
:;<var>damp</var>: the stopband damping in dB; <var>damp</var> &ge; 10 (default=60)
:;<var>ripple</var>: the passband ripple in dB; 0 &lt; <var>ripple</var> &le; 10 (default=1)
;Result: '''0''' for success and a non-zero value if failed
;Description: Define a filter for the signal <var>pos</var>. The filter applied to the signal is an IIR filter of the specified type. The arguments <var>f1</var>, <var>f2</var> and <var>inv</var> define the passband/stopband of the filter (see below). The parameters <var>order</var>, <var>damp</var> and <var>ripple</var> define the damping, the passband linearity and the slopes.).<br/>If the argument <var>type</var> is set to '''none''' the filter for the signal <var>pos</var> is cleared.


;<var>type</var>
:Filter types (with: ''fmax'' = half sampling rate):
::* <var>f1</var> = 0, <var>f2</var> > 0, <var>inv</var> = 0 &rarr; lowpass
::* <var>f1</var> > 0, <var>f2</var> = ''fmax'', <var>inv</var> = 0 &rarr; highpass
::* 0 < <var>f1</var> < <var>f2</var> < ''fmax'', <var>inv</var> = 0 &rarr; bandpass
::* 0 < <var>f1</var> < <var>f2</var> < ''fmax'', <var>inv</var> = 1 &rarr; bandstop (notch)


:The type of modulation function. The following values are supported:
===Assign Frq-Modulation===
;Usage:  
:<code><var>bseq_instance</var> fmod <var>pos</var> ; none</code>
:<code><var>bseq_instance</var> fmod <var>pos</var> ; sine ; <var>rate ; bw ; p</var></code>
:<code><var>bseq_instance</var> fmod <var>pos</var> ; rectangle | triangle ; <var>rate ; bw ; dc</var></code>
:<code><var>bseq_instance</var> fmod <var>pos</var> ; sweep ; <var>w ; k</var></code>
:;<var>pos</var>: the signal index; '''*''' for last defined signal
;:<var>rate, bw</var>: modulation rate and bandwidth in Hz
;:<var>p</var>: starting phase of '''sine''' modulation in rad (default=0)
;:<var>dc</var>: duty cycle factor '''rectangle''' and '''triangle''' modulation (0 < <var>dc</var> < 1, default=0.5)
;:<var>w, k</var>: width (<var>w</var>, in Hz) and exponent (<var>k</var>, &ge; 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 <var>pos</var>. Modulating frequency makes only sense for periodic signal generators (e.g. rectangle, triangle or tone).<br/>If the keyword '''none''' is used, the frq-modulation for the signal <var>pos</var> is cleared.


:<code>none</code>|<code>rectangle</code>|<code>triangle</code>|<code>sine</code>
:Computation of frequency modulation:
::f(t) = ''f'' + <var>bw</var>/2 . m(t)
::* ''f'': the frequency assigned to the signal generator (carrier)
::* <var>bw</var>: the modulation bandwidth in Hz (> 0)
::* m(t): the modulation function (depends on selected function type, <var>rate</var> and <var>p | dc</var>)
::* f(t): modulated frequency at time t


;<var>rate</var>
:Computation of sweep function:
::linear sweep if <var>k</var> = 0: f(t) = ''f'' + <var>w</var> . t / ''d''
::exponential sweep if <var>k</var> > 0: f(t) = f + <var>w</var> . (t / ''d'')<sup><var>k</var></sup>
::* ''f'': the frequency assigned to the signal generator (carrier)
::* ''d'': the duration assigned to the signal generator
::* <var>w</var>: the sweep width (in Hz, &ne; 0)
::* <var>k</var>: the sweep exponent (&ge; 0)
::* f(t): sweep frequency at time t


:The modulation rate in Hz.
===Assign Amp-Modulation===
;Usage:
:<code><var>bseq_instance</var> amod <var>pos</var> ; none</code>
:<code><var>bseq_instance</var> amod <var>pos</var> ; sine ; <var>rate ; k ; p</var></code>
:<code><var>bseq_instance</var> amod <var>pos</var> ; rectangle | triangle ; <var>rate ; k ; dc</var></code>
:;<var>pos</var>: the signal index; '''*''' for last defined signal
;:<var>rate</var>: modulation rate in Hz
;:<var>k</var>: modulation factor (0 &le; <var>k</var> &le; 1)
;:<var>p</var>: starting phase of '''sine''' modulation in rad (default=0)
;:<var>dc</var>: duty cycle factor '''rectangle''' and '''triangle''' modulation (0 < <var>dc</var> < 1, default=0.5)
;Result: '''0''' for success and a non-zero value if failed
;Description: Define a amplitude modulation for the signal <var>pos</var>. Amplitude modulating can be applied to any kind of signal.<br/>If the keyword '''none''' is used, the amp-modulation for the signal <var>pos</var> is cleared.


;<var>bw</var>
:Computation of amplitude modulation:
::x<sub>AM</sub>(t) = x(t) . ((1 – <var>k</var>/2) + m(t) . <var>k</var>/2)
::* x(t): the signal
::* x<sub>AM</sub>(t): the modulated signal
::* <var>k</var>: modulation factor (0 &le; <var>k</var> &le; 1)
::* m(t): the modulation function (depends on selected function type, <var>rate</var> and <var>p | dc</var>)


:The modulation bandwidth in Hz.
==Using the Sequence==


;<var>dc</var>
===Create Wave Item===
;Usage: <code><var>bseq_instance</var> createwave [ <var>sch ; multi</var> ]</code>
:;<var>sch</var>: the sequence channel list (blank separated list of channel indices)
:;<var>multi</var>: 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 [[Programmer_Guide/Shell_Items/Wave/SET_WAVE#Sequences|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 <var>sch</var> 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 <var>multi</var> must be set to '''1''' or '''yes'''.


:The duty cycle (if <var>type</var> is <code>rectangle</code> or <code>triangle</code>).
: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 [[#Delete_Wave_Item|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 Definition|test]], [[#Play Signal|#play]] and [[#Copy Signal|copy]]. Don't call one of these members, while working with the returned wave item.


;<var>phase</var>
===Delete Wave Item===
 
;Usage: <code><var>bseq_instance</var> deletewave</code>
:The starting phase (if <var>type</var> is <code>sine</code>).
;Result: always '''0'''
 
;Description: This function deletes the internal sequence wave item, which was created by the last call to member [[#Create Wave Item|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 [[#Create Wave Item|createwave]] is invalid and can not be used for further actions.
=====Result:=====
 
0 for success and a non-zero value if failed
 
Define or undefine an frequency sweep function for the signal <var>pos</var>. 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:
:Notes:
:* This function is called by the members [[#Test Definition|test]], [[#Play Signal|#play]] and [[#Copy Signal|copy]]. Don't call one of these members, while working with the sequence wave item.


{|
===Test Definition===
|-
;Usage: <code><var>bseq_instance</var> test [ <var>sch</var> ]</code>
|fc
:;<var>sch</var>: the sequence channel list &rarr; see [[#Create_Wave_Item|createwave]] for details
|fundamental frequency of the generator (carrier)
;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. 
|f(t)
|modulated frequency
|-
|width
|sweep width in Hz (any number)
|-
|exp
|sweep function exponent
|-
|d
|signal duration
|}


=====Usage:=====
===Play Signal===
;Usage: <code><var>bseq_instance</var> play [ <var>dlg ; sch</var> ]</code>
:;<var>dlg</var>: set this option to '''1''' (or '''yes''') if a play dialog should be displayed and to '''0''' (or '''no''') if not
:;<var>sch</var>: the sequence channel list &rarr; see [[#Create_Wave_Item|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 [[Programmer_Guide/Macro_Library/PlayWave|playwave]] is used. 


<code>inst FMod <var>pos</var> ; SWEEP ; <var>width</var> ; <var>exp</var></code>
===Copy Signal===
;Usage: <code><var>bseq_instance</var> copy <var>mode ; sch ; taset ; taseg ; tach ; tmode</var> ; tname</var></code>
:;<var>mode</var>: this parameter is currently not used, but is reserved for future expansions
:;<var>sch</var>: the sequence channel list &rarr; see [[#Create_Wave_Item|createwave]] for details
:;<var>taset</var>: the target audio set (iref), should point to a sound file (AFile)
:;<var>taseg</var>: the target segment (iref, id or expression)
:;<var>tach</var>: the (1st) target channel
:;<var>tmode</var>: the target mode; the following values are supported:
::* '''insert''' &rarr; insert into target
::* '''replace''' &rarr; replace (overwrite) target
::* '''mix''' &rarr; mix (add) sequence signal to target
:;<var>tname</var>: 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.


=====Parameters:=====
: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.


;<var>pos</var>
==Project Document Functions==


:See above
In the [[Programmer_Guide/Macro_Library/BDataSet|{{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|save / load]]) and the segment definitions ('''ASeg''' child elements, one / segment, [[#Create Segments|createsegments]]). The member functions do not attach (lock) and detach the project document, this must be done by the caller.


;<var>width</var>
===Create Segments===
;Usage: <code><var>bseq_instance</var> createsegments <var>ref</var></code>
:;<var>ref</var>: 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.


:The sweep width in Hz (positive and negative values are allowed).
===Save & Load===
;Usage:  
:<code><var>bseq_instance</var> save ; <var>ref</var></code>
:<code><var>bseq_instance</var> load ; <var>ref</var></code>
:;<var>ref</var>: 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 <var>ref</var>
::* all signal defintions including envelope, filter and modulation defintions as content (data) of the child element '''ASequenceSignals''' of the element <var>ref</var>


;<var>exp</var>
==Example==
The example script '''bseq_example.sts''' is part of the installed example script package (directory: ''stx-root'''''\scripts\examples''').


:The sweep function exponent (>= 0).
<pre>
 
// play a 1000Hz sine tone using the BSeq class
=====Result:=====
 
<code>0</code> for success and a non-zero value if failed.
 
===Get===
 
Get an attribute value. Any valid <code>Set</code> attribute name can be used as the attribute name. In addition the keyword <code>SIGNALS</code> (gets the number of defined sequence signals) and the keyword <code>TABLE</code> (get signal definition table) can be used.
 
=====Usage:=====
 
<code><var>inst</var> Get <var>attr</var></code>
 
=====Parameters:=====
 
;<var>attr</var>
 
: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:=====
 
<code><var>inst</var> Load <var>ref</var></code>
 
=====Parameters:=====
 
;<var>ref</var>
 
:The reference to a DataSet element containing a sequence signal definition element with tag <code>ASequenceSignals</code>.
 
=====Result:=====
 
<code>0</code> for success and a non-zero value if failed.
 
===Play===
 
Plays the sequence. The class <code>PlayWave</code> is used for playback.
 
=====Usage:=====
 
<code><var>inst</var> Play <var>dialog</var> [; <var>sch</var> ]</code>
 
=====Parameters:=====
 
;<var>dialog</var>
 
:Display a play dialog or play without a dialog. The following values are supported:
 
:<code>0</code> - do not display a dialog
 
:<code>1</code> - display a dialog
 
;<var>sch</var>
 
: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 <code>ASequenceSignals</code> of the specified DataSet element.
 
=====Usage:=====
 
<code><var>inst</var> Save <var>ref</var></code>
 
=====Parameters:=====
 
;<var>ref</var>
 
:The reference to a DataSet element.
 
=====Result:=====
 
<code>0</code> for success and a non-zero value if failed.
 
 
===Signal===
 
Define a new sequence signal and add it to the sequence definition. If <var>ch</var> is set to <code>0</code> or <code>*</code> the new signal is added to each sequence channel, otherwise it is added only to the specified channel. The timebase <var>base</var> selects how the time value <var>time</var> is used. If <var>base</var> is set to <code>absolute</code>, <var>time</var> is an absolute value relative to the beginning of the signal. If base is set to <code>begin</code> or <code>end</code>, <var>time</var> is an offset to the beginning or end of the previous signal. The signal itself is defined by <var>sigtype</var> and <var>sigpars</var>.
 
=====Usage:=====
 
<code><var>inst</var> Signal <var>ch</var> ; <var>base</var> ; <var>time</var> ; <var>sigtype</var> ; <var>sigpars</var></code>
 
=====Parameters:=====
 
;<var>ch</var>
 
:The sequence channel (<code>0</code> or <code>*</code> for all channels).
 
;<var>base</var>
 
:The time base. The following values are supported:
 
:<code>absolute</code>
 
:<code>begin</code>
 
:<code>end</code>
 
;<var>time</var>
 
:time value in seconds
 
;<var>sigtype</var>
 
:The type of signal. The following values are supported:


:<code>PAUSE | VALUE | NOISE | RECTANGLE | TRIANGLE | TONE | SEGMENT</code>
;<var>sigpars</var>
:The parameters for the specified signal type.
:<code>PAUSE ;</code> <var>d</var>
:A zero signal with a duration of <var>d</var> seconds.
:<code>VALUE ;</code> <var>d</var> <code>;</code> <var>v</var>
:A constant signal (dc) with a duration of <var>d</var> seconds and an amplitude <var>v</var>.
:<code>NOISE ;</code> <var>d</var> <code>;</code> <var>a</var>
:A linear distributed noise with a duration of <var>d</var> seconds and an amplitude <var>a</var>.
:<code>RECTANGLE ;</code> <var>d</var> <code>;</code> <var>a</var> <code>;</code> <var>f</var> <code>;</code> <var>q</var>
:A rectangle function with a duration of <var>d</var> seconds, an amplitude <var>a</var>, a frequency <var>f</var> Hz and a duty cycle <var>q</var> (0 < <var>q</var> < 1).
:<code>TRIANGLE ;</code> <var>d</var> <code>;</code> <var>a</var> <code>;</code> <var>f</var> <code>;</code> <var>q</var>
:A triangle function with a duration of <var>d</var> seconds, an amplitude <var>a</var>, a frequency <var>f</var> Hz and a duty cycle <var>q</var> (0 < <var>q</var> < 1).
:<code>TONE ;</code> <var>d</var> <code>;</code> <var>a</var> <code>;</code> <var>f</var> <code>;</code> <var>p</var> <code>;</code> <var>n</var> <code>;</code> <var>da</var> <code>;</code> <var>df</var>
:A sine wave or a harmonic tone with a duration of <var>d</var> seconds, an amplitude <var>a</var>, a frequency <var>f</var> Hz and a phase <var>p</var> rad. If the number of harmonics <var>n</var> is greater than one, the values <var>da</var> (def.=1) and <var>df</var> (def.=f) are used to compute the amplitude and frequency of component <code>i</code> (<code>i</code> = 1..<var>n</var>) as follows:
:<code>ai =</code> <var>a</var> <code>.</code> <var>da</var><code>i-1</code>
:<code>fi =</code> <var>df</var> <code>+</code> <var>f</var><code>.(i-1)</code>
:<code>SEGMENT ;</code> <var>aset</var> <code>;</code> <var>aseg</var> <code>;</code> <var>ach</var> <code>;</code> <var>a</var>
:Adds the signal of segment <var>aseg</var> and channel <var>ach</var> of audio set <var>aset</var> to the sequence. If <var>ach</var> is set to <code>0</code> or <code>*</code> all channels are added to the sequence (1 -> ch, 2 -> ch+1, ...). The value <var>a</var> 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:=====
<code><var>inst</var> Test [ <var>sch</var> ]</code>
=====Parameters:=====
;<var>sch</var>
:The sequence channel list (see <code>CreateWave</code>).
=====Result:=====
<code>0</code> for success and a non-zero value if failed.
====Examples====
<pre>
//{{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]
[Macro bseq_example]


// create a BSeq instance
// create a BSeq instance
#bseq := BSeq
#bseq := BSeq srate=44100; channels=1; envelope=cos;250;250; factor=0.5
if '$#bseq[?]' != 'instance' em -1 ; $#mac::Error - failed to create a BSeq instance
if '$#bseq[?]' != 'instance' em -1 ; $#mac::Error - failed to create a BSeq instance
// define a 100s sine tone at 1000Hz
// define a 100s sine tone at 1000Hz

Latest revision as of 16:17, 6 March 2018

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:
xAM(t) = x(t) . ((1 – k/2) + m(t) . k/2)
  • x(t): the signal
  • xAM(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 srate=44100; channels=1; envelope=cos;250;250; factor=0.5
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
Retrieved from "https://mediawiki.kfs.oeaw.ac.at/stx/docs/wiki/index.php?title=Programmer_Guide/Macro_Library/BSeq&oldid=9858"

Navigation menu

Personal tools