158 lines
7.7 KiB
Markdown
158 lines
7.7 KiB
Markdown
# 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 режим (предпросмотр изменений без файловых операций).
|
||
|