Programmer Guide/Macro Library/BSF: Difference between revisions

From STX Wiki
Jump to navigationJump to search
m (1 revision: Initial import)
No edit summary
Line 1: Line 1:
{{DISPLAYTITLE:{{SUBPAGENAME}}}}__NOTOC__
*File: BSF.STX, linked to library STX.LIB
*Title: soundfile handling


{{DISPLAYTITLE:{{SUBPAGENAME}}}}

==BSF==


This macro implements a function package for dealing with sound files.
:{|class="keinrahmen"
|[[#NewDialog|NewDialog]] ||—
|[[#OpenDialog|OpenDialog]]
|-
|[[#Open|Open]] ||—
|[[#Close|Close]] ||—
|[[#CloseAll|CloaseAll] ||—
|[[#Select|Select]] ||—
|[[#Truncate|Truncate]]
|}



This library uses the following global variables and items
==CLOSE==
{|class="einrahmen"
 
!name !!type !!description
Decrements the open-counter of the sound file and closes it if the counter is <code>0</code>. The argument <var>path</var>|<var>index</var> is used to select the sound file. If the argument delete is set to <code>1</code> the sound file is deleted after closing.
|@ParSoundFileNew ||global variable ||default values for function NewDialog
 
|@ListAudioSampleCode ||global variable ||list of defined sample code keywords
A sound file can only be closed if it is not in use (e.g. by a wave- or a spu-item). If a wave file addresses this sound file then the wave file must be deleted before closing the sound file. If a sound file was opened more than once, the same number of close-calls must be used to really close the sound file.
|@MaxAudioChannels ||global variable ||maximum number of soundfile channels
 
|@MaxAudioSRate ||global variable ||maximum sampling rate in Hz
=====Usage:=====
|@ListAudioSRate ||global variable ||list of standard sampling rate values
 
|@TempDir ||global variable ||directory for temporary files
<code>BSF CLOSE [ <var>path</var>|<var>index</var> [ ; <var>delete</var> ]]</code>
|BSFOpenList ||table item ||list of soundfiles opened with <code>BSF OPEN</code><BR>only used for BScript applications
 
|SoundFileList ||shell variable ||name of the shared soundfile table item<BR>see [[../BSTXIni|BSTXIni]]
=====Parameters:=====
|}
 
==NewDialog==
;<var>path</var>
;<code>BSF NEWDIALOG [ <var>srate</var> [ ; <var>nch</var> ; <var>code</var> ]</code>: New soundfile dialog.
 
{|class="einrahmen"
:The sound file path.
!argument !!description !!default
 
|-
;<var>index</var>
|<var>type</var>
 
|Selects the action to perform:<BR>
:The zero-based sound file index.
<code>LOAD</code> or <code>OPEN</code> &rarr; open existing file<BR>
 
<code>SAVE</code> or <code>NEW</code> &rarr; create new file
;<var>delete</var>
|<code>OPEN</code>
 
|-
:A flag indicating if the sound file should be deleted. The following values are supported:
|<var>title</var>
 
|The caption of the dialog window.
:<code>0</code> Do not delete the sound file (this is the default).
|<code>Select File</code>
 
|-
:<code>1</code> Delete the sound file.
|<var>file</var>
 
|The default file or directory.
=====Result:=====
|current directory
 
|-
<code>0</code> for success or non-zero errorcode
|<var>ftype1</var> ...
 
|Each <var>ftype</var> argument defines one entry of the filetype-combobox of the dialog.<BR>

Each filetype is defined by the string <code><var>extension</var>=<var>description</var></code>.<BR>
==CLOSEALL==
Example: <code>WAV=wave files</code><BR>
 
If a <var>ftype</var> argument is the name of a (simple) table item, each entry of the table defines a filetype.
Close all soundfiles opened by a script application. This function is called if the variable AUTOCLOSESF is set to 1 during script execution.
|-
 
!RESULT !!description
=====Result:=====
|-
 
|<var>path</var> ||The full pathname of the file to be opened or created.
0 for success or non-zero errorcode
|-
 
|''empty string'' ||If the dialog was canceled.
 
|}
 
;See also:

==FileCommands==
==NEWDIALOG==
;<code>BUTIL COPYFILE <var>src</var> ; <var>dst</var></code>: Copy file.
 
;<code>BUTIL MOVEFILE <var>src</var> ; <var>dst</var></code>: Copy file.
Shows a dialog to select the sound file path and the parameters and creates the file. The arguments (if present and valid) are used as default values for the sound file parameters. The created sound file is not opened!
;<code>BUTIL DELETEFILE <var>src</var></code>: Copy file.
 
{|class="einrahmen"
=====Usage:=====
!argument !!description !!default
 
|-
<code>WDIALOG [srate; channels; code]</code>
|<var>src</var>
 
|The file to copy, move (rename) or delete.
=====Parameters:=====
|
 
|-
;<var>srate</var>
|<var>dst</var>
 
|The target file or directory for copy or move (rename)
:The sampling rate in Hz.
|
 
|-
;<var>channels</var>
!RESULT !!description
 
|-
:The number of channels.
|<code>0</code> ||success
 
|-
;<var>code</var>
|<var>rc</var> ||The non-zero error code if the command has failed.
 
|}
:The sample code (<code>PCM8</code>|<code>PCM16</code>|<code>PCM24</code>|<code>PCM32</code>|<code>FLOAT</code>).
;See also:
 
==DirectoryDialog==
=====Result:=====
;<code>BUTIL DIRECTORYDIALOG [ <var>title</var> ; <var>path</var> ; <var>restore</var> ; <var>sdmode</var> ; <var>sdvalue</var> ]</code>:
 
;<code>DIRECTORYDIALOG [ '<var>title</var>' [ '<var>path</var>' '<var>restore</var>' '<var>sdmode</var>' '<var>sdvalue</var>' ]</code>: Dialog to select a directory.
The path of created sound file or empty string
{|class="einrahmen"
 
!argument !!description !!default

|-
==OPEN==
|<var>title</var>
 
|The caption of the dialog window.
The macro <code>BSF OPEN</code> creates and/or opens a sound file. The function returns <code>0</code> if the sound file was opened/created. In this case the sound file is made to the current sound file and its name (full path) and parameters are stored in the variables <code>CSF</code> and <code>CSFH</code>. If a sound file is already opened, it is only selected and the open-counter is incremented. See Shell Environment for detailed information about <code>CSF</code> and <code>CSFH</code>.
|<code>Select Directory</code>
 
|-
{|
|<var>path</var>
|The default directory.
|current directory
|-
|<var>restore</var>
|<code>no</code> or <code>0</code> &rarr; do not restore current directory<BR>
<code>yes</code> or <code>1</code> &rarr; restore current directory
|<code>no</code>
|-
|<var>sdmode</var>
|<code>no</code> or <code>0</code> &rarr; do not display the '''subdirectories''' checkbox<BR>
<code>yes</code> or <code>1</code> &rarr; display the '''subdirectories''' checkbox
|<code>no</code>
|-
|<var>sdvalue</var>
|Initial state of the '''subdirectories''' checkbox: <code>off</code> (=<code>0</code>) or <code>on</code> (=<code>1</code>)
|<code>off</code>
|-
!RESULT !!description
|-
|<var>path</var> ||If <var>sdmode</var> equals <code>no</code> &rarr; The full pathname of the selected directory.
|-
|<var>path;sdvalue</var> ||If <var>sdmode</var> equals <code>yes</code> &rarr; The full pathname of the selected directory and the value of the '''subdirectories''' checkbox (<code>0</code> or <code>1</code>).
|-
|''empty string'' ||If the dialog was canceled.
|}
;See also:
==GetDirectory==
;<code>BUTIL GETDIRECTORY <var>path</var></code>: Check if the directory exists.
{|class="einrahmen"
!argument !!description !!default
|-
|<var>path</var>
|The directory to be checked.
|
|-
!RESULT !!description
|-
|<var>path</var> ||The fullpath of the specified directory.
|-
|<code>$@root</code> ||The {{STX}} installation directory if the specified directory was not found.
|}
;See also:
==Directory==
;<code>BUTIL DIRECTORY [ <var>path</var></code> ]: Select directory and/or get full pathname of working directory.
{|class="einrahmen"
!argument !!description !!default
|-
|<var>path</var>
|The directory to be selected.
|
|-
!RESULT !!description
|-
|<var>path</var> ||The fullpath of the selected/current {{STX}} working directory.
|}
;See also:
==GetSwitch==
;<code>BUTIL GETSWITCH <var>val</var> ; <var>defval</var></code>: Verify and return boolean value.
{|class="einrahmen"
!argument !!description !!default
|-
|<var>val</var>
|The value to check.<BR>Valid values are: <code>0=no=false=off, 1=yes=true=on</code>
|
|-
|<var>defval</var>
|The default value to be used if <var>val</var> is invalid. The same values as for <var>val</var> can be specified.
|0
|-
!RESULT !!description
|-
|<code>0</code> or <code>1</code>
|
|}
;See also:
==GetKeyWord==
;<code>BUTIL GETKEYWORD <var>val</var> ; <var>defval</var> ; <var>keyword1</var> ...</code>: Verify keyword and return keyword value.
{|class="einrahmen"
!argument !!description !!default
|-
|<var>val</var>
|The value to check.
|
|-
|<var>defval</var>
|The default value to be returned if <var>val</var> is not a keyword.
|
|-
|<var>keyword1</var> ...
|Blank seperated list of keywords.
|
|-
!RESULT !!description
|-
|<var>keyword</var> ||If <var>val</var> is a keyword or an abbreviation of a keyword.
|-
|<var>defval</var> ||otherwise
|}
;See also:
==GetKeyIndex==
;<code>BUTIL GETKEYINDEX <var>val</var> ; <var>defval</var> ; <var>keyword1</var> ...</code>: Verify keyword (or index) and return keyword index.
{|class="einrahmen"
!argument !!description !!default
|-
|<var>val</var>
|The value to check.
|
|-
|<var>defval</var>
|The default value to be returned if <var>val</var> is not a keyword.
|
|-
|<var>keyword1</var> ...
|Blank seperated list of keywords.
|
|-
!RESULT !!description
|-
|<var>keyindex</var> ||The zero based index of the matching keyword, if <var>val</var> is a keyword or an abbreviation of a keyword.
|-
|<var>defval</var> ||otherwise
|}
;See also:
==SelectTable==
;<code>BUTIL SELECTTABLE <var>table</var> <var>sel</var></code>: Select table entries.
{|class="einrahmen"
!argument !!description !!default
|-
|-
|<code>READ</code>
|<var>table</var>
|The file must exist and is opened for read only access.
|Name of a table item.
|
|-
|-
|<code>WRITE</code>
|<var>sel</var>
|The file is opened for read/write access and created if it does not exist.
|The select command:<BR>
<code>ALL</code> &rarr; select all entries<BR>
<code>TOGGLE</code> &rarr; toggle (invert) selection<BR>
<code>NONE</code> &rarr; clear selection, deseclect all entries
|
|-
|-
|<code>AUTO</code>
!RESULT !!description
|The mode <code>READ</code> or <code>WRITE</code> is chosen automatically depending on the file's status.
|-
|-
|<code>CREATE</code>
|<var>nsel</var> ||Number of selected table entries.
|A new file is created even if the specified file exists. If an automatic file name is requested (path equals '<code>*</code>'), the mode <code>CREATE</code> is always assumed. The arguments <var>srate</var>, <var>channels</var>, <var>code</var>, <var>type</var> and <var>offset</var> are only used if a new file is created.
|}
|}
 
;See also:
=====Usage:=====
 
<code>BSF OPEN <var>path</var> [; <var>mode</var>; <var>srate</var>; <var>channels</var>; <var>code</var>; <var>type</var>; <var>offset</var>]</code>
 
=====Parameters:=====
 
;<var>path</var>
 
:The sound file path or <code>*</code> for automatic file name (e.g. for temporary files).
 
;<var>mode</var>
 
:The access mode {<code>READ</code>|<code>WRITE</code>|<code>AUTO</code>|<code>CREATE</code>}. See above for more details.
 
;<var>srate</var>
 
:The sampling rate in Hz.
 
;<var>channels</var>
 
:The number of channels.
 
;<var>code</var>
 
:The sample code (<code>PCM8</code>|<code>PCM16</code>|<code>PCM24</code>|<code>PCM32</code>|<code>FLOAT</code>).
 
;<var>type</var>
 
:The file format (<code>ST5</code>|<code>WAVE</code>|<code>BINARY</code>).
 
;<var>offset</var>
 
:The size of the file header in bytes (for type=BINARY).
 
=====Result:=====
 
<code>0</code> for success or non-zero error code.
 

==OPENDIALOG==
 
Display a dialog to open an existing soundfile. If the function returns a path, the file is tested, but not opened!
 
=====Result:=====
 
The path of selected soundfile or empty string
 

==SELECT==
 
This function selects an already opened soundfile, making it the current soundfile. The soundfile path or the zero based index can be used to identify the soundfile. If the function returns 0 the soundfile is selected and its name (full path) and parameters are stored in the variables <code>CSF</code> and <code>CSFH</code>. The open-counter of the soundfile is not changed.
 
=====Usage:=====
 
<code>BSF SELECT <var>path</var>|<var>index</var></code>
 
=====Parameters:=====
 
;<var>path</var>
 
:The soundfile path.
 
;<var>index</var>
 
:The soundfile index (zero based).
 
=====Result:=====
 
0 for success or non-zero errorcode
 

==TRUNCATE path|index; segexp [; aset]==
 
The signal outside of the specified segment is removed from the soundfile. The segments stored in the audioset aset (if specified) are updated (deleted or shifted) if a valid aset is specified.
 
=====Usage:=====
 
;<var>path</var>
 
:The soundfile path.
 
;<var>index</var>
 
:The soundfile index (zero based).
 
;<var>segment</var>
 
:The segment expression for the remaining signal.
 
;<var>aset</var>
 
:The reference of audioset linked to soundfile path.
 
=====Result:=====
 
0 for success or non-zero errorcode
 
Array

Revision as of 16:17, 11 May 2011

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


NewDialog — OpenDialog
Open — Close — [[#CloseAll|CloaseAll] — Select — Truncate

This library uses the following global variables and items

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 soundfiles opened with BSF OPEN
only used for BScript applications 		SoundFileList shell variable name of the shared soundfile table item
see BSTXIni

NewDialog

BSF NEWDIALOG [ srate [ ; nch ; code ]
New soundfile dialog.
argument description default
type Selects the action to perform:

LOAD or OPEN → open existing file
SAVE or NEW → create new file

OPEN
title The caption of the dialog window. Select File
file The default file or directory. current directory
ftype1 ... Each ftype argument defines one entry of the filetype-combobox of the dialog.

Each filetype is defined by the string extension=description.
Example: WAV=wave files
If a ftype argument is the name of a (simple) table item, each entry of the table defines a filetype.

RESULT description
path The full pathname of the file to be opened or created.
empty string If the dialog was canceled.
See also

FileCommands

BUTIL COPYFILE src ; dst
Copy file.
BUTIL MOVEFILE src ; dst
Copy file.
BUTIL DELETEFILE src
Copy file.
argument description default
src The file to copy, move (rename) or delete.
dst The target file or directory for copy or move (rename)
RESULT description
0 success
rc The non-zero error code if the command has failed.
See also

DirectoryDialog

BUTIL DIRECTORYDIALOG [ title ; path ; restore ; sdmode ; sdvalue ]
DIRECTORYDIALOG [ 'title' [ 'path' 'restore' 'sdmode' 'sdvalue' ]
Dialog to select a directory.
argument description default
title The caption of the dialog window. Select Directory
path The default directory. current directory
restore no or 0 → do not restore current directory

yes or 1 → restore current directory

no
sdmode no or 0 → do not display the subdirectories checkbox

yes or 1 → display the subdirectories checkbox

no
sdvalue Initial state of the subdirectories checkbox: off (=0) or on (=1) off
RESULT description
path If sdmode equals no → The full pathname of the selected directory.
path;sdvalue If sdmode equals yes → The full pathname of the selected directory and the value of the subdirectories checkbox (0 or 1).
empty string If the dialog was canceled.
See also

GetDirectory

BUTIL GETDIRECTORY path
Check if the directory exists.
argument description default
path The directory to be checked.
RESULT description
path The fullpath of the specified directory.
$@root The STx installation directory if the specified directory was not found.
See also

Directory

BUTIL DIRECTORY [ path ]
Select directory and/or get full pathname of working directory.
argument description default
path The directory to be selected.
RESULT description
path The fullpath of the selected/current STx working directory.
See also

GetSwitch

BUTIL GETSWITCH val ; defval
Verify and return boolean value.
argument description default
val The value to check.
Valid values are: 0=no=false=off, 1=yes=true=on
defval The default value to be used if val is invalid. The same values as for val can be specified. 0
RESULT description
0 or 1
See also

GetKeyWord

BUTIL GETKEYWORD val ; defval ; keyword1 ...
Verify keyword and return keyword value.
argument description default
val The value to check.
defval The default value to be returned if val is not a keyword.
keyword1 ... Blank seperated list of keywords.
RESULT description
keyword If val is a keyword or an abbreviation of a keyword.
defval otherwise
See also

GetKeyIndex

BUTIL GETKEYINDEX val ; defval ; keyword1 ...
Verify keyword (or index) and return keyword index.
argument description default
val The value to check.
defval The default value to be returned if val is not a keyword.
keyword1 ... Blank seperated list of keywords.
RESULT description
keyindex The zero based index of the matching keyword, if val is a keyword or an abbreviation of a keyword.
defval otherwise
See also

SelectTable

BUTIL SELECTTABLE table sel
Select table entries.
argument description default
table Name of a table item.
sel The select command:

ALL → select all entries
TOGGLE → toggle (invert) selection
NONE → clear selection, deseclect all entries

RESULT description
nsel Number of selected table entries.
See also
Retrieved from "https://mediawiki.kfs.oeaw.ac.at/stx/docs/wiki/index.php?title=Programmer_Guide/Macro_Library/BSF&oldid=4922"

Navigation menu

Personal tools