cc-1c-skills/docs/web-test-recording-guide.md

# Запись видеоинструкций

Навык `/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 (DmitryNeural / SvetlanaNeural) | Правильные ударения, естественная интонация, верные смысловые акценты |
| **Англоязычный / мультиязычный** | ElevenLabs | Менее «роботизированный» тембр, хорошая мультиязычная модель |
| **OpenAI-совместимый сервис** | OpenAI | Если уже есть API-ключ или свой TTS-сервер |

**Для русскоязычных видеоинструкций рекомендуется Edge TTS** — он бесплатный и даёт лучшее качество русской речи. Голоса DmitryNeural и SvetlanaNeural специально обучены для русского языка: правильно расставляют ударения, делают паузы в нужных местах и выделяют ключевые слова. ElevenLabs при озвучке русского текста звучит «через английский» — тембр приятнее, но акцент и просодика хуже.

### Edge TTS (бесплатный) — рекомендуется для русского

| Голос | Описание |
|-------|----------|
| `ru-RU-DmitryNeural` | Мужской, русский — спокойный, деловой |
| `ru-RU-SvetlanaNeural` | Женский, русский — чёткий, уверенный |

Полный список: `en-US-AriaNeural`, `en-US-GuyNeural`, `de-DE-ConradNeural` и другие. Edge TTS поддерживает десятки языков.

Конфигурация не нужна — Edge TTS используется по умолчанию. Для смены голоса:

```json
{
  "tts": {
    "voice": "ru-RU-SvetlanaNeural"
  }
}
```

### ElevenLabs (платный) — для английского и мультиязычного контента

Модель `eleven_multilingual_v2` поддерживает русский, но лучшие результаты — на английском. Тембр менее синтетический, чем у Edge TTS.

```json
{
  "tts": {
    "provider": "elevenlabs",
    "apiKey": "sk_...",
    "voice": "onwK4e9ZLuTAKqWW03F9"
  }
}
```

`voice` — ID голоса из библиотеки ElevenLabs (не имя). Список голосов — в личном кабинете. Требуется платный тариф (starter и выше).

Особенности: лимит на параллельные запросы (2–3 одновременно), система автоматически ограничивает размер пакета.

### OpenAI-compatible (платный)

```json
{
  "tts": {
    "provider": "openai",
    "apiKey": "sk-...",
    "voice": "alloy"
  }
}
```

Голоса: `alloy`, `echo`, `fable`, `onyx`, `nova`, `shimmer`.

Поле `apiUrl` позволяет подключить любой OpenAI-совместимый сервис (например, локальный TTS-прокси).

## Полный пример

Типовая структура озвученного сценария:

```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`