Series Tracker

Умный медиа-сервер для автоматического отслеживания, загрузки, организации и нарезки сериалов с торрент-трекеров и VK Video.

Series Tracker — это веб-приложение, которое превращает рутинную задачу по обновлению вашей медиатеки в полностью автономный фоновый процесс. Добавьте источники для ваших сериалов, и приложение само будет проверять наличие новых серий, скачивать их, переименовывать по гибким шаблонам и даже нарезать видеокомпиляции на отдельные эпизоды, готовя их для Plex, Jellyfin или любого другого медиа-сервера.

---

🚀 Возможности

• Поддержка нескольких источников: Система умеет работать как с торрент-трекерами (Kinozal, Anilibria, Anilibria.TV, Astar.bz), так и с VK Video.
• 🧠 Продвинутый движок правил: Мощный визуальный конструктор позволяет создавать сложные цепочки правил (ЕСЛИ... ТО...) для извлечения метаданных (сезон, эпизод, озвучка, качество) из названий видео и файлов.
• 🤖 Многоагентная архитектура: Надежные фоновые процессы обеспечивают стабильность и производительность:
  • MonitoringAgent: Плановое сканирование, синхронизация статусов, проверка файлов.
  • DownloaderAgent: Параллельная загрузка видео из VK через yt-dlp.
  • SlicingAgent: Автоматическая нарезка видеокомпиляций на эпизоды через ffmpeg.
  • RenamingAgent: Централизованная обработка задач на переименование.
  • StatefulAgent: Управление жизненным циклом торрентов в qBittorrent.
• 🎯 "Умный" планировщик для VK: Уникальный алгоритм SmartCollector анализирует все найденные видео (одиночные и компиляции) и строит оптимальный план загрузки для максимального покрытия серий.
• ✂️ Автоматическая нарезка видео: Система умеет получать оглавление (chapters) из видеокомпиляций VK и автоматически нарезать их на отдельные файлы-эпизоды без перекодирования.
• ✨ Централизованное переименование: Все загруженные и обработанные файлы переименовываются в соответствии с единым, настраиваемым форматом.
• 📡 Обновления в реальном времени: Интерфейс на Vue.js мгновенно отображает любые изменения статусов благодаря технологии Server-Sent Events (SSE).
• 🛡️ Отказоустойчивость:
  • Агенты восстанавливают прерванные задачи после перезапуска сервера.
  • Сканер автоматически переключается на рабочие зеркала трекеров в случае недоступности основного домена.
• Система логирования: Все действия агентов и парсеров записываются в базу данных и доступны для просмотра и фильтрации через веб-интерфейс.

---

🛠️ Установка и запуск

Инструкция предполагает установку на сервер под управлением Ubuntu/Debian.

1. Системные зависимости

Сначала необходимо установить все внешние инструменты, которые использует приложение.

# Обновляем систему
sudo apt update && sudo apt upgrade -y

# Устанавливаем Python, PIP и систему виртуальных окружений
sudo apt install python3 python3-pip python3-venv -y

# Устанавливаем FFmpeg (для нарезки видео)
sudo apt install ffmpeg -y

# Устанавливаем yt-dlp (для работы с VK Video)
sudo wget https://github.com/yt-dlp/yt-dlp/releases/latest/download/yt-dlp -O /usr/local/bin/yt-dlp
sudo chmod a+rx /usr/local/bin/yt-dlp

# Устанавливаем библиотеку libtorrent (для будущих функций)
sudo apt install libtorrent-rasterbar-dev -y

2. Установка приложения

1. Клонируйте репозиторий (или просто скопируйте файлы проекта на сервер):

   git clone https://github.com/wolfam0108/series-tracker.git
   cd series-tracker

2. Создайте и активируйте виртуальное окружение:

   # Создаем окружение в папке venv
   python3 -m venv venv
   
   # Активируем его
   source venv/bin/activate

3. Установите Python-библиотеки из файла requirements.txt:

   pip install -r requirements.txt

4. Установите системные зависимости для Playwright:

   sudo playwright install-deps

5. Загрузите браузерные движки для Playwright:

   playwright install

3. Первичная настройка и запуск

