SeriesToolkit

SeriesToolkit — это «одна папка — один инструмент» для навода порядка в библиотеках сериалов и мультсериалов. Это основной и актуальный релиз проекта: здесь текущий движок, GUI, сборка EXE и документация.

Зачем это нужно (по-человечески)

• В папках бардак: «Сезон 1», Season 01, файлы лежат не там.
• Имена файлов не совпадают с тем, как вы ищете серии.
• Хочется сначала посмотреть план (dry-run), потом один раз применить.
• Нужны русские названия эпизодов, где они вообще существуют в открытых источниках.

SeriesToolkit как раз это делает и пишет подробный CSV-лог, чтобы ничего не потерять.

Быстрые ссылки для тестеров (без git)

Что скачать	Прямая ссылка
Архив всего проекта (ветка master)	SeriesToolkit-master.zip
Только launcher (скрипт; положите рядом остальные файлы из ZIP)	SeriesToolkit.ps1 (raw)
Сборки / стабильные ZIP	Releases

После скачивания ZIP распакуйте в любую папку, рядом должен остаться родительский Fetch-VideoMetadata.ps1 (в архиве он в корне пакета, если синхронизация с родительским репозиторием настроена — см. Sync-GitHub.ps1).

Входная сортировка (отдельный продукт)

Пакет MediaInboxToolkit (каталог MediaInboxToolkit/ в корне репозитория, ветка media-inbox-toolkit) — раскладка inbox → Сериалы / Фильмы, TMDB, Blu-ray. SeriesToolkit остаётся про нормализацию уже разложенных сериалов. См. ../MediaInboxToolkit/README.md.

Как это выглядит (GUI)

Актуальные скриншоты интерфейса:

Как сделать настоящие скриншоты у себя — пошагово: docs/SCREENSHOTS-RU.md.

Вложенные папки («сага» → отдельные сериалы)

Если структура такая:

Сериалы\
  Звёздные войны\
    Войны клонов\     ← отдельный сериал
      Сезон 1\ ...
    Повстанцы\        ← другой сериал

то toolkit не склеивает «Звёздные войны» в один сериал: он обходит контейнер и обрабатывает каждую внутреннюю папку, которая выглядит как отдельное шоу (есть видео или папки сезонов). Если в корне контейнера лежат сами видеофайлы, контейнер считается одним сериалом — как раньше.

Недостающие сезоны на диске

Если в метаданных (TMDB и др.) есть сезон 3, а на диске папки нет, при включённой настройке (по умолчанию да):

• создаётся папка сезона;
• внутри — служебный маркер .series-toolkit-scaffold и короткая подсказка;
• в корне сериала пишется SeriesToolkit-episode-index.csv — полный список эпизодов из базы, чтобы быстрее ориентироваться при следующей докачке.

Отключить можно в SeriesToolkit.settings.json: create_missing_season_folders, write_episode_index_csv.

Что делает toolkit

• Приводит имена папок сезонов к одному шаблону (по умолчанию Сезон N).
• Строит безопасный план переименований и перемещений, снимает коллизии.
• Подтягивает названия эпизодов (HTML вручную, ru.wikipedia, Кинопоиск при доступе, TMDB ru-RU; опционально латиница для заглушек — см. настройки).
• Удаляет пустые папки после работы (папки-заготовки с маркером не пустые).

Режимы

• Batch — вся библиотека по RootPath.
• Manual — один сериал + опционально локальный HTML со списком серий.

Профили источников метаданных

• Fast:
  • при наличии TMDB API: только TMDB;
  • без TMDB API: только Wikipedia.
• Balanced:
  • при наличии TMDB API: TMDB + Wikipedia + Кинопоиск;
  • без TMDB API: Wikipedia + Кинопоиск.
• Full:
  • при наличии TMDB API: TMDB + Wikipedia + Кинопоиск + DDG + Yandex + Google;
  • без TMDB API: Wikipedia + Кинопоиск + DDG + Yandex + Google.

Важно: кэш метаданных теперь разделён по профилю и состоянию TMDB API, чтобы Fast не «загрязнял» результаты Balanced/Full.

Запуск из PowerShell

Пробный прогон (ничего не меняет на диске):

powershell -NoProfile -ExecutionPolicy Bypass -File .\SeriesToolkit.ps1 -Mode Batch -RootPath "\\сервер\шара\Сериалы" -DryRun

Проверка (VerifyOnly: строит план/логи, но не меняет файлы):

powershell -NoProfile -ExecutionPolicy Bypass -File .\SeriesToolkit.ps1 -Mode Batch -RootPath "\\сервер\шара\Сериалы" -VerifyOnly -ExecutionProfile Full

Для ускоренного пакетного предпросмотра можно включить ограниченный параллелизм через batch_max_parallel (до 4, только DryRun/VerifyOnly).

Боевой:

powershell -NoProfile -ExecutionPolicy Bypass -File .\SeriesToolkit.ps1 -Mode Batch -RootPath "\\сервер\шара\Сериалы" -Apply -UseTmdb

# пример выбора профиля
powershell -NoProfile -ExecutionPolicy Bypass -File .\SeriesToolkit.ps1 -Mode Batch -RootPath "\\сервер\шара\Сериалы" -DryRun -ExecutionProfile Full

GUI

