Difference between revisions of "Programmer Guide/General Descriptions/Segment Expressions"

From STX Wiki
Jump to navigation Jump to search
m (Text replace - "S_TOOLS-STx" to "{{STX}}")
Line 1: Line 1:
 
{{DISPLAYTITLE:{{SUBPAGENAME}}}}
 
{{DISPLAYTITLE:{{SUBPAGENAME}}}}
==Segment Expressions==
 
 
 
{{STX}} uses a special syntax to address a segment of a sound file. The syntax allows for the mixed use of segment names and time values in a complex expression known as a "segment expression". Segment expressions can be used in all commands and dialogs where a signal segment (or position/duration) can be specified (exceptions are described in the Command Reference). In dialogs, the supported value formats/types are always described in the control/dialog caption.
 
{{STX}} uses a special syntax to address a segment of a sound file. The syntax allows for the mixed use of segment names and time values in a complex expression known as a "segment expression". Segment expressions can be used in all commands and dialogs where a signal segment (or position/duration) can be specified (exceptions are described in the Command Reference). In dialogs, the supported value formats/types are always described in the control/dialog caption.
  
Line 49: Line 47:
 
|labelexpression_<nowiki>-</nowiki>labelexpression
 
|labelexpression_<nowiki>-</nowiki>labelexpression
 
|(end and duration)
 
|(end and duration)
 +
|}
 +
 +
The segment expression <var>segexpr</var> specifies a label (position) in a signal or a segment (part) of a signal. The command evaluates the segment expression and returns the label position or the begin, end and length of the segment.
 +
:{|class="einrahmen"
 +
!<var>segexpr</var> !! description
 +
|-
 +
|<code>''bexpr''</code> || a position (label) at ''bexpr''
 +
|-
 +
|<code>''bexpr''_''eexpr</code> || a segment with begin ''bexpr'' and end ''expr''
 +
|-
 +
|<code>''bexpr''_+''lexpr''</code> || a segment with begin ''bexpr'' and length ''lexpr'' (end = ''bexpr''+''lexpr'')
 +
|-
 +
|<code>''eexpr''_-''lexpr''</code> || a segment with end ''eexpr'' and length ''lexpr'' (begin = ''eexpr''-''lexpr'')
 +
|}
 +
Each part (''bexpr'', ''eexpr'' and ''lexpr'') of the segment expression specifies a time in samples and may consist of one or more time values which are joined with the operator '''+''' (add) or '''-''' (subtract).
 +
:{|class="einrahmen"
 +
!value !!description !!value in samples !!comment
 +
|-
 +
|<var>x</var> ||<var>x</var> samples ||<var>x</var> ||
 +
|-
 +
|<var>x</var>'''s''' ||<var>x</var> seconds ||<var>x</var> * ''sr'' ||
 +
|-
 +
|<var>x</var>'''ms''' ||<var>x</var> milliseconds ||<var>x</var> / 1000 * ''sr'' ||
 +
|-
 +
|<var>x</var>'''Hz'''  ||periode of a signal with <var>x</var> Hz ||''sr'' / <var>x</var> ||
 +
|-
 +
|<var>x</var>'''kHz''' ||periode of a signal with <var>x</var> kHz ||''sr'' / (<var>x</var> * 1000) ||
 +
|-
 +
|<var>x</var>'''%''' ||<var>x</var> percent of the signal length ||''l'' * <var>x</var> / 100 ||usage 1 and 2 only
 +
|-
 +
|<var>x</var>'''%%''' ||<var>x</var> per mill of the signal length ||''l'' * <var>x</var> / 1000 ||usage 1 and 2 only
 +
|-
 +
|<var>segid</var> ||begin and length of the segment with id <var>segid</var> || ||usage 3 only
 +
|-
 +
|<var>segid</var>''':b''' ||begin of the segment with id <var>segid</var> || ||usage 3 only
 +
|-
 +
|<var>segid</var>''':e''' ||end of the segment with id <var>segid</var> || ||usage 3 only
 +
|-
 +
|<var>segid</var>''':l''' ||length of the segment with id <var>segid</var> || ||usage 3 only
 +
|-
 +
|}
 +
