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