Если вы смотрите фильмы с MacBook на проекторе через HDMI, вы знаете, как это бывает.

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

Поэтому я сделал свой видеоплеер для Mac, а пультом стал iPhone. Пауза, громкость, назад на 10 секунд, следующая серия, всё с дивана. Тяжёлые MKV играют прямо с диска в исходном качестве, без стриминга и перекодирования, со всеми звуковыми дорожками и субтитрами внутри.

А главное в новой версии: теперь ничего не нужно открывать руками. Добавляешь папки один раз, кнопкой «+ Add» слева внизу, и Kinrox сам их сканирует и дальше следит за ними. Докачался новый сезон, скинул альбом в «Загрузки», и он уже в медиатеке: сериалы разложены по сезонам с кнопкой «Continue S01E08», у фильмов постеры, жанры и рейтинги. С музыкой то же самое: не нужно помнить, в какой папке какой альбом, и собирать плейлисты. Вся локальная музыка лежит в одном месте, и её можно сразу включить и слушать как в Spotify, с очередью, shuffle и пультом на iPhone, только с собственного диска.

Kinrox Home: папки слева сканируются автоматически, сериалы и фильмы сами появляются в медиатеке

Kinrox Home: папки слева сканируются автоматически, сериалы и фильмы сами появляются в медиатеке


Это четвёртая часть истории про Kinrox (GitHub). В первой мы собрали видеоплеер на libmpv с пультом на iPhone и лёгкий Spotify-клиент на 196 МБ, во второй написали свой поиск похожей музыки, в третьей ловили 400 МиБ памяти, которых не видел leaks.

С тех пор вышел Mac-релиз 0.5.11, и он про то, ради чего всё начиналось, то есть про кино на стене:

  • появилась медиатека: добавляешь папки или внешний диск, Kinrox сканирует их автоматически, сам раскладывает фильмы, сериалы и музыку, подтягивает жанры, рейтинги и постеры;

  • плеер запоминает, где ты остановился, а досмотрел серию, следующая уже ждёт в «Продолжить просмотр»;

  • играет локальная музыка (FLAC, ALAC, MP3 и остальные) с того же пульта;

  • пульт Kinrox Remote наконец вышел в App Store, собирать его в Xcode больше не нужно.

Ниже о том, как это устроено внутри, и о граблях, на которые мы наступили по дороге.

Что было до медиатеки

Напомню, как работает пульт, без подробностей из первой части. Mac поднимает локальный сервер на Network.framework и анонсирует себя по Bonjour, iPhone находит его в той же Wi-Fi сети, при первом сопряжении на экране Мака появляется 6-значный PIN, дальше устройства общаются зашифрованными JSON-фреймами по локальному WebSocket. Ни аккаунта, ни внешнего сервера.

Плеер умел открыть файл или папку, строил плейлист с естественной сортировкой (2 перед 10), сам находил внешние дорожки и субтитры во вложенных папках. Но каждый вечер начинался одинаково: открыть Finder, найти папку сериала, вспомнить, какую серию смотрел вчера. Для плеера, которым управляешь с дивана, это лишний поход к ноутбуку.

Медиатека: обход, слежение и SQLite без ORM

Теперь стартовый экран называется Home (Home | Spotify): слева то, что лежит на Маке и внешних дисках, справа Spotify. Внутри Home четыре раздела: обзор, «Фильмы и сериалы» с карточками сериалов и лентой эпизодов, «Музыка на Mac» и недавнее. Открыть или перетащить отдельный файл по-прежнему можно сразу, без настройки папок.

Обход. Папку сканирует обычный FileManager.enumerator с опциями [.skipsHiddenFiles, .skipsPackageDescendants]. Симлинки и пакеты пропускаются, а если внутри отслеживаемой папки встречается точка монтирования другого тома (другой volumeUUIDString), сканер в неё не спускается. Изменившиеся файлы определяются по паре size + mtime: если она совпадает с тем, что уже лежит в базе, файл не трогаем. Новые записи пишутся пачками по 32, а теги аудио читаются в TaskGroup с параллельностью 4.

