00NeriPlayer · Music for phones and computers

Many sources, local first, hand to desktop

The songs you love live in different places. NeriPlayer brings NetEase Cloud Music, Bilibili, YouTube Music and local songs into one player, keeping playlists and listening history on your device by default. A familiar way to listen, on your phone or computer.

For Android 9 and later, with desktop previews for Windows, macOS and Linux. Free and open source under GPL-3.0.

Also on your computer: Windows · macOS · Linux desktop app ↘

Signals Multi-source Local first Self-hosted sync

Listening together tonight?

Fig. 00 — Neri and Noir the black cat, crayon on paper
scroll

01Download · 下载

Install it and start listening.

Choose your phone or computer, then pick the right download for your device and start listening.

Cut along the dotted line
NeriPlayer · Android package Free download APK
FromGitHubRELEASES
ToYour phone你的手机
Version
Latest
Released
—
Requires
Android 9+ · API 28
Price
Free · GPL-3.0
Choose architecture · ABI

SHA-256

Release — Downloads—
01.1

Releaserecommended

Published by hand once a batch of features lands, built for four ABIs: arm64-v8a, armeabi-v7a, x86 and x86_64. It isn't a strictly stable channel and may still hide issues that haven't surfaced yet.

GitHub Releases ↗
01.3

Build from source

JDK 17
# Clone the repo with its submodules
git clone --recursive https://github.com/cwuom/NeriPlayer.git
cd NeriPlayer
# Build a debug APK and install it
./gradlew :app:assembleDebug
adb install -r app/build/outputs/apk/debug/app-debug.apk

The DEBUG build uses the package moe.ouom.neriplayer.debug and an orange icon, so it installs alongside the release.

Which ABI?

arm64-v8aNearly every phone and tablet from recent years
armeabi-v7aOlder 32-bit ARM devices
x86_64 / x86Emulators, Intel devices or Chromebooks

First launch

Read the disclaimer and finish onboarding first. Onboarding explains the notification and local music permissions, which are only requested when you tap — skipping them won't stop you from using the app.

Latest train

  • Checking GitHub for the latest version…
Cut along the dotted line
NeriPlayer · Desktop preview Free download PREVIEW
FromGitHubRELEASES
ToYour PC你的电脑
Version
Latest preview
Released
—
Requires
Win 10+ · macOS 10.15+ · WebKitGTK 4.1
Price
Free · GPL-3.0
SYSTEM
Choose a package

SHA-256

Release — Downloads—
01.1

Preview releaserecommended

Published after each batch of features, with packages for Windows, macOS and Linux, plus SHA256SUMS.txt, macOS install notes and the source and build scripts for the bundled FFmpeg. When reporting an issue, include the build version from Settings → About.

GitHub Releases ↗
01.2

CI builds

To try changes that haven’t shipped yet, pick a successful run of the Artifacts workflow and download the build for your platform. You need to be signed in to GitHub; unzip the outer archive before installing.

01.3

Build from source

pnpm 9 · Rust 1.95
# Clone the repo with the lyrics submodule
git clone --recursive https://github.com/cwuom/NeriPlayer-Desktop.git
cd NeriPlayer-Desktop
pnpm install --frozen-lockfile
# Start Vite and the Tauri dev window
pnpm tauri dev

You also need the Tauri prerequisites and a toolchain to compile the FFmpeg C++ shim.

First launch

WindowsThe installer isn’t code-signed yet. If SmartScreen blocks it, choose “More info → Run anyway”; install the WebView2 runtime first if it’s missing
macOSAd-hoc signed and not notarized: drag it into Applications, open it once, then choose “Open Anyway” in System Settings → Privacy & Security
LinuxMake the AppImage executable after extracting; install deb / rpm with your distribution’s package manager

Using it with your phone

Connect both to the same GitHub repository or WebDAV folder in Backup & Sync. The first time an old format is found you’ll be asked to upgrade; update your other devices to the latest version before confirming. Audio files are never synced.

Latest train

  • Checking GitHub for the latest version…

02Dual-theme design · Themes

Two themes,
two expressions.

A look for daylight and late nights. Clean keeps things simple and spacious; Material You brings more color. Both offer light and dark modes. Try switching between them and see what feels right.

Clean brings your music forward with neutral surfaces, clear typography and a floating glass navigation bar.

03Now Playing · 正在播放

Every song has its own colors.

Play a song and watch its cover colors drift through the background. Try the themes and immersive layout, press play for Startrail, then drag the progress bar or follow the lyrics. Use the mute button below whenever you would rather just look.

Colors pulled from the cover, blended into a flowing background
5colors
The fluid background needs Android 13 or later; older versions get a plain one
Android13+
Preview theme

Media3 / RuntimeShader

01Cover colors, turned into a fluid background

