Ethoscore : Video Behavior Annotator

Ethoscore is a video annotation tool for behavioral analysis, built with PySide6 and OpenCV. Annotate video footage with specific behaviors using keyboard, mouse, and gamepad controls.

Features

• Multi-Input Support: Keyboard shortcuts, mouse, and gamepad controls to keep muscle cramps away
• Multitrack Annotation: Label multiple behaviors on the same frame simultaneously
• Undo Support: Easily revert recent annotation changes with Ctrl+Z
• Timeline Interface: Interactive timeline with zoom/click/drag navigation
• Behavior Annotation: Label frames with customizable behaviors
• Optional Gamification: Get points according to the duration of the labels and even combos if executed quickly!
• Auto-Save: Configurable automatic saving
• Color-Coded Labels: Visual behavior identification in the timeline and preview bars for previous/next frame
• CSV Export: Classic frame by frame matrix

Installation

Prerequisites: Python 3.8+, pip

Install dependencies:

pip install -r requirements.txt

Run:

python ethoscore.py

Usage

1. Launch the application
2. Select a video file (MP4, AVI, MOV, MKV, WMV)
3. Label frames using behavior buttons or keyboard shortcuts
4. Navigate with arrow keys, mouse or gamepad
5. Annotations auto-save as CSV files

Keyboard controls

• Arrow Keys: Navigate frames
• Shift + Arrows: Jump larger increments (configurable)
• Number Keys: Toggle behaviors
• Escape: Remove labels
• Ctrl+Z: Undo last action
• Ctrl+S: Save
• Ctrl+O: Load video
• Ctrl+N: Load next video

Mouse controls

• Timeline dragging: Move through frames
• Left click on label: extend the label to the actual frame (left or right)
• Right click on label: delete the label / delete the section of the label until the actual frame

Gamepad

• Left Analog Stick: Frame navigation
• Buttons: Fully mappable to behaviors, erasing, undoing, or fast-forwarding using the in-app mapping utility

Settings

• Input Settings: Keyboard shortcuts and advanced controller mappings (deadzones, sensitivity)
• General Settings: Auto-save, UI preferences, Multitrack toggle
• Rescan Controllers: If you controller was disconnected, relink it here instead of restarting ethoscore

Data Format

Annotations saved as CSV with video filename. Here is a simple example:

Frames,nose-to-nose,nose-to-body,anogenital,passive,rearing,fighting,mounting
1,0,0,0,0,0,0,0
2,1,0,0,0,0,0,0
...

• Frames: 1-based frame numbers
• Behavior Columns: Binary indicators (1=present, 0=absent)

Roadmap

• Selective erasing in multitrack mode for controllers