Уточнение 1.0.90: основной кадр может быть JPEG или PNG по render.output_format.
Во всех пунктах ниже JPEG означает основной кадр, кроме совместимого current.jpg.
Для PNG image/верхний files указывают current.png; compatibility_image описывает current.jpg.
MP4 получает непосредственно основной файл; source_image_sha256 равен image.sha256.
Предпросмотр не является источником MP4. Детали: docs/theme-extensions.md.

КОНТРАКТ ПУБЛИКАЦИИ 4К-ВИДЕООБОЕВ ДЛЯ СБОРЩИКА · 1.0

1. Результат

Для опубликованного динамического профиля desktop_3840x2160 сборщик
сохраняет полный JPEG 3840×2160 и дополнительно создаёт MP4 из этого же
готового JPEG. MP4 — дополнительный вариант представления кадра.
Обязательные image, preview, inputs, recipe и существующие временные поля
JSON сохраняют действующий смысл. JPEG не уменьшается из-за появления MP4.

Первое применение: orbital-port и sunken-teahouse. Кодирование универсально
для динамических тем с этим профилем; тематических исключений не требуется.
Профили Mac, ultrawide и desktop_1920x1080 этим расширением не изменяются.
Слои, астрономия и погодные правила повторно для видео не вычисляются.

2. Адреса

Общий публичный корень:
https://games.oopssre.ru/assets/arcade/views/

Описание текущего кадра остаётся по существующему адресу:
dynamic/<theme>/devices/desktop_3840x2160/current.json

Существующий JPEG:
dynamic/<theme>/devices/desktop_3840x2160/current.jpg

Новый производный файл:
dynamic/<theme>/devices/desktop_3840x2160/video/<sha256>.mp4

<sha256> — 64 строчных шестнадцатеричных символа SHA-256 самого MP4.
Файл по такому адресу неизменяем. Адрес публикуется в video.url.
Отдельного current-video.json и обязательного current.mp4 нет.
Верхний dynamic/<theme>/current.json сохраняет существующие files и states;
files по-прежнему описывает JPEG, states ведёт к JSON устройства.

3. Блок video в JSON устройства

Необязательное добавление к действующему current.json; schema:1 и
schema_version действующего состояния не меняются. Прежние поля сохраняются.
Если MP4 не готов, поле video отсутствует. Не публиковать частичный блок.

Обязательные поля при наличии video:

url                  string   Путь MP4 относительно общего публичного корня.
format               string   "mp4"
codec                string   "hevc"
profile              string   "main"
pixel_format         string   "yuv420p"
width                integer  3840
height               integer  2160
fps                  integer  24
duration_ms          integer  4000
audio                boolean  false
bytes                integer  Реальный размер готового MP4, > 0.
sha256               string   SHA-256 готового MP4, 64 строчных hex-символа.
source_image_sha256  string   В точности image.sha256 данного состояния.

Все эти поля относятся к одному файлу. Хеш в имени файла равен video.sha256.
Штатный id состояния пересчитывается с учётом добавленного блока video.
Схемы контракта, документация и копии схем в сборщике/публичных материалах
дополняются описанием необязательного video. Действующие проверки JPEG
остаются действующими. Переименование профиля или изменение theme.json
ради кодирования готового кадра не требуется.

4. Параметры кодирования

Контейнер MP4 с moov в начале (faststart).
HEVC / H.265 Main, 8 бит, yuv420p, квадратный пиксель (SAR 1:1), 16:9.
3840×2160 без уменьшения, 24 кадра/с, 96 кадров, ровно 4 секунды.
Один неподвижный полный кадр. Начало с ключевого кадра на отметке 0.
BT.709, limited range. Аудиодорожек нет. Музыка не включается в MP4.

Параметры проверенного образца:

ffmpeg -filter_threads 1 -filter_complex_threads 1 -threads 2 \
  -loop 1 -framerate 24 -i current.jpg -t 4 -an \
  -vf "scale=iw:ih:in_range=full:out_range=limited:in_color_matrix=bt601:out_color_matrix=bt709,format=yuv420p,setsar=1,setparams=color_primaries=bt709:color_trc=bt709:colorspace=bt709:range=limited" \
  -c:v libx265 -preset fast -crf 18 -profile:v main -tag:v hvc1 \
  -x265-params "pools=2:frame-threads=1:rc-lookahead=8:bframes=2:ref=2:keyint=96:min-keyint=96:scenecut=0:open-gop=0:log-level=error" \
  -colorspace bt709 -color_primaries bt709 -color_trc bt709 -color_range tv \
  -movflags +faststart staged.mp4

Параметры и версия энкодера фиксируются в ключе повторного использования
результата. Изменение параметров или версии энкодера требует новой такой
ревизии. На сервере с 4 ГБ памяти кодировать последовательно, одним
процессом ffmpeg за раз; не запускать параллельно кодирование двух 4К тем.

5. Повторное использование

Ключ результата: image.sha256 + ревизия параметров/энкодера.
Если ключ прежний и готовый MP4 цел — переиспользовать его без кодирования.
Новый час или новое время публикации сами по себе не требуют нового MP4.
При свежем состоянии с тем же JPEG его at/valid_until обновляются по
действующим правилам, а video.url, bytes и sha256 могут оставаться прежними.

6. Порядок публикации

1) Получить готовый JPEG существующим механизмом сборки.
2) Переиспользовать подходящий MP4 либо закодировать новый во временный файл.
3) При успешном завершении проверить параметры контейнера/дорожки,
   определить размер и SHA-256. Полное повторное декодирование на каждом
   серверном обновлении не требуется.
4) Атомарно разместить готовый MP4 под именем его SHA-256.
5) Только после доступности MP4 атомарно опубликовать JSON с блоком video
   и штатно завершить публикацию текущего кадра.

Нельзя публиковать ссылку на недописанный/отсутствующий MP4. Нельзя менять
содержимое ранее опубликованного адреса video/<sha256>.mp4.
Нельзя описывать прежний MP4 как видео нового JPEG с другим image.sha256.

При ошибке энкодера обычный JPEG публикуется штатно; у нового состояния
video отсутствует. Ошибка видео фиксируется в журнале. Публикация картинки
и остальных тем не должна зависеть от успеха дополнительного кодирования.

7. Хранение (уточнение пользователя от 2026-11-06)

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

8. Реализация сервера 1.0.88

Кодирование выполняется из готового current.jpg в приватную готовую сборку.
Публикация MP4 предшествует JSON устройства, включая publish_root.
Ошибки ffmpeg/ffprobe оставляют штатную публикацию JPEG и JSON без video.
При том же JPEG и ревизии энкодера целый MP4 используется повторно.
Профиль определяется по desktop_3840x2160 и размеру 3840×2160, а не имени темы.

В приведённом фильтре ffmpeg реализация дополнительно задаёт setsar=1 и
setparams=color_primaries=bt709:color_trc=bt709:colorspace=bt709:range=limited.
Этим явно задаются требуемые контрактом SAR 1:1 и цветовые характеристики
кадров перед передачей энкодеру. Остальные параметры кодирования сохраняются.
