aevum

created with Claude

aevum (n.): an era, eternity, a timeless age - the span between fleeting time (tempus) and infinite time. A fixed capsule that keeps one moment alive forever.

Search YouTube (Music), pick the right result, download it as 320k MP3, tag it (title, artists, album, album artist, date, track/total, embedded cover), rename it Artist, ft. Other - Song.mp3, and optionally rsync it to your server or iPod.

Requirements

gum, yt-dlp (recent), ffmpeg (with ffprobe), rsync (only for sending), Python 3.9+. No Python packages (no mutagen/Pillow needed).

Install

pipx install .          # or: pip install -e .
aevum --help
# or without installing:  python -m aevum

Configure sending (optional)

Copy config.example.json to ~/.config/aevum/config.json and edit it. Nothing personal is hard-coded; with no config the server/iPod options simply say "not configured".

Use

aevum                                   # interactive menu
aevum -t album "maroon 5 songs about jane"
aevum send                              # send last download / browse for music files
aevum send song.mp3 --to ipod

Only files are ever sent, never folders.

iPod-safe cover art

Every download is tagged as ID3v2.3 with exactly one front cover: a standard baseline JPEG, at most 640px, embedded as Cover / Cover (front) (what ffprobe shows as title=Cover, comment=Cover (front)). This is done for all files, not only for the iPod, so one copy works everywhere (iPod, Navidrome, phones). To repair mp3s you already have:

aevum fix-art ~/Music/"Maroon 5 - Songs About Jane"     # folders are searched recursively

It keeps your other tags, keeps the front cover if there are several pictures, and edits in place. Size/format live at the top of aevum/tagging.py (COVER_MAX_PX, ID3_VERSION).

Layout

Core modules never print or prompt, so a web app or GUI can reuse them: models, text, net, youtube, metadata, tagging, library, transfer. cli is the only module that talks to gum.

Tests

python -m unittest discover -v