Programmer Guide/Macro Library/XWave: Difference between revisions
| (9 intermediate revisions by the same user not shown) | |||
| Line 1: | Line 1: | ||
{{DISPLAYTITLE:{{SUBPAGENAME}}}} | {{DISPLAYTITLE:{{SUBPAGENAME}}}} | ||
{{TOC limit|3}} | {{TOC limit|3}} | ||
{{TODO}} | |||
==XWave : CObjEx== | ==XWave : CObjEx== | ||
| Line 7: | 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 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). | 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 17: | 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: | |||
;<var>aset</var> | ;<var>aset</var> | ||
| Line 33: | Line 34: | ||
;<var>soundfile</var> | ;<var>soundfile</var> | ||
:The path to a | :The path to a sound file on disk. | ||
;<var>wave</var> | ;<var>wave</var> | ||
| Line 111: | Line 112: | ||
Quickly read the next frame. | Quickly read the next frame. | ||
;Usage:<code><var>xwave</var> ReadQ</code> | |||
<code><var>xwave</var> ReadQ</code> | |||
A signal vector of the next frame. | ;Result:A signal vector of the next frame. | ||
===SetFrame=== | ===SetFrame=== | ||
| Line 123: | Line 120: | ||
Set the I/O frame parameters. | Set the I/O frame parameters. | ||
;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> | |||
;Parameters | |||
;<var>mode</var> | ;<var>mode</var> | ||
| Line 135: | 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 149: | 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:Returns the number of frames (>1) or 0 for error. | |||
Returns the number of frames (>1) or 0 for error. | |||
===TBegin=== | ===TBegin=== | ||
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 attributesAmpMaxandAmpRef) orCALSET(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
