В первой части я рассказал, как Kalinka выросла из эксперимента с Raspberry Pi, а затем подробно разобрал локальный поиск музыки по звучанию: CLAP, отдельную модель valence/arousal, бенчмарки и борьбу за память на Raspberry Pi 4.

Но за рамками статьи остался более фундаментальный вопрос: что такое Kalinka как продукт и почему она устроена именно так.

Музыкальных серверов уже достаточно. Есть MPD и moOde, Volumio и Roon, Navidrome и Jellyfin, Lyrion Music Server и Music Assistant. Поэтому фраза «я написал ещё один музыкальный сервер» почти неизбежно вызывает вопрос: зачем?

Ответ заключается не в одной уникальной функции. Kalinka занимает узкую область между несколькими классами систем:

• сервер сам воспроизводит музыку и физически подключён к аудиосистеме;

• локальная коллекция является основным источником, а не дополнением к стриминговому сервису;

• поверх файлов строится отдельная библиотека с поиском и обогащёнными метаданными;

• телефон, браузер и настольное приложение работают как пульты управления;

• источники музыки и интеграции с устройствами подключаются в виде плагинов;

• система работает на Linux-устройстве класса Raspberry Pi без обязательного аккаунта или подписки.

Главный принцип Kalinka можно сформулировать одной фразой:

Сервер является проигрывателем. Клиенты являются пультами управления.

В этой статье я сначала обозначу границы продукта, а затем покажу, как они превратились в архитектуру из Python-сервера, плагинов, тонких клиентов и нативного аудиографа.

Что такое Kalinka

Kalinka — открытая headless-система воспроизведения музыки для 64-битного Linux.

Референсная конфигурация — Raspberry Pi, подключённая к ЦАП или цифровому входу усилителя. Однако сервер также работает на обычном Linux-компьютере, NUC или другом устройстве с архитектурой arm64 или amd64.

Система состоит из двух основных частей.

KalinkaPlayer — сервер. Его базовые компоненты отвечают за очередь, воспроизведение, REST- и WebSocket API, конфигурацию, обнаружение устройств в локальной сети через Zeroconf и жизненный цикл плагинов. Большая часть сервера написана на Python, а чувствительный к задержкам аудиотракт — на C++.

Kalinka AI — клиент на Flutter для Android и Linux. Он автоматически обнаруживает серверы в локальной сети и позволяет просматривать библиотеку, искать музыку, управлять очередью, избранным, плейлистами и настройками. Вместе с сервером также можно установить веб-клиент, который подключается по известному адресу и не использует сетевое обнаружение.

Телефон при этом не получает FLAC-файл и не передаёт звук по Bluetooth. Браузер не декодирует трек. Клиенты отправляют команды и получают актуальное состояние, а звук всегда выводит Linux-машина, подключённая к аудиосистеме.

Основным и наиболее развитым источником остаётся локальная библиотека. Дополнительно существуют плагины для Jamendo, экспериментальная интеграция с Qobuz и управление устройствами Yamaha MusicCast.

Сервер распространяется под лицензией GPL-3.0-or-later, клиент — под Apache 2.0.

Исходный код:

• KalinkaPlayer;

• KalinkaAI.

Границы продукта

Одинаковое выражение «музыкальный сервер» используется для систем с совершенно разной моделью. Поэтому сначала важно определить, что Kalinka делает, а что сознательно оставляет другим проектам.

Один сервер — один аудиовыход

Kalinka ближе к Volumio, moOde или самостоятельно собранному MPD-плееру, чем к обычному медиасерверу.

Компьютер с Kalinka физически подключён к ЦАП, ресиверу или активной акустике и сам воспроизводит музыку. Сейчас один экземпляр сервера управляет одним аудиовыходом.

Это не whole-home-система и не синхронный multi-room.

Локальная коллекция является основным источником

Kalinka создаётся вокруг файлов, которыми владеет пользователь. Потоковые источники могут находиться в той же очереди, но не определяют модель продукта.

Сервер индексирует коллекцию, извлекает обложки, пытается заполнить пробелы в метаданных и позволяет искать музыку как по названиям, так и по звучанию. Исходные файлы при этом не изменяются.

