# Audion Media Tools — руководство

[English](USER_GUIDE_EN.md) · [О программе](README_RU.md) · [Замеры](MEASUREMENTS_RU.md) · [Решения](DECISIONS_RU.md)

**Содержание**

- [Порядок работы](#порядок-работы)
- [Рабочая область](#рабочая-область)
- [Обрезка: плеер и клавиши](#обрезка-плеер-и-клавиши)
- [Страницы](#страницы)
- [Железо](#железо)
- [Терминал и отчёты](#терминал-и-отчёты)
- [Правила безопасной работы](#правила-безопасной-работы)
- [Проверка после изменений](#проверка-после-изменений)
- [Техническая часть](#техническая-часть)

Как работать: рабочая область, порядок запуска операции, обрезка с плеером,
страницы, отчёты.

## Порядок работы

1. Выбрать источник и папку результата.
2. Открыть нужную страницу.
3. Выбрать профиль.
4. Поменять только то, что нужно.
5. Нажать `Команда` — увидеть, что именно уйдёт в FFmpeg.
6. Прогнать первый файл.
7. Запустить пачку.

Профиль задаёт готовую основу, поля ниже переопределяют её точечно. Галочки не
включают скрытых действий, если профиль их не задал.

**Шаги 5 и 6 не пропускают на новой операции.** Ошибка в параметрах на одном
файле стоит секунд, на папке — часа.

## Рабочая область

Верхняя строка задаёт два пути для всех страниц:

| кнопка | что делает |
|---|---|
| Источник | папка с исходниками |
| Добавить файл… | один файл как источник |
| Назначение | папка результата |
| Сбросить | вернуть проектные `Source\` и `Transcoded\`, файлов не трогая |
| Удалить | очистить текущие источник и назначение после подтверждения |
| Список | вывести в терминал имена файлов текущего источника |

Поля путей помнят историю; закреплённый путь поднимается наверх. Очистка требует
подтверждения.

Источник обходится рекурсивно, и результат повторяет его структуру:

```
Назначение\<операция>\<профиль>\<как в источнике>\<имя файла>.<ext>
```

`Source\Day1\clip.mov` и `Source\Day2\clip.mov` не сваливаются в одну плоскую
папку и не спорят за имя.

## Обрезка: плеер и клавиши

Точки реза находят в плеере mpv — он открывается кнопкой из раздела — и
переносят в поля кнопкой `Взять A и B`. Клавиши работают **в окне плеера**, не в
панели программы.

Дюжина клавиш, которыми делается вся работа:

| клавиша | что делает |
|---|---|
| `Пробел` | играть или пауза |
| `,` `.` | шаг ровно в один кадр назад и вперёд |
| `←` `→` | перемотка на 5 секунд |
| `Shift+←` `Shift+→` | **точно** на секунду назад и вперёд |
| `Shift+↓` `Shift+↑` | **точно** на пять секунд |
| `↓` `↑` | на минуту назад и вперёд |
| `Home` | в начало файла |
| `l` | поставить точку **A**; второе нажатие — точку **B**; кусок между ними играет по кругу |
| `Ctrl+l` | снять точки A и B |
| `b` | играть **назад** |
| `n` | вернуться к воспроизведению вперёд |
| `[` `]` | медленнее или быстрее на 10 % — на скорости 0,25 слышно каждый слог |
| `Backspace` | вернуть обычную скорость |
| `s` | снимок кадра рядом с исходным файлом |

`l` — это и есть рез: поставили A и B, послушали петлю, и если точка неверна —
подвинули её `,` и `.`, нажали `l` снова.

**Разница между `←` и `Shift+←` важна.** Обычная перемотка прыгает на 5 секунд и
показывает ближайший кадр; `Shift` — точная, ровно на секунду, и попадает в кадр.
Для поиска точки реза нужна вторая.

`b` и `n` добавлены этой сборкой: в обычном mpv на `b` висит подавление полос,
здесь оно переопределено.

Полный список — все 197 привязок с командами плеера — в
`tools\MPV_HOTKEYS_RU.md`. Список снят с самого плеера ответом `input-bindings`,
а не переписан из интернета.

Подробности обрезки — рабочий цикл, три действия, точность, отказы — в
`tools\TRIM_RU.md`; что с чем совместимо при резе — в `tools\TRIM_MATRIX_RU.md`.

## Страницы

| страница | о чём | подробно |
|---|---|---|
| Скачивание | ссылка или список, профили формата, разрешение, субтитры, потоки | `tools\YOUTUBE_DOWNLOAD_RU.md` |
| Аудиопотоки | извлечение, ресемплинг, громкость, упаковка; звук в видео без перекодирования картинки | `tools\AUDIO_WORKFLOWS_RU.md` |
| Обрезка | покадровая и по ключевым кадрам, метки помнятся по файлу | `tools\TRIM_RU.md` |
| Перепаковка, частота, цвет | смена контейнера, частота кадров, таблицы цвета, HDR в SDR | `tools\REMUX_FPS_LUT_RU.md` |
| Архив, монтаж, хранение, доставка | FFV1 и x264 без потерь, ProRes и DNxHR, x264/x265/AV1, профили заливки | `tools\ENCODING_PIPELINES_RU.md` |
| Диагностика | что за железо, что оно умеет, проверка профилей | `tools\HARDWARE_DIAGNOSTICS_RU.md` |

## Железо

Программа умеет выбирать между аппаратными путями NVIDIA, Intel и AMD,
отдельными кодировщиком и декодировщиком AV1 и обычным процессором.

**Перед первым запуском на новой машине — «Возможности железа».** Результат
кладётся в кэш, и профили с аппаратным кодированием сверяются с ним. Отсутствие
пути — нормальный ответ, а не поломка: значит нет драйвера или самого железа.

## Терминал и отчёты

Справа — состояние операции, ход выполнения, журнал, кнопка `Команда` для сухого
прогона, выходы к журналам, отчётам и настройкам, разворот терминала и строка для
ручной команды с историей.

Каждая операция пишет `batch_report.md` и `.json`. Звук добавляет
`audio_report.md` и `.json`: исходный поток, параметры входа, режим обработки,
громкость, путь результата.

Подробно про рабочую область, кэш путей, терминал и отчёты —
`tools\WORKSPACE_REPORTS_TERMINAL_RU.md`.

## Правила безопасной работы

* Новая операция — сначала `Команда`, потом запуск.
* Большая папка — сначала первый файл.
* Перезапись не включают, не будучи уверенным в папке результата.
* Аппаратный путь — сначала проверить возможности железа.
* Цветовая таблица — сначала посмотреть, какой `.cube` выбран.
* Пачка скачивания — сначала проверить список ссылок.
* Очистка — внимательно посмотреть на выбранные папки.
* Две операции одновременно в одном окне не запускают.

## Проверка после изменений

```cmd
runtime\python.exe -m py_compile system_core\ui_nicegui\app.py system_core\services\media_service.py Scripts\Common\script_runner.py
runtime\python.exe system_core\ui_nicegui\app.py --smoke
```

Что именно прогоняется перед выпуском — [список проверок](SMOKE_TEST_RU.md).

---

## Техническая часть

### Запуск

```bat
launcher_gui.cmd
```

Окружение не собрано:

```bat
builder_main.cmd
```

Окно открывается на `http://127.0.0.1:8080/`.

### Подсказки

Появляются через 1500 мс, скрываются за 100 мс, фон `RGB(23, 33, 43)`.
Непонятно, что делает поле, — задержите курсор на полторы секунды.

Подсказки есть у режимов звука, выбора потоков, громкости, ресемплера,
аппаратного кодирования, пар перепаковки, цветовых таблиц и операций с побочными
действиями. Расширения файлов и очевидные кнопки вроде «Назад» и «Запустить»
подсказками не дублируются.

У крайних кнопок в группе подсказка выравнивается по краю, чтобы длинный текст не
обрезался.

### Названия в рабочей области

Единый словарь для всех проектов Audion. По-английски: **Source**, **Add file…**,
**Target**, **Reset**, **Delete**, **List**. Слова «Цель», «Очистить»,
`Destination` и `Clear` для этих кнопок не используются.