Programmer Guide/Programming a Toolbox/Example Toolbox function

The function ExportSegmentsToSoundfiles exports the selected segments from the Workspace Detail to individual soundfiles. It is only available in the DataSet context.

//{{3.7.0 849}{2005.05.30  15.31.20} - automatically created version information - do not change or delete this line}

/*
This is a Toolbox definition and implementation file. Load this file into
STx via the Special->Toolbox Function menu.
*/

/*++-------------------------------------------------------------------------//
Function:       ExportSegmentsToSoundfiles
Usage:          This is a Toolbox function definition and is called
                by the Toolbox manager.
Description:    The user can select segments in the Workspace Detail and 
                export them to individual soundfiles (one per segment).
                By default, soundfiles are exported to the same directory 
                as the segment's soundfile is in and sequences are exported
                to the working directory.
Author:         Jonnie White
History:        2005-06-03    jw    Created
                2005-09-21    jw    Version: 1.0
--*/
[Function ExportSegmentsToSoundfiles]
// Hotkey ; Command                    ; Type  ; Context ; Applications
*         ; ExportSegmentsToSoundfiles ; macro ; dataset ; *
// Description
Export the selected segments to individual soundfiles
// Setup Variables
// 
// Variable: AddToDataset
// Values:   0|1
//           0 - Do not add files to the dataset
//           1 - Ask the user if they want to add files to the dataset)
AddToDataset = 1
// Variable: PathFlags
// Values:   0|1|2|3
//           0 - The path should be the same as the source file. The 
//               value of Path is ignored.
//           1 - The value of Path should be used, or if Path is empty,
//               the path of the sourcefile should be used.
//           2 - The path should be chosen by the user and used for
//               all segements
//           3 - The user should choose a path for each segment.
PathFlags = 0
// Variable: Path
// Values:   empty or a valid directory path
Path =
// Variable: FileNameFormat
// Values:   String constants and the keywords <soundfile> and <segment> which 
//           are replaced with the soundfile ID and the segment ID 
//           respectively.
FileNameFormat = <soundfile>.<segment> 

/*++-------------------------------------------------------------------------//
Macro:          ExportSegmentsToSoundfiles
Usage:          This is a Toolbox function implementation macro for the DataSet
                context
Description:    This Toolbox function is called in the Dataset context and
                exports any selected segments to soundfiles. The user can
                choose the file name format for the soundfiles which will be
                created.
Author:         Jonnie White
History:        2005-06-03    jw    Created
--*/
[Macro ExportSegmentsToSoundfiles]
// Parses the arguments depending on the context.
// This must be the first command
$@TBPARSE '$#argv'
// Loads the settings (if any are defined)
$@TBLOADSETUP 

// if there are selected segments in the DataSet context table #etab
if '$#etab[?]' == 'table' && '$#etab[]' > 0 && '$#etag' == 'aseg' then
    $BDataset Attach // attach the dataset for the duration of this function
    // save the position so we can restore it at the end of the function
    #origPos := $($BDataset SavePos)
    #tFiles := new table * // Add new file paths to this table
    while '$#etab[]' > 0 // if the user has selected any segments
        $BDataset SelectASeg * ; $#etab[0] // select the segment
        if '$result' == 0 then
            // get information about the audio set the segment is in
            readstr '$($BDataset GetASetInfo)' #';'#ASetId';'#';'#';'#ASetFilePath /Delete
            // get information about the id of the segment
            readstr '$($BDataset GetSegment $#ASetIRef ; * ; ID)' #ASegId';'# /Delete
            // select the output path depending on the user's settings
            gosubx _SelectOutputPath
            // format the output path depending on the user's settings
            #file := $#OutputPath'\'$(gosubx _FormatFileName $#ASetId;$#ASegId).wav
            // create a wave item based on this segment and save it to file
            #wsrc := $($BDataset CreateWave '$#ASetIRef ; $#ASegId ; *') 
            if '$#wsrc[?]' == wave then
                if '$(bsf 'open $#file;create;~$#wsrc[!srate];~$#wsrc[!channels]')' == 0 then
                    #wdst := $(new wave * 0_~$#wsrc[!length])
                    if $rc == 0 then
                        if $($#wsrc copy $#wdst) == 0 $#tFiles * $#file
                        delete $#wdst
                    end
                    bsf 'close $#file'
                else
                    BUtil 'Msgbox Msg; Failed to create the file $#file ; ToolBox $#mac Error!'
                end
                $BDataset deletewave $#wsrc
            else
                BUtil 'Msgbox Msg; Create waveitem failed! ; ToolBox $#mac Error!'
            end
        end
        $#etab 0 /Delete
    end
    // Give the user the option to add the new soundfiles to the project.
    if '$#AddToDataset' > 0 then
        readstr '$($BDataset DialogSelectElement Select target set for new soundfiles; single; iref; Set; 1)' #targetSetRef
        if '$#read' > 0 then
            while $#tFiles[] > 0
                $BDataset AddASet '$#tFiles[0];$#targetSetRef;*'
                $#tFiles 0 /Delete
            end
            DatasetCmd RefreshAll
        end
    end

    $BDataset SelectIRef $#origPos
    $BDataset SavePos $#origPos
    $BDataset Detach
else
    BUtil 'MsgBox Msg; Please select at least one segment and try again.; ToolBox $#mac Error!'
end

$@TBSAVESETUP        // Save the settings (if any were changed)
exit 1 int $#changed // #changed must be set to 1 if any data was changed (otherwise 0)

//  The user can determine what the filename should look like, using
//  the keywords <soundfile> and <segment>. This function formats
//  the filename.
_FormatFileName:
    readvar #argv #soundfile';'#segment
    if '$#read' != 2 em -1 ; Not enough argument in $#mac
    #name := $#FileNameFormat
    readstr '$#name' #before'<soundfile>'#after /Delete
    if '$#read' > 0 && '$#before' != '$#name' #name := $#before'$#soundfile'$#after
    readstr '$#name' #before'<segment>'#after /Delete
    if '$#read' > 0 && '$#before' != '$#name'  #name := $#before'$#segment'$#after
    exit 1 set '$#name'

//  Select the output path based on the user's settings.
_SelectOutputPath:
    if '$#PathFlags' == 0 || '$#PathFlags' == 1 then
        // User settings path
        if '$#PathFlags' == 1 && '$#Path' != '' then
            #OutputPath := $(BUtil GetDirectory $#Path)
            if '$#OutputPath' != '$#Path' then
                #Path := $(Butil DirectoryDialog Please select an existing directory ; $#Path ; Yes ; No ; No)
                if '$#Path' != '' then 
                    #OutputPath := $#Path
                else
                    exit 2 // User has failed to select a path, so we will export nothing.
                end
            end
        // Automatic output path
        else
            if '$#ASetFilePath' != '' then // AFile
                readstr '$(FileToolBox Tokenize $#ASetFilePath)' #drive';'#dir';'#name';'#ext /Delete
                #OutputPath := '$#drive':'$#dir'
            else // ASeq: sequences are stored in the @WORK directory by default
                #OutputPath := $@WORK'\'
            end
        end
    else if '$#PathFlags' == 2 || '$#PathFlags' == 3 then
        if '$#OutputPath' == '' || '$#PathFlags' == 3 then
            #OutputPath := $(butil 'directorydialog Export path for soundfiles; *; No; No; No')
        end
    end
    exit