The Now Playing background is drawn by BgEffectPainter, which loads a GLSL / AGSL shader and renders it frame by frame through RuntimeShader. Palette first pulls five color roles from the cover — Base, Accent, Light, Dark and Bridge — then blends them into flowing patches and grain, wired to uMusicLevel / uBeat so it moves with the beat. It is not just a Gaussian-blurred cover.

Base Accent Light Dark Bridge

This background is the app's own shader, ported to WebGL ↗

WaveformSlider

02Progress and controls, right where your thumb is

While playing, the progress bar becomes a slowly flowing wave; on pause it settles into a straight line, and while buffering it turns into a beating pulse. Underneath, quality, codec and format show as configured — like RAW · 48 kHz for this FLAC — and dragging gives haptic ticks along the lyric timeline.

Now Playing controls position

Holding the phone in one hand? Move shuffle, previous, play, next and repeat down within thumb reach, and bring the progress bar along if you like. While the controls sit at the bottom, the Dock becomes a regular toolbar so the two never overlap.

  1. 01About 30 dp wavelength and 2.3 dp amplitude, one cycle every two seconds
  2. 02Tap the quality tag to switch; speeds other than 1.00× get their own label
  3. 03Controls on Now Playing and the lyrics page each come in small, medium and large

SyncedLyricsView

03Word-by-word lyrics on the cover page, too

Under the controls sits a strip of synced lyrics: the current line lights up word by word, its translation follows only that line, and the rest fade quietly to the side. Tap a line to jump there, long-press to share. If it feels crowded, the cover-page lyrics and the bottom toolbar can each be turned off.

  1. 0118 sp on the cover page, 14 sp for translations, sized separately from the lyrics page
  2. 02Swipe left for the full lyrics page
No.NP-01Version—PlatformAndroidPage01 / 14
StatusAndroid 9+ · fluid background & advanced blur need Android 13+
Sourcecwuom/NeriPlayer · 3.7k · 131Date—
Demo track“星轨” · Neri Line · NeriPlayer PVNP
“星轨” cover Local Files
星轨 Neri Line
00:08 01:12

RAW·48 kHz

Fig. 01 — Now Playing · Change the preview with the controls above

04Lyrics · 歌词

Original and translation, lit as one.

The line being sung lights up, with its translation just below. If the timing is a little off, adjust it by hand. Turn a favorite line into a card to keep or share with a friend.

星轨Neri Line
00:13 01:12
Fig. 02 — Lyrics page, the word-level timeline of “星轨”

LRC / YRC / TTML

02Deep lyrics, in the spirit of Apple Music

Line-synced and word-synced LRC (including line-end times and bracketed word timestamps), YRC and TTML are all supported. The lyrics page only shows options the current song can actually use, and after a track change it waits until lyrics are resolved before fading in — no flash of empty space.

  1. 01Tap a line to jump to it; long-press to select lyrics, copy text, share the song or render a 1080px lyric card
  2. 02Lyric offsets can default per source; font sizes are set separately for the cover page and the lyrics page
  3. 03Source preference: Auto / NetEase / Kugou / QQ Music / LRCLIB / AMLL TTML, with word-synced lyrics preferred when matching by hand
  4. 04Floating lyrics, status-bar lyrics, SuperLyric, Lyricon and Bluetooth lyrics all reuse the same playback data

Fig. 02b — with romanization (illustration)

星の線路を そっと辿って

hoshi no senro wo sotto tadotte

For Japanese songs that ship with romanization, the secondary line can switch to it: it also sits right beneath the original, taking the translation's place instead of floating above. When a song has no romanization, the option simply isn't there — like “星轨” above, which only has “Trans”.

Fig.Clean · Real device screenshots

This is how it looks on a phone ↓

Clean home screen captured on a real phone
Home
Clean Explore screen captured on a real phone
Explore
Clean library captured on a real phone
Library
Clean settings captured on a real phone
Settings

05Sources · 多源

One player, four lines.

From NetEase Cloud Music playlists and Bilibili live performances to YouTube Music and local songs, there is plenty to discover. Search each platform separately, then add the songs you find to one queue and keep listening.

NetEase Cloud Music · Bilibili · YouTube Music
3online platforms
Songs on your phone, imported with their lyrics and covers
+local audio
NetEase · Kugou · QQ Music · LRCLIB · AMLL TTML
5lyric sources

Login · Search · Play · Download · Comments

01

NetEase Cloud Music

From daily picks and Personal FM to artist pages, NetEase is the most complete line.

  1. 01QR code / web login; the home page shows charts, new songs, daily picks, Personal FM, radar and curated playlists
  2. 02Search songs, playlists or artists, with the next page loading as you reach the bottom
  3. 03Playlist and album details are cached; on network failure it falls back to the last successful load
  4. 04Artist pages with top songs and paged albums; followed artists show up under Favorites
  5. 05Comments: hot / latest / recommended, nested replies, likes, posting and replying — drafts survive a failed send
  6. 06Your local “Liked Songs” can sync back to NetEase
