Installation Instructions

The instructions for setting up the SynthARium Project are divided into 3 parts:

0. Setting up Tools
   • Installing Python
   • Installing Node
   • Installing Git
   • Installing Docker (Optional)
   • Configure ngrok (Optional)
   • Configure ChatGPT (Optional)
1. Installer Installation
   • Key Features
   • Download Installer Launcher Application
   • Test Python
   • Test Node.js
   • Test git
   • Configure Ngrok Token
   • Configure OpenAI Token
   • Configure OpenFace
   • Configure Experimenter Password
   • Install Project
   • Launcher
2. Manual Installation
   • Building and Running the Frontend
   • Building and Running the Backend
   • Building OpenFace for AU Filter

We did our best to make instructions as beginner-friendly as possible and even obtained user feedback to improve these instructions which you can find the results of here. However, if you have any further suggestions for improvements or run into trouble with installation, head over to our discussion forum.

Setting up Tools

If you do not have any of the below requirements already installed, please first install them.

• python (at least version 3.10.3)[1] + pip
• node[2] and npm[3]
• git

[1]: current tested versions are 3.10.4, 3.10.6, 3.10.7, 3.10.9, 3.11.6 Earlier python versions, e.g. 3.10.1 + 3.10.2, do not work. python version 3.12.00 will not work until some packages (i.e. av) have been updated to be used with it.

[2]: currently, tested versions node are: v16.17.1, v19.4.0, v19.6.0, v19.7.0

[3]: currently tested versions of npm are: 8.15.0, 9.4.0, 9.5.0, 9.6.1

Checking Installed Versions

To check the version number of each of the above requirements, for Python type which python, which pip, npm, or node in your terminal respectively. If you need to have multiple versions of a requirement, e.g. python, can use conda, for example, to manage them with conda e.g. conda create -n synchrony_hub python=3.10.3

Installing Python

If you think you already have Python installed, please check to make sure it meets the version requirements. If your system has Python installed with a version between 3.10.3 and 3.12, you do not need to reinstall Python. If you need detailed instructions for how to install Python, follow these steps to install Python 3.11.4 on your computer:

(Optional) YouTube links show how to install Python on your machine for Windows and Mac

Step 1: Download Python 3.11.4

• Open your web browser and navigate to the official Python website: https://www.python.org/downloads/release/python-3114/
• Choose the Correct Installer: On the Python 3.11.4 release page, scroll down to the "Files" section. Select the appropriate installer for your operating system:
  • Windows: Download the "Windows installer (64-bit)" or "Windows installer (32-bit)" depending on your system architecture.
  • macOS: Download the "macOS 64-bit universal2 installer."
  • Linux: Linux users generally prefer to install Python via their package manager, but you can also download the source code and compile it.

Step 2: Install Python 3.11.4

Follow the installer prompts (see below for a step-by-step guide).

Windows: Locate the downloaded installer file and double-click to run it. In the image below you will see the Python installation screen.

|

The installer will proceed with the installation. Once completed, you can click "Close."

macOS: Locate the downloaded .pkg file and double-click to run it. Follow the Installation Wizard:

Follow the on-screen instructions to install Python. The installer will guide you through the steps.

Linux: Most Linux distributions allow you to install Python via the package manager. For example, on Ubuntu, you can run:

> sudo apt update
> sudo apt install python3.11

Note that you might need to add a repository or update your package list depending on your distribution.

Step 3: Verify Python Installation Regardless of your operating system, ensure that Python is properly installed and accessible from the command line. Open a terminal or command prompt and type the following command:

> python --version

or

> python3 --version

The output should display the installed version as Python 3.11.4.

By following these steps, Python 3.11.4 should be successfully installed on your system, allowing you to proceed with the installation of the SynthARium project.

Installing Node

Before you begin installing Node.js 18, it’s important to verify whether Node.js is already installed on your system and if it meets the version requirements. If your system already has Node.js version 18.x installed, you can skip the installation step. Otherwise, follow the instructions below to install Node.js 18.

(Optional) YouTube links show how to install node.js on your machine for Windows and Mac.

Step 1: Download and Install Node.js 18

