Kalinka — lightweight, modular streaming software for DIY and embedded audio projects

[MadEnvel]

I previously posted about Kalinka in the DIY Audio section in 2024

The project has matured considerably since then, so I thought it was worth reintroducing it from a different angle - and with more technical detail, since this forum is likely to ask for it.

Kalinka Player is an open-source, self-hosted music-streaming platform for lightweight Linux hardware such as the Raspberry Pi. It has been in development for around three years, with most of that time spent not merely adding features, but refining playback reliability, queue synchronisation, reconnection behaviour and error recovery.

I think it could now be useful as a software base for DIY streamers, network-enabled amplifiers and other embedded audio projects.

Playback path​

Kalinka does not use MPD. It has its own native playback engine, written in C++, using libFLAC, minimp3, ALSA and a custom audio graph for decoding, buffering, stream switching and output.

Because playback is not delegated to a separate daemon, Kalinka retains direct control over the playback state and signal path. It can also be integrated with hardware-specific functionality such as amplifier controls, displays and physical buttons without having to coordinate with a separate playback process.

When a direct ALSA hardware device is selected and software volume is disabled, Kalinka performs no intentional resampling, mixing or DSP. Audio is decoded and passed to ALSA at the source sample rate and bit depth.

An optional software volume control is available, mainly as a fallback for desktop systems. Hardware volume can instead be implemented through a device-control plugin, keeping it outside the audio path. Yamaha MusicCast is currently supported through this interface, and the same mechanism can be used for custom amplifier hardware.

During initial setup, Kalinka lists the available ALSA outputs and distinguishes direct hardware devices from outputs that may involve an intermediate software layer or resampling. The output can be changed later in the settings.

My main development system uses a Raspberry Pi 4 with a HiFiBerry Digi2 Pro, so I2S-attached audio HATs are part of the regularly tested configuration.

In my current Raspberry Pi 4 measurements, playback CPU use is below 2% for 44.1 kHz/16-bit FLAC and below 10% for 192 kHz/24-bit FLAC streamed over HTTP. I can provide a more detailed test methodology if that would be useful.

FLAC and MP3 are currently decoded natively. The decoder architecture is modular, so support for ALAC, WAV, Opus and additional formats can be added without changing the rest of the playback engine.

Current capabilities​

• Gapless playback through ALSA
• Native FLAC and MP3 decoding
• A modular audio graph with stream switching
• Reliable queue and playback-state synchronisation across clients
• Recovery from network, stream and decoding failures
• Android, Linux desktop and web clients with a shared interface
• Jamendo and local-library support. In addition to that, Qobuz is supported (unofficially).
• Local collections stored directly or on a NAS
• Plugins for adding music sources and controlling external devices
• Automatic local-network discovery through ZeroConf

Natural-language music search​

Kalinka also includes local natural-language search, but it is not simply an LLM placed in front of metadata.

For personal collections, Kalinka analyses the audio using a CLAP model. A small custom valence/arousal model — approximately 66,000 parameters — is applied on top to improve mood-related retrieval. Audio-derived results are combined with full-text metadata search and ranking, so searches can use both musical characteristics and conventional tags.

Example requests include:

• “Something melancholic for tonight”
• “Quiet acoustic music”
• “Energetic electronic tracks without vocals”
• “Popular track on Jamendo”

The analysis and search run locally. No GPU, gaming PC or separate inference server is required, just a Raspberry Pi 4.

Kalinka is developed primarily on a Raspberry Pi 4 with 4 GB of RAM. In my current configuration, local indexing takes approximately 8–10 seconds per track with high CPU usage but without interrupting playback. A playback-only installation should require fewer resources. The AI search is an optional feature for each input source and can be disabled to save resources.

Jamendo natural-language search works before a personal collection has been indexed. On first use, Kalinka downloads the required model automatically; no manual machine-learning setup is needed.

This model was developed specifically to retrieve and recommend tracks from the Jamendo catalogue using descriptions of mood, instrumentation, energy and other musical qualities. It provides an immediately usable demonstration of natural-language discovery without requiring the user to build a local index first.

Architecture and integration​

Modularity has been a central design goal.

A DIY builder could use the complete Kalinka interface as supplied, replace the client, add a hardware control panel, integrate buttons or a display, expose amplifier functions, or write plugins for a particular NAS, music service or audio device.

