The current chapter describes how to manage workspaces, i.e a set of files and thier description. Then it describes how to use the Graphical User Interface (GUI) and the Command-line User Interface (CLI).
A workspace is a manager of a set of files and of manually defined references. Several workspaces can be created but only one at a time is enabled when using SPPAS. All the features of SPPAS are using such currently enabled workspace.
A workspace is described in a configuration file into the folder workspaces
of the SPPAS package. This file is made of the name of the workspace followed by the extension .json
. It includes all properties of a workspace that are described here.
This configuration file can be copied into any other directory and re-imported into SPPAS.
A workspace is managing a set of files. Each time a file is added into the currently selected workspace, its root
and its path
are extracted and stored into a tree-like architecture.
The data are structured as follow:
For example, when adding the file /sppas/samples/samples-eng/oriana1.wav
into the workspace, the following next actions will be performed:
/sppas/samples/samples-eng/is added,
/sppas/samples/samples-eng/oriana1is added into the path,
/sppas/samples/samples-eng/oriana1.wavis added into the root. Several properties of the file are also stored, including its size or the date of modification.
When SPPAS is creating a new file - like when annotating automatically, the filename is automatically added into the workspace. For example, when the automatic annotation Fill in IPUs
has finished, the newly created file /sppas/samples/samples-eng/oriana1.xra
is added into the workspace:
/sppas/samples/samples-eng/is already existing so it’s not added,
/sppas/samples/samples-eng/oriana1is not added into the path because it’s also already existing,
/sppas/samples/samples-eng/oriana1.xrais added into the root.
All files sharing the same root are then stored in the same place in the tree because there’re sharing properties: they are all related to the same recording. The only difference between files sharing the same root are:
Notice that a pattern:
-;
Thanks to this new management of files, the patterns used by the automatic annotations are not fixed anymore. Both the input and output patterns of the annotations can be modified at the time of configuring the annotations.
The second advantage of such management of files into a workspace is to add all files of a corpus only once into a workspace and to save it. It is then ready-to-use each time SPPAS is started.
To summarize, the file /sppas/samples/samples-eng/oriana1-token.TextGrid
will be represented as follow:
/sppas/samples/samples-eng/is the path
/sppas/samples/samples-eng/oriana1is the root
/sppas/samples/samples-eng/oriana1-token.TextGridis the filename, in which: -
-tokenis the pattern, -
.TextGridis the extension.
The workspace is also managing the state of each of these items: checked or not for filenames, checked/at least one checked/not checked for roots or paths.
The references
are information that can be associated to files.
There are 3 different types of references: STANDALONE, SPEAKER and INTERACTION. Each of them corresponds to an annotation type. The annotations of both SPEAKER and INTERACTION type require to associate roots with these references.
Each reference can contain a list of attributes with an identifier key to define them, a value and its type, and a description. Here is an example of a reference Oriana
of type SPEAKER with its list of attributes in the form key: values (type)
:
It is recommended to use only us-ascii characters and no whitespace for the key.
Roots and references should be associated. In the previous example, it could allow to declare the list of files related to a given speaker. In that example, the reference Oriana
should be associated to the roots: /sppas/samples/samples-eng/oriana1
and /sppas/samples/samples-eng/oriana2
.
In the specific case of interactions, a reference of the interaction has to be created and associated to the roots of the filenames.
The definition of such references, and their link to the corresponding roots allow to perform an elaborated way to check files of a workspace. It’s very easy for example to check all files with file extension .wav of female
gender more than 30 years old.
A command-line user interface (CLI) is a means of interacting with a computer program where the user issues commands to the program in the form of successive lines of text (command lines). Command-line interfaces provide a more concise and powerful means to control the program than the GUI.
Operating system command line interfaces are called a command-line interpreter, command processor or shell. It displays a prompt, accept a command line
typed by the user terminated by the Enter key, then execute the specified command and provide textual display of results or error messages. When a shell is active a program is typically invoked by typing its name followed by command-line arguments (if any).
Such CLI programs are located in the bin
folder of the sppas
directory of the package. All these programs are written with the programming language Python and are compatible with version 3.4+.
Installing Python is then the only required other program in order to work with SPPAS CLI except the alignment.py
program which requires either Julius CSR or HVite (see installation instructions).
It is usual for a program to be able to display a brief summary of its parameters. Each program included in SPPAS provides its usage by using the option --help
, as for example:
prompt> python .\sppas\bin\trsconvert.py --help
usage: trsconvert.py [files] [options]
... a program to export annotated files.
optional arguments:
-h, --help show this help message and exit
--quiet Disable the verbosity
--debug Highest level of verbosity
Files:
-i file Input annotated file name.
-o file Output annotated file name.
Options:
-n value Number of a tier (use as many -n options as wanted). Positive
or negative value: 1=first tier, -1=last tier.
-t tiername Name of a tier (use as many -t options as wanted).
This program is part of SPPAS version 2.0. Copyright (C) 2011-2019 Brigitte
Bigi. Contact the author at: contact@sppas.org
In most of the programs, there is an option -i
for the input file. There’s no specific constraint on this file name. For example, the following program will execute the Momel automatic annotation:
python .\sppas\bin\momel.py -i .\samples\samples-eng\ENG_M15_ENG_T02.PitchTier
With this option -i
, a name of an output file can be given with the option -o
; if not, the main part of the result is printed on the standard output.
In several programs, an option -I
can also be available to execute the program, and several files can be processed with this option. Moreover, there is some flexibility in file names with this option. SPPAS will search for the appropriate file from the given file name. For example, the next commands will proccess the same:
python .\sppas\bin\intsint.py -I .\samples\samples-eng\ENG_M15_ENG_T02.wav
python .\sppas\bin\intsint.py -I .\samples\samples-eng\ENG_M15_ENG_T02.PitchTier
python .\sppas\bin\intsint.py -I .\samples\samples-eng\ENG_M15_ENG_T02-momel.xra
With the option -I
, the name of the output file is fixed and can’t be changed. For example, the previous example will create a file with name .\samples\samples-eng\ENG_M15_ENG_T02-intsint.xra
. An option -e
allows to choose the extension of the file, .xra is the default one.
The options to manage input/output files can be summarized as follow:
Files (manual mode):
-i file An input file.
-o file Output file name (optionnal).
Files (auto mode):
-I file Input file (append).
-e .ext Output file extension. One of: .xra .TextGrid .eaf
.csv .mrk .txt .stm .ctm .lab .mlf .sub .srt .antx
.arff .xrff
This program allows to:
Once the installation is completed - including wxpython, the GUI feature is enabled. Do not launch the GUI of SPPAS if the installation is not finished, i.e. launch the setup first: see the tutorial series 2 and to follow instructions.
Once the SPPAS package is opened in the File Explorer, double-click on the sppas.bat
file.
In recent versions of Windows (e.g. 10), the first time you try to run SPPAS you may get a window with title Windows protected your PC
and the following message: Windows SmartScreen prevented an unrecognized app from starting. Running this app might put your PC at risk. More info
. Click More info
message and then Run anyway
button. The file will now run SPPAS, and you will now no longer get a Windows protected your PC prompt when you run this specific file next time. This warning message comes from the fact that SPPAS is a free software and we did not paid to Microsoft commercial fees which would remove the Unknown Publisher
warnings.
Once the SPPAS package is opened in the Finder, double-click on the sppas.command
file.
The first time you try to run SPPAS you may get a message: sppas.command can’t be opened because it is from an unidentified developer.
. This warning message comes from the fact that SPPAS is a free software and we did not paid to Apple commercial fees. The solution is to run SPPAS with a right click (alt-click) on sppas.command file. This time you will get a message: sppas.command is from an unidentified developer. Are you sure you want to open it?
Then click on Open
. It will also now work each time you run it.
Once the SPPAS package is opened in the File Explorer, double-click on the sppas.command
file. Either, open a terminal and run it. Last solution is to directly execute sppas/bin/sppasgui.py
.
Both the main windows and a Log window
will open. The main frame is made of a menubar at top, a main content in the middle and buttons for actions at bottom.
Most of the existing/incoming tutorials are explaining how to access features of SPPAS with this GUI. This chapter only summarizes some of them.
The top menu allows to open various pages like Files
, Annotate
or Analyze
. There are 2 ways to browse through the items of the menu: with the mouse or with the keyboard. To open a page with the mouse, just click on the item button in the menubar. To open a page with the keyboard, under Windows, press CTRL and under MacOS, press COMMAND. Click left-right arrows to navigate to the previous/next page. Use up-arrow to go to the 1st page and Down-arrow to the last page. Use CTRL+F
/COMMAND+F
to go to the Files
page.
To change colors and fonts, click the Settings
icon at bottom. These settings are saved in a file which is used each time SPPAS is executed.
The About
action button allows displaying information about SPPAS: author, license, a link to the web site, etc.
The home page shows a welcome message and gives a quick acess to a set of external links. Clicking on the buttons will open the default web-browser of the OS to this link.
The links are pointing to:
The page Files
is dealing with the workspaces (see the previous section about workspaces).
A column at left with green buttons contains a list of buttons to perform actions related to the workspaces then the list of existing ones.
The actions to perform are:
Import from: select a workspace file (.wjson) somewhere on the computer and add it into the SPPAS workspaces directory.
Export to: save the currently enabled workspace somewhere in the computer
Pin & Save: The currently selected workspace is saved. If the currently selected workspace is
Blank, clicking this action will ask for a workspace name and create it (
Pin), then select it.
Rename: change the name of the currently selected workspace. Can’t be applied on the
Blankworkspace.
The list of workspaces allows to select a workspace among the existing ones or to work with the Blank
one (default).
The files area with a pinky color displays the tree of files of the currently selected workspace, and a toolbar with action buttons.
The actions to perform are:
Add: add new files into the workspace
Remove checked: remove the checked files of the workspace
The References
area with a blue color displays the tree of references of the currently selected workspace, and a toolbar with action buttons.
The actions to perform are:
Create: Open a dialog to ask for a name and the reference type among: STANDALONE, INTERACTION, SPEAKER. It then creates the corresponding reference and add it to the workspace
Edit: Open a dialog to delete, add or modify the attributes of the checked references.
Delete: Definitively delete the checked references. There’s no way to recover them if needed.
Between the files and references, there’s a column with action buttons. The actions to perform are related to files:
Delete checked: remove the checked files of the workspace and delete them of the disk. Actually, there are moved and renamed into the trash of SPPAS. To recover a mistaken deleted file, use your OS explorer.
or to link files and references:
This page allows annotating checked files of the currently enabled workspace.
The automatic annotation is a 5-steps process:
powerfulthan others, some are more
sharable…
Search for IPUsor
Face detection. But some annotations are requiring linguistic resources like a lexicon (Text Normalization), a dictionary (Phonetization), etc. This step allows to choose the language among the list of installed ones.
Let’s gobutton to launch the automatic annotation process, and wait!
The previously saved reports are listed in the column at right of the page. Click the button Show report
to display the content of the checked one.
This page is a merge of the DataFilter
, the DataStats
and the DataRoamer
of the previous GUI version… with new features added.
It allows to display a summary of each file: either audio or annotated files can be opened and analyzed. The following analyses can be performed:
simpleor the "relation one;
This page is a merge the IPUScriber
and the Visualizer
of the previous GUI version… with new features added.
It allows to annotate manually and to view files in a timeline. The features video
is required to play a video file and the feature audioplay
is required to play an audio file.
This editor is very useful to play several media at a time synchronously.
The convert page allows to export the checked annotated files of the workspace in any of the supported file format.
The displayed table indicates all the format capabilities, including:
Point;
Interval.
{ | }system to parse the alternative tags and = for scores.
Installing plugins is a very useful solution to extend the features of SPPAS. Several plugins are available for download in the main site of SPPAS. The plugins of SPPAS are installed in a folder with name plugins
in the main directory of the SPPAS package.
To install a new plugin, simply follow this workflow:
Pluginthen click on the
Installbutton of the toolbar.
To delete a plugin, click on the Delete
button of the toolbar. Choose the plugin in the given list then click on the OK
button. Notice that the plugin is definitively deleted of the disk.
To execute a plug-in, check the file(s) of your current workspace in the File page, then, click on the icon of the plug-in and follow instructions of the plugged program.