BDataSet - Project Document and Project Management

From STX Wiki
< Programmer Guide‎ | Macro Library
Revision as of 14:50, 28 August 2023 by Toni (talk | contribs) (→‎OpenAutoAFile)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigationJump to search
File: BDataSet.STX, linked to library STX.LIB
Parent class: BXMLDoc
See also: BSTXIni, DataSetCmd

This class implements the project document. The project document is the global database available to all STx applications and scripts and contains all data and links of the current project. The content of the project document is stored in a XML file item The programmer must not create or destroy the project object because these functions are performed by the application startup and cleanup macros.

Never ever call the member functions CONSTRUCT, DESTRUCT or CLOSE!

At application startup a BDataSet instance is created and linked to the global project document which is created and managed by the STx master shell. The name of this instance is stored in the shell variable BDATASET. This object must be used to access the project document.

The class BDataSet is derived from the class BXMLDoc. Beware of using the base class functions, since they do not update the BDataSet member variables! No static commands are implemented by this class; a call to the macro BDataSet (e.g. bdataset save) will do nothing, returning an empty string.

Important note: A shell or a script should only access or change the content of the project document, while it is attached (locked). This is very important, because the project document can be (and is often) accessed by all running shells (e.g. STx applications or scripts). A code section accessing the project content should start with $bdataset attach and end with $bdataset detach.

Example for using attach/detach
 // first attach call - lock project document and save current xml-position (pos1)
 $bdataset attach
 ... 
 //	second attach call - save xml-position (pos2)
 $bdataset attach
 ...
 // first detach call - restore xml-position pos2, project document remains locked!
 $bdataset detach
 ...
 //	second detach call - restore xml-position pos1 and unlock project document, 
 //	if the project document was changed by the code between first attach and second detach,
 // the message "DATASETCHANGED" is sent to all running shells
 $bdataset detach

Project File Management

Validate

Usage
$bdataset validate showmsg
showmsg
if set to 1 a message is displayed also if no invalid elements were detected; default: no message if no invalid elements were found
Result
number of invalid elements (0 for none)
Description
This function checks all elements (sound files, segments, ...) of the project for validity. If invalid elements are detected, they can be displayed and the user is asked if they should be deleted or not.

Save

Usage
$bdataset save [ path=* ; auto=0 ; pbh=* ]
path
project file path; if not specified or *, the last load/save path is used
auto
if set to 1 the user is not prompted with a yes/no dialog as to whether they want to save or not.
pbh
a progress dialog handle (see macro ProgressBox); use * if no progress box should be displayed
Result
0 for success or a non-zero error code
Description
This function saves the current project to the specified or last assigned project file. During the load process all necessary element validations and path conversions are performed. If the project is in mode linked also the segment metadata files of all linked sound files are updated.

Load

Usage
$bdataset load [ filepath ]
filepath
the path of the project file to be loaded; if not specified the last assigned path is used
Result
0 for success or a non-zero error code
Description
This function loads the specified or last assigned project file. During the load process all necessary path conversions, additional load operations of linked files and element validations are performed. The progress of the load process is display in a popup progress dialog.

Project Properties

IsNewFile

Usage
$bdataset isnewfile
Result
1 if the project file is new (not named and not saved) and 0 otherwise.

GetPath

Usage
$bdataset getpath
Result
the full path of the project file or an empty string

SetLink

Usage
$bdataset setlink mode
mode
0 (or no) to set project to not linked and 1 (or yes) to set it to linked
Result
0 if the selected mode was enabled and 1 if the function fails.
Description
This function change the project attribute AFile (attribute of the root-element STXDataSet).
  • AFile=Link: The project is in mode linked. The segment metadata are stored in STx metadata files, which are xml-files with the same pathname as the sound file and the filetype stxsm. The segment metadata files of sound file linked to the project are loaded/saved automatically, when the project is loaded/saved. The project file contains only links to the sound files of the project.
  • AFile is not assigned: The project is in mode not linked. All data of the project, including segment metadata, are stored in the project file. A project in this mode may contain multiple links to one sound file (e.g. to manage different segmentations of the same signal).

IsLinked

Usage
$bdataset islinked
Result
1 if the project is set to linked and 0 otherwise

SetRelativity

Usage
$bdataset setrelativity mode
mode
0 (or no) to disable the relative path feature and 1 (or yes) to enable it
Result
0 if the selected mode was enabled and 1 if the function has failed.
Description
This function can be used to enable/disable the relative path option. If the relative path option is enabled, for sound file which are in the same directory as the project file or in subdirectories the relative path is saved in the project. This feature is useful if the project should be copied to other places. The relativity state is saved in the attribute ARelative of the root element of the project. If this attribute has the value yes, relative sound file pathes are used, otherwise (ARelative) equals no or is not set) absolute pathes are used.

