Installation instructions

Install or Update the SPPAS Package

SPPAS provides a single package version that is independent of the operating system.

Installation is easy: download the package from the website and place it in your user directory. Since it’s compressed, you must decompress and unpack it first — see recommendations below. Once unpacked, you can install the external programs — see the next section for details.

About the location of the uncompressed package

You need to choose a location within your user directory. SPPAS provides customizable solutions; therefore, each user must have their own installation of SPPAS and must have 'write' permissions for the chosen location.

About the name of the uncompressed package

Do not use "sppas" as the folder name. It is reserved for the source code. You can choose any other name (e.g., SPPAS-4, SPPAS-is-Magic, SPPAS-Love-Forever, etc.).
Preferably, use only US-ASCII characters (a-z, A-Z, 0-9) in both the path and filename.
Preferably, avoid spaces in both the path and filename.

Install external programs

This is an easy two-step process:

Install the only required one.
Launch setup to install the optional ones—just a click away!

1. Required external program: python

On Windows

Open the Microsoft Store and search for “Python 3”. Select the app named Python 3.9, 3.10, 3.11, or 3.12. Make sure it's published by the Python Software Foundation, click on "Obtain", and that’s it!

On macOS

Install Homebrew (if not already installed).
Python 3.9 is pre-installed, but to get the latest version, open Terminal and run:
```
brew install python
```

On Linux

Check if Python ≥ 3.9 is already installed. If needed, install it using apt, yum, brew, or any package manager:

python3
python3-venv
python3-pip
gstreamer (optional)

IMPORTANT! Use Python—DO NOT use Anaconda, or it will crash.
For the best SPPAS experience, choose Python 3.9 – 3.12.
Installing only one version of Python is highly recommended!

2. Enable Features: Setup

To enable certain features in SPPAS, external programs must be installed on your operating system. You’ll need to do this each time you install a new version of SPPAS or switch to a different Python version.

Tip 1: The SPPAS setup has been tested with Firefox only. Using a different web browser is at your own risk.

Tip 2: Install Mediapipe only if you really need it (e.g., for face or hand detection), as it can significantly slow down Python.

After each installation, a log file is created in the "logs" folder. You can review it, as it may contain important information, especially in case of installation failure for any component.

On Windows

Solution 1: Let SPPAS Install the Programs

Double-click the setup.bat file. After a few seconds, it will open a new tab in your default web browser—hopefully, Firefox. Then, just follow the instructions.

Once done, you can close the browser tab.

Solution 2: Install the Programs Manually

Open cmd.exe, PowerShell, or PowerShell (Admin mode).
Navigate to the unzipped SPPAS package folder.
Run the following command:
```
python.exe -m venv .sppaspyenv~
```
Then, run:
```
.sppaspyenv~\Scripts\python.exe sppas\bin\preinstall.py
```
Follow the prompts to select the features you want to install.

On macOS or Linux

You may need to change file permissions to add the "execute" right. Open a terminal, navigate to the SPPAS folder, and run: chmod +x *.command

Solution 1: Let SPPAS Install the Programs

Double-click the setup.command file. After a few seconds, a new tab will open in your default web browser—ideally Firefox. You may be prompted to enter your administrator password in the terminal.

On Linux, this procedure is supported only if either "brew" or "dpkg/apt" is available.

Solution 2: Install the Programs Manually

Open a Terminal application.
Navigate to the SPPAS package directory.
Run the command:
```
python3 -m venv .sppaspyenv~
```
Then, run:
```
.sppaspyenv~/bin/python sppas/bin/preinstall.py
```
Follow the prompts to select the features you want to install.

Solution 3: Full manual procedure

Perform steps 1 to 3, of Solution 2.

Below are most of the programs and Python packages to be installed either in your OS, or in the python virtual environment, with pypi. Take a look at the file sppas/etc/features.ini for the full list and versions.

REQUIRED: the pypi packages of AudiooPy, WhakerPy, and ClammingPy:

.sppaspyenv~/bin/python -m pip install AudiooPy WhakerPy ClammingPy

OPTIONAL: the pypi package of WxPython allows interacting with SPPAS with the Graphical User Interface - GUI:
```
.sppaspyenv~/bin/python -m pip install wxpython
```

OPTIONAL: the pypi packages of OpenCV and of Mediapipe to enable image and video processing:

.sppaspyenv~/bin/python -m pip install opencv-contrib-python-headless

.sppaspyenv~/bin/python -m pip install opencv-contrib-python

.sppaspyenv~/bin/python -m pip install mediapipe

OPTIONAL: the pypi package PyAudio" to allow playing sounds in the 'Edit' page of the GUI:
```
.sppaspyenv~/bin/python -m pip install pyaudio
```
OPTIONAL: the CSR Engine Julius, is used by the automatic annotation 'Alignment'. The HVite command of HTK 3.4.1 can also be used by the automatic annotation 'Alignment' but there are license restrictions.

F.A.Q.

I'm trying to run a .command file, and macOS says I don't have the appropriate access privileges!

If you have a .command script that you’re trying to run, and you keep getting the “File could not be executed because you do not have appropriate access privileges”, your script needs to be authorized to run. What’s unhelpful about this error is that it points you to the worst place to fix it; the Get Info window. That isn’t going to be of any help. Here’s what you need to do.

Option 1: use Terminal

Open Terminal application, then launch the followings:

             > cd /path/to/SPPAS
             > chmod +x *.command

This command grants execution permissions to all `.command` files in the specified folder. Then, you'll be able to double-click the .command files in the 'Finder'.

Option 2: use Finder

Alternatively, you can follow these steps in the 'Finder':

Right-click on the .command file.
Hover over Open With.
Choose Other...
You should be in the Applications folder. Open Utilities folder and select Terminal.app.
If you can't select Terminal.app, change the enabled applications from Recommended Applications to All Applications. It is at the bottom of the window.
If you want to open every .command file with Terminal.app, tick Always Open With.
Press the Open button in the bottom right corner of the window.

Note

If you still encounter issues, 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.

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 we must constrain our dependencies accordingly. As a result, OpenCV also cannot be updated to its latest versions, which affects all image and video processing features in SPPAS.

Python 3.13 is supported by SPPAS from version 4.23.
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.10.

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

SPPAS can work with various versions of Python. If you need to update Python on your system, you also have to delete the folder ".sppaspyenv~", which is located at the root of the SPPAS package. Then, re-launch the setup.

Contact Python developers or see the Python FAQ for any help with Python installation.

Externally programs installation ISSUES

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" to C:\\WINDOWS, or anywhere else Windows can find it.

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 for macOS 12+

The new gift of Apple: Under macOS 12, it seems that SPPAS is no longer allowed to launch "julius" to perform alignment. The Gatekeeper is overly zealous in preventing a third party app from being used in macOS.

In that case, turn off Gatekeeper through the System Preferences or launch Terminal if you haven't done so yet (/Applications/Utilities/) and issue the following command to turn off Gatekeeper: >sudo spctl --master-disable

ISSUE for Windows 10 + Python 3 + wxPython 4 + non-romanized languages

There's currently an issue - described here, under Some Windows OS with the versions Python 3.8+ and WxPython 4.1.0. It concerns only languages with a non-Romanized writing system. We are waiting that the developers of Python/wxPython solve the problem. I recommend to Windows users of non-romanized languages to choose an earlier version of Python (3.6 or 3.7).

Notice that it is not an issue under Linux and macOS; because the problem comes from Windows OS itself.