Login✓Download✓
Search✓Lyrics✓
Playlists✓Comments✓

Favorites · Collections · Multi-part

02

Bilibili

Listen to video favorites like playlists: multi-part videos play and download as audio, with collection context kept all the way through.

  1. 01Web and QR login, video search, created / subscribed favorites and collections
  2. 02DASH audio retries, falling back to html5 / mp4 progressive streams when needed
  3. 03Optional BilibiliSponsorBlock: only a SHA-256 prefix of the BV ID is sent, and segments are skipped locally
  4. 04Custom skip ranges saved per BVID + CID, syncable via GitHub / WebDAV
  5. 05Comments with hot / latest, paged nested replies, likes and replies

Account sessions · Playback compatibility

03

YouTube Music

In international mode, the home page puts YouTube Music playlists and song shelves first.

  1. 01Login, home / library playlists, playlist details and search
  2. 02Logged-in cookies and anonymous visitor sessions are kept apart, with protected cookie rotation
  3. 03PoToken / JS Challenge, reusing cached bootstrap and player.js first
  4. 04When a candidate is rejected it falls back to EJS / HLS instead of retrying the same one
  5. 05Can be switched off entirely in “Settings > General” — no entry points and no background warm-up when off

Import · Scan · Organize

04

Local audio

Songs in a folder move into your library along with the lyrics and covers sitting next to them.

  1. 01Import via system share or “Open with”, scan the media library, or scan granted folders directly
  2. 02Recognizes lrc / txt lyrics and cover / folder / front artwork
  3. 03Large scans show a quick preview first, then fill in titles, artists, albums and covers in the background
  4. 04Groups by artist automatically, splitting feat. / with / 和 / 与 / slashes and other ways of writing collaborations

Automatic fallback

05

Playback fallback

When a song won't play, NeriPlayer looks for another way first instead of just throwing an error.

  1. NetEase can't play itNo permission, no usable result, or only a preview clip
  2. Lower the qualityTry each lower quality in turn
  3. Try BilibiliMatch by a title, artist and duration score
  4. Try local audioMatch readable local audio by stable metadata
  5. Still failingRefresh the playback link first; skip or stop after repeated failures

Bilibili and local fallback are off by default — switch them on yourself

Fig. 03e — the fallback flow

06Hi-Fi · 音质

Every sample, arriving untouched.

Put on your headphones and give an album your full attention. Connect a compatible external digital-to-analog converter (DAC) to your phone to use USB exclusive output. With suitable hardware and source audio, the sound can bypass the system mixer and go straight to the DAC.

  1. SourceFLAC · 24bit / 48kHz
  2. Media3ExoPlayer decoding
  3. EffectsEQ · loudness · speed
  4. AudioSink32-bit PCM / float
  5. lib_neri.soUSB exclusive transfer
  6. USB DACUAC1.0 · UAC2.0

Bit-perfect skips the effects chain ↷

Software gain −3.2 dB · through the effects chain
Fig. 04 — the signal chain from decoder to DAC
  1. 01UAC1.0 · UAC2.0 Type I PCMDevice selection, sample rate / bit depth / buffer strategy and compatibility switches
  2. 02Follows the source sample rateTries the source rate from the USB descriptors first, falling back to a rate the device supports
  3. 0332-bit PCMPCM float converted in software to the device's format
  4. 04Explicit feedback clockParses the UAC2 clock topology and feedback endpoints, recapturing after long scheduling gaps
  5. 05Recovers from stallsStartup watchdog, health audits, in-place reconfiguration and dynamic transfer scaling, falling back to system playback if it must
  6. 06Seamless in the backgroundWake strategy chosen by network or local source; USB exclusive resumes when you come back
  7. 07Regular output, done properly32-bit hi-res output, real-time loudness normalization, channel balance, pause on Bluetooth disconnect
  8. 08Honest boundariesImplicit feedback or unverifiable topologies reject the native candidate and take the compatible fallback

07Native DSP · 音效

Whatever sound you’re after, dial it in yourself.

No two headphones sound quite alike, and everyone has their own taste. The phone and desktop apps share 29 sound presets, with manual controls for vocals, bass and individual frequency bands. Play a familiar song and take your time finding the sound you like.

Sorted by genre, tone, scene and device, and you can keep fine-tuning after you pick one
29built-in presets
A draggable 10-band graphic EQ, plus up to 10 parametric bands and AutoEQ import
10+ 10 EQ bands
The app bypasses the effects chain when effects are off or all settings are neutral
Bypasswhen neutral

