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

From STX Wiki
Jump to navigation Jump to search
 
(21 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 
{{DISPLAYTITLE:{{SUBPAGENAME}}}}
 
{{DISPLAYTITLE:{{SUBPAGENAME}}}}
{{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 [[User_Guide/Project/Segment#Segment_Name_Restrictions|segment names]] and time values in a complex expression known as a ''segment expression''. Segment expressions may be used in all commands and dialogs where a signal segment (or a position/duration) may be specified (exceptions are described in the [[Programmer_Guide/Command_Reference|Command Reference]]). In dialogs, the supported value formats/types are always described in the control/dialog caption.
  
;Segment expression: A ''segment expression'' addresses a part of a soundfile with a non-zero duration. It can consist of (1) a segment ''name'', or (2) of two label expressions (see below) specifying the ''beginning'' and the ''end'' of the segment, or (3) of two label expressions (see below) specifying the ''position'' of the segment and its ''duration''.
+
==Segment Expression==
{| style="margin-left:1.5em;"
+
A ''segment expression'' addresses a part of a sound file with a non-zero duration. It can consist of (1) a [[User_Guide/Project/Segment#Segment_Name_Restrictions|segment name]], or (2) of two label expressions (see below) specifying the ''beginning'' and the ''end'' of the segment, or (3) of two label expressions (see below) specifying the ''position'' of the segment and its ''duration''.
|-
+
{|class="einrahmen" style="margin-left:1.5em;"
|segment expression
+
!segment expression!!description
|explanation
 
 
|-
 
|-
 
|labelexpression_labelexpression
 
|labelexpression_labelexpression
Line 18: Line 17:
 
|}
 
|}
  
;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==
{| style="margin-left:1.5em;"
+
: 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.
|-
+
{|class="einrahmen" style="margin-left:1.5em;"
|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
 
|}
 
 
 
 
 
 
 
 
 
 
 
:{|class="einrahmen" style="margin-left:1.5em;"
 
 
!label expression!!description!!value in samples !!comment
 
!label expression!!description!!value in samples !!comment
 
|-
 
|-
Line 60: Line 32:
 
|<var>x</var>'''kHz''' ||periode of a signal with <var>x</var> kHz ||''sr'' / (<var>x</var> * 1000) ||
 
|<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 || only with [[Programmer_Guide/Command_Reference/SEGMENT#usage1|this]] and [[Programmer_Guide/Command_Reference/SEGMENT#usage2|that]] version of the [[Programmer_Guide/Command_Reference/SEGMENT|SEGMENT]] command
+
|<var>x</var>'''%''' ||<var>x</var> percent of the signal length ||''l'' * <var>x</var> / 100 || only with [[Programmer_Guide/Command_Reference/SEGMENT#usage1|this]] and [[Programmer_Guide/Command_Reference/SEGMENT#usage2|that]] version of the [[Programmer_Guide/Command_Reference/SEGMENT|<code>SEGMENT</code>]] command
 
|-
 
|-
|<var>x</var>'''%%''' ||<var>x</var> per mill of the signal length ||''l'' * <var>x</var> / 1000 ||  only with [[Programmer_Guide/Command_Reference/SEGMENT#usage1|this]] and [[Programmer_Guide/Command_Reference/SEGMENT#usage2|that]] version of the [[Programmer_Guide/Command_Reference/SEGMENT|SEGMENT]] command
+
|<var>x</var>'''%%''' ||<var>x</var> per mill of the signal length ||''l'' * <var>x</var> / 1000 ||  only with [[Programmer_Guide/Command_Reference/SEGMENT#usage1|this]] and [[Programmer_Guide/Command_Reference/SEGMENT#usage2|that]] version of the [[Programmer_Guide/Command_Reference/SEGMENT|<code>SEGMENT</code>]] command
 
|-
 
|-
|<var>segid</var> ||begin and length of the segment with id <var>segid</var> || ||[[Programmer_Guide/Command_Reference/SEGMENT#usage3]] only
+
|<var>segid</var> ||begin and length of the segment with id <var>segid</var> || || only with [[Programmer_Guide/Command_Reference/SEGMENT#usage3|this version of the <code>SEGMENT</code> command]]
 
|-
 
|-
|<var>segid</var>''':b''' ||begin of the segment with id <var>segid</var> || ||[[Programmer_Guide/Command_Reference/SEGMENT#usage3]] only
+
|<var>segid</var>''':b''' ||begin of the segment with id <var>segid</var> || || only with [[Programmer_Guide/Command_Reference/SEGMENT#usage3|this version of the <code>SEGMENT</code> command]]
 
|-
 
|-
|<var>segid</var>''':e''' ||end of the segment with id <var>segid</var> || ||[[Programmer_Guide/Command_Reference/SEGMENT#usage3]] only
+
|<var>segid</var>''':e''' ||end of the segment with id <var>segid</var> || || only with [[Programmer_Guide/Command_Reference/SEGMENT#usage3|this version of the <code>SEGMENT</code> command]]
 
|-
 
|-
|<var>segid</var>''':l''' ||length of the segment with id <var>segid</var> || ||[[Programmer_Guide/Command_Reference/SEGMENT#usage3]] only
+
|<var>segid</var>''':l''' ||length of the segment with id <var>segid</var> || || only with [[Programmer_Guide/Command_Reference/SEGMENT#usage3|this version of the <code>SEGMENT</code> command]]
 
|-
 
|-
 
|}
 
|}
  
:{|class="keinrahmen"
+
{|class="keinrahmen" style="margin-left:1.5em;"
|with: ||<var>x</var>||=||a number
+
|Where: ||<var>x</var>||is a number
 
|-
 
|-
| ||''sr''||=||signal sampling rate in Hz
+
| ||<var>sr</var>||is the signal sampling rate in Hz
 
|-
 
|-
| ||''l''||=||signal length in samples (e.g. soundfile length)
+
| ||<var>l</var>||is the signal length in samples (e.g. soundfile length)
 
|-
 
|-
| ||''segid''||=||id of a segment defined in the xml-file item
+
| ||<var>segid</var>||is the ID of a segment defined in the XML file
 
|}
 
|}
  
'''Examples'''
+
==Examples==
 
+
Below you will find a short list of examples.
<pre>
+
:;<code>0_4s</code>: addresses the segment from sample 0 (the beginning) to 4 seconds into the file
0_4s
+
:;<code>SegmentA:B+100_+10s</code>: addresses 100 samples after the beginning of an existing segment called "SegmentB" for a duration of ten seconds
</pre>
+
:;<code>SegmentB</code>: addresses an existing segment called "SegmentB"
addresses 0 samples to 4 seconds
+
:;<code>SegmentA:B_SegmentB:E</code>: addresses the range from the beginning of SegmentA to the end of SegmentB
 
+
:;<code>SegmentB:E_-100ms</code>: addresses the range starting 100 milliseconds ''before'' the end of SegmentB and ending at the end of SegmentB
<pre>
 
SegmentA:B+100_+10s
 
</pre>
 
addresses 100 samples after the beginning of SegmentB for a duration of 10 seconds
 
 
 
<pre>
 
SegmentB
 
</pre>
 
addresses SegmentB
 
 
 
<pre>
 
SegmentA:B_SegmentB:E
 
</pre>
 
addresses the beginning of SegmentA to the end of SegmentB
 
  
<pre>
+
==Notes==
SegmentB:E_<nowiki>-</nowiki>100ms
+
For some expressions, the values <code>number%</code> (percentage of the full duration) and <code>number%%</code> (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 <code>segmentname</code> 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.''
</pre>
 
addresses 100 milliseconds before the end of SegmentB to the end of SegmentB
 
  
Notes: For some expressions, the values <code>number%</code> (percentage of the full duration) and <code>number%%</code> (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 <code>segmentname</code> 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!
+
<!-- hidden keywords -->
 +
<div class="keywords">Time Expression</div>

Latest revision as of 09:50, 12 September 2016

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 may be used in all commands and dialogs where a signal segment (or a position/duration) may be specified (exceptions are described in the Command Reference). In dialogs, the supported value formats/types are always described in the control/dialog caption.

Segment Expression

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

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

Label Expression

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 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 only with this and that version of the SEGMENT command
x%% x per mill of the signal length l * x / 1000 only with this and that version of the SEGMENT command
segid begin and length of the segment with id segid only with this version of the SEGMENT command
segid:b begin of the segment with id segid only with this version of the SEGMENT command
segid:e end of the segment with id segid only with this version of the SEGMENT command
segid:l length of the segment with id segid only with this version of the SEGMENT command
Where: x is a number
sr is the signal sampling rate in Hz
l is the signal length in samples (e.g. soundfile length)
segid is the ID of a segment defined in the XML file

Examples

Below you will find a short list of examples.

0_4s
addresses the segment from sample 0 (the beginning) to 4 seconds into the file
SegmentA:B+100_+10s
addresses 100 samples after the beginning of an existing segment called "SegmentB" for a duration of ten seconds
SegmentB
addresses an existing segment called "SegmentB"
SegmentA:B_SegmentB:E
addresses the range from the beginning of SegmentA to the end of SegmentB
SegmentB:E_-100ms
addresses the range starting 100 milliseconds before the end of SegmentB and ending at 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.

Time Expression