powershell -NoProfile -ExecutionPolicy Bypass -File .\Start-SeriesToolkitGui.ps1

Во время работы GUI теперь показывает:

• общий прогресс библиотеки: LibraryProgress % (i/N);
• прогресс текущего сериала: SeriesProgress % (этап/всего);
• метрики времени: время старта, сколько прошло, ETA (оценка завершения);
• отдельную визуальную общую шкалу процента выполнения библиотеки;
• «последняя активность Nс назад» (если долго нет новых строк — видно, что происходит тяжёлый этап);
• кнопки Свернуть, Пауза / Продолжить, Пропуск (текущий сериал) и Стоп без закрытия окна;
• выбор профиля запуска Быстрый / Баланс / Полный с краткой подсказкой по источникам;
• компактный readonly-блок Диагностика с последней причиной недобора метаданных по текущему сериалу;
• корректную адаптацию интерфейса при изменении размера/разворачивании окна;
• при нажатии Стоп — корректный финальный статус «прервано пользователем» с краткой статистикой выполнения.

Служебные GUI-логи:

• LOGS/gui-session-*.log — события GUI (старт, кнопки, причины закрытия, ошибки);
• LOGS/gui-progress-*.log — поток прогресса от движка.

Для упаковки в один файл: .\Build-SeriesToolkitExe.ps1 → SeriesToolkit.GUI.exe.
У EXE и у окна во время выполнения используется иконка assets/SeriesToolkit.icon.ico; при сборке старый SeriesToolkit.GUI.exe автоматически ротируется в .bak.

EXE пересобирается автоматически, когда меняется SeriesToolkit.ps1 и срабатывает инкремент версии (см. Bump-Version.ps1). Отключить пересборку: -SkipAutoBuildExe у launcher.

Настройки и секреты

1. Скопируйте SeriesToolkit.settings.example.json → SeriesToolkit.settings.json.
2. Подробно: SeriesToolkit.settings.README.md.
3. Файл с ключами и cookie не коммитьте (см. корневой .gitignore).

Версии, OLD и GitHub

• Версия в version.json.
• Инкремент версии и снимок в OLD/ выполняются только когда изменился файл SeriesToolkit.ps1 (хэш сравнивается с локальным .launcher-content.sha256, файл в .gitignore).
• После успешного bump по желанию пересобирается EXE (если установлен модуль ps2exe).
• Sync-GitHub.ps1 публикует копию без секретов в репозиторий emildg8/SeriesToolkit и автоматически делает/обновляет GitHub Release vX.Y.Z с ZIP-архивом.

Логи

Каталог LOGS: CSV по операциям, краткий TXT и отдельный *-renames.txt с явным FROM -> TO по переименованиям. Также формируется *-renames.csv для фильтрации/аналитики в Excel/BI. Для ручного разбора спорных кейсов формируется *-review-queue.csv (low-confidence, review-required, проблемные skip). В итоговом TXT добавлены throughput-метрики: ProcessedSeries, SeriesPerMinute, AvgMetaFirstPassMs.

Если метаданные не нашлись

• Проверьте профиль: для максимального добора используйте Full (в GUI или -ExecutionProfile Full).
• Убедитесь, что корректно задан tmdb_api_key в SeriesToolkit.settings.json; без ключа TMDB отключается и используются fallback-источники.
• Для Кинопоиска обновите kinopoisk_cookie (если устарел сеанс, растёт шанс капчи/пустых ответов).
• Увеличьте metadata_request_timeout_sec (например, до 90) при медленном интернете.
• Включайте strict_mode=true для безопасного режима: toolkit не будет делать рискованные переименования с заглушками, а отправит их в review-очередь.
• Подключите алиасы в series-aliases.json (шаблон: series-aliases.example.json) для сложных/франшизных названий.
• Для повторной проверки проблемного сериала запустите Manual + DryRun, чтобы быстро увидеть причины в LOGS/gui-progress-*.log.
• Ищите строки [SeriesToolkit][Diag] ... в gui-progress/TXT — там кратко видно, какой источник дал ok/no-match/error/captcha.
• Если в файлах остались заглушки Серия N, проверьте *-renames.txt и SeriesToolkit-episode-index.csv в папке сериала: там видно, что найдено и что не удалось сопоставить.

Как читать review-queue

*-review-queue.csv — это очередь ручной проверки спорных кейсов.

• review-required: strict mode заблокировал рискованное переименование (обычно нет подтверждённого названия, иначе была бы заглушка).
• skip-low-confidence: итоговый confidence ниже rename_min_confidence_apply.
• skip-file (WARN/ERROR): файл не удалось надёжно распарсить или собрать корректную цель.

Практический порядок разбора:

1. Сначала review-required (самые важные, потенциально рискованные случаи).
2. Затем skip-low-confidence (порог можно ослабить, если кейсы массовые и однотипные).
3. В конце skip-file (ERROR) — обычно это нестандартные имена/структура.

Рекомендуемые пороги rename_min_confidence_apply:

• 85 — консервативно (для «боевого» Apply на незнакомой библиотеке).
• 75 — сбалансировано (дефолт, обычно лучший старт).
• 65 — агрессивнее (когда библиотека однотипная и вы готовы чаще смотреть review-queue).

Обратная связь

Репозиторий: https://github.com/emildg8/SeriesToolkit