• Open your web browser and navigate to the Node.js download page: https://nodejs.org/en/blog/release/v18.12.0
• Download the Node.js 18 Installer: On the download page, you will see options for different versions of Node.js. Select the latest LTS (Long-Term Support) version under Node.js 18.x. This version is recommended for most users and ensures long-term stability. Choose the appropriate installer for your operating system: Windows: Download the .msi installer. macOS: Download the .pkg installer. Linux: Follow the instructions provided on the website, typically involving the use of a package manager like apt or yum.

Step 2: Install Node.js 18

Windows: Run the downloaded .msi installer. Follow the on-screen instructions, accept the license agreement, and choose the default installation settings unless you have specific preferences.

macOS: Run the downloaded .pkg installer. Follow the installation prompts, and Node.js will be installed on your system. Node.js should automatically be added to your PATH.

Linux: Follow the instructions provided on the Node.js download page to use your package manager. For example, on Ubuntu, you can run:

> curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
> sudo apt-get install -y nodejs

Step 3: Verify Node.js Installation (Optional)

Regardless of your operating system, ensure that Node.js is properly installed and accessible from the command line. Open a terminal or command prompt and type the following command:

> node –-version

The output should display the installed version as Node 18.12.0.

Installing Git

Before installing Git, it’s essential to verify if Git is already installed on your system and if it meets the necessary version requirements. If Git is installed and up-to-date, you can skip the installation step. Otherwise, follow the steps below to install Git. (Optional) YouTube links show how to install git on your machine for Windows and for Mac.

Step 1: Download Git

• Open your web browser and navigate to the Git download page: https://git-scm.com/downloads.
• On the download page, choose the appropriate installer for your operating system: Windows: Download the .exe installer. macOS: Download the .dmg installer or use Homebrew (see below). Linux: Follow the instructions for your specific distribution (see below).

Step 2: Install Git

Windows: Run the downloaded .exe installer. Follow the installation prompts, including accepting the license agreement and selecting your desired components. During installation, you can choose the default editor that Git will use. If you don’t have a preference, you can stick with the default (usually Vim or Nano). You will also be prompted to choose the PATH environment. It’s mandatory to select "Git from the command line and also from 3rd-party software." Complete the installation by clicking "Finish."

macOS: Run the downloaded .dmg installer and follow the on-screen instructions. After installation, Git should be automatically added to your PATH.

Linux: Git is usually available through the package manager. You can install it by running the appropriate command for your distribution. For example:

> sudo apt update
> sudo apt install git

If you are using git for the first time on your device, ensure that you have set up your login credentials. To set it up for the first time, use:

$ git config --global user.name "<Your github username>"

$ git config --global user.email "<email address linked to your github account>"

Installing Docker (Optional)

Docker Desktop is recommended for integrating the OpenFace tool with the SynthARium project. While Docker Desktop is not mandatory for running the basic SynthARium setup, it is necessary if you plan to utilize OpenFace for facial analysis during your experiments unless you intend to build OpenFace yourself (see manual build instructions for openface). If you don't require this feature, you can skip this installation step. Otherwise, follow the instructions below to install Docker Desktop.

(Optional) YouTube links show how to install git on your machine for Windows and for Mac.

Step 1: Download Docker Desktop

• Open your web browser and navigate to the Docker Desktop download page: https://www.docker.com/products/docker-desktop
• Download Docker Desktop: Choose the appropriate installer for your operating system: Windows: Download the .exe installer.

macOS: Download the .dmg installer.

Step 2: Install Docker Desktop

Windows: Run the downloaded .exe installer. Follow the installation prompts, including agreeing to the license agreement. During the installation, Docker Desktop will check if the required Windows features (like WSL 2) are enabled. If not, it will prompt you to enable them. Once the installation is complete, Docker Desktop will start automatically.

macOS: Run the downloaded .dmg installer. Drag the Docker icon to the Applications folder. Open Docker Desktop from the Applications folder or Launchpad. Docker Desktop will start and install the necessary components. You may be prompted to enter your password to allow the installation.

Step 3: Initial Setup (First-Time Run)

After installation, the Docker Desktop will run automatically. On the first run, you may need to complete a short setup process. Follow the prompts to complete the setup. This may include logging into a Docker account or creating one if you don't already have one.

