# 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