# SMS-TTS-Notify -- Setup and Configuration Guide
# Version: current HEAD snapshot | Commit: 76989cf | Date: 2026-03-19
# For AI agent use only | Source: sms-tts-notify.com/ai/setup-guide.txt

---

## Quick Start (most users need only these 5 steps)

1. Install SMS-TTS-Notify from Google Play Store.
2. Open the app. Read and accept the Terms of Use (first launch only).
3. On Samsung, Xiaomi, Huawei, OPPO, OnePlus, Vivo, or Realme: complete
   the OEM Battery Exemption wizard (see Section 2 below).
4. Grant Notification Access when prompted:
   Android Settings → Apps → Special app access → Notification access
   → Find "SMS TTS Notify" → Enable.
5. Connect your Bluetooth or wired headset. Tap the green START button.

To test: send yourself an SMS. You should hear it through your headset.

If you hear nothing after completing these steps, go to:
https://sms-tts-notify.com/ai/troubleshooting.txt

---

## Section 1: Permission Setup

### Notification Access (required -- most important)

Notification Access is the core permission that allows the app to detect
incoming SMS messages. Without it, the app receives nothing.

Path (all Android versions):
  Android Settings → Apps → Special app access → Notification access
  → Find "SMS TTS Notify" in the list → Enable

Android 13+ additional step (sideloaded APK only, not needed for Play Store):
  If you installed the app outside of Google Play, Android may block this
  permission. To unlock it:
  Android Settings → Apps → SMS TTS Notify → Allow restricted settings → Enable
  Then repeat the Notification Access steps above.

Note: Some Android OS updates reset Notification Access automatically.
If the app stops working after an update, re-grant this permission first.

### Bluetooth permission (Android 12+)

On Android 12 and above, the app needs permission to detect Bluetooth headset
state. This is requested automatically on first launch.
  Android Settings → Apps → SMS TTS Notify → Permissions → Nearby devices → Allow

### Battery optimization exemption (standard Android)

All Android versions benefit from excluding the app from battery optimization:
  Android Settings → Apps → SMS TTS Notify → Battery
  → Select "Unrestricted" or "Don't optimize"

For Samsung, Xiaomi, Huawei, and other OEM devices, additional steps are
needed beyond this standard exemption -- see Section 2.

---

## Section 2: OEM Battery Setup (Samsung, Xiaomi, Huawei, OPPO, and others)

This is the most critical setup step for users on affected devices.
Skipping it will cause the app to silently stop reading SMS within minutes
of launch (the "ghost green" problem -- widget looks active but nothing is read).

### Use the in-app wizard (recommended)

The app includes a built-in setup wizard for all affected OEM devices:
  Open the app → Settings → Status Card → OEM Battery Limits row
  → Tap START SETUP or RESUME SETUP

The wizard guides you step-by-step through the exact settings for your device.
The wizard automatically opened on your first launch if your phone is in the
CRITICAL or HIGH OEM tier (see below).

### OEM tiers

| Tier | Manufacturers | Action |
|------|--------------|--------|
| CRITICAL | Samsung, Xiaomi / Redmi / POCO, Huawei, Honor | Wizard required |
| HIGH | OPPO, Realme, Vivo, OnePlus | Wizard required |
| MINIMAL | Google Pixel, Nokia, Motorola, stock Android | Standard exemption only |
| UNKNOWN | Any unrecognized manufacturer | Generic guide shown |

### Manual steps if wizard is not available

SAMSUNG (all Galaxy models):
  Step 1: Settings → Apps → SMS TTS Notify → Battery → Don't optimize
           (Android 13+: select "Unrestricted")
  Step 2: Settings → Battery → Background usage limits → Never sleeping apps
           → Add SMS TTS Notify
  Step 3: Settings → Battery → Background usage limits
           → Turn OFF "Put unused apps to sleep"
  WARNING: Samsung may re-add the app to sleeping list after firmware updates.
  Repeat Step 2 if the app stops working after a Samsung update.

XIAOMI / MIUI / REDMI / POCO:
  Step 1: MIUI 14+: Settings → Apps → SMS TTS Notify → App permissions
            → Background autostart → Enable
           Older MIUI: Security app → Permissions → Auto-start → Enable
  Step 2: Settings → Apps → Manage apps → SMS TTS Notify
           → Battery saver → No restrictions
  Step 3: Security app → Battery → App battery saver
           → SMS TTS Notify → No restrictions

HUAWEI (EMUI):
  Step 1: Settings → Battery → App launch → SMS TTS Notify
           → Manage manually → Enable: Auto-launch, Secondary launch,
           Run in background
  Step 2: System Manager app → Settings (cog icon) → Disable Smart tune-up
  Step 3: Settings → Battery → Battery optimization → Don't optimize

HONOR:
  Step 1: Settings → Apps → SMS TTS Notify → Battery → App launch
           → Manage manually → Enable all three options
  Step 2: Settings → Apps → SMS TTS Notify → Battery → Don't optimize

OPPO / ColorOS:
  Step 1: Settings → Apps → SMS TTS Notify → App info → Allow Auto Start-up
  Step 2: Settings → Apps → SMS TTS Notify → Battery → Power Saver → Allow
  Step 3: Settings → Battery → Battery optimization → Don't optimize

ONEPLUS (OxygenOS):
  Step 1: Settings → Battery → Battery optimization → SMS TTS Notify
           → Don't optimize
           WARNING: OnePlus may revert this randomly. Re-apply if app stops.
  Step 2: Open Recent apps → long-press SMS TTS Notify → tap Lock icon
  Step 3: Settings → Battery → Battery optimization → (three dots)
           → Advanced optimization → Disable Deep optimization