Settings · Audio effects & speed

05Eight sections, each with its own job

At the top are the master switch and live status: the current output device, processing load and the clipping guard. Below are eight sections, each with its own switch. Turning one off only lets that part play as original, and your values stay put; a small dot lights up next to any section you have changed. Tap a section below and the phone flips to it.

Drag a dot on the curve or switch presets, and the sound really changes ↗

星轨Neri Line
Fig. 05 — Settings · Audio Effects & Speed · every switch works

Sound previewWeb Audio approximates the effects. Your browser selects the output; native processing is available in the app.

Effect monitorModeled spectrum · switches to live analysis once you press play

Stereo field100%

OutputGR 0.0 dB

  1. Preamp前级
  2. EQGraphic · PEQ
  3. ToneBass · Treble
  4. Virtual bassHarmonics
  5. CharacterWarmth · Clarity
  6. StereoWidth · Crossfeed
  7. Surround3D
  8. ReverbRoom · Delay
  9. SpeakerBuilt-in only
  10. CompressorDynamics
  11. OutputGain · Limiter

Processing · lit stages are active

Fig. 05b — App DSP signal flow; browser audio and visuals are an approximation
  1. 01Neutral means bypassWhen effects are off, or every setting matches the original sound, the whole chain is skipped and the system can keep using low-power hardware playback
  2. 02Three processing modesPower saver uses lighter reverb and compression with no dither; high quality makes parameter changes finer and adds noise-shaped dither on 16-bit output
  3. 03Remembered per deviceThe speaker, wired headphones, Bluetooth and USB each keep their own sound, switched in automatically when you plug in or change outputs
  4. 04Bit-perfect firstUSB exclusive bypasses effects by default; with “Bit-perfect output” on, nothing is processed at all
  5. 05Shareable presetsSave a sound you like under “Mine”, copy its share code and anyone can import it in one tap
  6. 06Same on bothThe desktop app runs the same native DSP, with all 29 presets, the 10-band EQ, parametric EQ and AutoEQ / Equalizer APO import

08Listen Together · 一起听

Miles apart, on the very same song.

Share a chorus, even when your friends are far away. Create a room and send an invite to keep tracks and playback in sync. Wherever you are, there is a melody you can share.

  1. 01Host · listenersMember control switches and control requests, with host offline detection and recovery
  2. 02Same line, same secondEstimates the server clock offset and corrects past a drift threshold; single-track repeat wraps around by duration
  3. 03A shared queueDrags, adds and removals merge by room version; shuffle reuses the host's actual shuffled order
  4. 04Safe invitesJoining for the first time needs an invite key, and member keys never appear in public room state
  5. 05Candidate sharingOptionally share the host's resolved playback candidates, up to 3 per track, never written to the offline cache
LTWWorkers · DO
NeriHost
NoirListener
KaruhaListener

Room NR7K2Q · live sync

Fig. 06 — three people, one room

09Local & offline · 本地与离线

The signal drops, the song plays on.

Even where there is no signal, music can keep you company. Songs on your device and music already cached remain available offline. Playlists, history and settings stay on the device, keeping familiar music close at hand.

09.1

Offline mode

NetworkStatusMonitor detects being offline from the system's default network; while offline, remote image requests are blocked and cached covers come first.

  • Online explore & home refresh
  • Local files & downloaded songs
  • Playback cache & cached covers
  • Local playlists, recents & stats
09.2

Downloads that pick up where they left off

6 at once · up to 8
  • 星轨.flacDownloading
  • 晚安,列车.mp3Downloading
  • Polaris · HLSDownloading

No system DownloadManager: plain HTTP appends with Range, chunked transfers resume by offset, and HLS recovers from checkpoints. The queue is persisted and resumes after a restart; canceling by hand cleans up partial files.

09.3

Storage, at a glance

  • Audio cache1.0 GB
  • Image cache236 MB
  • Platform playlist cache142 MB
  • Downloads896 MB
  • Logs & crash reports9 MB
  • Core app data230 MB

Cleanup only touches caches that can be rebuilt — songs you chose to download are never treated as cache. The audio cache is capped at 1 GB by default.

09.4

Local artists, sorted for you

Neri feat. Noir / Karuha、Hanae

NeriNoirKaruhaHanae

Splits on feat., with, 和 / 与, the Chinese list comma, semicolons and slashes; artist pages can play everything, multi-select into a playlist, or batch-download online songs.

09.5

Playlist mistakes, undone

  1. 01Deleting a playlist or a song can be undone, and batch exports can roll back what they added
  2. 02Insert selected songs at a chosen position, previewing 5 songs of context on each side first
  3. 03“Local Files” is split into “Manually Added” and “Downloaded”, with total play counts in the details
09.6