Клиент управляет, но не воспроизводит

Navidrome, Jellyfin и Subsonic-совместимые системы хорошо решают задачу доступа к коллекции с разных устройств и через интернет. В их основном сценарии сервер отдаёт файл или транскодированный поток клиенту, а клиент воспроизводит его локально.

Kalinka решает обратную задачу: клиент выбирает музыку, но воспроизводит её сервер, находящийся рядом с аудиосистемой.

Удалённый многопользовательский доступ через интернет не является целью проекта.

Это не универсальный аудиокомбайн

Kalinka пока не поддерживает десятки форматов, AirPlay, Spotify Connect, Bluetooth-вход, сложный DSP, room correction и синхронизацию нескольких зон.

Текущая поддержка аудиоформатов ограничена FLAC и MP3. Архитектура допускает подключение новых декодеров, но сейчас развитие локальной библиотеки, поиска и клиентского интерфейса имеет более высокий приоритет, чем максимальная широта форматов.

Это не закрытый коммерческий appliance

Установка и настройка постепенно упрощаются, а значительную часть параметров уже можно менять из приложения. Но система всё ещё рассчитана на пользователей, которые не боятся Linux и понимают, что такое ALSA-устройство.

В обмен на отсутствие подписки и vendor lock-in пользователь получает контроль над системой, но не круглосуточную поддержку и не гарантированную совместимость с любым экзотическим оборудованием.

Где Kalinka находится среди готовых решений

Сравнение здесь нужно не для того, чтобы объявить один проект лучше другого. Разные системы оптимизированы под разные сценарии.

Volumio и moOde значительно зрелее как универсальные Raspberry Pi-проигрыватели. Они поддерживают больше форматов, протоколов воспроизведения и DSP-сценариев. Kalinka делает ставку на собственную модель локальной библиотеки, расширение через плагины и единый интерфейс для локальных и потоковых источников.

Roon, Plexamp и Audirvana предлагают более отполированный пользовательский опыт, богатые каталоги метаданных и зрелые механизмы рекомендаций. Однако это закрытые продукты, которые обычно зависят от аккаунта, облачных компонентов или подписки.

Navidrome и Jellyfin лучше подходят для удалённого доступа к библиотеке и воспроизведения на множестве клиентских устройств. В Kalinka аудиовыходом владеет сам сервер. Теоретически Navidrome или другой медиасервер можно подключить к Kalinka как ещё один источник, не дублируя его функции внутри проекта.

MPD и Mopidy являются отличными строительными блоками. На их основе можно собрать гибкую систему, самостоятельно выбрав клиент, библиотеку, интеграции и связующую логику. Kalinka находится уровнем выше: это связный продукт с собственной моделью каталога, единым состоянием воспроизведения, официальным клиентом и SDK для плагинов.

Music Assistant ближе всего к Kalinka по общей идее: он также объединяет разные источники музыки и устройства воспроизведения. Однако Music Assistant ориентирован прежде всего на маршрутизацию музыки на широкий набор существующих проигрывателей и multi-room-сценарии. Kalinka пока решает более узкую задачу: один Linux-узел одновременно владеет локальной библиотекой, очередью и непосредственным ALSA-аудиотрактом.

В результате целевого пользователя Kalinka можно описать так:

У него есть локальная музыкальная коллекция, один хороший ЦАП или цифровой вход, небольшая Linux-машина рядом с аудиосистемой и желание получить интерфейс современного музыкального сервиса, не передавая коллекцию облачной платформе и не превращая телефон в источник звука.

Ниша не обязательно огромна. Но именно её границы объясняют архитектуру проекта.

Архитектура верхнего уровня

В работающей системе можно выделить четыре слоя:

1. клиенты;

2. Python-ядро сервера;

3. SDK и плагины;

4. нативный аудиотракт.

Клиенты общаются с сервером через REST и WebSocket.

REST используется для запросов каталога и выполнения команд. WebSocket доставляет изменения очереди, позиции воспроизведения, состояния проигрывателя и подключённого оборудования в реальном времени.

Python-ядро владеет:

• API;

• очередью;

• текущим состоянием воспроизведения;

