sacad 2.8.0

Description:

sacad 2.8.0

SACAD
Smart Automatic Cover Art Downloader





SACAD is a multi platform command line tool to download album covers without manual intervention, ideal for integration in scripts, audio players, etc.
SACAD also provides a second command line tool, sacad_r, to scan a music library, read metadata from audio tags, and download missing covers automatically, optionally embedding the image into audio audio files.
Features

Can target specific image size, and find results for high resolution covers
Support JPEG and PNG formats
Customizable output: save image along with the audio files / in a different directory named by artist/album / embed cover in audio files...
Currently support the following cover sources:

Amazon CD (.com, .ca, .cn, .fr, .de, .co.jp and .co.uk variants) & Amazon digital music (removed, too unreliable)
CoverLib (site is dead)
Deezer
Discogs
Google Images (removed, too unreliable)
Last.fm
Itunes


Smart sorting algorithm to select THE best cover for a given query, using several factors: source reliability, image format, image size, image similarity with reference cover, etc.
Automatically crunch images with optipng, oxipng or jpegoptim (can save 30% of filesize without any loss of quality, great for portable players)
Cache search results locally for faster future search
Do everything to avoid getting blocked by the sources: hide user-agent and automatically take care of rate limiting
Automatically convert/resize image if needed
Multiplatform (Windows/Mac/Linux)

SACAD is designed to be robust and be executed in batch of thousands of queries:

HTML parsing is done without regex but with the LXML library, which is faster, and more robust to page changes
When the size of an image reported by a source is not reliable (ie. Google Images), automatically download the first KB of the file to get its real size from the file header
Process several queries simultaneously (using asyncio), to speed up processing
Automatically reuse TCP connections (HTTP Keep-Alive), for better network performance
Automatically retry failed HTTP requests
Music library scan supports all common audio formats (MP3, AAC, Vorbis, FLAC..)
Cover sources page or API changes are quickly detected, thanks to high test coverage, and SACAD is quickly updated accordingly

Installation
SACAD requires Python >= 3.8.
Standalone Windows executable
Windows users can download a standalone binary which does not require Python.
Arch Linux
Arch Linux users can install the sacad AUR package.
From PyPI (with PIP)

If you don't already have it, install pip for Python 3
Install SACAD: pip3 install sacad

From source

If you don't already have it, install setuptools for Python 3
Clone this repository: git clone https://github.com/desbma/sacad
Install SACAD: python3 setup.py install

Optional
Additionally, if you want to benefit from image crunching (lossless recompression to save additional space):

Install oxipng or optipng
Install jpegoptim

On Ubuntu and other Debian derivatives, you can install them with sudo apt-get install optipng jpegoptim.
Note that depending of the speed of your CPU, crunching may significantly slow down processing as it is very CPU intensive (especially with optipng).
Command line usage
Two tools are provided: sacad to search and download one cover, and sacad_r to scan a music library and download all missing covers.
Run sacad -h / sacad_r -h to get full command line reference.
Examples
To download the cover of Master of Puppets from Metallica, to the file AlbumArt.jpg, targetting ~ 600x600 pixel resolution: sacad "metallica" "master of puppets" 600 AlbumArt.jpg.
To download covers for your library with the same parameters as previous example: sacad_r library_directory 600 AlbumArt.jpg.
Limitations

Only supports front covers

Adding cover sources
Adding a new cover source is very easy if you are a Python developer, you need to inherit the CoverSource class and implement the following methods:

getSearchUrl(self, album, artist)
parseResults(self, api_data)
updateHttpHeaders(self, headers) (optional)

See comments in the code for more information.
License
Mozilla Public License Version 2.0