Programmer Guide/Macro Library/XWave: Difference between revisions

From STX Wiki
Jump to navigationJump to search
m (1 revision: Initial import)
 
(14 intermediate revisions by 2 users not shown)
Line 1: Line 1:
{{DISPLAYTITLE:{{SUBPAGENAME}}}}
{{DISPLAYTITLE:{{SUBPAGENAME}}}}
{{TOC limit|3}}
{{TODO}}
==XWave : CObjEx==
==XWave : CObjEx==


Line 6: Line 8:
====XWave Construction====
====XWave Construction====


Create a new <code>XWAVE</code> instance. The <code>XWAVE</code> references either a segment (<var>aseg</var>), a whole soundfile (<var>soundfile</var>) or a wave-item signal (<var>wave</var>). Information and error messages are written to the script console. If no optional arguments are specified, only the instance is created, otherwise the frame-setup is also performed (see member SETFRAME).
Create a new <code>XWAVE</code> instance. The <code>XWAVE</code> references either a segment (<var>aseg</var>), a whole sound file (<var>soundfile</var>) or a wave-item signal (<var>wave</var>). Information and error messages are written to the script console. If no optional arguments are specified, only the instance is created, otherwise the frame-setup is also performed (see member [[#SetFrame|SETFRAME]]).


=====Usage:=====
=====Usage:=====
Line 16: Line 18:
<code>XWAVE <var>wave</var> [; <var>mode</var> ; <var>length</var> ; <var>shift</var> ; <var>amax</var> ; <var>aref</var>]</code>
<code>XWAVE <var>wave</var> [; <var>mode</var> ; <var>length</var> ; <var>shift</var> ; <var>amax</var> ; <var>aref</var>]</code>


=====Parameters:=====
;Parameters:


;<var>aset</var>
;<var>aset</var>
Line 32: Line 34:
;<var>soundfile</var>
;<var>soundfile</var>


:The path to a soundfile on disk.
:The path to a sound file on disk.


;<var>wave</var>
;<var>wave</var>
Line 66: Line 68:
You can also use "<code>cobj new xwave ...</code>" to create a <code>XWAVE</code> object. You can delete an <code>XWAVE</code> object using "<code>COBJ DELETE xwaveobject</code>" or "<code>xwaveobject DESTROY</code>".
You can also use "<code>cobj new xwave ...</code>" to create a <code>XWAVE</code> object. You can delete an <code>XWAVE</code> object using "<code>COBJ DELETE xwaveobject</code>" or "<code>xwaveobject DESTROY</code>".


====XWave Member Functions====
==XWave Member Functions==


The <code>XWave</code> class implements the following member functions. See CObjEx Member Functions for a list of functions implemented in the parent class.
The <code>XWave</code> class implements the following member functions. See CObjEx Member Functions for a list of functions implemented in the parent class.
Line 110: Line 112:
Quickly read the next frame.
Quickly read the next frame.


=====Usage:=====
;Usage:<code><var>xwave</var> ReadQ</code>
 
<code><var>xwave</var> ReadQ</code>
 
=====Result:=====


A signal vector of the next frame.
;Result:A signal vector of the next frame.


===SetFrame===
===SetFrame===
Line 122: Line 120:
Set the I/O frame parameters.
Set the I/O frame parameters.


=====Usage:=====
;Usage:<code><var>xwave</var> SetFrame <var>mode</var> ; <var>length</var> ; <var>shift</var>=25% ; <var>amax</var>=1 ; <var>aref</var>=1</code>


<code><var>xwave</var> SetFrame <var>mode</var> ; <var>length</var> ; <var>shift</var>=25% ; <var>amax</var>=1 ; <var>aref</var>=1</code>
;Parameters
 
=====Parameters:=====


;<var>mode</var>
;<var>mode</var>
Line 134: Line 130:
;<var>length</var>
;<var>length</var>


:The frame length (a time expression).
:The frame length ([[Programmer_Guide/Command_Reference/SEGMENT#Segment_Expression|a time expression]]).


;<var>shift</var>
;<var>shift</var>
Line 148: Line 144:
:The reference signal amplitude (=0dB). This is only used if <var>amax</var> is a number.
:The reference signal amplitude (=0dB). This is only used if <var>amax</var> is a number.


=====Result:=====
;Result:Returns the number of frames (>1) or 0 for error.
 
Returns the number of frames (>1) or 0 for error.


===TBegin===
===TBegin===
Line 184: Line 178:
<code><var>xwave</var> Play</code>
<code><var>xwave</var> Play</code>


====XWave Attribute Functions====
==XWave Attribute Functions==


The following functions return attribute values from the <code>XWave</code> instance but do not modify the instance.
The following functions return attribute values from the <code>XWave</code> instance but do not modify the instance.

Latest revision as of 11:04, 17 April 2018

This STx-related article may be outdated.

XWave : CObjEx

A wave I/O class for signal processing in scripts.

XWave Construction

Create a new XWAVE instance. The XWAVE references either a segment (aseg), a whole sound file (soundfile) or a wave-item signal (wave). Information and error messages are written to the script console. If no optional arguments are specified, only the instance is created, otherwise the frame-setup is also performed (see member SETFRAME).

Usage:

XWAVE aset ; aseg ; ach [; mode ; length ; shift ; amax ; aref]

XWAVE soundfile [; mode ; length ; shift ; amax ; aref]

XWAVE wave [; mode ; length ; shift ; amax ; aref]

Parameters
aset
An audio set reference.
aseg
A segment ID.
ach
A channel index.
soundfile
The path to a sound file on disk.
wave
The id of a wave item.
mode
Optional argument for frame-setup.
length
Optional argument for frame-setup.
shift
Optional argument for frame-setup.
amax
Optional argument for frame-setup.
aref
Optional argument for frame-setup.
Result:

A new XWAVE instance if successful or an empty string.

Notes:

You can also use "cobj new xwave ..." to create a XWAVE object. You can delete an XWAVE object using "COBJ DELETE xwaveobject" or "xwaveobject DESTROY".

XWave Member Functions

The XWave class implements the following member functions. See CObjEx Member Functions for a list of functions implemented in the parent class.

Next

Usage:

xwave Next

Result:

Returns 1 if the end of the signal is reached, otherwise 0.

Description:

Increment the frame index.

Read

Read one signal frame. Returns a buffer (vector or matrix) containing the signal or an empty string. If a buffer is passed, the signal is stored in this buffer. If read fails or the end of the signal is reached and a buffer is passed, the buffer is deleted. The returned signal is scaled with the factor 'amax' (set during SetFrame).

Usage:

xwave Read next=1 ; buffer=

Parameters:
next
Increment frame index (0=no, 1=yes). If this parameter is not specified the frame index is incremented.
buffer
The signal buffer. If no buffer is specified or the specified buffer is invalid, a new buffer is created.
Result:

Returns a buffer (vector or matrix) containing the signal or an empty string.

ReadQ

Quickly read the next frame.

Usage
xwave ReadQ
Result
A signal vector of the next frame.

SetFrame

Set the I/O frame parameters.

Usage
xwave SetFrame mode ; length ; shift=25% ; amax=1 ; aref=1
Parameters
mode
The I/O mode. Either the first frame starts at the beginning of the signal (left aligned: mode=0) or the first frame is centered around signal beginning (centred: mode=1).
length
The frame length (a time expression).
shift
The frame shift (time expression). shift must be lower or equal to length.
amax
The maximum signal amplitude or one of the following calibration keywords: CALATTR (use the audioset attributes AmpMax and AmpRef) or CALSET (use the calibration set linked to the signal).
aref
The reference signal amplitude (=0dB). This is only used if amax is a number.
Result
Returns the number of frames (>1) or 0 for error.

TBegin

Set the signal begin time in the selected unit. If the unit is not specified, samples is used.

Usage:

xwave TBegin [ samples|s|ms ]

TEnd

Set the signal end time in the selected unit. If the unit is not specified, samples is used.

Usage:

xwave TEnd [ samples|s|ms ]

TLength

Set the signal begin time in the selected unit. If the unit is not specified, samples is used.

Usage:

xwave TLength [ samples|s|ms ]

Play

Play the assigned signal using the PlayWave class.

Usage:

xwave Play

XWave Attribute Functions

The following functions return attribute values from the XWave instance but do not modify the instance.

FRAMELENGTH

Usage:

xwave FRAMELENGTH

Result:

Return the framelength in samples.

FFTLENGTH

Usage:

xwave FFTLENGTH

Result:

Return the next power of 2 of the framelength.

FRAMESHIFT

Usage:

xwave FRAMESHIFT

Result:

Return the frameshift in samples.

FRAMECOUNT

Usage:

xwave FRAMECOUNT

Result:

Return the number of frames.

FRAMEINDEX

Usage:

xwave FRAMEINDEX

Result:

Return the index of the current frame.

AMAX

Usage:

xwave AMAX

Result:

Return the value of the maximum signal amplitude.

AREF

Usage:

xwave AREF

Result:

Return the value of the reference signal amplitude.

SRATE

Usage:

xwave SRATE

Result:

Return the sampling rate in Hz.

SAMPLES

Usage:

xwave SAMPLES

Result:

Return the signal length in samples.

CHANNELS

Usage:

xwave CHANNELS

Result:

Return the number of signal channels.

WAVE

Usage:

xwave WAVE

Result:

Return the internal wave object id.

WAVECOPY

Usage:

xwave WAVECOPY

Result:

Return a virtual wave object linked to the internal wave object.

TITLE

Return the title text (as generated during construction).

Usage:

xwave TITLE

Result:

The text displayed in the title.

TYPE

Usage:

xwave TYPE

Result:

Return the type of signal associated with the instance. The result depends on which method was used to create the instance:

WAVE

FILE; filepath

ASEG;aset;aseg;ach

Retrieved from "https://mediawiki.kfs.oeaw.ac.at/stx/docs/wiki/index.php?title=Programmer_Guide/Macro_Library/XWave&oldid=10016"

Navigation menu

Personal tools