{"id":44642566,"url":"https://github.com/eddiesanjuan/markupr","last_synced_at":"2026-02-14T19:04:21.396Z","repository":{"id":336580473,"uuid":"1149340307","full_name":"eddiesanjuan/markupr","owner":"eddiesanjuan","description":"Menu bar voice feedback capture with local AI transcription. Speak naturally, get AI-ready Markdown. Works offline.","archived":false,"fork":false,"pushed_at":"2026-02-08T00:21:00.000Z","size":2824,"stargazers_count":0,"open_issues_count":3,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-08T01:51:49.022Z","etag":null,"topics":["developer-tools","electron","macos","menu-bar","productivity","transcription","voice-recording","whisper"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/eddiesanjuan.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null},"funding":{"ko_fi":"eddiesanjuan"}},"created_at":"2026-02-04T02:09:27.000Z","updated_at":"2026-02-08T00:21:03.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/eddiesanjuan/markupr","commit_stats":null,"previous_names":["eddiesanjuan/feedbackflow","eddiesanjuan/markupr"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/eddiesanjuan/markupr","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eddiesanjuan%2Fmarkupr","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eddiesanjuan%2Fmarkupr/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eddiesanjuan%2Fmarkupr/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eddiesanjuan%2Fmarkupr/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/eddiesanjuan","download_url":"https://codeload.github.com/eddiesanjuan/markupr/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eddiesanjuan%2Fmarkupr/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29452617,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-14T15:52:44.973Z","status":"ssl_error","status_checked_at":"2026-02-14T15:52:11.208Z","response_time":53,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["developer-tools","electron","macos","menu-bar","productivity","transcription","voice-recording","whisper"],"created_at":"2026-02-14T19:04:18.443Z","updated_at":"2026-02-14T19:04:21.386Z","avatar_url":"https://github.com/eddiesanjuan.png","language":"TypeScript","funding_links":["https://ko-fi.com/eddiesanjuan"],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"src/renderer/assets/logo.svg\" alt=\"markupr Logo\" width=\"120\" height=\"120\"\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003emarkupr\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eTurn voice narration into AI-ready Markdown with intelligent screenshots\u003c/strong\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/eddiesanjuan/markupr/actions/workflows/ci.yml\"\u003e\u003cimg src=\"https://github.com/eddiesanjuan/markupr/actions/workflows/ci.yml/badge.svg\" alt=\"CI\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/eddiesanjuan/markupr/actions/workflows/release.yml\"\u003e\u003cimg src=\"https://github.com/eddiesanjuan/markupr/actions/workflows/release.yml/badge.svg\" alt=\"Release\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/eddiesanjuan/markupr/releases\"\u003e\u003cimg src=\"https://img.shields.io/github/v/release/eddiesanjuan/markupr?style=flat-square\" alt=\"Latest Release\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/eddiesanjuan/markupr/releases\"\u003e\u003cimg src=\"https://img.shields.io/github/downloads/eddiesanjuan/markupr/total?style=flat-square\" alt=\"Downloads\"\u003e\u003c/a\u003e\n  \u003ca href=\"LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square\" alt=\"License\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://ko-fi.com/eddiesanjuan\"\u003e\u003cimg src=\"https://img.shields.io/badge/Support-Ko--fi-FF5E5B?style=flat-square\u0026logo=ko-fi\" alt=\"Ko-fi\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"#quick-start\"\u003eQuick Start\u003c/a\u003e |\n  \u003ca href=\"#why-markupr\"\u003eWhy markupr?\u003c/a\u003e |\n  \u003ca href=\"#features\"\u003eFeatures\u003c/a\u003e |\n  \u003ca href=\"#how-it-works\"\u003eHow It Works\u003c/a\u003e |\n  \u003ca href=\"#installation\"\u003eInstallation\u003c/a\u003e |\n  \u003ca href=\"#cli-usage\"\u003eCLI Usage\u003c/a\u003e |\n  \u003ca href=\"#usage\"\u003eUsage\u003c/a\u003e |\n  \u003ca href=\"#keyboard-shortcuts\"\u003eShortcuts\u003c/a\u003e |\n  \u003ca href=\"#export-formats\"\u003eExport\u003c/a\u003e |\n  \u003ca href=\"#development\"\u003eDevelopment\u003c/a\u003e |\n  \u003ca href=\"#contributing\"\u003eContributing\u003c/a\u003e |\n  \u003ca href=\"CHANGELOG.md\"\u003eChangelog\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\nmarkupr is a menu bar app that intelligently captures developer feedback. Press a hotkey, talk through what you see, and markupr records your screen while transcribing your voice. When you stop, an intelligent post-processing pipeline correlates your transcript timestamps with the screen recording to extract the right frames at the right moments -- then stitches everything into a structured, AI-ready Markdown document.\n\nOne hotkey to start. One hotkey to stop. A Markdown file with your words, contextually-placed screenshots, and intelligent structure -- ready to hand to your AI coding agent, paste into a GitHub issue, or drop in a Slack thread.\n\n## Quick Start\n\n### CLI (for developers and AI agents)\n```bash\nnpx markupr analyze ./recording.mov\n```\n\nOr install globally:\n```bash\nnpm install -g markupr\n# or\nbun install -g markupr\n```\n\n### Desktop App\nDownload from [markupr.com](https://markupr.com) or the [releases page](https://github.com/eddiesanjuan/markupr/releases) -- available for macOS, Windows, and Linux.\n\n**First-time setup:**\n1. Install the application (DMG for macOS, installer for Windows)\n2. Grant required permissions (Microphone, Screen Recording)\n3. Press `Cmd+Shift+F` (macOS) or `Ctrl+Shift+F` (Windows) to start recording\n4. Narrate your feedback while markupr captures screenshots at pause points\n5. Press the hotkey again to stop -- post-processing runs automatically\n6. Paste the file path from your clipboard into your AI coding agent\n\n**No API key required!** markupr uses local Whisper transcription by default.\n\nIf markupr saves you hours, consider [supporting development on Ko-fi](https://ko-fi.com/eddiesanjuan).\n\n## Why markupr?\n\nAI coding agents are transforming development, but they're only as good as the context you give them. Typing out bug reports with manual screenshots is slow and lossy -- you lose the flow of what you saw and the nuance of what you meant.\n\nmarkupr bridges this gap. Record your screen, narrate what you see, and markupr produces a structured Markdown document that AI agents can consume directly. The output isn't a raw transcript with random screenshots -- it's an intelligently structured document where every screenshot is placed at the exact moment you were describing it, every issue is categorized, and the format is optimized for LLM consumption.\n\n**The workflow:**\n1. You see a bug. Press `Cmd+Shift+F`.\n2. Talk through what you see: \"This button is hidden on mobile, and the spacing is off here...\"\n3. Press the hotkey again to stop.\n4. Paste the file path into Claude Code, Cursor, or any AI agent.\n5. The agent reads your structured feedback -- with screenshots -- and fixes the issues.\n\n**What makes it different:**\n- **Timestamp-correlated frames** -- screenshots are extracted from the exact video frame matching your narration, not taken at arbitrary intervals\n- **Local-first** -- Whisper runs on your machine, your data stays on your machine\n- **AI-native output** -- Markdown structured for LLM consumption, not human-only reading\n- **Zero-friction capture** -- one global hotkey from any app, no context switching\n\n## Features\n\n### Voice-Driven Capture\n- **Local Whisper transcription** runs entirely on your machine -- no API key, no internet required\n- **Optional OpenAI cloud transcription** for higher accuracy (BYOK)\n- **Intelligent screenshot timing** captures automatically during voice pauses\n- **Audio waveform visualization** for real-time feedback\n\n### Intelligent Post-Processing Pipeline\n- **Timestamp-correlated frame extraction** -- every screenshot corresponds to what you were describing\n- **Key-moment detection** analyzes your transcript to find the most important moments\n- **Video frame extraction** via ffmpeg pulls precise frames from the screen recording\n- **Structured Markdown output** optimized for LLM consumption (llms.txt inspired)\n\n### Smart Screenshots\n- **Voice Activity Detection (VAD)** triggers captures at natural pause points\n- **Manual screenshot hotkey** (`Cmd+Shift+S`) for precise control\n- **Multi-monitor support** with display selection\n- **Window-specific capture** for focused feedback\n\n### AI-Ready Output\n- **Markdown format** with contextually-placed screenshots and structured feedback items\n- **Multiple export formats**: Markdown, PDF, HTML, JSON\n- **Clipboard bridge** -- file path is copied to clipboard so AI tools can read the full document\n\n### Bulletproof Reliability\n- **7-state finite state machine** with watchdog timer -- no state the app can enter and not exit\n- **Crash recovery** with 5-second auto-save -- never lose a feedback session\n- **Graceful degradation** -- if transcription fails, frame extraction continues; if ffmpeg is missing, transcript-only output is generated\n- **Auto-updater** for seamless updates\n\n### Professional Experience\n- **Native macOS menu bar** integration (no dock icon)\n- **Windows system tray** support\n- **Global hotkeys** that work from any application\n- **Annotation tools** (arrow, circle, rectangle, freehand, text)\n- **Session history browser** with search and export\n- **Dark/light/system theme** support\n- **Onboarding experience** for first-run setup\n\n## How It Works\n\n### The Post-Processing Pipeline\n\nWhen you press stop, markupr's intelligent pipeline takes over:\n\n1. **Transcribe** -- Your audio is transcribed using local Whisper (or OpenAI API if configured)\n2. **Analyze** -- The transcript is analyzed to identify key moments, topic changes, and important observations\n3. **Extract** -- Video frames are extracted at the exact timestamps corresponding to each key moment\n4. **Generate** -- Everything is stitched into a structured Markdown document with screenshots placed exactly where they belong\n\nThe result isn't just \"screenshots taken during pauses\" -- it's contextually-aware frame extraction that ensures every image in the document shows exactly what you were talking about.\n\n### The Clipboard Bridge\n\nWhen a session completes, the **file path** to your Markdown document is copied to clipboard. Not the content -- the path. This is deliberate:\n\n- If your clipboard gets overwritten, the file lives on disk permanently\n- AI tools like Claude Code can read the file path and process the full document including screenshots\n- The file is yours -- local, private, no cloud dependency\n\n### Session State Machine\n\nThe recording session is governed by a 7-state FSM with timeouts:\n\n```\nidle ─→ starting (5s timeout) ─→ recording (30min max) ─→ stopping (3s timeout)\n                                                              │\n                                                              ▼\n                                                         processing (10s timeout) ─→ complete (30s auto-idle)\n                                                              │\n                                                              ▼\n                                                            error (5s auto-recover)\n```\n\nEvery state has a maximum duration. A watchdog timer monitors state age and forces recovery if anything gets stuck.\n\n## Installation\n\n### macOS\n\nDownload the `.dmg` file from the [releases page](https://github.com/eddiesanjuan/markupr/releases).\n\n1. Open the DMG file\n2. Drag markupr to your Applications folder\n3. Launch markupr from Applications\n4. Grant required permissions (Microphone, Screen Recording)\n\n### Windows\n\nDownload the `.exe` installer from the [releases page](https://github.com/eddiesanjuan/markupr/releases).\n\n1. Run the installer\n2. Follow the installation wizard\n3. Launch markupr from the Start menu\n\n### Linux\n\nDownload the `.AppImage` or `.deb` file from the [releases page](https://github.com/eddiesanjuan/markupr/releases).\n\n```bash\n# AppImage\nchmod +x markupr-*.AppImage\n./markupr-*.AppImage\n\n# Debian/Ubuntu\nsudo dpkg -i markupr_*.deb\n```\n\n## Configuration\n\n### Transcription\n\nmarkupr works out of the box with **local Whisper** transcription -- no API key needed. On first run, you'll be prompted to download a Whisper model (~75MB for tiny, ~500MB for base).\n\nFor cloud post-session transcription with higher accuracy, add your OpenAI API key:\n\n1. Sign up at [platform.openai.com/api-keys](https://platform.openai.com/api-keys)\n2. Create an API key with \"Usage\" permissions\n3. Open Settings \u003e Advanced \u003e Transcription Service\n4. Enter your OpenAI API key\n\nOpenAI usage is billed to your own API account.\n\n### AI-Enhanced Analysis (Optional)\n\nAdd your Anthropic API key for Claude-powered document analysis:\n\n1. Get an API key at [console.anthropic.com](https://console.anthropic.com/)\n2. Open Settings \u003e Advanced \u003e AI Analysis\n3. Enter your Anthropic API key\n\nClaude analyzes your transcript alongside screenshots to produce an intelligent document -- grouping related feedback, identifying patterns, and writing actionable summaries.\n\n### Settings Overview\n\n| Category | Setting | Description |\n|----------|---------|-------------|\n| **General** | Output Directory | Where sessions are saved |\n| | Launch at Login | Start markupr on system boot |\n| **Recording** | Countdown | 0, 3, or 5 second countdown before recording |\n| | Transcription Preview | Show live transcription overlay |\n| | Audio Waveform | Visual audio level feedback |\n| **Capture** | Pause Threshold | Voice pause duration before screenshot (500-3000ms) |\n| | Min Time Between | Minimum gap between screenshots |\n| **Appearance** | Theme | Dark, Light, or System |\n| | Accent Color | Customize UI accent color |\n| **Hotkeys** | Toggle Recording | Default: `Cmd/Ctrl+Shift+F` |\n| | Manual Screenshot | Default: `Cmd/Ctrl+Shift+S` |\n\n## CLI Usage\n\nmarkupr can run as a standalone CLI tool -- no Electron or desktop app required. This is ideal for:\n- CI/CD pipelines processing screen recordings\n- AI coding agents that need to analyze recordings programmatically\n- Developers who prefer the command line\n\n### Installation\n\n```bash\n# Run without installing\nnpx markupr analyze ./recording.mov\n\n# Install globally via npm\nnpm install -g markupr\n\n# Install globally via bun\nbun install -g markupr\n```\n\n### Commands\n\n#### `markupr analyze \u003cvideo-file\u003e`\n\nProcess a screen recording into a structured Markdown document with extracted frames and transcript.\n\n**Options:**\n| Flag | Description | Default |\n|------|-------------|---------|\n| `--audio \u003cfile\u003e` | Separate audio file (if not embedded in video) | Auto-extracted from video |\n| `--output \u003cdir\u003e` | Output directory | `./markupr-output` |\n| `--whisper-model \u003cpath\u003e` | Path to local Whisper model file | Auto-detected in `~/.markupr/whisper-models/` |\n| `--no-frames` | Skip frame extraction | `false` |\n| `--verbose` | Show detailed progress output | `false` |\n\n**Examples:**\n\n```bash\n# Basic usage - analyze a screen recording\nmarkupr analyze ./bug-demo.mov\n\n# Use a specific output directory\nmarkupr analyze ./recording.mov --output ./reports\n\n# Separate audio and video files\nmarkupr analyze ./screen.mov --audio ./voiceover.wav\n\n# Skip frame extraction (transcript only)\nmarkupr analyze ./recording.mov --no-frames\n```\n\n### Requirements\n\n- **Node.js** 18+\n- **ffmpeg** must be installed and on your PATH (for frame extraction and audio processing)\n  - macOS: `brew install ffmpeg`\n  - Ubuntu/Debian: `sudo apt install ffmpeg`\n  - Windows: `choco install ffmpeg` or download from ffmpeg.org\n\n### For AI Agents\n\nmarkupr is designed to be used by AI coding agents. An agent can:\n\n```bash\n# Install and process a recording in one command\nnpx markupr analyze ./recording.mov --output ./feedback\n\n# The output is a structured Markdown file with embedded screenshots\n# Perfect for feeding into Claude, GPT, or any LLM\ncat ./feedback/markupr-report.md\n```\n\nThe output Markdown follows the llms.txt convention -- structured, parseable, and optimized for AI consumption.\n\n## Usage\n\n### Basic Workflow\n\n1. **Start Recording**: Press `Cmd+Shift+F` (macOS) or `Ctrl+Shift+F` (Windows)\n2. **Select Source**: Choose which screen or window to capture\n3. **Narrate**: Speak naturally about what you see\n4. **Screenshots**: Captured automatically during pauses (or press `Cmd+Shift+S` manually)\n5. **Stop Recording**: Press the hotkey again\n6. **Post-Processing**: Pipeline automatically transcribes, analyzes, extracts frames, and generates output\n7. **Use Output**: File path is on your clipboard -- paste into your AI tool\n\n### Recording Tips\n\n- **Speak naturally** -- markupr detects pauses to time screenshots\n- **Pause briefly** when you want a screenshot captured\n- **Use manual capture** (`Cmd+Shift+S`) for precise timing\n- **Review before export** to remove unwanted items\n\n### Using with AI Coding Agents\n\nAfter a session completes, the file path is on your clipboard. Paste it into:\n\n- **Claude Code**: `Read the feedback session at [paste path]`\n- **Cursor/Windsurf**: Reference the file path in your prompt\n- **GitHub Issues**: Copy the Markdown content directly\n\n### AI Agent Setup\n\nFor coding agents, use the one-liner from repo root:\n\n```bash\nnpm run setup:markupr\n```\n\nDetailed agent setup notes are in [`docs/AI_AGENT_QUICKSTART.md`](docs/AI_AGENT_QUICKSTART.md).\n\n### Session Output\n\nSessions are saved to an organized folder:\n\n```\n~/markupr/sessions/2026-02-05_14-23-41/\n  feedback-report.md     # Structured Markdown with inline screenshots\n  metadata.json          # Session metadata (source, duration, environment)\n  screenshots/\n    fb-001.png           # Extracted frames from key moments\n    fb-002.png\n    fb-003.png\n  session-recording.webm # Full screen recording (optional)\n```\n\n## Keyboard Shortcuts\n\n### Recording\n\n| Action | macOS | Windows/Linux |\n|--------|-------|---------------|\n| Start/Stop Recording | `Cmd+Shift+F` | `Ctrl+Shift+F` |\n| Manual Screenshot | `Cmd+Shift+S` | `Ctrl+Shift+S` |\n| Pause/Resume | `Cmd+Shift+P` | `Ctrl+Shift+P` |\n\n### Navigation\n\n| Action | macOS | Windows/Linux |\n|--------|-------|---------------|\n| Open Settings | `Cmd+,` | `Ctrl+,` |\n| Session History | `Cmd+H` | `Ctrl+H` |\n| Keyboard Shortcuts | `Cmd+/` | `Ctrl+/` |\n| Close Dialog | `Escape` | `Escape` |\n\n### Editing\n\n| Action | macOS | Windows/Linux |\n|--------|-------|---------------|\n| Delete Selected | `Backspace` | `Delete` |\n| Edit Item | `Enter` | `Enter` |\n| Move Up | `Cmd+Up` | `Ctrl+Up` |\n| Move Down | `Cmd+Down` | `Ctrl+Down` |\n| Undo | `Cmd+Z` | `Ctrl+Z` |\n| Redo | `Cmd+Shift+Z` | `Ctrl+Shift+Z` |\n| Select All | `Cmd+A` | `Ctrl+A` |\n\n### Annotation Tools\n\n| Tool | Shortcut |\n|------|----------|\n| Arrow | `1` |\n| Circle | `2` |\n| Rectangle | `3` |\n| Freehand | `4` |\n| Text | `5` |\n| Clear Annotations | `Cmd/Ctrl+Backspace` |\n\n## Export Formats\n\n### Markdown (.md)\n\nAI-optimized format inspired by [llms.txt](https://llms.txt). Includes:\n\n- Structured headings with timestamps\n- Feedback items with categories and severity\n- Inline screenshot references\n- Summary table with session metadata\n\n```markdown\n# Feedback Report: My App\n\n## Summary\n- **Duration**: 2m 34s\n- **Items**: 5 feedback points\n- **Screenshots**: 3 captured\n\n## Feedback Items\n\n### FB-001: Login button not visible\n**Timestamp**: 00:15 | **Type**: Bug\n\n\u003e The login button is hidden behind the header on mobile viewport...\n\n![Screenshot](./screenshots/fb-001.png)\n```\n\n### PDF (.pdf)\n\nProfessional document with embedded screenshots, print-ready layout, and theme support.\n\n### HTML (.html)\n\nSelf-contained web page with embedded images, dark/light theme toggle, and mobile responsive design.\n\n### JSON (.json)\n\nMachine-readable format for integrations and automation.\n\n## Architecture\n\n```\nmarkupr/\n├── src/\n│   ├── main/                  # Electron main process\n│   │   ├── index.ts           # Entry point, orchestration\n│   │   ├── SessionController  # 7-state FSM with watchdog\n│   │   ├── CrashRecovery      # Auto-save and crash detection\n│   │   ├── ai/                # Claude AI analysis pipeline\n│   │   ├── audio/             # Audio capture and VAD\n│   │   ├── capture/           # Screen capture services\n│   │   ├── output/            # Document generation (MD, PDF, HTML, JSON)\n│   │   ├── pipeline/          # Post-processing (transcribe → analyze → extract → generate)\n│   │   ├── settings/          # Settings with secure API key storage\n│   │   ├── transcription/     # Whisper + tier management\n│   │   └── windows/           # Window management (popover, taskbar)\n│   ├── renderer/              # React UI\n│   │   ├── App.tsx            # Main component\n│   │   ├── components/        # UI components (30+)\n│   │   ├── audio/             # Renderer-side audio bridge\n│   │   ├── capture/           # Renderer-side screen recording\n│   │   └── hooks/             # React hooks (theme, animation)\n│   ├── preload/               # Electron preload (secure IPC bridge)\n│   └── shared/                # Shared types and constants\n├── tests/                     # Test suite\n├── docs/                      # Documentation\n├── site/                      # Landing page\n└── package.json\n```\n\n## Development\n\n### Prerequisites\n\n- Node.js 18+\n- npm 9+\n- macOS, Windows, or Linux\n\n### Setup\n\n```bash\n# Clone the repository\ngit clone https://github.com/eddiesanjuan/markupr.git\ncd markupr\n```\n\nUse either npm or bun:\n\n```bash\n# npm\nnpm install\n\n# Start development mode\nnpm run dev\n```\n\n```bash\n# bun\nbun install\n\n# Start development mode\nbun run dev\n```\n\n### Scripts\n\n| Script | Description |\n|--------|-------------|\n| `npm run dev` | Start in development mode with hot reload |\n| `npm run build` | Build for production |\n| `npm run build:desktop` | Build desktop app only |\n| `npm run package` | Package for current platform |\n| `npm run package:mac` | Package for macOS |\n| `npm run package:win` | Package for Windows |\n| `npm run package:linux` | Package for Linux |\n| `npm test` | Run all tests |\n| `npm run test:unit` | Run unit tests only |\n| `npm run test:watch` | Run tests in watch mode |\n| `npm run lint` | Lint code |\n| `npm run lint:fix` | Auto-fix lint issues |\n| `npm run typecheck` | TypeScript type checking |\n\nYou can run the same scripts with bun (`bun run dev`, `bun run test`, etc.).\n\n### Running Tests\n\n```bash\n# Run all tests\nnpm test\n\n# Run with coverage\nnpm run test:coverage\n\n# Run specific test file\nnpx vitest tests/unit/postProcessor.test.ts\n```\n\n## Contributing\n\nWe welcome contributions! markupr is MIT licensed and community-driven.\n\n### Quick Start for Contributors\n\n1. Fork the repository\n2. Create a feature branch: `git checkout -b feature/amazing-feature`\n3. Make your changes\n4. Run tests: `npm test`\n5. Run lint: `npm run lint`\n6. Commit: `git commit -m 'Add amazing feature'`\n7. Push: `git push origin feature/amazing-feature`\n8. Open a Pull Request\n\n### Guidelines\n\n- **Tests required** for new functionality\n- **Lint clean** -- run `npm run lint` before submitting\n- **TypeScript strict** -- run `npm run typecheck`\n- **Small PRs preferred** -- focused changes are easier to review\n- **Follow existing patterns** -- check CLAUDE.md for architecture details\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for full guidelines.\n\n## Troubleshooting\n\n### Common Issues\n\n**Microphone not detected**\n- Check System Preferences \u003e Security \u0026 Privacy \u003e Microphone\n- Grant markupr microphone access\n\n**Screen recording permission denied**\n- macOS: System Preferences \u003e Security \u0026 Privacy \u003e Screen Recording\n- Restart markupr after granting permission\n\n**Whisper model download failing**\n- Check your internet connection\n- Try a smaller model first (tiny: ~75MB)\n- Downloads support resume if interrupted\n\n**OpenAI API connection failed**\n- Verify your API key is correct\n- Check your internet connection\n- Ensure your OpenAI project has billing enabled\n\n**Hotkeys not working**\n- Check for conflicts with other applications\n- Try customizing hotkeys in Settings \u003e Hotkeys\n\n**ffmpeg not found for frame extraction**\n- Install ffmpeg: `brew install ffmpeg` (macOS) or download from [ffmpeg.org](https://ffmpeg.org/)\n- markupr gracefully degrades to transcript-only output without ffmpeg\n\nSee [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md) for more solutions.\n\n## Support markupr\n\nIf markupr is useful in your workflow and you want to keep it improving quickly:\n\n- [Support on Ko-fi](https://ko-fi.com/eddiesanjuan)\n- Share the project with a teammate who writes bug reports\n- Open issues with reproducible feedback sessions so fixes land faster\n\n## License\n\nMIT License - see [LICENSE](LICENSE) for details.\n\n## Acknowledgments\n\n- [Whisper](https://github.com/openai/whisper) for local speech recognition\n- [Anthropic Claude](https://anthropic.com) for AI-enhanced document analysis\n- [OpenAI](https://platform.openai.com) for cloud transcription\n- [Electron](https://electronjs.org) for cross-platform desktop framework\n- [React](https://reactjs.org) for the UI framework\n- [Vite](https://vitejs.dev) for blazing fast builds\n\n---\n\n\u003cp align=\"center\"\u003e\n  Built by \u003ca href=\"https://github.com/eddiesanjuan\"\u003eEddie San Juan\u003c/a\u003e. Open source. MIT licensed.\u003cbr\u003e\n  \u003ca href=\"https://ko-fi.com/eddiesanjuan\"\u003eSupport markupr on Ko-fi\u003c/a\u003e\n\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feddiesanjuan%2Fmarkupr","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Feddiesanjuan%2Fmarkupr","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feddiesanjuan%2Fmarkupr/lists"}