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
This commit is contained in:
Maksim Totmin
parent
54cd87654f
commit
8317ad1fe4
163
README.md
163
README.md
@ -1,84 +1,149 @@
|
|||||||
# neo-pod-desktop
|
# 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
|
- **Встроенный плеер** — воспроизведение локальной библиотеки через QMediaPlayer, отображение обложек альбомов (60x60), перемотка, громкость, повтор (all/one), shuffle
|
||||||
- **Metadata** handling -- title, artist, album, track number, genre, embedded cover art
|
- **Конвертация аудио** — FFmpeg конвертация в AAC/M4A (libfdk_aac с AAC-LC профилем, 160 kbps) и MP3 (libmp3lame); конвертация видео для iPod (H.264, 640x480)
|
||||||
- **Cover art pipeline** -- extract from audio files (APIC/covr/FLAC pictures), encode to iPod Nano 7G formats (RGB565), write ArtworkDB + ithmb
|
- **Пайплайн ArtworkDB** — извлечение обложек из аудиофайлов (APIC/covr/FLAC pictures), кодирование в iPod-нативные форматы (RGB565, RGB555, UYVY, JPEG), запись ithmb + ArtworkDB (MHFD→MHII→MHNI структуры)
|
||||||
- **iTunes-style player** -- play local library with cover art display (60x60), seek, volume
|
- **Генерация баз iPod** — полная регенерация iTunesDB (бинарный mhbd) и SQLite баз для Nano 6G/7G через iOpenPod, cross-reference валидация db_pid
|
||||||
- **iPod Nano 7G database** -- full iTunesCDB sync, SQLite management, Locations.itdb with HASHAB checksums
|
- **Синхронизация статистики** — двухсторонняя синхронизация play count, rating, skip count, last played между локальным кэшем (SQLite) и iPod; автосинк при подключении; validation gate против потери данных
|
||||||
- **Library management** -- sortable table, source/ready track separation, bulk transfer
|
- **Локальная библиотека** — сортируемая таблица с поддержкой drag-and-drop, фильтрация по альбомам/плейлистам, поиск, разделение на source-треки (FLAC/WAV) и готовые (MP3/M4A)
|
||||||
- **Portable AppImage** -- `scripts/build-appimage.sh` builds standalone x86_64 AppImage
|
- **Плейлисты** — создание, переименование, удаление, drag-and-drop треков; перенос плейлистов на iPod с двухпроходным сопоставлением (content hash → metadata fallback)
|
||||||
- **Config** stored in `~/.config/neo-pod-desktop/config.ini`
|
- **Редактор метаданных** — редактирование тегов и обложек для 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+
|
- Python 3.10+
|
||||||
- FFmpeg (for audio conversion)
|
- FFmpeg (для конвертации аудио)
|
||||||
- libusb (for USB device access on Linux)
|
- libusb (для доступа к USB на Linux)
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
pip install -r requirements.txt
|
pip install -r requirements.txt
|
||||||
```
|
```
|
||||||
|
|
||||||
Install FFmpeg:
|
Установка FFmpeg:
|
||||||
- **macOS**: `brew install ffmpeg`
|
- **macOS**: `brew install ffmpeg`
|
||||||
- **Linux**: `sudo apt-get 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
|
```bash
|
||||||
python src/main.py
|
python src/app.py
|
||||||
```
|
```
|
||||||
|
|
||||||
### AppImage (portable)
|
### AppImage (портативная версия)
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
./neo-pod-desktop-x86_64.AppImage
|
./neo-pod-desktop-x86_64.AppImage
|
||||||
```
|
```
|
||||||
|
|
||||||
Build from source:
|
Сборка из исходников:
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
./scripts/build-appimage.sh
|
./scripts/build-appimage.sh
|
||||||
```
|
```
|
||||||
|
|
||||||
## Project Structure
|
## Структура проекта
|
||||||
|
|
||||||
```
|
```
|
||||||
src/
|
neo-pod-desktop/
|
||||||
main.py -- GUI application (PyQt6)
|
├── src/
|
||||||
track_info.py -- TrackInfo data class
|
│ ├── app.py -- Главное окно, плеер (QMediaPlayer), оркестрация вкладок
|
||||||
audio_converter.py -- FFmpeg audio conversion
|
│ ├── worker.py -- Фоновые потоки (конвертация, передача, синхронизация)
|
||||||
metadata_handler.py -- ID3/MP4 tag reading and writing
|
│ ├── audio_converter.py -- FFmpeg конвертация аудио/видео для iPod
|
||||||
metadata_editor.py -- GUI metadata editing widget
|
│ ├── metadata_handler.py -- Чтение и запись ID3/MP4 тегов, встраивание обложек
|
||||||
config_loader.py -- Config in ~/.config/
|
│ ├── track_info.py -- TrackInfo dataclass
|
||||||
ipod_device.py -- iPod device detection and file management
|
│ ├── config_loader.py -- Конфигурация в ~/.config/ (configparser)
|
||||||
ipod_nano7_db.py -- Nano 7G SQLite + iTunesCDB + ArtworkDB
|
│ ├── session_store.py -- Состояние сессии плеера (JSON)
|
||||||
ipod_mhbd_writer.py -- Binary iTunesDB writer
|
│ ├── library_cache.py -- SQLite кэш библиотеки с WAL и ротацией бэкапов
|
||||||
hashab.py -- HASHAB checksum generation
|
│ ├── playlist_manager.py -- Управление плейлистами (JSON)
|
||||||
hotkeys.py -- Global keyboard shortcut management
|
│ ├── ipod_device.py -- Детекция, монтирование и передача файлов на iPod
|
||||||
library_cache.py -- Local library caching
|
│ ├── ipod_nano7_db.py -- Менеджер БД iPod через iOpenPod (iTunesDB + SQLite)
|
||||||
artwork/
|
│ ├── device_monitor.py -- Фоновый мониторинг подключения iPod
|
||||||
__init__.py -- Public API
|
│ ├── hotkeys.py -- Настраиваемые горячие клавиши
|
||||||
presets.py -- 50+ iPod artwork format definitions
|
│ ├── xdg_base.py -- XDG Base Directory пути (~/.config, ~/.local/share, ~/.cache)
|
||||||
types.py -- ArtworkEntry, EncodedFormatPayload, IthmbLocation
|
│ ├── hashab.py -- HASHAB контрольные суммы
|
||||||
codecs.py -- RGB565/RGB555/UYVY/JPEG encode/decode (numpy)
|
│ ├── ipod_mhbd_writer.py -- Бинарный писатель iTunesDB (mhbd)
|
||||||
extractor.py -- Cover extraction from audio files (mutagen)
|
│ ├── models/
|
||||||
chunks.py -- ArtworkDB binary parser/writer (MHFD->MHII->MHNI)
|
│ │ └── __init__.py
|
||||||
writer.py -- ithmb file + ArtworkDB writing
|
│ ├── services/
|
||||||
cache.py -- Local JPEG cover cache for player UI
|
│ │ └── itunes_search.py -- iTunes Search API для автозаполнения метаданных
|
||||||
scripts/
|
│ ├── artwork/
|
||||||
build-appimage.sh -- AppImage builder (PyInstaller + appimagetool)
|
│ │ ├── __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
|
||||||
|
|||||||
Loading…
x
Reference in New Issue
Block a user