HearLingo Companion Service (macOS)
===================================

WHAT IS THIS?
The HearLingo browser extension reads video subtitles aloud in your
language. This companion program provides the speech and translation
engine locally on your computer.

REQUIREMENTS
- macOS 12 (Monterey) or newer
- Apple Silicon (M1/M2/M3/M4) or Intel Mac — use the zip built for
  your architecture
- Google Chrome, Microsoft Edge, Chromium or Brave

HOW TO USE
1. Unzip and drag HearLingoService.app anywhere (e.g. Applications
   or your home folder).
2. Double-click HearLingoService.app.
   - FIRST LAUNCH ONLY: macOS Gatekeeper blocks apps that are not
     from the App Store. If double-clicking shows "cannot be opened
     because the developer cannot be verified", right-click (or
     Control-click) the app and choose "Open", then click "Open" in
     the dialog. Alternatively open System Settings > Privacy &
     Security, scroll down and click "Open Anyway".
   - If the app is reported as "damaged" (common on Apple Silicon
     after downloading), run this once in Terminal from the folder
     you extracted to:
        xattr -cr HearLingoService.app
   - Allow incoming connections if the firewall asks.
   - The app runs entirely silently: no window, no pop-up dialogs.
     You are ready when the extension's floating ball turns green
     (the extension popup shows the connection status).
     If it does not turn green, check the logs (see NOTE below).
3. The extension's floating ball turns green when connected.
   Afterwards the extension starts the service automatically
   whenever needed - no manual steps required.

NOTE: no window stays open while the service runs - it works
entirely in the background. Logs are written to
~/Library/Application Support/HearLingo/logs

WHY THE WARNING APPEARS
The program is not code-signed with a paid Apple Developer ID.
Gatekeeper shows a one-time notice for every unsigned app
downloaded from the internet. It is a reputation check, not a
malware finding. Following "HOW TO USE" step 2 once is enough -
afterwards it opens normally.

HOW TO STOP
- Click "Stop" next to the green status in the extension popup, or
- In Terminal: pkill -f HearLingoService

HOW TO UPGRADE
1. Stop the service first (see HOW TO STOP above).
2. Replace the old HearLingoService.app with the new one.
3. Double-click to start. Your settings are preserved.

KNOWN LIMITATIONS (macOS version)
- The optional local engines (Hy-MT local translation, Fish Speech
  voice cloning) are not available yet - translation uses online
  providers and speech uses Edge-TTS. Core features (TTS reading,
  translation, OCR hard-subtitle reading) work fully.

PRIVACY
- Speech synthesis: subtitle text sent to Microsoft Edge TTS cloud.
- Translation: subtitle text sent to online providers (Google, MyMemory).
- OCR: runs 100% locally, no frames leave your computer.
- No analytics, no personal data collected.

License: Proprietary. (c) 2026 HearLingo. All rights reserved.
