Создание скриншотов и видео
Пакет @diplodoc/screencaster создаёт скриншоты и видео для документации. Он открывает страницу в Chromium, выполняет действия в интерфейсе и сохраняет результат.
Скриншотницей управляет агент с поддержкой MCP (Model Context Protocol). Вы описываете, что нужно показать, агент находит элементы страницы и выполняет сценарий. Для использования в собственном приложении у пакета есть TypeScript API.
Возможности
С помощью скриншотницы можно:
- Снять видимую область страницы, всю страницу или отдельный элемент.
- Выделить нужный элемент на скриншоте или в видео.
- Записать работу с интерфейсом и сократить паузы между действиями.
- Добавить озвучку и субтитры.
- Вырезать фрагмент записи или сохранить его как GIF.
- Обрезать скриншоты, собрать коллаж и подготовить разметку YFM для вставки изображений.
Исходная запись сохраняется вместе с обработанными файлами. Из неё можно подготовить ещё один вариант видео без повторного прохождения сценария.
Скриншоты сохраняются в PNG, обработанные ролики — в WebM. Для размещения на сайте ролик можно преобразовать в MP4 с помощью FFmpeg.
Подготовка
-
Установите Node.js версии 24 или выше и npm версии 11.5.1 или выше.
-
Установите пакет:
npm install @diplodoc/screencaster -
Подготовьте Chromium для версии Playwright, которую использует пакет. Для обработки видео также нужен FFmpeg с кодеками
libvpx-vp9иlibopus. Если FFmpeg находится внеPATH, укажите путь к нему в переменнойFFMPEG_PATH.Требования к окружению и установке браузера приведены в README пакета.
Настройка
Создайте файл run.config.json. В этом примере скриншотница открывает Playground, записывает видео и позволяет делать скриншоты с выделением элементов:
{
"version": 1,
"directory": "./runs",
"browser": {
"url": "https://diplodoc-platform.github.io/transform/",
"headless": true,
"locale": "ru-RU",
"colorScheme": "light",
"viewport": {
"width": 1920,
"height": 1080
},
"deviceScaleFactor": 1
},
"policy": {
"rules": [
{
"origin": "https://diplodoc-platform.github.io",
"pathPrefix": "/transform/",
"actions": ["read", "act"]
}
]
},
"outputs": {
"video": {
"name": "walkthrough",
"highlights": true
},
"screenshots": {
"highlight": true
}
}
}
directory— папка для результатов. Для каждой съёмки внутри неё создаётся отдельный каталог.browser.url— адрес страницы, с которой начинается сценарий.browser.headless— режим запуска браузера. Значениеtrueскрывает окно,falseоткрывает его на экране.browser.viewport— размер области страницы в CSS-пикселях. Этот размер также используется для записи видео.browser.deviceScaleFactor— плотность пикселей для скриншотов. Например, значение2даёт изображение двойного разрешения.policy— адреса страниц и действия, к которым у агента есть доступ.outputs.video— автоматическая обработка видео после завершения съёмки.highlightsиhighlight— выделение элементов в видео и на скриншотах.
Пути в конфигурации отсчитываются от каталога, в котором лежит run.config.json. Параметр locale задаёт язык браузера, но не меняет язык, сохранённый в настройках самого сервиса.
Для страницы с авторизацией можно передать подготовленную сессию через storageState или подключить свой модуль входа. Эти варианты описаны в настройках авторизации.
Подключение к агенту
Добавьте MCP-сервер в настройки агента. В клиентах с JSON-конфигурацией подключение выглядит так:
{
"mcpServers": {
"screencaster": {
"command": "npx",
"args": [
"--yes",
"@diplodoc/screencaster",
"--config",
"/path/to/run.config.json"
]
}
}
}
Замените /path/to/run.config.json на абсолютный путь к вашему файлу. Формат настроек зависит от клиента. Для клиентов с другим форматом используйте ту же команду и аргументы.
Сервер запускается командой:
npx @diplodoc/screencaster --config ./run.config.json
После подключения дайте агенту сценарий съёмки. Инструкцию можно передать текстом, файлом Markdown или ссылкой на источник Markdown.
Съёмка
В сценарии укажите адрес страницы, последовательность действий и результат, который должен быть виден после каждого шага. Например, «Переключись на второй таб и проверь, что появился его текст».
Если нужны скриншоты, укажите, какие состояния интерфейса нужно снять и что выделить. Видео записывается во время выполнения сценария.
Попросите агента завершить съёмку и вернуть пути к готовым файлам. Скриншотница обработает запись и сохранит результаты в папке runs. Список файлов, статусы шагов и ошибки доступны в manifest.json внутри каталога съёмки.
Перед публикацией проверьте, что на записи показан нужный результат, подписи читаются, а выделение попадает на нужные элементы.
Озвучка и субтитры
Для озвучки подключите сервис синтеза речи (TTS, text-to-speech). В пакет входит адаптер Яндекс SpeechKit.
-
Создайте рядом с
run.config.jsonфайл.envи сохраните в нём API-ключ:SPEECHKIT_API_KEY=ваш_ключ -
Добавьте в конфигурацию поля
envFileиtts:{ "envFile": ".env", "tts": { "provider": "speechkit", "options": { "apiKey": {"env": "SPEECHKIT_API_KEY"}, "voice": "jane", "speed": 1 } } } -
Дополните существующий блок
outputsнастройкойnarration, сохранив в нёмvideoиscreenshots:{ "narration": { "name": "narrated", "captions": true, "maxHoldSeconds": 5 } } -
На macOS и Linux ограничьте доступ к файлам:
chmod 600 run.config.json .env
В сценарии задайте короткую реплику для каждого шага. Агент использует эти реплики в поле actionText плана. После завершения записи скриншотница добавит озвучку к успешно выполненным шагам.
Настройка captions: true также создаёт файл субтитров WebVTT. Подключите этот файл к плееру отдельно. Субтитры не вшиваются в кадры видео.
Если реплика длиннее подходящего фрагмента, скриншотница может продлить показ кадра в пределах maxHoldSeconds. Для короткого видео лучше сократить реплику, чтобы зритель успел услышать её и увидеть действие.
Для русского языка в примере используется голос jane, для английского — john. Для каждого языка переведите текст сценария и реплики, измените голос и запишите отдельный ролик.
Обработка результатов
После съёмки агент может вырезать лишние действия, подготовить короткий фрагмент, GIF или обложку. Для этого используются инструменты MCP screencaster_edit, screencaster_clip и screencaster_preview.
Сокращение пауз опирается на записанные действия и изменения страницы. Длительность готового ролика зависит от самого сценария, а при озвучке — ещё и от длины реплик.
Для скриншотов доступна отдельная обработка: кадрирование, выделение области, сравнение двух состояний и сборка серии изображений. Описание этого режима есть в руководстве по иллюстрациям.
Пример
В статье о табах используется пример с двумя разделами, списком и жирным начертанием. На его основе можно записать работу с Playground.
Откройте пример в Playground. Чтобы записать такой ролик, передайте агенту ссылку на пример выше и следующую инструкцию:
Открой готовый пример с табами в Playground Diplodoc и запиши короткое видео. Проверь результат в превью, переключись на второй таб и вернись к первому. Добавь озвучку и субтитры. В готовом ролике сократи ожидания агента, сохрани переключения и время на чтение результата. Заверши съёмку и верни пути к готовым файлам.