150 lines
10 KiB
Markdown
150 lines
10 KiB
Markdown
# neo-pod-desktop
|
||
|
||
Настольное приложение для управления музыкой на iPod Nano 7G с встроенным iTunes-подобным плеером, конвертацией аудио, полным пайплайном обложек и генерацией iTunesDB/SQLite/ArtworkDB.
|
||
|
||
## Возможности
|
||
|
||
- **Встроенный плеер** — воспроизведение локальной библиотеки через 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 7G, 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
|
||
|
||
## Установка
|
||
|
||
### Зависимости
|
||
|
||
- Python 3.10+
|
||
- FFmpeg (для конвертации аудио)
|
||
- libusb (для доступа к USB на Linux)
|
||
|
||
```bash
|
||
pip install -r requirements.txt
|
||
```
|
||
|
||
Установка FFmpeg:
|
||
- **macOS**: `brew install ffmpeg`
|
||
- **Linux**: `sudo apt-get install ffmpeg`
|
||
- **Windows**: Скачайте с [ffmpeg.org](https://ffmpeg.org/download.html)
|
||
|
||
## Использование
|
||
|
||
### GUI приложение
|
||
|
||
```bash
|
||
python src/app.py
|
||
```
|
||
|
||
### AppImage (портативная версия)
|
||
|
||
```bash
|
||
./neo-pod-desktop-x86_64.AppImage
|
||
```
|
||
|
||
Сборка из исходников:
|
||
|
||
```bash
|
||
./scripts/build-appimage.sh
|
||
```
|
||
|
||
## Структура проекта
|
||
|
||
```
|
||
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
|
||
```
|
||
|
||
## Ключевые технологии
|
||
|
||
| Технология | Назначение |
|
||
|---|---|
|
||
| **PyQt6** | Графический интерфейс, QMediaPlayer, сигналы/слоты |
|
||
| **iOpenPod (vendored)** | Генерация iTunesDB + SQLite + ArtworkDB для iPod Nano 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
|