音理音理!

✨ A native Android audio player that combines multi-source streaming, local control, rich lyrics, and self-hosted sync 🎵

The project name and icon are inspired by "Kazamata Neri" from "星空鉄道とシロの旅".

NeriPlayer is a native Android app for Android 9 (API 28) and above, focused on multi-source exploration, online playback, local control, and user-owned data.

●About NeriPlayer is a native Android audio player built with Jetpack Compose + Media3. It does not build a public cloud service. Instead, it integrates online content from NetEase Cloud Music, Bilibili, and YouTube Music when the user has the corresponding third-party platform account capability. It also provides local playback, downloads, caching, playlist management, and several sync/backup options.

●Current positioning:

・Account as capability: third-party platform authorization enables search, playback, playlists, and favorites access. ・Local-first: playback cache, downloads, playlists, history, settings, and auth data are stored locally on the device by default. ・Optional sync: playlists, favorites, recent plays, track playback stats, playlist open counts, and local-playlist playback stats can be synced to your own GitHub repository (repositories created in-app default to private) or a WebDAV remote file. ・Privacy and account safety first: sync is intentionally decentralized. Data is written to GitHub/WebDAV storage that you control, not to a centralized service operated by the project maintainer. The app is technically capable of sending playback history back to third-party music platforms, but centralized music clients often have risk-control and behavior-sampling systems. Uploading local playback history directly may be interpreted as abnormal login or playback behavior and could put an account at risk. To protect account safety, NeriPlayer does not upload local playback history or playback stats back to those platforms. ・Single Activity + Compose: MainActivity is the only external entry point. The UI is organized by Compose NavHost, a dynamic bottom bar, Mini Player, and the Now Playing overlay. ・Startup and recovery flow: the normal startup path is Loading -> Disclaimer -> Onboarding -> Main. If the previous launch ended in a crash or system ANR, the app enters Safe Mode first. ・Test guardrails: download storage, sync merging, YouTube playback compatibility, Listen Together, lyrics, playback policies, config backup, and safe mode all have focused unit or device tests.

●Why it stands out

▲Local-first, with real offline behavior: NetworkStatusMonitor follows Android's default direct network transport, while offlineCachedImageRequest disables remote image requests in offline mode and falls back to local caches. Home, Explore, Now Playing, Lyrics, playlists, and downloads all receive offlineMode, so local files, downloaded audio, playback cache, cached covers, and local playlists remain usable without a network.

▲Multi-source playback is not just a list of entry points: PlayerManager owns playback resolution, queues, and failure recovery. When a NetEase track is unavailable, has no playable result, or only returns a preview, the player first tries a lower quality, then PlayerManagerNeteaseAutoSourceSwitch scores Bilibili candidates by title, artist, and duration. Playback errors can also refresh the current URL before falling back to skip/stop behavior.

▲YouTube playback compatibility has layered fallbacks: valid signed-in identity cookies are preserved and rotated when needed, while anonymous visitor sessions keep separate bootstrap and PoToken state. Verified signature/n, player.js, and challenge results are cached and reused; stale player code or a platform-rejected playback candidate falls through to EJS/HLS instead of retrying the same unusable candidate.

▲High-performance GLSL/AGSL fluid background: the Now Playing dynamic background is rendered frame-by-frame by BgEffectPainter, RuntimeShader, and assets/shaders/hyper_background_effect.glsl. The shader combines cover-derived colors, animated color blobs, and lightweight grain while reacting to uMusicLevel / uBeat; it is not just a Gaussian-blurred cover. The RuntimeShader/audio-reactive path requires Android 13+. Cover blur requires Android 12+, while advanced blur requires Android 13+; older versions automatically use a compatible fallback without those effects.

