Installing WhiteCat

Installing on Windows
Installing on Linux
Installing on Raspberry Pi
Installing DMX and MIDI drivers
Sleep / hibernate
Performance

Installing on Windows

Download format

WhiteCat is distributed as a .zip archive, downloaded from GitHub.
There is no installer.
This makes it easy to keep multiple versions side by side — useful when shows were created with different versions.
The WhiteCat folder can also run directly from a USB stick.

Install

Extract the archive directly under the root of a hard drive (C:/ or D:/).
Avoid paths that contain accented characters or spaces.
Do not run WhiteCat directly from inside the compressed archive — Windows lets you browse a .zip without extracting it. First sign of this mistake: the program displays Can't load fonts/doom.ttf and stops.

To extract: right-click the archive > Extract All > choose a location under C:/ or D:/.

Firewall

You must allow WhiteCat through the Windows firewall (and through any third-party antivirus or firewall installed on the machine).

WhiteCat opens network ports to send and receive DMX over ethernet (ArtNet protocol). The firewall may flag this and block startup.

On first launch, a Windows prompt will ask whether to allow WhiteCat network access. Click Allow access and check Private networks.
If WhiteCat gets stuck at startup without this prompt appearing, check your firewall rules manually and add an exception for the WhiteCat executable.

Launching WhiteCat

Double-click Whitecat_Crossplatform.exe in the extracted folder.

To create a desktop shortcut:

Right-click the executable > Create shortcut
Drag the shortcut to the desktop or taskbar

Installing on Linux

WhiteCat is distributed as a .tar.gz archive (64-bit x86_64 build) on GitHub. Extract it into your home folder, avoiding paths with accented characters or spaces. All files (the executable, Fonts/, gfx/, user/, saves/...) must stay together in the same folder.

The .sh scripts below can be launched either by double-click (choose "Execute" / "Run", possibly after ticking "Allow executing") or from a terminal.

1. Install dependencies (once per machine)

In a terminal opened in the extracted folder:

./install_deps.sh

This installs the required libraries (SDL2, audio, PDF export). The administrator password is requested.

2. Desktop integration (recommended)

./install.sh

Adds the cat icon and a launcher in the application menu and on the desktop. No password required: this script only touches your user profile. Note: the executable launched on its own keeps a generic icon — this is normal on Linux, the icon comes from the launcher.

3. Access to USB DMX interfaces

To drive a USB DMX interface (Enttec Open/Pro, DMX King...), add your user to the dialout group, then log out and back in:

sudo usermod -aG dialout $USER

(On Linux the libftdi1 driver replaces the Windows FTD2XX driver — no manual driver installation is needed.)

4. Run

Double-click the WhiteCat (cat) icon in the application menu or on the desktop — the launcher created in step 2. (If needed, you can also run ./run.sh from a terminal.)

Video tracking (OpenCV) is disabled in the Linux build.
If a firewall is active (ufw), allow UDP port 6454 for Art-Net.

Installing on Raspberry Pi

WhiteCat runs on Raspberry Pi under Raspberry Pi OS Bookworm 64-bit (aarch64 archive). A Raspberry Pi 4 or 5 is recommended: the Pi 3 works but stays limited (less fluid display).

Installation is identical to Linux (scripts can be launched by double-click or from a terminal):

./install_deps.sh — dependencies (once)
./install.sh — icon, launcher and window placement
sudo usermod -aG dialout $USER — USB DMX access
run: for everyday use, just double-click the WhiteCat icon (application menu or desktop); ./run.sh remains an alternative

Window placement (Wayland)

Raspberry Pi OS uses the Wayland/labwc compositor, under which an application cannot decide its own on-screen position. The install.sh script therefore adds a labwc rule that pins the WhiteCat window to the top-left corner. To choose another position, edit the WC_POS_X / WC_POS_Y variables at the top of install.sh and run it again.

Installing DMX and MIDI drivers

To send DMX through a USB interface, its driver must be installed on the computer. See DMX Configuration for the list of supported interfaces.

Most MIDI interfaces are recognised automatically by Windows with no manual installation. For less common devices, install the driver provided by the manufacturer — always download the most recent version from the manufacturer's website.

General tips for driver installation:

Do installations at home, calmly, with an internet connection.
Run installers with administrator rights (right-click > Run as administrator).
After installation, restart the computer.
If you go on international tour, keep the manufacturer's installer on a USB stick.

You can check that your devices are correctly installed via the Device Manager: right-click the Start menu > Device Manager. A faulty device appears with a yellow warning triangle.

Sleep / hibernate

Since version 0.9.x, WhiteCat appears to handle sleep better than before. As a precaution, it is still recommended to disable sleep during a show.

Control Panel > Power Options > Change plan settings > set Never for sleep, both on battery AND on mains power.
Never close the laptop lid while WhiteCat is running.

Performance

Since version 0.9.x, WhiteCat uses a smart ticker with three levels:

60 fps while the user is interacting (mouse, keyboard)
25 fps during automatic animations (LFO, chasers, crossfades, dampers)
Near-idle mode (100 ms) when no animation is active

CPU usage is significantly lower than in previous versions.

If you still experience slowdowns:

Turn off Wi-Fi during the show.
Disable real-time antivirus scanning.
Disable automatic Windows updates.

Table of contents