2. User interfaces
Introduction
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).
Workspaces
Overview
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.
Create and save a 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.
Files
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:
- a workspace contains a list of paths,
- each path contains the list of roots sharing this path,
- each root contains the list of filenames sharing this root.
For example, when adding the file
/sppas/samples/samples-eng/oriana1.wav
into the workspace, the
following next actions will be performed:
- the path
/sppas/samples/samples-eng/
is added, - the root
/sppas/samples/samples-eng/oriana1
is added into the path, - the filename
/sppas/samples/samples-eng/oriana1.wav
is 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:
- the path
/sppas/samples/samples-eng/
is already existing so it’s not added, - the root
/sppas/samples/samples-eng/oriana1
is not added into the path because it’s also already existing, - the filename
/sppas/samples/samples-eng/oriana1.xra
is 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:
- the extension (.wav, .mp4, .mkv, .xra, .TextGrid, …)
- the pattern (-ipus, -token, -phon, -palign, -lexm, -orepet, …)
Notice that a pattern:
- must start by the character
-
; - must contain at least 1 character.
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/oriana1
is the root/sppas/samples/samples-eng/oriana1-token.TextGrid
is the filename, in which: --token
is the pattern, -.TextGrid
is 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.
References
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)
:
- firstname: Oriana (str)
- gender: female (str)
- recorded_in: 2012 (int)
- L1: eng (str)
- L2: fra (str)
It is recommended to use only us-ascii characters and no whitespace for the key.
Associate files and references
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.
The Command-Line user Interface - CLI
Overview
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).
Usage
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
Arguments for input/output
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
preinstall.py
This program allows to:
- install external programs to enable some of the features of SPPAS – including the GUI;
- install linguistic resources for the supported languages;
- install resources required to enable some of the annotations.
The graphical user interface
Important
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.
Launch the GUI
Under Windows
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.
Under MacOS
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.
Under Linux
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
.
The GUI of SPPAS
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 main frame
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.
Home page
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 SPPAS home web site: https://sppas.org
- the in-line version of this documentation
- the in-line tutorials
- the frequently asked questions
- the home page of the author, including the whole list of publications related to SPPAS: https://sppas.org/bigi/
Files page
The page Files
is dealing with the workspaces (see the
previous section about workspaces).
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 computerPin & Save
: The currently selected workspace is saved. If the currently selected workspace isBlank
, 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 theBlank
workspace.
The list of workspaces allows to select a workspace among the
existing ones or to work with the Blank
one (default).
Files:
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 workspaceRemove checked
: remove the checked files of the workspace- Remove missing files of the workspace. The tree of paths/roots/files is explored and if a filename does not correspond to an existing file on the disk, it is removed of the workspace tree
- All files of the disk sharing the checked roots will be added to the workspace tree
References:
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 workspaceEdit
: 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.
Column of action buttons:
Between the files and references, there’s a column with action buttons. The actions to perform are related to files:
- Open the checked files with a text editor (under development)
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.- Check/uncheck all files
- Check only files matching some patterns.
or to link files and references:
- Associate the checked roots to the checked references
- Dissociate the checked roots of the checked references
Annotate page
This page allows annotating checked files of the currently enabled workspace.
The automatic annotation is a 5-steps process:
- Choose the output file format. All the automatic annotations are
creating files. Choosing the extension means to choose the format of the
resulting file. Some formats are more
powerful
than others, some are moresharable
… - Fix the language. Some annotations are language-independent, so they
don’t need a specific language resource, like
Search for IPUs
orFace 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. - Select and configure annotations. Click any of the STANDALONE, SPEAKER or INTERACTION button. It will change the page content in order to select the annotations SPPAS will perform and to configure them. Click the top arrow to come back to the main page.
- Perform the annotations. Click the
Let’s go
button to launch the automatic annotation process, and wait! - A procedure outcome report is displayed and saved in the logs folder of the SPPAS package.
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.
Analyze page
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:
- manage tiers: duplicate, remove, copy, move, …
- estimate distribution statistics on tiers;
- create new tiers with the filter systems, either the
simple
or the “relation one; - check if an audio file is compatible with the automatic annotations.
Editor page
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.
Convert page
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:
- Metadata: the file format supports metadata, i.e. it can save extra-information, not only annotations. If not, the metadata won’t be exported;
- Multi tiers: the file format accepts to save more than one tier;
- No tier: the file format can save a file without tiers;
- Point: the file format can save tiers of type
Point
; - Interval: the file format can save tiers of type
Interval
. - Gaps: the file format supports gaps between annotations of a tier. If not, when exporting the file, SPPAS will fill in the gaps by annotations with an empty label;
- Overlaps: the file format supports overlaps between annotations of a tier. If not, when exporting the file, SPPAS will split annotations to create a sequence of non-overlapping ones.
- Hierarchy: the format can deal with a hierarchy of tiers. If not, the hierarchy won’t be saved.
- Ctrl vocab: the format can save a controlled vocabulary of tiers. If not, the controlled vocabularies won’t be saved.
- Media: the format can save a reference to a media of tiers. If not, the media information won’t be saved.
- Vagueness: the format supports a vagueness value of the localization. If not, the vagueness value won’t be saved.
- Alt. loc: the format supports alternative annotation localizations. If not, the alternative localizations won’t be saved.
- Alt. tag: the format supports alternative annotation tags. If not,
when exporting the annotations, SPPAS will use a
{ | }
system to parse the alternative tags and = for scores.
Plugins page
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:
- Create or download the plugin package - e.g. a zip file.
- Execute SPPAS.
- Click on
Plugin
then click on theInstall
button of the toolbar. - Browse to indicate the plugin package.
- See the new plugin at bottom of the plugins list.
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.