▲Apple Music-style lyrics, backed by the playback pipeline: SyncedLyricsView and AdvancedLyricsView support line-, word-, and character-timed LRC (including trailing timestamps and square-bracket word timestamps), plus YRC/TTML highlighting, translated lyrics, phonetic display, lyric offset, click-to-seek, long-press sharing, depth blur, edge fade, and a full-screen Lyrics page. LyricShareSheet can select lyric lines, copy text, share the song, or render a 1080px lyric card. The Now Playing cover lyric view and bottom Dock can be disabled independently; narrow or heavily scaled portrait layouts switch to a compact control arrangement with stable touch slots. Long-press selection can select a range from the first line to the target line. Lyrics-page Japanese lines that contain kana get extra translation spacing so dense glyphs and translations do not crowd each other. Floating lyrics, status-bar lyrics, SuperLyric, Lyricon, Bluetooth lyrics, and lyric editing reuse the same playback data path.

▲Complete local music management: LocalAudioImportManager supports external share/open imports, authorized folder scanning, device media-library scanning, common audio formats, nearby lrc/txt lyrics, and cover/folder/front cover files. Large scans can show a quick preview first, then hydrate richer title/artist/album/cover metadata in the background. LocalPlaylistRepository manages system local playlists, user playlists, favorites, sorting, de-duplication, backup, and sync triggers.

▲Library browsing now has real categories: Library is no longer just a playlist list. Local content can switch between playlists and artists, while LocalArtistSummary groups songs by display artist, splits common collaboration artist text, and keeps stable identity and cover selection. NetEase songs can open an artist page with songs, albums, and follow state.

▲Large screens and daily controls are getting real polish: tablet/landscape Now Playing, Lyrics, Settings, and artist pages use steadier width constraints and bottom control layouts. The Mini Player supports horizontal swipe for previous/next without expanding the full player. Home widgets add a 4x2 playback card and a 2x2 mini player. Card backgrounds and the primary play button derive their colors from the current artwork. The 4x2 card shows the song, artwork, progress, four playback controls, and a floating-lyrics entry; the 2x2 layout makes artwork the main visual while keeping the three core playback controls. Launcher shortcuts can continue playback, open Explore, open Library, or shuffle My Favorite Music. Main bottom tabs use interruptible directional page transitions that retain both outgoing and incoming scenes, avoiding glass, scroll-state, and page-state discontinuities during rapid switching. Long-pressing the Now Playing artwork opens an immersive preview with pinch-to-zoom, panning, and a download action.

▲Sound controls are tied to the active audio session: PlaybackEffectsController applies speed, pitch, Android Equalizer, and LoudnessEnhancer to the current Media3 audio session. Presets, manual bands, loudness gain, per-track real-time normalization, fade/crossfade, pause on Bluetooth disconnect, channel balance, 32-bit high-resolution system output, USB exclusive playback, and audio-focus behavior are all available. Native USB exclusive playback currently targets UAC1.0 and compatible UAC2.0 Type I PCM audio devices, so system sounds and other apps cannot share the USB transport on that path. Device selection, sample-rate/bit-depth/ buffer policies, 32-bit PCM, software PCM-float conversion, background-playback guidance, UAC2 clock-topology and explicit-feedback endpoint resolution, startup watchdogs, foreground/background health audits, dynamic transfer scaling, and automatic stall recovery are now part of the path. After a long scheduling gap, the runtime reacquires the feedback clock instead of continuing with a stale rate estimate. Foreground/background recovery chooses wake behavior from the network or local source, and bit-perfect volume keeps software gain at 0 dB so the DAC controls the level. Settings report battery-optimization or background-permission limits. While service playback is retained, a background audio anchor selects silence or a zero-mean carrier for the actual output route; MediaSession provides remote volume routing and the carrier is not user content.

▲Downloads have moved from "can save" to "can recover": downloads do not use the system DownloadManager. They use the shared OkHttpClient, configurable concurrency, staging files, and sidecar metadata. Direct HTTP transfers, platform-specific range transfers, and HLS each have a resume strategy. Network-policy pauses can continue later, startup recovery restores unfinished queues, and already-finalized local hits are settled directly. Manual cancellation cleans up partial artifacts.

▲Storage usage is visible and cleanup has boundaries: StorageUsageAnalyzer groups audio cache, image cache, download staging, share staging, platform playlist cache, downloaded content, logs, crash reports, and core app data. Cache cleanup targets regenerable cache data and does not treat user-saved downloads as disposable cache.

