{"id":46371445,"url":"https://github.com/shub-rajput/pubbles","last_synced_at":"2026-04-02T14:50:54.090Z","repository":{"id":341836442,"uuid":"1171692356","full_name":"shub-rajput/pubbles","owner":"shub-rajput","description":"A macOS menubar app which shows a text bubble below your pointer","archived":false,"fork":false,"pushed_at":"2026-03-26T16:40:33.000Z","size":3229,"stargazers_count":8,"open_issues_count":3,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-03-26T23:40:47.308Z","etag":null,"topics":["annotations","macapp","macos","menubar-app","swift"],"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/shub-rajput.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"shub-rajput","patreon":null,"open_collective":null,"ko_fi":"shubhangrajput","tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"lfx_crowdfunding":null,"polar":null,"buy_me_a_coffee":null,"thanks_dev":null,"custom":null}},"created_at":"2026-03-03T14:03:55.000Z","updated_at":"2026-03-19T15:24:26.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/shub-rajput/pubbles","commit_stats":null,"previous_names":["shub-rajput/cursor_subtitles","shub-rajput/pubbles"],"tags_count":11,"template":false,"template_full_name":null,"purl":"pkg:github/shub-rajput/pubbles","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shub-rajput%2Fpubbles","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shub-rajput%2Fpubbles/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shub-rajput%2Fpubbles/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shub-rajput%2Fpubbles/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/shub-rajput","download_url":"https://codeload.github.com/shub-rajput/pubbles/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shub-rajput%2Fpubbles/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31308446,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-02T12:59:32.332Z","status":"ssl_error","status_checked_at":"2026-04-02T12:54:48.875Z","response_time":89,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5: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":["annotations","macapp","macos","menubar-app","swift"],"created_at":"2026-03-05T04:03:59.061Z","updated_at":"2026-04-02T14:50:54.085Z","avatar_url":"https://github.com/shub-rajput.png","language":"Swift","funding_links":["https://github.com/sponsors/shub-rajput","https://ko-fi.com/shubhangrajput","https://ko-fi.com/U7U11CXDRK'"],"categories":[],"sub_categories":[],"readme":"\u003cimg width=\"124\" height=\"124\" alt=\"Cursor_subtitles_256x256\" src=\"https://github.com/user-attachments/assets/54467e14-4770-4bcf-b6b8-7bb9d93e772f\" /\u003e\n\n# Pubbles\n\n\nSubtitle bubbles for your pointer. A lightweight macOS menubar app that displays text bubbles below the pointer when enabled. Perfect for real-time context while screen recording for support, feedback and more! Requires **macOS 14.0+** (Sonoma or later).\n\n\n![GH intro small](https://github.com/user-attachments/assets/96bee091-cb90-45b8-a058-9ccbdb3e4024)\n\n\n\u003ca href='https://ko-fi.com/U7U11CXDRK' target='_blank'\u003e\u003cimg height='42' style='border:0px;height:42px;' src='https://storage.ko-fi.com/cdn/kofi1.png?v=6' border='0' alt='Buy Me a Coffee at ko-fi.com' /\u003e\u003c/a\u003e\n\n\n\n## Install\n\n### Homebrew (Recommended)\n\n```bash\nbrew install --cask shub-rajput/pubbles/pubbles\n```\n\n### Install Script\n\nPaste this in Terminal, downloads the latest release, removes the macOS quarantine flag, and moves the app to `/Applications`:\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/shub-rajput/pubbles/main/scripts/install.sh | bash\n```\n\n### Manual\n\nDownload the latest `.zip` from [Releases](https://github.com/shub-rajput/pubbles/releases), unzip, and move `Pubbles.app` to `/Applications`.\n\n\u003e [!NOTE]\n\u003emacOS might show a warning and ask you to trash the app.\n\u003eThat's because I haven't paid Apple $99/yr for the privilege of being a \"verified\" developer :) [(donate to support!)](https://ko-fi.com/shubhangrajput)\n\u003eJust close the prompt, then go to Settings \u003e Privacy \u0026 Security \u003e scroll down and click \"Open Anyway\"\n\n### Build from Source\n\n```bash\ngit clone https://github.com/shub-rajput/pubbles.git\ncd pubbles\nchmod +x scripts/build.sh\n./scripts/build.sh\nopen Pubbles.app\n```\n\n## Usage\n\n1. Press **Cmd+/** (editable) to activate the subtitle bubble\n2. Type your text — it appears in a pill near your pointer\n3. Press **Enter** for a new line (or wrap across multiple lines with multi-line mode on)\n4. Press **Escape** or click anywhere to dismiss\n5. The pill follows your pointer and fades after 10s of inactivity\n\n### Babble Mode\n\nPress **Cmd+M** (editable) to toggle babble mode — real-time speech-to-text that transcribes your voice into the pill using on-device speech recognition.\n\n- Works alongside typing — edit with the keyboard mid-dictation and speech picks up where you left off\n- In single-line mode, text auto-advances to a new line when the character limit is hit (with word-wrap so words don't split)\n- The pill shows \"Listening…\" while waiting for speech\n- Requires **Microphone** and **Speech Recognition** permissions (prompted on first use, or grant via Settings)\n- If permissions were previously denied, the pill shows a message directing you to System Settings\n\n### Doodle Mode\n\nPress **Cmd+D** (editable) to toggle doodle mode — no need for the pill to be active first. When enabled:\n\n- Hold **Cmd** and click+drag to draw on screen (red strokes by default)\n- Release **Cmd** to stop drawing — type normally again\n- Press **Cmd+/** while doodling to show the pill on top; press **Cmd+/** or **Escape** to reset everything\n- A colored dot appears at the cursor while Cmd is held to indicate drawing is ready\n- Drawing resets the idle timer — strokes and pill fade together\n- Customize line color and width via `style.drawingLineColor` and `style.drawingLineWidth` in config\n- The hold-modifier key (default: `cmd`) is configurable via `drawingHotkey` in config\n\n### Settings\n\nOpen **Settings** from the menubar icon for a full settings window with tabs for Style, Hotkeys, General, and About.\n\n\u003cimg width=\"770\" height=\"639\" alt=\"CleanShot 2026-03-27 at 10 51 11\" src=\"https://github.com/user-attachments/assets/5863cfe9-cba8-445a-9f71-3c0cf24e61e4\" /\u003e\n\n### Keyboard Shortcuts\n\nWhile the pill is active:\n\n| Shortcut | Action |\n|----------|--------|\n| **Cmd+/** (editable) | Toggle pill on/off |\n| **Cmd+M** (editable) | Toggle babble mode (speech-to-text) |\n| **Cmd+D** (editable) | Toggle doodle mode on/off |\n| **Cmd+Up** | Previous theme |\n| **Cmd+Down** | Next theme |\n| **Cmd+Right** | Scale pill up |\n| **Cmd+Left** | Scale pill down |\n| **Hold Cmd + click+drag** | Draw on screen (in doodle mode) |\n| **Escape** | Dismiss pill |\n| **Enter** | New line |\n\n## Updating\n\n### Homebrew\n\n```bash\nbrew update \u0026\u0026 brew upgrade --cask pubbles\n```\n\n### Install Script\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/shub-rajput/pubbles/main/scripts/install.sh | bash\n```\n\nQuits the running app, installs the latest release, and relaunches.\n\n### Build from Source\n\n```bash\n./scripts/update.sh\n```\n\nThis quits the app, pulls latest changes, rebuilds, and reopens. If you don't have a signing certificate, it will also reset permissions and prompt you to re-grant Accessibility access.\n\nTo avoid the permission prompt on every update, set up a signing certificate (see below).\n\n## Signing Certificate (Recommended)\n\nWithout a local signing certificate, macOS invalidates Accessibility permission every time you rebuild. To avoid this:\n\n1. Open **Keychain Access** (Spotlight → \"Keychain Access\")\n2. Menu: **Keychain Access → Certificate Assistant → Create a Certificate...**\n3. Set **Name** to `Pubbles`, **Identity Type** to Self Signed Root, **Certificate Type** to Code Signing\n4. Click **Create**\n5. Find the certificate in Keychain Access, double-click it, expand **Trust**, set **Code Signing** to **Always Trust** (enter your Mac login password when prompted)\n\nThe build script will automatically detect and use this certificate. This is entirely local — the certificate never leaves your machine.\n\n## Themes\n\nSwitch themes from the menubar icon → **Theme**. Built-in themes:\n\n- **Default** — solid blue pill with many color options to choose from (no theme selected)\n- **Bold** — bold yellow with hard shadows and bold text\n- **Candy** — pastel gradient with typewriter font\n- **Frosted Glass** — translucent frosted blur\n- **Liquid Glass** — Apple's native glass effect (macOS Tahoe/26+)\n- **Midnight** — dark and minimal with charcoal gradient\n- **Notepad** — warm parchment with Georgia serif\n- **Terminal** — dark, green text, monospace font\n\nWhen selecting Default theme you can quickly change the pill color from preset options.\n\n### Custom Themes\n\nDrop a `.json` file in `~/.config/pubbles/themes/` and it appears in the Theme menu. A theme file sets any style or behavior options:\n\n```json\n{\n  \"name\": \"My Theme\",\n  \"style\": {\n    \"backgroundColor\": \"#FF6600\",\n    \"textColor\": \"#FFFFFF\",\n    \"cornerRadius\": 8\n  }\n}\n```\n\nSee the built-in themes in that directory for more examples.\n\n## Configuration\n\nEdit `~/.config/pubbles/config.json` to customize. The config file only needs to contain the values you want to change — everything else uses defaults (or theme values if a theme is active).\n\nA minimal config looks like:\n\n```json\n{\n  \"hotkey\": \"cmd+/\",\n  \"theme\": \"liquid-glass\"\n}\n```\n\nTo override a theme's style, add specific keys under `style` or `behavior`:\n\n```json\n{\n  \"hotkey\": \"cmd+/\",\n  \"theme\": \"terminal\",\n  \"style\": {\n    \"fontSize\": 18\n  }\n}\n```\n\n### All Options\n\n**Top-level:**\n- `hotkey` — trigger shortcut (default: `cmd+/`)\n- `drawingHotkey` — modifier key for hold-to-draw (default: `cmd`)\n- `drawingToggleHotkey` — dedicated doodle mode toggle (default: `cmd+d`)\n- `dictationHotkey` — babble mode toggle (default: `cmd+m`)\n- `theme` — theme name matching a file in `~/.config/pubbles/themes/` (default: none)\n\n**Style** (`style.*`):\n- `backgroundColor` — pill color, hex (default: `#1F6BE8`)\n- `backgroundOpacity` — background opacity 0–1 (default: `1.0`)\n- `backgroundGradient` — array of hex colors for linear gradient, e.g. `[\"#6366F1\", \"#EC4899\"]` (default: none)\n- `vibrancy` — frosted blur material: `ultraThin`, `thin`, `regular`, `thick`, `ultraThick` (default: none)\n- `glassEffect` — Apple Liquid Glass, macOS 26+ only (default: `false`)\n- `textColor` — text color, hex (default: `#FFFFFF`)\n- `placeholderText` — placeholder text (default: `Say something`)\n- `fontSize` — font size (default: `14`)\n- `pillScale` — overall pill scale, presets: `0.8`, `1.0`, `1.3`, `1.6`, `2.0` (default: `1.0`)\n- `fontFamily` — font name or `system` (default: `system`)\n- `fontWeight` — font weight: `ultraLight`, `thin`, `light`, `regular`, `medium`, `semibold`, `bold`, `heavy`, `black` (default: `regular`)\n- `cornerRadius` — pill roundness (default: `16`)\n- `pointerCorner` — sharp top-left corner pointing at pointer (default: `true`)\n- `paddingH` — horizontal padding (default: `12`)\n- `paddingV` — vertical padding (default: `8`)\n- `maxWidth` — max pill width (default: `300`)\n- `cursorOffset.x` — horizontal offset from pointer (default: `12`)\n- `cursorOffset.y` — vertical offset from pointer (default: `12`)\n- `borderColor` — border color, hex (default: `#FFFFFF`)\n- `borderOpacity` — border opacity 0–1 (default: `0.2`)\n- `borderWidth` — border width (default: `2`)\n- `shadowColor` — shadow color, hex (default: `#000000`)\n- `shadowOpacity` — shadow opacity 0–1 (default: `0.1`)\n- `shadowRadius` — shadow blur (default: `3`)\n- `shadowX` — shadow horizontal offset (default: `0`)\n- `shadowY` — shadow vertical offset (default: `5`)\n- `drawingLineColor` — drawing stroke color, hex (default: `#FF0000`)\n- `drawingLineWidth` — drawing stroke width (default: `3`)\n\n**Behavior** (`behavior.*`):\n- `idleTimeout` — seconds before fade (default: `10`)\n- `fadeOutDuration` — fade out duration in seconds (default: `0.5`)\n- `fadeInDuration` — fade in duration in seconds (default: `0.2`)\n- `charLimit` — max characters per line, ignored when `multiLine` is on (default: `30`)\n- `multiLine` — wrap text across multiple lines instead of a single scrolling line (default: `false`)\n\nChanges apply instantly — no restart needed.\n\n## Permissions\n\n- **Accessibility** — required for global hotkey capture. Prompted on first launch.\n- **Microphone** and **Speech Recognition** — required for babble mode. Prompted on first use of babble mode, or grant ahead of time via Settings.\n\n## License\n\nGPLv3 — see [LICENSE](LICENSE) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshub-rajput%2Fpubbles","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fshub-rajput%2Fpubbles","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshub-rajput%2Fpubbles/lists"}