Рефакторизация структуры кода для улучшения читаемости и удобства сопровождения.
This commit is contained in:
Dmitriy Fofanov
+176
@@ -0,0 +1,176 @@
|
||||
# ---> Python
|
||||
# Byte-compiled / optimized / DLL files
|
||||
__pycache__/
|
||||
*.py[cod]
|
||||
*$py.class
|
||||
|
||||
# C extensions
|
||||
*.so
|
||||
|
||||
# Distribution / packaging
|
||||
.Python
|
||||
build/
|
||||
develop-eggs/
|
||||
dist/
|
||||
downloads/
|
||||
eggs/
|
||||
.eggs/
|
||||
lib/
|
||||
lib64/
|
||||
parts/
|
||||
sdist/
|
||||
var/
|
||||
wheels/
|
||||
share/python-wheels/
|
||||
*.egg-info/
|
||||
.installed.cfg
|
||||
*.egg
|
||||
MANIFEST
|
||||
|
||||
# PyInstaller
|
||||
# Usually these files are written by a python script from a template
|
||||
# before PyInstaller builds the exe, so as to inject date/other infos into it.
|
||||
*.manifest
|
||||
*.spec
|
||||
|
||||
# Installer logs
|
||||
pip-log.txt
|
||||
pip-delete-this-directory.txt
|
||||
|
||||
# Unit test / coverage reports
|
||||
htmlcov/
|
||||
.tox/
|
||||
.nox/
|
||||
.coverage
|
||||
.coverage.*
|
||||
.cache
|
||||
nosetests.xml
|
||||
coverage.xml
|
||||
*.cover
|
||||
*.py,cover
|
||||
.hypothesis/
|
||||
.pytest_cache/
|
||||
cover/
|
||||
|
||||
# Translations
|
||||
*.mo
|
||||
*.pot
|
||||
|
||||
# Django stuff:
|
||||
*.log
|
||||
local_settings.py
|
||||
db.sqlite3
|
||||
db.sqlite3-journal
|
||||
|
||||
# Flask stuff:
|
||||
instance/
|
||||
.webassets-cache
|
||||
|
||||
# Scrapy stuff:
|
||||
.scrapy
|
||||
|
||||
# Sphinx documentation
|
||||
docs/_build/
|
||||
|
||||
# PyBuilder
|
||||
.pybuilder/
|
||||
target/
|
||||
|
||||
# Jupyter Notebook
|
||||
.ipynb_checkpoints
|
||||
|
||||
# IPython
|
||||
profile_default/
|
||||
ipython_config.py
|
||||
|
||||
# pyenv
|
||||
# For a library or package, you might want to ignore these files since the code is
|
||||
# intended to run in multiple environments; otherwise, check them in:
|
||||
# .python-version
|
||||
|
||||
# pipenv
|
||||
# According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
|
||||
# However, in case of collaboration, if having platform-specific dependencies or dependencies
|
||||
# having no cross-platform support, pipenv may install dependencies that don't work, or not
|
||||
# install all needed dependencies.
|
||||
#Pipfile.lock
|
||||
|
||||
# poetry
|
||||
# Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
|
||||
# This is especially recommended for binary packages to ensure reproducibility, and is more
|
||||
# commonly ignored for libraries.
|
||||
# https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
|
||||
#poetry.lock
|
||||
|
||||
# pdm
|
||||
# Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
|
||||
#pdm.lock
|
||||
# pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
|
||||
# in version control.
|
||||
# https://pdm.fming.dev/#use-with-ide
|
||||
.pdm.toml
|
||||
|
||||
# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
|
||||
__pypackages__/
|
||||
|
||||
# Celery stuff
|
||||
celerybeat-schedule
|
||||
celerybeat.pid
|
||||
|
||||
# SageMath parsed files
|
||||
*.sage.py
|
||||
|
||||
# Environments
|
||||
.env
|
||||
.venv
|
||||
env/
|
||||
venv/
|
||||
ENV/
|
||||
env.bak/
|
||||
venv.bak/
|
||||
|
||||
# Spyder project settings
|
||||
.spyderproject
|
||||
.spyproject
|
||||
|
||||
# Rope project settings
|
||||
.ropeproject
|
||||
|
||||
# mkdocs documentation
|
||||
/site
|
||||
|
||||
# mypy
|
||||
.mypy_cache/
|
||||
.dmypy.json
|
||||
dmypy.json
|
||||
|
||||
# Pyre type checker
|
||||
.pyre/
|
||||
|
||||
# pytype static type analyzer
|
||||
.pytype/
|
||||
|
||||
# Cython debug symbols
|
||||
cython_debug/
|
||||
|
||||
# PyCharm
|
||||
# JetBrains specific template is maintained in a separate JetBrains.gitignore that can
|
||||
# be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
|
||||
# and can be added to the global gitignore or merged into this file. For a more nuclear
|
||||
# option (not recommended) you can uncomment the following to ignore the entire idea folder.
|
||||
#.idea/
|
||||
|
||||
# ---> Project specific
|
||||
# Локальные библиотеки/сканы и результаты обработки (могут быть очень большими)
|
||||
scan/
|
||||
output/
|
||||
audiobooks/
|
||||
AudiobookOutput/
|
||||
|
||||
# Генерируемые отчеты
|
||||
directory_tree_*.json
|
||||
|
||||
# Системные артефакты
|
||||
Thumbs.db
|
||||
.DS_Store
|
||||
|
||||
@@ -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 режим (предпросмотр изменений без файловых операций).
|
||||
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
Reference in New Issue
Block a user