Configure ngrok (Optional)

If you want your SynthARium instance to be accessible to the internet, one easy option is to sign up and use ngrok. If you plan to use Ngrok, for secure tunneling and remote access to your localhost server, you will need to configure it with an authentication token. This step is optional and only necessary if you require external access to your local development environment.

(Optional) Youtube links show how to get ngrok authentication token link

Step 1: Sign Up for an Ngrok Account

Open your web browser and navigate to the Ngrok website: Signup Page. Sign Up or Log In: If you don’t have an account, click on the "Sign Up" button and create a new account using your email, Google, or GitHub credentials. Note: If you already have an account, simply log in with your credentials.

Step 2: Get Your Authentication Token

Access the Ngrok Dashboard, once you are logged in, you will be redirected to the Ngrok dashboard. Retrieve Your Authentication Token: On the dashboard, you will see a section labeled "Your Authtoken" or something similar. Copy the provided authentication token. This token will be used to configure Ngrok on your local machine in the installer application in Step 1.4.

Configure ChatGPT (Optional)

To access the ChatGPT API or integrate it into SynthARium, you'll need to obtain an authentication token. This token is essential for secure access and will be used in your requests to the ChatGPT service.

(Optional) Youtube links show how to get ChatGPT authentication token link

Step 1: Sign Up for an OpenAI Account

Go to the official website of the ChatGPT API provider (e.g., OpenAI). Sign Up or Log In: If you don’t have an account, click on the "Sign Up" button and create a new account using your email, Google, or GitHub credentials. Note: If you already have an account, simply log in with your credentials.

Step 2: Get Your Authentication Token

Access the OpenAI Dashboard, once you are logged in, you will be redirected to the OpenAI dashboard. Retrieve Your Authentication Token: On the dashboard, you will see a section labeled "Your Authtoken" or something similar. Copy the provided authentication token. This token will be used to configure ChatGPT on your local machine in the installer application.

Installer Installation

The SynthARium Installer Launcher is a user-friendly desktop application designed to guide users through setting up the SynthARium project on their local machine. The application streamlines the installation process by breaking it down into clear, sequential steps, each represented in the application's interface.

Key Features:

1. Step Navigation: The application interface includes a list of installation steps on the left-hand side. Each step corresponds to a critical part of the installation process, such as testing system requirements, configuring optional components, and installing the project. As you complete each step, a checkmark appears next to the step, indicating it has been completed.

2. Interactive Instructions: For each step, the main panel provides detailed instructions along with interactive buttons that allow users to perform necessary actions, such as checking software versions or proceeding to the next step.

3. Guidance and Support: Each page within the application provides contextual information and guidance on what is being checked or configured. Users are informed about what is required, why it’s important, and how to address any issues that might arise.

Download Installer Launcher Application

Before you begin using the SynthARium Installer Launcher application, you need to download the latest version from the GitHub repository. This step ensures that you have the most up-to-date version of the application, which includes all the latest features and bug fixes.

• Visit the SynthARium GitHub Repository: Open your web browser and go to the official SynthARium GitHub repository

• Navigate to the Releases Section: Once on the repository page, look for the "Releases" section. This section contains all the officially released versions of the SynthARium Installer Launcher. You can usually find a "Releases" link on the right-hand side of the repository's main page or in the repository's menu under "Code."

• Download the Latest Version: In the "Releases" section, locate the most recent release. It is typically listed at the top with a version number (e.g., v0.0.15). Under this latest release, you will find assets such as .zip, .exe, or .dmg files, depending on your operating system. Click on the appropriate file to download the installer for your system: Windows: Download the .exe file (SynthARiumInstallerLauncher-Setup-0.0.15.exe). macOS: Download the .dmg file (SynthARiumInstallerLauncher-0.0.15-arm64.dmg). Linux: Download the .AppImage or other relevant file type. Save the file to a location on your computer where you can easily access it.

• Install the Application: After downloading, open the file to begin the installation process. Follow the on-screen instructions to install the SynthARium Installer Launcher on your computer.

NOTE: This step on Windows may require administration permissions. When you download the setup from GitHub, please store the document.

Test Python

