BSF

From STX Wiki
Jump to navigationJump to search
  • 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 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

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 path ; segexp [ ; afileref ]

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.

Navigation menu

Personal tools