Если вы смотрите фильмы с MacBook на проекторе через HDMI, вы знаете, как это бывает.
Мак стоит у стены. В одной сцене шёпот, в следующей взрыв. И каждая пауза означает поход к ноутбуку в темноте в поисках трекпада.
Поэтому я сделал свой видеоплеер для Mac, а пультом стал iPhone. Пауза, громкость, назад на 10 секунд, следующая серия, всё с дивана. Тяжёлые MKV играют прямо с диска в исходном качестве, без стриминга и перекодирования, со всеми звуковыми дорожками и субтитрами внутри.
А главное в новой версии: теперь ничего не нужно открывать руками. Добавляешь папки один раз, кнопкой «+ Add» слева внизу, и Kinrox сам их сканирует и дальше следит за ними. Докачался новый сезон, скинул альбом в «Загрузки», и он уже в медиатеке: сериалы разложены по сезонам с кнопкой «Continue S01E08», у фильмов постеры, жанры и рейтинги. С музыкой то же самое: не нужно помнить, в какой папке какой альбом, и собирать плейлисты. Вся локальная музыка лежит в одном месте, и её можно сразу включить и слушать как в Spotify, с очередью, shuffle и пультом на iPhone, только с собственного диска.

Это четвёртая часть истории про 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).
Следующая серия для «Продолжить просмотр» выбирается так:
Берём эпизод с самым свежим прогрессом.
Если он не досмотрен, предлагаем его же.
Если досмотрен, предлагаем первый недосмотренный эпизод после него.
Если прогресса нет вообще, предлагаем первый недосмотренный.
Прогресс хранится в таблице 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.2App 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 мс,Next20,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, код пульта открыт для личного некоммерческого использования и форков.
А чем вы смотрите фильмы с ноутбука на телевизоре или проекторе? И как у вас устроен парсер имён файлов, если вы тоже собирали свою медиатеку?

Комментарии 0