# Product Requirements Document (PRD) **Product:** GSPro Remote **Version:** 0.1.0 (Restart Foundation) **Author:** \[You] **Date:** \[Today’s date] --- ## 1. Executive Summary GSPro Remote is a companion application for **GSPro golf simulator users** running on Windows. It allows golfers to control GSPro from a secondary device (tablet, phone, or PC) via a web-based interface. The app’s purpose is to: * Simplify control of GSPro without needing a physical keyboard nearby. * Provide intuitive UI for common simulator functions (aim, club selection, mulligans, tee box navigation, shot options, map interaction). * Enhance immersion and ease-of-use for golf enthusiasts with GSPro setups. Future versions may incorporate **computer vision (OCR/marker detection)** to auto-detect and track GSPro UI elements, reducing manual setup and enabling more advanced automation. --- ## 2. Goals 1. **Deliver a clean, intuitive remote-control interface** optimized for tablets/phones. 2. **Support all GSPro keyboard shortcuts** via touch-friendly buttons. 3. **Provide low-latency streaming of the GSPro map/mini-map** (\~200ms or less). 4. **Persist user settings/configuration** locally on the GSPro PC between sessions. 5. **Make installation simple** for non-technical users (one installer, auto-start server). 6. **Prepare for future OCR-based automation**, but keep it out of MVP. --- ## 3. Non-Goals * Multiplayer sync or cloud-hosted services. (There is zero value in a any cloud related services) * Mobile native apps (PWA installable from browser is sufficient). * Full-fledged vision debugging UI for end-users (that stays an advanced/dev option). --- ## 4. Target Audience * **Primary:** GSPro simulator owners with a launch monitor, seeking more convenient in-round controls. * **Secondary:** Enthusiasts who like to customize sim setups (may use advanced OCR features later). Users are assumed to be **non-technical golfers**, not developers. Installation and updates must be straightforward. --- ## 5. Personas & Use Cases ### Persona A: “Weekend Golfer” * Wants to control GSPro from a tablet while standing on the mat. * Needs quick access to Aim, Mulligan, Club Selection, Tee Box controls. * Doesn’t want to touch a keyboard during play. --- ## 6. Functional Requirements ### 6.1 Core Features (MVP) * **UI Controls** * Directional Pad for Aim (Up/Down/Left/Right/Reset). * Club Indicator + Detection (manual at first, OCR planned later). * Mulligan button. * Tee box navigation (previous/next tee). * Map panel with expand/collapse. (should stream the map from the GSPro UI) * **Backend Integration** * WebSocket streaming of GSPro map region. * API endpoints to send keypresses mapped to GSPro shortcuts. * Config persistence (JSON stored on host PC). * mDNS discovery (`gsproapp.local`) for easy access. * **Performance** * Streaming latency under 200ms (720p @ 30fps acceptable). * Smooth interaction (key commands executed <100ms). ### 6.2 Advanced / V2 Features * **OCR & Region Detection** * EasyOCR/Tesseract integration to auto-detect club, map, shot info. * Auto-configuration of regions (user doesn’t manually define). * **Custom Monitor Tasks** * Background monitoring of regions for changes (e.g., “detect when putting mode enabled”). * **Marker Detection** * Visual template matching for advanced element tracking. * **Extended Controls** * Support for additional GSPro shortcuts (e.g., free look, flyover, lighting). --- ## 7. Technical Architecture * **Frontend:** React + TypeScript * `DynamicGolfUI` = Main consumer UI (touch-friendly, polished). * `VisionDashboard` = Developer/advanced-only UI (OCR testing, markers). * **Backend:** Python + FastAPI * `/api/actions/key` → Trigger GSPro keypresses. * `/api/vision/ws/stream` → WebSocket for video streaming. * `/api/vision/ocr`, `/api/vision/markers`, `/api/vision/regions` → Vision endpoints (advanced). * **System Design** * Runs locally on Windows (FastAPI server). * UI served at `http://gsproapp.local:5005/ui`. * Input simulated via `pydirectinput` to control GSPro. * Screen captured via `mss` + OpenCV. --- ## 8. User Experience * **Primary UI (DynamicGolfUI)** Matches "GSPro App.png" in project root directory: * Top: App name/version, Mulligan button. * Left: Club indicator. * Center: Aim directional pad. * Right: Map stream (expandable). * Bottom: Shot Options + Tee controls. * **Advanced UI (VisionDashboard)** Hidden behind advanced toggle. Used by devs to: * Test OCR engines. * Define/capture regions. * Add/verify markers. * Monitor tasks. --- ## 9. Success Metrics * MVP launch: * Users can control 90% of their round without a keyboard. * Map streaming latency <200ms. * 1-click installer on Windows. * V2: * Automatic detection of club + map area with >90% reliability. * Config persistence across restarts without user intervention. --- ## 10. Milestones * **Phase 1 (MVP / Public Beta)** * Polish DynamicGolfUI. * Ensure all GSPro shortcuts are covered. * Stable WebSocket streaming. * Windows installer packaging. * **Phase 2 (Vision + OCR)** * Add OCR-based auto-detection. * Background monitor tasks. * VisionDashboard improvements. * **Phase 3 (Subscription-ready)** * Licensing/subscription integration. * Polished UX/UI redesign (visual depth, animations, better icons). * Documentation & onboarding guide. --- ## 11. Risks / Open Questions * Will OCR performance be good enough at different resolutions (1080p vs 4K)? * Will average users struggle with network/firewall setup for accessing the web UI? * Packaging FastAPI + dependencies into an easy Windows installer (PyInstaller vs. MSI vs. Docker)? --- ## 12. Feature Mapping Matrix | **UI Control** | **GSPro Shortcut** | **API Endpoint** | **Notes** | | ----------------------------------------- | ------------------------------- | ----------------------------------------- | ---------------------------------------------- | | **Reset** | `A` | `POST /api/actions/key` | Reset | | **Aim Pad (Up/Down/Left/Right)** | Arrow keys | `POST /api/actions/keydown` + `/keyup` | aim adjust = arrow keys, needs “hold” support | | **Club Selection (Up/Down)** | `U` (club up), `K` (club down) | `POST /api/actions/key` | Shown as club indicator in UI | | **Mulligan** | `Ctrl+M` | `POST /api/actions/key` | Toggle mulligan | | **Shot Options (Normal/Punch/Flop/Chip)** | `'` (apostrophe) + context? | `POST /api/actions/key` | Might need mapping to GSPro UI if not explicit | | **Tee Box (Left/Right)** | `C` (tee left), `V` (tee right) | `POST /api/actions/key` | Navigates tee position | | **Map Expand/Collapse** | `S` | `POST /api/actions/key` | Toggles map size | | **Map Zoom (In/Out)** | `Q` (zoom +), `W` (zoom -) | `POST /api/actions/key` | Could be UI slider later | | **Map Click (Expanded)** | Mouse click | `POST /api/actions/key` or WS click event | Normalized coordinates mapped to screen | | **Scorecard** | `T` | `POST /api/actions/key` | Toggle scorecard | | **Range Finder** | `R` | `POST /api/actions/key` | Launch rangefinder | | **Heat Map** | `Y` | `POST /api/actions/key` | Toggle heatmap overlay | | **Putt Toggle** | `U` | `POST /api/actions/key` | Enable/disable putting mode | | **Pin Indicator** | `P` | `POST /api/actions/key` | Show/hide pin indicator | | **Flyover** | `O` | `POST /api/actions/key` | Hole preview | | **Tracer Clear** | `F1` | `POST /api/actions/key` | Clear ball tracer | | **Aim Point** | `F3` | `POST /api/actions/key` | Toggle aim point view | | **Free Look** | `F5` | `POST /api/actions/key` | Unlock camera | | **Console Short/Tall** | `F8` / `F9` | `POST /api/actions/key` | Open GSPro dev consoles | | **Fullscreen** | `F11` | `POST /api/actions/key` | Toggle fullscreen | | **Camera Go To Ball** | `5` | `POST /api/actions/key` | Jump to ball cam | | **Camera Fly To Ball** | `6` | `POST /api/actions/key` | Fly cam to ball | | **Go To Ball (practice)** | `8` | `POST /api/actions/key` | Only in practice mode | | **Previous/Next Hole** | `9` / `0` | `POST /api/actions/key` | Only in practice mode | | **Sound On/Off** | `+` / `-` | `POST /api/actions/key` | Volume control | | **FPS Display** | `F` | `POST /api/actions/key` | Show/hide FPS | | **Green Grid** | `G` | `POST /api/actions/key` | Show/hide green putting grid | | **Lighting** | `L` | `POST /api/actions/key` | Adjust lighting | | **Shot Camera** | `J` | `POST /api/actions/key` | Switch to shot cam | | **UI Hide/Show** | `H` | `POST /api/actions/key` | Toggle GSPro UI | | **3D Grass Toggle** | `Z` | `POST /api/actions/key` | Show/hide grass detail | | **Switch Handedness** | `N` | `POST /api/actions/key` | Left/right handed player | | **Shadow Intensity** | `<` / `>` | `POST /api/actions/key` | Adjust shadows | | **Fast Forward Ball Roll** | Hold key (space?) | `POST /api/actions/keydown` + `/keyup` | Needs “hold” support |