Audire

A local-first audiobook and e-book player for Android. Play your personal audio library and read PDF/EPUB documents offline — no cloud, no subscriptions, no tracking.

• Features
• Architecture Overview
• Project Structure
• Data Layer
• UI Screens
• Background Playback
• Theme System
• Internationalization
• Permissions
• Dependencies
• Build & Run
• Known Limitations & Technical Debt

┌─────────────────────────────────────────┐
│              MainActivity               │  Single Activity
│  (Compose UI — all screens in one file) │
└──────────────┬──────────────────────────┘
               │ observes StateFlow
┌──────────────▼──────────────────────────┐
│          AudiobookViewModel             │  MVVM — AndroidViewModel
│  Player · Library · Stats · Settings    │
└──────┬──────────────────────────┬───────┘
       │ coroutines                │ PlaybackController (singleton bridge)
┌──────▼──────┐         ┌─────────▼────────────────┐
│  Room DB    │         │  AudiobookPlaybackService │  Foreground Service
│  (3 tables) │         │  (media notification)     │
└─────────────┘         └──────────────────────────┘

Patterns in use:

• MVVM — AudiobookViewModel + StateFlow drives all UI state
• Repository — AudiobookRepository abstracts the DAO and owns domain rules
• Singleton bridge — PlaybackController connects the Service to the ViewModel without a bound service
• Coroutines — all async work via viewModelScope, Dispatchers.IO/Default/Main

Intentional simplifications (see Known Limitations):

• Navigation is a rememberSaveable { mutableStateOf("Library") } string — no Compose Navigation NavHost
• All UI lives in MainActivity.kt — no per-screen files
• One ViewModel serves all 5 screens

source/app/src/main/java/com/example/
│
├── MainActivity.kt               # Single Activity + all Composable screens (~3 200 lines)
├── AudiobookPlaybackService.kt   # Foreground Service for background audio
├── PlaybackController.kt         # Singleton bridge: Service ↔ ViewModel
├── LanguageManager.kt            # Runtime i18n dictionary (ES / EN)
│
├── data/
│   ├── Audiobook.kt              # Room @Entity — audio files and documents
│   ├── ScanDirectory.kt          # Room @Entity — user-granted scoped storage URIs
│   ├── ListeningLog.kt           # Room @Entity — one row per calendar day
│   ├── AudiobookDao.kt           # @Dao — all CRUD for the three entities
│   ├── AudiobookDatabase.kt      # @Database singleton (Room v3)
│   └── AudiobookRepository.kt   # Repository with immutable-progress rule
│
└── ui/
    ├── viewmodel/
    │   └── AudiobookViewModel.kt # AndroidViewModel — all app state
    └── theme/
        ├── Color.kt              # Material 3 color tokens
        ├── Theme.kt              # MyApplicationTheme — 7 color schemes
        └── Type.kt               # Typography scale

Represents any media item in the library. Audio files and documents (PDF/EPUB) share the same entity — type is inferred from filePath extension at runtime.

Tracks user-granted scoped storage tree URIs.

One record per calendar day for statistics.

Immutable Progress Rule (AudiobookRepository.updatePlaybackPosition): The saved position can never decrease unless isExplicitRewind = true is explicitly passed. This prevents accidental progress regression from seek events or service restarts. A book is marked isCompleted when the position reaches within 2 seconds of its total duration.

• Name: sanctuary_database
• Room version: 3
• Migration strategy: fallbackToDestructiveMigration (no migration scripts — DB is rebuilt on schema change)
• Single AudiobookDao covers all three entities

Navigation is state-driven — a selectedTab: String in MainScreen drives a when block swapping composables. There is no NavHost.

App Launch
  └── MainScreen
        ├── Onboarding Dialog (first launch — blocks until a directory is selected)
        │
        ├── "Library" → LibraryScreen
        │     ├── tap audio file  → PlayerScreen
        │     └── tap PDF/EPUB    → ReaderScreen
        │
        ├── "Player" → PlayerScreen
        │     └── document loaded → "Enter Reading Mode" → ReaderScreen
        │
        ├── "Reader" → ReaderScreen (TopBar + BottomBar hidden, fullscreen)
        │     └── back → LibraryScreen
        │
        ├── "Stats"    → StatsScreen
        └── "Settings" → SettingsScreen

Displays the user's book collection.

• Full-text search across title and author
• Status filters: All · Favorites · In Progress · Completed
• Format filters: All · Audiobooks · PDFs · EPUBs
• LazyColumn of AudiobookCard items with reading progress bar
• Per-card cover image picker (system gallery)
• Empty state with a directory picker call-to-action