• агрегацией каталога и поиска;

• конфигурацией;

• обнаружением сервера в локальной сети;

• жизненным циклом плагинов.

Плагины предоставляют конкретные источники музыки и интеграции с устройствами.

Нативный аудиодвижок не знает, что такое Qobuz, Jamendo, MusicBrainz или локальная библиотека. Для него существуют только воспроизводимый ресурс, декодер и ALSA-выход.

Это разделение стало одним из самых важных архитектурных решений проекта. Каталог, поиск и интеграции можно развивать на Python, не смешивая их с аудиотрактом, который должен предсказуемо работать во время воспроизведения.

От нажатия Play до ALSA

Объект в очереди не содержит заранее сохранённый URL.

Вместо этого он хранит идентификатор сущности и источник. Когда трек становится текущим, сервер обращается к соответствующему модулю ввода — InputModule — и просит разрешить сущность в воспроизводимый ресурс.

Для локальной библиотеки результатом будет путь к файлу. Для потокового источника — HTTP URL. Такой URL может иметь ограниченный срок действия, поэтому его нужно получать непосредственно перед воспроизведением, а не в момент добавления трека в очередь.

После разрешения ресурс передаётся в C+±аудиограф:

1. FileInputNode или AudioGraphHttpStream читает данные;

2. декодер преобразует FLAC или MP3 в PCM;

3. узлы обмениваются данными через ограниченные буферы;

4. ALSA sink выводит PCM на выбранное устройство.

Ограниченные буферы обеспечивают обратное давление: быстрый источник не может бесконечно накапливать данные, если следующий узел временно не успевает их обрабатывать.

Движок может заранее подготовить следующий трек и подключить его к аудиографу ещё до завершения текущего. Если параметры обоих потоков совместимы с уже открытым аудиотрактом, ALSA-устройство не приходится останавливать и запускать заново.

За переключение отвечает специальный узел AudioStreamSwitcher. Он объединяет несколько подготовленных аудиопотоков в один непрерывный поток и переключается между ними точно на границе треков. В отличие от остальных узлов графа, AudioStreamSwitcher не использует собственный рабочий поток (thread), а выполняет только роль переключателя.

Благодаря этому нативный плеер может одновременно держать открытыми несколько дорожек и начинать воспроизведение следующей без дополнительной задержки. За добавление и удаление этих дорожек в графе отвечает код, управляющий очередью воспроизведения.

За добавление этих дорожек в аудиограф отвечает код, управляющий очередью воспроизведения.

Почему аудиодвижок написан на C++

Большая часть Kalinka не требует нативного языка. API, индексирование, конфигурацию и интеграции удобно реализовывать на Python.

Но требования к аудиотракту отличаются:

• прямой контроль над форматами ALSA;

• отсутствие скрытого ресемплинга внутри приложения;

• декодирование FLAC и MP3;

• чтение временных HTTP URL;

• ограниченные и предсказуемые буферы;

• предварительная подготовка следующего трека;

• воспроизведение без пауз между совместимыми композициями;

• низкое потребление ресурсов.

Движок выводит звук непосредственно через ALSA, без PulseAudio или PipeWire между приложением и устройством. Он пытается открыть аудиоустройство с параметрами исходного потока.

Термин bit-perfect здесь требует аккуратности.

При отключённой программной регулировке громкости Kalinka не выполняет ресемплинг и не изменяет PCM после декодирования. Однако конечный результат зависит от конфигурации ALSA, драйвера и оборудования. Например, dmix или внешний DSP могут изменить сигнал уже за пределами приложения.

Поэтому корректнее говорить о бит-в-бит пути там, где его допускают настройки ALSA и оборудование.

Если программная регулировка громкости включена, амплитуда PCM изменяется и бит-в-бит путь ожидаемо перестаёт существовать.

Почему не MPD

На раннем этапе MPD был очевидным кандидатом. Это зрелый, компактный и хорошо проверенный проигрыватель с поддержкой ALSA.

Но по мере развития Kalinka потребовалась собственная модель состояния:

• единая очередь для локальных и потоковых источников;

• временные URL, получаемые непосредственно перед воспроизведением;

