sacad 1.6.0

Search and download music album covers

SACAD
=====

Smart Automatic Cover Art Downloader
------------------------------------

|Latest Version| |Tests Status| |Coverage| |Supported Python versions|
|License|

SACAD is a multi platform command line tool to download album covers
without manual intervention, ideal for integration in scripts, audio
players, etc.

**Since version 1.6.0, SACAD also provides a new command line tool,
``sacad_r``, to scan a music library, read metadata from audio tags, and
download missing covers automatically.**

Features
--------

- Can target specific image size, and find results for high resolution
covers
- Support JPEG and PNG formats
- Currently support the following cover sources:

- Last.fm
- Google Images
- CoverLib
- Amazon CD (.com, .ca, .cn, .fr, .de, .co.jp and .co.uk variants)
- Amazon digital music

- 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 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
- Use multiple threads or processes automatically when relevant, to
speed up processing
- Automatically reuse TCP connections (HTTP Keep-Alive), for better
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 needs Python >= 3.3**.

From PyPI (with PIP)
~~~~~~~~~~~~~~~~~~~~

1. If you don't already have it, `install
pip <http://www.pip-installer.org/en/latest/installing.html>`__ for
Python 3 (not needed if you are using Python >= 3.4)
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``

Standalone Windows executable
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Windows users can also download a `standalone binary which does not
require Python <https://github.com/desbma/sacad/releases>`__.

Optional
^^^^^^^^

Additionnaly, if you want to benefit from image crunching (lossless
recompression):

- Install `optipng <http://optipng.sourceforge.net/>`__
- Install `jpegoptim <http://freecode.com/projects/jpegoptim>`__

On Ubuntu and other Debian derivatives, you can install both 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 for PNG files).

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/>`__

.. |Latest Version| image:: https://img.shields.io/pypi/v/sacad.svg?style=flat
:target: https://pypi.python.org/pypi/sacad/
.. |Tests Status| image:: https://img.shields.io/travis/desbma/sacad/master.svg?label=tests&style=flat
:target: https://travis-ci.org/desbma/sacad
.. |Coverage| image:: https://img.shields.io/coveralls/desbma/sacad/master.svg?style=flat
:target: https://coveralls.io/r/desbma/sacad?branch=master
.. |Supported Python versions| image:: https://img.shields.io/pypi/pyversions/sacad.svg?style=flat
:target: https://pypi.python.org/pypi/sacad/
.. |License| image:: https://img.shields.io/github/license/desbma/sacad.svg?style=flat
:target: https://pypi.python.org/pypi/sacad/