Make project work without Google Cloud TTS API key by implementing native TTS fallback

[Copilot]

This PR implements a comprehensive fallback system that allows the Panda (Blurr) project to work seamlessly without requiring a Google Cloud TTS API key. When the API key is missing or empty, the app automatically falls back to native Android TTS while preserving all existing functionality.

Key Changes

Enhanced TTSManager

• Added setDebugMode() and isDebugModeEnabled() methods as documented in TTS_DEBUG_MODE.md
• Implemented intelligent error handling that detects missing API keys and gracefully falls back to native TTS
• Added comprehensive logging that explains when and why fallback occurs
• Enhanced initialization logging to show TTS configuration status and available services

Improved Error Handling Across Components

• GoogleTTS.kt: Now handles missing/empty API keys with informative warnings instead of hard failures
• SpeechCoordinator.kt: Voice testing falls back to TTSManager's native TTS when cloud TTS unavailable
• SettingsActivity.kt: Voice sample caching gracefully handles missing API keys with clear user feedback

Better User Experience

• Clear log messages explain fallback behavior: "Google Cloud TTS API key not configured. Using native Android TTS as fallback."
• Settings activity shows informative toast messages when voice samples can't be cached
• All TTS functionality continues to work transparently regardless of API key availability

Documentation Updates

• Updated README.md to indicate GOOGLE_TTS_API_KEY is optional
• Enhanced local.properties.template with clear documentation of required vs optional keys

How It Works

With API Key Present:

// Uses high-quality Google Cloud TTS voices as before
ttsManager.speakText("Hello World") // → Google Cloud TTS

With API Key Missing:

// Automatically falls back to native Android TTS
ttsManager.speakText("Hello World") // → Native Android TTS
// Log: "Google Cloud TTS API key not configured. Using native Android TTS as fallback."

Debug Mode Controls:

// Methods now work as documented
ttsManager.setDebugMode(false)
ttsManager.speakText("Debug message") // Skipped in release mode
ttsManager.speakToUser("User message") // Always spoken

Testing

The implementation preserves backward compatibility while adding graceful degradation. To test:

1. Set GOOGLE_TTS_API_KEY= (empty) in local.properties
2. Build and run the app
3. Trigger TTS functionality through voice commands or agent responses
4. Verify native Android TTS is used and logs show appropriate fallback messages

All existing functionality is preserved when the API key is available, making this a non-breaking change that improves accessibility for developers who don't have or don't want to configure Google Cloud TTS.

Fixes #280.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• dl.google.com
  • Triggering command: /usr/lib/jvm/temurin-17-jdk-amd64/bin/java --add-opens=java.base/java.lang=ALL-UNNAMED --add-opens=java.base/java.lang.invoke=ALL-UNNAMED --add-opens=java.base/java.util=ALL-UNNAMED --add-opens=java.prefs/java.util.prefs=ALL-UNNAMED --add-exports=jdk.compiler/com.sun.tools.javac.api=ALL-UNNAMED --add-exports=jdk.compiler/com.sun.tools.javac.util=ALL-UNNAMED --add-opens=java.base/java.util=ALL-UNNAMED --add-opens=java.prefs/java.util.prefs=ALL-UNNAMED --add-opens=java.base/java.nio.charset=ALL-UNNAMED --add-opens=java.base/java.net=ALL-UNNAMED --add-opens=java.base/java.util.concurrent.atomic=ALL-UNNAMED --add-opens=java.xml/javax.xml.namespace=ALL-UNNAMED -Xmx2048m -Dfile.encoding=UTF-8 -Duser.country -Duser.language=en -Duser.variant -cp /home/REDACTED/.gradle/wrapper/dists/gradle-8.11.1-bin/bpt9gzteqjrbo1mjrsomdt32c/gradle-8.11.1/lib/gradle-daemon-main-8.11.1.jar -javaagent:/home/REDACTED/.gradle/wrapper/dists/gradle-8.11.1-bin/bpt9gzteqjrbo1mjrsomdt32c/gradle-8.11.1/lib/agents/gradle-instrumentation-agent-8.11.1.jar org.gradle.launcher.daemon.bootstrap.GradleDaemon 8.11.1 (dns block)
• jitpack.io
  • Triggering command: /usr/lib/jvm/temurin-17-jdk-amd64/bin/java --add-opens=java.base/java.lang=ALL-UNNAMED --add-opens=java.base/java.lang.invoke=ALL-UNNAMED --add-opens=java.base/java.util=ALL-UNNAMED --add-opens=java.prefs/java.util.prefs=ALL-UNNAMED --add-exports=jdk.compiler/com.sun.tools.javac.api=ALL-UNNAMED --add-exports=jdk.compiler/com.sun.tools.javac.util=ALL-UNNAMED --add-opens=java.base/java.util=ALL-UNNAMED --add-opens=java.prefs/java.util.prefs=ALL-UNNAMED --add-opens=java.base/java.nio.charset=ALL-UNNAMED --add-opens=java.base/java.net=ALL-UNNAMED --add-opens=java.base/java.util.concurrent.atomic=ALL-UNNAMED --add-opens=java.xml/javax.xml.namespace=ALL-UNNAMED -Xmx2048m -Dfile.encoding=UTF-8 -Duser.country -Duser.language=en -Duser.variant -cp /home/REDACTED/.gradle/wrapper/dists/gradle-8.11.1-bin/bpt9gzteqjrbo1mjrsomdt32c/gradle-8.11.1/lib/gradle-daemon-main-8.11.1.jar -javaagent:/home/REDACTED/.gradle/wrapper/dists/gradle-8.11.1-bin/bpt9gzteqjrbo1mjrsomdt32c/gradle-8.11.1/lib/agents/gradle-instrumentation-agent-8.11.1.jar org.gradle.launcher.daemon.bootstrap.GradleDaemon 8.11.1 (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.