IsRelative

Usage
$bdataset isrelative
Result
1 if the project is set to relative sound file pathes and 0 otherwise

Audio Set Functions

AddASet

Usage
$bdataset addaset tag ; targetset ; id ; srate ; channels ; update
tag
the type off the new audio set; this can be ...
  • the name of an existing sound file to be added to the project
  • the keyword AFile or * to create (via dialog) a new soundfile and add it to the project
  • the keyword ASequence or Sequence to add a new sequence to the project
targetset
the set (folder) where the new audio set should be located; if set to *, the target is selected via a dialog
id
the unique id of the new audio set; if set to * an unique id is choosen automatically
srate
the sampling rate in Hz for a new soundfile or a sequence
channels
the number of channels for a new soundfile or a sequence
update
if set to 1 (or yes) the function DataSetCmd RefreshAll is called to refresh the project GUI
Result
if successful, the the reference (iref) of the added audio set if returned, otherwise an empty string
Description
This function adds an audio set (sound file or sequence) to the project.

AFileIsLinked

Usage
$bdataset afileislinked path
path
the path of the sound file to be tested
Result
1 if the sound file path is already linked to the project and 0 otherwise.
Description
This function tests if a sound file is already linked to the project or not. The check is performed only if the project is set to linked. For not linked projects the functions returns always 0.

SelectASet

Usage
$bdataset selectaset aset ; type
aset
the reference (iref or position) of an audio set or of an element inside an audio set (e.g. a segment)
type
assumed type of the audio set: AFile, Soundfile, ASequence, Sequence or * (default) if type is unknown
Result
0 if the audio set is selected and a non-zero error code otherwise
Description
This function selects the specified audio set. If the function was sussessful, the following member variables of the object $bdataset are assigned:
  • &asetPos: xml position of the audio set element
  • &asetTag: xml tag of the audio set element (AFile or ASequence)
  • &asetID: xml element id (value of attribute ID)
  • &asetSR: sampling rate in Hz (value of attribute SR)
  • &asetCH: number of channels (value of attribute CH)
  • &asetFile: sound file path (only if tag equals AFile)

GetASetInfo

Usage
$bdataset getasetinfo [ aset ; type ]
aset
the reference (iref or position) of an audio set or of an element inside an audio set (e.g. a segment)
type
assumed type of the audio set: AFile, Soundfile, ASequence, Sequence or * (default) if type is unknown
Result
an empty string for error or the available attributes of the selected audio set:
  • for sound files: Soundfile ; id ; sr ; ch ; filepath
  • for sequences: Sequence ; id ; sr ; ch
Description
This function retrieves information about the selected audio set. If arguments are specified, they are passed to the function SelectASet to select the audio set, before the audio set information is returned.

OpenAutoAFile

Usage
$bdataset openautoafile mode ; srate ; channels ; code ]
mode
  • 0 → replace the last created autofile
  • 1 → get last created autofile, file is replaced if srate or channels are different
  • 2 → create and add a new autofile
srate
sampling rate in Hz
channels
number of signal channels
code sample code (see command LOAD SOUNDFILE)
Result
'iref ; created' with:
  • iref: the audio set reference of the autofile
  • created: 1 if a new sound file was created and 0 if an existing sound file was opened
Description
This function creates/opens an temporary sound file and adds it to the project. Temporary sound files (autofiles) can be used to save results of signal processing/modification operations. All autofiles are deleted when the project is closed.

RemoveTmpSet

Usage
$bdataset removetmpset del ]
del
0 to copy the tmp-set and 1 to delete the tmp-set and all temporary sound files
Result
an empty string if the tmp-set was deleted and the name of an xml file item containing the tmp-set elements otherwise
Description
This function removes the tmp-set, this is the set element (folder) containing all temporary audio sets (autofiles), from the project. If the argument del is set to 1, the temporary sound files are deleted and the tmp-set is removed from the project. Otherwise, the tmp-set is copied to a new xml file item, which is returned to the caller, and than it is removed from the project, but the temporary sound files are not deleted.

RestoreTmpSet

Usage
$bdataset restoretmpset xmlfile ]
xmlfile
a xml file item containing the tmp-set to be restored; normally created with $bdataset removetmpset 0
Result
none (void)
Description
This function add the tmp-set contained in xml file item passed to the function to the project.

Audio Segment Functions

SelectASeg

Usage
:$bdataset selectaseg aset; aseg
aset
audio set reference (position or iref)
aseg
audio segment reference or id
Result
0 for success or a non-zero error code
Description
Selects the segment aseg of the audio set aset. This function calls SelectASet first to select the audio set. If the function succeeds, the current element of the xml project file is the selected segment.

