Desktop app
Record experiments from USB cameras and analyze videos, without code. There are two apps over one engine, and they share everything they store:
| App | Systems | Notes |
|---|---|---|
| AnimalPose (SwiftUI) | macOS 14+ on Apple Silicon | native Mac app; Liquid Glass on macOS 26 |
| animalpose-gui (egui) | Windows, Linux (and macOS) | same pages and settings |
← Overview · Quick start · Results
The window
| Area | What it holds |
|---|---|
| Process (sidebar) | the videos to analyze; a badge counts them |
| Live (sidebar) | camera previews and recording; a badge counts active previews |
| Profile (sidebar) | the profile in use; its menu switches profiles or opens Edit Profiles… (not while a job runs) |
| Results (sidebar) | the 5 most recent result folders: click to open; right-click for Open Log (and Show in Finder on macOS) |
| progress card (sidebar, bottom) | "Video N of M" while a batch runs |
| status banner (top) | messages fade after 5 seconds; hover to keep one; Open jumps to the result; warnings are orange |
| Settings (⌘, / Ctrl+,) | General, Profiles, Configs; locked while a job runs |
Keyboard shortcuts use ⌘ on macOS and Ctrl elsewhere: ⌘O add videos, ⇧⌘P pause or resume, ⌘. stop.
Profiles
A profile is everything one experiment needs, so every session is set up the same way. Edit them in Settings → Profiles; every change saves at once.
| Section | Setting | Meaning |
|---|---|---|
| Name | rename with Enter; Use makes it the profile in use | |
| Pipeline | Config | the pipeline config (Configuration); Default is the shipped one |
| Detector, Pose, Temporal, Behavior | the networks; From Config uses the ones the config names | |
| Classify Behavior | off skips the behavior network | |
| Arena | Arena Detector | finds the arena's floor and zones for experiment scoring (optional) |
| Camera Model | a rig's calibration (cams.json) for 3D; Import… adds one; lists the model's camera names |
|
| Camera Names | the label of each connected camera (shown when cameras are found) | |
| Stages | name, seconds, Wait | the timed recording plan, e.g. Accustomization 60 s then Experiment 300 s; Wait pauses after a stage until Continue |
+ creates a profile, Duplicate copies one ("X Copy"), Delete removes one (at least one must remain). Switching profiles loads its networks in the background.
Sample profiles
On every launch the app installs the sample profiles it ships with, with their configs, camera models and networks: Three Chamber (four variants), Open Field (two), Grooming and Plus Maze.
- Files are checked against their SHA-256 first; if any is damaged, nothing is installed and the log says why.
- A sample you edited, or a file of your own with the same name, is never overwritten.
- A sample you deleted is not brought back.
- A sample you did not change is updated when a new version of the app ships a newer one.
Live: preview and record
- Tick the cameras to use (Refresh Cameras looks again). The first queued video can also play as a camera (Play as a Camera), to try things without hardware.
- Press Preview. Each tile shows its view label, the camera's name, the animals found and the time per frame. Pose Overlay draws the keypoints.
- Name each view: click the tile's label ("Camera 1", "Camera 2", …) and type, or, with a camera model in the profile, pick the model's camera. The label becomes the clip's file name, which is how processing knows which view is which. Every camera needs its own label.
- Optionally type a Recording Name, then:
- Record records until Stop.
- Timed runs the profile's stages, with a clock and a bar counting down each stage. After a stage marked Wait, recording continues into a separate clip until you press Continue. The recording ends by itself after the last stage.
Recording needs FFmpeg. Recording has priority over analysis: every frame goes to its camera's file in order, and capture waits rather than drops frames if the disk is slow. Pose inference pauses while recording. Cameras open at their highest frame rate and run freely (there is no hardware synchronization).
Where recordings go
~/AnimalPose/recordings/<name>-<time>-<n>/
├── session.json written at the start: stages, sources, which file is which view
├── recording.json written at the end: clips, frame counts, first/last frame times, fps
├── 01-Accustomization/
│ ├── Camera 1.mp4 one MP4 per view
│ └── Camera 2.mp4
├── 01-Accustomization-waiting/ a Wait period, when there was one
└── 02-Experiment/
└── …
A plain Record writes manual/ instead of the stage folders. Settings → General →
Recordings moves the folder. See Results → Recordings.
Analyze Recording (Process toolbar; on macOS also Analysis → Analyze Last Recording)
analyzes the last recording of this session in place: each stage gets an analysis/ folder,
fused into 3D when the profile has a camera model, otherwise one folder per view.
Process: analyze videos
- Add videos: drop files or folders on the window, or + → Videos… / Folders… (⌘O).
Folders are searched recursively for
.mp4 .mov .m4v .avi .mkv .webm .ogv .mpg .mpeg .wmv; hidden files and folders that already hold results are skipped. - Save To: Next to Video or a folder of your choice.
- Press Process.
| You added | Results |
|---|---|
| one video | <video name>-analysis/ |
| several videos | animalpose-batch-<time>-<n>/, with a folder per video and batch.json listing each video's result or error |
The sidebar and page show progress: overall ("Video 2 of 5") and the current stage (analyzing, refining tracks, saving, writing the overlay). Pause, Resume and Stop act at the next step. Stopping keeps every finished video and discards the one in progress. A video that fails is logged and the batch continues.
Multiview (several cameras)
Turn on Multiview (needs a camera model in the profile). Each folder's videos are one session:
- Videos are matched to cameras by file name (
Camera 1.mp4→ the camera named "Camera 1", ignoring case and punctuation), otherwise by the number in the name (View-1,cam_3,camera-02). - A folder must hold one video per camera; a folder with a single video is analyzed on its own.
- The list shows each video's camera, and problems in orange before you start.
Each session is fused into 3D; see Multiview and Results → Multiview.
Settings
General
| Setting | Meaning |
|---|---|
| Processed Videos | default results folder: Next to Video or Other… |
| Recordings | where recordings go |
| Logs | Show in Folder opens ~/AnimalPose/logs |
| Library | Show in Folder opens ~/AnimalPose; Import → Model… / Config… / Folder… |
Imports:
- Model… (
.ptor.safetensors): the file must be an AnimalPose checkpoint (it records its kind: detector, pose, temporal, behavior or arena). It becomes the profile's model of that kind. - Config…: copied with its
extends:chain flattened; the profile's selected models are used. - Folder…: every config and checkpoint inside, with the configs relinked to the imported checkpoints.
Configs
Edits a pipeline config with controls: General (device), Detection, Pose, Background, Tracking (maximum animals, identity method), Smoothing, Behavior, Camera Drift and Experiment (none, open field, plus maze, three chamber, grooming, with their thresholds). Changes save at once.
The Default config is read-only: Duplicate… makes an editable copy that inherits
everything from it (extends:) until you change a value. Checkpoint paths and network input
sizes are not editable here. A config used by a profile cannot be deleted.
The library: ~/AnimalPose
Both apps keep everything here; back it up to keep your setup.
| Path | Contents |
|---|---|
settings.json |
the profile in use, recent results, folder choices, which samples were installed |
profiles/*.json |
profiles |
configs/*.yaml |
your configs |
models/<kind>/ |
imported networks: detector, pose, temporal, behavior, arena |
cameras/*.json |
camera models; cameras/<model>.references/ holds each camera's reference picture for drift correction |
zones/ |
arena layouts found in videos (and hand-made ones, which always win) |
recordings/ |
recordings, unless moved |
logs/<date>.log |
a daily log; each job also copies its part into its result folder as animalpose.log |
Hardware and FFmpeg
- On Apple Silicon the networks run on the GPU through Metal, about 6× faster than the CPU. Elsewhere they run on all CPU cores.
- Video needs FFmpeg. Without it, Process shows "FFmpeg Not Installed" and recording asks you
to install it. The apps look for it through
ANIMALPOSE_FFMPEG/ANIMALPOSE_FFPROBE, then beside the app, then onPATH(plus Homebrew's folders on macOS). See Quick start → Install FFmpeg.
Differences between the two apps
| macOS app | egui app | |
|---|---|---|
| Menu-bar commands (e.g. Analysis → Analyze Last Recording) | yes | — |
| Select several videos and press Delete | yes | — |
| Drop files anywhere in the window | on the Process page | anywhere |
--check-samples [DIR] (checks the bundled samples by loading and running each profile) |
— | yes |