A native music player for Linux, drawn in the Nodalia Design Language.
Installation · Sources · Preview · Why Vinilo · First launch · Contributing · Translations · Support
Vinilo is a native front-end for the music you already pay for, not a website wrapped in a window. The interface is GTK4 drawn in the Nodalia Design Language. Apple Music still needs Apple's own player and Google's official Widevine CDM, so a small Chromium process stays hidden after sign-in. Local files never touch it.
The app talks to a small engine that keeps playing in the background, so closing the window does not stop the music.
Important
Apple Music needs an active subscription, an x86_64 machine and a network connection on every play. Linux Widevine cannot keep licences offline, so there is no download button and there never will be.
Tip
This computer plays MP3, FLAC, Ogg and WAV on its own. No Chromium, no account, no sidecar. Choose that source on first launch if you only want files.
The music in these screenshots is a demo collection made for them: invented albums and covers, no account.
| Interface | Playback | Desktop |
|---|---|---|
| A native app in the Nodalia Design Language, not a website in a frame | Gapless playback, queue, lyrics and karaoke with a voice level on catalogue tracks | Play, pause and skip from the top bar, lock screen or media keys |
| Your library: songs, albums, artists and playlists | The catalogues you already use, searchable from one place | Music keeps going when you close the window |
| English or Spanish, or the system language | Crossfade, local listening stats, optional Last.fm scrobbling | Open audio files straight from the file manager |
Vinilo is built for daily listening: one queue, one native interface, and a small hidden web layer only where DRM requires it.
| Source | Channel | What you need |
|---|---|---|
| Apple Music | Stable | Active subscription, x86_64, network on every play |
| This computer | Stable | Audio files on disk |
| Spotify | Stable | Sign-in. Premium uses librespot; otherwise a fallback |
| YouTube Music | Beta | Sign-in |
| Tidal | Alpha | Sign-in |
Favourites, library saves and new playlists are available from the row menu
where the source allows it. Change language or source later in
Preferences (Ctrl+,).
Vinilo keeps play counts and time listened on this machine (sidebar → Listening). To mirror that online, open Preferences → Last.fm:
- Create an API account at last.fm/api/account/create.
- Paste the API key and shared secret.
- Click Connect, authorize Vinilo in the browser, then I authorized Vinilo.
Scrobbles and now-playing updates go out from the engine for every source.
Credentials live in ~/.config/vinilo/lastfm.json and are never written to
logs.
Build and install from a clone of this repository, inside that directory,
into ~/.local (no sudo).
-
Install the build and runtime packages:
sudo pacman -S --needed base-devel pkgconf rustup gtk4 librsvg \ nodejs npm libpulse alsa-lib yt-dlp ffmpeg webkitgtk-6.0 rustup default stable # Vinilo needs Rust ≥ 1.93 (edition 2024) -
Clone and install:
git clone https://github.com/danielmigueltejedor/vinilo.git cd vinilo make install -
Open Vinilo from the app grid, or run
vinilo.
The first Apple Music install also fetches castLabs Electron (~200 MB) for the Widevine CDM. Local-only use skips that once you never open Apple Music.
Tip
On fish, GNOME's PATH often omits ~/.local/bin. Add it once with
fish_add_path ~/.local/bin.
cd ~/vinilo
pkill vinilo; pkill vinilod
make updatemake update discards a dirty local Cargo.lock, fast-forwards main and
reinstalls. If the grid still launches nothing, the desktop file must read
Exec=/home/YOU/.local/bin/vinilo-desktop. Log out once if an icon or launcher
looks stale.
Every release ships two editions as separate DMGs. They have their own bundle identifiers and their own settings, so they install side by side:
| DMG | Edition | What it is |
|---|---|---|
Vinilo-<version>-native-macos-arm64.dmg |
Vinilo Native | SwiftUI, with the system's own controls and, on macOS 26, Liquid Glass |
Vinilo-<version>-nodalia-macos-arm64.dmg |
Vinilo Nodalia | the GTK interface in the Nodalia Design Language, the same as on Linux |
Download one from the latest release, open it and drag it to Applications. The apps are signed ad-hoc, not notarized, so the first time macOS refuses to open one: right-click it in Applications, choose Open, and confirm. See docs/macos-editions.md for how the two differ, how to build them, and what is and is not verified.
YouTube Music, Tidal and links play through yt-dlp and ffmpeg:
brew install yt-dlp ffmpeg. Those sources sign in through your browser, and
Vinilo reads the session back when you press Done.
To build Vinilo Nodalia yourself: brew install gtk4 librsvg adwaita-icon-theme pkgconf node,
then cargo build --release && make sidecar && packaging/macos/bundle.sh dist/macos.
For Vinilo Native: cargo build --release -p vinilod && make sidecar && platforms/apple/build.sh dist/macos.
In Files: right-click a track → Open With → Vinilo → Always. Or:
xdg-mime default dev.danielmiguelt.Vinilo.desktop audio/mpeg
xdg-mime default dev.danielmiguelt.Vinilo.desktop audio/flac
xdg-mime default dev.danielmiguelt.Vinilo.desktop audio/oggcargo run # the app
make sidecar-run # hidden player, window visible (DRM isolation)
make check # fmt + clippy + tests- The interface follows the system language (English or Spanish). Change it in Preferences if you want.
- Choose a source: Apple Music, this computer, Spotify, YouTube Music or Tidal.
- Streaming sources open a sign-in window you cannot skip. Sign out from the app menu to pick another source.
- The Apple Music library is cached for the next start. Local files play as soon as you open them.
On Linux the window draws Nodalia's minimise, maximise and close buttons. To use your desktop's instead (GNOME, KDE…), turn on Desktop window controls in Preferences and restart Vinilo.
Language lives in ~/.config/vinilo/locale. The source lives in
~/.config/vinilo/provider. Catalogue sessions stay in cookies next to that;
tokens are never written to disk.
┌────────────────────────────┐
│ Vinilo GTK4 / Nodalia │
│ library · search · player │
└─────────────┬──────────────┘
│ JSON on a Unix socket
┌────────────────────────────▼──────────────────────────────────┐
│ vinilod — the engine no window │
│ queue · desktop controls · artwork · local files · cache │
│ listen stats · Last.fm scrobbles │
└──────────────┬──────────────────────────────┬────────────────┘
│ Apple Music │ files / catalogues
┌──────────────▼──────────────┐ ┌──────────▼────────────────┐
│ sidecar castLabs Electron │ │ rodio in the engine │
│ MusicKit + Widevine CDM │ │ MP3, FLAC, streams… │
└─────────────────────────────┘ └───────────────────────────┘
Apple Music goes through Apple's MusicKit player and Google's official CDM. Vinilo does not strip DRM, cache decrypted audio, or offer downloads.
| Constraint | Why |
|---|---|
| No offline Apple Music | Linux Widevine cannot persist licences |
| ~200 MB Chromium sidecar | Only if you use Apple Music |
| x86_64 only for Apple Music | Linux ARM Widevine is not a stable target |
| Spotify and Apple Music are ready; YouTube Music is Beta; Tidal is Alpha | Catalogue clients are still settling |
| Karaoke voice attenuation is catalogue / local only | MusicKit never hands Vinilo samples |
| Apple Music on macOS needs the player VMP-signed | Release builds sign it with castLabs EVS (packaging/macos/vmp_sign.sh); a build without that signature does not offer Apple Music on macOS, since Apple would play only 90-second previews. Local files and Spotify are unaffected |
| macOS: no media keys or Now Playing yet | The shell controls are MPRIS, which is Linux's |
Patches, bug reports and translations are welcome.
-
Fork and branch from
main(feat/…,fix/…,docs/…). -
Keep changes focused. The engine lives in
crates/vinilo-coreandcrates/vinilod; drawing belongs incrates/vinilo. A terminal client that draws nothing should still be able to use anything you add to the engine. -
Before opening a pull request:
make check # rustfmt + clippy -D warnings + tests -
Use conventional commits (
feat:,fix:,docs:,refactor:,chore:). -
Do not paste tokens, cookies,
settings.iniorlastfm.jsoninto issues or PRs. -
Read
CLAUDE.md/AGENTS.mdbefore large changes — especially the DRM line we do not cross, and MusicKit owning the queue.
Licensing: every new source file needs the two-line SPDX header
(GPL-3.0-or-later).
Strings are runtime tables in
crates/vinilo-core/src/i18n.rs, not
gettext. The app and the engine both call t(Key::…), so one edit covers
both.
- Add a variant to
Language(and usually toLocale). - Add an
xx(Key) -> &'static strtable besideen/es— everyKeymust be covered; the compiler will tell you if one is missing. - Wire it in
t(),Locale::parse,Locale::resolve, and the Preferences language combo (native name + index). - Search for other
match current()arms that build sentences outsidet(plurals, shortcuts) and extend those too.
- Prefer short, GNOME-flavoured wording over marketing copy.
- Keep placeholders (
{}) identical across languages when a string is filled withreplace. - Re-run
make checkafter editing the tables;rustfmtis picky about long string literals.
The user's choice is stored in ~/.config/vinilo/locale (system, en, or
es). System follows LC_MESSAGES / LANG and falls back to English when the
tag is unsupported.
- Use GitHub Issues for reproducible bugs and focused feature requests.
- Include your installed Vinilo version, distribution, GTK version and the source (Apple Music, local, Spotify, YouTube Music or Tidal).
- Never paste tokens, cookies,
settings.iniorlastfm.jsoninto an issue.
Vinilo is a Nodalia app. Linux Apple Music playback through castLabs Electron
follows the path opened by Sidra and Cider. Copyright notices for code by other
authors are kept in the source files and listed in NOTICE.
Vinilo is released under the GPL-3.0-or-later.
Designed and maintained by Daniel Miguel Tejedor.