Programmer Guide/Command Reference/SEGMENT: Difference between revisions
No edit summary |
No edit summary |
||
| Line 18: | Line 18: | ||
:*success: <code>''bseg eseg lseg''</code> - the return value is the begin (''bseg''), end (''eseg'') and length (''lseg'') of the segment specified by the segment expression. The variable <code>RC</code> is set to 0. | :*success: <code>''bseg eseg lseg''</code> - the return value is the begin (''bseg''), end (''eseg'') and length (''lseg'') of the segment specified by the segment expression. The variable <code>RC</code> is set to 0. | ||
:*error: the command returns the empty string and the error- or warning-code is stored in variable <code>RC</code> | :*error: the command returns the empty string and the error- or warning-code is stored in variable <code>RC</code> | ||
;Description: | |||
:The segment expression <var>segexpr</var> specifies a position in a signal or the begin and end of a part of a signal. | |||
::{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 !!comment | |||
|<var>x</var> || <var>x</var> samples | |||
|<var>x</var>'''ms''' || <var>x</var> milliseconds | |||
|<var>x</var>'''s''' || <var>x</var> seconds | |||
|<var>x</var>'''Hz''' || periode duration of a harmonic tone with <var>x</var> Hz<BR>= <code>''sampling-rate'' / ''x''</code> | |||
|<var>x</var>'''kHz''' || periode duration of a harmonic tone with <var>x</var> Hz<BR>= <code>''sampling-rate'' / (''x'' * 1000)</code> | |||
|} | |||
{{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. | |||
'''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<nowiki>-</nowiki>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_<nowiki>-</nowiki>labelexpression | |||
|(end and duration) | |||
|} | |||
'''Examples''' | |||
<pre> | |||
0_4s | |||
</pre> | |||
addresses 0 samples to 4 seconds | |||
<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> | |||
SegmentB:E_<nowiki>-</nowiki>100ms | |||
</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! | |||
;See also: | |||
Revision as of 09:04, 27 April 2011
- Usage
1. Evaluate the segment expression segexpr, using the sampling rate and the length of the current soundfile (see LOAD SOUNDFILE).
SEGMENT segexpr [/S | /?]- segexpr
- the segment expression to be evaluated
/S,/?- silent error handling; generate warnings rather than errors.
2. Evaluate the segment expression segexpr, using the specified sampling rate and length.
SEGMENT segexpr sr l [/S | /?]- sr
- sampling rate in Hz
- l
- maximum signal duration in samples
3. Evaluate the segment expression segexpr, using the sampling rate and the segment definitions stored in the xml-file item xitem.
SEGMENT segexpr xmlfile srattr segtag idattr pattr lattr- xmlfile
- a xml-file item containing the metadata; the selected element must contain soundfile metadata and the segment definitions must be stored as child elements
- srattr
- the xml attribute of the selected element containing the sampling rate (in Hz)
- segtag
- the xml element tag used for segment definitions
- idattr, pattr, lattr
- the xml attributes used in the segment definition elements to specifiy the segment id (idattr) and its starting position (pattr) and length (lattr)
- Result
-
- success:
bseg eseg lseg- the return value is the begin (bseg), end (eseg) and length (lseg) of the segment specified by the segment expression. The variableRCis set to 0. - error: the command returns the empty string and the error- or warning-code is stored in variable
RC
- success:
- Description
- The segment expression segexpr specifies a position in a signal or the begin and end of a part of a signal.
- {class="einrahmen"
!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).
- {class="einrahmen"
!value !!description !!comment
|x || x samples
|xms || x milliseconds
|xs || x seconds
|xHz || periode duration of a harmonic tone with x Hz
= sampling-rate / x
|xkHz || periode duration of a harmonic tone with x Hz
= sampling-rate / (x * 1000)
|}
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.
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) |
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!
- See also