Standard audio player UI.

• Cover art (tap to replace from gallery)
• Title, author, autosave status pill
• Seek slider with elapsed / remaining time
• Controls: −30s skip, Play/Pause, +30s skip
• Playback speed cycle: 0.75× → 1× → 1.25× → 1.5× → 2× → ...
• Sleep timer button (UI only — not yet implemented)
• Chapters and Bookmarks buttons (UI only — not yet implemented)
• For PDF/EPUB files: redirects to ReaderScreen instead

Immersive reading experience.

• EPUB: HorizontalPager, serif font, adjustable font size (12–36sp), TTS narration per page, page slider
• PDF: LazyColumn of rendered bitmap pages, pinch-to-zoom, optional "clean text mode" toggle
• Double-tap anywhere to toggle immersive (fullscreen) mode
• TTS play/pause toggle with speed control in the top bar
• Page progress slider and prev/next page buttons in the bottom bar

Listening analytics.

• Daily progress circular indicator vs 60-minute goal
• Current streak / Max streak cards
• Rank system: Rookie → Avid Listener → Grandmaster → Audire Sage (based on total hours)
• 7-day bar chart (dynamic scale)
• Stats simulator: +/−15 min buttons and full reset (for testing)

App configuration.

• Language: ES / EN toggle
• Theme: Dark · Light · Peach Sunset · Abyss Marine · Sage Mystic · Cosmic Slate · Custom (hex color picker for primary, background, secondary)
• Permissions: storage access toggle, background playback toggle
• Auto-save interval: 5s / 10s / 30s / Manual
• Voice personalization: TTS engine configuration, naturalness (noise_scale) and expressiveness (noise_w) sliders, voice test button
• Scan directories: list of added directories, add/remove, title count per folder
• Diagnostics: DB latency, buffer health, cache usage, API version
• System testing: simulate incoming call, headset disconnect, forced close
• Reset: purge entire database and library

AudiobookPlaybackService is an Android Service with foregroundServiceType="mediaPlayback".

Lifecycle:

1. AudiobookViewModel.syncWithPlaybackService() is called after every playback state change
2. The service creates/updates a persistent media notification with Play/Pause and Stop actions
3. Notification actions send intents back to the service (ACTION_PLAY, ACTION_PAUSE, ACTION_STOP, ACTION_UPDATE)
4. The service delegates actual audio control to PlaybackController, which calls viewModel.togglePlayPause()

PlaybackController is a Kotlin object (singleton) that holds a nullable reference to the active AudiobookViewModel. The ViewModel registers itself in init and clears the reference in onCleared.

MyApplicationTheme in Theme.kt supports 7 color schemes:

Custom themes use buildDynamicColorScheme() which auto-detects light vs dark mode from the background color's luminance (> 0.45f → light), then derives appropriate text, surface, and container colors automatically.

Theme selection and custom hex values are persisted to SharedPreferences ("audire_prefs") and survive process death.

LanguageManager is a Kotlin object that holds two Map<String, String> dictionaries (Spanish and English). All UI strings that need translation call LanguageManager.getString(key, lang). There are no Android strings.xml resources — the entire i18n system is code-based.

The selected language ("es" or "en") is stored in SharedPreferences and exposed as a StateFlow from the ViewModel. Composables collect this flow and re-render when the language changes.

All file access uses Scoped Storage (DocumentFile.fromTreeUri + contentResolver.takePersistableUriPermission). No raw file path scanning.

Not yet in use (declared but disabled): Firebase AI, CameraX, Accompanist Permissions, Datastore, Navigation Compose, Play Services Location.

• Android Studio Hedgehog or later
• JDK 11
• Android SDK 36 (compileSdk)
• Minimum device: Android 7.0 (API 24)

# Clone
git clone <repo-url>
cd Audire/source

# Open in Android Studio and run on a device or emulator (API 24+)

Release builds expect the following environment variables:

KEYSTORE_PATH   — path to .jks file (default: <root>/my-upload-key.jks)
STORE_PASSWORD  — keystore password
KEY_PASSWORD    — key password

Debug builds use debug.keystore at the project root with standard Android debug credentials.

On first launch, an onboarding dialog prompts the user to select a folder. The app will scan that folder for audio files and documents. Three demo titles are pre-loaded (Don Quijote, El Principito, and a streaming sample of La Metamorfosis) if the library is empty after the initial scan.