BookFlow Curator

BookFlow Curator — консольный инструмент на Python для автоматизации разбора и организации коллекции аудиокниг.

Portfolio snapshot. Проект показывает полный файловый pipeline: сканирование коллекции, извлечение тегов, AI-обогащение, нормализацию структуры и формирование metadata.json для дальнейшей интеграции.

Проект сканирует папки с аудиофайлами, извлекает метаданные (теги, длительность, главы), при необходимости дополняет их через LLM (OpenRouter), переименовывает каталоги по единому формату и формирует структурированную библиотеку с metadata.json.

Что умеет

• Сканирует дерево каталогов и находит поддерживаемые аудиофайлы.
• Извлекает метаданные из аудио через mutagen (если библиотека установлена).
• Собирает сводную информацию по папке-книге: количество файлов, длительность, главы.
• Генерирует/обновляет metadata.json в папках книг.
• Переименовывает папки книг в унифицированный формат.
• Организует выходную структуру по шаблону:
  • AUDIOBOOK_OUTPUT_PATH/<Буква>/<Автор>/<Книга>/...
• Поддерживает AI-обогащение метаданных через OpenRouter (OPENROUTER_API_KEY обязателен в текущем UI-наборе настроек).
• Показывает интерактивный интерфейс в терминале (rich), включая логи и прогресс.

Рабочий сценарий

В главном меню оставлен один законченный сценарий — Организация библиотеки аудиокниг. Экспериментальные пункты без реализации удалены, чтобы интерфейс не обещал несуществующие возможности.

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

• bookflow_curator.py — основной исполняемый файл, содержит:
  • конфигурацию (ConfigurationManager, SettingsManager),
  • UI и меню (UIManager, InteractiveMenu),
  • AI-слой (AITextProcessor),
  • сканер/извлечение/организацию (AudiobookScanner, AudiobookMetadataExtractor),
  • оркестратор (BookFlowCurator) и точку входа main().
• README.md — документация проекта.

Требования

• Python 3.10+ (рекомендуется 3.11).
• ОС: Windows/Linux/macOS (основной сценарий проверен под Windows).
• Доступ в интернет для AI-функций (OpenRouter).

Установка

Из корня проекта:

python -m venv .venv
# Windows PowerShell
.\.venv\Scripts\Activate.ps1

pip install --upgrade pip
pip install -r requirements.txt

InquirerPy и mutagen в коде обработаны как опциональные; без них приложение запускается, но часть возможностей будет упрощена.

Настройка .env

Создайте файл .env в корне проекта. Минимально:

# Обязательное (в текущей валидации SettingsManager)
OPENROUTER_API_KEY=your_openrouter_api_key

# Базовые пути
AUDIOBOOK_SCAN_PATH=./scan
AUDIOBOOK_OUTPUT_PATH=./output
AUDIOBOOK_LIBRARY_PATH=./audiobooks

# OpenRouter
OPENROUTER_BASE_URL=https://openrouter.ai/api/v1
OPENROUTER_MODEL=deepseek/deepseek-chat-v3-0324:free
OPENROUTER_REFERER=https://github.com/dfofanov/repo
OPENROUTER_APP_TITLE=BookFlow Curator
OPENROUTER_MAX_INPUT_CHARS=12000

# Форматы
SUPPORTED_AUDIO_EXTENSIONS=mp3,m4a,m4b,opus,ogg,flac
SUPPORTED_TEXT_EXTENSIONS=txt,pdf,epub,mobi

Дополнительно (опционально):

AUDIOBOOK_SOURCE_API_KEY=
AUDIOBOOK_SOURCE_BASE_URL=
AUDIOBOOK_SOURCE_TIMEOUT=20
AUDIOBOOK_SOURCE_USER_AGENT=Mozilla/5.0 (compatible; BookFlowCuratorBot/1.0)

Запуск

python bookflow_curator.py

Далее сценарий такой:

1. Открывается интерфейс настроек (SettingsManager) с валидацией.
2. После подтверждения появляется главное меню.
3. Выберите Организация библиотеки аудиокниг.

Как устроена обработка

1. Сканирование AUDIOBOOK_SCAN_PATH на поддерживаемые аудиоформаты.
2. Для каждой папки с аудио:
   • чтение метаданных,
   • расчет длительностей и глав,
   • попытка AI-обогащения,
   • генерация metadata.json,
   • переименование папки,
   • копирование/перенос в выходную структуру.
3. Сохранение итогового дерева в JSON-отчет вида directory_tree_YYYYMMDD_HHMMSS.json.

Управление во время долгой обработки

• Пробел — пауза/продолжение.
• Q — прервать текущий процесс.

Формат создаваемого metadata.json

Проект формирует файл примерно с такими полями:

• tags
• chapters (id, start, end, title)
• title, subtitle
• authors, narrators, series, genres
• publishedYear, publishedDate, publisher
• description
• isbn, asin, language, explicit, abridged

Ограничения и важные замечания

• Текущая AI-обработка отправляет в LLM в основном имя папки; качество обогащения зависит от нейминга исходных каталогов.
• При наличии конфликтов имен целевых папок может выполняться удаление существующей папки перед копированием.
• Некоторые функции ориентированы на структуру русскоязычных метаданных и названий.

Рекомендованная структура локальных данных

bookflow-curator/
├─ bookflow_curator.py
├─ .env
├─ scan/                 # входные неорганизованные аудиокниги
├─ output/               # структурированный вывод
└─ audiobooks/           # отчеты и служебные результаты

Планы развития

• Добавить тесты для модулей метаданных и безопасного переименования/копирования.
• Расширить dry-run режим (предпросмотр изменений без файловых операций).

Лицензия

Другие проекты и контакты автора: DFV24 — dfv24.com.

Проект распространяется по лицензии MIT.