From 8317ad1fe4cc93b6551a658bc398c60f61b94957 Mon Sep 17 00:00:00 2001 From: Maksim Totmin Date: Tue, 2 Jun 2026 08:58:13 +0700 Subject: [PATCH] docs: rewrite README.md with detailed project description - Update entry point from main.py to app.py - Document all modules: artwork pipeline, iOpenPod integration, SQLite cache, session store, device monitor, playlist manager, hotkeys, UI widgets (8 tabs), worker thread - Add architecture overview and technology table - Add configuration paths section --- README.md | 163 ++++++++++++++++++++++++++++++++++++++---------------- 1 file changed, 114 insertions(+), 49 deletions(-) diff --git a/README.md b/README.md index 60be066..c4c38f5 100644 --- a/README.md +++ b/README.md @@ -1,84 +1,149 @@ # neo-pod-desktop -Desktop application for converting, managing and transferring music to iPod Nano 7G. Includes format conversion, metadata management, local library with playback, cover art pipeline, and full iTunesDB/ArtworkDB generation. +Настольное приложение для управления музыкой на iPod Nano 6G/7G с встроенным iTunes-подобным плеером, конвертацией аудио, полным пайплайном обложек и генерацией iTunesDB/SQLite/ArtworkDB через iOpenPod. -## Features +## Возможности -- **Convert** to iPod-compatible formats (AAC/M4A, MP3) with `-map 0:t?` cover preservation -- **Metadata** handling -- title, artist, album, track number, genre, embedded cover art -- **Cover art pipeline** -- extract from audio files (APIC/covr/FLAC pictures), encode to iPod Nano 7G formats (RGB565), write ArtworkDB + ithmb -- **iTunes-style player** -- play local library with cover art display (60x60), seek, volume -- **iPod Nano 7G database** -- full iTunesCDB sync, SQLite management, Locations.itdb with HASHAB checksums -- **Library management** -- sortable table, source/ready track separation, bulk transfer -- **Portable AppImage** -- `scripts/build-appimage.sh` builds standalone x86_64 AppImage -- **Config** stored in `~/.config/neo-pod-desktop/config.ini` +- **Встроенный плеер** — воспроизведение локальной библиотеки через QMediaPlayer, отображение обложек альбомов (60x60), перемотка, громкость, повтор (all/one), shuffle +- **Конвертация аудио** — FFmpeg конвертация в AAC/M4A (libfdk_aac с AAC-LC профилем, 160 kbps) и MP3 (libmp3lame); конвертация видео для iPod (H.264, 640x480) +- **Пайплайн ArtworkDB** — извлечение обложек из аудиофайлов (APIC/covr/FLAC pictures), кодирование в iPod-нативные форматы (RGB565, RGB555, UYVY, JPEG), запись ithmb + ArtworkDB (MHFD→MHII→MHNI структуры) +- **Генерация баз iPod** — полная регенерация iTunesDB (бинарный mhbd) и SQLite баз для Nano 6G/7G через iOpenPod, cross-reference валидация db_pid +- **Синхронизация статистики** — двухсторонняя синхронизация play count, rating, skip count, last played между локальным кэшем (SQLite) и iPod; автосинк при подключении; validation gate против потери данных +- **Локальная библиотека** — сортируемая таблица с поддержкой drag-and-drop, фильтрация по альбомам/плейлистам, поиск, разделение на source-треки (FLAC/WAV) и готовые (MP3/M4A) +- **Плейлисты** — создание, переименование, удаление, drag-and-drop треков; перенос плейлистов на iPod с двухпроходным сопоставлением (content hash → metadata fallback) +- **Редактор метаданных** — редактирование тегов и обложек для MP3/M4A/FLAC/OGG/OPUS, batch-режим, интеграция с iTunes Search API для автозаполнения +- **Горячие клавиши** — полностью настраиваемые шорткаты (воспроизведение, навигация, громкость, перемотка, управление библиотекой) +- **Сессия воспроизведения** — автоматическое сохранение и восстановление последнего трека, позиции, громкости, режимов shuffle/repeat +- **Автоопределение устройств** — фоновый мониторинг iPod (Linux/macOS/Windows) через DeviceMonitor с polling +- **AppImage** — портативная сборка через PyInstaller + appimagetool -## Installation +## Установка -### Dependencies +### Зависимости -- Python 3.14+ -- FFmpeg (for audio conversion) -- libusb (for USB device access on Linux) +- Python 3.10+ +- FFmpeg (для конвертации аудио) +- libusb (для доступа к USB на Linux) ```bash pip install -r requirements.txt ``` -Install FFmpeg: +Установка FFmpeg: - **macOS**: `brew install ffmpeg` - **Linux**: `sudo apt-get install ffmpeg` -- **Windows**: Download from [ffmpeg.org](https://ffmpeg.org/download.html) +- **Windows**: Скачайте с [ffmpeg.org](https://ffmpeg.org/download.html) -## Usage +## Использование -### GUI Application +### GUI приложение ```bash -python src/main.py +python src/app.py ``` -### AppImage (portable) +### AppImage (портативная версия) ```bash ./neo-pod-desktop-x86_64.AppImage ``` -Build from source: +Сборка из исходников: ```bash ./scripts/build-appimage.sh ``` -## Project Structure +## Структура проекта ``` -src/ - main.py -- GUI application (PyQt6) - track_info.py -- TrackInfo data class - audio_converter.py -- FFmpeg audio conversion - metadata_handler.py -- ID3/MP4 tag reading and writing - metadata_editor.py -- GUI metadata editing widget - config_loader.py -- Config in ~/.config/ - ipod_device.py -- iPod device detection and file management - ipod_nano7_db.py -- Nano 7G SQLite + iTunesCDB + ArtworkDB - ipod_mhbd_writer.py -- Binary iTunesDB writer - hashab.py -- HASHAB checksum generation - hotkeys.py -- Global keyboard shortcut management - library_cache.py -- Local library caching - artwork/ - __init__.py -- Public API - presets.py -- 50+ iPod artwork format definitions - types.py -- ArtworkEntry, EncodedFormatPayload, IthmbLocation - codecs.py -- RGB565/RGB555/UYVY/JPEG encode/decode (numpy) - extractor.py -- Cover extraction from audio files (mutagen) - chunks.py -- ArtworkDB binary parser/writer (MHFD->MHII->MHNI) - writer.py -- ithmb file + ArtworkDB writing - cache.py -- Local JPEG cover cache for player UI -scripts/ - build-appimage.sh -- AppImage builder (PyInstaller + appimagetool) +neo-pod-desktop/ +├── src/ +│ ├── app.py -- Главное окно, плеер (QMediaPlayer), оркестрация вкладок +│ ├── worker.py -- Фоновые потоки (конвертация, передача, синхронизация) +│ ├── audio_converter.py -- FFmpeg конвертация аудио/видео для iPod +│ ├── metadata_handler.py -- Чтение и запись ID3/MP4 тегов, встраивание обложек +│ ├── track_info.py -- TrackInfo dataclass +│ ├── config_loader.py -- Конфигурация в ~/.config/ (configparser) +│ ├── session_store.py -- Состояние сессии плеера (JSON) +│ ├── library_cache.py -- SQLite кэш библиотеки с WAL и ротацией бэкапов +│ ├── playlist_manager.py -- Управление плейлистами (JSON) +│ ├── ipod_device.py -- Детекция, монтирование и передача файлов на iPod +│ ├── ipod_nano7_db.py -- Менеджер БД iPod через iOpenPod (iTunesDB + SQLite) +│ ├── device_monitor.py -- Фоновый мониторинг подключения iPod +│ ├── hotkeys.py -- Настраиваемые горячие клавиши +│ ├── xdg_base.py -- XDG Base Directory пути (~/.config, ~/.local/share, ~/.cache) +│ ├── hashab.py -- HASHAB контрольные суммы +│ ├── ipod_mhbd_writer.py -- Бинарный писатель iTunesDB (mhbd) +│ ├── models/ +│ │ └── __init__.py +│ ├── services/ +│ │ └── itunes_search.py -- iTunes Search API для автозаполнения метаданных +│ ├── artwork/ +│ │ ├── __init__.py -- Публичный API artwork пайплайна +│ │ ├── presets.py -- 50+ форматов artwork для iPod +│ │ ├── types.py -- ArtworkEntry, EncodedFormatPayload, IthmbLocation +│ │ ├── codecs.py -- RGB565/RGB555/UYVY/JPEG кодеки (numpy) +│ │ ├── extractor.py -- Извлечение обложек из аудиофайлов (mutagen) +│ │ ├── chunks.py -- ArtworkDB бинарный парсер/писатель (MHFD→MHII→MHNI) +│ │ ├── writer.py -- Запись ithmb + ArtworkDB +│ │ └── cache.py -- Кэш JPEG обложек для UI плеера +│ └── ui/ +│ ├── library_tab.py -- Вкладка библиотеки (таблица, поиск, фильтры) +│ ├── ipod_tab.py -- Вкладка iPod (устройства, треки, экспорт/удаление) +│ ├── settings_tab.py -- Вкладка настроек (горячие клавиши, поведение) +│ ├── player_header.py -- Виджет плеера (кнопки, слайдер, обложка, время) +│ ├── sidebar_widget.py -- Боковая панель (навигация, плейлисты) +│ ├── metadata_editor.py -- Редактор метаданных (одиночный/batch) +│ ├── splash_overlay.py -- Экран загрузки со сканированием библиотеки +│ └── star_rating.py -- Виджет рейтинга (кликабельные звёзды) +├── scripts/ +│ └── build-appimage.sh -- Сборка AppImage (PyInstaller + appimagetool) +├── tests/ +│ └── test_basic.py +├── requirements.txt +├── setup.py +├── install.sh +└── install.bat ``` -## License +## Ключевые технологии -MIT License +| Технология | Назначение | +|---|---| +| **PyQt6** | Графический интерфейс, QMediaPlayer, сигналы/слоты | +| **iOpenPod** | Генерация iTunesDB + SQLite + ArtworkDB для iPod Nano 6G/7G | +| **FFmpeg** | Конвертация аудио (AAC/MP3) и видео (H.264) | +| **mutagen / eyeD3** | Чтение и запись метаданных (ID3, MP4, FLAC, OGG) | +| **NumPy + Pillow** | Кодирование обложек (RGB565, масштабирование) | +| **SQLite** | Кэш библиотеки, playcounts_log, WAL режим | + +## Архитектура + +Приложение построено на PyQt6 с разделением на UI-слой (пакет `ui/`), бизнес-логику (корневые модули `src/`) и движок генерации баз iPod (iOpenPod и пакет `artwork/`). + +- **app.py** — центральный оркестратор: создаёт плеер (QMediaPlayer + QAudioOutput), управляет вкладками (Library, iPod, Settings) и боковой панелью, обрабатывает hotkeys, сохраняет сессию +- **worker.py** — QThread для фоновых задач с сигналами progress/finished; поддерживает конвертацию, передачу, детекцию, монтирование, удаление, дедупликацию, синк метаданных, создание плейлистов +- **ipod_nano7_db.py** — делегирует генерацию iTunesDB и SQLite баз iOpenPod, управляет artwork пайплайном, мержит play stats, валидирует данные +- **artwork/** — полный пайплайн: extractor → codecs (numpy) → chunks (бинарный парсер) → writer (ithmb + ArtworkDB) +- **library_cache.py** — SQLite база с WAL журналом, автоматической ротацией бэкапов, индексами по content_hash/uuid/artist/album + +## Конфигурация + +- **Конфиг**: `~/.config/neo-pod-desktop/config.ini` +- **Сессия**: `~/.local/share/neo-pod-desktop/session.json` +- **Плейлисты**: `~/.local/share/neo-pod-desktop/playlists.json` +- **Кэш библиотеки**: `~/.local/share/neo-pod-desktop/library_cache.db` +- **Кэш обложек**: `~/.cache/neo-pod-desktop/` + +## Сборка AppImage + +```bash +./scripts/build-appimage.sh +``` + +Требует: Python 3.10+, PyInstaller, appimagetool, FFmpeg (включается в AppImage). + +## Лицензия + +MIT