# neo-pod-desktop

Desktop application for downloading, converting, managing and transferring music to iPod Nano 7G. Includes YouTube audio extraction, format conversion, metadata management, local library with playback, cover art pipeline, and full iTunesDB/ArtworkDB generation.

## Features

- **Download** audio from YouTube videos/playlists
- **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 (60×60), 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
```

### Command Line Interface

```bash
python src/cli.py --url "https://www.youtube.com/watch?v=VIDEO_ID" --output-dir "/path/to/ipod"
```

### 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)
  cli.py                   — CLI interface
  youtube_downloader.py    — YouTube audio downloader
  audio_converter.py       — FFmpeg audio conversion
  metadata_handler.py      — ID3/MP4 tag reading and writing
  config_loader.py         — Config in ~/.config/
  ipod_device.py           — iPod device detection and file management
  ipod_nano7_db.py         — Nano 7G SQLite + iTunesCDB + ArtworkDB
  hashab.py                — HASHAB checksum generation
  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)
```

## Cover Art Re-embed

One-time script to restore cover art in already-converted files:

```bash
python /tmp/reembed_covers.py /path/to/source_music /path/to/output_dir
```

Matches output files to source files by artist+album, detects embedded covers and separate `cover.jpg`/`folder.jpg` files.

## Legal Disclaimer

This tool is intended for personal use only. Users are responsible for complying with YouTube's Terms of Service and copyright laws.

## License

MIT License