EvalSegment

Usage
:$bdataset evalsegment aset; aseg; fmt
aset
audio set reference (position or iref)
asegid
audio segment reference, id or expression
fmtselect output format and time unit (see result)
Result
  • empty string on error
  • fmt=samples → 'beginsample endsample numberofsamples' (boundaries in samples, separated by blanks)
  • fmt=seconds → 'begintime endtime duration' (time values in seconds, separated by blanks)
  • fmt=segment → 'segmentexpression' (a valid segment expression for the specified segment)
Description
This function returns the boundaries of the specified segment or the segment expression in the selected format.
See also
command SEGMENT

SetSegment

Usage
$bdataset setsegment aset; asegid; asegexpr; attrname=attrvalue; ...
$bdataset setsegment aset; asegid; asegexpr; attrtable
aset
audio set reference (position or iref)
asegid
audio segment id
attrname=valuename
name and value segment attribute; multiple attribute assignments can be specified separated by semi-colons
attrtable
a simple table containing von attribute assignment (name=value) per line; Warning: This table is deleted after processing!
Result
0 for success or a non-zero error code
  • for positive error codes (>0) see command EMSG
  • -4 → invalid segment id asegid (for new segment)
  • -3 → bad segment expression asegexpr
  • -2 → bad segment address (aset and/or asegid)
  • -1 → cannot add segment to database (e.g. due to a duplicate name asegid)
Description
This functions creates a new segment asegid with the boundaries specified by asegexpr and assignes the specified attributes. If the segment with id asegid already exists, only the boundaries and attributes are updated.
  • To leave the boundaries of an existing segment (attributes P and L) untouched, set asegexpr to *.
  • To remove an attribute, leave the attribute value empty (attrname=).
  • Error and warning messages are written to the STx log-window.

GetSegment

Usage
$bdataset getsegment aset; aseg; attr1; ...
aset
audio set reference (position or iref)
aseg
audio segment reference or id
attr1, attr2, ...
keyword or name of requested attribute(s)
Result
The function returns the values of the requested attributes or an empty string on error. If more than one value is requested, the returned attribute values are separated by semi-colons.
Description
This functions retrieves attributes (properties) of the specified segment. The table below shows the possible values and keywords for the attribute argument(s).


attrX return value comment
id or name segment id attribute ID
iref segment reference (iref)
segment [unit] segment expression attributes P and L
position [unit] or
begin [unit]		 begin of segment attribute P
end [unit] end of segment attribute P and L
length [unit] segment length attribute L
channel [unit] channel assigned to segment attribute CH
attrname value of attribute attrname attribute names are case sensitive!

Note: The optional argument unit specifies the unit for time values. It can be samples (default), seconds, milliseconds (or ms) or hms

FindSegment

Usage
$bdataset findsegment first; aset ; asegid ; range ; attrexpr1 ; ...
$bdataset findsegment next; asegpos ; asegid ; range ; attrexpr1 ; ...
Result
position asegpos of first / next matching segment or empty string
Description
The find first/next function can be used to process audio segments in an interation loop. If a call to next fails (no more matching segments found), the position asegpos passed to function is cleared automatically. If an iteration loop is leaved before the last segment was processed, the reset variant must be called to clear the last saved position.
Usage
$bdataset findsegment all|directory; aset ; asegid ; range ; attrexpr1 ; ...
Result
For all a simple table containing the xml positions of all found segments is returned. For directory the function returns an extended table containing the id, begin, length and channel assignment (fields: ID, P, L and CH). If the function fails or no matching elements were found, it returns an empty string.
Usage
$bdataset findsegment reset; table|asegpos ; delete=0
Result
none (void)
Description
This function variant clears the position asegpos or the segments positions stored in table. If delete is set to 1 also the segments themselves are deleted. It must be called to reset the segment position if an iteration loop is left early and to reset positions of segments found by the all variant.
Arguments
aset
audio set reference (iref or position)
asegid
segment name (wildcard)
asegpos
segment element position
range
segment expression defining the search range (* = whole audio set)
attrexpr
an attribute compare expression (see SET xmlfileitem FIND)
table
a simple table with segment element positions (returned by ALL)
delete
1 if element(s) should be deleted on RESET, 0 otherwise

DialogSelectSegment

Usage
$bdataset dialogselectsegment title ; aset ; mode ; output
title
dialog capture, empty string to use default title
aset
audio set reference (iref)
mode
selection mode; single for one segment, multiple for multiple segments
output
return value(s); positioon = xml position of segment(s), iref xml reference (iref) of segment(s), id segment id
Result
  • empty string if failed/canceled
  • if mode = single → the specified return value as string
  • if mode = multiple → a simple table with one entry for each selected segment holding the specified output value as string
