Bit-perfect playback from your own library, on your own hardware — with on-device semantic search. No cloud, no subscription, no account.
💿 Flash an image · 📦 Releases · 📱 Control app · 🌐 kalinkaplayer.com · 💬 Help test it
Kalinka turns a Raspberry Pi or any Linux computer into a music player you control from your phone, desktop or a browser. The server holds your library; a separate renderer does the playing, talking to ALSA directly — so it can sit on the same machine, or on a Pi next to each amplifier in the house.
Your files stay yours — nothing is uploaded, there is no account and no telemetry, and the semantic search runs on the device. Optional internet requests cover metadata lookups that repair your tags (MusicBrainz, Wikidata, Deezer, Cover Art Archive), hourly checks for published releases, and the public plugin catalog, from which the app installs, updates and removes plugins. Fetching requires no account; see the catalog configuration and trust model.
-
Install the server. On a Raspberry Pi or a spare PC, flash a ready-made image: Kalinka is already on it and plays as soon as the machine starts. On a machine that already runs Debian 13, Raspberry Pi OS (64-bit, Trixie), DietPi or Ubuntu 24.04, one command installs everything:
sudo apt install -y curl python3 curl -fsSL https://kalinkaplayer.com/install.sh | sudo bashIt runs in a virtual machine too.
-
Open a remote. Install the Kalinka app (Android, Windows, Linux), which finds the server by itself, or open
http://<server-address>:8000in any browser. -
Follow the setup in the app. It asks where your music is and where the sound should come out. There are no config files to edit.
-
Add your music, and more outputs if you like. Copy music onto it or point it at a NAS, and put a renderer on any Linux computer next to an amplifier, or play in a browser tab.
Full installation guide → It covers the images, virtual machines, Wi-Fi and logins, the supervisor, updates and troubleshooting.
Setting up Wi-Fi from a laptop? Join Kalinka-Setup-XXXX with password kalinka-setup, stay connected without internet, then open http://192.168.4.1. The full steps also cover Bluetooth setup from the app.
| 🎵 Your library | Indexes your directories, watches them for changes, and repairs the metadata — MusicBrainz, Wikidata and Deezer, plus AcoustID fingerprinting once you add a key of your own, falling back to filename heuristics. Artwork is extracted, cached, and generated when there is none. |
| 🔍 Smart Search | Ask for "dreamy ambient guitar" and get matching tracks. My Library analyses the audio itself with a CLAP model; Jamendo matches a prebuilt index of track descriptions. Opt-in per plugin. |
| 🔊 Bit-perfect playback | A C++ renderer with direct ALSA access. FLAC and WAV include 24-bit/96 kHz and 192 kHz playback; WAV also supports 32-bit PCM and float on compatible outputs. MP3 and Ogg Vorbis are supported too. Gapless between tracks of the same format; samples are not altered unless you turn on software volume. Mono and stereo DSF and uncompressed DFF play as native DSD or DoP through a compatible direct ALSA output at fixed volume, once DSD output is selected in the renderer's settings. |
| 🏠 Renderers anywhere | Put a renderer on any computer on your network and it appears as an output. They find the server over mDNS and upgrade themselves. |
| 🌐 Browser player | The server serves a web player, so any browser is both a remote control and an output. |
| 🧩 Plugins | Sources, enrichers and device integrations are ordinary Python packages discovered at runtime. My Library, Jamendo and a UPnP renderer input ship in the box; MusicCast handles Yamaha volume and power. |
| 🪄 Guided first run | The app and the browser player walk you through the first setup. Nothing to edit on the server itself. |
| ⚙️ Live configuration | Everything stays editable afterwards from the app, with the common settings up front and an about:config-style search for the rest. |
| 🔄 Updates itself | The server checks published releases hourly; with auto-upgrade on it installs during quiet hours while playback is stopped, otherwise the app offers a button. Server, plugins, browser player and renderers move together — renderers first, so the pair never lands on a combination that cannot play. |
A 64-bit OS is required — packages are built for arm64 and amd64 only. On Raspberry Pi that means the Kalinka image, Raspberry Pi OS (64-bit) or DietPi (64-bit); the Pi 2, Pi 1 and original Pi Zero are not supported.
| Configuration | Minimum hardware | Notes |
|---|---|---|
| Playback + library | Raspberry Pi 3 / Zero 2 W, or any arm64/amd64 computer with 512 MB RAM | Headless OS recommended at 512 MB; enable swap for the first install and large scans. 1 GB is comfortable. |
| With Smart Search | Raspberry Pi 4B with 2 GB RAM, or any arm64/amd64 computer with 2 GB+ | Measured on a 4 GB Pi 4B: ~1.15 GB resident with the library indexed and idle, and ~1.5 GB at the peak — the embedding pass, which loads a second model on top and is CPU-heavy. 2 GB should therefore work; 4 GB is what has actually been tested end to end. Allow ~1 GB extra disk. |
Smart Search can be toggled per install, so you can start small and enable it after moving the library to a bigger board.
Audio is played by a renderer, not by the server, so gapless and bit-perfect behaviour depend on which renderer you use.
The default one (kalinka-renderer, C++) talks to the sound card directly. It does not alter the audio unless specifically instructed to — software volume being the one thing that does. The app shows whether the current route is 1:1: a hw: device takes the samples unchanged, plughw: resamples and reformats whatever the card will not accept, and default or a sound server mixes with everything else. What it cannot see is a resampler configured elsewhere in your ALSA stack.*
In-browser playback goes through the browser's audio stack, so there is no gapless and no bit-perfect guarantee there — it is a convenience path.
| Installation | Installing the server, connecting it to your network, adding music and more outputs, the supervisor, updates, troubleshooting |
Kalinka is young, and the interesting problems are the ones that only happen on someone else's hardware, with someone else's music. If you try it, say how it went in the testing thread — what you ran it on, where your music lives, what you played it through, and where you got stuck. Setup questions belong there too; something you can reproduce is easier to act on as an issue.
See CONTRIBUTING.md for what issues and pull requests are accepted, and for the project's disclosure on AI-assisted development.
| Architecture | How the pieces fit, the package layout, the REST/WS API, configuration and tuning |
| Development | Building the Debian packages, running from source, tests |
| Renderer design | The contract a renderer implements |
| Plugin catalog design | Proposed discovery, installation, compatibility checks, and updates |
| TIDAL plugin | Account sign-in, discovery catalogs, collection browsing, and lossless streaming |
| Appliance images | How the ready-to-flash images are built |
| Releasing | Version model and release procedure |
Source code is GPL-3.0-or-later — see LICENSE.
The visual assets are not. The Kalinka logo, icon and related artwork under docs/images/ are covered by the Kalinka Asset License and need the author's permission to use. Fork the code freely; put your own branding on it.
Third-party components and their terms are listed in THIRD-PARTY-NOTICES.md.
* The audio engine uses ALSA directly and relies on its configuration. If automatic resampling is configured it will likely affect the path but should still work. Developed and tested on a Raspberry Pi 4 with a HiFiBerry Digi2 card configured per its manual; it should work with any ALSA-compatible card, though some may need extra quirks.