• подробные уведомления клиентам;

• собственная модель артистов, альбомов, плейлистов и треков;

• поиск сразу по нескольким источникам;

• управляемый переход между локальными файлами и HTTP-потоками;

• конфигурационная схема, доступная клиентскому приложению;

• расширение через общий SDK для плагинов.

Всё это можно было бы построить вокруг MPD. Но Python-сервер всё равно владел бы почти всей бизнес-логикой, а MPD оставался бы вторым компонентом со своей очередью, состоянием и правилами переходов.

Состояния двух систем пришлось бы постоянно синхронизировать.

Собственный аудиограф сделал низкоуровневую часть сложнее, но упростил систему целиком: очередь существует в одном месте, сервер точно знает текущее состояние, а нативный движок остаётся узким исполнителем команд.

Плагины вместо интеграций в ядре

Первоначально Kalinka была тесно связана с Qobuz. Со временем это стало выглядеть архитектурным тупиком: API сервиса мог измениться, а локальная коллекция и другие источники требовали совершенно другой логики.

Теперь ядро не содержит знаний о конкретных музыкальных сервисах.

Источники реализуют интерфейс InputModule, который включает операции для:

• просмотра каталогов;

• получения артистов, альбомов, плейлистов и треков;

• поиска;

• разрешения трека в локальный путь или URL;

• работы с избранным;

• управления плейлистами, принадлежащими конкретному источнику.

Отдельный интерфейс предназначен для управления внешним оборудованием.

Например, плагин MusicCast может включать ресивер, менять громкость и получать его состояние. Благодаря этому кнопки громкости телефона управляют моей Hi-Fi-системой, хотя сам аудиосигнал идёт отдельно: из ALSA через ЦАП или S/PDIF.

Плагины являются обычными Python-пакетами и обнаруживаются при запуске. Их можно распространять в отдельных Debian-пакетах, поэтому новый источник не требует изменения ядра сервера.

Для разработки существует cookiecutter-шаблон, который создаёт структуру пакета, интерфейсы, конфигурационную схему и тестовый каркас.

Конфигурация тоже является частью контракта плагина. Модуль публикует схему параметров, а клиент динамически строит по ней экран настроек. Поэтому добавление нового параметра обычно не требует изменений в Flutter-приложении.

Локальная библиотека как производная модель

Файлы пользователя остаются источником аудио, но не всегда являются хорошим источником структуры каталога.

В реальных коллекциях встречаются:

• пустые или противоречивые теги;

• разные варианты написания имени одного артиста;

• отсутствующие номера дисков;

• собственные оцифровки винила;

• компиляции;

• редкие издания;

• директории с правильными именами и почти пустыми метаданными.

Kalinka не переписывает исходные файлы. Вместо этого плагин localfiles строит поверх них отдельную производную модель библиотеки.

Indexer отслеживает музыкальные директории и использует окно ожидания завершения загрузки: новый файл не обрабатывается, пока его размер продолжает меняться. Это защищает от индексирования частично скопированных FLAC-файлов.

Сначала индексатор читает встроенные теги, имя файла, путь и технические параметры аудио.

Затем он локально вычисляет Chromaprint-отпечаток. При наличии ключа отпечаток отправляется в AcoustID, чтобы попытаться определить запись.

Недостающие сведения дополняются через MusicBrainz, Wikidata и Deezer. Если внешние источники не помогают, используются файловые эвристики, чтобы библиотека оставалась пригодной для просмотра.

Отдельная логика агрегирует сборники с разными исполнителями, чтобы компиляции не распадались на несколько независимых альбомов.

Результат сохраняется в SQLite, а обложки кэшируются отдельно.

Такой подход не означает, что Kalinka всегда правильно определяет релиз. Fingerprint и внешние базы хорошо работают для распространённых записей, но собственные рипы, редкие издания и пользовательские сборники остаются сложными случаями.

Одна из текущих задач — перейти от независимого решения по каждому треку к согласованию на уровне альбома: учитывать общую директорию, последовательность треков, длительности, близость тегов и согласованность внешних результатов.

Однако даже текущая система обладает важным свойством: ошибка обогащения не повреждает исходные файлы. Производный индекс можно удалить и построить заново из настроек приложения.

