Installation

Requirements

Before installing Pianove, make sure the following are available on your system:

Python 3.10 or later — Pianove uses match statements and union types introduced in 3.10.
pip — included with all standard Python distributions.
git — to clone the repository. Alternatively, download the ZIP from GitHub.

A MIDI keyboard is optional for installation but required for interactive lessons. The built-in synthesiser works without a MIDI device.

1. Install Python

Windows

Download the installer from python.org/downloads. During installation, check Add Python to PATH. Verify with:

python --version

macOS

The system Python on macOS is 2.x and should not be used. Install via Homebrew:

brew install python3
python3 --version

Linux

Most distributions ship Python 3. Install it via your package manager if needed:

# Debian / Ubuntu
sudo apt update && sudo apt install python3 python3-pip

# Arch
sudo pacman -S python python-pip

python3 --version

2. Get the source code

Option A — Clone with git

git clone https://github.com/MariusAngermann08/Pianove.git
cd Pianove

Option B — Download ZIP

Go to the GitHub repository, click Code → Download ZIP, extract it, and open a terminal in the extracted folder.

3. Create a virtual environment (recommended)

A virtual environment keeps Pianove's dependencies isolated from your system Python.

python -m venv .venv

# Activate — Windows
.venv\Scripts\activate

# Activate — macOS / Linux
source .venv/bin/activate

Note: You need to activate the virtual environment every time you open a new terminal before running Pianove.

4. Install dependencies

pip install pygame

Pianove has no other required dependencies. pygame.freetype is included in the standard pygame distribution.

Optional: Install Pillow if you want PyLay to display PNG images inside the UI (not required for core lesson functionality).

pip install Pillow

5. Launch Pianove

python main.py

The Pianove window opens. If a MIDI keyboard is already connected via USB, it will be detected automatically. If not, connect it now and go to Settings → MIDI Device to select it.

Troubleshooting

`ModuleNotFoundError: No module named 'pygame'`

You are running Python from outside the virtual environment, or pygame was installed in a different environment. Activate the venv and re-run pip install pygame.

Blank or black window on launch

This is usually a graphics driver issue with pygame on some Linux configurations. Try running with the SDL software renderer:

SDL_VIDEODRIVER=x11 python main.py

MIDI keyboard not detected

Make sure the keyboard is connected before launching Pianove, or use Settings → MIDI Device → Refresh after connecting it. See MIDI Setup for a full troubleshooting guide.

`python` command not found (macOS / Linux)

Use python3 instead of python, and pip3 instead of pip.