The "Test Python" page is a crucial part of the SynthARium Installer Launcher application, ensuring that your system has the correct version of Python installed to run the SynthARium project. This page not only verifies the Python installation but also provides feedback through a logs section, which helps users understand the results of the version check.

• Objective: The primary goal of this page is to check if Python is installed on your system and whether the version falls within the required range (greater than 3.10.3 and less than 3.12). Python is essential for running the backend of the SynthARium project.

• User Instructions: The instructions on this page explain that Python must be installed and why it is necessary for the project. Users are directed to click the "Check Python Version" button to initiate the version check.

• User Interaction:

  1. Check Python Version Button: When the user clicks this button, the application runs a check to determine if Python is installed and whether it meets the version requirements. If Python is detected and the version is correct, a success message will be displayed in the logs section, and the step will be marked complete with a checkmark on the left-hand navigation.

• Logs Section: After performing the version check, the results are displayed in the logs section below the button. In the provided screenshot, the logs section shows the message: "Success Python 3.11.4 meets the requirements!" This confirms that the system has a compatible version of Python installed. If Python was not installed or the version did not meet the requirements, the logs would display an error message, and further instructions would be provided to guide the user through installing the correct version.

Test Node.js

After downloading and installing the SynthARium Installer Launcher, the next step in the setup process is to verify that Node.js is installed on your system and that the version meets the necessary requirements. This is crucial because Node.js is needed to run various frontend components of the SynthARium project.

• Objective: This page checks if Node.js is installed and ensures that it meets the required version. The application specifically looks for Node.js version 18.x.

• User Instructions: The instructions on this page explain the importance of Node.js for running the SynthARium project. Users are directed to click the "Check Node.js Version" button to initiate the version check.

• User Interaction:

  1. Check Node.js Version Button: When the user clicks this button, the application checks if Node.js is installed and whether the version is 18.x. If Node.js is detected and the version is correct, a success message will be displayed in the logs section, and the step will be marked complete with a checkmark on the left-hand navigation.

• Logs Section: After performing the version check, the results are displayed in the logs section below the button. If the correct version of Node.js is installed, the logs section will display a success message similar to: "Success: Node.js 18.x meets the requirements!" If Node.js is not installed or the version is incorrect, the logs will display an error message, and further instructions will be provided on how to install or update Node.js to the correct version.

Test git

The next step in the SynthARium Installer Launcher setup process is to verify that Git is installed on your system and that it meets the requirements. Git is essential for cloning the SynthARium repository and managing the project's version control.

• Objective: This page checks if Git is installed on your system and ensures that it meets the required version. Git is needed to clone the SynthARium repository from GitHub and manage the project's version history.

• User Instructions: The instructions on this page explain the importance of Git for the SynthARium project. Users are prompted to click the "Check Git Version" button to initiate the version check.

• User Interaction:

  1. Check Git Version Button: When the user clicks this button, the application checks if Git is installed and whether the version is appropriate. If Git is detected and the version is correct, a success message will be displayed in the logs section, and the step will be marked complete with a checkmark on the left-hand navigation.

• Logs Section: After performing the version check, the results are displayed in the logs section below the button. If the correct version of Git is installed, the logs section will display a success message similar to: "Success: Git version X.X.X meets the requirements!" If Git is not installed or the version is outdated, the logs will display an error message, and further instructions will be provided on how to install or update Git to the correct version.

Configure Ngrok Token

The "Configure Ngrok" step in the SynthARium Installer Launcher is optional but highly useful if you need to expose your local application to the global network. Ngrok provides a secure tunnel to your localhost, which can be especially helpful for sharing your development environment with others or testing webhooks.

• Objective: This step is designed to help you set up Ngrok by entering your authentication token obtained from Step 0.5. This token is required to establish a secure connection between your local environment and the internet using Ngrok.

• User Instructions: The page explains why Ngrok might be useful and informs users that this step is optional. If you decide to use Ngrok, you'll need to obtain an authentication token from the Ngrok website.