1. Создайте директории для медиафайлов и дайте права на них вашему пользователю (замените your_user):

   sudo mkdir -p /путь/к/вашим/сериалам
   sudo chown -R your_user:your_user /путь/к/вашим/сериалам

2. Запустите приложение с помощью Gunicorn:

   # Убедитесь, что виртуальное окружение активировано
   gunicorn -c gunicorn_config.py run:app

3. Настройте авторизацию:

   • Откройте в браузере http://<АДРЕС_ВАШЕГО_СЕРВЕРА>:5000.
   • Перейдите в Настройки → Авторизация.
   • Заполните учетные данные для qBittorrent, Kinozal и VK Video (Access Token).
   • Сохраните изменения.

Теперь ваше приложение полностью настроено и готово к работе. Для остановки Gunicorn нажмите Ctrl+C.

⚙️ Настройка автозапуска через systemd (Linux)

Чтобы приложение запускалось автоматически при старте системы и работало в фоновом режиме, можно создать systemd сервис.

1. Создайте файл сервиса:

sudo nano /etc/systemd/system/series-tracker.service

2. Вставьте в него следующую конфигурацию:

Замените /path/to/your/project на полный путь к папке series-tracker и your_user на ваше имя пользователя.

[Unit]
Description=Series Tracker Application
After=network.target

[Service]
User=your_user
Group=your_user
WorkingDirectory=/path/to/your/project/series-tracker
ExecStart=/path/to/your/project/series-tracker/venv/bin/python3 run.py
Restart=always

[Install]
WantedBy=multi-user.target

3. Включите и запустите сервис:

# Перезагружаем конфигурацию systemd
sudo systemctl daemon-reload

# Включаем автозапуск сервиса при старте системы
sudo systemctl enable series-tracker.service

# Запускаем сервис немедленно
sudo systemctl start series-tracker.service

# Проверяем статус сервиса
sudo systemctl status series-tracker.service

---

📖 Руководство по созданию фильтров

Основы: Как устроен редактор

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

• Профиль: Профиль — это просто контейнер, который хранит набор правил. Каждый сериал (и VK, и торрент) привязывается к одному из профилей. Вы можете создать один универсальный профиль или отдельные профили для разных студий озвучки (например, "AniLibria Rules", "VK Dub Studio Rules").

• Правило: Правило — это одна инструкция в формате "ЕСЛИ... ТО...". Правила в профиле выполняются строго по порядку, сверху вниз. С помощью стрелок вы можете менять их приоритет.

• Условия (ЕСЛИ): Эта часть проверяет, соответствует ли название видео/файла заданному вами шаблону (паттерну).

  • Содержит / Не содержит: Базовые проверки.
  • И / ИЛИ: Вы можете добавлять несколько условий в одно правило и объединять их логикой "И" (должны выполниться все) или "ИЛИ" (должно выполниться хотя бы одно).

• Действия (ТО): Эта часть определяет, что нужно сделать, если условия выполнились.

  • Исключить видео: Самое простое действие. Если условие сработало, это видео/файл будет полностью проигнорировано. Идеально для отсеивания трейлеров, анонсов, обзоров и т.д.
  • Извлечь / Назначить: Основные рабочие действия. Позволяют извлечь из названия динамические данные (номер серии, разрешение) или назначить статические (тег озвучки).

• Конструктор паттернов: Это визуальный редактор, где вы собираете шаблон для поиска.

  • Текст: Соответствует точному тексту, который вы введете.
  • Число: Соответствует любому одному или нескольким числам (1, 05, 155).
  • Пробел: Соответствует одному или нескольким пробелам.
  • *: "Джокер". Соответствует любому количеству любых символов.
  • Начало / Конец: "Якоря", которые привязывают ваш паттерн к началу или концу строки.
  • + / -: Математические операции для корректировки извлеченных чисел.

---

Практика: Настройка фильтров для VK Video

Давайте создадим профиль для типичной группы, которая выкладывает аниме.

Цель: Научить систему правильно распознавать серии, игнорировать мусор и извлекать все метаданные. Пример названия видео: Магическая битва - 2 сезон, 15 серия [1080p] [AniDub]

Шаг 1: Создание профиля

1. Перейдите в Настройки → Фильтры VK.
2. В поле "Имя нового профиля" введите AniDub VK Rules и нажмите кнопку "+".
3. Выберите только что созданный профиль из выпадающего списка. Теперь вы готовы добавлять в него правила.

