Installation instructions

Install or Update the SPPAS Package

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

The installation process is simple: all you need to do is download the package from the website and place it in a location within your user directory. Since the package is compressed and zipped, you will need to decompress and unpack it after downloading it. Once unpacked, you're ready to install the external programs. See the next section for details on how to install them.

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 the name "sppas". You can choose any name you like (e.g., SPPAS, SPPAS-4, SPPAS-Love-Forever, ...) but "sppas" is reserved for the source code folder and cannot also be used as the name of the software folder.
Preferably use only US-ASCII characters — i.e., a-z and A-Z, in both the path and the filename.
Preferably choose a name without any whitespace in both the path and the filename.

Install external programs

This is a two-stage process:

install the required ones;
launch setup to install the optional ones.

1. Required external programs

Under Windows

Launch the Microsoft Store. Search the Microsoft Store app for “Python 3”. Select the App with the name Python 3.9, or 3.10, or 3.11. Ensure that the app you select is published by the Python Software Foundation.

Get details about this installation procedure

Under MacOS

Install Homebrew.
Python 3.9 is already installed. However, if you want to install a more recent version, open the Terminal application and launch the command:
```
brew install python
```

Under Linux

Check if Python >= 3.7, then use either apt/yum/brew or any other tool to install the packages:

python3
python3-venv
python3-pip
gstreamer (optional)

IMPORTANT! Use Python... Do NOT use Anaconda: it will crash.
For a full experience of SPPAS, choose Python 3.9 - 3.11
Installing one and ONLY ONE version of Python is highly recommended!

2. Enable features: setup

External programs must be installed on your operating system to enable certain features of SPPAS. You need to do this each time you install a new version of SPPAS or change the version of Python on your computer.

The SPPAS setup was tested with Firefox only. Using another web-browser is at your own risk.

Under Windows

Solution 1: Let's SPPAS installing the programs

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

Once it's done, you can close the web browser tab.

Solution 2: Install the programs manually

Launch either 'cmd.exe' or the 'PowerShell' application or the 'PowerShell with Admin rights' application
Change location to the unzipped SPPAS package
Launch the command:
```
python.exe -m venv .sppaspyenv~
```
Launch the command:
```
.sppaspyenv~\Scripts\python.exe sppas\bin\preinstall.py
```
Then choose the features to be installed.

Under MacOS or Linux

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

Solution 1: Let's SPPAS installing the programs

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

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
Change location to the SPPAS package
Launch the command:
```
python3 -m venv .sppaspyenv~
```
Launch the command:
```
.sppaspyenv~/bin/python sppas/bin/preinstall.py
```
Then choose the features to be installed.

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.

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.