slouchbuddy 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (48) hide show
  1. slouchbuddy-0.1.0/LICENSE +21 -0
  2. slouchbuddy-0.1.0/PKG-INFO +185 -0
  3. slouchbuddy-0.1.0/README.md +134 -0
  4. slouchbuddy-0.1.0/pyproject.toml +47 -0
  5. slouchbuddy-0.1.0/setup.cfg +4 -0
  6. slouchbuddy-0.1.0/src/slouchbuddy/__init__.py +3 -0
  7. slouchbuddy-0.1.0/src/slouchbuddy/alert_tracker.py +46 -0
  8. slouchbuddy-0.1.0/src/slouchbuddy/app.py +227 -0
  9. slouchbuddy-0.1.0/src/slouchbuddy/buddy.py +164 -0
  10. slouchbuddy-0.1.0/src/slouchbuddy/buddy_brain.py +139 -0
  11. slouchbuddy-0.1.0/src/slouchbuddy/calibration.py +27 -0
  12. slouchbuddy-0.1.0/src/slouchbuddy/cli.py +87 -0
  13. slouchbuddy-0.1.0/src/slouchbuddy/config.py +63 -0
  14. slouchbuddy-0.1.0/src/slouchbuddy/dashboard.py +292 -0
  15. slouchbuddy-0.1.0/src/slouchbuddy/dashboard_art.py +39 -0
  16. slouchbuddy-0.1.0/src/slouchbuddy/dashboard_data.py +121 -0
  17. slouchbuddy-0.1.0/src/slouchbuddy/dashboard_theme.py +220 -0
  18. slouchbuddy-0.1.0/src/slouchbuddy/ipc.py +63 -0
  19. slouchbuddy-0.1.0/src/slouchbuddy/koala.py +187 -0
  20. slouchbuddy-0.1.0/src/slouchbuddy/launch_agent.py +122 -0
  21. slouchbuddy-0.1.0/src/slouchbuddy/launcher.py +33 -0
  22. slouchbuddy-0.1.0/src/slouchbuddy/menubar.py +155 -0
  23. slouchbuddy-0.1.0/src/slouchbuddy/notifications.py +99 -0
  24. slouchbuddy-0.1.0/src/slouchbuddy/pose_detection.py +96 -0
  25. slouchbuddy-0.1.0/src/slouchbuddy/posture_analyzer.py +126 -0
  26. slouchbuddy-0.1.0/src/slouchbuddy/session_logger.py +37 -0
  27. slouchbuddy-0.1.0/src/slouchbuddy/session_summary.py +80 -0
  28. slouchbuddy-0.1.0/src/slouchbuddy/ui_overlay.py +161 -0
  29. slouchbuddy-0.1.0/src/slouchbuddy/wake_reminder.py +26 -0
  30. slouchbuddy-0.1.0/src/slouchbuddy.egg-info/PKG-INFO +185 -0
  31. slouchbuddy-0.1.0/src/slouchbuddy.egg-info/SOURCES.txt +46 -0
  32. slouchbuddy-0.1.0/src/slouchbuddy.egg-info/dependency_links.txt +1 -0
  33. slouchbuddy-0.1.0/src/slouchbuddy.egg-info/entry_points.txt +2 -0
  34. slouchbuddy-0.1.0/src/slouchbuddy.egg-info/requires.txt +15 -0
  35. slouchbuddy-0.1.0/src/slouchbuddy.egg-info/top_level.txt +1 -0
  36. slouchbuddy-0.1.0/tests/test_alert_tracker.py +70 -0
  37. slouchbuddy-0.1.0/tests/test_buddy_brain.py +151 -0
  38. slouchbuddy-0.1.0/tests/test_calibration.py +22 -0
  39. slouchbuddy-0.1.0/tests/test_cli_and_launch_agent.py +61 -0
  40. slouchbuddy-0.1.0/tests/test_dashboard_art.py +26 -0
  41. slouchbuddy-0.1.0/tests/test_dashboard_data.py +79 -0
  42. slouchbuddy-0.1.0/tests/test_ipc.py +37 -0
  43. slouchbuddy-0.1.0/tests/test_koala.py +37 -0
  44. slouchbuddy-0.1.0/tests/test_menubar_title.py +49 -0
  45. slouchbuddy-0.1.0/tests/test_posture_analyzer.py +97 -0
  46. slouchbuddy-0.1.0/tests/test_session_logging.py +54 -0
  47. slouchbuddy-0.1.0/tests/test_sound.py +51 -0
  48. slouchbuddy-0.1.0/tests/test_wake_reminder.py +28 -0
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Hardi Parikh
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,185 @@
1
+ Metadata-Version: 2.4
2
+ Name: slouchbuddy
3
+ Version: 0.1.0
4
+ Summary: Slouchbuddy: real-time desk posture coaching from your webcam, with calibration, alerts and an analytics dashboard.
5
+ Author: Hardi Parikh
6
+ License: MIT License
7
+
8
+ Copyright (c) 2026 Hardi Parikh
9
+
10
+ Permission is hereby granted, free of charge, to any person obtaining a copy
11
+ of this software and associated documentation files (the "Software"), to deal
12
+ in the Software without restriction, including without limitation the rights
13
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
14
+ copies of the Software, and to permit persons to whom the Software is
15
+ furnished to do so, subject to the following conditions:
16
+
17
+ The above copyright notice and this permission notice shall be included in all
18
+ copies or substantial portions of the Software.
19
+
20
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
21
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
22
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
23
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
24
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
25
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
26
+ SOFTWARE.
27
+
28
+ Project-URL: Homepage, https://github.com/HardiParikh1/slouchbuddy
29
+ Project-URL: Source, https://github.com/HardiParikh1/slouchbuddy
30
+ Project-URL: Issues, https://github.com/HardiParikh1/slouchbuddy/issues
31
+ Keywords: posture,computer-vision,mediapipe,opencv,health
32
+ Classifier: Programming Language :: Python :: 3
33
+ Classifier: Topic :: Multimedia :: Video :: Capture
34
+ Classifier: Intended Audience :: End Users/Desktop
35
+ Requires-Python: <3.13,>=3.9
36
+ Description-Content-Type: text/markdown
37
+ License-File: LICENSE
38
+ Requires-Dist: mediapipe<=0.10.21,>=0.10.14
39
+ Requires-Dist: pillow>=10.1
40
+ Requires-Dist: opencv-contrib-python>=4.8
41
+ Requires-Dist: numpy<2,>=1.26
42
+ Requires-Dist: pandas>=2.0
43
+ Requires-Dist: plotly>=5.18
44
+ Requires-Dist: streamlit>=1.30
45
+ Requires-Dist: sounddevice>=0.4
46
+ Requires-Dist: plyer>=2.1
47
+ Requires-Dist: rumps>=0.4; sys_platform == "darwin"
48
+ Provides-Extra: dev
49
+ Requires-Dist: pytest>=8; extra == "dev"
50
+ Dynamic: license-file
51
+
52
+ # Slouchbuddy 🐨
53
+
54
+ [![CI](https://github.com/HardiParikh1/slouchbuddy/actions/workflows/ci.yml/badge.svg)](https://github.com/HardiParikh1/slouchbuddy/actions/workflows/ci.yml)
55
+ [![PyPI](https://img.shields.io/pypi/v/slouchbuddy)](https://pypi.org/project/slouchbuddy/)
56
+
57
+ **Your slouch-fixing desk buddy.** A real-time posture coach for people who work from home: it watches you through your webcam, learns what *your* good posture looks like, and an animated koala in your menu bar nudges you (kindly) when you've been slouching for too long.
58
+
59
+ ![The Slouchbuddy dashboard](https://raw.githubusercontent.com/HardiParikh1/slouchbuddy/main/docs/dashboard.png)
60
+
61
+ ## Why I built this
62
+
63
+ After about six months of working from home, my posture was wrecked. No office chair, no colleagues walking past, just me, a laptop and hours of slowly sinking into the desk. I knew I should sit up straight, but nothing was reminding me, and by the time I noticed, I'd been hunched over for an hour.
64
+
65
+ Posture apps I looked at either wanted a wearable or only gave a generic "sit up" timer. I figured the better fix was to build the thing I actually wanted: a live monitor that sees how I'm sitting right now, compares it to my own upright baseline, and taps me on the shoulder only when it matters.
66
+
67
+ It started as a webcam experiment and grew into a small menu bar app, an analytics dashboard so I can see whether I'm actually improving, and a koala that hangs out in my menu bar so that working alone is a little less lonely (and the nagging is a lot friendlier).
68
+
69
+ ## Features
70
+
71
+ - **Real-time pose tracking** (MediaPipe) with a live camera view you can open when you want it
72
+ - **Per-user calibration:** your upright pose is the baseline, so it adapts to your camera angle and body proportions
73
+ - **Five posture checks:** uneven shoulders, head forward, head tilt and leaning toward the screen (all relative to your baseline), plus an **absolute** check for head level with or below the shoulders that ignores calibration
74
+ - **A 0-100 posture score,** weighted across those checks
75
+ - **A koala buddy** that reacts to how you sit (happy, lazy-slouching, oops, curious, sleepy, coffee break). On macOS it lives in the menu bar; anything it has to say arrives as a notification: specific tips ("shoulders are uneven", "chin back"), cheers when you recover, good-streak milestones and break reminders
76
+ - **Gentle alerts:** only after posture stays bad for a sustained period, with a cooldown, a soft chime (configurable) and no nagging
77
+ - **Break reminders** and a friendly "sit up" notification whenever your laptop wakes from sleep
78
+ - **A cosy analytics dashboard** (Streamlit + Plotly) with day / week / month / year views, good-vs-bad percentages and your most frequent issues
79
+ - **Starts at login** on macOS, Windows and Linux
80
+ - **Private by design:** everything runs locally; no video or data leaves your machine, and pausing releases the camera entirely
81
+
82
+ ## Install
83
+
84
+ Requires Python 3.9-3.12 and a webcam.
85
+
86
+ ```bash
87
+ pip install slouchbuddy
88
+ ```
89
+
90
+ Or straight from GitHub: `pip install git+https://github.com/HardiParikh1/slouchbuddy.git`. From a clone: `pip install .`, or `pip install -e ".[dev]"` for development.
91
+
92
+ ## Usage
93
+
94
+ ```bash
95
+ slouchbuddy # macOS: koala in the menu bar. Windows/Linux: the koala card
96
+ slouchbuddy dashboard # analytics dashboard in your browser
97
+ slouchbuddy run # plain camera window (C = calibrate, B = break taken, Q = quit)
98
+ slouchbuddy buddy # the on-screen koala card (Windows/Linux)
99
+ slouchbuddy menubar # the menu bar koala (macOS)
100
+ slouchbuddy test-sound # hear the alert sound
101
+ slouchbuddy install-login / uninstall-login
102
+ ```
103
+
104
+ **First run:** sit up straight as you would at your desk, then choose **Calibrate** from the koala's menu. If the wrong camera opens (e.g. an iPhone through Continuity Camera), set `CAMERA_INDEX=1` (or 2, ...), or use `slouchbuddy install-login --camera 1` for the login item.
105
+
106
+ ### The koala buddy
107
+
108
+ On macOS the koala lives **only in the menu bar**, animated next to your live score and changing mood with your posture. Nothing is drawn over your screen. Click it to calibrate, take a break, pause (which turns the camera off), open the camera view or open the dashboard.
109
+
110
+ On Windows and Linux there's no menu bar koala, so `slouchbuddy` opens a small koala card in the top-right corner of your screen instead (drag it anywhere, right-click for the same menu).
111
+
112
+ The koala is drawn entirely in code ([`koala.py`](https://github.com/HardiParikh1/slouchbuddy/blob/main/src/slouchbuddy/koala.py)), so there are no image assets, and its personality is a small, tested state machine ([`buddy_brain.py`](https://github.com/HardiParikh1/slouchbuddy/blob/main/src/slouchbuddy/buddy_brain.py)): it waits before commenting, doesn't repeat itself, and only praises a recovery that was worth praising.
113
+
114
+ ### The dashboard
115
+
116
+ `slouchbuddy dashboard` opens a cosy eucalyptus-grove page (screenshot at the top) (light and dark themes) with a koala whose mood follows your average score, soft cards, drifting leaves, and:
117
+
118
+ - the score over time by **day, week, month or year**, with a picker for the exact period
119
+ - good-posture percentage, longest bad streak and sessions tracked
120
+ - your most frequent issues and a session-by-session trend
121
+
122
+ ### Alert sound
123
+
124
+ Alerts play a soft two-note chime. Hear the options with `slouchbuddy test-sound chime` (or `beep`, `Glass`, `Pop`, `Ping`, ...) and choose one with `ALERT_SOUND` in [`config.py`](https://github.com/HardiParikh1/slouchbuddy/blob/main/src/slouchbuddy/config.py): `"chime"`, `"beep"`, `"off"`, or the name of a macOS system sound.
125
+
126
+ ### Windows and Linux
127
+
128
+ Everything works on all three platforms except the menu bar koala (macOS only): the monitor, the on-screen koala card, notifications and the dashboard. `install-login` registers startup via the registry (Windows) or an autostart entry (Linux). macOS is where it's developed and used daily; CI runs the tests on all three systems, but the Windows and Linux camera and window behaviour is untested on real machines, so bug reports are very welcome.
129
+
130
+ ### Where data is stored
131
+
132
+ Calibration and session logs live in `~/.slouchbuddy/data/` (override with `SLOUCHBUDDY_HOME`). When running from a source checkout they stay in the repo's `data/` folder.
133
+
134
+ ## How it works
135
+
136
+ ```
137
+ webcam frame -> MediaPipe Pose (33 landmarks) -> PostureDetector (metrics)
138
+ -> analyze_posture(current, baseline) -> status + score
139
+ -> BadPostureTracker (sustained-bad + cooldown) -> chime
140
+ -> status file -> koala (menu bar / card) -> BuddyBrain -> mood + notification
141
+ -> SessionLogger (CSV) -> dashboard
142
+ ```
143
+
144
+ The camera runs in a background process; the menu bar app and the koala card are thin front ends that read its status and send it commands (calibrate, pause, ...) through small files ([`ipc.py`](https://github.com/HardiParikh1/slouchbuddy/blob/main/src/slouchbuddy/ipc.py)).
145
+
146
+ | Module | Responsibility |
147
+ | --- | --- |
148
+ | `pose_detection.py` | Turns landmarks into normalized metrics (shoulder imbalance, head offset, tilt, mouth width, head-above-shoulders) |
149
+ | `posture_analyzer.py` | Compares metrics to the calibrated baseline; produces the status and weighted score |
150
+ | `alert_tracker.py` | Pure state machine for "bad for N seconds" plus alert cooldown (injectable clock) |
151
+ | `app.py` | The camera loop; runs in the foreground or hidden in the background |
152
+ | `koala.py` | Draws the animated koala (Pillow): six moods shared by the menu bar, the card and the dashboard |
153
+ | `buddy_brain.py` | The koala's personality: monitor status in, mood and comment out |
154
+ | `menubar.py` / `buddy.py` | The macOS menu bar app and the tkinter koala card |
155
+ | `ipc.py` / `launcher.py` | File-based status and commands; helpers that start the monitor and dashboard |
156
+ | `notifications.py` | Desktop notifications and the alert chime |
157
+ | `calibration.py` / `session_logger.py` | JSON baseline and CSV session persistence |
158
+ | `dashboard*.py` | Streamlit analytics, theme and artwork |
159
+ | `launch_agent.py` / `cli.py` | Start-at-login on each OS and the `slouchbuddy` command |
160
+
161
+ Design notes:
162
+
163
+ - Metrics are compared against *your* baseline rather than fixed angles, because a laptop camera's height and tilt change what "upright" looks like in the frame.
164
+ - Each score factor starts losing points only once it crosses its threshold and bottoms out at 2x the threshold, so small natural movement doesn't tank the score.
165
+ - Anything with timing or decisions (alerts, the koala's mood, wake detection, dashboard aggregation) is a pure function or state machine with an injectable clock, so it's unit-tested without a camera or a display.
166
+ - All thresholds live in [`config.py`](https://github.com/HardiParikh1/slouchbuddy/blob/main/src/slouchbuddy/config.py).
167
+
168
+ ## Tests
169
+
170
+ ```bash
171
+ pip install -r requirements-dev.txt # lightweight: no camera or MediaPipe needed
172
+ pytest
173
+ ```
174
+
175
+ The suite (80+ tests) covers the analyzer and scoring, the alert tracker, the koala's behaviour and rendering, the IPC channel, calibration and session persistence, the alert sound, the CLI and login items, and the dashboard's aggregation and artwork. CI runs it on Linux, Windows and macOS, and builds the package.
176
+
177
+ ## Limitations
178
+
179
+ - Designed for a seated desk setup with your head and shoulders in frame; it isn't for lying down or for off-axis camera angles.
180
+ - Thresholds are hand-tuned defaults and may need adjusting for your camera and desk.
181
+ - The dashboard loads its fonts from Google Fonts and falls back to system fonts offline.
182
+
183
+ ## Tech stack
184
+
185
+ Python, OpenCV, MediaPipe, NumPy, pandas, Pillow, Streamlit, Plotly, tkinter, rumps (macOS menu bar), pytest, GitHub Actions
@@ -0,0 +1,134 @@
1
+ # Slouchbuddy 🐨
2
+
3
+ [![CI](https://github.com/HardiParikh1/slouchbuddy/actions/workflows/ci.yml/badge.svg)](https://github.com/HardiParikh1/slouchbuddy/actions/workflows/ci.yml)
4
+ [![PyPI](https://img.shields.io/pypi/v/slouchbuddy)](https://pypi.org/project/slouchbuddy/)
5
+
6
+ **Your slouch-fixing desk buddy.** A real-time posture coach for people who work from home: it watches you through your webcam, learns what *your* good posture looks like, and an animated koala in your menu bar nudges you (kindly) when you've been slouching for too long.
7
+
8
+ ![The Slouchbuddy dashboard](https://raw.githubusercontent.com/HardiParikh1/slouchbuddy/main/docs/dashboard.png)
9
+
10
+ ## Why I built this
11
+
12
+ After about six months of working from home, my posture was wrecked. No office chair, no colleagues walking past, just me, a laptop and hours of slowly sinking into the desk. I knew I should sit up straight, but nothing was reminding me, and by the time I noticed, I'd been hunched over for an hour.
13
+
14
+ Posture apps I looked at either wanted a wearable or only gave a generic "sit up" timer. I figured the better fix was to build the thing I actually wanted: a live monitor that sees how I'm sitting right now, compares it to my own upright baseline, and taps me on the shoulder only when it matters.
15
+
16
+ It started as a webcam experiment and grew into a small menu bar app, an analytics dashboard so I can see whether I'm actually improving, and a koala that hangs out in my menu bar so that working alone is a little less lonely (and the nagging is a lot friendlier).
17
+
18
+ ## Features
19
+
20
+ - **Real-time pose tracking** (MediaPipe) with a live camera view you can open when you want it
21
+ - **Per-user calibration:** your upright pose is the baseline, so it adapts to your camera angle and body proportions
22
+ - **Five posture checks:** uneven shoulders, head forward, head tilt and leaning toward the screen (all relative to your baseline), plus an **absolute** check for head level with or below the shoulders that ignores calibration
23
+ - **A 0-100 posture score,** weighted across those checks
24
+ - **A koala buddy** that reacts to how you sit (happy, lazy-slouching, oops, curious, sleepy, coffee break). On macOS it lives in the menu bar; anything it has to say arrives as a notification: specific tips ("shoulders are uneven", "chin back"), cheers when you recover, good-streak milestones and break reminders
25
+ - **Gentle alerts:** only after posture stays bad for a sustained period, with a cooldown, a soft chime (configurable) and no nagging
26
+ - **Break reminders** and a friendly "sit up" notification whenever your laptop wakes from sleep
27
+ - **A cosy analytics dashboard** (Streamlit + Plotly) with day / week / month / year views, good-vs-bad percentages and your most frequent issues
28
+ - **Starts at login** on macOS, Windows and Linux
29
+ - **Private by design:** everything runs locally; no video or data leaves your machine, and pausing releases the camera entirely
30
+
31
+ ## Install
32
+
33
+ Requires Python 3.9-3.12 and a webcam.
34
+
35
+ ```bash
36
+ pip install slouchbuddy
37
+ ```
38
+
39
+ Or straight from GitHub: `pip install git+https://github.com/HardiParikh1/slouchbuddy.git`. From a clone: `pip install .`, or `pip install -e ".[dev]"` for development.
40
+
41
+ ## Usage
42
+
43
+ ```bash
44
+ slouchbuddy # macOS: koala in the menu bar. Windows/Linux: the koala card
45
+ slouchbuddy dashboard # analytics dashboard in your browser
46
+ slouchbuddy run # plain camera window (C = calibrate, B = break taken, Q = quit)
47
+ slouchbuddy buddy # the on-screen koala card (Windows/Linux)
48
+ slouchbuddy menubar # the menu bar koala (macOS)
49
+ slouchbuddy test-sound # hear the alert sound
50
+ slouchbuddy install-login / uninstall-login
51
+ ```
52
+
53
+ **First run:** sit up straight as you would at your desk, then choose **Calibrate** from the koala's menu. If the wrong camera opens (e.g. an iPhone through Continuity Camera), set `CAMERA_INDEX=1` (or 2, ...), or use `slouchbuddy install-login --camera 1` for the login item.
54
+
55
+ ### The koala buddy
56
+
57
+ On macOS the koala lives **only in the menu bar**, animated next to your live score and changing mood with your posture. Nothing is drawn over your screen. Click it to calibrate, take a break, pause (which turns the camera off), open the camera view or open the dashboard.
58
+
59
+ On Windows and Linux there's no menu bar koala, so `slouchbuddy` opens a small koala card in the top-right corner of your screen instead (drag it anywhere, right-click for the same menu).
60
+
61
+ The koala is drawn entirely in code ([`koala.py`](https://github.com/HardiParikh1/slouchbuddy/blob/main/src/slouchbuddy/koala.py)), so there are no image assets, and its personality is a small, tested state machine ([`buddy_brain.py`](https://github.com/HardiParikh1/slouchbuddy/blob/main/src/slouchbuddy/buddy_brain.py)): it waits before commenting, doesn't repeat itself, and only praises a recovery that was worth praising.
62
+
63
+ ### The dashboard
64
+
65
+ `slouchbuddy dashboard` opens a cosy eucalyptus-grove page (screenshot at the top) (light and dark themes) with a koala whose mood follows your average score, soft cards, drifting leaves, and:
66
+
67
+ - the score over time by **day, week, month or year**, with a picker for the exact period
68
+ - good-posture percentage, longest bad streak and sessions tracked
69
+ - your most frequent issues and a session-by-session trend
70
+
71
+ ### Alert sound
72
+
73
+ Alerts play a soft two-note chime. Hear the options with `slouchbuddy test-sound chime` (or `beep`, `Glass`, `Pop`, `Ping`, ...) and choose one with `ALERT_SOUND` in [`config.py`](https://github.com/HardiParikh1/slouchbuddy/blob/main/src/slouchbuddy/config.py): `"chime"`, `"beep"`, `"off"`, or the name of a macOS system sound.
74
+
75
+ ### Windows and Linux
76
+
77
+ Everything works on all three platforms except the menu bar koala (macOS only): the monitor, the on-screen koala card, notifications and the dashboard. `install-login` registers startup via the registry (Windows) or an autostart entry (Linux). macOS is where it's developed and used daily; CI runs the tests on all three systems, but the Windows and Linux camera and window behaviour is untested on real machines, so bug reports are very welcome.
78
+
79
+ ### Where data is stored
80
+
81
+ Calibration and session logs live in `~/.slouchbuddy/data/` (override with `SLOUCHBUDDY_HOME`). When running from a source checkout they stay in the repo's `data/` folder.
82
+
83
+ ## How it works
84
+
85
+ ```
86
+ webcam frame -> MediaPipe Pose (33 landmarks) -> PostureDetector (metrics)
87
+ -> analyze_posture(current, baseline) -> status + score
88
+ -> BadPostureTracker (sustained-bad + cooldown) -> chime
89
+ -> status file -> koala (menu bar / card) -> BuddyBrain -> mood + notification
90
+ -> SessionLogger (CSV) -> dashboard
91
+ ```
92
+
93
+ The camera runs in a background process; the menu bar app and the koala card are thin front ends that read its status and send it commands (calibrate, pause, ...) through small files ([`ipc.py`](https://github.com/HardiParikh1/slouchbuddy/blob/main/src/slouchbuddy/ipc.py)).
94
+
95
+ | Module | Responsibility |
96
+ | --- | --- |
97
+ | `pose_detection.py` | Turns landmarks into normalized metrics (shoulder imbalance, head offset, tilt, mouth width, head-above-shoulders) |
98
+ | `posture_analyzer.py` | Compares metrics to the calibrated baseline; produces the status and weighted score |
99
+ | `alert_tracker.py` | Pure state machine for "bad for N seconds" plus alert cooldown (injectable clock) |
100
+ | `app.py` | The camera loop; runs in the foreground or hidden in the background |
101
+ | `koala.py` | Draws the animated koala (Pillow): six moods shared by the menu bar, the card and the dashboard |
102
+ | `buddy_brain.py` | The koala's personality: monitor status in, mood and comment out |
103
+ | `menubar.py` / `buddy.py` | The macOS menu bar app and the tkinter koala card |
104
+ | `ipc.py` / `launcher.py` | File-based status and commands; helpers that start the monitor and dashboard |
105
+ | `notifications.py` | Desktop notifications and the alert chime |
106
+ | `calibration.py` / `session_logger.py` | JSON baseline and CSV session persistence |
107
+ | `dashboard*.py` | Streamlit analytics, theme and artwork |
108
+ | `launch_agent.py` / `cli.py` | Start-at-login on each OS and the `slouchbuddy` command |
109
+
110
+ Design notes:
111
+
112
+ - Metrics are compared against *your* baseline rather than fixed angles, because a laptop camera's height and tilt change what "upright" looks like in the frame.
113
+ - Each score factor starts losing points only once it crosses its threshold and bottoms out at 2x the threshold, so small natural movement doesn't tank the score.
114
+ - Anything with timing or decisions (alerts, the koala's mood, wake detection, dashboard aggregation) is a pure function or state machine with an injectable clock, so it's unit-tested without a camera or a display.
115
+ - All thresholds live in [`config.py`](https://github.com/HardiParikh1/slouchbuddy/blob/main/src/slouchbuddy/config.py).
116
+
117
+ ## Tests
118
+
119
+ ```bash
120
+ pip install -r requirements-dev.txt # lightweight: no camera or MediaPipe needed
121
+ pytest
122
+ ```
123
+
124
+ The suite (80+ tests) covers the analyzer and scoring, the alert tracker, the koala's behaviour and rendering, the IPC channel, calibration and session persistence, the alert sound, the CLI and login items, and the dashboard's aggregation and artwork. CI runs it on Linux, Windows and macOS, and builds the package.
125
+
126
+ ## Limitations
127
+
128
+ - Designed for a seated desk setup with your head and shoulders in frame; it isn't for lying down or for off-axis camera angles.
129
+ - Thresholds are hand-tuned defaults and may need adjusting for your camera and desk.
130
+ - The dashboard loads its fonts from Google Fonts and falls back to system fonts offline.
131
+
132
+ ## Tech stack
133
+
134
+ Python, OpenCV, MediaPipe, NumPy, pandas, Pillow, Streamlit, Plotly, tkinter, rumps (macOS menu bar), pytest, GitHub Actions
@@ -0,0 +1,47 @@
1
+ [build-system]
2
+ requires = ["setuptools>=68"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "slouchbuddy"
7
+ dynamic = ["version"]
8
+ description = "Slouchbuddy: real-time desk posture coaching from your webcam, with calibration, alerts and an analytics dashboard."
9
+ readme = "README.md"
10
+ license = { file = "LICENSE" }
11
+ authors = [{ name = "Hardi Parikh" }]
12
+ requires-python = ">=3.9,<3.13"
13
+ keywords = ["posture", "computer-vision", "mediapipe", "opencv", "health"]
14
+ classifiers = [
15
+ "Programming Language :: Python :: 3",
16
+ "Topic :: Multimedia :: Video :: Capture",
17
+ "Intended Audience :: End Users/Desktop",
18
+ ]
19
+ dependencies = [
20
+ "mediapipe>=0.10.14,<=0.10.21", # newer releases removed the mp.solutions API
21
+ "pillow>=10.1",
22
+ "opencv-contrib-python>=4.8",
23
+ "numpy>=1.26,<2",
24
+ "pandas>=2.0",
25
+ "plotly>=5.18",
26
+ "streamlit>=1.30",
27
+ "sounddevice>=0.4",
28
+ "plyer>=2.1",
29
+ "rumps>=0.4; sys_platform == 'darwin'",
30
+ ]
31
+
32
+ [project.optional-dependencies]
33
+ dev = ["pytest>=8"]
34
+
35
+ [project.urls]
36
+ Homepage = "https://github.com/HardiParikh1/slouchbuddy"
37
+ Source = "https://github.com/HardiParikh1/slouchbuddy"
38
+ Issues = "https://github.com/HardiParikh1/slouchbuddy/issues"
39
+
40
+ [project.scripts]
41
+ slouchbuddy = "slouchbuddy.cli:main"
42
+
43
+ [tool.setuptools.dynamic]
44
+ version = { attr = "slouchbuddy.__version__" }
45
+
46
+ [tool.setuptools.packages.find]
47
+ where = ["src"]
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -0,0 +1,3 @@
1
+ """Slouchbuddy: real-time desk posture monitoring with a webcam."""
2
+
3
+ __version__ = "0.1.0"
@@ -0,0 +1,46 @@
1
+ import time
2
+
3
+ from slouchbuddy import config
4
+
5
+
6
+ class BadPostureTracker:
7
+ """Tracks how long posture has been continuously bad and decides when to alert.
8
+
9
+ Pure logic with an injectable clock, so it can be unit-tested without a camera.
10
+ """
11
+
12
+ def __init__(self, threshold_seconds=None, cooldown_seconds=None, clock=time.time):
13
+ self.threshold_seconds = (
14
+ config.BAD_POSTURE_THRESHOLD_SECONDS if threshold_seconds is None else threshold_seconds
15
+ )
16
+ self.cooldown_seconds = (
17
+ config.ALERT_COOLDOWN_SECONDS if cooldown_seconds is None else cooldown_seconds
18
+ )
19
+ self._clock = clock
20
+ self._bad_since = None
21
+ self._last_alert = None
22
+
23
+ def update(self, is_bad):
24
+ """Record the latest frame. Returns (bad_duration_seconds, should_alert)."""
25
+ now = self._clock()
26
+
27
+ if not is_bad:
28
+ self._bad_since = None
29
+ return 0, False
30
+
31
+ if self._bad_since is None:
32
+ self._bad_since = now
33
+ duration = now - self._bad_since
34
+
35
+ if duration < self.threshold_seconds:
36
+ return duration, False
37
+
38
+ cooled_down = (
39
+ self._last_alert is None or now - self._last_alert >= self.cooldown_seconds
40
+ )
41
+ if cooled_down:
42
+ self._last_alert = now
43
+ return duration, cooled_down
44
+
45
+ def reset(self):
46
+ self._bad_since = None