{"id":25990061,"url":"https://github.com/epilande/annotate","last_synced_at":"2026-01-08T12:08:37.923Z","repository":{"id":279144340,"uuid":"937844770","full_name":"epilande/Annotate","owner":"epilande","description":"📝 Annotation tool for macOS","archived":false,"fork":false,"pushed_at":"2025-03-04T12:54:18.000Z","size":980,"stargazers_count":25,"open_issues_count":1,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-04T13:42:38.239Z","etag":null,"topics":["annotation","drawing","macos","swift","swiftui"],"latest_commit_sha":null,"homepage":"","language":"Swift","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/epilande.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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}},"created_at":"2025-02-24T02:01:20.000Z","updated_at":"2025-03-04T12:24:20.000Z","dependencies_parsed_at":null,"dependency_job_id":"57011d20-13d4-43ea-aaf1-3b9fd912fe2f","html_url":"https://github.com/epilande/Annotate","commit_stats":null,"previous_names":["epilande/annotate"],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/epilande%2FAnnotate","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/epilande%2FAnnotate/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/epilande%2FAnnotate/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/epilande%2FAnnotate/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/epilande","download_url":"https://codeload.github.com/epilande/Annotate/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":242032668,"owners_count":20060833,"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","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":["annotation","drawing","macos","swift","swiftui"],"created_at":"2025-03-05T13:24:24.022Z","updated_at":"2026-01-08T12:08:37.917Z","avatar_url":"https://github.com/epilande.png","language":"Swift","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003cimg alt=\"logo\" width=\"120\" src=\"https://github.com/user-attachments/assets/f994edf4-c4be-46d2-a946-47d728171ffd\" /\u003e\n  \u003ch1\u003eAnnotate\u003c/h1\u003e\n\u003c/div\u003e\n\n \u003cp align=\"center\"\u003e\n  \u003cstrong\u003eA lightweight, keyboard-driven screen annotation tool for macOS that allows you to quickly draw, highlight, and annotate anything on your screen.\u003c/strong\u003e\n\u003c/p\u003e\n\n![annotate](https://github.com/user-attachments/assets/16baefb6-9fad-4702-9233-2991992ad030)\n\n## ❓ Why?\n\nSometimes you need to emphasize a part of your screen or share ideas visually, and Annotate fills that gap with a simple, efficient interface. It enables real-time screen annotations using tools like pen, arrow, highlighter, rectangle, circle, counter, and text—perfect for highlighting and explaining concepts during presentations, live demos, or teaching sessions where visual annotations enhance understanding and clarity.\n\n## ✨ Features\n\n- 🎨 **Drawing Tools**:\n  - ✒️ **Pen** tool for freehand drawing.\n  - ➡️ **Arrow** tool for directional indicators.\n  - 📏 **Line** tool for straight lines.\n  - 🟨 **Highlighter** for emphasizing content.\n  - 🔲 **Rectangle** shapes for boxing content.\n  - ⭕ **Circle** shapes for highlighting areas.\n  - 🔢 **Counter** tool for adding sequential numbered circles.\n  - 📝 **Text** annotations with drag \u0026 edit support.\n  - 👆 **Select** tool for moving and managing objects.\n  - 🧹 **Eraser** tool for removing annotations.\n- ✨ **Fade/Persist Mode:** Control whether annotations fade out after a duration or persist on the screen.\n- 📌 **Always-On Mode:** Display annotations persistently without user interaction.\n- 🌈 **Color Picker:** Easily select and persist your preferred color.\n- ↕️ **Line Width Control:** Adjust line thickness with an interactive picker or Command+Scroll wheel.\n- ⬛ **Board**: Toggle whiteboard or blackboard based on system appearance.\n- 👆 **Cursor Highlight**: Visual spotlight that follows your cursor for better visibility during presentations.\n- 🎯 **Active Cursor Indicator**: Custom cursor styles to visually indicate when Annotate is active.\n- 🖥️ **Fullscreen Support:** Works seamlessly over fullscreen applications.\n- 🎛️ **Menu Bar Integration:** Quick access via a status icon.\n- 🧹 **Auto-Clear Option:** Automatically clear all drawings when toggling the overlay.\n- ⌨️ **Keyboard Shortcuts:** Switch between modes and toggle the overlay with customizable keyboard shortcuts.\n- ⚡ **Global Hotkey:** Toggle Annotate with a global shortcut.\n- 🔄 **Auto-Updates:** Automatic update checking with secure, cryptographically signed updates.\n\n## 📦 Installation\n\n### Download Release\n\n1. **Download the Application:**\n\n   - Go to [latest release](https://github.com/epilande/Annotate/releases/latest) page.\n   - Download the `Annotate-x.x.x.dmg` file for easy installation, or `Annotate-x.x.x.zip` for manual installation.\n\n2. **Install the Application:**\n\n   **Using DMG (Recommended):**\n\n   - Open the downloaded `Annotate-x.x.x.dmg` file.\n   - Drag the `Annotate.app` into your **Applications** folder.\n\n   **Using ZIP:**\n\n   - Unzip the downloaded `Annotate-x.x.x.zip` file.\n   - Drag the `Annotate.app` file into your **Applications** folder.\n\n3. **Run the Application:**\n\n   - Open your **Applications** folder and double-click `Annotate.app` to launch it.\n\n\u003e [!NOTE]\n\u003e Requires macOS 14 (Sonoma) or later. Supports both Apple Silicon and Intel Macs.\n\u003e\n\u003e The app is code-signed and notarized for macOS Gatekeeper compatibility.\n\n### Build from Source\n\n1. **Clone the Repository:**\n\n   ```sh\n   git clone https://github.com/epilande/Annotate\n   ```\n\n2. **Open the Project in Xcode:**\n\n   ```sh\n   cd Annotate\n   open Annotate.xcodeproj\n   ```\n\n3. **Build and Run:**\n   - Ensure you have the latest version of Xcode installed.\n   - Select your target macOS version, then build and run the project in Xcode.\n\n## 🚀 Quick Start\n\n1. Launch Annotate.\n2. Press the global hotkey (configurable in Settings) to toggle the overlay.\n3. Start annotating with the default pen tool.\n4. Press \u003ckbd\u003eEsc\u003c/kbd\u003e to exit the overlay.\n\n\u003e [!TIP]\n\u003e The application provides a menu bar item that lets you select tools, choose colors, and perform actions like undo and redo.\n\u003e It also shows the application's active state, current color selection, tool, and mode.\n\n\u003cimg width=\"250\" alt=\"image\" src=\"https://github.com/user-attachments/assets/40a94d67-29f1-49a6-9a3a-453d7f3d89e1\" /\u003e\n\n## 🎮 Usage\n\n### Keyboard Shortcuts\n\n\u003e [!TIP]\n\u003e All tool shortcuts can be customized in Settings.\n\n#### 🎨 Drawing Tools\n\n| Key          | Tool            | Description                                         |\n| ------------ | --------------- | --------------------------------------------------- |\n| \u003ckbd\u003eP\u003c/kbd\u003e | **Pen**         | Freehand drawing                                    |\n| \u003ckbd\u003eL\u003c/kbd\u003e | **Line**        | Draw straight lines                                 |\n| \u003ckbd\u003eH\u003c/kbd\u003e | **Highlighter** | Highlight areas with semi-transparent brush         |\n| \u003ckbd\u003eR\u003c/kbd\u003e | **Rectangle**   | Draw rectangles (hold \u003ckbd\u003eOption\u003c/kbd\u003e for center) |\n| \u003ckbd\u003eO\u003c/kbd\u003e | **Circle**      | Draw circles (hold \u003ckbd\u003eOption\u003c/kbd\u003e for center)    |\n| \u003ckbd\u003eA\u003c/kbd\u003e | **Arrow**       | Draw directional arrows                             |\n| \u003ckbd\u003eN\u003c/kbd\u003e | **Counter**     | Add sequential numbered circles (1, 2, 3...)        |\n| \u003ckbd\u003eT\u003c/kbd\u003e | **Text**        | Add text annotations                                |\n| \u003ckbd\u003eE\u003c/kbd\u003e | **Eraser**      | Remove annotations by dragging over them            |\n\n#### 🎯 Tool Settings \u0026 Selection\n\n| Key          | Tool             | Description                      |\n| ------------ | ---------------- | -------------------------------- |\n| \u003ckbd\u003eC\u003c/kbd\u003e | **Color Picker**     | Open color selection menu                 |\n| \u003ckbd\u003eW\u003c/kbd\u003e | **Line Width**       | Open line width picker                    |\n| \u003ckbd\u003eV\u003c/kbd\u003e | **Select**           | Select, move, and manage objects          |\n| \u003ckbd\u003eB\u003c/kbd\u003e | **Board**            | Toggle whiteboard/blackboard              |\n| \u003ckbd\u003eK\u003c/kbd\u003e | **Cursor Highlight** | Toggle cursor highlight and click effects |\n\n#### ⚡ Quick Actions\n\n| Shortcut                                             | Action               | Description                                       |\n| ---------------------------------------------------- | -------------------- | ------------------------------------------------- |\n| \u003ckbd\u003eSpace\u003c/kbd\u003e                                     | **Toggle Fade Mode** | Switch between fade and persist modes             |\n| \u003ckbd\u003eDelete\u003c/kbd\u003e                                    | **Delete**           | Remove selected objects or most recent annotation |\n| \u003ckbd\u003eOption\u003c/kbd\u003e + \u003ckbd\u003eDelete\u003c/kbd\u003e                | **Clear All**        | Remove all annotations                            |\n| \u003ckbd\u003eCommand\u003c/kbd\u003e + \u003ckbd\u003eZ\u003c/kbd\u003e                    | **Undo**             | Undo the last action                              |\n| \u003ckbd\u003eCommand\u003c/kbd\u003e + \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eZ\u003c/kbd\u003e | **Redo**             | Redo the last undone action                       |\n| Mouse Backward Button                                | **Undo**             | Undo the last action (mouse button 3)             |\n| Mouse Forward Button                                 | **Redo**             | Redo the last undone action (mouse button 4)      |\n| \u003ckbd\u003eCommand\u003c/kbd\u003e + \u003ckbd\u003eScroll\u003c/kbd\u003e               | **Adjust Width**     | Quickly change line width                         |\n| \u003ckbd\u003eShift\u003c/kbd\u003e (while drawing)                     | **Constrain**        | Lines: 45° angles; Pen/Highlighter: straight      |\n\n#### 📋 Copy/Paste (Select Mode Only)\n\n| Shortcut                          | Action         | Description                            |\n| --------------------------------- | -------------- | -------------------------------------- |\n| \u003ckbd\u003eCommand\u003c/kbd\u003e + \u003ckbd\u003eA\u003c/kbd\u003e | **Select All** | Select all objects on the canvas       |\n| \u003ckbd\u003eCommand\u003c/kbd\u003e + \u003ckbd\u003eC\u003c/kbd\u003e | **Copy**       | Copy selected objects to clipboard     |\n| \u003ckbd\u003eCommand\u003c/kbd\u003e + \u003ckbd\u003eX\u003c/kbd\u003e | **Cut**        | Cut selected objects (copy + delete)   |\n| \u003ckbd\u003eCommand\u003c/kbd\u003e + \u003ckbd\u003eV\u003c/kbd\u003e | **Paste**      | Paste objects at mouse cursor position |\n| \u003ckbd\u003eCommand\u003c/kbd\u003e + \u003ckbd\u003eD\u003c/kbd\u003e | **Duplicate**  | Duplicate selected objects with offset |\n\n#### 🪟 Overlay Controls\n\n| Shortcut                                            | Action             | Description                          |\n| --------------------------------------------------- | ------------------ | ------------------------------------ |\n| Custom (Settings)                                   | **Toggle Overlay** | Show or hide the annotation overlay  |\n| Custom (Settings)                                   | **Always-On Mode** | Persistent, non-interactive display  |\n| \u003ckbd\u003eEsc\u003c/kbd\u003e or \u003ckbd\u003eCommand\u003c/kbd\u003e + \u003ckbd\u003eW\u003c/kbd\u003e | **Close**          | Closes the annotation overlay        |\n| \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eEsc\u003c/kbd\u003e                   | **Switch Mode**    | Close interactive → enable always-on |\n| \u003ckbd\u003eEnter\u003c/kbd\u003e or \u003ckbd\u003eEsc\u003c/kbd\u003e (in text)        | **Finalize Text**  | Complete text input                  |\n\n### Drawing Tools\n\n#### Pen \u0026 Highlighter\n\n- Click and drag to draw freehand lines\n- Pen creates solid lines while highlighter creates semi-transparent, thicker strokes\n- Hold \u003ckbd\u003eShift\u003c/kbd\u003e while drawing to constrain to a perfectly straight line at 45° angle increments (0°, 45°, 90°, 135°, 180°, 225°, 270°, 315°)\n- Adjust line thickness using the Line Width Picker or \u003ckbd\u003eCommand\u003c/kbd\u003e + \u003ckbd\u003eScroll\u003c/kbd\u003e for quick adjustments\n\n#### Line Width Control\n\nAnnotate provides flexible line width control:\n\n- **Interactive Picker**: Press \u003ckbd\u003eW\u003c/kbd\u003e or select \"Line Width\" from the menu bar to open a picker with:\n  - Visual line preview showing the current thickness\n  - Slider for precise width adjustment (0.5px to 20px)\n  - Real-time feedback as you adjust\n- **Quick Adjustment**: Hold \u003ckbd\u003eCommand\u003c/kbd\u003e and scroll your mouse wheel to quickly adjust line width\n  - Scroll up to increase thickness\n  - Scroll down to decrease thickness\n  - Visual feedback appears at the bottom center showing current width and a preview line\n- **Smart Scaling**: Arrowhead sizes automatically scale proportionally with line width for better visual balance\n\n\u003e [!TIP]\n\u003e Line width settings are persisted across sessions and apply to all drawing tools (pen, arrow, line, rectangle, circle).\n\n#### Shapes (Rectangle, Circle)\n\n- Click and drag to create shapes\n- Hold \u003ckbd\u003eOption\u003c/kbd\u003e while drawing rectangles or circles to expand from the center point\n\n#### Arrow \u0026 Line\n\n- Click and drag to create directional arrows or straight lines\n- Hold \u003ckbd\u003eShift\u003c/kbd\u003e while drawing to snap to 45° angle increments for perfectly horizontal, vertical, or diagonal lines\n- Arrows automatically create arrowheads pointing in the direction of the drag\n- Lines create simple straight connections between two points\n\n#### Text Annotations\n\n- Click to place a text annotation\n- Type your text and press \u003ckbd\u003eEnter\u003c/kbd\u003e or \u003ckbd\u003eEsc\u003c/kbd\u003e to finalize\n- Double-click any text annotation to edit its content\n- Click and drag to reposition text\n\n#### Counter Tool\n\n- Click anywhere to add sequential numbered circles (1, 2, 3...)\n- Numbers increment automatically with each click\n\n#### Select Tool\n\nThe Select tool allows you to manipulate existing annotations with precision:\n\n- **Select Objects**: Press \u003ckbd\u003eV\u003c/kbd\u003e to enter select mode\n\n  - Click on objects to select them (lines, arrows, shapes, text, etc.)\n  - Circles and rectangles must be clicked on their edges\n  - A blue dashed bounding box appears around selected objects\n\n- **Multiple Selection**:\n\n  - **Rectangle Selection**: Click and drag on empty space to draw a selection rectangle\n    - All objects inside or touching the rectangle are selected\n  - **Shift+Click**: Hold \u003ckbd\u003eShift\u003c/kbd\u003e and click objects to add/remove them from selection\n  - **Shift+Rectangle**: Hold \u003ckbd\u003eShift\u003c/kbd\u003e while drawing a rectangle to add to existing selection\n\n- **Move Objects**:\n\n  - Click anywhere inside the blue bounding box and drag to move selected objects\n  - Multiple selected objects move together, maintaining their relative positions\n\n- **Copy/Paste/Cut/Duplicate**:\n\n  - **Select All** (\u003ckbd\u003eCommand\u003c/kbd\u003e+\u003ckbd\u003eA\u003c/kbd\u003e): Select all objects on the canvas\n  - **Copy** (\u003ckbd\u003eCommand\u003c/kbd\u003e+\u003ckbd\u003eC\u003c/kbd\u003e): Copy selected objects to clipboard\n  - **Cut** (\u003ckbd\u003eCommand\u003c/kbd\u003e+\u003ckbd\u003eX\u003c/kbd\u003e): Cut selected objects (copy and delete)\n  - **Paste** (\u003ckbd\u003eCommand\u003c/kbd\u003e+\u003ckbd\u003eV\u003c/kbd\u003e): Paste objects at mouse cursor position\n    - Automatically switches to select mode with pasted objects selected\n  - **Duplicate** (\u003ckbd\u003eCommand\u003c/kbd\u003e+\u003ckbd\u003eD\u003c/kbd\u003e): Duplicate selected objects with a small offset\n    - Keeps you in select mode with duplicated objects selected\n\n- **Delete Selected**:\n\n  - Press \u003ckbd\u003eDelete\u003c/kbd\u003e to remove all selected objects\n  - Use \u003ckbd\u003eCommand\u003c/kbd\u003e + \u003ckbd\u003eZ\u003c/kbd\u003e to undo deletions\n\n- **Clear Selection**: Click on empty space (without \u003ckbd\u003eShift\u003c/kbd\u003e) to deselect all objects\n\n\u003e [!TIP]\n\u003e The select tool makes it easy to correct mistakes, reposition elements, and build complex diagrams by moving groups of objects together.\n\n#### Eraser Tool\n\nThe Eraser tool allows you to remove specific annotations by dragging over them:\n\n- **Activate Eraser**: Press \u003ckbd\u003eE\u003c/kbd\u003e to enter eraser mode\n- **Erase Annotations**: Click and drag over any annotation to remove it\n  - Works with all annotation types (pen, arrows, lines, highlighters, shapes, text, counters)\n  - Annotations are removed instantly as you drag over them\n  - Supports undo (\u003ckbd\u003eCommand\u003c/kbd\u003e + \u003ckbd\u003eZ\u003c/kbd\u003e) to restore erased items\n\n### Drawing Modes\n\nToggle between modes with the \u003ckbd\u003eSpace\u003c/kbd\u003e key.\n\n#### Fade Mode\n\nIn fade mode, annotations gradually disappear after a few seconds, keeping your screen clean while allowing for temporary emphasis.\n\n#### Persist Mode\n\nIn persist mode, annotations remain on screen until manually cleared, allowing you to build up complex annotations over time.\n\n### Always-On Mode\n\nAlways-On Mode displays your annotations persistently without any user interaction capability. This mode is ideal for presentations where you need important information visible without accidental modifications, reference displays with static guides or markers, and multi-screen setups where annotations remain on secondary monitors.\n\n#### How to use:\n\n1. Create your annotations in normal interactive mode\n2. Toggle always-on mode via the global hotkey (configurable in Settings) or menu bar\n3. Annotations become persistent and non-interactive\n4. Use the same hotkey or menu option to exit always-on mode and resume editing\n\n### Deletion Controls\n\n- \u003ckbd\u003eDelete\u003c/kbd\u003e: Removes the most recently added annotation.\n- \u003ckbd\u003eOption\u003c/kbd\u003e + \u003ckbd\u003eDelete\u003c/kbd\u003e: Clear all annotations from the screen.\n\n## ⚙️ Settings\n\nAccess the Settings panel from the menu bar icon or by pressing \u003ckbd\u003eCommand\u003c/kbd\u003e + \u003ckbd\u003e,\u003c/kbd\u003e.\n\nSettings are organized into two tabs: **General** and **Shortcuts**.\n\n### General Settings\n\n- **Activation Shortcut**: Set a global keyboard shortcut to toggle Annotate.\n- **Always-On Mode**: Set a global keyboard shortcut to toggle always-on mode.\n- **Clear Drawings on Toggle**: Automatically clear all drawings when activating Annotate.\n- **Hide Tool Feedback**: Disable visual feedback when switching tools.\n- **Show in Dock**: Display Annotate icon in the Dock.\n- **Enable Board**: Show whiteboard or blackboard background.\n- **Board Opacity**: Adjust board background transparency (10-100%).\n- **Cursor Style**: Choose how the cursor appears while annotating (None, Outline, Circle, Crosshair).\n- **Cursor Size**: Adjust the size of circle or crosshair cursor indicators (8-24px).\n- **Enable Cursor Spotlight**: Show a visual spotlight following your cursor.\n- **Enable Click Effect**: Show ripple effect on mouse clicks.\n\n### Keyboard Shortcuts\n\nCustomize keyboard shortcuts for all tools, organized into categories:\n\n- **Drawing Tools**: Pen, Arrow, Line, Highlighter\n- **Shapes**: Rectangle, Circle\n- **Advanced Tools**: Counter, Text, Select\n- **Utilities**: Color Picker, Line Width, Toggle Board\n\n\u003cimg width=\"575\" height=\"740\" alt=\"image\" src=\"https://github.com/user-attachments/assets/23909c0a-7d8f-4d36-8ea5-f6d5783e7d19\" /\u003e\n\n## 🔄 Auto-Updates\n\nAnnotate includes automatic update checking powered by [Sparkle](https://sparkle-project.org/):\n\n- **Automatic Checks**: The app checks for updates once per day.\n- **Manual Check**: Select **Check for Updates...** from the menu bar or use the About window.\n- **Secure Updates**: All updates are cryptographically signed and verified before installation.\n\nUpdates are downloaded and installed seamlessly in the background. You'll be notified when a new version is available, with release notes and the option to install immediately or later.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fepilande%2Fannotate","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fepilande%2Fannotate","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fepilande%2Fannotate/lists"}