Формат сценария

В веб-приложении этот текст можно открыть в браузере: /docs/scenario-format (с префиксом приложения, например https://ваш-домен/ai_video/docs/scenario-format). Сырой Markdown: ?raw=1, скачать файл: ?download=1.

Где хранятся сценарий и медиа

В рабочем режиме приложение хранит данные в MySQL:

таблица scenarios — поля сценария (id, title, description, loop, default_theme, slides как JSON и т.д.);
таблица media_resources — файлы (картинки, аудио), привязанные к scenario_id и относительному имени файла (например assets/screen.png).

Папка videos/<video-id>/ на диске для работы плеера не обязательна: медиа отдаются по HTTP-пути /videos/<id>/<путь-из-json> (в HTML это относительный videos/<id>/... относительно <base href="...">, чтобы за прокси /ai_video/ не было 404 на корневой /videos/).

В самом scenario.json (и при загрузке ZIP) пути к картинкам и аудио указываются относительно id сценария — обычно через префикс assets/…, например assets/music.mp3. Внешние URL (http:// / https://) для ресурсов не преобразуются.

Обязательные поля (валидация)

На уровне сценария:

id, title — непустые строки;
slides — массив, минимум один слайд.

Каждый слайд:

id — строка;
durationSec — число > 0;
background — объект с полем type: одно из solid | gradient | image;
- для solid — value как цвет (hex rgb/hsl по правилам валидатора);
- для gradient — value непустая строка (CSS-градиент);
- для image — src непустая строка (путь к файлу или URL).

Опционально: description, loop (boolean; по умолчанию при отсутствии в рантайме часто подставляется true — см. withScenarioDefaults), defaultTheme, texts, images, audio, layout, transition.

Для блоков texts[]: value обязателен; x, y, width если заданы — числа 0…100 (проценты).

Для images[]: src обязателен; x, y, width, height если заданы — 0…100.

Минимальный пример `scenario.json`

{
  "id": "my-video",
  "title": "Название видео",
  "description": "Короткое описание",
  "loop": false,
  "defaultTheme": {
    "fontFamily": "Verdana, sans-serif",
    "textColor": "#FFFFFF",
    "accentColor": "#7CC6FF"
  },
  "slides": [
    {
      "id": "slide-1",
      "durationSec": 6,
      "layout": "free",
      "transition": "fade",
      "background": { "type": "solid", "value": "#0E1325" },
      "texts": [
        {
          "value": "Текст слайда",
          "x": 8,
          "y": 15,
          "width": 60,
          "fontFamily": "Verdana, sans-serif",
          "fontSize": 42,
          "weight": 700,
          "color": "#FFFFFF",
          "align": "left"
        }
      ],
      "images": [
        {
          "src": "assets/screen.svg",
          "alt": "Описание скриншота",
          "x": 45,
          "y": 12,
          "width": 50,
          "height": 70,
          "fit": "cover"
        }
      ],
      "audio": {
        "music": "assets/music.mp3",
        "voiceover": "assets/voice-1.mp3",
        "caption": "Подпись о текущем аудио"
      }
    }
  ]
}

Поля (кратко)

background.type: solid | gradient | image
background.value: цвет или строка градиента для solid / gradient
background.src: путь или URL для фона типа image
Координаты x / y / width / height: в процентах (0…100)
layout: логическое поле для рендера (free, split, screencast, …)
audio: music, voiceover, caption — пути как в assets/… или абсолютные URL
loop: повтор сценария после последнего слайда (true | false)

Как добавить или изменить видеоинструкцию

Веб-консоль (нужны регистрация и вход по API-ключу): откройте /register, затем /login. Создание: главная → «Создать новое видео» или переход на /edit/<uuid> (uuid можно сгенерировать новый). Редактировать можно только свои сценарии (после первого сохранения сценарий привязывается к вашему ключу).
ZIP-архив в консоли редактирования: в архиве должен быть scenario.json (в корне или в одной вложенной папке) и файлы по путям из JSON. При загрузке id в JSON заменяется на id страницы редактирования. Служебные файлы macOS (__MACOSX, .DS_Store, ._*, .AppleDouble) не импортируются.
API (с cookie-сессией после входа в браузере или с заголовком X-API-Key / Authorization: Bearer <ключ>):
- POST /api/scenarios — multipart: поле scenario (JSON-строка) и опционально файлы media;
- POST /api/scenarios/<id>/zip — поле archive (файл .zip).

Подробнее про API и ключи — в README.md.

Проверка структуры (`npm run check`)

Команда npm run check использует тот же валидатор, что и сервер, и загружает сценарии из MySQL (нужен настроенный .env с DB_*). Это не проверка локальной папки videos/ на диске.

Прямая ссылка на одну инструкцию

Формат пути (с префиксом приложения, если оно смонтировано как /ai_video):

/watch/<id>

Пример для id: my-video на сервере:

https://ваш-домен/ai_video/watch/my-video

Локально без префикса:

http://127.0.0.1:3030/watch/my-video

Встраивание в iframe на другой сайт

Сервер отдаёт страницу с Content-Security-Policy: frame-ancestors * для режима встраивания.

Рекомендуемый URL:

/embed/<id>

Альтернатива (тот же плеер, подходящий для iframe):

/watch/<id>?embed=1 (или ?iframe=1)

Пример:

<iframe
  src="https://ваш-домен/ai_video/embed/my-video"
  width="100%"
  height="640"
  title="Инструкция"
  allowfullscreen
  loading="lazy"
></iframe>

Экспорт в MP4

Для выгрузки ролика на стриминговые платформы используется CLI (нужен ffmpeg в PATH):

npm run export -- --id my-video --out dist/my-video.mp4

Детали — в README.md, раздел «Экспорт в MP4».