diff --git a/README.md b/README.md index a5f4b36..5f06114 100644 --- a/README.md +++ b/README.md @@ -106,7 +106,7 @@ Same accuracy, dramatically better Apple platform integration. ## 📋 Requirements - **macOS 13 (Ventura)** or later -- **Apple Silicon Mac** (M1/M2/M3/M4) — **Intel Macs are not supported.** The released DMG is built for `arm64` only. +- **Apple Silicon Mac** (M1/M2/M3/M4) — **Intel Macs are not supported.** VocaMac is built for `arm64` only. - **Xcode 15+** or Swift 5.9+ (only for building from source) ### Permissions @@ -125,7 +125,23 @@ VocaMac requires three macOS permissions: ## 🚀 Quick Start -### Option 1: Download DMG (Recommended) +### Option 1: Install via Homebrew (Recommended) + +```bash +brew tap jatinkrmalik/vocamac +brew trust --cask jatinkrmalik/vocamac/vocamac +brew install --cask vocamac +``` + +Homebrew installs VocaMac to `/Applications/VocaMac.app`. Launch it from Spotlight or your Applications folder. Updates are a single command away: + +```bash +brew upgrade --cask vocamac +``` + +> **Why Homebrew?** Terminal-based install. One-command updates. Permissions persist across upgrades. No manual DMG downloads. See [`docs/HOMEBREW.md`](docs/HOMEBREW.md) for the full Homebrew guide. + +### Option 2: Download DMG 1. **Download** the latest `VocaMac-x.x.x-arm64.dmg` from the [Releases page](https://github.com/jatinkrmalik/vocamac/releases) 2. **Open** the DMG and drag VocaMac to Applications @@ -134,7 +150,7 @@ VocaMac requires three macOS permissions: > VocaMac is **Developer ID signed and notarized** by Apple — macOS will open it without any security warnings. -### Option 2: Build from Source (Recommended) +### Option 3: Build from Source ```bash git clone https://github.com/jatinkrmalik/vocamac.git @@ -144,7 +160,7 @@ make install This builds VocaMac, installs it to `/Applications`, and launches it. Permissions are granted directly to VocaMac, just like the DMG method. -### Option 3: CLI Commands (For Developers) +### Option 4: CLI Commands (For Developers) ```bash git clone https://github.com/jatinkrmalik/vocamac.git @@ -179,6 +195,14 @@ Nightly builds are automated builds from the latest `main` branch, published eve **How to install:** +**Via Homebrew (recommended):** +```bash +brew tap jatinkrmalik/vocamac +brew trust --cask jatinkrmalik/vocamac/vocamac-nightly +brew install --cask vocamac-nightly +``` + +**Or via DMG:** 1. Download the latest `VocaMac-nightly-*.dmg` from the [Nightly Release](https://github.com/jatinkrmalik/vocamac/releases/tag/nightly) 2. Open the DMG and drag VocaMac to Applications 3. Grant permissions when prompted (same as a stable release) diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index f98aad8..5b34f24 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -301,7 +301,7 @@ Apple Silicon: > The `recommendModel` function in `SystemInfo.swift` retains a defensive > Intel branch (smaller models, no Metal). It exists only to keep the -> code valid if someone compiles from source on Intel; the released DMG +> code valid if someone compiles from source on Intel; the released binary > is `arm64`-only and Intel Macs are not a supported configuration. #### 3.2.8 `TextInjector` - System-Wide Text Insertion @@ -337,9 +337,9 @@ CGEventSource(stateID: .hidSystemState) #### 3.2.9 `UpdateChecker` - GitHub Release Updates -**Responsibility:** Detect new stable releases from GitHub, download the latest signed DMG, verify integrity, and guide the user through drag-to-replace installation. +**Responsibility:** Detect new stable releases from GitHub and manage updates. For Homebrew-installed copies, it shows a `brew upgrade` command instead of in-app DMG downloads. -**Update Flow:** +**Update Flow (DMG installs):** ``` On launch (max once every 24h) → GET /repos/jatinkrmalik/vocamac/releases/latest @@ -351,6 +351,14 @@ On launch (max once every 24h) → Open DMG in Finder (user drags app to /Applications) ``` +**Update Flow (Homebrew installs):** +``` +On launch (max once every 24h) + → Detect /Caskroom/ in Bundle.main.bundlePath + → If newer release available: show "brew upgrade --cask vocamac" banner + → User copies command and upgrades via Homebrew +``` + **Manual Check:** - Settings → About includes **Check for Updates...** @@ -495,8 +503,8 @@ swift build -c release ### 7.3 Distribution Strategy -1. **GitHub Releases** — Developer ID signed & notarized DMG and ZIP, built by CI -2. **Homebrew Cask** - `brew install --cask vocamac` (see docs/HOMEBREW.md) +1. **Homebrew Cask** — `brew install --cask vocamac` (recommended, see `docs/HOMEBREW.md`) +2. **GitHub Releases** — Developer ID signed & notarized DMG and ZIP, built by CI 3. **Mac App Store** - Future consideration (requires sandbox compliance) --- diff --git a/docs/HOMEBREW.md b/docs/HOMEBREW.md index 5d3c026..75d53fa 100644 --- a/docs/HOMEBREW.md +++ b/docs/HOMEBREW.md @@ -1,5 +1,7 @@ # VocaMac Homebrew Distribution Guide +> **🍺 Homebrew is the recommended way to install VocaMac.** See the [README](../README.md#-quick-start) for the full installation options. + ## Overview VocaMac is distributed via Homebrew as a **cask**, not a formula. This distinction matters: @@ -7,13 +9,14 @@ VocaMac is distributed via Homebrew as a **cask**, not a formula. This distincti - **Formula** — for command-line tools and libraries built from source - **Cask** — for pre-built macOS applications distributed as binaries (`.app`, `.dmg`) -Since VocaMac is a native macOS `.app` distributed as a signed and notarized DMG via GitHub Releases, a cask is the correct packaging format. Users get the exact same binary as the manual download, installed with a single command. +Since VocaMac is a native macOS `.app` primarily distributed via Homebrew (with DMG downloads also available via GitHub Releases), a cask is the correct packaging format. ## Quick Start (For Users) ```bash # Install brew tap jatinkrmalik/vocamac +brew trust --cask jatinkrmalik/vocamac/vocamac brew install --cask vocamac # Upgrade to latest version @@ -31,6 +34,8 @@ After installation, VocaMac appears in `/Applications/VocaMac.app`. Launch it fr A nightly cask is also available, built daily from the latest `main` branch: ```bash +brew tap jatinkrmalik/vocamac +brew trust --cask jatinkrmalik/vocamac/vocamac-nightly brew install --cask vocamac-nightly ``` @@ -40,6 +45,7 @@ The nightly cask uses `version :latest` and `sha256 :no_check` because the DMG c ```bash brew uninstall --cask vocamac +brew trust --cask jatinkrmalik/vocamac/vocamac-nightly brew install --cask vocamac-nightly ``` @@ -75,17 +81,26 @@ The cask lives in a custom tap repository: `jatinkrmalik/homebrew-vocamac`. git push origin main ``` -Users can then install with `brew tap jatinkrmalik/vocamac && brew install --cask vocamac`. +Users can then install with: + +```bash +brew tap jatinkrmalik/vocamac +brew trust --cask jatinkrmalik/vocamac/vocamac +brew install --cask vocamac +``` ## Testing Locally -Before pushing a cask update to the tap, test it locally against a real DMG: +Before pushing a cask update to the tap, test it from a tap checkout against a real DMG. Homebrew 6 rejects loose cask files outside a tap, so copy the cask into a local tap checkout first: ```bash -brew install --cask ./homebrew/Casks/vocamac.rb +brew tap jatinkrmalik/vocamac +cp homebrew/Casks/vocamac.rb "$(brew --repository jatinkrmalik/vocamac)/Casks/vocamac.rb" +brew trust --cask jatinkrmalik/vocamac/vocamac +brew install --cask vocamac ``` -This installs the cask directly from the file path, bypassing the tap. It requires a real DMG to exist at the URL specified in the cask (i.e., a published GitHub Release). +This installs the cask from the local tap checkout. It requires a real DMG to exist at the URL specified in the cask (i.e., a published GitHub Release). To verify the installation: @@ -100,6 +115,8 @@ To uninstall after testing: brew uninstall --cask vocamac ``` +Then restore or commit the tap checkout changes, depending on whether the test was for a local-only change or a real tap update. + ## Manual Cask Update When a new VocaMac version ships, the cask needs two updates: the `version` string and the `sha256` checksum. @@ -226,6 +243,18 @@ A previous installation exists at `/Applications/VocaMac.app`. **Fix:** Remove the existing app first: ```bash rm -rf /Applications/VocaMac.app +brew trust --cask jatinkrmalik/vocamac/vocamac +brew install --cask vocamac +``` + +### Homebrew refuses to load the cask from an untrusted tap + +Homebrew 6 requires explicit trust for casks from third-party taps. + +**Fix:** Trust the VocaMac cask, then install again: + +```bash +brew trust --cask jatinkrmalik/vocamac/vocamac brew install --cask vocamac ``` diff --git a/web/content/features/github-release-updates.md b/web/content/features/github-release-updates.md index c870f4c..09a40c2 100644 --- a/web/content/features/github-release-updates.md +++ b/web/content/features/github-release-updates.md @@ -1,6 +1,6 @@ --- title: "GitHub Release Updates" -subtitle: "VocaMac checks GitHub Releases, downloads the latest signed DMG, and guides you through drag-to-replace updates." +subtitle: "VocaMac checks GitHub Releases for updates. Homebrew users run `brew upgrade`. DMG users get in-app downloads." description: "VocaMac includes built-in update checks powered by the GitHub Releases API. See new versions in-app, download the signed DMG with progress, and install safely." keywords: "mac app update checker, github releases updater, signed dmg updates, menu bar app update flow, vocamac updates" icon: "⬇️" @@ -8,7 +8,9 @@ icon: "⬇️" ## Built-In Update Checks -VocaMac can now check for new releases directly from GitHub. It compares your current app version to the latest stable release, then shows an in-app update banner when a newer version is available. +VocaMac checks for new releases directly from GitHub. It compares your current app version to the latest stable release, then shows an in-app update banner when a newer version is available. + +If you installed VocaMac via Homebrew (`brew install --cask vocamac`), updates are managed by Homebrew — simply run `brew upgrade --cask vocamac`. VocaMac detects Homebrew installs and guides you accordingly. The check is lightweight and rate-limit friendly: @@ -16,7 +18,7 @@ The check is lightweight and rate-limit friendly: - manual **Check for Updates...** button in **Settings -> About** - no extra account, login, or update service required -## Update Flow +## Update Flow (DMG Installs) When an update is found, VocaMac shows a clear, non-intrusive banner in the menu bar popover. From there, you can open update details, review release notes, and start the download. diff --git a/web/content/features/smart-model-selection.md b/web/content/features/smart-model-selection.md index da50c72..908bd40 100644 --- a/web/content/features/smart-model-selection.md +++ b/web/content/features/smart-model-selection.md @@ -12,7 +12,7 @@ Every Apple Silicon Mac is different. An 8 GB MacBook Air has very different hea On first launch, VocaMac analyzes your chip generation, CPU core count, Neural Engine availability, and installed RAM. It then suggests the optimal model tier. You remain free to choose any model, but the recommendation gets you great results immediately without guesswork. -> **Note:** VocaMac is Apple Silicon only. The released DMG does not run on Intel Macs. +> **Note:** VocaMac is Apple Silicon only — it does not run on Intel Macs. ## Five Model Tiers diff --git a/web/layouts/index.html b/web/layouts/index.html index 3c705f8..371c772 100644 --- a/web/layouts/index.html +++ b/web/layouts/index.html @@ -107,9 +107,28 @@