Поиск по звучанию как часть общей системы

Локальный семантический поиск подробно разобран в первой статье, поэтому здесь я не буду повторять историю перехода от теггеров к CLAP, устройство valence/arousal-модели и результаты бенчмарков.

В общей архитектуре это опциональная ветка конвейера локальной библиотеки:

• фоновый процесс читает аудио;

• CLAP создаёт векторные представления;

• векторы квантизуются и сохраняются;

• текстовый запрос преобразуется в вектор;

• система ищет ближайшие треки;

• результат объединяется с лексическим поиском и сигналами из метаданных.

Тяжёлый аудиокодер требуется при индексировании, а текстовый кодер — при выполнении запросов. Это позволяет разделить жизненный цикл моделей и не держать их одновременно в памяти.

Важно, что семантический поиск не является отдельным экраном или специальным «AI-режимом». Пользователь вводит запрос в одно поле, а сервер сочетает несколько разных механизмов:

• точные и нечёткие лексические совпадения;

• поиск в каталогах подключённых источников;

• распознавание каталожных запросов;

• семантический поиск локальных треков по звучанию.

Например, запрос Most streamed on Qobuz направляется в соответствующий каталог Qobuz, а запрос вроде «что-нибудь меланхоличное на вечер» может использовать локальный поиск по звучанию.

Таким образом, AI-функции встроены в общую модель продукта, но не определяют всю архитектуру и не требуются для обычного воспроизведения.

Одна очередь воспроизведения для разных источников музыки

Плагинная модель позволяет локальным файлам и потоковым сервисам находиться в одной очереди.

Очередь хранит абстрактную ссылку на сущность. Когда приходит время воспроизведения, соответствующий плагин преобразует её в реальный ресурс.

Поэтому последовательность может выглядеть так:

1. локальный FLAC;

2. трек из Jamendo;

3. локальный MP3;

4. композиция из Qobuz.

Для аудиографа меняется только источник данных: локальный файл или HTTP-поток.

Одинаково названные объекты из разных источников не объединяются автоматически. У пользователя могут быть собственный виниловый рип, другое издание того же альбома и потоковая версия.

Источник объекта остаётся видимым в интерфейсе. Для локальных файлов отдельная атрибуция не показывается.

Поиск работает похожим образом: сервер параллельно отправляет запрос подходящим InputModule, получает результаты и агрегирует их, не теряя происхождение каждого объекта.

Доставка состояния клиентам

Когда сервер является проигрывателем, клиенту недостаточно получить успешный ответ на команду play.

Он должен быстро узнавать:

• какой трек действительно начал играть;

• текущую позицию;

• новую очередь;

• момент перехода на следующий трек;

• состояние паузы и остановки;

• громкость и состояние питания внешнего устройства;

• прогресс индексирования библиотеки.

Команды и обычные запросы идут через REST. Изменения состояния публикуются через WebSocket-каналы.

Сервер остаётся единственным источником истины, а телефон, ноутбук и браузер получают одну и ту же модель.

Это особенно важно при управлении с нескольких устройств: действие на одном клиенте должно сразу появиться на всех остальных.

Развёртывание и разработка

Production-сборка состоит из отдельных Debian-пакетов для arm64 и amd64:

• ядро сервера;

• SDK для плагинов;

• плагины, поддерживаемые самим проектом;

• дополнительные необязательные компоненты.

При первом запуске bootstrap-скрипт создаёт приватное Python-окружение (venv) и устанавливает в него пакеты ядра и доступных плагинов.

Тяжёлые необязательные зависимости можно устанавливать только при включении соответствующего модуля. После изменения состава окружения служба перезапускается через systemd.

Для пользователя установка сведена к скрипту с сайта или готовым .deb-пакетам. После запуска основная настройка продолжается в клиентском приложении.

Для разработки существует режим запуска без root. Сервер, конфигурация, база данных, логи и тестовая музыкальная директория размещаются в пользовательском каталоге. Это позволяет запускать полный стек из исходников без установки systemd-службы.

Изменения Python-кода применяются после перезапуска приложения. После изменения C+±кода нативный модуль необходимо собрать заново.

