Jellyfin Wrapped

Jellyfin Wrapped генерирует персональный "итог года" по данным просмотров из Jellystat (PostgreSQL) и показывает его в веб-интерфейсе или сохраняет в HTML через CLI.

Возможности

• Авторизация через Jellyfin (логин/пароль) и Quick Connect.
• Генерация персонального отчета за текущий год:
  • суммарные часы/события/активные дни;
  • топ фильмов и сериалов;
  • активность по месяцам и дням недели;
  • топ устройств и жанров;
  • первое и последнее просмотренное;
  • "персона" на основе жанров.
• Экспорт шеринговой PNG-картинки (/report/share-image).
• Админ-панель для удаления сгенерированных отчетов.
• CLI-режим: генерация HTML-файла без веб-интерфейса.

Стек

• Python 3.12
• Flask
• PostgreSQL (данные Jellystat)
• psycopg2-binary
• requests
• Pillow (для PNG; уже используется в коде)
• Gunicorn (для прод-запуска в Docker)

Структура проекта

• app.py - точка входа Flask для локального запуска.
• cli.py - генерация отчета из командной строки.
• jellyfin_wrapped/webapp.py - веб-приложение и роуты.
• jellyfin_wrapped/queries.py - SQL-запросы к Jellystat.
• jellyfin_wrapped/config.py - чтение конфигурации из переменных окружения.
• reports/ - директория сгенерированных HTML-отчетов (создается автоматически).

Требования

• Доступ к PostgreSQL базе Jellystat.
• Jellyfin-сервер с доступным API.
• Python 3.12+.

Настройка

1) Установить зависимости

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
pip install pillow gunicorn

Примечание: в requirements.txt сейчас отсутствуют pillow и gunicorn, хотя они используются проектом.

2) Заполнить переменные окружения (обязательно)

Создайте локальный .env на основе шаблона:

cp example.env .env

Далее укажите реальные значения в .env и экспортируйте их в окружение:

set -a
source .env
set +a

3) Поддерживаемые env-переменные

Поддерживаемые переменные окружения:

• DB_HOST (обязательная)
• DB_PORT (по умолчанию 5432)
• DB_NAME (обязательная)
• DB_USER (обязательная)
• DB_PASSWORD (обязательная)
• ANIME_LIBRARY_NAME (по умолчанию Аниме)
• SERIES_LIBRARY_NAME (по умолчанию Сериалы)
• JELLYFIN_URL (по умолчанию http://localhost:8096)
• JELLYFIN_CLIENT_NAME (по умолчанию Jellyfin Wrapped)
• JELLYFIN_CLIENT_VERSION (по умолчанию 1.0.0)
• JELLYFIN_DEVICE_NAME (по умолчанию Wrapped Web)
• JELLYFIN_DEVICE_ID (если не задан, генерируется автоматически)
• WRAPPED_SECRET_KEY (обязательная)

Пример:

export JELLYFIN_URL="http://jellyfin.local:8096"
export WRAPPED_SECRET_KEY="change-me-long-random-value"

Запуск

Локальный веб-режим (dev)

python app.py

По умолчанию приложение слушает 0.0.0.0:8000, debug включен.

Прод-режим (Gunicorn)

gunicorn --workers 4 --bind 0.0.0.0:8000 "jellyfin_wrapped.webapp:create_app()"

CLI-режим

python cli.py --user USERNAME --year 2025 --output report.html

Параметры:

• --user (обязательный) - UserName из jf_playback_activity.
• --year (необязательный) - год отчета, по умолчанию текущий.
• --output (необязательный) - путь к HTML-файлу, по умолчанию index.html.

Docker

Сборка:

docker build -t jellyfin-wrapped .

Запуск:

docker run --rm -p 8000:8000 \
  -e DB_HOST="host.docker.internal" \
  -e DB_NAME="jfstat" \
  -e DB_USER="postgres" \
  -e DB_PASSWORD="change_me" \
  -e JELLYFIN_URL="http://host.docker.internal:8096" \
  -e WRAPPED_SECRET_KEY="change-me-long-random-value" \
  jellyfin-wrapped

Важно для Docker:

• Контейнеру нужен сетевой доступ к Jellyfin и PostgreSQL.
• Обязательные DB_* и WRAPPED_SECRET_KEY нужно передать через -e или --env-file.

Основные маршруты

• GET / - страница входа.
• POST / - авторизация по логину/паролю.
• POST /quickconnect/start - старт Quick Connect.
• GET /quickconnect/status - проверка статуса Quick Connect.
• GET /report - экран загрузки отчета.
• GET /report/generate - генерация отчета.
• GET /report/view - просмотр отчета.
• GET /report/share-image - PNG-картинка для шеринга.
• GET /admin - админ-панель.

Известные ограничения

• Отчеты генерируются за текущий год в веб-режиме (год пока не передается параметром).

Рекомендации по безопасности

• Не храните реальные пароли в репозитории.
• Вынесите БД-настройки в переменные окружения.
• Обязательно задавайте WRAPPED_SECRET_KEY в проде.
• Ограничьте доступ к /admin на уровне reverse-proxy/сети.