- Install Now - It's Free + Quick Install + More Options Star on GitHub
+
🔒 100% Offline 🛡️ Privacy First @@ -369,17 +388,71 @@

Choose Your Model

BETA

Get Started in Minutes

-

Download the signed DMG or build from source. No terminal gymnastics required.

+

Install via Homebrew, download the DMG, or build from source. Your choice.

- + +
- -
+ +
+
+
+
1
+
+

Install via Homebrew

+
+
+
+ + + +
+ Terminal + +
+
+ $ brew tap jatinkrmalik/vocamac +$ brew trust --cask jatinkrmalik/vocamac/vocamac +$ brew install --cask vocamac +
+
+

Installs to /Applications/VocaMac.app. Launch from Spotlight or your Applications folder.

+
+
+
+
2
+
+

Grant Permissions & Dictate

+

Grant Microphone, Accessibility, and Input Monitoring permissions when prompted. Permissions persist across upgrades — no re-granting needed.

+

Hold Right Option (⌥) → speak → release. Text appears at your cursor. ✨

+
+
+
+
+
+

Requirements

+
    +
  • macOS 13 (Ventura) or later
    • +
  • Apple Silicon (M1/M2/M3/M4)
    • +
  • 8 GB RAM (16 GB+ recommended)
    • +
  • Homebrew installed
    • +
  • Microphone
    • +
+
+
+

Staying Up to Date

+

Run brew upgrade --cask vocamac to get the latest version. VocaMac detects Homebrew installs and guides you automatically. Learn more →

+
+
+
+ + +