Gamepad-driven ethogram annotation for animal behaviour research.
GameThogram is a desktop application for manually scoring animal behaviours in video recordings using a gamepad (Xbox, PlayStation) or keyboard. It is designed for ethologists and behavioural neuroscientists who need frame-accurate behavioural coding with real-time visual feedback.
Formerly known as pyMovScorer / pyVISOR.
No Python required. Pre-built binaries for Windows, macOS, and Linux are available on the Releases page. Download the archive for your platform, unzip, and double-click GameThogram to launch.
| Platform | Download | Notes |
|---|---|---|
| Windows | GameThogram-Windows.zip |
Unzip, run GameThogram.exe |
| macOS | GameThogram-macOS.zip |
Unzip, right-click → Open on first launch (Gatekeeper) |
| Linux | GameThogram-Linux.tar.gz |
Extract, run ./GameThogram |
If you prefer to install from source (e.g. for development), see Installation below.
- Video playback with frame-by-frame stepping, variable-speed forward/reverse, and FPS control
- Gamepad support — Xbox, PlayStation, and generic controllers via pygame; keyboard fallback always available
- Multi-animal scoring — define independent behaviour sets per animal with colour-coded icons
- Behaviour compatibility — mark which behaviours can co-occur on the same frame
- Visual feedback — recorded annotations shown semi-transparent, active annotations highlighted with golden border; F1-toggleable key binding overlay
- Session persistence — resume files (
.gamethogram.pkl) saved automatically next to the video; re-running the scorer on the same video restores all previous annotations seamlessly - Autosave — periodic background snapshots (enabled by default, every 5 minutes)
- Built-in analysis — behaviour percentages, bout durations (mean ± SD), and transition probability matrices (pseudo-log colour scale) per animal and globally
- Export — annotation data as text, Excel, MATLAB, or pickle; analysis plots as CSV, PNG, or SVG (text as text in SVG); scored video overlay as MP4 or image sequence
- Portable settings — save/load all animals, behaviours, colours, icons, and key bindings as a single JSON file
- Python 3.9 or later
- A working display (GameThogram uses PyQt5 for the configuration GUI and pygame for the scoring window)
git clone https://github.com/zerotonin/GameThogram.git
cd GameThogram
pip install -e .Tip: Use a virtual environment:
python -m venv .venv source .venv/bin/activate # Linux/macOS .venv\Scripts\activate # Windows pip install -e .
conda env create -f environment.yml
conda activate pyvisor
pip install -e .gamethogram # launch from anywhere after install- Behaviours tab — define animals and their behaviours; pick icons, colours, and compatibility
- Button Assignment tab — select your input device from the dropdown; assign gamepad buttons to behaviours and movie controls (or use "Set default movie bindings")
- Analysis tab — load a video file, then click Run Scorer
- Score — the scorer window opens with your video; press gamepad buttons to toggle behaviours; F1 shows/hides the key binding overlay; close the window when done
- Export — choose a format and click Export Data; or switch to the Results Overview tab for plots and CSV/PNG/SVG export
GameThogram works with any gamepad that pygame/SDL can detect. Plug in your controller before launching so that pygame picks it up at startup.
The "Set default movie bindings" button provides one-click presets for Xbox and PlayStation layouts only. All other controllers (8BitDo, generic USB pads, Nintendo-style controllers, etc.) work perfectly well — you simply assign each button manually using the "assign button" dialog, which detects any button press, stick movement, or trigger pull on any recognised controller.
| Controller | Connection | OS | Status |
|---|---|---|---|
| Xbox 360 | USB | Linux | ✅ Works out of the box |
| Xbox One | USB | Linux | ✅ Works out of the box |
| Xbox Elite Series 2 | USB | Linux | ✅ Works out of the box; paddles register as extra buttons |
| Sony PS5 DualSense | USB | Linux | ✅ Works out of the box |
| CSL PS2-style clone | USB | Linux | ✅ Works out of the box |
| 8BitDo Pro 3 | Bluetooth (S mode) | Linux | ✅ Works after Bluetooth pairing |
| 8BitDo Pro 3 | USB cable | Linux | ❓ Not yet tested reliably |
The 8BitDo Pro 3 works over Bluetooth after a standard pairing procedure:
- Set the switch on the back of the controller to S
- Pair via your system's Bluetooth settings or
bluetoothctl:bluetoothctl power on scan on # Hold the pairing button on the controller until the LED flashes pair XX:XX:XX:XX:XX:XX trust XX:XX:XX:XX:XX:XX connect XX:XX:XX:XX:XX:XX - Launch GameThogram — the controller appears as "Pro Controller" in the device dropdown
- Assign buttons manually (no default preset for this layout)
USB dongle support (S/X and D modes) has not been tested reliably and may depend on your kernel and SDL versions.
- Linux: Most USB gamepads work out of the box. If a controller is not detected, try installing
xboxdrvorxpad. For Bluetooth controllers, ensure the device is paired before launching. - macOS: Xbox controllers may require 360Controller or Bluetooth pairing.
- Windows: Xbox controllers work natively. PlayStation controllers may need DS4Windows.
GameThogram uses pims + PyAV for video I/O: AVI, MP4, MOV, MKV, MPG, WMV, FLV, WebM, M4V, and Norpix SEQ files. Image sequences (JPEG, PNG, TIFF) are also supported.
GameThogram/
├── pyvisor/ # Main package (internal name kept for compatibility)
│ ├── GUI/ # PyQt5 interface
│ │ ├── model/ # Data model (Animal, Behaviour, KeyBindings, …)
│ │ ├── tab_behaviours/ # Behaviour definition tab
│ │ ├── tab_buttons/ # Button assignment tab
│ │ ├── icon_gallery/ # Icon selection dialogs
│ │ ├── tab_analysis.py # Video loading, scorer control, export
│ │ ├── tab_results.py # Analysis plots (matplotlib embedded in Qt)
│ │ ├── main_gui.py # Main window
│ │ └── run_gui.py # Entry point
│ ├── analysis/ # Offline and online analysis modules
│ ├── resources/ # Bundled icons and logo
│ ├── manual_ethology_scorer_2.py # Scorer engine (pygame)
│ ├── MediaHandler.py # Video playback via pims
│ ├── ethogram.py # Ethogram data structure
│ ├── animal_ethogram_2.py # Per-animal frame-level data (pandas)
│ ├── dataIO.py # Save/load/export
│ └── user_input_control.py # Input dispatch
├── docs/ # Sphinx documentation source
├── tests/ # Unit and integration tests
├── pyproject.toml # Modern Python packaging
├── setup.py # Legacy packaging (kept for editable installs)
└── environment.yml # Conda environment specification
- Fork and create a feature branch
- Install dev dependencies:
pip install -e .[dev] - Run tests:
pytest - Open a pull request
- GUI does not start — verify PyQt5 is installed and you are using Python 3.9+
- Controller not detected — confirm the OS recognises the gamepad (
jstest-gtkon Linux); plug in before launching - Video won't load — ensure PyAV is installed:
pip install av - Reset settings — delete
~/.local/share/pyVISOR/(Linux) or equivalent on your platform
Bart Geurten, Ilyas Kuhlemann
GPL-3.0-or-later