Programmer Guide/Macro Library/BSF



BSF

This macro implements a function package for dealing with sound files.



CLOSE

Decrements the open-counter of the sound file and closes it if the counter is 0. The argument path|index is used to select the sound file. If the argument delete is set to 1 the sound file is deleted after closing.

A sound file can only be closed if it is not in use (e.g. by a wave- or a spu-item). If a wave file addresses this sound file then the wave file must be deleted before closing the sound file. If a sound file was opened more than once, the same number of close-calls must be used to really close the sound file.

Usage:

BSF CLOSE [ path|index [ ; delete ]]

Parameters:

path

The sound file path.

index

The zero-based sound file index.

delete

A flag indicating if the sound file should be deleted. The following values are supported:

0 Do not delete the sound file (this is the default).

1 Delete the sound file.

Result:

0 for success or non-zero errorcode



CLOSEALL

Close all soundfiles opened by a script application. This function is called if the variable AUTOCLOSESF is set to 1 during script execution.

Result:

0 for success or non-zero errorcode



NEWDIALOG

Shows a dialog to select the sound file path and the parameters and creates the file. The arguments (if present and valid) are used as default values for the sound file parameters. The created sound file is not opened!

Usage:

WDIALOG [srate; channels; code]

Parameters:

srate

The sampling rate in Hz.

channels

The number of channels.

code

The sample code (PCM8|PCM16|PCM24|PCM32|FLOAT).

Result:

The path of created sound file or empty string



OPEN

The macro BSF OPEN creates and/or opens a sound file. The function returns 0 if the sound file was opened/created. In this case the sound file is made to the current sound file and its name (full path) and parameters are stored in the variables CSF and CSFH. If a sound file is already opened, it is only selected and the open-counter is incremented. See Shell Environment for detailed information about CSF and CSFH.

READ	The file must exist and is opened for read only access.
WRITE	The file is opened for read/write access and created if it does not exist.
AUTO	The mode READ or WRITE is chosen automatically depending on the file's status.
CREATE	A new file is created even if the specified file exists. If an automatic file name is requested (path equals '*'), the mode CREATE is always assumed. The arguments srate, channels, code, type and offset are only used if a new file is created.

Usage:

BSF OPEN path [; mode; srate; channels; code; type; offset]

Parameters:

path

The sound file path or * for automatic file name (e.g. for temporary files).

mode

The access mode {READ|WRITE|AUTO|CREATE}. See above for more details.

srate

The sampling rate in Hz.

channels

The number of channels.

code

The sample code (PCM8|PCM16|PCM24|PCM32|FLOAT).

type

The file format (ST5|WAVE|BINARY).

offset

The size of the file header in bytes (for type=BINARY).

Result:

0 for success or non-zero error code.



OPENDIALOG

Display a dialog to open an existing soundfile. If the function returns a path, the file is tested, but not opened!

Result:

The path of selected soundfile or empty string



SELECT

This function selects an already opened soundfile, making it the current soundfile. The soundfile path or the zero based index can be used to identify the soundfile. If the function returns 0 the soundfile is selected and its name (full path) and parameters are stored in the variables CSF and CSFH. The open-counter of the soundfile is not changed.

Usage:

BSF SELECT path|index

Parameters:

path

The soundfile path.

index

The soundfile index (zero based).

Result:

0 for success or non-zero errorcode



TRUNCATE path|index; segexp [; aset]

The signal outside of the specified segment is removed from the soundfile. The segments stored in the audioset aset (if specified) are updated (deleted or shifted) if a valid aset is specified.

Usage:

path

The soundfile path.

index

The soundfile index (zero based).

segment

The segment expression for the remaining signal.

aset

The reference of audioset linked to soundfile path.

Result:

0 for success or non-zero errorcode

Array