cc-1c-skills/.claude/skills/web-test/recording.md

Video Recording

Record browser automation sessions as MP4 video files. Uses CDP Page.startScreencast to capture JPEG frames and pipes them to ffmpeg for encoding.

Prerequisites

ffmpeg must be installed. Choose один из вариантов:

Вариант 1: в проект (рекомендуется)

Скачать essentials build с https://www.gyan.dev/ffmpeg/builds/, распаковать в tools/ffmpeg/ проекта:

tools/ffmpeg/
├── bin/
│   ├── ffmpeg.exe      ← этот файл ищет startRecording()
│   ├── ffplay.exe
│   └── ffprobe.exe
└── ...

Код автоматически найдёт tools/ffmpeg/bin/ffmpeg.exe — ничего больше настраивать не нужно.

Вариант 2: глобально (один раз на машину)

Скачать, распаковать в любой каталог (напр. C:\tools\ffmpeg), добавить bin/ в системный PATH. После этого ffmpeg доступен во всех проектах.

Вариант 3: через .v8-project.json (общий путь)

Чтобы не копировать ffmpeg в каждый проект, указать путь в конфиге:

{
  "ffmpegPath": "C:\\tools\\ffmpeg\\bin\\ffmpeg.exe"
}

Модель прочитает это поле и передаст в startRecording({ ffmpegPath }).

Порядок поиска ffmpeg

1. opts.ffmpegPath — явный путь (из .v8-project.json или параметра)
2. FFMPEG_PATH — переменная окружения
3. ffmpeg — в системном PATH
4. tools/ffmpeg/bin/ffmpeg.exe — относительно корня проекта

API

startRecording(outputPath, opts?)

Start recording the browser viewport to an MP4 file.

Parameter	Type	Default	Description
outputPath	string	required	Output .mp4 file path
opts.fps	number	25	Target framerate
opts.quality	number	80	JPEG quality (1-100)
opts.ffmpegPath	string	auto	Explicit path to ffmpeg binary

• Output directory is created automatically if it doesn't exist
• Throws if already recording or browser not connected
• Recording auto-stops when disconnect() is called

stopRecording() → { file, duration, size }

Stop recording and finalize the MP4 file.

Return field	Type	Description
file	string	Absolute path to the MP4 file
duration	number	Recording duration in seconds
size	number	File size in bytes

isRecording() → boolean

Check if recording is active.

showCaption(text, opts?)

Display a text overlay on the page (visible in recording). Calling again updates the text.

Parameter	Type	Default	Description
text	string	required	Caption text
opts.position	'top' | 'bottom'	'bottom'	Vertical position
opts.fontSize	number	24	Font size in px
opts.background	string	'rgba(0,0,0,0.7)'	Background color
opts.color	string	'#fff'	Text color

The overlay uses pointer-events: none — does not interfere with clicking.

hideCaption()

Remove the caption overlay.

showTitleSlide(text, opts?)

Display a full-screen title slide overlay (gradient background, centered text). Useful for intro/outro frames in video recordings. Calling again updates the content.

Parameter	Type	Default	Description
text	string	required	Title text (\n → line break)
opts.subtitle	string	''	Smaller text below the title
opts.background	string	dark gradient	CSS background
opts.color	string	'#fff'	Text color
opts.fontSize	number	36	Title font size in px

The overlay covers the entire viewport with z-index: 999999 and pointer-events: none.

hideTitleSlide()

Remove the title slide overlay.

setHighlight(on)

Enable or disable auto-highlight mode. When enabled, action functions (navigateSection, openCommand, clickElement, selectValue, fillFields) automatically highlight the target element for 500ms before performing the action.

Parameter	Type	Description
on	boolean	true to enable, false to disable

How it works: each action highlights the element → waits 500ms (viewer reads) → removes highlight → performs the action. This prevents the highlight overlay from interfering with modals, dropdowns, or focus changes caused by the action.

Search priority: form elements (buttons, links, fields, grid rows) are searched first. Sections and commands are used as fallback only if the element is not found in the current form. This avoids false matches (e.g., "ОК" matching section "Покупки" via substring).

isHighlightMode() → boolean

Check if auto-highlight mode is active.

highlight(text)

Manually highlight a UI element by name (fuzzy match). Places a semi-transparent blue overlay (rgba(0,100,255,0.25)) with a border on the element. The overlay tracks element position via requestAnimationFrame.

Parameter	Type	Description
text	string	Element name — button, link, field, section, or command

• Fuzzy match order: exact → startsWith → includes
• Searches form elements first, then sections/commands
• pointer-events: none — does not block clicks

unhighlight()

Remove the highlight overlay.

Example: Record a workflow with highlight, title slide, and captions

await startRecording('recordings/create-order.mp4');

// Title slide — 4 seconds
await showTitleSlide('Создание заказа клиента', { subtitle: 'Демонстрация' });
await wait(4);
await hideTitleSlide();
setHighlight(true); // enable auto-highlight for all actions

// Steps: caption → pause → action (highlight is automatic)
await showCaption('Шаг 1. Переходим в раздел «Продажи»');
await wait(1.5);
await navigateSection('Продажи');

await showCaption('Шаг 2. Открываем заказы клиентов');
await wait(1.5);
await openCommand('Заказы клиентов');

await showCaption('Шаг 3. Создаём новый заказ');
await wait(1.5);
await clickElement('Создать');
await wait(2); // wait for form to load

await showCaption('Шаг 4. Заполняем шапку');
await wait(1.5);
await fillFields({ 'Организация': 'Конфетпром', 'Контрагент': 'Альфа' });
await wait(1);

await hideCaption();
setHighlight(false);
const result = await stopRecording();
console.log(`Recorded ${result.duration}s, ${(result.size / 1024 / 1024).toFixed(1)} MB`);

Caption timing: show the caption before the action with a wait(1.5) pause — the viewer reads what will happen, then sees it happen. Add wait() after the action only when the next step needs the result to load (e.g., form opening).

Highlight timing: setHighlight(true) enables auto-mode — each action function highlights the target for 500ms, then removes the highlight before performing the action. No manual highlight()/unhighlight() calls needed. Enable after title slide, disable before stopRecording().

Troubleshooting

Problem	Solution
"ffmpeg not found"	Install ffmpeg and ensure it's discoverable (see Prerequisites)
Recording file is 0 bytes	Check that output path is writable. ffmpeg may have crashed
Video is choppy	Add wait() between steps. Reduce quality for faster capture
"Already recording"	Call stopRecording() before starting a new recording
Recording stops on disconnect	Expected — auto-stop prevents orphaned ffmpeg processes