Roboto and dark mode	OpenDyslexic3 and light mode

Narra is a mobile app (currently Android exclusive) that allows users to listen to webpages and ebooks read aloud by TTS in a podcast-like experience. Choose from a wide variety* of TTS voices, subscribe to the RSS feeds of your favourite blogs, and queue up several texts to listen to without ads.

*At least, that's the goal.

This project was vibecoded by someone who didn't start the project with the skills required to write this code by hand. I started out using Gemini 3 Flash because of its integration with Android Studio and generous free tier, but have since switched to using more recent and capable lightweight open models like Deepseek V4.1 Flash via Opencode (both the harness and the cloud hosting).

I understand that I have a lot to learn in order to be a good head dev for this project, and I am sharing this repo with the hope of getting it looked over by more qualified devs.

I can't guarantee that data won't be lost when updating, even though I've done what I can to implement database protection features. If you want to ensure that you keep your listening history and the content that you add to the app, please keep backups. OPML exports are handy for backing up feeds, but the database backup feature could potentially have problems that need fixing.

Follow these steps to set up the development environment and build Narra.

Requires Android Studio Quail 4 (2026.1.4) or newer and JDK 21 or higher.

1. Clone the repository:

   git clone https://github.com/mienaiKnife/Narra.git

2. Open the project: Open Android Studio and select "Open" to choose the project directory.

3. Gradle Sync: Wait for the project to finish syncing. If there are any issues, go to File > Sync Project with Gradle Files.

4. Select the app configuration and your target device (emulator or physical device).

5. Click the Run button or use the shortcut Shift + F10.

If you just want an APK and would rather not install Android Studio, you can build inside a disposable Docker container instead. The only requirement on your machine is Docker (or Podman).

1. Build a debug APK:

   ./build-apk.sh

   The APK will be written to out/debug/app-debug.apk.

2. Build a release APK:

   ./build-apk.sh assembleRelease

   The Docker build produces an unsigned, minified release APK. To build a signed release, see docs/RELEASING.md.

3. Install on a device:

   adb install out/debug/app-debug.apk

The first run downloads the Android SDK and project dependencies, so it takes a few minutes. Subsequent builds reuse cached layers and Gradle dependencies, so they are usually under a minute. See Dockerfile for details.

Run unit tests using the following command:

./gradlew test

• User Guide - Learn how to use Narra's features
• AGENTS.md - Guide to the project for AI agents
• Localization - Guide to translating Narra into new languages
• Architecture - Learn about the project's technical design
• TTS Engines - Guide for implementing and extending TTS providers
• Content Parsing - How we extract text from RSS, ebooks, and Web
• Playback Lifecycle - Understanding the media service and audio flow
• Testing Guide - How to run and write tests for Narra
• Releasing - Signing, versioning, and publishing releases
• Contributing - How to contribute, coding standards, and tests
• Roadmap - Where the project is headed
• Privacy Policy - Our commitment to your privacy
• Security Policy - How to report a vulnerability

• RSS Feed Subscription: Subscribe to blog feeds and automatically fetch new articles.
• Web Page Importing: Extract clean text from webpages using a reader-mode heuristic for a distraction-free experience.
• EPUB Support: Import and listen to DRM-free ebook files in EPUB format.
• Listening Queue: A playlist-style UI for managing and listening to multiple articles in sequence.
• Multiple TTS Engines: Support for Android's built-in TTS and natural-sounding, on-device AI voices (Sherpa-ONNX).
• Background Playback: Foreground service support for uninterrupted listening with system media controls and lock screen integration.
• Home Screen Widget: Glance-based widget for quick playback control and queue status.
• Database Backup & Sync: File-based backup/restore and optional auto-export for manual syncing (e.g., via Syncthing).
• OPML Support: Import and export your feed list for easy migration between RSS apps.
• Privacy First: No accounts required; all data and TTS synthesis stay on your device.

See ROADMAP.md for planned features and non-goals.