:{|class="keinrahmen"
 +
|with: ||<var>x</var>||=||a number
 +
|-
 +
| ||''sr''||=||signal sampling rate in Hz
 +
|-
 +
| ||''l''||=||signal length in samples (e.g. soundfile length)
 +
|-
 +
| ||''segid''||=||id of a segment defined in the xml-file item
 
|}
 
|}
  

Revision as of 20:00, 28 April 2014

STx uses a special syntax to address a segment of a sound file. The syntax allows for the mixed use of segment names and time values in a complex expression known as a "segment expression". Segment expressions can be used in all commands and dialogs where a signal segment (or position/duration) can be specified (exceptions are described in the Command Reference). In dialogs, the supported value formats/types are always described in the control/dialog caption.

Labels

A label expression is a position in a sound file (e.g. the begin/end of a segment) or the duration of a segment. A label expression may consist of a sign (+/-) and one or more values formatted as described below and combined with the operators + (add) or – (subtract). If a label expression contains blanks, it must be quoted when used as an argument.

label expression explanation
segmentname:B start time of segment segmentname
segmentname:E end time of segment segmentname
segmentname:L duration (length) of segment segmentname
numberS time in seconds
numberMS time in milliseconds
number number of samples

Segments

A segment expression addresses a part of a soundfile with a non-zero duration. It can consist of (1) a segment name or (2) two label expressions specifying the beginning and end or (3) two label expressions specifying a position and the duration.

segment expression explanation
labelexpression_labelexpression (beginning and end)
labelexpression_+labelexpression (beginning and duration)
labelexpression_-labelexpression (end and duration)

The segment expression segexpr specifies a label (position) in a signal or a segment (part) of a signal. The command evaluates the segment expression and returns the label position or the begin, end and length of the segment.

segexpr description
bexpr a position (label) at bexpr
bexpr_eexpr a segment with begin bexpr and end expr
bexpr_+lexpr a segment with begin bexpr and length lexpr (end = bexpr+lexpr)
eexpr_-lexpr a segment with end eexpr and length lexpr (begin = eexpr-lexpr)

Each part (bexpr, eexpr and lexpr) of the segment expression specifies a time in samples and may consist of one or more time values which are joined with the operator + (add) or - (subtract).

value description value in samples comment
x x samples x
xs x seconds x * sr
xms x milliseconds x / 1000 * sr
xHz periode of a signal with x Hz sr / x
xkHz periode of a signal with x kHz sr / (x * 1000)
x% x percent of the signal length l * x / 100 usage 1 and 2 only
x%% x per mill of the signal length l * x / 1000 usage 1 and 2 only
segid begin and length of the segment with id segid usage 3 only
segid:b begin of the segment with id segid usage 3 only
segid:e end of the segment with id segid usage 3 only
segid:l length of the segment with id segid usage 3 only
with: x = a number
sr = signal sampling rate in Hz
l = signal length in samples (e.g. soundfile length)
segid = id of a segment defined in the xml-file item

Examples

0_4s

addresses 0 samples to 4 seconds

SegmentA:B+100_+10s

addresses 100 samples after the beginning of SegmentB for a duration of 10 seconds

SegmentB

addresses SegmentB

SegmentA:B_SegmentB:E

addresses the beginning of SegmentA to the end of SegmentB

SegmentB:E_-100ms

addresses 100 milliseconds before the end of SegmentB to the end of SegmentB

Notes: For some expressions, the values number% (percentage of the full duration) and number%% (thousandths of the full duration) can be used, but only if the 'full signal' is available/defined (e.g. for envelopes of sequence signals).A segmentname can only be used if a sound file or an audio-element of an XML-file is involved in the expression evaluation.Segment names are case sensitive!