Programmer Guide/Macro Library/BSF

• File: BSF.STX, linked to library STX.LIB
• Title: soundfile handling

---

Content

NewDialog · OpenDialog · Open · Close · CloseAll · Select · Truncate

See also

command LOAD SOUNDFILE,

command SFTRUNCATE

Variables and items used by this library

name	type	description
@ParSoundFileNew	global variable	default values for function NewDialog
@ListAudioSampleCode	global variable	list of defined sample code keywords
@MaxAudioChannels	global variable	maximum number of soundfile channels
@MaxAudioSRate	global variable	maximum sampling rate in Hz
@ListAudioSRate	global variable	list of standard sampling rate values
@TempDir	global 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	shell 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	shell variable	close all soundfiles opened by a BScript application.
CSF	shell variable	full path of the selected (active) soundfile.
CSFH	shell 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 the 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 soundfile.

argument	description	default
path	Path of the soundfile to be opened or created. Note: If the asterisk * is used for path, an unique soundfile is created in the temp. directory (see @TempDir. In this case, the argument mode is ignored.
mode	CREATE → Create a new soundfile. If the file path exists, it is replaced by the new soundfile. READ → Open an existing soundfile for readonly-access. WRITE → Open a soundfile for read- and write-access. The file is created if it do not exist! AUTO → Open a soundfile 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 soundfile.	0.
RESULT	description
0	The soundfile was successfully selected, opened or created.
≠ 0	Failed. -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 soundfile 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 soundfile.
• If a soundfile is opened the first time, the open-counter is set to 1.
• This function updates the shared soundfile 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 soundfile is created (mode is WRITE or AUTO) or if the type BINARY is used. If an existing soundfile with a known header format is opened, these parameters are read from the soundfile header.
• If a soundfile of type BINARY is opened, the soundfile 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 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 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 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.