DeskamiA small companion on your desk

Export format

Export, part of Deskami Plus, writes the same minute-by-minute record Deskami keeps on your Mac. Nothing is added, estimated or filled in. This page describes what is in the file.

Conventions

  • An empty cell in CSV, or null in JSON, means not measured. A 0 means measured, and it was zero.
  • Column names are in English in every language and fixed; they change only together with a new export_version.
  • The files are UTF-8. CSV is comma-separated with a header row.
  • Times are UTC in ISO 8601, such as 2026-09-28T07:41:00Z. Dates are YYYY-MM-DD, the calendar day the minute was recorded under.
  • Decimals use a point, never a thousands separator. Booleans are true and false.
  • There is one row for each minute in which Deskami recorded anything, and no row for minutes it did not.

Minute columns

The CSV has these columns, in this order; in JSON the same fields make up each minute. The name in brackets is the column in the raw database file.

  • minute_utc — time. The start of the minute, in UTC. (minute_utc, in Unix seconds)
  • local_day — date. The calendar day this minute belongs to, in the time zone the Mac was in at the time. It is fixed when written; a later time-zone change does not move it. (day_key)
  • setup_id — integer. The setup in use: a camera plus a display arrangement. In JSON the setups are listed under setups. (profile_id)
  • seconds_at_desk — 0 to 60. Seconds the camera saw you in this minute. With camera_off false, 0 means the camera was on and did not see you. (present_s)
  • posture_deviation — number, 0 or more. How far your head and shoulders sat below your own reference, averaged over the minute, as a multiple of the reminder threshold in force at the time: 0 at the reference, 1 at the threshold. Empty when posture was not measured. (posture_dev)
  • posture_peak — number, 0 or more. The largest value of the same measure within the minute. (posture_peak)
  • distance_deviation — number, 0 or more. How much closer your face was to the screen than at your reference, on the same scale, read from the spacing of your eyes in the picture. (distance_dev)
  • blinks — integer. Blinks counted while the eyes could be measured. Empty when they could not. (blinks)
  • incomplete_blinks — integer. Blinks whose narrowest moment did not come close enough to closed. Empty when no judgement was possible. (incomplete_blinks)
  • head_pitch_degrees — number. Average head pitch in degrees as the camera reports it: relative to the camera, not to your reference. (head_pitch)
  • confidence — 0 to 1. Average face-detection confidence. (confidence)
  • light — 0 to 1. Average brightness of the face region, from 0 dark to 1 bright. Not the room. (light)
  • eyes_measured — boolean. The eyes could be measured at least once in this minute. When false, blinks, incomplete_blinks and eye_observed_seconds are empty. (eye_valid)
  • eye_observed_seconds — 0 to 60. Seconds the eyes were actually watched. Blinks per minute is blinks × 60 ÷ eye_observed_seconds. (eye_observed_s)
  • look_aways — integer. Completed looks into the distance, the 20-20-20 habit. Empty when looking away was not being measured. (gaze_breaks)
  • camera_off — boolean. The camera was off for this minute: you turned it off, another app held it, or permission was removed. The camera columns are then empty; the app and activity columns may still be filled. (camera_off)
  • declared_break — boolean. You told Deskami you were on a break. The minute counts as away from the desk, whatever the camera saw. (declared_break)
  • front_app — text. The bundle identifier of the app in front for most of the minute, such as com.apple.Safari. Empty when that reading was switched off, the screen was locked or nothing was in front. Never a window title. (app_id)
  • app_switches — integer. How many times the app in front changed in this minute. (app_switches)
  • active_seconds — 0 to 60. Seconds in which the keyboard or mouse had been touched within the last 15 seconds. Only the time since the last event is read, never the keys. Empty when that reading was switched off. (active_s)
  • call_seconds — 0 to 60. Seconds in which a call app was in front, or one app had the microphone and the speaker open together. Empty when not measured, including every minute recorded before Deskami measured this. (meeting_s)

JSON

The JSON file is one object. It starts with a header: export_version, app_version, exported_at, time_zone (at the time of export), database_schema_version, range (kind, from, to) and setups (id, camera_name, created_at).

Then comes days, one object for each recorded day in the range. Each day carries its own summary, minutes and reminders:

  • local_day and minutes_at_desk, the sum of seconds_at_desk divided by 60.
  • breaks: stretches of 5 minutes or more away from the desk and under 2 hours, between two stretches at the desk. Time with the camera off counts neither way.
  • posture_fine_minutes (posture_deviation below 1) and posture_attention_minutes (1 or above).
  • blink_rate: blinks per minute over the time the eyes were watched; null under one minute of watching.
  • incomplete_blink_ratio: null when too few blinks could be judged.
  • reminders_by_signal: reminders shown, counted by signal.
  • minutes: the minute columns above, one object per minute.
  • reminders: one object per reminder, with time_utc, local_day, setup_id, signal (posture, distance, blink, incompleteBlink or gaze), build_up_seconds (time over the threshold before the reminder), recover_seconds (time until back under it; null when measuring stopped first), asked (whether the question about your reference was shown) and answer (null when not asked, otherwise true or false).

PDF

The PDF is not a table: it is the summary itself — the day summary, the week or the month — printed on one page exactly as it looks on screen. Every number in it is the number on screen.

The raw file

Settings › General › Data › Show in Finder reveals history.sqlite, next to history.sqlite-wal and history.sqlite-shm. While Deskami is running, the newest minutes may still be in the -wal file; copy all three files, or quit Deskami first. If you delete them while Deskami is running, it starts a new, empty record within a few seconds. Export always writes a complete snapshot. What the database holds is listed on the privacy page.