Data usage, accounted for

Separates playback / download traffic, Wi‑Fi / mobile / roaming and cache hits, and warns before downloading on risky networks.

10Sync & Privacy · 同步与隐私

Your data, in your hands only.

Changing devices does not mean starting your playlists from scratch. Sync playlists, favorites and listening history through your own GitHub repository or WebDAV storage. You choose where they are kept.

  1. 015-second delay · hourlyLocal changes sync after a short delay, plus a periodic sync; scheduled by WorkManager and only run on validated networks
  2. 02Three-way mergePlaylists, favorites, history, deletion records and play stats all merge, and a song you restored won't be removed again by an old deletion
  3. 03V4 incremental formatProtobuf record streams + ZSTD chunks, no object over 2 MiB, and unchanged chunks are never uploaded again
  4. 04Atomic publishingGitHub updates conditionally via GraphQL beforeOid; WebDAV uploads immutable objects first, then writes the manifest with a strong ETag
  5. 05Encrypted on deviceCookies, YouTube auth, GitHub tokens and WebDAV passwords live in Android Keystore + EncryptedSharedPreferences

Four promises

  1. 01
    No ads, no tracking.

    No ad SDKs, third-party analytics or crash-reporting SDKs.

  2. 02
    No public music library.

    No cloud media distribution, and no personal data gathered into the maintainers' hands.

  3. 03
    Credentials stay on the device.

    Audio cache, downloads, cookies and playback tokens are never uploaded.

  4. 04
    Your accounts, protected.

    Local play history is never written back to third-party platforms, so it won't trip risk controls or suspicious-login checks.

07bPlay stats

Play counts, listening time and daily buckets are recorded against each song's stable identity, and they take part in sync merges too.

plays
186
hours listened
11.2
songs
74

Listening time

Week / month / year use rolling 7 / 30 / 365-day windows; the weekly hot list only counts songs with at least 10 minutes of total listening, and the monthly list needs 30. Neither the GitHub repository nor the WebDAV files are end-to-end encrypted, so keep them safe.

11Personalize · 个性

More than a new accent color.

Everyone has their own way of getting around. Choose which page opens first, adjust theme colors, interface and lyric sizes, and arrange the home page to suit your habits.

App theme
Seed color
Dark mode
  1. 01Dynamic color, seed color and theme style, with auto / light / dark
  2. 02OnePlus high-density screens get an automatic 0.95× correction, with your setting applied on top
  3. 03Android 13+ can turn on advanced blur, adjustable from 12–64 dp, in ultra-low / low / default / high quality
  4. 04“Continuous feedback” hands the background on to detail pages in one motion; when off, pages open like a drawer
  5. 05Lyric size and blur, home cards, start page, haptics — even each song's title, artist and cover

NeriPlayer

Continue

Local Files10 songs
Neri Line2 songs
NeriPlayer PV10 songs

Personal Radar

  1. 1
    PolarisNeri Line / NeriPlayer PV
  2. 2
    Paper PlanetsNeri Line / NeriPlayer PV
  3. 3
    Low OrbitNeri Line / NeriPlayer PV

Radar Playlists

Radar时光
雷达
时光雷达1.6B · 30 songs
Radar宝藏
雷达
宝藏雷达873.1M · 30 songs
Radar新歌
雷达
新歌雷达359.8M · 30 songs
Radar乐迷
雷达
乐迷雷达283.4M · 30 songs
Radar神秘
雷达
神秘雷达37.9M · 30 songs

Trending

  1. 1
    海边的信号Glass Harbor / NeriPlayer PV
  2. 2
    猫与汽水Soda Cat / NeriPlayer PV
  3. 3
    雨后电台Paper Satellite / NeriPlayer PV

New Picks

星轨Neri Line
Fig. 09 — Home · Clean / Material You interactive demo

12Tablet · 平板

A bigger screen, a different layout.

A bigger screen gives your music room to breathe. In landscape, cover art and lyrics sit side by side, as do settings lists and details. These four images show the app running in a tablet emulator.