• User Interaction:

  1. Input Section: In the input field provided on the "Configure Ngrok" page, paste the Ngrok authentication token that you copied from the Ngrok dashboard. Details are covered about how to get the ngrok authentication token in Activity 0.5.
  2. Set Ngrok Token Button: After pasting your token, click the "Set ngrok token" button. This action saves your token, enabling the application to use Ngrok to expose your local server. Upon successfully saving the token, a confirmation message will appear in the logs section stating, "Ngrok authentication token is successfully saved."

• Logs Section: The logs section below the input field displays the status of your Ngrok token setup. In the provided screenshot, shows the success message, confirming that the token has been saved and is ready to use.

NOTE: You can only run one instance at the same time with the free-tier ngrok auth token. So please make sure, no other clients are running with this token.

Configure OpenAI Token

The "Configure OpenAI" step in the SynthARium Installer Launcher allows you to set up an OpenAI API token, which is necessary if you plan to integrate OpenAI's services into the SynthARium project. This step, like the Ngrok configuration, involves entering your API token to enable the application to access OpenAI's capabilities.

• Objective: This step is designed to help you configure OpenAI by entering your API token. This token is required for any interactions with OpenAI's API, enabling features like language models or other AI-powered functionalities within the SynthARium project.

• User Instructions: The page explains the importance of the OpenAI token and instructs users on how to obtain and configure it. This step is optional and should be completed if you intend to use OpenAI's services within the SynthARium project.

• User Interaction:

  1. Input Section: In the input field provided on the "Configure OpenAI" page, paste your OpenAI API token that you copied from the OpenAI dashboard.
  2. Set OpenAI Token Button: After pasting your token, click the "Set OpenAI token" button. This action saves your token, enabling the application to use OpenAI's services. Upon successfully saving the token, a confirmation message will appear in the logs section stating, "OpenAI authentication token is successfully saved."

• Logs Section: The logs section below the input field displays the status of your OpenAI token setup. If the token is successfully saved, the logs will confirm this with a message indicating that the token has been saved.

Configure OpenFace

The "Configure OpenFace" step in the SynthARium Installer Launcher is designed to help users set up OpenFace, a tool for facial behavior analysis, within the SynthARium project. This step requires Docker, as OpenFace is deployed through a Docker container. The process involves checking for Docker on your machine and then pulling the necessary OpenFace image from the Docker repository. This step takes around 5 to 10 minutes depending on your internet speed.

• Objective: This step ensures that Docker is installed on your system and then pulls the OpenFace Docker image, allowing you to run OpenFace as part of the SynthARium project.

• User Instructions: The page informs users that OpenFace configuration is optional but highly useful if you need to analyze facial behavior as part of your research. It explains that Docker is required for this step, and the application will handle the setup automatically.

• Configuration Process:

  1. Docker Check: When you click the "Open Face" button, the application first checks if Docker is installed on your system. Docker is necessary because OpenFace runs within a Docker container. If Docker is not installed, the application will prompt you to install Docker before proceeding.
  2. Pulling OpenFace Docker Image: If Docker is installed, the application then checks if the OpenFace Docker image is already present on your machine. If the image is not found, the application will automatically pull the OpenFace Docker image from the Docker repository, ensuring that you have the latest version ready to use.

• Logs Section: The logs section below the "Open Face" button displays real-time updates on the configuration process. Messages such as "Checking for Docker installation in your computer," "Checking for Docker image in your computer," and "Requested OpenFace Docker image exists in your computer" provide feedback on the progress. If the configuration is successful, a message like "OpenFace successfully configured" will confirm that the setup is complete and that OpenFace is ready to use.

Configure Experimenter Password

The "Configure Password" step in the SynthARium Installer Launcher allows you to set up an optional password for securing experiment logins within the SynthARium project. This is an important step if you want to ensure that access to your experiments is restricted and secure.

• Objective: This step is designed to help you configure a password that will be used to secure logins for your experiments. Setting a password is optional but recommended if you want to control access to your experiment environment.

• User Instructions: The page provides an explanation of why setting a password is important for securing access to your experiments. It also informs users that this step is optional and can be skipped if password protection is not needed.

• User Interaction:

  1. Password Input Section: There is an input field where you can enter your desired password. This password will be used to secure logins for your experiments.
  2. Set Experimenter Password Button: After entering your password, click the "Set experimenter password" button to save it. This will ensure that your experiments are protected by the password you've chosen. Upon successfully saving the password, a confirmation message will appear in the logs section stating, "Experimenter password is successfully configured."