Слежение. Для изменений на диске используется FSEventStream с флагами kFSEventStreamCreateFlagWatchRoot | kFSEventStreamCreateFlagNoDefer и задержкой 0,25 с. Дополнительно приложение подписано на NSWorkspace didMount, willUnmount, didUnmount и didWake, потому что внешний диск может уехать вместе с ноутбуком в рюкзак. События склеиваются за 350 мс, после чего пересканируются все папки сразу. Звучит расточительно, но с проверкой size + mtime повторный проход по неизменившимся файлам почти ничего не стоит, а логика получается в разы проще, чем точечная обработка путей из FSEvents.

Хранилище. База живёт в ~/Library/Application Support/Kinrox/media-library.sqlite и работает через чистый C API SQLite3, без ORM. Доступ к ней изолирован в отдельном actor MediaLibraryDatabase, а сканирование идёт в Task.detached(priority: .utility), чтобы главный поток рисовал интерфейс. Настройки базы:

PRAGMA journal_mode=WAL;
PRAGMA mmap_size=0;
PRAGMA cache_size=-2000;
-- плюс max_page_count под потолок в 100 МБ

Таблиц четыре: watched_folders, media_files, enrichment_cache и playback_progress. После истории из третьей части мы следим за памятью отдельно, и медиатека её почти не добавляет (замеры ниже).

Парсер «грязных» имён файлов

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

Dune.Part.Two.2024.2160p.HDR.HEVC.mkv        → «Dune Part Two», 2024, 4K, HDR, HEVC
Dune.1080p.BluRay.x264.2021.mkv              → «Dune», 2021
The Expanse/Season_01/s01e07_Episode.Seven.avi → S1E7, «Episode Seven»
Series.1x03.mkv                              → S1E3
S02E01E02.mkv                                → S2, эпизоды [1, 2]
2001.A.Space.Odyssey.1968.mkv                → «2001 A Space Odyssey», 1968
IMG_4021.MOV                                 → личное видео

Как это работает:

  • Эпизоды ловит регулярка s(\d{1,2})[ ._-]*e(\d{1,3})((?:[ ._-]*e\d{1,3})*)|(\d{1,2})x(\d{1,3}). Она понимает и S01E07, и 1x03, и двойные эпизоды S02E01E02. Отдельно распознаются папки вида Season_01 и имена Episode 7.

  • Год ищется паттерном (19|20)\d{2}, причём берётся последнее совпадение, перед которым есть непустой префикс. Иначе «2001 Космическая одиссея» превращается в фильм без названия 2001 года.

  • Название обрезается на первом «релизном» токене: 2160p, 4k, 1080p, hevc, x265, x264, av1, bluray, webrip, web-dl, bdrip, remux и так далее. Всё, что правее, включая релиз-группу, отбрасывается.

  • Если после обрезки префикс пустой (файл называется просто s01e07.mkv), название берётся из имени папки сериала.

  • Файлы вида IMG_, DSC_, MVI_ и Screen Recording помечаются как личные видео. Их названия никуда в сеть не уходят: искать постер для IMG_4021 незачем, а отправлять такие имена на сторонний сервер и вовсе не стоит.

Фильм это или сериал, решает простое правило: если в имени нашлись сезон и номер эпизода, это сериал, иначе фильм. Музыку от видео отличает расширение.

Бейджи 4K и HDR на карточке тоже берутся из имени файла. Это подсказка о том, что лежит на диске, а не результат анализа потока.

Сериалы и «Продолжить просмотр»

Эпизоды группируются в сериал по нормализованному названию: регистр и диакритика сворачиваются, остаются только буквы и цифры. Так The.Expanse, the expanse и The_Expanse попадают в одну карточку. Внутри эпизоды сортируются по паре (season, number).

Следующая серия для «Продолжить просмотр» выбирается так:

  1. Берём эпизод с самым свежим прогрессом.

  2. Если он не досмотрен, предлагаем его же.

  3. Если досмотрен, предлагаем первый недосмотренный эпизод после него.

  4. Если прогресса нет вообще, предлагаем первый недосмотренный.

