- 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.
|