▲Self-owned sync plus playback stats: NeriPlayer does not provide a public cloud library or developer-hosted user data service. GitHub/WebDAV sync stores playlists, favorites, recent plays, and playback stats in the user's own remote. PlaybackStatsRepository records play count, total listen time, first/last played time, and daily buckets by stable track identity, then participates in sync merging. Remote sync snapshots tolerate legacy or malformed missing-field payloads, filter records without resolvable track identity, and keep songs with missing addedAt behind dated songs in current display-order playlists. Playback and traffic statistics use debounced batch writes, flush at important lifecycle points, and keep a bounded number of daily buckets.

▲Traffic controls are built into the product, not bolted on later: TrafficStatsRepository tracks playback/download bytes, Wi-Fi/mobile/roaming distribution, and cache-hit bytes. Download flows can also warn before high-risk mobile or roaming transfers.

▲Highly personalized, beyond theme colors: AutoSettingsSchema covers dynamic colors, seed colors, palette style, auto/light/dark mode, UI scaling, custom backgrounds, lyric font size, lyric blur, two-level advanced blur, Coherent Feedback, the fluid Now Playing background, Home card toggles, default start destination, haptic feedback, and custom song title/artist/cover metadata. OnePlus devices with high-density displays (densityDpi >= 500) automatically apply an additional 0.95x UI correction; normal-density devices skip it, while the user's manual scale remains an additional multiplier. Enhanced Advanced Blur and Coherent Feedback are off by default. With Coherent Feedback off, playlist and related detail pages use a drawer-style transition. Enhanced Advanced Blur is available only on Android 13+ while its parent blur setting is enabled. It adds shared live-glass material to screen-level top tabs, the bottom tab bar, and structural settings cards without changing foreground content, layout, or touch targets. Its blur radius is adjustable from 12-64 dp. Blur quality is configured separately as Ultra Low, Low, Default, or High. Ultra Low and Low retain Default's blur coverage while using region-local rendering, dynamic downsampling, and RenderNode hardware caching to reduce render work. A detected Dimensity SoC defaults to Ultra Low until a preference is saved; local caches are rebuilt after background/foreground transitions and quality changes to avoid an invalid backdrop after resuming. High requires Enhanced Advanced Blur.

▲ANR, crash logs, and safe mode form a diagnostics loop: AnrWatchdog reads Android ApplicationExitInfo.REASON_ANR and stores the system ANR trace. ExceptionHandler and NativeCrashHandler record JVM and native crashes. If the previous startup failed, SafeModeManager can skip full app initialization and open safe mode for preview, copy, or export.

▲Listen Together syncs the room, not just a progress bar: the Android client and Cloudflare Worker maintain rooms, roles, queues, playback state, repeat/shuffle modes, controller-offline recovery, member control requests, optional session playback-candidate sharing, version-gated updates, and custom server URLs. Repeat/shuffle changes use PLAYBACK_MODE / REQUEST_PLAYBACK_MODE, while member controls and asynchronous playback-candidate results validate the target stable track key so they cannot affect a track that has already changed. The client also estimates server clock offset, corrects position drift by threshold, and reloads the authoritative playback candidate after an asynchronous shared candidate result arrives so pending local startup cannot override the room's pause/play command. Invites must carry the room secret needed for a first join, while member secrets are kept out of public room state. Local tracks cannot create or replace a room track. When session candidate sharing is enabled, Durable Objects temporarily cache the controller's current playback candidates so listeners can retrieve them without waiting for another controller response. A current track keeps at most three validated candidates; listeners always resolve with their own quality policy first, try those local candidates first, and keep the session-only candidates as isolated startup fallbacks, so they never enter song or offline caches. Valid playback-mode queue snapshots reuse the requester's real shuffle or restored order without reloading the current track. Mode commits re-anchor projected position with the previous repeat semantics. When enabled, member joins and explicit departures publish an authoritative room pause; reconnecting with the same member credential does not trigger that pause, and both roles keep their WebSocket connection alive. A transport-only disconnect remains reconnectable. Durable Objects persist room state while WebSocket keeps active members in sync.

●Interface language: Chinese, English ●Project homepage: https://github.com/cwuom/NeriPlayer

🎯 Project author:github@cwuom