A shortest side of 600 dp or more counts as a tablet, free to rotate
600dp
From 840 dp of landscape width, a side rail and two-pane settings take over
840dp
Now Playing, Library, Settings… the main pages all have tablet layouts
4page types
Tablet home in landscape: side navigation, search, three-column personal radar and playlist cards 1 2 3 4
Tablet Now Playing in landscape: cover, progress and controls on the left, full bilingual lyrics on the right 1 2 3 4
Tablet playlist in landscape: header, Manually Added / Downloaded tabs and a full-width track list 1 2 3 4
Tablet settings in landscape: grouped list and search on the left, “General” details on the right 1 2 3 4
Fig. 10 — Android tablet emulator · Clean · 2560 × 1600 landscape
  1. 01The bottom bar becomes a side rail, labeling the current page
  2. 02Search and playlist cards expand with the screen
  3. 03Personal radar spreads nine songs across three columns
  4. 04The mini player becomes a full bar: skip, shuffle, repeat, volume, Listen Together and the queue, all within reach
  1. 01Cover, progress and controls stay in the left column at a fixed width
  2. 02Lyrics sit right in the right column, original and translation together — no separate page
  3. 03Wave progress bar, quality tag and all five tool buttons, nothing left out
  4. 04The background still takes its colors from the cover, across the whole screen
  1. 01Playlist header and track list scroll together on one page
  2. 02“Manually Added / Downloaded” tabs
  3. 03The list spans the full width, with durations and more actions aligned right
  4. 04A floating queue button jumps to what's playing
  1. 01Groups and search on the left, the same structure as on phones
  2. 02Details open on the right — no jumping back and forth
  3. 03The current group is highlighted, and the two panes stay in step
  4. 04The side rail and mini player bar are always there

Phones stay locked to portrait, and only Now Playing can rotate; tablets held upright get a Now Playing layout of their own.

13Desktop · 桌面

On your computer, still the same Neri.

Let familiar songs keep you company while you write or work. The Windows, macOS and Linux previews support desktop lyrics and keyboard shortcuts for changing tracks. They can also sync playlists with your phone and join the same Listen Together room.

Windows, macOS (Apple Silicon and Intel) and Linux
3systems
Simplified Chinese, Traditional Chinese, English and Japanese
4languages
Currently a preview: ready to try and give feedback on, not yet stable
StatusPreview
Desktop home: the sidebar on the left, search at the top, “Continue playing” playlist cards and a three-column personal radar, with the player bar at the bottom
Fig. 11a — NeriPlayer Desktop · 1280 × 800 · every button works

Preview simulation, not the final versionThe app you actually run is the reference for its interface and features.

  1. 01Sidebar: Home, Explore, Library and Settings
  2. 02Search at the top; press Enter to jump to Explore
  3. 03“Continue playing” ranks recent playlists by when and how often you open them
  4. 04Player bar: progress hugs the edge, with lyrics, volume, Listen Together and the queue on the right
  1. 01The cover carries a source badge, and its colors spread into the fluid background
  2. 02AMLL word-by-word lyrics: the current line lights up, neighbors blur with depth
  3. 03A wavy progress bar, with the real bitrate and format below
  4. 04Favorite, queue, sleep timer, volume, effects and add to playlist
  1. 01Switch between local, favorites, downloads and each platform’s playlists
  2. 02Playlists, artists and local files; the local library takes multiple folders
  3. 03Drag playlists to reorder, multi-select, and right-click for more
  4. 04Play stats, recent plays and multi-select
  1. 01Cover, name, track count and total length; NetEase playlists add a description and play count
  2. 02Play all, shuffle and multi-select, plus search inside the playlist at the top
  3. 03Track rows: number, cover, artist · album and length — click “星轨” to hear it
  4. 04Every playlist card on Home and in the Library opens here; the back button returns to where you came from
  1. 01Pick a preset, then fine-tune bass, vocals, brightness, warmth and space under Listening tuning
  2. 02The theoretical response follows the EQ, preamp, tone and loudness compensation in real time
  3. 03Speaker optimization, dynamics, speed and the vinyl effect each get their own section with its own reset
  4. 04Shares one sound with the phone page above — turn a knob on either side and the other follows
  1. 0121 sections in nine groups, from accounts, playback and audio to backup, sync and About
  2. 02Search at the top jumps straight to any setting
  3. 03Switches, sliders and segmented options all respond, and groups fold away and back
  4. 04Keyboard shortcuts come in in-app and global sets, with a warning on conflicts

The window holds the real interface structure and styles exported from the desktop front end, wired to this page’s player; the tracks and covers are NeriPlayer PV samples, and no account is signed in. Light and dark follow this page, and the system can be switched at the top right. The desktop app is still in preview and this simulation is a snapshot of one moment — the version you actually run is the reference.

  1. 01Local libraryMultiple music folders, native file watching and incremental scans; titles, artists and albums can be written back to the audio files
  2. 02Downloads1–8 at once, with decodability and duration checks after download; lyrics, covers and source info are saved with the file, and the queue resumes after a restart
  3. 03Native DSP10-band EQ, up to 10 parametric bands, AutoEQ / Equalizer APO import and 29 presets, remembered per output device
  4. 04Decoding & outputRust cpal output and Symphonia decoding, with a bundled FFmpeg adding Opus, ALAC, APE, WavPack and DSD
  5. 05LyricsAMLL word-by-word rendering, translations and romanization; matched across QQ Music, NetEase, Kugou, LRCLIB and AMLL TTML, with a per-source offset
  6. 06System integrationTray, close to tray, Windows SMTC, Linux MPRIS, macOS Now Playing and menu bar lyrics
  7. 07Works with your phoneThe same V4 ProtoBuf + Zstd sync format and merge rules as Android, and Listen Together speaks the same protocol
  8. 08InterfaceFour interface languages, light and dark, cover colors, custom backgrounds and a fluid background that moves with the music