Прогресс хранится в таблице playback_progress(path, position, duration, completed, updated_at). Серия считается досмотренной, если плеер дошёл до конца файла или если просмотрено 92% длительности (для файлов длиннее минуты). Финальные титры досматривают немногие, и без такого порога сериал застревал бы на каждой серии. Пишем прогресс не чаще раза в 5 секунд и только после пятой секунды просмотра, чтобы случайно открытый файл не попадал в «Продолжить просмотр».

let completed = completed || isAtEnd || (duration >= 60 && position >= duration * 0.92)
guard completed || position >= 5 else { return }

Грабли: досмотренные серии не отмечались. Первая версия исправно писала прогресс, но досмотренные до конца серии так и оставались недосмотренными. Видеоплеер работает с keep-open=yes, чтобы после последнего кадра не закрываться, а показывать стоп-кадр. В таком режиме естественный конец файла приходит из libmpv как .endReached, а не как .ended, и позиция успевала сброситься раньше, чем мы записывали прогресс. Исправили проверкой isAtEnd и записью прогресса в момент завершения.

Внешние диски, которые уезжают в рюкзак

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

Том опознаётся по volumeUUIDString плюс проверке, что путь /Volumes/... действительно лежит внутри текущей точки монтирования. Если диск пропал, файлы помечаются как офлайн (markOffline), но из базы не удаляются. В интерфейсе они становятся полупрозрачными с подписью «Drive disconnected», а в «Продолжить просмотр» не попадают, чтобы пульт не предлагал серию, которую нельзя включить. Подключили диск обратно, пришло didMount, прошёл пересчёт, и is_offline снова 0.

Грабли: гонка FSEvents и отключения диска. На ревью нашёлся неприятный сценарий. При отключении диска FSEvents мог запустить сканирование пустой точки монтирования раньше, чем придёт didUnmount. Сканер видел пустую папку и решал, что все файлы удалены. Один выдернутый кабель, и каталог сериала исчезает вместе с прогрессом.

Решение: UUID и монтирование тома перепроверяются перед каждой пачкой, внутри транзакции и в её конце. Если том поменялся или пропал, сканирование превращается в markOffline, а не в удаление. Для съёмных томов без UUID удаление файлов из базы мы не делаем вообще: лучше устаревшая карточка, чем потерянный прогресс.

Жанры, рейтинги и постеры: что уходит в сеть

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

  • Cinemeta для фильмов и сериалов: поиск по названию, затем запрос /meta/... по найденному идентификатору, но только при точном совпадении нормализованного названия и года. Лучше без постера, чем с чужим постером.

  • TVMaze для сериалов, если Cinemeta ничего не нашёл: singlesearch/shows?q=<title>&embed=episodes.

  • MusicBrainz для альбомов: поиск release group по альбому и артисту, затем рейтинги и жанры.

  • Cover Art Archive для обложек альбомов.

