Programmer Guide/Shell Items/Wave/Introducing Wave Items

Introducing Wave Items

STx wave items are used to play and record soundfiles as well as generate signals and sequences of signals.

Playing Sound files

In order to play a sound file in STx, you need to load it into STx using the LOAD SOUNDFILE command. Once loaded, you can attach it to a WAVE item and play it back.

A macro which plays back a sound file.

[macro wave_item_play_example]
    //
    // ask user to select a soundfile from disk
    //
    #sf := butil 'FileDialog open ; Select a soundfile'
    if '$#sf' == '' exit
    //
    // load the soundfile in STx
    //
    load soundfile '$#sf' /Read
    if '$rc' > 0 em $rc ; LOAD SOUNDFILE failed ($emsg)
    readvar csfh #srate #nch #nsamples #code #type #mode
    //
    // create a wave item addressing the soundfile
    //
    #wave := new wave * 1_$#nsamples
    if '$#wave[?]' != 'wave' em -1 ; wave creation failed ($emsg)
    //
    // play the contents of the soundfile
    //
    $#wave play
    //
    // use message box to prevent script from ending
    //
    um 'Do you want to exit?'
    //
    // clean up
    //
    delete $#wave
exit

An alternative method is to use the XWAVE class:

[macro xwave_play_example]
    //
    // ask user to select a soundfile from disk
    //
    #sf := butil 'FileDialog open ; Select a soundfile'
    if '$#sf' == '' exit
    //
    // create XWAVE instance
    //
    #xwave := xwave '$#sf'
    if '$#xwave[?]' != 'instance' then
        em -1 ; Failed to create the xwave item.
    end
    //
    // play soundfile
    //
    $#xwave play
    //
    // clean up
    //
    $#xwave destroy
exit

Recording Sound files

A macro which records a signal to file.

[macro wave_item_record_example]
    //
    // create file to record to
    //
    #sf := bsf newdialog 44100 ; 2 ; PCM16
    if '$#sf' == '' exit
    //
    // load the soundfile in STx
    //
    bsf open $#sf
    bsf select $#sf
    readvar csfh #srate #nch #nsamples #code #type #mode
    //
    // create a wave item to record to
    //
    #wave := new wave * 0_44100
    if '$#wave[?]' != 'wave' em -1 ; wave creation failed ($emsg)
    //
    // record 1 second
    //
    $#wave record 44100
    if '$rc' > 0 em $rc ; RECORD failed ($emsg)
    //
    // use message box to prevent script from ending
    // before the signal has been recorded
    //
    um 'Stop recording?'
    $#wave stop
    //
    // clean up
    //
    delete $#wave
    bsf close $#sf
    if '$result' != '0' em $result ; closing soundfile failed
exit

Sequences

A 'sequence' is a virtual soundfile dynamically created in memory from a sequence definition. The sequence definition specifies the order and type of signals to sequence.

Sequence wave items are created using the option /Q.

Defining a Sequence

A sequence is defined using the wave item command SIGNAL. Defined signals can then be filtered using the filter commands (see Filtering a Sequence). When signal definitions and filtering have been done, the sequence is finalized using the END command. The sequence can then be accessed like any other wave item.