https://github.com/ljufa/rsplayer
RSPlayer - Diy-friendly Music Player
https://github.com/ljufa/rsplayer
alsa audio-server headless linux music-player music-server nas raspberry-pi rust self-hosted
Last synced: about 2 months ago
JSON representation
RSPlayer - Diy-friendly Music Player
- Host: GitHub
- URL: https://github.com/ljufa/rsplayer
- Owner: ljufa
- License: mit
- Created: 2020-08-13T06:46:14.000Z (almost 6 years ago)
- Default Branch: main
- Last Pushed: 2026-04-21T15:23:05.000Z (2 months ago)
- Last Synced: 2026-04-21T17:33:38.870Z (2 months ago)
- Topics: alsa, audio-server, headless, linux, music-player, music-server, nas, raspberry-pi, rust, self-hosted
- Language: Rust
- Homepage: https://ljufa.github.io/rsplayer/
- Size: 91.5 MB
- Stars: 22
- Watchers: 2
- Forks: 4
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Agents: AGENTS.md
Awesome Lists containing this project
README
# RSPlayer
RSPlayer is an open-source, headless music server for Linux — run it on your NAS, home server, Raspberry Pi, or any x86_64/ARM machine and control it from any browser.
It runs as a systemd service and exposes a responsive web UI, making it a great fit for machines without a monitor or keyboard — but equally at home on a dedicated desktop audio PC. Hardware and DIY integrations (GPIO DAC control, custom firmware) are fully optional.
Under the hood RSPlayer uses [Symphonia](https://github.com/pdeljanov/Symphonia) for audio decoding and [Cpal](https://github.com/rustaudio/cpal) for output, with a Rust-native audio pipeline for low-latency, high-performance playback.
### Online demo -> https://rsplayer.dlj.freemyip.com/
## How does RSPlayer compare?
> Approximate comparison as of early 2026. Features change frequently.
| Feature | RSPlayer | Volumio | Moode Audio | MPD |
|---|---|---|---|---|
| Language | Rust | Node.js | PHP/Bash | C |
| Runs on x86_64 / NAS / server | ✓ | ✓ | Pi-only | ✓ |
| Parametric EQ / DSP | ✓ built-in | paid tier | ✓ (CamillaDSP) | via plugins |
| Multi-room | planned | paid tier | ✓ | via plugins |
| DSD playback | ✓ | ✓ | ✓ | ✓ |
| Web UI | ✓ | ✓ | ✓ | 3rd party |
| Local browser playback | ✓ | — | — | — |
| Loudness normalization (EBU R128) | ✓ | — | — | — |
| Synchronized lyrics | ✓ | — | — | — |
| Docker | ✓ | ✓ | — | ✓ |
| RISC-V 64 | ✓ | — | — | — |
| Home Assistant integration | ✓ | ✓ | — | ✓ |
| DIY hardware integration | optional | — | — | — |
| License | MIT | GPL | GPL | GPL |
## Features
- **Low Latency Output**: Direct output to ALSA or PipeWire minimizes latency.
- **Local Browser Playback**: Stream audio directly to your web browser for local playback.
- **Automatic Resampling**: High-quality FFT-based resampling (via rubato) when the output device doesn't support the source sample rate — no configuration needed. Automatically probes fallback rates for ALSA drivers that misreport their supported range.
- **Fixed Output Sample Rate**: Optionally lock the output to a specific sample rate, overriding automatic detection.
- **Multiple Music Sources**: Configure multiple local directories and network mounts as music sources, all scanned together.
- **Network Storage Management**: Discover, mount, and manage SMB/CIFS and NFS shares directly from the settings page.
- **Adjustable Playback Thread Priority**: Customize the priority of the playback thread up to a real-time rating of 99 via the settings page.
- **Dedicated CPU Core for Playback**: By default, the playback thread is pinned to a single CPU core for optimized performance.
- **Web UI Remote Control**: Manage your playback remotely with an intuitive web interface.
- **Flexible Volume Control**: Control the volume using software (alsa mixer) or hardware control (Dac chip instructions via GPIO).
- **Written in Rust**: Enjoy the benefits of minimal dependencies and high performance, thanks to the Rust native implementation.
- **Comprehensive Music Library Management**: Scan, search, and browse your music library and online radio stations with ease.
- **Dynamic Playlists**: Automatically create dynamic playlists for personalized listening experiences.
- **DSP Integration**: Advanced Digital Signal Processing with parametric EQ, filters, and presets.
- **Web UI VU Meter**: Real-time audio visualization in the web interface.
- **Extended Hardware Control**: Support for seek and power management via firmware interactions.
- **Web UI Themes**: Support for customizable themes and dark/light modes (10+ built-in themes).
- **Synchronized Lyrics**: Real-time synchronized lyrics support via LRCLIB integration.
- **Playlists by genre, year**: Browse and create playlists based on genre or year.
- **Loudness Normalization**: Per-song EBU R128 loudness normalization, toggleable from the settings page. Analysis runs automatically in the background while playback is stopped and results are stored permanently.
- **Library Statistics**: Dedicated statistics page showing song/album/artist counts, total duration, play history, top genres, albums by decade, and loudness analysis progress.
- **Priority Queue**: Add songs, albums, artists, or directories to play next without disrupting the queue order.
- **Drag-and-Drop Queue Reordering**: Reorder queue items by dragging them directly in the queue view.
- **Automatic Cache Busting**: Browser caches are automatically invalidated on every release — no stale UI after upgrading.
- **Volume Persistence**: Volume level is saved on change and restored on restart, defaulting to 0 on first use to prevent hardware-max shock.
- **Global Keyboard Shortcuts**: Full keyboard control for playback, navigation, and search (Space, arrows, M, L, Y, S, /, ?, 1-4, F/A/P/R/T).
- **Monkey's Audio (APE) Support**: Play lossless APE files with full metadata support.
- **Breadcrumb Navigation**: Clear navigation context on all library pages.
- **Skeleton Loading & Empty States**: Visual feedback during loading and helpful empty state screens.
## Known Limitations
- **DSD passthrough bypass**: DSP (parametric EQ, filters), loudness normalization, and resampling are all bypassed for DSD files (`.dsf`, `.dff`). DSD bitstreams are passed directly to the DAC without any signal processing.
- **Radio streams**: Loudness normalization is not applied to internet radio streams — it requires pre-scanned file metadata. Seeking is not supported for streams.
- **Supported formats**: Supported formats include FLAC, MP3, AAC, OGG Vorbis, WAV, AIFF, CAF, DSD (DSF/DFF), and APE (Monkey's Audio).
- **Local Browser Playback**: In this mode the browser's native audio engine plays files directly. DSP, loudness normalization, resampling, VU metering, and DSD playback are all unavailable — format support is limited to what the browser itself can decode.
### Planned features
- **Expanded Audio Codec Support**: Compatibility with a wider range of audio codecs.
- **Intelligent Dynamic Playlists**: Advanced dynamic playlists that adapt based on user likes or playback counts for a personalized listening experience.
- **Windows Compatibility**: Development of a Windows build to extend platform support.
- **MacOS Compatibility**: Development of a MacOS build to extend platform support.
- **Music Recommendations**: Suggest similar tracks or artists based on listening history or current playback.
- **Generate missing album cover image**: Auto-generate album art using album name.
- **MPD protocol support**: Compatibility with MPD clients.
- **Subsonic protocol support**: Compatibility with Subsonic clients.
- **Multi-room playback**: Synchronized playback across multiple devices.
- **MPRIS D-Bus integration**: Native Linux desktop media key and player integration.
- **Community plugin framework**: Extensible architecture for third-party plugins.
- **Improve playlists management create/modify/delete items and playlists**: Items can be added/removed to/from playlist from everywhere.
- **New version detection and upgrade from the app**: Detect a new version and provide upgrade button
- **Problem(bug) report with diagnostic**: Report problem by user
- **Scheduled music library scans**: Enable user to define automatic library scan interval (or cron)
### Planned code improvements
- Replace Bulma CSS with a modern, maintained alternative.
- Replace seed-rs with a newer, maintained framework.
- Replace `warp` with `axum` or `actix`.
## Supported Platforms
RSPlayer runs on Linux. The Deb, RPM, and Arch packages include a systemd service for automatic startup.
| Architecture | Rust Target | Binary | Deb | RPM | Arch | Docker |
|---|---|---|---|---|---|---|
| ARMv6 (Pi Zero/1) | `arm-unknown-linux-gnueabihf` | Yes | Yes | Yes | Yes | - |
| ARMv7 (Pi 2-4) | `armv7-unknown-linux-gnueabihf` | Yes | Yes | Yes | Yes | - |
| ARM64 (Pi 4 64-bit) | `aarch64-unknown-linux-gnu` | Yes | Yes | Yes | Yes | - |
| x86_64 | `x86_64-unknown-linux-gnu` | Yes | Yes | Yes | Yes | Yes |
| RISC-V 64 | `riscv64gc-unknown-linux-gnu` | Yes | Yes | Yes | Yes | - |
## Installation
To install RSPlayer, execute the following script (requires curl):
```bash
bash <(curl -s https://raw.githubusercontent.com/ljufa/rsplayer/master/install.sh)
```
The installation script detects your Linux distribution (Debian/Ubuntu, Fedora/RHEL/CentOS, Arch/Manjaro) and architecture, then installs the appropriate package. It will install all necessary files, configure and start the systemd service.
To stop RSPlayer, run the following command:
```bash
sudo systemctl stop rsplayer
```
To start RSPlayer service again, run the following command:
```bash
sudo systemctl start rsplayer
```
## Run as docker container
```bash
docker run -p 8000:80 -v ${MUSIC_DIR}:/music -v rsplayer_data:/opt/rsplayer --device /dev/snd -it --rm ljufa/rsplayer:latest
```
or [docker compose](docker-compose.yaml)
```yaml
services:
rsplayer:
image: ljufa/rsplayer:latest
devices:
- /dev/snd
ports:
- 8000:80
volumes:
- ${MUSIC_DIR}:/music:ro
- 'rsplayer_volume:/opt/rsplayer'
restart: unless-stopped
volumes:
rsplayer_volume:
driver: local
```
## Usage
Once RSPlayer is installed, you can access the web user interface by navigating to http://localhost or the IP address of the machine on which it is installed.
For detailed configuration instructions, please refer to the [documentation](https://ljufa.github.io/rsplayer/#/?id=basic-configuration).
## Home Assistant Integration
RSPlayer can be controlled from [Home Assistant](https://www.home-assistant.io/) via the [rsplayer_hacs_plugin](https://github.com/ljufa/rsplayer_hacs_plugin).
Features include media player control (play, pause, stop, next/prev, volume) and real-time sync with `rsplayer_firmware` power state.
Install via HACS by adding `https://github.com/ljufa/rsplayer_hacs_plugin` as a custom repository.
## DIY Hardware
For DIY enthusiasts, `rsplayer` offers the flexibility to integrate with custom hardware components.
- **Hardware Designs**: [rsplayer_hardware](https://github.com/ljufa/rsplayer_hardware)
- **Firmware**: [rsplayer_firmware](https://github.com/ljufa/rsplayer_firmware)
See the [Hardware Integration documentation](https://ljufa.github.io/rsplayer/#/?id=hardware-integration) for more details.
## Contributing
If you would like to contribute to RSPlayer, please submit a pull request or open an issue on the GitHub repository.
For instructions on how to build the project from source, please see the [Building from Source](https://ljufa.github.io/rsplayer/#/BUILD) documentation.
## License
RSPlayer is licensed under the MIT license. See the LICENSE file for more information.