a36312c9d7
Root cause: QThread C++ destructor ran while underlying OS thread was still terminating. The pattern of checking isRunning() and using short timeouts (wait(3000/5000)) left a window where the Python reference was dropped and Shiboken destroyed the C++ object before the thread fully exited. Fixes: - Remove all self.finished.connect(self.deleteLater) — unsafe, deleteLater from within run() or from worker thread races with thread termination - _cleanup_worker: always call wait() (no timeout) before nulling the Python reference — guarantees OS thread is fully dead - Add _is_worker_running() helper with try/except RuntimeError guard to safely check stale C++ objects - DeviceMonitor._poll/stop/wait: use wait() with no timeout - closeEvent: guard isRunning() with try/except RuntimeError
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.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
AppImage (portable)
./neo-pod-desktop-x86_64.AppImage
Build from source:
./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