Ограничения как часть архитектуры

Некоторые отсутствующие функции являются вопросом времени. Другие потребуют изменения самой модели системы.

Дополнительные форматы

ALAC, Opus и WAV можно добавить в виде новых декодеров.

DSD сложнее: потребуется определить, должна ли система поддерживать native DSD, DoP или конвертацию в PCM и какие гарантии при этом можно давать пользователю.

Multi-room

Синхронное воспроизведение нельзя добавить как ещё одну кнопку.

Понадобятся:

• общие часы;

• компенсация задержек;

• дополнительная буферизация;

• управление группами;

• доставка аудио между узлами;

• восстановление синхронизации после сетевых сбоев.

Текущая модель «один сервер — один выход» намеренно проще.

При этом индексирование локальной коллекции в будущем можно отделить от узла воспроизведения. Например, модуль библиотеки мог бы работать на NAS в Docker-контейнере, а проигрыватель получать от него каталог и воспроизводимые ресурсы.

DSP

Сейчас задача аудиотракта — вывести декодированный PCM без дополнительных преобразований.

Эквалайзер или room correction логично реализовать в виде дополнительных узлов аудиографа. Но тогда интерфейс должен явно показывать, что бит-в-бит путь отключён.

На данный момент единственным опциональным преобразованием является программная регулировка громкости. Она включается пользователем явно.

Удалённый доступ и многопользовательский режим

Это не просто авторизация поверх существующего API.

Понадобятся:

• разграничение библиотек;

• права на управление очередью;

• безопасная публикация сервера в интернет;

• возможно, транскодирование;

• другая модель клиентских приложений.

Вероятно, Kalinka не должна превращаться в Navidrome. Подключить существующий медиасервер как источник может оказаться разумнее, чем дублировать его функции.

Что получилось

После нескольких итераций Kalinka стала не просто способом воспроизвести Qobuz через Raspberry Pi.

Сейчас это система с достаточно чёткими границами:

• звук воспроизводится на стороне сервера через ALSA;

• очередь и состояние существуют в одном месте;

• локальная коллекция является главным источником;

• библиотека строится отдельно и не изменяет оригинальные файлы;

• источники и устройства подключаются через плагины;

• разные источники используют общую очередь и общий поиск;

• Android-, Linux- и веб-клиенты остаются тонкими пультами;

• семантический поиск является необязательной локальной функцией;

• сервер может работать на небольшом Linux-устройстве.

Kalinka не заменяет Roon, Volumio, moOde, Navidrome, Music Assistant или MPD во всех сценариях. Каждый из этих проектов значительно зрелее в своей области.

Смысл Kalinka не в максимальном количестве функций, а в конкретном сочетании свойств: локальная библиотека, сервер как физический проигрыватель, открытая модульная архитектура и удобная работа с коллекцией без обязательного облака или подписки.

Архитектура начинается не с AI-модели и не с красивого клиента. Она начинается с ответа на три вопроса:

1. где живёт музыка;

2. кто владеет очередью;

3. какое устройство в конечном счёте выдаёт звук.

Что дальше

Ближайшие технические направления:

• согласование альбомов и обогащение метаданных на уровне коллекции;

• поддержка новых аудиоформатов;

• стабилизация API и SDK для плагинов;

• дальнейшая работа над объединённым поиском;

• тестирование с большим количеством ЦАП и ALSA-конфигураций;

• упрощение первого запуска и настройки;

• более точная документация архитектурных контрактов.

Kalinka открыта для тестировщиков и участников.

Полезны не только изменения в коде. Проекту нужны:

• коллекции со сложными или противоречивыми тегами;

• собственные рипы и редкие издания;

• необычные ЦАП и аудиоконфигурации;

• отчёты о несовместимостях;

• идеи для новых источников и устройств.

Изменения, подготовленные с помощью AI-инструментов, тоже принимаются, если автор понимает код, может объяснить решение и добавляет необходимые тесты.

• Сайт проекта: kalinkaplayer.com

• Сервер: github.com/madenvel/KalinkaPlayer

• Клиент: github.com/madenvel/KalinkaAI