Media Known Pitfalls

Плоский OUT

Проблема: из нескольких подпапок Source получается одна плоская папка результатов. Одинаковые имена файлов конфликтуют или перезаписывают друг друга.

Решение: обычные batch media-операции должны сохранять относительную структуру Source внутри OUT. Проверяй это после изменений в _output_path() и Scripts\Common\script_runner.py.

Непонятные Режимы Аудио

Проблема: названия вроде “Разделить файлы”, “Внутри видео”, “Только аудио” не объясняют результат.

Решение: использовать action labels:

Извлечь аудио;
Звук в видео;
Конвертировать аудио.

Подсказка должна объяснять, создаются ли отдельные аудиофайлы, новый видеофайл или обрабатываются standalone audio files.

Tooltips Обрезаются На Краях

Проблема: длинный tooltip центрируется относительно первой или последней кнопки и уезжает за край панели.

Решение: для крайних segmented-кнопок использовать классы edge alignment:

первая: left aligned;
последняя: right aligned;
центральные: centered.

Проверять computed style ::after: у первой left: 0, у последней right: 0.

Проблема: native NiceGUI q-tooltip может не монтироваться или вставленный script через add_body_html не выполняется как ожидается.

Решение: tooltips хранятся в data-audion-tooltip и показываются CSS-псевдоэлементом. Не полагаться на runtime JS для базовой подсказки.

Нажали Реальный Batch Вместо Проверки

Проблема: пользователь запускает длинную папку до проверки команды.

Решение: рабочая привычка:

Команда;
Тест: первый файл;
просмотр результата;
полный batch.

Overwrite Стирает Хороший Результат

Проблема: включено Перезаписывать, OUT уже содержит нужные файлы.

Решение: overwrite по умолчанию false. Включать только для disposable OUT или после явной очистки.

Hardware Backend Выбран На Машине Без Такого Железа

Проблема: CUDA/QSV/AMF профиль выбран, но драйвера или hardware нет.

Решение: запускать Hardware Capabilities. MISS - нормальный результат для отсутствующего backend. Выбирать CPU или другой backend.

Remux Используется Вместо Encode

Проблема: пользователь ждёт смену codec, FPS или audio params от remux.

Решение: remux меняет контейнер без перекодирования. Для codec/resolution/FPS/LUT/audio изменений нужны соответствующие encode/audio/FPS/LUT страницы.

FPS: Varispeed И Conform Путают

Проблема: результат имеет неожиданную длительность.

Решение: сначала тестировать один файл. Varispeed меняет скорость и duration. Conform имеет другой timing-смысл. Всегда сверять duration до batch.

LUT Выбран Не Тот

Проблема: pinned LUT или fallback active.cube не соответствует текущей задаче.

Решение: перед цветовой операцией выбрать LUT явно, проверить tooltip/путь, открыть папку LUT при сомнении, нажать Команда.

LUT Path Сломался Из-За Символов Windows

Проблема: путь содержит пробелы, диск, скобки, апострофы или запятые.

Решение: использовать общий helper escaping, не собирать filtergraph вручную строковой склейкой.

YouTube Скачал Плейлист

Проблема: ссылка на видео содержит playlist context.

Решение: включить Без плейлиста.

YouTube Требует Auth

Проблема: в браузере ссылка работает, yt-dlp не может скачать.

Решение: cookies-файл, Safe Safari, IPv4, retries, обновление yt-dlp. Cookies не коммитить и не класть в отчёты.

Старый GUI-Сервер На Порту

Проблема: порт занят старым процессом, новый код не виден.

Решение: проверить порт и PID:

Get-NetTCPConnection -LocalPort 8080 -State Listen

Для тестов использовать 8081 или остановить старый процесс.

Ручная Командная Строка Заменяет GUI

Проблема: пользователь запускает сложные media-команды вручную в нижнем терминале и теряет reports/progress/preflight.

Решение: ручная строка - для служебных команд. Media workflows должны идти через дерево операций, если уже есть готовый профиль.

Интерактивные CLI В GUI

Проблема: команда ждёт stdin, а GUI выглядит зависшим.

Решение: GUI-операции должны быть неинтерактивными. Интерактивные wizard-команды оставлять в CLI/TUI или проектировать отдельный GUI-flow.

Документация Устарела После Manifest

Проблема: добавили профиль или поле, но guide не обновился.

Решение: после изменения config\tool_manifest.yaml обновлять:

USER_GUIDE_RU.md;
USER_GUIDE_EN.md;
соответствующий файл в Docs\docs;
smoke checklist при необходимости.