Desktop lyrics · Tray · SMTC

11Lyrics floating above everything

A separate desktop lyrics window lights up word by word, in one line, two alternating lines or three scrolling lines, with the second line showing the translation or the next line. Colors, font, outline, shadow and opacity are all adjustable; once locked, clicks pass through while an unlock button stays on hover. Close the main window and it keeps playing from the tray, with media keys and the system media session still working.

Colors

Layout

Second line

Drag the lyrics bar, then click Neri in the tray at the bottom right ↘

Fig. 11b — desktop lyrics, tray and system media session · drag and click

In-app shortcutsClick here, then try your keyboard

  • SpacePlay / pause
  • ←→Back / forward 5 s
  • Shift←→Back / forward 30 s
  • ↑↓Volume up / down
  • MMute
  • LLike
  • DDesktop lyrics

Windows · macOS · Linux

11bThree systems, each wired to its native features

One Tauri 2 + Rust core, hooked into each system’s own media session, tray and audio output. The table lists the release workflow’s targets and the platform code in the source; how the tray, lyrics and media keys look still depends on the system and desktop environment.

FeatureWindowsmacOSLinux
Media sessionSMTC: lock screen, volume flyout and headset buttonsNow Playing: Control Center and media keysMPRIS: GNOME / KDE media controls
Tray & backgroundNotification area icon; close to tray and keep playingMenu bar icon; closing the window doesn’t quitStatus area icon (depends on the desktop environment)
LyricsDesktop lyrics with click-through when lockedDesktop lyrics + menu bar lyricsDesktop lyrics with click-through when locked
Global shortcutsCtrl + Alt combosCmd + Option combosCtrl + Alt combos
Audio outputcpal · WASAPIcpal · CoreAudiocpal · ALSA
Packages.exe (NSIS) · .msi.dmg · Apple Silicon / Intel.deb · .rpm · AppImage
Requiresx64 · WebView2 runtimeApple Silicon 11.0+ · Intel 10.15+x64 · WebKitGTK 4.1 · GTK 3
First launchNot code-signed yet; choose “Run anyway” in SmartScreenAd-hoc signed; choose “Open Anyway” in Privacy & SecurityExtract the AppImage and make it executable

The desktop app has no in-app updater; grab new versions from Releases. USB exclusive, SAF and status bar lyrics are Android features; on desktop the tray, desktop lyrics, media session and shortcuts fill those roles.

14Details · 细节

The little details you meet every day.

The little things you use every day deserve care, too. Home screen widgets, long-press shortcuts and mini-player gestures save a few taps. Playback also remembers your place in long recordings.

14.1

Home screen widgets

4×2 · 2×2 · 4×1
4×2 playback card widget preview
4 × 2
2×2 mini player widget preview
2 × 2
4×1 strip widget preview
4 × 1

Material You rounded cards colored from the cover, adapting to light and dark themes, large fonts and both orientations. The wide card adds favorite and desktop-lyrics buttons; even the narrow sizes keep previous, play and next, and elapsed time ticks every second while playing.

Shown: the widget previews bundled with the app.

14.2

Launcher shortcuts

Long-press the app icon to jump straight in; when there's no queue to restore, you get feedback instead of a silent failure.

14.3

Mini player, swipe to skip

Swipe the bottom mini player left or right for the previous / next track; tap to expand and play / pause work as usual.

14.4

Floating & status-bar lyrics

Floating lyrics let you set color, outline, size, position and alignment; Meizu status-bar lyrics, SuperLyric, Lyricon and Bluetooth lyrics are supported.

14.5

In the car

Android Auto and devices with AVRCP browsing can browse the queue and playlists and search the library; connecting never starts playback by itself.

14.6

Safe mode

JVM crashes, native crashes and system ANRs are all recorded; after an abnormal exit, full initialization is skipped and the app goes straight into safe mode.

14.7

Resume long audio

Long podcasts and multi-part videos pick up where you left off; an explicitly requested position always wins over the remembered one.

14.8

Developer mode

It works the same on a real device: tap the version 7 times in Settings and a Debug tab appears in the nav bar, with per-platform probes and a log viewer.

15Inside · 构造

Fourteen modules, each minding its stretch.

Code takes care of the details behind playback, lyrics and sync. Below, fourteen Android modules show how the work is divided. It is all on GitHub. If you find the app useful, a Star is a simple way to support the project.

