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.
- slouchbuddy-0.1.0/LICENSE +21 -0
- slouchbuddy-0.1.0/PKG-INFO +185 -0
- slouchbuddy-0.1.0/README.md +134 -0
- slouchbuddy-0.1.0/pyproject.toml +47 -0
- slouchbuddy-0.1.0/setup.cfg +4 -0
- slouchbuddy-0.1.0/src/slouchbuddy/__init__.py +3 -0
- slouchbuddy-0.1.0/src/slouchbuddy/alert_tracker.py +46 -0
- slouchbuddy-0.1.0/src/slouchbuddy/app.py +227 -0
- slouchbuddy-0.1.0/src/slouchbuddy/buddy.py +164 -0
- slouchbuddy-0.1.0/src/slouchbuddy/buddy_brain.py +139 -0
- slouchbuddy-0.1.0/src/slouchbuddy/calibration.py +27 -0
- slouchbuddy-0.1.0/src/slouchbuddy/cli.py +87 -0
- slouchbuddy-0.1.0/src/slouchbuddy/config.py +63 -0
- slouchbuddy-0.1.0/src/slouchbuddy/dashboard.py +292 -0
- slouchbuddy-0.1.0/src/slouchbuddy/dashboard_art.py +39 -0
- slouchbuddy-0.1.0/src/slouchbuddy/dashboard_data.py +121 -0
- slouchbuddy-0.1.0/src/slouchbuddy/dashboard_theme.py +220 -0
- slouchbuddy-0.1.0/src/slouchbuddy/ipc.py +63 -0
- slouchbuddy-0.1.0/src/slouchbuddy/koala.py +187 -0
- slouchbuddy-0.1.0/src/slouchbuddy/launch_agent.py +122 -0
- slouchbuddy-0.1.0/src/slouchbuddy/launcher.py +33 -0
- slouchbuddy-0.1.0/src/slouchbuddy/menubar.py +155 -0
- slouchbuddy-0.1.0/src/slouchbuddy/notifications.py +99 -0
- slouchbuddy-0.1.0/src/slouchbuddy/pose_detection.py +96 -0
- slouchbuddy-0.1.0/src/slouchbuddy/posture_analyzer.py +126 -0
- slouchbuddy-0.1.0/src/slouchbuddy/session_logger.py +37 -0
- slouchbuddy-0.1.0/src/slouchbuddy/session_summary.py +80 -0
- slouchbuddy-0.1.0/src/slouchbuddy/ui_overlay.py +161 -0
- slouchbuddy-0.1.0/src/slouchbuddy/wake_reminder.py +26 -0
- slouchbuddy-0.1.0/src/slouchbuddy.egg-info/PKG-INFO +185 -0
- slouchbuddy-0.1.0/src/slouchbuddy.egg-info/SOURCES.txt +46 -0
- slouchbuddy-0.1.0/src/slouchbuddy.egg-info/dependency_links.txt +1 -0
- slouchbuddy-0.1.0/src/slouchbuddy.egg-info/entry_points.txt +2 -0
- slouchbuddy-0.1.0/src/slouchbuddy.egg-info/requires.txt +15 -0
- slouchbuddy-0.1.0/src/slouchbuddy.egg-info/top_level.txt +1 -0
- slouchbuddy-0.1.0/tests/test_alert_tracker.py +70 -0
- slouchbuddy-0.1.0/tests/test_buddy_brain.py +151 -0
- slouchbuddy-0.1.0/tests/test_calibration.py +22 -0
- slouchbuddy-0.1.0/tests/test_cli_and_launch_agent.py +61 -0
- slouchbuddy-0.1.0/tests/test_dashboard_art.py +26 -0
- slouchbuddy-0.1.0/tests/test_dashboard_data.py +79 -0
- slouchbuddy-0.1.0/tests/test_ipc.py +37 -0
- slouchbuddy-0.1.0/tests/test_koala.py +37 -0
- slouchbuddy-0.1.0/tests/test_menubar_title.py +49 -0
- slouchbuddy-0.1.0/tests/test_posture_analyzer.py +97 -0
- slouchbuddy-0.1.0/tests/test_session_logging.py +54 -0
- slouchbuddy-0.1.0/tests/test_sound.py +51 -0
- 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
|
+
[](https://github.com/HardiParikh1/slouchbuddy/actions/workflows/ci.yml)
|
|
55
|
+
[](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
|
+

|
|
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
|
+
[](https://github.com/HardiParikh1/slouchbuddy/actions/workflows/ci.yml)
|
|
4
|
+
[](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
|
+

|
|
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,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
|