Programmer Guide/Command Reference/SEGMENT

SEGMENT evaluates a segment expression in various ways, returning a string

bseg eseg lseg

indicating the begin (bseg), the end (eseg) and the length (lseg) of the segment addressed by the respective segment expression.

Based on the current soundfile

Evaluate the segment expression segexpr, using the sampling rate and the length of the current soundfile (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 | /? ]

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

SEGMENT segexpr xmlfile srattr segtag idattr pattr  lattr [ /Silent | /? ]

xmlfile

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

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

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 10kHz sampling rate 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)