• Logs Section: The logs section below the input field provides feedback on the status of your password configuration. If the password is successfully saved, the logs will display a confirmation message indicating that the password has been set.

Install Project

The "Install Project" page is the final and most crucial step in the SynthARium Installer Launcher. This step involves downloading the SynthARium repository, setting up a Python virtual environment, and installing all necessary backend and frontend dependencies. Given the complexity of these tasks, this step may take some time to complete.

• Objective: The goal of this step is to set up the SynthARium project fully on your local machine. This includes downloading the latest version of the project from GitHub, creating a Python virtual environment, and installing all required dependencies for both the backend (using pip) and the frontend (using npm).

• User Instructions: The page provides clear instructions that inform users about the process. It explains that by clicking the "Install Project Dependencies" button, the application will automatically handle the following tasks:

  • Download the SynthARium Repository: The application will clone the latest version of the SynthARium project from the GitHub repository to your local machine.
  • Create a Python Virtual Environment: A virtual environment will be set up to ensure that all Python dependencies are isolated and managed correctly.
  • Install Backend Dependencies with pip: The necessary Python packages required by the SynthARium project will be installed within the virtual environment.
  • Install Frontend Dependencies with npm: The application will then install the required frontend dependencies using npm to ensure that all JavaScript and React components function correctly.

• User Interaction:

  1. Install Project Dependencies Button: When the user clicks this button, the application begins the installation process. This includes downloading the repository, setting up the environment, and installing dependencies.
  2. Logs Section: As the installation progresses, detailed logs will be displayed in the section below the button. These logs provide real-time feedback on each step of the process, such as cloning the repository, creating the virtual environment, and installing dependencies.
  3. Expand/Collapse Logs: Users can expand the logs to view more detailed information or collapse them to keep the interface clean. This is particularly useful for troubleshooting if the installation encounters any issues.

• Installation Duration: Users are informed that this step might take some time, depending on their internet speed and system performance. The process involves downloading potentially large files and running multiple installation commands, so patience is advised.

Launcher

The "Launcher Page" is the final and most interactive step in the SynthARium Installer Launcher application. This page allows you to customize and launch the SynthARium project based on the configurations you have set up in the previous steps. It also provides real-time feedback through logs and gives you access to the project's URL once the server is running.

• Objective: The primary goal of this page is to allow you to launch the SynthARium project with specific features enabled, based on your preferences. You can customize the launch by selecting or deselecting various options that you configured during the setup process.

• User Interaction:

  1. Checkboxes for Configuration:

     1. Enable OpenFace: This option allows you to enable OpenFace if it was configured earlier. If OpenFace is not configured, this checkbox will be disabled.
     2. Enable ChatGPT: This option allows you to enable ChatGPT integration if it was configured earlier. If not, this checkbox will be disabled.
     3. Enable Ngrok: This option allows you to enable Ngrok to expose your local server to the internet. If Ngrok is not configured, this checkbox will be disabled.
     4. Use Experimenter Password: This option enables the use of a password to secure experiment logins, provided it was configured in the previous step. If not configured, this checkbox will be disabled.

  2. Launch Button: After selecting your desired options, click the "Launch" button. This will start the SynthARium project server based on the configurations you’ve selected. The application will display real-time logs in the section below the button, showing the status of the server and any operations being performed. The project URL, typically http://127.0.0.1:8080, will be displayed, indicating where you can access the running application. If you launch the application with ngrok enabled configuration then a different https link will disappear.

  3. Terminate Button: After the server is successfully launched, the "Launch" button changes to a "Terminate" button. Clicking "Terminate" will stop the server and end the current session. This feature allows you to easily stop the SynthARium project when you are done using it.

• Logs Section: As the server starts, detailed logs will appear in the logs section. These logs include information about the server startup process, the configurations applied, and any other relevant messages. The logs help you monitor the launch process and troubleshoot if any issues arise.

• Launch URL: Once the server is running, the URL where you can access the SynthARium project is displayed. For example, http://127.0.0.1:8080. You can click this link to open the project in your web browser.