Шаг 2: Правило №1 — Исключаем лишнее

Первым делом всегда лучше создавать правила для исключения ненужного контента.

1. Нажмите "Добавить правило".
2. Назовите правило, например, Исключить трейлеры и обзоры.
3. В блоке ЕСЛИ выберите Содержит и в конструкторе паттернов соберите шаблон [Трейлер].
4. Нажмите кнопку + рядом с конструктором, чтобы добавить еще одно условие. Выберите логический оператор ИЛИ.
5. Во втором условии соберите паттерн [Обзор].
6. В блоке ТО выберите действие Исключить видео.
7. Сохраните правило.

Теперь, если в названии видео будет слово "Трейлер" или "Обзор", оно будет проигнорировано.

Шаг 3: Правило №2 — Извлекаем метаданные

Это самое главное правило, которое будет обрабатывать стандартные названия серий.

1. Нажмите "Добавить правило" еще раз. Оно появится ниже первого.

2. Назовите его Извлечение данных о серии (Sxx Exx).

3. Блок ЕСЛИ:

   • Создайте условие Содержит со следующим паттерном: [сезон, ] [<Число>] [серия]
   • Это гарантирует, что правило сработает только на названиях, где есть упоминание сезона и серии.

4. Блок ТО: Здесь мы добавим несколько действий, нажимая + после каждого.

   • Действие 1: Извлечь номер сезона. Паттерн: [сезон, ] [<Число>]. Система поймет, что число после "сезон, " — это номер сезона.
   • Действие 2: Извлечь номер серии. Паттерн: [серия] (можно дополнить [, ] [<Число>]).
   • Действие 3: Назначить озвучку/тег. В поле для значения просто впишите AniDub.
   • Действие 4: Извлечь разрешение. Паттерн: [ [<Число>] [p] ]. Конструкция найдет число, после которого идет буква "p", и извлечет его.

5. Сохраните правило.

Шаг 4: Тестирование

1. Перейдите на вкладку "Шаг 3: Тестирование профиля".
2. В большое текстовое поле вставьте проблемные названия, например:

   Магическая битва - 2 сезон, 15 серия [1080p] [AniDub]
   Магическая битва - Трейлер 2 сезона
   

3. Нажмите "Запустить тест".
4. Вы увидите результат: первая строка будет успешно обработана (станет зеленой) с извлеченными данными (Сезон: 2, Серия: 15, Тег: AniDub, Разрешение: 1080), а вторая будет помечена как "ИСКЛЮЧЕНО" (станет красной). Это значит, что ваш профиль работает правильно.

---

Практика: Настройка переименования для торрент-сериалов

Логика здесь абсолютно такая же, но применяется она не к названию видео в VK, а к имени файла внутри торрента.

Цель: Научить систему правильно переименовывать файлы вида [AniLibria.TV]_Shaman_King_Flowers_-_05_[1080p].mkv.

1. Привязка профиля:

   • Зайдите в статус нужного торрент-сериала.
   • На вкладке "Свойства" в поле "Профиль правил" выберите тот профиль, который вы хотите использовать для переименования (можно создать новый, например, "Torrent Renaming Rules").

