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.
- 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
Prerequisites: Python 3.8+, pip
Install dependencies:
pip install -r requirements.txtRun:
python ethoscore.py- Launch the application
- Select a video file (MP4, AVI, MOV, MKV, WMV)
- Label frames using behavior buttons or keyboard shortcuts
- Navigate with arrow keys, mouse or gamepad
- Annotations auto-save as CSV files
- 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
- 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
- Left Analog Stick: Frame navigation
- Buttons: Fully mappable to behaviors, erasing, undoing, or fast-forwarding using the in-app mapping utility
- 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
Annotations are saved as CSV files named after your video.
Pro Tip: Any annotation CSV can be used as a Behavior Template via File > Load Behaviors. This will automatically set up your behavior buttons using the CSV's column headers.
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)
- Selective erasing in multitrack mode for controllers