index.md — rendered

Rendering...

# EpubReader 📚

***A versatile and user-friendly EPUB reader/viewer for Windows, Android, iOS, and macOS***

*Enjoy your favorite ebooks with extensive customization options and robust support for various EPUB formats*

[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=ne0rrmatrix_EpubReader&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=ne0rrmatrix_EpubReader)
[![.NET MAUI](https://img.shields.io/badge/.NET%20MAUI-Cross%20Platform-blue)](https://dotnet.microsoft.com/en-us/apps/maui)
[![License](https://img.shields.io/github/license/ne0rrmatrix/EpubReader)](LICENSE.txt)
[![GitHub stars](https://img.shields.io/github/stars/ne0rrmatrix/EpubReader)](https://github.com/ne0rrmatrix/EpubReader/stargazers)
[![GitHub issues](https://img.shields.io/github/issues/ne0rrmatrix/EpubReader)](https://github.com/ne0rrmatrix/EpubReader/issues)

</div>

---

## 📋 Table of Contents

- [✨ Features](#-features)
- [📸 Screenshots](#-screenshots)
- [🚀 Get Started](#-get-started)
- [🛠️ Building from Source](#️-building-from-source)
  - [PowerShell Build Scripts](#powershell-build-scripts)
- [🔥 Firebase Setup](#-firebase-setup)
- [📸 Screenshots](#-screenshots)
- [🛠️ Development](#️-development)
- [🤝 Contributing](#-contributing)
- [📄 License](#-license)

---

## ✨ Features

### 🌐 Cross-Platform Compatibility
Available on **Windows**, **Android**, **iOS**, and **macOS** with native performance on each platform.

### 📖 Reading Customization
- **📑 Chapter & Page Navigation:** Navigate seamlessly through chapters and pages
- **🎨 Font Customization:** Adjust font family and font size to your preference
- **📍 Reading Position:** Automatic tracking of reading position when switching between books
- **🎨 Color Themes:** Various color themes with automatic dark/light mode switching
- **📊 Library Sorting:** Sort by title, author, or date (on Calibre Server)

### ☁️ Cloud Sync & Authentication
- **🔐 Google Authentication:** Sign in with your Google account for cloud features
- **📱 Cross-Device Sync:** Reading progress and settings sync across devices in real-time
- **🔄 Automatic Backup:** Reading progress is automatically backed up to Firebase
- **📍 Position Tracking:** Resume reading exactly where you left off on any device
- **🔁 Offline Queueing:** Progress updates queue locally and reconcile on reconnect
- **🔒 Local-Only Mode:** Use the app without authentication for complete privacy

- **🔐 Privacy:** An in-app privacy policy is available under Settings → Privacy Policy or online: [Privacy Policy](https://ne0rrmatrix.github.io/EpubReader/privacy.html). Cloud sync is optional and must be enabled by the user.

### 🔗 Calibre Integration
- **🔍 Discovery:** Connect to Calibre Server using **Bonjour** auto-discovery
- **🌐 Manual Connection:** Set Calibre Server URL directly
- **📚 Library Access:** Navigate your entire Calibre library
- **⬇️ Download:** Download EPUB books directly from your server

### 📚 EPUB Support
- **📖 Format Support:** Full support for **EPUB 2** and **EPUB 3.x** versions
- **🔧 Compatibility:** Enhanced compatibility for out-of-spec and broken EPUBs
- **🎯 Reliability:** Most ebooks work seamlessly (minor issues only with extremely malformed files)

### 🎨 Rich Content Display
- **🖼️ Images:** Full support for embedded images
- **💄 CSS Styling:** Complete CSS styles support within books
- **🔤 Fonts:** Full support for fonts embedded within ebooks

### 🔊 Media Overlays (EPUB 3)
- **Audio Playback:** Plays synchronized audio tracks embedded via MediaOverlays
- **SMIL Highlighting:** Highlights text in sync with audio using SMIL files
- **Read-Along Support:** Provides a seamless read-along experience with word/phrase highlighting
- **Granular Controls:** Play/pause and navigation work across chapters with overlays

---

## 📸 Screenshots

### Windows

#### 🖥️ Default Light Mode Theme

---

#### 🌙 Dark Mode Theme (Sepia)

---

### 📱 Android

#### ☀️ Light Mode (Sepia Theme)

---

#### 🌙 Dark Mode

---

## 🚀 Getting Started

### Download Now

</div>

---

## 🛠️ Building from Source

### Prerequisites

- Visual Studio 2022/2026 or later with .NET MAUI workload (or the .NET SDK + workloads via CLI)
- .NET 10.0 SDK or later
- Platform SDKs: Android SDK (API 34+), Windows App SDK, Xcode (macOS only) for iOS/macOS

### Clone the repository

```bash
git clone https://github.com/ne0rrmatrix/EpubReader.git
cd EpubReader
```

### Restore & build (CLI)

Restore packages and build for a specific target framework (example: Android):

```bash
dotnet restore EpubReader/EpubReader.csproj
dotnet build EpubReader/EpubReader.csproj -f net10.0-android -c Debug
```

For Windows debug build:

```bash
dotnet build EpubReader/EpubReader.csproj -f net10.0-windows10.0.19041.0 -c Debug
```

### PowerShell build scripts

The repository includes helper PowerShell scripts to make builds and signing easier:

- `build.ps1` — main build script that supports `-Android`, `-Windows`, `-DebugBuild`, `-ReleaseBuild` and accepts Firebase secrets via parameters, env vars, or `build-secrets` folder.
- `build-from-env.ps1` — loads secrets from `.env`/.env.local and runs the build.
- `gen-android-strings.ps1` — converts `google-services.json` to Android XML resource strings for signing and embedding.

Example: build Android Debug using local json

```powershell
.\build.ps1 -Android -GoogleJsonPath "build-secrets/google-services.json" -DebugBuild
```

### Using .env files

Create a `.env` or `.env.local` with your Firebase and signing values (gitignored) and run:

```powershell
.\.vscode\build-from-env.ps1
```

### Android signing (release)

Set these environment variables (or add to `.env.local`):

- `ANDROID_KEYSTORE` — path to keystore
- `ANDROID_KEYSTORE_PASSWORD` — keystore password
- `ANDROID_KEYSTORE_ALIAS` — alias
- `ANDROID_KEY_PASSWORD` — key password

The scripts will sign artifacts when `ANDROID_KEYSTORE` points to a valid file.

### Troubleshooting

- If `google-services.json` is not found, place it under `build-secrets/google-services.json` or pass `-GoogleJsonPath` to `build.ps1`.
- For package name or SHA mismatches, verify `ApplicationId` in `EpubReader.csproj` and AndroidManifest package attribute match the Firebase app.
- Use `dotnet workload install maui,android,ios,windows` to ensure required workloads are installed.

---