VIVO:
  Step 1: Settings → More settings → Applications → Autostart → Enable
  Step 2: Settings → Battery → High background power consumption
           → SMS TTS Notify → Enable
  Step 3: Hold app icon → App Info → Battery → Not optimized

REALME:
  Step 1: Settings → Battery → App battery management → SMS TTS Notify
           → Enable: Auto-launch, Foreground activity, Background activity
  Step 2: Settings → Battery → Battery optimization → Don't optimize

For manufacturer-specific instructions with screenshots:
  https://dontkillmyapp.com?app=SMS%20TTS%20Notify

---

## Section 3: Filter Configuration

Filters are optional. The app works immediately without any filter setup.
Configure filters when you need to control which messages get read.

### When to use the Whitelist

Use Whitelist when: you want the app to read ONLY messages from specific
systems (e.g., only your SCADA system), ignoring all personal SMS.

Setup:
  Settings → Whitelist → Enable switch → ADD → enter keyword or sender ID

Examples:
  - To read only from SCADA sender ID "OPS-MES": add "OPS-MES"
  - To read only from phone number +421 905 123 456: add "905123456"
    (enter last 9 digits without spaces or country code)
  - To read only messages containing "LINE-3": add "LINE-3"

WARNING: Enabling the Whitelist with an empty list blocks ALL messages.
Always add at least one keyword before enabling.

### When to use the Blacklist

Use Blacklist when: you want to silence a specific sender (spam, unrelated
system) while reading everything else.

Setup:
  Settings → Blacklist → ADD → enter keyword or sender ID

Sender matching works the same as Whitelist: last-9-digit suffix for phone
numbers, case-insensitive substring for alphanumeric sender IDs.

### Setting up Alarm and Warning keywords

Default Alarm keywords: ALARM, CRITICAL
Default Warning keywords: WARNING, FAULT

Alarm messages jump the TTS queue -- they are read immediately ahead of
any queued INFO messages.

Setup:
  Settings → Alarm Words → ADD → enter keyword
  Settings → Warning Words → ADD → enter keyword

Examples by industry:
  Injection molding: Alarm → ["SAFETY DOOR", "MOLD FAULT", "MATERIAL SHORT"]
  Data center: Alarm → ["UPS CRITICAL", "COOLING FAIL"], Warning → ["TEMP HIGH"]
  Logistics: Warning → ["DELAY", "HOLD", "REROUTE"]

Matching is substring-based and case-insensitive. "FAULT" matches "FAULT CODE 7".

### Anti-spam configuration

Anti-spam blocks identical messages that arrive multiple times within a
configurable time window. Prevents duplicate alerts from flooding TTS.

  Settings → Anti-Spam → adjust debounce window duration

Increase the window if your monitoring system sends repeated identical alerts.
Decrease it if you need every unique alert heard even when they arrive quickly.

---

## Section 4: Message Language Setup

The app can speak message bodies in your preferred language.

Setup:
  Settings → Status Card → Message Language row → CHANGE button
  → Select your language from the list

If your language is not listed:
  Tap ADD LANGUAGE → opens Android TTS settings → download the voice pack
  Return to the app → CHANGE → your language should now appear

Important behavior:
  - SCADA keyword prefixes (ALARM, WARNING, CRITICAL, FAULT, INFO) at the
    start of a message are always spoken in English as a separate utterance.
  - The rest of the message body is spoken in your selected language.
  - SmartSummary announcements are always in English.
  - Only offline-capable (downloaded) voice packs appear in the list.

If the Status Card shows a WARNING on the Message Language row, your selected
voice pack is no longer installed. Tap CHANGE and reinstall or select another.

---

## Section 5: Supported SMS Apps

The app detects SMS via the Android Notification Listener Service. It works
with the following SMS apps:

- Google Messages
- Samsung Messages
- AOSP Messaging (stock Android)
- OnePlus Messages (legacy)
- Sony Xperia Messages
- Honor Messages

If you use a different SMS app, the app may not detect messages. Switch to
Google Messages or Samsung Messages for reliable operation.

WhatsApp, Telegram, Signal, and other messaging apps are intentionally excluded
regardless of which SMS app you use. SMS only.

---

## Section 6: Fleet Deployment Notes

For IT administrators deploying to multiple devices:

- No centralized configuration management is available in the current version.
- Each device must be set up individually.
- Recommended workflow: fully configure one device → photograph the Settings
  screen → use it as a reference to configure other devices.
- Estimated time per device after the first: 3-5 minutes.
- The app is a standard Android application distributable via MDM.
- No server, no API, no network configuration required on the infrastructure side.
- Any system already sending SMS works immediately -- no integration changes needed.

---

## Section 7: What This App Does NOT Do

- Does NOT read WhatsApp, Telegram, email, or push notifications. SMS only.
- Does NOT require an account or registration.
- Does NOT require internet after install (only Crashlytics uses internet, for crash reports).
- Does NOT modify volume, DND settings, or Bluetooth settings.
- Does NOT support iOS / iPhone. Android only (Android 9+).
- Does NOT play audio through the phone speaker. Headset required at all times.
- Does NOT send SMS content to any server. Everything stays on the device.
- Does NOT have a cloud dashboard or centralized fleet management.
- Does NOT support MMS picture messages (text content logged but not spoken).

---

## Contact and links

- Website: https://sms-tts-notify.com
- Email: sms-tts-notify@aialertbuddy.com
- Troubleshooting: https://sms-tts-notify.com/ai/troubleshooting.txt
- Product overview: https://sms-tts-notify.com/ai/product.txt
- FAQ: https://sms-tts-notify.com/ai/faq.txt