Грабли (references/pitfalls.md)

Источник: ds-internal/presentations/component-video-skill/references/pitfalls.md — справочник скилла astra-component-video

Самопроверка не совпала

node tools/selftest.mjs собирает образцы и сравнивает с эталоном tests/expected.json.


«метки разошлись»	другой движок или Chrome	проверить, что `engine/` не правили; `npx --yes hyperframes@0.8.160 browser ensure --force`
«музыка совпала по громкости, биты другие»	другая версия numpy или scipy	не ошибка: звучит так же
«музыка разошлась»	синтезатор правили или Python без scipy	вернуть `tools/synth_music.py` из скилла, `pip install -r requirements.txt`
«кадр … отличается» на обложке	нет шрифта Inter — подставился системный	файлы `assets/fonts/*.woff2` на месте и не пустые
«кадр … отличается» в сцене	пропала картинка, правили CSS	сравнить снимок из `renders/<образец>.snapshots/` с `tests/reference/<образец>/` глазами
«сборка упала»	нет инструмента	вывод покажет какого: Node, Python, ffmpeg, npx

Снимки самопроверки делаются без GPU (build.mjs --soft), поэтому одинаковы на любой машине. Обычная сборка снимает и рендерит через GPU — там кадры могут отличаться от эталона на уровне шума (PSNR около 55 дБ), это нормально.

HyperFrames

HYPERFRAMES_SKIP_SKILLS=1 — при ручном вызове npx hyperframes всегда ставить эту переменную: без неё CLI переписывает глобальные скиллы пользователя. build.mjs ставит её сам.
Версия закреплена: hyperframes@0.8.160 (переменная HYPERFRAMES_VERSION). Другая версия может иначе считать кадр — эталон самопроверки записан на этой.
npx hyperframes check здесь врёт в аудитах вёрстки и контраста: фон собран режимами наложения, и проверка считает его белым. Проверять lint, снимками и рендером.
Рендер только --quality delivery: при обычном качестве по плавному градиенту фона идут полосы. build.mjs так и делает.
Таймлайн регистрируется колбэком: AstraVideo.build((tl) => …) в index.html. У таймлайна GSAP есть .then(), и await ждал бы конца анимации, то есть вечно. Разметку index.html не переписывать.
«data-duration=…, а таймлайн длится … с» в консоли — длина в index.html не совпала с роликом. build.mjs ставит её сам; ошибка значит, что index.html правили руками.
Вне HyperFrames (открыть index.html в браузере) таймлайн стоит на паузе. Посмотреть момент: в консоли __timelines.main.seek(8.6). Страницу открывать через локальный сервер (python -m http.server), не как файл: иначе браузер не загрузит шрифты.

Кадры

Серая подложка или фон в углах компонента — кадр взят PNG-выгрузкой или SVG не очищен. Крупно — только SVG через clean_figma_svg.py.
Подложка в углах ячеек матрицы — угол компонента не такой, как у Astra Fintech (--radius-m 24 со сглаживанием). Выгрузить ячейки SVG и поставить clip: false.
Размер SVG не совпал с данными (build.mjs пишет «! … — 343×88, а в данных …») — выгружен не тот узел или в данных не та высота. Высоту брать из get_metadata.
Стрелка → выглядит иначе — её нет в шрифте Inter; писать словами или тире.

Голос


«Стоп: озвучка упала … No module named 'torch'»	озвучку запустил обычный Python	`ASTRA_TTS_PYTHON` — на Python окружения голоса (`references/voice.md`)
Qwen3 работает минутами на фразу	torch не видит видеокарту: у RTX 50xx нужна сборка `cu128`	переставить torch с индекса `whl/cu128`
«flash-attn не установлен», предупреждение SoX	так и должно быть под Windows	ничего: работает `sdpa`
«в озвучке не кириллица» / «цифры»	Silero читает только кириллицу и слова	латиницу — по-русски («Фигма»), числа словами; или Qwen3
«ИИ» звучит как «и»	модель читает аббревиатуру как букву	в голосе — «нейросеть»
Слово пропало или слилось («однако манда» вместо «одна команда»)	модель проглатывает короткие слова и стыки	перестроить фразу; ударение у Silero — плюсом перед гласной
«файл … с, а в метках …» при сведении	фразы переозвучены после снятия меток	`build.mjs` пересобирает в верном порядке; вручную — снова `cues.mjs`
Голос «затягивает», паузы между действиями	старые паузы до 21.10.2026 (0,5 / 0,35 / 0,9 с)	переозвучить `voice.py say` — новые 0,3 / 0,2 / 0,5 с
Тембр плывёт от фразы к фразе	эталон голоса пересоздан или удалён `_reference.wav`	не трогать `assets/<ролик>/voice/_reference.*`; сменить голос — сменить `design` и переозвучить всё
`voice_check.py` падает на чтении файла (`metadata_errors`)	несовместимые версии `av` и faster-whisper	скрипт читает WAV сам; обновить скрипт из скилла
Числа и латиница в отчёте проверки	Whisper пишет «264» и «Skill»	строки `~` — не ошибка голоса

Windows

python3 может оказаться заглушкой Microsoft Store: печатает «Python» и молча выходит. build.mjs пробует python, python3, py -3 и берёт первый, где есть numpy и scipy; руками — python или py -3.
Вывод Python в cp1251: без -X utf8 кириллица в отчётах скриптов превращается в мусор. PYTHONIOENCODING при -I не действует.
PowerShell 5.1 портит кириллицу: Set-Content, Add-Content, > без -Encoding utf8 пишут в ANSI или UTF-16. Файлы данных и скрипты создавать средствами записи файлов агента, а не из оболочки. Heredoc в Git Bash тоже ненадёжен для больших файлов.
curl в PowerShell 5.1 — псевдоним Invoke-WebRequest: писать curl.exe.
В PowerShell 5.1 нет &&: команды через ; или по одной.
Пути: в данных ролика — только прямые слэши assets/…, иначе картинка не найдётся на сервере рендера.

Сеть

npx не скачивает hyperframes — проверить реестр (npm config get registry) и прокси. Корпоративный реестр-зеркало подходит, если в нём есть пакет.
Ошибки TLS вида UNABLE_TO_VERIFY_LEAF_SIGNATURE — корневой сертификат сети не известен Node: NODE_EXTRA_CA_CERTS=<путь к .pem>. Назвать ошибку пользователю, а не перебирать обходы.
Chrome для рендера HyperFrames качает сам при первом запуске (npx hyperframes browser ensure).