mirror of
https://github.com/fabiodalez-dev/Monochrome-Android-APK.git
synced 2026-10-18 23:07:33 -05:00
fabiodalez-dev
3b5503bb45
Major wrapper rewrite with architecture-level improvements: Search & Performance: - Debounce 3000ms → 700ms with min 3-char threshold - Explicit &limit=100 on all search endpoints (shows all albums) - Cache normalization: trim/lowercase/NFD diacritics (Björk = bjork) - Per-type TTL: tracks 10min, artists 60min, albums 30min - CDN preconnect/dns-prefetch for Tidal API endpoints Android Native: - WebView hardening: cache mode, DOM storage, text zoom, HW accel - AudioForegroundService: ExecutorService + LruCache for cover art - MediaSession hardware keys (headphones, Bluetooth, car stereo) - LocalFilesBridge: content:// URI streaming (no more base64 OOM) - Safe onDestroy with try/catch, RECEIVER_NOT_EXPORTED - windowSoftInputMode=adjustResize, WindowInsetsController migration - Splash screen config, largeHeap, hardwareAccelerated in manifest - Back button dismisses modals/lyrics/fullscreen before navigating UI/UX: - Tap targets ≥ 48dp, touch feedback (active state), route fade - Responsive card grid (2-4 cols based on screen width) - Pull-to-refresh, swipe left/right on now-playing-bar - Safe-area CSS variables (--fm-safe-top/bottom) - Double-back-to-exit with toast confirmation Build System: - fm-build.sh: one-shot install + build entry point - verify-patches.sh: dry-run patch verification (CI-ready) - PATCHES.md: full documentation of all 50+ optimizations - Robust cleanup trap (file-by-file git checkout) - @capgo/capacitor-media-session shimmed (our ForegroundService wins) - Upstream bug workarounds: sourcemap-codec override, backtick typo Bug Fixes: - JS injection via filename (escape backslash before apostrophe) - Timer leak in setInterval without clearInterval - Notification channel created once (singleton pattern) - Notification ID reuse (no tray accumulation) - ClipboardManager null check - DownloadBridge thread-safe with background executor Closes #4: haptic/vibration feedback removed entirely.
Fabiodalez Music — Android App
Android wrapper for Monochrome, a privacy-respecting music streaming application.
Features
- Background playback — Foreground Service keeps audio playing when the screen is off
- Media controls — Play/pause/skip in the notification shade, lock screen, and Bluetooth
- Battery optimization bypass — Requests exclusion from Android's battery killer on first launch
- Downloads — Saves tracks to
Downloads/FabiodalezMusic/with Android notification - Local files — Select Music Folder works on Android (native folder picker)
- OAuth — Last.fm/Libre.fm authentication via Chrome Custom Tab
- Clipboard — Copy to clipboard works natively
- Bluetooth auto-pause — Music pauses automatically when Bluetooth disconnects
- Full UI — Navigation bar visible, status bar visible with safe area padding
- Back navigation — Back button in header for album/artist/playlist navigation
- Branding — "Fabiodalez Music" name, custom splash screen
Requirements
- macOS (with Homebrew)
- JDK 21 (
brew install openjdk@21) - Android command-line tools (
brew install --cask android-commandlinetools)
Quick Start
# 1. Clone Monochrome
git clone https://github.com/monochrome-music/monochrome.git
cd monochrome
git remote rename origin upstream
# 2. Clone this overlay
cd ..
git clone https://github.com/fabiodalez-dev/Monochrome-Android-APK
# 3. Install overlay into Monochrome
cd Monochrome-Android-APK
chmod +x install.sh
./install.sh ../monochrome
# 4. Build APK
cd ../monochrome
./build-android.sh
The APK will be at Monochrome-debug.apk.
Updating
When Monochrome releases updates:
cd monochrome
./build-android.sh
The script automatically pulls the latest from upstream, applies patches, builds, and restores all files. No manual work needed.
How It Works
The build script temporarily patches these upstream files during build:
index.html— adds viewport-fit, script tag, brand namepackage.json— adds Capacitor dependencies
All patches are reverted after build. The upstream repo stays clean.
The Android-specific code lives entirely in:
android/— Native Java code (foreground service, download bridge, etc.)android/android-service.js— JS bridge (media controls, downloads, CSS, back button)capacitor.config.ts— Capacitor configurationbuild-android.sh— Build automation
Architecture
Monochrome (upstream web app)
│
├── Capacitor WebView (wraps the web app)
│
├── android-service.js (injected at build time)
│ ├── Download handler (monkey-patches <a download>)
│ ├── Media controls (MutationObserver on document.title)
│ ├── CSS injection (safe areas, layout fixes)
│ ├── Back button (history.pushState hook)
│ ├── Clipboard override (AndroidBridge)
│ └── OAuth override (window.open → Chrome Custom Tab)
│
└── Native Java
├── AudioForegroundService (MediaSession + notification)
├── AudioServicePlugin (Capacitor bridge)
├── DownloadBridge (MediaStore file saving)
├── LocalFilesBridge (Android folder picker)
└── AndroidBridge (clipboard, browser)
License
Same as Monochrome.