2. Создание правил:

   • Перейдите в Настройки → Фильтры VK и выберите ваш профиль для торрентов.
   • Создайте правило. Например, для файла [AniLibria.TV]_Shaman_King_Flowers_-_05_[1080p].mkv:
     • ЕСЛИ: Содержит паттерн _-_ [<Число>] _[
     • ТО (Действие 1): Извлечь номер серии с паттерном _-_ [<Число>]
     • ТО (Действие 2): Извлечь разрешение с паттерном [ [<Число>] [p] ]
     • ТО (Действие 3): Назначить озвучку/тег со значением AniLibria.

3. Тестирование:

   • На вкладке тестирования есть уникальная функция для торрентов. Вместо того чтобы вставлять названия вручную, вы можете ввести ID<номер_сериала> (например, ID13) и нажать "Получить с VK" (кнопка также работает для получения файлов из БД).
   • Система автоматически загрузит в поле для теста реальные имена файлов из указанного сериала в вашей базе данных.
   • После этого нажмите "Запустить тест" и убедитесь, что все файлы распознаются корректно.

Эта система очень гибкая. Не бойтесь экспериментировать с разными комбинациями блоков и правил, чтобы добиться идеального результата для ваших источников.

---

📖 Руководство: Добавление нового сериала

Это руководство предполагает, что вы уже создали и настроили профиль фильтров в разделе Настройки → Фильтры VK. Если вы этого еще не сделали, пожалуйста, сначала создайте профиль.

---

Часть 1: Добавление торрент-сериала

Цель: Добавить сериал с трекера (например, Anilibria или Kinozal) и привязать к нему профиль правил для будущего переименования файлов.

Шаг 1: Открытие окна добавления

На главной странице приложения нажмите большую синюю кнопку «Добавить сериал».

Шаг 2: Вставка ссылки и автоматический анализ

В открывшемся окне найдите поле «URL для парсинга». Вставьте в него полную ссылку на страницу с раздачей сериала.

Приложение автоматически начнет анализ ссылки. Вы увидите индикатор загрузки. Если ссылка корректна и трекер доступен, через несколько секунд поля ниже заполнятся автоматически.

Шаг 3: Проверка и заполнение данных

После завершения анализа проверьте автоматически заполненные поля и заполните оставшиеся:

• Название (RU) и (EN): Обычно заполняются автоматически. Проверьте их корректность.
• Путь сохранения: (Обязательно) Укажите полный путь на вашем сервере, куда будут скачиваться файлы этого сериала.
• Сезон: Обычно заполняется автоматически (по умолчанию s01). Если на раздаче несколько сезонов или сезон не важен (например, для фильмов), поставьте галочку "Раздача содержит несколько сезонов".

Шаг 4: Выбор профиля правил (Ключевой шаг)

Найдите поле «Профиль правил». Это выпадающий список.

• Нажмите на него и выберите из списка ваш заранее созданный профиль (например, "Torrent Renaming Rules").

Именно этот профиль будет использоваться для переименования файлов этого сериала после их загрузки.

Шаг 5: Выбор качества (для некоторых трекеров)

Если вы добавляете сериал с трекера, который предлагает несколько версий раздачи (например, Anilibria или Astar.bz), ниже появится блок «Выбор качества». Выберите предпочтительные для вас версии (например, 1080p HEVC).

Шаг 6: Завершение

Нажмите кнопку «Добавить». Окно закроется, и новый сериал появится в общем списке на главной странице, готовый к первому сканированию.

---

Часть 2: Добавление VK-сериала

Цель: Добавить сериал из группы VK и привязать к нему профиль фильтров для распознавания и обработки видео.

Шаг 1: Открытие окна добавления

Так же, как и для торрентов, нажмите кнопку «Добавить сериал».

Шаг 2: Вставка ссылки из VK

В поле «URL для парсинга» вставьте ссылку на видео из нужного вам канала VK. Система автоматически определит, что это VK-ссылка, и интерфейс изменится, показав блок "Настройки для VK Video".

• Поля «Ссылка на канал» и «Поисковые запросы» заполнятся автоматически из вставленной вами ссылки. Вы можете их скорректировать.

Шаг 3: Настройка параметров VK и сериала

1. Режим поиска: Выберите "Быстрый поиск" (рекомендуется для начала) или "Полное сканирование".
2. Название (RU) и (EN): (Обязательно) В отличие от торрентов, эти поля нужно заполнить вручную.
3. Путь сохранения: (Обязательно) Укажите путь для загрузки файлов.
4. Сезон: Если в группе выкладывают несколько сезонов вперемешку, поставьте галочку "Раздача содержит несколько сезонов". В противном случае, укажите номер сезона (например, s01).

Шаг 4: Выбор профиля правил (Ключевой шаг)

Это самый важный шаг для VK-сериалов.

• В поле «Профиль правил» выберите ваш заранее созданный профиль для VK (например, "AniDub VK Rules").

Без правильно выбранного профиля система не сможет распознать серии в потоке видео из группы.

Ша-г 5: Завершение

Нажмите кнопку «Добавить». Сериал появится в общем списке. Теперь вы можете запустить для него сканирование, чтобы система нашла и запланировала к загрузке первые серии согласно вашим правилам.