• Navigation:

  1. Back to Installer: If you need to return to the previous setup steps, you can click the "Back to Installer" link at the top left of the page.

  2. Summary: The "Launcher Page" offers a flexible and powerful way to start the SynthARium project with the specific configurations you’ve set up, such as OpenFace, ChatGPT, Ngrok, and password protection. The ability to view real-time logs and the project URL provides transparency and control over the launch process. The "Terminate" button adds convenience by allowing you to stop the project when it’s no longer needed. This final step brings together all the configurations you’ve made and launches the project, ready for you to start your experiments or development work.

Manual Installation

If you decided to manually set up the project, you likely have already forked our project and would like to make your own modifications to the code! 🧑‍🔬 That's very exciting and let us know how it goes in our Github Discussions Page.

Creating a Virtual Environment

Virtual environments are recommended for maintaining isolated environments across different Python projects. If you don’t have it installed yet, use the following command:

$ pip install virtualenv

or through homebrew (if using OSX) or the Microsoft Store app (if using Windows). We recommend creating your venv in the root folder of the project code, e.g. within the cloned repo and you can set your virtual environment for Python dependencies using:

OSX/Linix: python3 -m venv exp-hub-venv

Windows: py -m venv exp-hub-venv

Where you can name the venv (exp-hub-venv above) anything that suits your purpose best. You can activate the venv by running the following command in the same directory of your venv source <name-of-venv>/bin/activate

(Note: the command may be python or either python3 depending on your installation and the PATH variable)

---

Installation and running

In this section, we want to explain how to set up and run SynthARium.

First, using the terminal, navigate to your desired directory and clone the GitHub repo [git clone https://github.com/TUMFARSynchrony/experimental-hub.git](https://github.com/TUMFARSynchrony/SynthARium.git)

Building and Running the Frontend

In your terminal, navigate into the frontend directory:

$ cd SynthARium/frontend

First, we need to install dependencies using:

$ npm install

Now we have two choices, either running the frontend in developer mode or building it, so it can be served through the backend.

Running in developer mode

You can run the frontend directly which is recommended for (frontend) developing, because changes in the code are automatically propagated when reloading. You can do it by:

$ npm start

The server will now be accessible on http://localhost:3000.

You should be able to see the following screen:

[!NOTE] Note how no sessions are "loaded" or visible. This is because the backend is not yet.

Building the frontend

You can also build the app for production in the build folder.

$ npm run build

Now the frontend can be served using the backend. See below.

Building and Running the Backend

To start the backend server, open up a new terminal for the backend and navigate into the directory:

$ cd SynthARium/backend

Make sure your venv is activated and install the backend dependencies using:

$ pip install -r requirements.txt

Now start the server using:

$ python main.py

[!NOTE] You may need to use py/python/python3 depending on your installation and the PATH variable

By default the backend server will also serve the frontend. So make sure you have built the frontend. Now SynthARium should be available on: http://localhost:8080.

Alternatively, you can serve the frontend separately using the frontend development server. If you want to do this, change serve_frontend to false in backend/config.json. In this case, the hub should be available on: http://localhost:3000.

If everything worked you should be able to see the following screen with the experimental sessions loaded:

These were the basics of setting up SynthARium. Suppose you want to go further and also let others from outside of your network access the hub then have a look at hosting. To get an overview of all config options you have when setting up the hub, look at the configuration page.

If you just want to try everything out you can continue with running an experiment.

Building OpenFace for AU Filter

If you intend to use the OpenFace AU filter for your experiments, then you must install the OpenFace project. There are two varieties of AU filters: real-time and async. The real-time filter displays the Action Unit values in the video stream and uses ZeroMQ as the communication channel between the hub and OpenFace. The async filter processes all frames into Action Unit values asynchronously so it doesn't show in the video stream and it uses RabbitMQ.

Real-Time

1. Install cppzmq.
2. Install OpenFace by cloning the project from the forked github here and this exact branch. Then follow the steps from the official documentation of OpenFace.

Async

1. Install rabbitmq.
2. Install rabbitmq-c
3. Install OpenFace by cloning the project from the forked github here and this exact branch (different from the real-time). Then follow the steps from the official documentation of OpenFace.