Cross-reference 03 Play 04 Lyrics 05 Sources 06 Hi-Fi 08 Together 09 Local 10 Sync

Modules

  • :playback:runtimeMedia3 engine, source resolution, USB output, system effects
  • :playback:logicPlayback policy, state coordination, PCM and queue rules
  • :lyricsLRC / YRC / TTML parsing, translation alignment, Lyricon integration
  • :platformNetEase, Bilibili and YouTube protocols, accounts, comments
  • :nativeUSB protocol, PCM math, exclusive transfer, packaged as lib_neri.so
  • :listentogetherListen Together protocol, WebSocket, sessions and playback sync
  • :download:runtimeDownload execution, Room queue, managed files and recovery
  • :download:logicAdmission, state transitions, retries, scheduling and commit rules
  • :localSettings, media, playlists, stats, backup and cache cleanup
  • :syncGitHub / WebDAV transport, codecs, merging and scheduling
  • :databaseRoom entities, DAOs, schema history and migrations
  • :networkShared HTTP, Range and web-login foundations
  • :modelCross-module data models and state contracts
  • :commonShared utilities, logging, strings, icons and locale support

Tools

  • KotlinJava 17 / JVM 17
  • Jetpack ComposeSingle Activity · NavHost
  • Media3 ExoPlayerPlayback core
  • AGSL / GLSLRuntimeShader fluid background
  • Room · DataStoreLocal persistence
  • WorkManagerSync and download scheduling
  • OkHttp · CoilNetwork and images
  • KSPSettings schema generation
  • NDK · C++ · CMakelibusb, exclusive transfer
  • Protobuf · ZSTDV4 sync format
  • Cloudflare WorkersDurable Objects · WebSocket
  • GitHub ActionsCI, multi-ABI releases, sanitizer gates

iFAQ · 常见问题

Anything you'd like to ask?

Q.Can local and online songs share a playlist?

Yes. Select songs in your local library, then choose “Export to Playlist” to add them to a playlist of your own, alongside online tracks.

Discussion #457 ↗

Q.Will my playlists and downloads sync to another device?

Connect both devices to the same GitHub or WebDAV sync location to sync playlists, favorites, listening history and statistics. Audio downloads are not uploaded; you will need to transfer or download them separately on the other device.

Issue #178 ↗

Q.Can NeriPlayer use songs cached by the NetEase Cloud Music app?

Usually not: that app’s private cache is isolated by Android. To save data, download songs in NeriPlayer; it will prefer the local copy when the file is available.

Discussion #431 ↗

Q.Can I sign in to Bilibili with a QR code?

Yes. In Settings → Third-party Platform Login → Bilibili, choose QR sign-in. Scan and confirm in the Bilibili app, then return to NeriPlayer. The QR page also offers web sign-in.

Issue #156 ↗

Q.Why won’t YouTube Music load after I sign in?

First, try the YouTube Music website with the same network and account. Network, region and account restrictions still apply, so signing in alone does not guarantee access to its content.

Discussion #602 ↗

Q.Is there a desktop version, and where can I get it?

Yes. NeriPlayer Desktop is available for Windows, macOS and Linux from its GitHub Releases page. It is still a preview; choose the package for your operating system and processor.

Issue #555 ↗

Q.Why is playback still shuffled after I change the repeat mode?

Shuffle and repeat are separate controls. Turn shuffle off to play in order. Repeat controls whether the queue starts over or the current track repeats; the icon with “1” means repeat one.

Issue #289 ↗

Q.Can I make the playback buttons bigger?

Yes. Open Settings → Now Playing → Now Playing control size to resize the top actions, main controls and bottom toolbar together. The lyrics page has its own control size setting.

Issue #271 ↗

Q.Where can I switch between lyric translations and phonetics?

Open Now Playing → More → Adjust Lyrics Behavior to control the second lyric line. When a song has both translations and phonetics, turn on “Show lyric translation”, then use “Show phonetics” to switch.

Issue #365 ↗

Q.Why don’t some songs show word-by-word lyrics with advanced lyrics enabled?

Word-by-word highlighting needs timing data for each word. Try another lyric source or song version under “Get Song Info” to find lyrics with word timing.

Issue #412 ↗

Q.What if lyrics look wrong in another player after downloading a song?

Try enabling metadata post-processing and “Standardized lyric embedding” in download settings, then download the song again. The latter converts embedded word-by-word lyrics to more widely supported line-by-line LRC.

Issue #362 ↗

Q.How do I adjust volume during USB exclusive playback?

With “Bit-perfect output” off, use the volume keys, lock screen or system volume panel. With it on, the keys adjust the DAC’s hardware volume when supported. Otherwise, switch bit-perfect output off to adjust volume on your phone.

Discussion #296 ↗