neuropose/benchmarks

benchmarks/

Workflow convenience directory for performance benchmarking. Drop videos into benchmarks/videos/, then rsync the whole repo to a research machine — the videos travel alongside the code without needing a second path on either end.

This directory is not a persistent data store. It is a local scratch area for ephemeral benchmark inputs. Everything under benchmarks/videos/ is gitignored (see the .gitignore rules and the per-directory README) so committing videos by accident is mechanically prevented.

Policy

Only put benchmark test videos here. Never subject or clinical recordings. Subject data still goes through $XDG_DATA_HOME/neuropose/ via the normal interfacer workflow, and that rule is load-bearing for the project's data-handling posture.

The distinction in practice:

Type of video	Goes here	Goes to $XDG_DATA_HOME
Synthetic test videos (gradient frames, etc.)	Yes	No
Public-domain reference footage	Yes	No
Recordings you personally filmed for benchmarking	Yes	No
Anything a clinician recorded	No	Yes
Anything with an identifiable subject	No	Yes
Anything IRB-gated	No	Yes

When in doubt, route through $XDG_DATA_HOME. That path has cross-machine isolation by design; this directory does not.

Usage

Assuming you have a short test video to work with:

$ cp ~/Downloads/short_clip.mp4 benchmarks/videos/
$ uv run neuropose benchmark benchmarks/videos/short_clip.mp4 \
    --repeats 5 --warmup-frames 3 \
    --output benchmarks/videos/short_clip_run.json

The *.json benchmark output is also gitignored — .json is not a tracked extension inside benchmarks/videos/ because only README.md is whitelisted in that directory.

Rsyncing to the research Mac

The directory layout is designed so one rsync path covers both code and videos:

$ rsync -av --delete \
    --exclude='.venv/' \
    --exclude='site/' \
    --exclude='.git/' \
    ~/Repos/research/brown/shu/neuropose/ \
    mac.local:~/Repos/research/brown/shu/neuropose/

After the sync, the videos in benchmarks/videos/ on the Mac are identical to the ones on Linux, so a benchmark run on the Mac can reference the same filename the Linux report does — makes cross- machine comparisons trivial.

Tips:

• Add --exclude='benchmarks/videos/*.json' if you want to keep per-machine benchmark results isolated.
• --delete makes the target exactly mirror the source. Without it, old files on the target persist — safer but surprising.
• For one-off pushes, scp benchmarks/videos/clip.mp4 mac.local:~/Repos/research/brown/shu/neuropose/benchmarks/videos/ works without touching the rest of the repo.

Bulk intake via neuropose ingest

When you have a whole batch of recordings instead of a single benchmark clip, drop the zip archive anywhere you like (the benchmarks/videos/ directory is fine for transient test zips) and let neuropose ingest unpack them into per-video job directories for the running daemon:

$ uv run neuropose ingest benchmarks/videos/session_2026-04-15.zip
ingested 12 job(s) from benchmarks/videos/session_2026-04-15.zip (1842.3 MB, 2 non-video member(s) skipped)
  patient_001_trial_01/trial_01.mp4
  patient_001_trial_02/trial_02.mp4
  ...

Each video becomes its own $data_dir/in/<job_name>/ directory, and the daemon picks them up on its next poll with no further operator action. Pass --force to overwrite existing job directories with the same derived names. See the neuropose ingest --help output for the full flag surface and neuropose.ingest for the library API.

Reminder: the benchmarks/videos/ directory is for benchmark test data only, including the zip archives you pass to ingest. Actual clinical recordings should not transit through this directory — route those through $XDG_DATA_HOME instead.

Directory layout

benchmarks/
├── README.md           # this file (tracked)
└── videos/
    ├── README.md       # placeholder to keep the directory tracked
    └── <your-clip>.mp4 # ignored