Рефакторизация структуры кода для улучшения читаемости и удобства сопровождения.

2026-02-22 22:09:57 +03:00
parent 3d514e436a
commit 344e1eb63c
3 changed files with 2788 additions and 0 deletions
@@ -1,2 +1,157 @@
 # AudiobookOrganizer

+AudiobookOrganizer — консольный инструмент на Python для автоматизации разбора и организации коллекции аудиокниг.
+
+Проект сканирует папки с аудиофайлами, извлекает метаданные (теги, длительность, главы), при необходимости дополняет их через LLM (OpenRouter), переименовывает каталоги по единому формату и формирует структурированную библиотеку с `metadata.json`.
+
+## Что умеет
+
+- Сканирует дерево каталогов и находит поддерживаемые аудиофайлы.
+- Извлекает метаданные из аудио через `mutagen` (если библиотека установлена).
+- Собирает сводную информацию по папке-книге: количество файлов, длительность, главы.
+- Генерирует/обновляет `metadata.json` в папках книг.
+- Переименовывает папки книг в унифицированный формат.
+- Организует выходную структуру по шаблону:
+	- `AUDIOBOOK_OUTPUT_PATH/<Буква>/<Автор>/<Книга>/...`
+- Поддерживает AI-обогащение метаданных через OpenRouter (`OPENROUTER_API_KEY` обязателен в текущем UI-наборе настроек).
+- Показывает интерактивный интерфейс в терминале (`rich`), включая логи и прогресс.
+
+## Текущий статус команд меню
+
+В главном меню сейчас доступны 3 пункта:
+
+1. `Организация библиотеки аудиокниг` — **реализован** (основной рабочий сценарий).
+2. `Извлечение метаданных` — заглушка (каркас без полноценной бизнес-логики).
+3. `Создание каталога` — заглушка (каркас без полноценной бизнес-логики).
+
+## Структура проекта
+
+- `audiobookorganizer.py` — основной исполняемый файл, содержит:
+	- конфигурацию (`ConfigurationManager`, `SettingsManager`),
+	- UI и меню (`UIManager`, `InteractiveMenu`),
+	- AI-слой (`AITextProcessor`),
+	- сканер/извлечение/организацию (`AudiobookScanner`, `AudiobookMetadataExtractor`),
+	- оркестратор (`AudiobookOrganizer`) и точку входа `main()`.
+- `README.md` — документация проекта.
+
+## Требования
+
+- Python 3.10+ (рекомендуется 3.11).
+- ОС: Windows/Linux/macOS (основной сценарий проверен под Windows).
+- Доступ в интернет для AI-функций (OpenRouter).
+
+## Установка
+
+Из корня проекта:
+
+```bash
+python -m venv .venv
+# Windows PowerShell
+.\.venv\Scripts\Activate.ps1
+
+pip install --upgrade pip
+pip install python-dotenv PyPDF2 python-docx rich openai requests mutagen InquirerPy
+```
+
+> `InquirerPy` и `mutagen` в коде обработаны как опциональные; без них приложение запускается, но часть возможностей будет упрощена.
+
+## Настройка `.env`
+
+Создайте файл `.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=AudiobookOrganizer
+OPENROUTER_MAX_INPUT_CHARS=12000
+
+# Форматы
+SUPPORTED_AUDIO_EXTENSIONS=mp3,m4a,m4b,opus,ogg,flac
+SUPPORTED_TEXT_EXTENSIONS=txt,pdf,epub,mobi
+```
+
+Дополнительно (опционально):
+
+```env
+AUDIOBOOK_SOURCE_API_KEY=
+AUDIOBOOK_SOURCE_BASE_URL=
+AUDIOBOOK_SOURCE_TIMEOUT=20
+AUDIOBOOK_SOURCE_USER_AGENT=Mozilla/5.0 (compatible; AudiobookOrganizerBot/1.0)
+```
+
+## Запуск
+
+```bash
+python audiobookorganizer.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 в основном имя папки; качество обогащения зависит от нейминга исходных каталогов.
+- Пункты меню `Извлечение метаданных` и `Создание каталога` пока не реализованы полностью.
+- При наличии конфликтов имен целевых папок может выполняться удаление существующей папки перед копированием.
+- Некоторые функции ориентированы на структуру русскоязычных метаданных и названий.
+
+## Рекомендованная структура локальных данных
+
+```text
+AudiobookOrganizer/
+├─ audiobookorganizer.py
+├─ .env
+├─ scan/                 # входные неорганизованные аудиокниги
+├─ output/               # структурированный вывод
+└─ audiobooks/           # отчеты и служебные результаты
+```
+
+## Планы развития
+
+- Доработать команды `extract_metadata` и `create_catalog` до полноценных сценариев.
+- Вынести зависимости в `requirements.txt`.
+- Добавить тесты для модулей метаданных и безопасного переименования/копирования.
+- Расширить dry-run режим (предпросмотр изменений без файловых операций).
+