Programmer Guide/Macro Library/BSeq: Difference between revisions
From STX Wiki
Jump to navigationJump to search
No edit summary |
No edit summary |
||
| Line 76: | Line 76: | ||
* Gaps are filled with zero (pause). This means, all regions of a sequence, where no signal is assigned are implicit set to pause. | * 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). | * Signals which are overlapping in time are mixed (added). | ||
* The member functions [[ | * 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. | ||
===Delete Signal=== | ===Delete Signal=== | ||
| Line 100: | Line 100: | ||
:;<var>order</var>: the filter order; this must be must an integer greater than '''1''' (default=5) | :;<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> ≥ 10 (default=60) | :;<var>damp</var>: the stopband damping in dB; <var>damp</var> ≥ 10 (default=60) | ||
;<var>ripple</var>: the passband ripple in dB; 0 < <var>ripple</var> ≤ 10 (default=1) | :;<var>ripple</var>: the passband ripple in dB; 0 < <var>ripple</var> ≤ 10 (default=1) | ||
;Result: '''0''' for success and a non-zero value if failed | ;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. | ;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. | ||
Filter types (with: ''fmax'' = half sampling rate): | :Filter types (with: ''fmax'' = half sampling rate): | ||
:* <var>f1</var> = 0, <var>f2</var> > 0, <var>inv</var> = 0 → lowpass | ::* <var>f1</var> = 0, <var>f2</var> > 0, <var>inv</var> = 0 → lowpass | ||
:* <var>f1</var> > 0, <var>f2</var> = ''fmax'', <var>inv</var> = 0 → highpass | ::* <var>f1</var> > 0, <var>f2</var> = ''fmax'', <var>inv</var> = 0 → highpass | ||
:* 0 < <var>f1</var> < <var>f2</var> < ''fmax'', <var>inv</var> = 0 → bandpass | ::* 0 < <var>f1</var> < <var>f2</var> < ''fmax'', <var>inv</var> = 0 → bandpass | ||
:* 0 < <var>f1</var> < <var>f2</var> < ''fmax'', <var>inv</var> = 1 → bandstop (notch) | ::* 0 < <var>f1</var> < <var>f2</var> < ''fmax'', <var>inv</var> = 1 → bandstop (notch) | ||
===Assign Frq-Modulation=== | ===Assign Frq-Modulation=== | ||
| Line 135: | Line 135: | ||
::* ''f'': the frequency assigned to the signal generator (carrier) | ::* ''f'': the frequency assigned to the signal generator (carrier) | ||
::* ''d'': the duration assigned to the signal generator | ::* ''d'': the duration assigned to the signal generator | ||
::* <var>w</ | ::* <var>w</var>: the sweep width (in Hz, ≠ 0) | ||
::* <var>k</ | ::* <var>k</var>: the sweep exponent (≥ 0) | ||
::* f(t): sweep frequency at time t | ::* f(t): sweep frequency at time t | ||
===Assign Amp-Modulation=== | ===Assign Amp-Modulation=== | ||
Revision as of 12:46, 6 March 2018
- 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.
Contents
Create an 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. In the descriptions of the member functions the first argument bseq_instance is an instance of the class BSeq created by this function.
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 channelsenvelope→ get global envelope definition (type,ton,toff)factor→ get global amplitude factorsrate→ get sampling ratesignals→ get number of signal definitionstable→ get signal definition table
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.
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 <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 ; nonebseq_instance fmod pos ; sine ; rate ; bw ; pbseq_instance fmod pos ; rectangle | triangle ; rate ; bw ; dcbseq_instance fmod pos ; sweep ; w ; k
- 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
- f(t) = f + bw/2 . m(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
