Programmer Guide/Command Reference/SEGMENT: Difference between revisions

From STX Wiki
Jump to navigationJump to search
No edit summary
 
(45 intermediate revisions by 4 users not shown)
Line 1: Line 1:
{{DISPLAYTITLE:{{SUBPAGENAME}}}}
{{DISPLAYTITLE:{{SUBPAGENAME}}}}
;Usage:
The <code>SEGMENT</code> command evaluates a segment expression in various ways returning a string indicating the ''begin'' (<var>bseg</var>), the ''end'' (<var>eseg</var>) and the ''length'' (<var>lseg</var>) of the segment addressed by the respective segment expression.
'''1.''' Evaluate the segment expression <var>segexpr</var>, using the sampling rate and the length of the current soundfile (see [[../LOAD|LOAD SOUNDFILE]]).
:<code>SEGMENT <var>segexpr</var> [/S | /?]</code>
:;<var>segexpr</var>:the segment expression to be evaluated
:;<code>/S</code>, <code>/?</code>:silent error handling; generate warnings rather than errors.
'''2.''' Evaluate the segment expression <var>segexpr</var>, using the specified sampling rate and length.
:<code>SEGMENT <var>segexpr sr l</var> [/S | /?]</code>
:;<var>sr</var>:sampling rate in Hz
:;<var>l</var>:maximum signal duration in samples
'''3.''' Evaluate the segment expression <var>segexpr</var>, using the sampling rate and the segment definitions stored in the [[Programmer_Guide/Shell_Items/File|xml-file item]] <var>xitem</var>.
:<code>SEGMENT <var>segexpr xmlfile srattr segtag idattr pattr lattr</var> [/S | /?]</code>
:;<var>xmlfile</var>:a [[Programmer_Guide/Shell_Items/File|xml-file item]] containing the metadata; the selected element must contain soundfile metadata and the segment definitions must be stored as child elements
:;<var>srattr</var>:the xml attribute of the selected element containing the sampling rate (in Hz)
:;<var>segtag</var>:the xml element tag used for segment definitions
:;<var>idattr, pattr, lattr</var>:the xml attributes used in the segment definition elements to specifiy the segment id (<var>idattr</var>) and its starting position (<var>pattr</var>) and length (<var>lattr</var>)
;Result:
:*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. If the segment expression specifies a label, the values of ''bseg'' and ''eseg'' are equal and ''lseg'' equals zero.
:*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 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>''':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
|}


{{DISPLAYTITLE:{{SUBPAGENAME}}}}
<var>bseg</var> <var>eseg</var> <var>lseg</var>
==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.
== {{anchor|usage1|Based on the current sound file}} ==


'''Labels'''
Evaluate the segment expression <var>segexpr</var>, using the sampling rate and the length of the [[Programmer_Guide/Concepts/Current_Soundfile|current sound file]] (see [[../LOAD|LOAD SOUNDFILE]]):


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.
SEGMENT <var>segexpr</var> [ [[Programmer_Guide/Command_Reference_Options/Silent|/Silent | /?]] ]
:;<var>segexpr</var>:the segment expression to be evaluated
:;[[Programmer_Guide/Command_Reference_Options/Silent|<code>/Silent</code>]], <code>/?</code>:silent error handling; generate warnings rather than errors.


{|
== {{anchor|usage2|Based on supplied data}} ==
|-
|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'''
Evaluate the segment expression <var>segexpr</var>, using the specified sampling rate and length.


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 <var>segexpr</var> <var>sr</var> <var>l</var> [ [[Programmer_Guide/Command_Reference_Options/Silent|/Silent | /?]] ]
:;<var>segexpr</var>:the segment expression to be evaluated
:;<var>sr</var>:sampling rate in Hz
:;<var>l</var>:maximum signal duration in samples
 
== {{anchor|usage3|Based on data from an XML segment definition}} ==


{|
Evaluate the segment expression <var>segexpr</var>, using the sampling rate and the segment definitions stored in the [[Programmer_Guide/Shell_Items/File|XML file item]] <var>xmlfile</var>.
|-
|segment expression
|explanation
|-
|labelexpression_labelexpression
|(beginning and end)
|-
|labelexpression_+labelexpression
|(beginning and duration)
|-
|labelexpression_<nowiki>-</nowiki>labelexpression
|(end and duration)
|}


'''Examples'''
SEGMENT <var>segexpr</var> <var>xmlfile</var> <var>srattr</var> <var>segtag</var> <var>idattr</var> <var>pattr </var> <var>lattr</var> [ [[Programmer_Guide/Command_Reference_Options/Silent|/Silent | /?]] ]
:;<var>segexpr</var>:the segment expression to be evaluated
:;<var>xmlfile</var>:an [[Programmer_Guide/Shell_Items/File|XML file item]] containing the metadata; the selected element must contain sound file metadata, and the segment definitions must be stored as child elements
:;<var>srattr</var>:the XML attribute of the selected element containing the sampling rate (in Hz)
:;<var>segtag</var>:the XML element tag used for segment definitions
:;<var>idattr</var>, <var>pattr</var> and <var>lattr</var>:the XML attributes used in the segment definition elements to specifiy the segment id (<var>idattr</var>) and its starting position (<var>pattr</var>) and length (<var>lattr</var>)


