# 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://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:
- Deezer
- Discogs
- 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.10.
### 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": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "download, album, cover, art, albumart, music",
"author": "desbma",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/b9/ca/2f466cfdbfaecca099e64ccae7930aaf0c2510f88b75af0d6aa5bedd8a1a/sacad-2.8.2.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://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 - Deezer\n - Discogs\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.10.\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": null,
"summary": "Search and download music album covers",
"version": "2.8.2",
"project_urls": {
"Download": "https://github.com/desbma/sacad/archive/2.8.2.tar.gz",
"Homepage": "https://github.com/desbma/sacad"
},
"split_keywords": [
"download",
" album",
" cover",
" art",
" albumart",
" music"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "b9ca2f466cfdbfaecca099e64ccae7930aaf0c2510f88b75af0d6aa5bedd8a1a",
"md5": "a7b70f5df3e5b90bb150a93cb54fe900",
"sha256": "72b533f09c6cbdc7d9509ad2e1885f23e2ecc05f9e89d853e1c6fa78eb511ab8"
},
"downloads": -1,
"filename": "sacad-2.8.2.tar.gz",
"has_sig": false,
"md5_digest": "a7b70f5df3e5b90bb150a93cb54fe900",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 37184,
"upload_time": "2025-10-21T14:44:28",
"upload_time_iso_8601": "2025-10-21T14:44:28.611649Z",
"url": "https://files.pythonhosted.org/packages/b9/ca/2f466cfdbfaecca099e64ccae7930aaf0c2510f88b75af0d6aa5bedd8a1a/sacad-2.8.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-21 14:44:28",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "desbma",
"github_project": "sacad",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "aiohttp",
"specs": [
[
">=",
"3.6"
]
]
},
{
"name": "appdirs",
"specs": [
[
">=",
"1.4.0"
]
]
},
{
"name": "bitarray",
"specs": [
[
">=",
"2.0.0"
]
]
},
{
"name": "cssselect",
"specs": [
[
">=",
"1.1.0"
]
]
},
{
"name": "lxml",
"specs": [
[
">=",
"4.0.0"
]
]
},
{
"name": "mutagen",
"specs": [
[
">=",
"1.31"
]
]
},
{
"name": "pillow",
"specs": [
[
">=",
"8.0.0"
]
]
},
{
"name": "tqdm",
"specs": [
[
">=",
"4.28.1"
]
]
},
{
"name": "unidecode",
"specs": [
[
">=",
"1.1.1"
]
]
},
{
"name": "web_cache",
"specs": [
[
">=",
"1.1.0"
]
]
}
],
"lcname": "sacad"
}
JSON
