# 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.

## 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`

## Installation

### Dependencies

- Python 3.14+
- FFmpeg (for audio conversion)
- libusb (for USB device access on Linux)

```bash
pip install -r requirements.txt
```

Install FFmpeg:
- **macOS**: `brew install ffmpeg`
- **Linux**: `sudo apt-get install ffmpeg`
- **Windows**: Download from [ffmpeg.org](https://ffmpeg.org/download.html)

## Usage

### GUI Application

```bash
python src/main.py
```

### AppImage (portable)

```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)
```

## License

MIT License