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 box 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. Two things do reach the internet, both switchable: the metadata lookups that repair your tags (MusicBrainz, Wikidata, Deezer, Cover Art Archive), and an hourly check for a published release.
-
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) or Ubuntu 24.04, one command installs everything:
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 wizard. It asks where your music is and where the sound should come out. There are no config files to edit. What each step asks.
-
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 box next to an amplifier, or play in a browser tab.
Full installation guide → It covers the images, virtual machines, Wi-Fi and logins, updates and troubleshooting.
| 🎵 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 MP3 up to 192 kHz / 24-bit, gapless between tracks of the same format, and the samples are not altered unless you turn on software volume. |
| 🏠 Renderers anywhere | Put a renderer on any box 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 and Jamendo ship in the box; MusicCast handles Yamaha volume and power. |
| 🪄 Guided first run | A setup wizard runs in the app and in the browser alike — name the server, point it at your music, pick an output, done. Nothing to edit on the server itself. |
| ⚙️ Live configuration | Everything stays editable afterwards from Settings, with a simple tier of common fields 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 box 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 box 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 a remote, adding music and more outputs, updates, troubleshooting |
| First-run setup | Every step of the setup wizard, in the app and in the browser |
| App manual | An illustrated tour of the app |
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 how to send a change, 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 |
| 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.