How it works

What each asset gets

Field Example
Description House Finch — Bird Buddy feeder "BackyardFeeder" (Springfield, United States), 14 Oct 2026, 8:46 AM. Recogniser confidence: high.
Capture time the media's createdAt from Bird Buddy
GPS (--gps) your coordinates
Tags (--tags) Bird Buddy/Species/House Finch, Bird Buddy/Feeder/BackyardFeeder, Bird Buddy/City/Springfield
File name birdbuddy-<media id>.jpg or .mp4
  • Bird Buddy files have no EXIF data. The bird data lives only in Immich: in its database and in the XMP sidecar file it writes next to the photo. This sidecar should work with most photo apps.
  • The confidence sentence appears only when birdpal itself triggered the identification in that run. Bird Buddy shows the confidence only at that moment.
  • Immich names the place from the GPS point. That place can differ from the city in the description and the city tag, which come from Bird Buddy.

Note: to see tags in Immich, turn them on first: Account Settings → Features → Tags.

A run, step by step

  1. Check the Immich key and log in to Bird Buddy.
  2. With --triggerID: trigger identification on inbox postcards.
  3. With --sync: collect the inbox postcards, so their media go into the species collections.
  4. Read the full catalog: all collections plus never-recognized feed media, newest first.
  5. Work through the catalog in batches (default 100). For each batch: look up each media in Immich by file name, download the rest and check their checksums, upload what is new, write tags first and then description, capture time and GPS, and delete the temporary files. Without --full, stop after a batch with nothing new.
  6. Wait 15 seconds, read every asset it wrote back from Immich, and re-apply anything that is missing (up to two repairs).

Errors and retries

  • Bird Buddy API errors (5xx): birdpal tries the request two more times, after 2 and 4 seconds. Bird Buddy's gateway returns a passing 502 now and then.
  • Expired token: on a GraphQL or authentication error, birdpal refreshes its token once and tries again.
  • Download errors (5xx): birdpal then fetches the media's thumbnail, which Bird Buddy makes from the same stored file. If the thumbnail also fails, the file is broken at Bird Buddy: birdpal logs broken at Bird Buddy, skipped and does not count a failure. If the thumbnail works, it was a passing outage: birdpal counts a failure (exit code 1) and tries again next run.
  • Immich background jobs: after each change, Immich rewrites the asset's XMP sidecar and reads it back, which can undo a write made in between. birdpal writes tags before the description, and checks and repairs every write at the end of the run.
  • Media in the Immich trash: birdpal uploads them again, which restores them.

Limits

  • Without --full, birdpal assumes new media appear at the newest end of the catalog. Run --full from time to time to catch anything else.
  • --update overwrites descriptions that other tools wrote.
  • Bird Buddy's API is not documented. Bird Buddy can change it at any time.