podlite/spec.md

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.11)

• 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.

Out of scope

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

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.
• 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.