User interfaces


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



Since version 2.3, a workspace manager was introduced into SPPAS. It allows to manage the files and the references. All the automatic annotations are using the workspaces.

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 in this chapter.

This configuration file can be copied into any other directory and re-imported into SPPAS.


A workspace can manage a set of files. Each time a file is added into the workspace, its root and its path are extracted and stored into a tree-like architecture. Data are strutured as follow:

For example, if the file /sppas/samples/samples-eng/oriana1.wav is added into the workspace, the following next actions will be performed:

Then, when an annotated file is created, its filename is inserted into the already existing root.

The annotation manager is automatically searching for a given input pattern in the filenames of a given root and is creating a file with a different output pattern. Notice that a pattern:

Thanks to this new management of files, the input and output patterns of the annotations can be modified. 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 so that it is ready-to-use each time SPPAS is started.

To summarize, if we consider the file /sppas/samples/samples-eng/oriana1-token.TextGrid, we have:

  1. /sppas/samples/samples-eng/ is the path
  2. /sppas/samples/samples-eng/oriana1 is the root
  3. /sppas/samples/samples-eng/oriana1-token.TextGrid is the filename, in which: - -token is the pattern, - .TextGrid is the extension.


There are 3 differente types of references: STANDALONE, SPEAKER and INTERACTION. Each of them corresponds to an annotation type. The annotations of both SPEAKER and INTERACTION require to associate roots with these references.

Each reference can contain a list of values with an identifier key to define them. Here is an example of a reference John of type SPEAKER with its list of values:

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 and the same to declare interactions.

The definition of such references/values, and their link to the corresponding roots allow to perform an elaborated way to check files of a workspace. It could be easy for example to check all files with file extension .wav of male gender more than 40 years old.

The graphical user interface

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

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/

The main frame

The top menu allows to open various pages like Files, Annotate or Analyze. To browse through the pages, use the mouse to click its button in the menubar or use keyboard shortcuts. Under Windows, press CTRL and under MacOS, press COMMAND. Then, 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 on the Settings icon at bottom. These settings are saved in a file to be used each time SPPAS is executed.

The About action button allows to display the main information about SPPAS: author, license, a link to the web site, etc.

Analyze page

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:

Edit page

It allows to annotate manually and to view files in a timeline. It can play several media at a time, it displays the list of annotations of the opened tiers…

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

To install a new plugin, simply follow this workflow:

  1. Create or download the plugin package - e.g. a zip file.
  2. Execute SPPAS.
  3. Click on the Plugin icon then click on the Install button of the toolbar.
  4. Browse to indicate the plugin package.
  5. See the new plugin icon in 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, select file(s) in the File explorer, click on the icon of the plug-in and follow instructions of the plugged program.

The Command-Line user Interface - CLI

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 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 both compatible with version 2.7 and 3.4+. They do not use a GUI so that installing wxPython is not required. The program also requires Julius or HVite.


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\ --help
usage: [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

  -i file      Input annotated file name.
  -o file      Output annotated file name.

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

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\ -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\ -I .\samples\samples-eng\ENG_M15_ENG_T02.wav
python .\sppas\bin\ -I .\samples\samples-eng\ENG_M15_ENG_T02.PitchTier
python .\sppas\bin\ -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