{"id":31936142,"url":"https://github.com/dnouri/posturama","last_synced_at":"2025-10-14T07:22:08.527Z","repository":{"id":316916723,"uuid":"1065330978","full_name":"dnouri/Posturama","owner":"dnouri","description":"Real-time posture monitoring for healthier computer work","archived":false,"fork":false,"pushed_at":"2025-09-27T15:45:00.000Z","size":39,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-09-27T16:09:48.823Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dnouri.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-27T14:04:44.000Z","updated_at":"2025-09-27T15:45:01.000Z","dependencies_parsed_at":"2025-09-28T15:34:26.156Z","dependency_job_id":null,"html_url":"https://github.com/dnouri/Posturama","commit_stats":null,"previous_names":["dnouri/posturama"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/dnouri/Posturama","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dnouri%2FPosturama","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dnouri%2FPosturama/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dnouri%2FPosturama/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dnouri%2FPosturama/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dnouri","download_url":"https://codeload.github.com/dnouri/Posturama/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dnouri%2FPosturama/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279018216,"owners_count":26086303,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-14T02:00:06.444Z","response_time":60,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-10-14T07:22:02.070Z","updated_at":"2025-10-14T07:22:08.523Z","avatar_url":"https://github.com/dnouri.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Posturama\n\nReal-time posture monitoring for healthier computer work.\n\n**➜ Try it now:** [Posturama](https://dnouri.github.io/Posturama) _(No installation required)_\n\n## What it does\n\nPosturama helps prevent cervicogenic headaches and asymmetrical neck strain by monitoring lateral head tilt during computer work. By maintaining neutral head alignment, users can reduce muscle tension imbalances that contribute to workplace-related neck discomfort.\n\nThe app uses your webcam to detect head position and provides immediate visual feedback when your posture needs correction, helping you build better ergonomic habits over time.\n\n## Quick Start\n\n1. **Open** [Posturama](https://dnouri.github.io/Posturama) in your browser\n2. **Click** \"Start Monitoring\"\n3. **Allow** camera access when prompted\n4. **Position** the small monitor window where you can see it\n5. **Work** normally - Posturama will alert you when your posture needs adjustment\n\nThat's it! The launcher window closes automatically once monitoring starts.\n\n## Using Posturama\n\n### The Monitor Window\n\nThe compact monitor shows your posture status at a glance:\n\n- **Green (✅)** - Good posture, keep it up!\n- **Yellow (⏳)** - Detecting your position\n- **Red (⚠️)** - Time to straighten your head\n\n### Controls\n\n- **▶/⏸ Button** - Start or pause monitoring\n- **Threshold Slider** - Adjust sensitivity (3-8 degrees)\n  - Lower = more strict\n  - Higher = more lenient\n  - Default: 5°\n- **🔊/🔇 Button** - Toggle sound alerts\n- **🐛 Button** - Open debug view to see what the camera sees\n\n### Privacy First\n\n- ✅ All processing happens in your browser\n- ✅ No video is recorded or stored\n- ✅ No data ever leaves your device\n- ✅ No account or sign-up required\n\n## Requirements\n\n- Modern browser (Chrome, Firefox, or Edge)\n- Webcam\n- Popup windows must be allowed (you'll be prompted)\n\n## Important Notice\n\nThis app monitors only lateral (sideways) head tilt and does not assess forward head posture or overall postural alignment. It is designed as an ergonomic awareness tool to complement, not replace, proper workstation setup and regular movement breaks. Users experiencing ongoing neck pain or headaches should consult healthcare professionals.\n\n---\n\n# Technical Documentation\n\n_For developers and contributors_\n\n## Architecture Overview\n\nPosturama uses a popup window architecture to ensure continuous monitoring without browser tab throttling. The app leverages MediaPipe's face landmark detection to calculate head tilt angle in real-time.\n\n### Why Popup Windows?\n\nBrowser tabs throttle JavaScript to 1Hz when inactive. Since posture monitoring needs to run continuously in the background, Posturama uses a dedicated popup window that remains active even when not in focus.\n\n### Key Components\n\n```\n├── index.html              # Launcher page\n├── monitor.html            # Popup monitor window\n├── app.js                  # Application orchestration\n├── posture-calculator.js   # Pure functions for angle calculation\n├── face-detector.js        # MediaPipe wrapper\n├── grace-period.js         # Alert timing logic\n├── audio-alert.js          # Sound notifications\n├── debug-view.js           # Debug visualization\n├── style.css               # Popup window styles\n└── test-runner.js          # Custom test framework\n```\n\n## Technical Features\n\n- **Pure JavaScript** - No frameworks, no build tools, no dependencies\n- **Test-Driven Development** - 65+ tests with custom test runner\n- **Modular Architecture** - Event-driven design with clean separation of concerns\n- **MediaPipe Integration** - Google's 478-point face landmark detection\n- **Grace Period System** - 3-second buffer prevents alert fatigue\n- **Web Audio API** - Generated tones for audio alerts (no audio files)\n\n## Development\n\n### Setup\n\n```bash\n# Clone the repository\ngit clone https://github.com/dnouri/posturama.git\ncd posturama\n\n# Run tests\nmake test\n\n# Start development server\nmake serve\n# Then open http://localhost:8000\n```\n\n### Testing\n\n```bash\n# Run all tests\nmake test\n\n# Run specific test file\nmake test-file FILE=posture-calculator.test.js\n\n# Watch mode\nmake test-watch\n\n# Coverage summary\nmake test-coverage\n```\n\n### Code Quality\n\n```bash\n# Check formatting\nmake lint\n\n# Auto-format code\nmake format\n\n# Run all checks (tests + lint)\nmake check\n```\n\n## How It Works (Technical)\n\n### Detection Pipeline\n\n1. **Video Capture** → Webcam at 640×480 resolution\n2. **Face Detection** → MediaPipe FaceLandmarker identifies 478 facial landmarks\n3. **Angle Calculation** → Extract eye positions (landmarks 33 \u0026 263), calculate tilt angle\n4. **Posture Evaluation** → Compare angle against threshold\n5. **Grace Period** → 3-second buffer for temporary movements\n6. **Feedback Loop** → Visual/audio alerts if bad posture persists\n\n### State Management\n\n```javascript\nDETECTING → GOOD_POSTURE ↔ BAD_POSTURE\n```\n\n- **DETECTING**: No face found or initializing\n- **GOOD_POSTURE**: Head tilt within threshold\n- **BAD_POSTURE**: Head tilt exceeds threshold after grace period\n\n### Performance Optimizations\n\n- Processes at 10 FPS (balanced accuracy vs CPU usage)\n- Throttled render updates to prevent UI jank\n- Efficient landmark extraction (only uses 2 of 478 points)\n- Canvas rendering only when debug view is active\n\n## Debug Mode\n\nThe debug view provides real-time visualization for troubleshooting:\n\n1. Click 🐛 to open debug mode\n2. Window expands to 500×600px\n3. Shows:\n   - Live camera feed with overlay\n   - Eye position markers\n   - Angle visualization\n   - FPS counter\n   - All metrics (angle, threshold, state, grace period)\n4. Click ✕ to return to normal size\n\n## Contributing\n\nContributions welcome! The codebase follows:\n\n- Test-first development\n- No external dependencies\n- Clean, modular architecture\n- Comprehensive documentation\n\nRun `make check` before submitting PRs.\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdnouri%2Fposturama","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdnouri%2Fposturama","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdnouri%2Fposturama/lists"}