The server and plugin layer are written in Python, while the performance-sensitive playback engine is written in C++. The client is built in Flutter from a shared codebase targeting Android, Linux desktop and the web. iOS build is currently not provided due to lack of Apple hardware, but Flutter supports that.

The server and playback engine are licensed under GPLv3. The client and web interface are licensed under Apache 2.0, allowing them to be customised and embedded under a permissive licence. Anyone distributing the GPLv3 server or modified versions would, of course, still need to comply with the GPL. Kalinka artwork has a private license.

Feedback and collaboration​

I am particularly interested in feedback from people working on:

• Raspberry Pi and embedded streamers running on Linux
• DIY network amplifiers
• DAC and digital-transport projects
• Hardware control panels and displays
• Lightweight alternatives to larger music-server stacks

I would also be interested in collaborating with anyone who wants to integrate Kalinka into a hardware project.

Source code, installation instructions and screenshots:

GitHub links:
KalinkaPlayer
KalinkaAI App

 

[MadEnvel]

Kalinka 3.5.0 (server) / 0.5.0 (app) — redesigned Discover, rebuilt metadata enrichment, one-click server updates, browser UI, Windows client

Hi all — new release of Kalinka, the open-source music system for Raspberry Pi and other Linux boxes (lightweight C++/ALSA playback engine with a bit-perfect path, controlled by a Flutter app). Website with install instructions: https://kalinkaplayer.com

What's new in this release:

Redesigned Discover screen
The search/browse surface has been rebuilt around two clear modes:
- Catalog browsing — curated catalog cards from your sources (new releases, popular, genres, ...) that you browse directly, deterministically — no AI in the loop, just fast navigation with inline album/artist expansion.
- Smart search — a single search entry that understands natural language ("dreamy ambient guitar", "upbeat 80s synth pop") and searches across your local library and connected catalogs, with live AI suggestions and recent-search history. The semantic layer runs entirely on your own hardware (CLAP embeddings, ONNX) — nothing leaves your network.

Rebuilt metadata enrichment pipeline
The engine that identifies your local files against MusicBrainz/AcoustID/Deezer/Wikidata was redesigned from the ground up. It now works evidence-based: every source contributes claims, and a single resolution step picks the winner instead of sources overwriting each other. Albums are clustered folder-first and matched as whole releases — candidate MusicBrainz releases are ranked by how well their tracklist aligns with your files — rather than track-by-track guessing. Embedded-tag consensus across an album now counts as evidence too, and AcoustID fingerprinting is reserved for rescuing tracks nothing else can identify. Net effect: noticeably fewer wrong album/artist matches, and much better results on messy or untagged rips.

Server updates from the app
- The app shows a banner when a new server release is available; updating is one tap, with a confirmation dialog and progress — no SSH session needed.
- Optionally, enable automatic unattended updates: the server installs new releases by itself during quiet hours (3–6 AM local), and only while playback is stopped. Off by default.
- The release check is token-free (public feed, no GitHub account or API limits involved).

Web UI
The Kalinka app now also runs in the browser. The server serves it at its own address — open it and you get the full player UI as a remote control, same origin as the API, no extra port, no CORS setup, works on LANs without internet access. Audio stays on the server; the browser only controls it.

Experimental: Windows client
The app is now also available as a native Windows build (x64), with a regular installer — no admin rights needed — plus a portable zip. Handy if your listening PC or work machine is the most convenient remote.

Also in the box: local FLAC/MP3 playback up to 24/192 with a bit-perfect path where your ALSA config permits, and it runs comfortably on a Pi (512 MB RAM without AI search, 4 GB with it).

Under the hood: gapless playback
Gapless isn't new in this release, but it's the thing people always ask about, so worth stating precisely: the player holds a single ALSA device open across track boundaries instead of reopening it per file, and transitions are covered by an automated test that captures every frame handed to ALSA and asserts the result is sample-identical to the same music rendered as one continuous file — nothing inserted, dropped or duplicated at the boundary. I wrote up the architecture and the verification (hash comparison plus a null test) here:
Gapless playback with one ALSA device

Feedback very welcome — especially from anyone running it on unusual DACs or configs.