From 37d2a5ee15f3bd015314b67848d366597fddcbc0 Mon Sep 17 00:00:00 2001 From: Nick Shirokov Date: Tue, 3 Mar 2026 10:58:27 +0300 Subject: [PATCH] docs(web-test): add video recording guide for users Co-Authored-By: Claude Opus 4.6 --- docs/web-test-guide.md | 1 + docs/web-test-recording-guide.md | 266 +++++++++++++++++++++++++++++++ 2 files changed, 267 insertions(+) create mode 100644 docs/web-test-recording-guide.md diff --git a/docs/web-test-guide.md b/docs/web-test-guide.md index 744c50ef..78afef25 100644 --- a/docs/web-test-guide.md +++ b/docs/web-test-guide.md @@ -296,6 +296,7 @@ await closeForm({ save: false }); ## Связанные навыки +- [Запись видеоинструкций](web-test-recording-guide.md) — запись видео, субтитры, подсветка, TTS-озвучка - [Веб-публикация](web-guide.md) — `/web-publish`, `/web-info`, `/web-stop`, `/web-unpublish` - [Базы данных](db-guide.md) — `/db-load-xml`, `/db-update`, `/db-run` - [Расширения](cfe-guide.md) — `/cfe-init`, `/cfe-borrow`, `/cfe-patch-method` diff --git a/docs/web-test-recording-guide.md b/docs/web-test-recording-guide.md new file mode 100644 index 00000000..ddc425ed --- /dev/null +++ b/docs/web-test-recording-guide.md @@ -0,0 +1,266 @@ +# Запись видеоинструкций + +Навык `/web-test` умеет записывать видеоинструкции по работе в 1С: автоматические действия в браузере записываются в MP4 с субтитрами, подсветкой элементов и голосовой озвучкой. Результат — готовое обучающее видео. + +``` +сценарий → запись экрана → субтитры → подсветка → озвучка голосом → MP4 +``` + +## Предусловия + +### ffmpeg (обязательно) + +Выберите один из вариантов: + +1. **В проект** (рекомендуется) — скачать essentials build с https://www.gyan.dev/ffmpeg/builds/, распаковать в `tools/ffmpeg/`. Код найдёт `tools/ffmpeg/bin/ffmpeg.exe` автоматически + +2. **Глобально** — скачать, распаковать в любой каталог, добавить `bin/` в системный PATH + +3. **Через конфиг** — указать путь в `.v8-project.json`: + ```json + { "ffmpegPath": "C:\\tools\\ffmpeg\\bin\\ffmpeg.exe" } + ``` + +### node-edge-tts (для озвучки) + +```bash +npm install --prefix tools/tts node-edge-tts +``` + +Бесплатный, без API-ключа. Если не установлен — запись видео работает, только озвучка недоступна. + +### Конфигурация голоса в `.v8-project.json` + +```json +{ + "ffmpegPath": "tools/ffmpeg/bin/ffmpeg.exe", + "tts": { + "provider": "edge", + "voice": "ru-RU-DmitryNeural" + } +} +``` + +## Быстрый старт + +Минимальный сценарий — запись 3 шагов с озвучкой: + +```js +// Начинаем запись +await startRecording('recordings/demo.mp4'); + +// Субтитры + действия +await showCaption('Переходим в раздел «Продажи»'); +await wait(1.5); +await navigateSection('Продажи'); + +await showCaption('Открываем заказы клиентов'); +await wait(1.5); +await openCommand('Заказы клиентов'); + +await showCaption('Создаём новый заказ'); +await wait(1.5); +await clickElement('Создать'); +await wait(2); + +// Завершаем запись +await hideCaption(); +const video = await stopRecording(); +console.log(`Записано: ${video.duration.toFixed(1)}s`); + +// Озвучка +const narrated = await addNarration(video.file, { + ffmpegPath: 'tools/ffmpeg/bin/ffmpeg.exe', + voice: 'ru-RU-DmitryNeural', +}); +console.log(`Озвучено: ${narrated.file}`); +``` + +Результат: `recordings/demo-narrated.mp4` — видео с голосовым сопровождением. + +## Сценарии использования + +### Запись без озвучки + +Простейший вариант — субтитры на экране, без голоса: + +``` +> Запиши видеоинструкцию: открой раздел Продажи, создай заказ клиента, +> заполни организацию и контрагента. Без озвучки +``` + +Claude запишет видео с субтитрами и подсветкой элементов. + +### Запись с озвучкой + +Полный pipeline — голос озвучивает каждый шаг: + +``` +> Запиши озвученную видеоинструкцию по созданию заказа клиента. +> Голос — Светлана +``` + +Claude запишет видео, затем наложит голосовую дорожку. Субтитры показываются на экране, параллельно звучит голос. + +### Переозвучка другим голосом + +Видео уже записано — хотите другой голос? Не нужно перезаписывать: + +``` +> Переозвучь recordings/demo.mp4 голосом Светланы +``` + +Claude вызовет `addNarration` с другим голосом. Тексты берутся из файла `.captions.json`, который сохраняется рядом с видео при записи. + +### Редактирование субтитров + +После записи рядом с видео появляется файл `video.captions.json`: + +```json +{ + "videoTimestamps": true, + "captions": [ + { "text": "Переходим в раздел «Продажи»", "speech": "Переходим в раздел Продажи", "time": 3160 }, + { "text": "Открываем заказы клиентов", "speech": "Открываем заказы клиентов", "time": 7040 } + ] +} +``` + +Можно отредактировать `speech` (текст озвучки) и переозвучить: + +``` +> Отредактируй субтитры в recordings/demo.captions.json — замени "Продажи" на +> "раздел Продажи", потом переозвучь +``` + +## Приёмы + +### Титульный слайд + +Полноэкранная заставка в начале видео: + +```js +await startRecording('recordings/demo.mp4'); +await showTitleSlide('Создание заказа клиента', { + subtitle: '1С:Бухгалтерия в примерах' +}); +await wait(4); +await hideTitleSlide(); +// ... далее контент +``` + +### Подсветка элементов + +Полупрозрачная рамка на элементе, который сейчас используется. Два режима: + +- **Авторежим** — `setHighlight(true)` перед началом действий. Каждая функция (`navigateSection`, `clickElement`, `fillFields` и т.д.) автоматически подсвечивает элемент перед действием +- **Ручная** — `highlight('Провести')` для произвольной подсветки конкретного элемента + +```js +setHighlight(true); // включить авто +// ... все действия подсвечиваются автоматически +setHighlight(false); // выключить перед stopRecording +``` + +### Паузы и ритм + +Ритм «субтитр → пауза → действие» даёт зрителю время прочитать, что произойдёт: + +```js +await showCaption('Проводим документ'); // зритель читает +await wait(1.5); // пауза 1.5 сек +await clickElement('Провести'); // действие +``` + +Пауза после действия нужна только когда загружается следующая форма: + +```js +await clickElement('Создать'); +await wait(2); // форма загружается +``` + +### Разделение текста и озвучки + +Параметр `speech` в `showCaption` позволяет показывать одно, а озвучивать другое: + +```js +// Субтитр технический, озвучка человечная +await showCaption('Дт 60.02 — Кт 51', { + speech: 'Дебет шестьдесят ноль два — кредит пятьдесят один' +}); + +// Показать субтитр, но НЕ озвучивать +await showCaption('Технические детали', { speech: false }); +``` + +Это полезно для: +- **Бухгалтерских проводок** — на экране формула, голосом — словами +- **Технических данных** — показать, но не зачитывать +- **Информационных плашек** — немой субтитр на несколько секунд + +## Доступные голоса + +### Edge TTS (бесплатный) + +| Голос | Описание | +|-------|----------| +| `ru-RU-DmitryNeural` | Мужской, русский | +| `ru-RU-SvetlanaNeural` | Женский, русский | + +Полный список: `en-US-AriaNeural`, `en-US-GuyNeural`, `de-DE-ConradNeural` и другие. Edge TTS поддерживает десятки языков. + +### OpenAI-compatible (платный) + +Конфигурация в `.v8-project.json`: + +```json +{ + "tts": { + "provider": "openai", + "apiKey": "sk-...", + "voice": "alloy" + } +} +``` + +Голоса: `alloy`, `echo`, `fable`, `onyx`, `nova`, `shimmer`. + +## Полный пример + +Типовая структура озвученного сценария: + +```js +await startRecording('output.mp4'); +await showTitleSlide('Заголовок', { subtitle: 'Подзаголовок' }); +await wait(4); +await hideTitleSlide(); +setHighlight(true); + +// ... шаги с showCaption + действия ... + +await hideCaption(); +setHighlight(false); +const video = await stopRecording(); + +const narrated = await addNarration(video.file, { + ffmpegPath: 'tools/ffmpeg/bin/ffmpeg.exe', + voice: 'ru-RU-SvetlanaNeural', +}); +``` + +## Типичные проблемы + +| Проблема | Решение | +|----------|---------| +| `ffmpeg not found` | Установите ffmpeg (см. Предусловия) | +| Файл записи 0 байт | Проверьте права на запись в выходной каталог | +| Видео дёргается | Добавьте `wait()` между шагами | +| `Already recording` | Вызовите `stopRecording()` перед новой записью | +| `No captions available` | Используйте `showCaption()` во время записи | +| TTS timeout | Проверьте интернет-соединение (Edge TTS требует сеть) | +| Озвучка обрезается | Увеличьте паузы `wait()` между субтитрами | + +## Связанные навыки + +- [Тестирование через веб-клиент](web-test-guide.md) — навигация, формы, таблицы, отчёты +- [Веб-публикация](web-guide.md) — `/web-publish`, `/web-info`, `/web-stop`