# Podlite (Android) — spec

The short contract for working on this app. `README.md` is the user guide; this file says what the app is
for, what limits it lives within, and what must not break.

## Goal

A small Audiobookshelf podcast client for the Samsung Galaxy Mini whose progress stays in sync with the
server and other apps.

## Target and hard limits

- Samsung Galaxy Mini GT-S5570 and other Android 2.2+ phones (API 8), 240×320 ldpi.
- Native Java, no libraries beyond the bundled TLS stack. All sizes in `res/values/dimens.xml`.
- Galician interface; warm dark colours with an amber accent (from the radio icon).

## Current scope (1.12)

- Login with user/password (refreshes 2.26+ short-lived tokens; older servers' long-lived token) or an API key.
- HTTP on the LAN; bundled TLS 1.2 for `https://` (Mozilla roots); other certificates shown by fingerprint,
  trusted once (trusting the issuing CA so renewals work), forgettable in Settings.
- Loopback stream proxy for HTTPS, forwarding seeks with a fresh token per request.
- Tabs: Latest (continue listening + newest), Shows, Saved (SD-card downloads, Wi-Fi only by default).
- Player: skip back/forward (amounts in Settings), seek, show notes, sleep timer, mark played, close.
- Progress sync every 15 s and on pause; offline positions sent later.
- Headset buttons; pauses for calls and unplugging.

## Android 4.1 build

- `build/Podlite-api16.apk` (minSdk/targetSdk 16) next to `build/Podlite.apk` (API 8): shared `src/`, per-level
  `platform/api8|api16/…/Platform.java` with the same methods, `platform/api16/res` overlaid. ExoPlayer with speed and
  skip silences, notification and lock screen with cover and buttons, Holo, ⋮ without a Menu key, metered networks.

## Out of scope

- Audiobooks, HLS/transcoded streams (so no Opus); playback speed on Android 2.x (it can't).

## Must not break

- An episode only counts as played within a minute of its real end; drop-outs and cut files are retried or
  reported, never marked played. A stall of 12 s is reported.
- Package `com.miniabs` and `miniabs.keystore` (password `miniabs`): updates install over MiniABS.
- `src/com/miniabs/net/` is a copy of `tlskit`: change it in `../tlskit` and reinstall.
- `platform/api8` and `platform/api16` keep the same `Platform` methods; shared code calls no API the API 8 jar lacks
  (the api8 compile and Dalvik check catch it). Each build's `versionCode` is the manifest's × 100 + level, same key;
  both APKs are listed in `../tenda-lite/repo/apps.json`.
- The Android 4.1 build targets API 16: network on the main thread is allowed in `Platform.init`; keep the desktop
  tests' files (`Util`, `Api`…) free of `Platform`.
- Installs to internal storage.

## Code map

`Api` · `PlayerService` · `StreamProxy` · `DownloadService` / `Downloads` · `Trust` / `TrustPrompt` · `Prefs` ·
activities Home, Podcast, Player, Login, Settings · `net/` tlskit · `tools/make_icons.py`, `translate_gl.py`.

## Build, test, release

- `ANDROID_JAR=/path/to/android-8/android.jar ./build.sh` (JDK, aapt, dx, zipalign, apksigner, `BC_SRC`).
- `JSON_JAR=… test/run_tests.sh`: API, JSON, progress, HTTPS trust and proxy against `test/mock_abs.py`,
  with good, expired, wrong-host, forged and self-signed certificates (`test/make_pki.sh`).
- Release: raise `versionCode`/`versionName`, build, add `changes` in `../tenda-lite/repo/apps.json`, commit
  and push, `../tenda-lite/repo/publish.sh`.
- Siblings: `podlite-ios`, `podlite-mac`; behaviour fixes are backported between them.