Description
This function displayes a dialog with a segment list of the specified audio set, where the user can select segment(s).

DialogEditSegment

Usage
$bdataset dialogeditsegment aset ; aseg ; segment ; channel ; title
aset
audio set reference (iref)
aseg
segment reference, segment id or * (for new segments)
segment
segment expression specifying both boundaries of segment or *
channel
channel of segment or 0 for all channels
title
dialog capture, empty string to use default title
Result
empty string if failed/canceled or id of changed/created segment
Description
This function implements a complex dialog to create new segments and to edit properties/attributes of segments.

CreateWave

Usage
$bdataset createwave aset ; aseg ; channels=* ; mode=single
aset
audio set reference (iref or position)
aseg
specifies the segment (begin and end) to be addressed by the created wave item
  • a segment reference (iref or position), a segment id or a segment expression
  • the character * can be used to address the signal of the whole sound file
  • the expression *length can be used to create a wave item that appends a signal of duration length to a sound file
channels
defines which channels of the audio set should be addressed by the created wave item
  • * or 0 for all channels
  • use keyword channels (or ch) to retrieve channel value from the attribute CH of the segment element
  • specify a channel number (1, 2, ..) or a list of blank separated channel numbers (e.g. 1 3 4)
mode
this argument is only used, if the specified audio set is a sequence (ASequence)
  • set mode to single if the signal is processed sequential
  • is the signal is accessed in a random way, set mode to multiple
Return
the created wave item (item id) or an empty string if the function fails
Description
This function creates a wave item which can be used to read, write or append a signal from/to an audio set of the current project. A wave item created by this function must be deleted by calling the member function DeleteWave. All wave items created by this member, are automatically deleted by the STx application management functions, when the shell exits.

CreateWaveEx

This function takes the same arguments and performs the same function as CreateWave. Only the result is different.

Result
the created wave item or a numeric error code

DeleteWave

Usage
$bdataset deletewave waveitem
waveitem
id of waveitem to be deleted
Result
no result (void)
Description
This function deletes the wave item and performs all necessary cleanup operations (e.g. delete assoziated items, close used soundfiles, etc.). Use this function only to delete wave items created with CreateWave/CreateWaveEx.

Uncommon Functions and Functions for internal use only

The following functions are not often used and not so important for user script programming. If you want to know more about these functions look at the comments in the source file BDataSet.stx


  • GetBaseDirecory(read: #filepath): used by member Save to verify the project file path


  • BackupSave: create a backup copy of the current project if backups are enabled; this function is called by the members Save/Load
  • BackupEmpty: empty backup directory - delete all backups
  • BackupLoad: display a list of available backups including options to restore selected backups


  • ImportXML(read: #filepath; #set=*; #id=*): import the content of a xml file into the project (e.g. merge projects)
  • ImportSD0(read: afileref=*): import segment metadata of the specified (selected) audio set; try all versions (stxsm/sd0/st5); this function is used to load segment metadata of linked projects
  • ExportSD0(read: afileref=* [xmlfile]): export segment metadata of the specified (selected) audio set; this function is used to save segment metadata of linked projects


  • SetSetting(read: #id; version; value): set the value of project setting '#id' in the STXDataSet/Settings element
  • GetSetting(read: #id; version): get the valud of project setting '#id' from STXDataSet/Settings element


  • GetWaveInfo(read: waveitem): retrieve all information associated to a wave item (created with member CreateWave)


  • MakeChannelList(read: nch|aset; withall): initialize a channel-list variable for dialogs (combobox)


  • GetReservedAttributes: returns a blank seperated list of all reserved attribute names
  • IsReservedAttribute(read: attrname): returns 1 if the argument attrname is the name a reserved attribute and 0 otherwise
  • GetAttributes(read: type table autoexclude excludelist): returns a list of all attributes assigned to elements of the specified; the whole project is scanned
  • DialogGetAttributes(read: type vlist): implements a dialog to select visible attributes of the selected element type (e.g. sets, segments, ...); returns a blank separated list of visible attributes


  • GetTemplateForCurrentTag: get the template assigned to the current element (or its parent if possible)


  • AttrListView: a special handler for attribute editors (controls a dialog via msg. handling and callback); used by some standard dialogs of the GUI
Retrieved from "https://mediawiki.kfs.oeaw.ac.at/stx/docs/wiki/index.php?title=Programmer_Guide/Macro_Library/BDataSet&oldid=10697"

Navigation menu

Personal tools