plexamp-lite/spec.md

Plexamp Lite (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 Plexamp-style Plex music player for the Samsung Galaxy Mini that keeps playing reliably at home, away and over a Bluetooth speaker.

Target and hard limits

• Samsung Galaxy Mini GT-S5570: Android 2.2/2.3 (API 8), 240×320 ldpi, 600 MHz ARMv6, 384 MB RAM; any 2.2+ phone.
• Native Java (this app uses XML layouts), no libraries beyond the bundled Bouncy Castle TLS.
• Galician by default, English in Settings. All text in tools/strings.py, which generates res/values*/strings.xml. The connection log stays in English.
• Plays MP3/AAC/Vorbis directly; FLAC, ALAC and the rest are transcoded to MP3 by the server.

Current scope (1.13)

• Sign in with a plex.tv/link PIN (or a manual address + token). Owned and shared servers and libraries.
• Connection picking: last good one first, then LAN HTTP, LAN HTTPS (plex.direct), remote HTTPS, Relay (capped at 192 kbps). Secure addresses tried one at a time; re-checked on network changes.
• Bundled TLS 1.2/1.3 with session resumption; a loopback StreamProxy feeds the media player.
• Quality per network (home, away, Bluetooth cap), read-ahead of the next two tracks, stall and failure recovery (re-pick, then download first), resume after short Bluetooth drop-outs.
• Home radios and shelves, Artists/Albums/Playlists, Search, artist/album/playlist pages, Now Playing, Up Next queue (survives restarts), sleep timer, love, downloads to SD card with offline play reporting.
• Headset and Bluetooth buttons; pauses for calls and unplugging. Plays reported to Plex.

Out of scope

• Gapless playback and notification playback buttons (Android 2.x can't), video, photos.

Must not break

• Package com.minamp and signing/minamp.keystore (password minamp123): updates install over Minamp.
• Signing: tools/signapk.py (classic SignApk v1); never jarsigner.
• src/com/minamp/net/ is the origin of tlskit; keep the two in step (change ../tlskit, reinstall).
• This repo's tools/setup_toolchain.sh, make_roots.py and signapk.py prepare the toolchain all the Galaxy Mini apps use: changes there affect every app.
• Installs to internal storage (SD-card installs get killed during USB sharing).

Code map

PlayerService (playback, recovery) · PlayQueue · Downloads · plex/ (Plex, Server, Library, Item) · net/ (Http, CertVerifier, StreamProxy, Threads, DiagLog) · activities Home, Browse, NowPlaying, Queue, Search, Setup, Downloads.

Build, test, release

• tools/setup_toolchain.sh once, then ./build.sh → build/PlexampLite.apk.
• Tests on the desktop JVM: PlexTest with test/mock_plex.py, QueueTest, PreferHomeTest with test/identity_server.py, NetTest, HandshakeProfile.
• Release: raise versionCode/versionName, build, add changes in ../tenda-lite/repo/apps.json, commit and push, ../tenda-lite/repo/publish.sh.
• Siblings for iPod, Mac and Linux (plexamp-lite-ios, -mac, -linux) share behaviour; fixes are often backported between them.