Update README with current features and project structure
- Cover art pipeline, iTunes-style player, Nano 7G DB - AppImage build, config in ~/.config/, reembed script - Accurate directory structure
This commit is contained in:
Maksim Totmin
parent
59865169e6
commit
803f0c4d9a
93
README.md
93
README.md
@ -1,41 +1,40 @@
|
||||
<!-- # neo-pod-desktop -->
|
||||
# neo-pod-desktop
|
||||
|
||||
Desktop application for downloading, converting, managing and transferring music to iPod Nano devices. Combines YouTube audio extraction, format conversion, metadata management, local library with playback, and direct device transfer while adhering to iPod Nano's technical specifications.
|
||||
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)
|
||||
- Automatic metadata handling (title, artist, album art)
|
||||
- Direct transfer to iPod Nano
|
||||
- Cross-platform support (Windows, macOS, Linux)
|
||||
- **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
|
||||
|
||||
1. Clone this repository:
|
||||
### Dependencies
|
||||
|
||||
```bash
|
||||
git clone https://github.com/yourusername/youtube-to-ipod-nano.git
|
||||
cd youtube-to-ipod-nano
|
||||
```
|
||||
|
||||
1. Install dependencies:
|
||||
- Python 3.14+
|
||||
- FFmpeg (for audio conversion)
|
||||
- libusb (for USB device access on Linux)
|
||||
|
||||
```bash
|
||||
pip install -r requirements.txt
|
||||
```
|
||||
|
||||
1. Install FFmpeg (required for audio conversion):
|
||||
- **macOS**: `brew install ffmpeg`
|
||||
- **Linux**: `sudo apt-get install ffmpeg`
|
||||
- **Windows**: Download from [FFmpeg website](https://ffmpeg.org/download.html)
|
||||
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
|
||||
|
||||
Run the application:
|
||||
|
||||
```bash
|
||||
python src/main.py
|
||||
```
|
||||
@ -46,17 +45,57 @@ python src/main.py
|
||||
python src/cli.py --url "https://www.youtube.com/watch?v=VIDEO_ID" --output-dir "/path/to/ipod"
|
||||
```
|
||||
|
||||
Options:
|
||||
### AppImage (portable)
|
||||
|
||||
- `--url`: YouTube video or playlist URL
|
||||
- `--output-dir`: Output directory (iPod mount point)
|
||||
- `--format`: Audio format (default: m4a)
|
||||
- `--quality`: Audio quality in kbps (default: 256)
|
||||
- `--video`: Enable video download (for compatible iPod models)
|
||||
```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. Please only download content that you have the right to access and use.
|
||||
This tool is intended for personal use only. Users are responsible for complying with YouTube's Terms of Service and copyright laws.
|
||||
|
||||
## License
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user