# SACAD
## Smart Automatic Cover Art Downloader
[](https://pypi.python.org/pypi/sacad/)
[](https://aur.archlinux.org/packages/sacad/)
[](https://github.com/desbma/sacad/actions)
[](https://coveralls.io/github/desbma/sacad?branch=master)
[](https://github.com/desbma/sacad)
[](https://pypi.python.org/pypi/sacad/)
[](https://github.com/desbma/sacad/blob/master/LICENSE)
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
- ~~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](https://docs.python.org/3/library/asyncio.html)), 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](https://www.python.org/downloads/) >= 3.7.
### Standalone Windows executable
Windows users can download a [standalone binary](https://github.com/desbma/sacad/releases/latest) which does not require Python.
### Arch Linux
Arch Linux users can install the [sacad](https://aur.archlinux.org/packages/sacad/) AUR package.
### From PyPI (with PIP)
1. If you don't already have it, [install pip](https://pip.pypa.io/en/stable/installing/) for Python 3
2. Install SACAD: `pip3 install sacad`
### From source
1. If you don't already have it, [install setuptools](https://pypi.python.org/pypi/setuptools#installation-instructions) for Python 3
2. Clone this repository: `git clone https://github.com/desbma/sacad`
3. Install SACAD: `python3 setup.py install`
#### Optional
Additionally, if you want to benefit from image crunching (lossless recompression to save additional space):
- Install [oxipng](https://github.com/shssoichiro/oxipng) or [optipng](http://optipng.sourceforge.net/)
- Install [jpegoptim](http://freecode.com/projects/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](https://www.mozilla.org/MPL/2.0/)
Raw data
{
"_id": null,
"home_page": "https://github.com/desbma/sacad",
"name": "sacad",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "download,album,cover,art,albumart,music",
"author": "desbma",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/4f/86/56378a6d46f64067d93cae9b585a1df86bdd371672a6658e24c6554c651a/sacad-2.7.5.tar.gz",
"platform": null,
"description": "# SACAD\n\n## Smart Automatic Cover Art Downloader\n\n[](https://pypi.python.org/pypi/sacad/)\n[](https://aur.archlinux.org/packages/sacad/)\n[](https://github.com/desbma/sacad/actions)\n[](https://coveralls.io/github/desbma/sacad?branch=master)\n[](https://github.com/desbma/sacad)\n[](https://pypi.python.org/pypi/sacad/)\n[](https://github.com/desbma/sacad/blob/master/LICENSE)\n\nSACAD is a multi platform command line tool to download album covers without manual intervention, ideal for integration in scripts, audio players, etc.\n\nSACAD 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.\n\n## Features\n\n- Can target specific image size, and find results for high resolution covers\n- Support JPEG and PNG formats\n- Customizable output: save image along with the audio files / in a different directory named by artist/album / embed cover in audio files...\n- Currently support the following cover sources:\n - Amazon CD (.com, .ca, .cn, .fr, .de, .co.jp and .co.uk variants)\n - Amazon digital music\n - ~~CoverLib~~ (site is dead)\n - Deezer\n - Discogs\n - ~~Google Images~~ (removed, too unreliable)\n - Last.fm\n - Itunes\n- 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.\n- Automatically crunch images with optipng, oxipng or jpegoptim (can save 30% of filesize without any loss of quality, great for portable players)\n- Cache search results locally for faster future search\n- Do everything to avoid getting blocked by the sources: hide user-agent and automatically take care of rate limiting\n- Automatically convert/resize image if needed\n- Multiplatform (Windows/Mac/Linux)\n\nSACAD is designed to be robust and be executed in batch of thousands of queries:\n\n- HTML parsing is done without regex but with the LXML library, which is faster, and more robust to page changes\n- 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\n- Process several queries simultaneously (using [asyncio](https://docs.python.org/3/library/asyncio.html)), to speed up processing\n- Automatically reuse TCP connections (HTTP Keep-Alive), for better network performance\n- Automatically retry failed HTTP requests\n- Music library scan supports all common audio formats (MP3, AAC, Vorbis, FLAC..)\n- Cover sources page or API changes are quickly detected, thanks to high test coverage, and SACAD is quickly updated accordingly\n\n## Installation\n\nSACAD requires [Python](https://www.python.org/downloads/) >= 3.7.\n\n### Standalone Windows executable\n\nWindows users can download a [standalone binary](https://github.com/desbma/sacad/releases/latest) which does not require Python.\n\n### Arch Linux\n\nArch Linux users can install the [sacad](https://aur.archlinux.org/packages/sacad/) AUR package.\n\n### From PyPI (with PIP)\n\n1. If you don't already have it, [install pip](https://pip.pypa.io/en/stable/installing/) for Python 3\n2. Install SACAD: `pip3 install sacad`\n\n### From source\n\n1. If you don't already have it, [install setuptools](https://pypi.python.org/pypi/setuptools#installation-instructions) for Python 3\n2. Clone this repository: `git clone https://github.com/desbma/sacad`\n3. Install SACAD: `python3 setup.py install`\n\n#### Optional\n\nAdditionally, if you want to benefit from image crunching (lossless recompression to save additional space):\n\n- Install [oxipng](https://github.com/shssoichiro/oxipng) or [optipng](http://optipng.sourceforge.net/)\n- Install [jpegoptim](http://freecode.com/projects/jpegoptim)\n\nOn Ubuntu and other Debian derivatives, you can install them with `sudo apt-get install optipng jpegoptim`.\n\nNote that depending of the speed of your CPU, crunching may significantly slow down processing as it is very CPU intensive (especially with optipng).\n\n## Command line usage\n\nTwo tools are provided: `sacad` to search and download one cover, and `sacad_r` to scan a music library and download all missing covers.\n\nRun `sacad -h` / `sacad_r -h` to get full command line reference.\n\n### Examples\n\nTo 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`.\n\nTo download covers for your library with the same parameters as previous example: `sacad_r library_directory 600 AlbumArt.jpg`.\n\n## Limitations\n\n- Only supports front covers\n\n## Adding cover sources\n\nAdding 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:\n\n- `getSearchUrl(self, album, artist)`\n- `parseResults(self, api_data)`\n- `updateHttpHeaders(self, headers)` (optional)\n\nSee comments in the code for more information.\n\n## License\n\n[Mozilla Public License Version 2.0](https://www.mozilla.org/MPL/2.0/)\n",
"bugtrack_url": null,
"license": "",
"summary": "Search and download music album covers",
"version": "2.7.5",
"project_urls": {
"Download": "https://github.com/desbma/sacad/archive/2.7.5.tar.gz",
"Homepage": "https://github.com/desbma/sacad"
},
"split_keywords": [
"download",
"album",
"cover",
"art",
"albumart",
"music"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "4f8656378a6d46f64067d93cae9b585a1df86bdd371672a6658e24c6554c651a",
"md5": "c871de900ef0ab5eb413c9a1ec4616f8",
"sha256": "6493dcc4a7341bc57bc7d9f2cca5da5e97cda4c077fea4685f477895f0594c56"
},
"downloads": -1,
"filename": "sacad-2.7.5.tar.gz",
"has_sig": false,
"md5_digest": "c871de900ef0ab5eb413c9a1ec4616f8",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 40257,
"upload_time": "2023-06-13T20:55:24",
"upload_time_iso_8601": "2023-06-13T20:55:24.748377Z",
"url": "https://files.pythonhosted.org/packages/4f/86/56378a6d46f64067d93cae9b585a1df86bdd371672a6658e24c6554c651a/sacad-2.7.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-06-13 20:55:24",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "desbma",
"github_project": "sacad",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "sacad"
}
JSON