<pre>
==Result==
0_4s
;success: <code>''bseg eseg lseg''</code> - the return value is the ''begin'' (''bseg''), the ''end'' (''eseg'') and the ''length'' (''lseg'') of the segment specified by the segment expression. The variable <var>RC</var> is set to 0.
</pre>
:Note: If the segment expression specifies a label at position ''lpos'', the return value is <code><var>lpos</var> <var>lpos</var> '''0'''</code>.
addresses 0 samples to 4 seconds
;error: the command returns an empty string. As usual, the error, or warning code (0 on success) is stored in the variable <var>RC</var>.


<pre>
==Segment Expressions ==
SegmentA:B+100_+10s
{{:Programmer_Guide/General_Descriptions/Segment_Expressions}}
</pre>
addresses 100 samples after the beginning of SegmentB for a duration of 10 seconds


<pre>
==Further Examples==
SegmentB
Address 0 samples to 4 seconds of the current soundfile:
</pre>
segment 0_4s     
addresses SegmentB


<pre>
Address 2 seconds in the middle of the current soundfile:
SegmentA:B_SegmentB:E
segment 50%-1s_+2s
</pre>
addresses the beginning of SegmentA to the end of SegmentB


<pre>
Address 1 second to 1 second plus 100 samples of a signal with a 10kHz sampling rate and a 5 seconds duration:
SegmentB:E_<nowiki>-</nowiki>100ms
segment 1s_+100 10000 5*10000
</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!
Note: XML attributes and element names and segment ids are case sensitive!


Address the whole signal of segment '''seg1''':
segment seg1 ''xmlfile'' SR ASeg ID P L 


Address the signal from the beginning of '''seg1''' to the end of '''seg1''' plus 2 seconds:
segment seg1:b_seg2:e+2s ''xmlfile'' SR ASeg ID P L


;See also:
==See also==
[[Programmer_Guide/Class_Library/BDataSet|class BDataSet]], [[../LOAD|LOAD SOUNDFILES]], [[../INT|INT]], [[../NUM|NUM]], [[Programmer_Guide/Shell_Items/File|file item (xml)]]

Latest revision as of 11:01, 17 April 2018

The SEGMENT command evaluates a segment expression in various ways returning a string indicating the begin (bseg), the end (eseg) and the length (lseg) of the segment addressed by the respective segment expression. 

bseg eseg lseg

Based on the current sound file

Evaluate the segment expression segexpr, using the sampling rate and the length of the current sound file (see LOAD SOUNDFILE): 

SEGMENT segexpr [ /Silent | /? ]
segexpr
the segment expression to be evaluated
/Silent, /?
silent error handling; generate warnings rather than errors.

Based on supplied data

Evaluate the segment expression segexpr, using the specified sampling rate and length. 

SEGMENT segexpr sr l [ /Silent | /? ]
segexpr
the segment expression to be evaluated
sr
sampling rate in Hz
l
maximum signal duration in samples

Based on data from an XML segment definition

Evaluate the segment expression segexpr, using the sampling rate and the segment definitions stored in the XML file item xmlfile. 

SEGMENT segexpr xmlfile srattr segtag idattr pattr  lattr [ /Silent | /? ]
segexpr
the segment expression to be evaluated
xmlfile
an XML file item containing the metadata; the selected element must contain sound file 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 and 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), the end (eseg) and the length (lseg) of the segment specified by the segment expression. The variable RC is set to 0.
Note: If the segment expression specifies a label at position lpos, the return value is lpos lpos 0.
error
the command returns an empty string. As usual, the error, or warning code (0 on success) is stored in the variable RC.

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 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

Further Examples

Address 0 samples to 4 seconds of the current soundfile: 

segment 0_4s

Address 2 seconds in the middle of the current soundfile: 

segment 50%-1s_+2s

Address 1 second to 1 second plus 100 samples of a signal with a 10kHz sampling rate and a 5 seconds duration: 

segment 1s_+100 10000 5*10000

Note: XML attributes and element names and segment ids are case sensitive!

Address the whole signal of segment seg1: 

segment seg1 xmlfile SR ASeg ID P L

Address the signal from the beginning of seg1 to the end of seg1 plus 2 seconds: 

segment seg1:b_seg2:e+2s xmlfile SR ASeg ID P L

See also

class BDataSet, LOAD SOUNDFILES, INT, NUM, file item (xml)

Retrieved from "https://mediawiki.kfs.oeaw.ac.at/stx/docs/wiki/index.php?title=Programmer_Guide/Command_Reference/SEGMENT&oldid=10015"

Navigation menu

Personal tools