How Kalinka works.

Point Kalinka at folders on the box, on a USB drive or on a NAS. Network shares work without mounting anything: Kalinka connects to SMB shares itself. It indexes everything, watches the folders for changes and skips files that are still being copied.

Most collections have messy tags. Kalinka reads what is in the files, then fills the gaps from MusicBrainz, Wikidata, Deezer and the Cover Art Archive. With your own AcoustID key it can identify tracks by their sound. Artwork is extracted, cached, and generated when there is none. Your files are never changed. You can turn each lookup off.

Browse by folder or by album, artist and genre. Keep playlists and collections that mix tracks from different sources.

Ask for dreamy ambient guitar or jazz for a cozy evening. For your own library, Kalinka listens to each track once with a small AI model and remembers what it sounds like, so a search matches the sound, not only the tags. For Jamendo it uses a ready-made index of track descriptions. Results mix with ordinary text search.

It all runs on your own box: no cloud service, no key, no cost per search. It is opt-in, because the model needs about 1 GB of memory and the first pass over a large library takes a while.

Every renderer on your network appears as an output in the app. Switching outputs hands the music over mid-track rather than starting again. The browser player is an output too, which is how a laptop can play from a server that has no sound card.

The renderer sends samples to the sound card unchanged unless you turn on software volume. The app shows a 1:1 badge while the path is bit-perfect: a direct hw: device takes the samples as they are, while plughw: or a sound server may convert them. Tracks of the same format play gapless.

Kalinka is a UPnP renderer, so controllers such as BubbleUPnP can send it tracks, including internet radio and DSD. With the Qobuz plugin it is a Qobuz Connect output; with the Spotify plugin, a Spotify Connect output for Premium accounts. An experimental Roon plugin lets Roon play through the renderer. Whatever is playing shows in the Kalinka app with the same controls.

FLAC up to 192 kHz / 24-bit, MP3 and Ogg Vorbis, from files or HTTP streams.

DSD in DSF and DFF files, from DSD64 up to DSD512, sent to the DAC as native DSD or as DoP. DSD is never resampled, volume-adjusted or converted to PCM. DSD output is off by default: turn on DSD output in the renderer's settings and choose Automatic, Native or DoP. It needs a direct hw: output device and fixed volume, so set the listening level on your amplifier.

The exact rules, and what is not supported, are on the limits page.

A full-screen display of what plays: the cover, the track, the output and a large progress bar, laid out for a 1024×600 panel and scaled to other sizes. The queue, search and settings are not loaded at all. While music plays the controls fade after a few seconds; with nothing playing the screen shows a clock and dims. A touch wakes it and brings up the volume.

Use it on a tablet on a shelf (Settings › General › This device), in a browser (add ?kiosk to the address), or on the Raspberry Pi's own touch panel or HDMI screen, where it draws straight to the screen with no desktop and starts with the box.

The supervisor runs beside the core, independent of it. A box flashed with a Kalinka image that finds no network offers setup over Bluetooth: tap Set up a box in the app, pick the Wi-Fi network and enter its password. Over Bluetooth it exchanges only the Wi-Fi details and progress, nothing else.

The supervisor also serves a control page at http://<box>:8001 that shows whether Kalinka is running, the box's memory, CPU, disk and temperature, and the installed versions, with buttons to restart Kalinka, restart or power off the box, or reinstall. It works even when Kalinka itself has failed. The app offers the same controls.

The first time you connect, a wizard asks for a name, where your music is and which output to use. Afterwards everything stays editable from the app: a simple tier of common settings, and an expert tier with a search over the rest. Changes apply live.

The server checks for new releases once an hour. With auto-upgrade on it installs them during quiet hours while nothing plays; 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.

No account, no telemetry, nothing uploaded. The internet is used only for the metadata lookups above, the hourly update check, the one-time download of the search models, and the streaming sources you add. Each one is listed, with what it receives, in the privacy policy.