Programmer Guide/Command Reference/SEGMENT: Difference between revisions

From STX Wiki
Jump to navigationJump to search
No edit summary
No edit summary
Line 1: Line 1:
{{DISPLAYTITLE:{{SUBPAGENAME}}}}__NOTOC__
{{DISPLAYTITLE:{{SUBPAGENAME}}}}__NOTOC__
===Usage===
==Usage==
'''1.''' Evaluate the segment expression <var>segexpr</var>, using the sampling rate and the length of the current soundfile (see [[../LOAD|LOAD SOUNDFILE]]).
'''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>
:<code>SEGMENT <var>segexpr</var> [/S | /?]</code>
Line 15: Line 15:
:;<var>segtag</var>:the xml element tag used for segment definitions
:;<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>)
:;<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===
==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.  
*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.  
::Note: If the segment expression specifies a label, the return value is <code>''pos'' ''pos'' '''0'''</code>.
:Note: If the segment expression specifies a label, the return value is <code>''pos'' ''pos'' '''0'''</code>.
:*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==
==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.
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"
:{|class="einrahmen"
!<var>segexpr</var> !! description
!<var>segexpr</var> !! description
|-
|-
Line 32: Line 32:
|<code>''eexpr''_-''lexpr''</code> || a segment with end ''eexpr'' and length ''lexpr'' (begin = ''eexpr''-''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).
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"
::{|class="einrahmen"
!value !!description !!value in samples !!comment
!value !!description !!value in samples !!comment
Line 42: Line 42:
|<var>x</var>'''ms''' ||<var>x</var> milliseconds ||<var>x</var> / 1000 * ''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>'''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>'''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> 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>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> ||begin and/or length the segment with id <var>segid</var>
|-
|-
|<var>segid</var>''':e''' || end of the segment with id <var>segid</var> || || usage 3 only
|<var>segid</var>''':b''' ||begin of the segment with id <var>segid</var> (see [[#Examples]])|| ||usage 3 only
|-
|-
|<var>segid</var>''':l''' || length 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"
:{|class="keinrahmen"
|with: ||<var>x</var>||=||a number
|with: ||<var>x</var>||=||a number
|-
|-
Line 66: Line 68:
| ||''segid''||=||id of a segment defined in the xml-file item
| ||''segid''||=||id of a segment defined in the xml-file item
|}
|}
==See also==
[[Programmer_Guide/Class_Library/BDataSet|class BDataSet]], [[../LOAD|LOAD SOUNDFILES]], [[../INT|INT]], [[../NUM|NUM]], [[Programmer_Guide/Shell_Items/File|file item (xml)]]
==Examples==
segment 0_4s      // addresses 0 samples to 4 seconds of the current soundfile
segment 50%-1s_+2s // addresses 2 seconds in the middle of the current soundfile


{{DISPLAYTITLE:{{SUBPAGENAME}}}}
segment 1s_+100 10000 5*10000 // addresses 1 second to 1 second plus 100 samples
==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>
segment seg1:b_
SegmentA:B+100_+10s
SegmentA:B+100_+10s
</pre>
</pre>

Revision as of 10:29, 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 [/S | /?]
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 variable RC is set to 0.
Note: If the segment expression specifies a label, the return value is pos pos 0.
  • error: the command returns the empty string and the error- or warning-code is stored in variable RC

Description

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/or length the segment with id segid
segid:b begin of the segment with id segid (see #Examples) 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

See also

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

Examples

segment 0_4s       // addresses 0 samples to 4 seconds of the current soundfile
segment 50%-1s_+2s // addresses 2 seconds in the middle of the current soundfile

segment 1s_+100 10000 5*10000 // addresses 1 second to 1 second plus 100 samples

segment seg1:b_

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
Retrieved from "https://mediawiki.kfs.oeaw.ac.at/stx/docs/wiki/index.php?title=Programmer_Guide/Command_Reference/SEGMENT&oldid=4244"

Navigation menu

Personal tools