4f7bd2709c
main.py imports our local ipod_device first, which caches it in sys.modules. When ipod_nano7_db later tried 'from ipod_device import ChecksumType', Python returned the cached local module (which lacks ChecksumType), causing 'ipod_nano7_db not available' and falling back to simple file copy into wrong /Music/ directory. Fix: replace top-level iOpenPod imports with lazy _import_iop() helper that temporarily evicts local ipod_device from sys.modules, adds /tmp/iOpenPod to sys.path, loads the iOpenPod module, then restores the path. All iOpenPod imports now happen inside method bodies only.
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.shbuilds 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)
pip install -r requirements.txt
Install FFmpeg:
- macOS:
brew install ffmpeg - Linux:
sudo apt-get install ffmpeg - Windows: Download from ffmpeg.org
Usage
GUI Application
python src/main.py
Command Line Interface
python src/cli.py --url "https://www.youtube.com/watch?v=VIDEO_ID" --output-dir "/path/to/ipod"
AppImage (portable)
./neo-pod-desktop-x86_64.AppImage
Build from source:
./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:
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