Programmer Guide/Macro Library/BSF

File: BSF.STX, linked to library STX.LIB

See also: LOAD SOUNDFILE, UNLOAD SOUNDFILE,SFTRUNCATE, SEGMENT, WAVE items

Variables and items used by this library

name	type	description
@ParSoundFileNew	variable	default values for function NewDialog
@ListAudioSampleCode	variable	list of defined sample code keywords
@MaxAudioChannels	variable	maximum number of soundfile channels
@MaxAudioSRate	variable	maximum sampling rate in Hz
@ListAudioSRate	variable	list of standard sampling rate values
@TempDir	variable	directory for temporary files
BSFOpenList	table item	list of open soundfiles (only for BScript applications); this table is used by the functions Open, Close and CloseAll
SoundFileList	variable	name of the shared soundfile table item (see BSTXIni); the following information is stored in the table fields: File = full path SRate = sampling rate in Hz Channels = number of channels Length = signal length in seconds Used = open-counter Code = sampling code Mode = accesss mode Because the table is shared between shells, the LOCK/UNLOCK methods should be used to access the table. Do not change table content!
AutoCloseSF	variable	if set to 1all soundfiles opened by a BScript application are closed when the script exits.
CSF	variable	full path of the selected (active) soundfile.
CSFH	variable	header parameters of the selected (active) soundfile. CSFH=srate nchannels nsamples code type accessmode

NewDialog

BSF NEWDIALOG [ srate [ ; nch ; code ]

Dialog to create a new soundfile.

argument	description	default
srate	Sampling rate in Hz	last dialog value
nch	Number of channels.	last dialog value
code	Signal sample size (number of bits) and code.	last dialog value
RESULT	description
path	The full pathname of the created soundfile.
empty string	If the dialog was canceled or the creation fails.

Notes

• This function uses a two step dialog. In the first the soundfile name is selected. The second is used to select the soundfile parameters.
• The new soundfile is always created using the Windows WAVE format.
• On return, the soundfile is created but not opened.

OpenDialog

BSF OPENDIALOG

Dialog to open an existing soundfile.

RESULT	description
path	The full pathname of the selected soundfile.
empty string	If the dialog was canceled or the soundfile check fails.

Notes

• The dialog can open soundfiles in the Windows WAVE and the S_TOOLS 5 format.
• On return, the soundfile is checked (existence, format) but not opened.

Open

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

Create and/or open a sound file.

argument	description	default
path	Path of the sound file to be opened or created. Note: If the asterisk * is used for path, an unique sound file is created in the temp. directory (@TempDir).
mode	CREATE → Create a new sound file. If the file path exists, it is replaced by the new sound file. READ → Open an existing sound file for readonly-access. WRITE → Open a sound file for read- and write-access. The file is created if it do not exist! AUTO → Open a sound file and select the access type automatically (try read/write first and than readonly).	WRITE
srate	Sampling rate in Hz.	44100
nch	Number of channels.	1
code	Signal sample size (number of bits) and code. PCM8, PCM16, PCM24, PCM32 → 8/16/24/32 bit integer twos-complement FLOAT → 32 bit IEEE floating point	PCM16
type	File format. WAVE → Windows WAVE format (Microsoft) ST5 → S_TOOLS 5 format (ISF) BINARY → plain binary file; may contain a unknown offset-byte header	WAVE
offset	The size of the header of a plain binary sound file.	0.
RESULT	description
0	The sound file was successfully selected, opened or created.
≠ 0	It is not the case that the sound file was successfully selected, opened or created. -2 → can not assign unique tempfile name -3 → sampling rate out of range -4 → number of channels out of range -5 → header size of binary-files must be greater/equal 0 otherwise → a STx error code

Notes

• If a sound file is already opened, it is selected and its open-counter is incremented. The variables CSF and CSFH contain the full path and the header parameters of the sound file.
• If a sound file is opened the first time, the open-counter is set to 1.
• This function updates the shared sound file table (SoundFileList) and the table BSFOpenList (if called in a BScript application)
• The arguments srate, nch, code and type are only used if a new sound file is created (mode equals CREATE, WRITE or AUTO) or if the type BINARY is used. If an existing sound file with a known header format is opened, these parameters are read from the sound file header.
• If a sound file of type BINARY is opened, the sound file parameters srate, nch and code must always be specified, because the format and content of the (optional) header of such files is not known. The header of binary files must be located at the file begin and must consist of offset (≥ 0) bytes. If a binary file is created, no header is written and offset must be 0.

Close

BSF CLOSE path [ ; del ]
BSF CLOSE index [ ; del ]

Decrement open-counter of the soundfile and close it, if the open-counter equals zero.

argument	description	default
path	Path of the soundfile to be closed.
index	Zero based index of the soundfile (see Select).
del	Delete flag. If this flag is set to 1 (or yes) and the specified soundfile is closed by this function, the soundfile and all corresponding metadata files are deleted.	0
RESULT	description
0	Success.
≠ 0	Failed. The return value is a STx error code.

Notes

• First the open-counter of the specified soundfile is decremented. If the open-counter equals zero, the soundfile is closed and (optional) deleted.
• This function updates the shared soundfile table (SoundFileList) and the table BSFOpenList (if called in a BScript application).
• To really close a soundfile the number of CLOSE calls must be equal to the number of OPEN calls for this soundfile.

CloseAll

BSF CLOSEALL

Close all soundfiles opened by a BScript application. This function is automatically called at the end of the script execution if the variable AutoCloseSF equals 1.

RESULT	description
0	Success. All soundfiles are closed.
≠ 0	Failed, some soundfiles are still open. The return value is a STx error code.

Select

BSF SELECT path|index

Select (activate) the specified soundfile.

argument	description	default
path	Path of the soundfile to be selected.
index	Zero based index of the soundfile to be selected.
RESULT	description
0	Success.
≠ 0	Failed. The return value is a STx error code.

Notes

• To select a soundfile, it must be open.
• After a successful soundfile selection, the variables CSF and CSFH contain the full path and the header parameters of the soundfile.
• This function do not change the open-counter of a soundfile.
• Some commands (e.g. NEW WAVE or SEGMENT) are using the selected (activated) soundfile.

Truncate

BSF TRUNCATE path|index ; segexp [ ; afileref ]

Truncate the specified soundfile. Remove the signal outside the range specified by segexp from the soundfile.

argument	description	default
path	Path of the soundfile to be truncate.
index	Zero based index of the soundfile to be truncated (see Select).
segexp	A segment expression (see SEGMENT) specifying the remaining signal range.
afileref	A reference to the AFile element of the current project, containing the metadate (segments, etc.) of the specified soundfile (see BDataSet). If afileref is specified, the segment addresses are updated and segments addressing removed signal parts are deleted.
RESULT	description
0	Success.
≠ 0	Failed. The return value is a STx error code.