BSF - Soundfile Handling

From STX Wiki
< Programmer Guide‎ | Macro Library
Revision as of 12:12, 19 September 2018 by Jw (talk | contribs) (→‎Open)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search
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.