Что уходит наружу: очищенное название и год, а для музыки название альбома и артист. По HTTPS, без cookies, без путей к файлам и идентификаторов пользователя. User-Agent прямо представляется как Kinrox/<version> ( https://kinrox.app ). Клиент видео выдерживает 520 мс между запросами, пускает только хосты из белого списка и ограничивает ответ 8 МиБ.

Запросы включены по умолчанию и выключаются одним переключателем «Load ratings, genres, and artwork», который есть и в настройках папок, и в общих настройках. Выключение сразу отменяет активные запросы. Чтобы опоздавший ответ не записался в базу после отмены, у обогащения есть поколение: при каждом выключении создаётся новый enrichmentGeneration = UUID(), текущая задача отменяется, а перед записью результата поколение перепроверяется.

func stopEnrichment() {
    enrichmentGeneration = UUID()
    enrichmentTask?.cancel()
}

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

Обложки кэшируются в ~/Library/Caches/Kinrox/MediaLibrary/Artwork: ключ это SHA-256 содержимого, картинка уменьшается через ImageIO до 480 px и сохраняется в JPEG с качеством 0,85. В памяти держится NSCache на 100 картинок и 12 МиБ. Если каталог ничего не нашёл, повторный запрос будет не раньше чем через 7 дней.

Грабли: Cover Art Archive не работал вообще. Ни одной обложки альбома. Оказалось, что наш клиент из соображений безопасности запрещал любые редиректы, а Cover Art Archive всегда отвечает 307 на хранилище *.archive.org. Разрешили строго ограниченную цепочку HTTPS-редиректов между хостами из белого списка.

Там же нашлись ещё две проблемы. Первая: у Spotify-части и у медиатеки были два отдельных лимитера запросов к MusicBrainz, и вместе они давали 2 запроса в секунду. MusicBrainz разрешает один и отвечает 503. Теперь лимитер один на всё приложение: актор выдерживает секунду между стартами запросов, а при 503 делает один повтор с учётом Retry-After, но не дольше 5 секунд. Вторая: кавычка или обратный слеш в имени артиста ломали поисковый запрос Lucene и давали HTTP 400. Добавили экранирование фразы.

Локальная музыка: тот же libmpv, но без видео

Для локальной музыки мы не стали подключать отдельный аудиостек и снова взяли libmpv, только без видео: vo=null, выключены vid, audio-display, обработка медиаклавиш внутри mpv, ytdl, пользовательские конфиги и скрипты. Громкость задаётся до инициализации движка, а volume-max=100, чтобы громкость Kinrox оставалась в пределах 0-100 и не трогала системную.

Как и Spotify-движок из первой части, локальный плеер «паркуется»: если пауза длится 20 секунд, движок выгружается, а позиция и громкость запоминаются. Нажал Play на пульте, и он поднимается за десятки миллисекунд.

Грабли: трек перескакивал через один. После loadfile ... replace mpv присылает END_FILE для предыдущего файла с причиной MPV_END_FILE_REASON_STOP, а код принимал это за естественный конец трека и включал следующий. В итоге одно нажатие Next перескакивало на два трека. Теперь автопереход срабатывает только на MPV_END_FILE_REASON_EOF, и только если событие относится к текущему playlist_entry. Заодно поймали вторую ошибку: после парковки движок пересоздавался с громкостью 100 вместо сохранённой. В тихой сцене на проекторе это особенно запоминается.

Теги и бейджи. FLAC, Ogg и Opus читает собственный небольшой парсер. Длительность Ogg берётся по последней granule position в хвосте файла, читаем не больше 64 КиБ. Остальные форматы идут через AVURLAsset с асинхронным load.

Бейдж lossless определяется не по расширению, а по mFormatID из CMAudioFormatDescription. Расширению верить нельзя: внутри .m4a бывает и AAC, и ALAC. kAudioFormatAppleLossless даёт ALAC, LinearPCM даёт PCM, FLAC тоже lossless. Частота дискретизации берётся из mSampleRate, разрядность из mBitsPerChannel, а для ALAC из флагов формата.

Поддерживаются FLAC, ALAC, MP3, M4A, AAC, WAV, AIFF, OGG и OPUS. Очередь, shuffle и repeat общие с режимом Spotify, медиаклавиши Мака работают через MPRemoteCommandCenter и MPNowPlayingInfoCenter.

Как пульт научился музыке, не меняя протокол

К этому релизу у пользователей уже стояли пульты прошлых версий, и ломать им протокол не хотелось. При этом пульт должен управлять локальной музыкой, а Мак не должен отправлять на телефон пути к файлам.

Решение получилось почти хулиганским. Пока играет локальная музыка, сервер отдаёт пульту обычное состояние видеоплеера, в котором вместо названия фильма стоит название трека:

PlayerState(
    title: track.title,
    position: ...,
    canNext: ...,
    source: .video,
    music: nil
)

Команды видео (togglePause, seek, next, previous, volume) на стороне Мака перенаправляются в LocalAudioViewModel. Пульт думает, что управляет фильмом, и всё работает, включая управление с экрана блокировки iPhone. Протокол RemoteProtocol остался первой версии, поэтому пульт 0.2.2 и более старые работают с Mac 0.5.11 без обновления, а путей к файлам телефон не получает.

Пульт в App Store

В первой части я жаловался, что ревью у Apple растянулось и пульт приходится собирать из исходников в Xcode. Теперь Kinrox Remote лежит в App Store и ставится как обычное приложение. По дороге было несколько поучительных моментов:

  • Первую отправку версии 0.2.2 App Store Connect не принял ещё до ревью: пустое поле «What's New». Тексты пришлось написать на всех 30 языках интерфейса.

  • Ревьюер не может проверить пульт без Мака, поэтому в приложении есть демо-режим, который работает без компьютера.

  • Слово Spotify в метаданных магазина не используется совсем: упоминание чужой торговой марки в описании легко упирается в правила App Store про метаданные и интеллектуальную собственность.

  • Ревью вернулось с запросом по Guideline 2.1 (Information Needed): Apple попросила видео с физическим iPhone, где видно первое сопряжение и весь сценарий работы с Маком, причём оба устройства должны быть в кадре.

  • Приватность в карточке приложения: «Data Not Collected». Это правда, пульт ничего не собирает и не отправляет никуда, кроме вашего Мака в локальной сети.

Замеры

Окружение: macOS 26.5.2, Apple Silicon, Release-сборка, окно 1440×940, громкость Kinrox 0.

  • Пустой Home: 70,33 МиБ footprint, 0,29% CPU.

  • Home с медиатекой на 241 файл (видео и FLAC): 83,00 МиБ footprint, 0,24% CPU. Медиатека добавила к процессу около 13 МиБ.

  • Холодное сканирование 240 файлов с тегами и обложками: 103,2 мс, самый длинный тик главного потока 10,56 мс. Интерфейс в это время не замирает.

  • Сканирование после добавления одного файла: 50,2 мс. Повторный проход без изменений почему-то занимает 157,3 мс, то есть дольше, чем с новым файлом. Причину пока не разобрали, если есть идеи, пишите.

  • Локальный FLAC: холодный старт 207,1 мс, Next 20,31 мс, возобновление после парковки 23,53 мс. Для сравнения, Next в Spotify-режиме из первой части занимает около двух секунд.

  • Воспроизведение музыки: 86,33 МиБ и 2,98% CPU, после парковки на паузе 0,23% CPU.

  • Переход с музыки на видео: 30,65 мс, с видео на Home 36,11 мс. Двойного звука нет: координатор «один звук за раз» из первой части работает и для локальной музыки.

Ограничения

  • Только Apple Silicon и macOS 14 или новее. Живые замеры и прогон сделаны на macOS 26.5.2, отдельного прогона на macOS 14 не было, проверялись только метаданные минимальной версии в бинарях.

  • Релиз-группы отдельно не распознаются. Если в имени нет релизных токенов (например, Movie-GROUP.mkv), суффикс останется в названии, и постер может не найтись.

  • Отключение внешнего диска покрыто тестами, но ручной проверки с выдёргиванием кабеля в этом релизе не было.

  • Бейджи 4K и HDR берутся из имени файла, анализа видеопотока за ними нет.

  • Spotify-режим, как и раньше, требует Premium, свой Client ID и отдельно скачанный Spotify Soloist. Видео, локальная музыка и пульт работают без всего этого.

Итог

Без аккаунта, без сервера, без аналитики. Файлы не покидают Мак, телефон общается с ним по локальному Wi-Fi. Наружу уходит только название фильма или альбома для поиска жанров и постеров, и это выключается одним переключателем. Весь код на GitHub.

Теперь я правда почти не встаю. Хе-хе.

  • Сайт и DMG для Mac (Apple Silicon, macOS 14+): https://kinrox.app/. Установленные версии 0.3.0 и новее обновляются через Kinrox → Check for Updates….

  • Пульт для iPhone: Kinrox Remote в App Store.

  • Исходники: https://github.com/awaik/Kinrox. Mac-плеер под GPL-3.0-only, код пульта открыт для личного некоммерческого использования и форков.

А чем вы смотрите фильмы с ноутбука на телевизоре или проекторе? И как у вас устроен парсер имён файлов, если вы тоже собирали свою медиатеку?