HTTP API библиотеки

API библиотеки позволяет получить общий каталог, организовать фильмы в группы и запустить выбранный фильм на плеере. По умолчанию сервис работает на порту 8081. Все пути ниже относятся к адресу библиотеки, например http://192.168.1.10:8081.

Тела запросов передаются в JSON с заголовком Content-Type: application/json. Идентификаторы файлов берите из каталога, идентификаторы групп — из дерева, идентификаторы плееров — из списка плееров. Значения в сегментах URL нужно кодировать стандартным URL-кодированием.

Библиотека отдаёт данные и команды. Само видео загружается напрямую с хоста по адресу streamUrl; его способы доставки описаны в API хоста.

Каталог

Запрос	Ответ
GET /api/media	200: массив фильмов со всех доступных хостов
GET /api/media/{id}	200: сведения об одном фильме; 404, если доступный источник не найден

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

Запись содержит поля хоста, включая id, title, playable, streamType, durationSeconds, сведения о дорожках и дополнительные поля:

Поле	Значение
streamUrl	Абсолютный URL видео на хосте; может отсутствовать или быть пустым, если воспроизведение недоступно
host	Имя выбранного хоста
hostUrl	Базовый адрес хоста, например для получения субтитров

Возможные значения streamType: direct, hls, unsupported и pending — хост ещё читает сведения о файле. Метаданные библиотеки добавляются в запись на верхнем уровне и заменяют одноимённые поля, например title.

Одинаковые файлы на нескольких хостах дают одну запись. Файлы недоступного хоста не попадают в каталог, если нет доступной копии на другом хосте. Сохранённые сведения и связи с группами при этом не удаляются.

Дерево групп

GET /api/library/tree возвращает 200 и объект с массивами nodes и items. Пример структуры:

{
  "nodes": [
    {
      "id": "1fefb064-7d7b-46c0-ae73-2c4c08a6dc71",
      "parentId": null,
      "name": "Фильмы",
      "meta": {}
    }
  ],
  "items": [
    {
      "nodeId": "1fefb064-7d7b-46c0-ae73-2c4c08a6dc71",
      "mediaId": "идентификатор-из-каталога",
      "present": true
    }
  ]
}

parentId: null означает группу верхнего уровня. Группы имеют UUID. Один файл может входить в несколько групп. present: false означает, что файл сейчас не найден ни на одном доступном хосте; причиной может быть как удаление файла, так и выключенный хост.

Создание, переименование и перенос

Запрос	Назначение	Успешный ответ
POST /api/library/nodes	Создать группу	200, объект с id, parentId, name
PUT /api/library/nodes/{id}	Переименовать группу или сменить её родителя	204
DELETE /api/library/nodes/{id}	Удалить группу вместе с вложенными группами	204

Для POST и PUT тело имеет одинаковый формат:

{
  "parentId": null,
  "name": "Фильмы"
}

В PUT передавайте и имя, и нужного родителя: это не частичное обновление. parentId: null переносит группу на верхний уровень.

Пустое имя, несуществующий родитель или перенос группы в саму себя либо своего потомка дают 400. Для PUT и DELETE неизвестная группа даёт 404.

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

Файлы в группах

Запрос без тела	Назначение
PUT /api/library/nodes/{id}/items/{mediaId}	Добавить файл в группу
DELETE /api/library/nodes/{id}/items/{mediaId}	Убрать файл из группы

Успех — 204, неизвестная группа — 404. Повторное добавление не создаёт дубликат; удаление отсутствующей связи также возвращает 204. Существование файла не проверяется: связь можно сохранить и для временно недоступного источника.

Метаданные

Метаданные — произвольные пары «ключ → строковое значение», например название фильма, сезон или описание группы.

Запрос	Назначение
PUT /api/media/{id}/meta	Добавить или изменить метаданные файла
DELETE /api/media/{id}/meta	Удалить все метаданные файла
PUT /api/library/nodes/{id}/meta	Добавить или изменить метаданные группы
DELETE /api/library/nodes/{id}/meta	Удалить все метаданные группы

Пример тела PUT:

{
  "title": "Новое название",
  "season": "1",
  "description": null
}

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

Успех — 204. Для группы проверяется существование: неизвестный UUID даёт 404. Для файла такой проверки нет — метаданные можно задать заранее. Метаданные файлов возвращаются в каталоге и карточке, групп — в nodes[].meta.

Плееры

Список устройств

GET /api/players возвращает 200 и массив плееров, известных библиотеке через MQTT. Если брокер не настроен — 503.

Поле	Назначение
id	Идентификатор плеера
name	Отображаемое имя
online	Оценка доступности по свежести сообщений
lastSeenSecondsAgo	Сколько секунд прошло с последнего сообщения о состоянии
status	Состояние воспроизведения
url	Адрес текущего видео
positionSec	Позиция в секундах
durationSec	Длительность в секундах

online — приблизительная оценка с окном в 15 секунд, а не проверка соединения с устройством. Сохранённое сообщение MQTT при подключении библиотеки может временно создать впечатление, что выключенный плеер доступен.

Запуск фильма

POST /api/players/{id}/open принимает идентификатор фильма из каталога:

{
  "mediaId": "идентификатор-из-каталога"
}

Библиотека находит адрес видео и отправляет плееру MQTT-команду.

Код	Значение
202	Команда отправлена
400	Пустой mediaId или у фильма нет доступного адреса потока
404	Плеер неизвестен либо доступный источник фильма не найден
503	MQTT не настроен или нет подключения к брокеру

202 не подтверждает начало воспроизведения. Команда не сохраняется брокером для последующей доставки: выключенный плеер её не получит. Проверяйте последующее состояние через список плееров.

В HTTP API библиотеки сейчас есть команда запуска. Остальные доступные команды плеера описаны в MQTT API.

Обслуживание

Обновить структуру по правилам

POST /api/library/scan без тела запрашивает фоновое обслуживание: перенос сохранённых связей при изменении идентификаторов файлов и применение правил организации коллекции. Ответ — 202; окончания обработки запрос не ждёт, результат записывается в журнал библиотеки.

Пересоздать структуру

POST /api/library/scan?replace=true возвращает 202 и заказывает пересоздание в следующем фоновом проходе.

Сброс оформления коллекции

Этот режим удаляет группы, связи с файлами и метаданные файлов и групп, затем применяет правила заново. Ручные изменения будут потеряны. Видеофайлы на дисках не удаляются.

Удалить записи недоступных файлов

POST /api/library/gc без тела удаляет связи с группами, метаданные и сохранённые привязки к хостам для файлов, которых сейчас нет в доступном каталоге. Ответ 200 содержит число удалённых записей:

{
  "removedItems": 3,
  "removedMeta": 2,
  "removedHostLinks": 1
}

Проверьте доступность хостов

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

Пример последовательности запуска

1. Получите фильмы через GET /api/media.
2. Получите устройства через GET /api/players.
3. Передайте mediaId выбранному плееру через POST /api/players/{id}/open.
4. Проверьте состояние плеера повторным запросом списка устройств.

Адреса источников и MQTT задаются в конфигурации библиотеки.