Frequently Asked Questions

General use

SPPAS send a message with an encoding error.

SPPAS can only deal with UTF8 encoding. If the input file is not UTF-8, the encoding error message is sent. So... the files must be converted.

Solution for TextGrid files: At a first stage, Praat has to be configured properly. Execute Praat, then click on the Praat menu. Click on Preferences then, click on "Text writing preferences...". Choose "Output encoding UTF-8" (it's the first choice). Then, each file has to be converted: Open the file, then save it.

Solution for any file under Windows: Open the file(s) with Notepad++, choose UTF-8 in the "Encoding" menu then save.

Installation

macOS says I don't have the appropriate access privileges!

macOS might be blocking the file because it isn't signed. In this case:

Go to System Preferences > Security & Privacy > General.
Click Allow Anyway next to the blocked file message.

macOS — Double-clicking sppas.app does nothing

This is most likely caused by macOS quarantine: when the zip archive is downloaded or transferred via certain tools (file managers, cloud storage apps, etc.), macOS silently blocks the app from running.

Solution — remove the quarantine flag:

Open a Terminal (Applications → Utilities → Terminal).
Run the following command, replacing /path/to/ with the actual location of the unzipped folder:
```
xattr -rd com.apple.quarantine /path/to/sppas.app
```
Double-click sppas.app again — it should now launch normally.

To verify whether quarantine is the cause, you can first check with:

xattr -l /path/to/sppas.app

If the output contains com.apple.quarantine, the command above will fix it.

If the problem persists, open a terminal and run:

open -a /path/to/sppas.app

Any error message will then be displayed in the terminal, which can help diagnose the issue further.

You can also try deleting the sppas-code/sppas-venv folder and re-launching Setup.

What happens with newer versions of Python?

Due to MediaPipe's outdated state and lack of maintenance by Google, users requiring MediaPipe functionality in SPPAS cannot currently use Python 3.12 or newer. MediaPipe currently requires an older version of NumPy, as it has not been updated for compatibility with NumPy >= 2.0. Unfortunately, this dependency issue originates from MediaPipe’s current state of development, and SPPAS must constrain its dependencies accordingly. As a result, OpenCV or NumPy also cannot be updated to its latest versions, which affects all image and video processing features in SPPAS.

In the same way, Whisper (for speech to text) is not available for python > 3.13.

Python 3.13/3.14 are supported by SPPAS from version 4.23, but they are not supported by the programs SPPAS needs! So... it won't work!
Python 3.12 is supported by SPPAS from version 4.17.
Python 3.11 is supported by SPPAS starting from version 4.12.
Python 3.10 is supported by SPPAS starting from version 4.7.

If you need a previous version of SPPAS, you must install a compatible version of Python.

What happens with older versions of Python?

Python 2.7.x is no longer supported.
Most of the features of SPPAS require external programs that are not available or deprecated for Python before 3.9.

What is happening if I change the Python version on my computer?

If you need to update Python on your system, you also have to update the created python virtual environment for SPPAS. Delete the folder "sppas-venv", which is located in "sppas-code" folder of the SPPAS package. Then, re-launch the Setup.

ImportError: DLL load failed while importing _framework_bindings:

This error occurs when using "Mediapipe" on Windows. It may appear either when the compiled library is for the wrong architecture (e.g., a 32-bit library on a 64-bit host) or when an underlying library is missing. Unfortunately, no additional information can be logged for this error, so it's impossible to know the exact cause... and thus, there's no way to resolve it.

I recommend re-installing Visual Studio to ensure it's installed for the same architecture as Python - i.e. both are 64-bit or both are 32-bit. Then, you'll need to restart your computer.

ISSUE with SPPAS < 5.0: Installation error of Julius under Windows

If you installed the programs without the administration rights, Julius failed to be installed. You have then to move the file "julius.exe" from SPPAS package to C:\\WINDOWS, or anywhere else Windows can find it.

Automatic annotations

Support of a new language?

All automatic annotations included in SPPAS are implemented with language-independent algorithms... this means that adding a new language in SPPAS only consists in adding the linguistic resources related to the annotation (like lexicons, dictionaries, models, set of rules, etc).

Linguistic resources can be edited, modified, changed or deleted by any user.

Supporting new languages is performed step by step, by adding linguistic resources; and constructing linguistic resources requires to collaborate with linguists. So... any help is welcome!

Find more details in chapter 3: each annotation requiring a specific resource has a section "Support of a new language".

[ ERROR ] End TimePoint must be greater than Begin TimePoint

This error message means that the given file contains a degenerated interval. It has to be corrected before the use of SPPAS.

Julius failed to time-align

The procedure outcome report indicates an error message, and the IPU is not time-aligned.

It can happen when something is wrong: julius is not installed, the audio signal quality is not good, the orthographic transcription does not really match the audio signal, there are errors in the phonetization, etc. You can then try to identify the problem and to solve it! You can also enable the basic option and SPPAS will assign the same duration to each phoneme to that specific IPU.

How long audio files can SPPAS process?

SPPAS can work on any audio file in length, as soon as the computer has enough memory.

[WARNING] Unknown word phonetization

When a token is missing of the pronunciation dictionary, SPPAS tries to phonetize by analogy with other entries of the dictionary, so this warning message occurs. If the proposed phonetization is the right one, you can ignore it. If not, you can edit the dictionary, then perform again the phonetization. See Chapter 3, Section 5 for details and the "Resources Documentation".

Do SPPAS can transcribe automatically?

SPPAS can ask Whisper to do so... if your computer can support it.

However, this system is not able to produce the high quality orthographic transcription which is required for further reliable analyses!

Orthographic transcription has to be done or checked manually, and it must follow the convention briefly described in (Chapter 3, Section 3) and detailed here.

SPPAS doesn't create annotated files:

From SPPAS version 2.3, when I run a python script, I found SPPAS don't create annotated files. My input file name is "bcf2e54f-16ea-46d2-a969-38bda8b9265e.wav". When I remove "-", it can be run. If my file name is "1-1-1.wav", it can be run. Prior to this version, SPPAS didn't have this kind of behavior.

There's no way for the workspace manager to distinguish if the character "-" is part of a filename or if it's a "root-pattern" separator. I recommend to use "_" instead.

In details... This is not a bug but the consequence of a new feature. From version 2.3, annotations of SPPAS are based on the use of "Workspaces". All the advantages of such new feature in the new GUI (requires python3 + wx4). In workspaces, filenames like "oriana1.wav" or "oriana1.TextGrid" or oriana1-token.TextGrid are all sharing the same file root which is "oriana1" and annotations will append a pattern to that root like "-token". When annotating, the workspace manager is searching for the file root from the given filename and so...

for "oriana1-token.wav" the root is "oriana1", because a pattern "-token" is existing.
for "bcf2e54f-16ea-46d2-a969-38bda8b9265e.wav" the root is "bcf2e54f-16ea-46d2-a969", because a pattern "-38bda8b9265e" is existing. SPPAS is then searching for annotated files like bcf2e54f-16ea-46d2-a969.TextGrid, bcf2e54f-16ea-46d2-a969-token.TextGrid, etc.
for "1-1-1.wav" the root is "1-1-1" because a pattern can't be less than 2 characters.

File conversion

What are the file formats supported by SPPAS?

SPPAS can to open/save and convert files from a wide range of file formats including (but not limited to) TextGrid, eaf, antx, mrk, ctm, stm, lab, srt, sub, csv, txt... The full list is available in the documentation, chapter "Introduction", section "Compatibility and Operability".