Skip to content

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

  1. 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.
  2. 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.
  3. 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.
  4. Optionally type a Recording Name, then:
  5. Record records until Stop.
  6. 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

  1. 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.
  2. Save To: Next to Video or a folder of your choice.
  3. 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… (.pt or .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 on PATH (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