Metadata-Version: 1.1
Name: sacad
Version: 2.1.5
Summary: Search and download music album covers
Home-page: https://github.com/desbma/sacad
Author: desbma
Author-email: UNKNOWN
License: UNKNOWN
Download-URL: https://github.com/desbma/sacad/archive/2.1.5.tar.gz
Description: SACAD
        =====
        
        Smart Automatic Cover Art Downloader
        ------------------------------------
        
        |PyPI version| |AUR version| |Tests status| |Coverage| |Lines of code|
        |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, 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, optionally embedding the image
        into audio audio files (since version 1.9).**
        
        **Since version 2.0, SACAD has been rewritten to use the
        `asyncio <https://docs.python.org/3/library/asyncio.html>`__ framework,
        which typically results in ~40% faster processing for ``sacad`` and
        600-700% faster (yes, 6-7x faster!) for ``sacad_r``.**
        
        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
           -  [STRIKEOUT:CoverLib] (site is down)
           -  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
        -  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
           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.5.
        
        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
        ^^^^^^^^
        
        Additionnaly, if you want to benefit from image crunching (lossless
        recompression to save additional space):
        
        -  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/>`__
        
        .. |PyPI version| image:: https://img.shields.io/pypi/v/sacad.svg?style=flat
           :target: https://pypi.python.org/pypi/sacad/
        .. |AUR version| image:: https://img.shields.io/aur/version/sacad.svg?style=flat
           :target: https://aur.archlinux.org/packages/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/github/desbma/sacad?branch=master
        .. |Lines of code| image:: https://tokei.rs/b1/github/desbma/sacad
           :target: https://github.com/desbma/sacad
        .. |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://github.com/desbma/sacad/blob/master/LICENSE
        
Keywords: download,album,cover,art,albumart,music
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: Mozilla Public License 2.0 (MPL 2.0)
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Multimedia :: Graphics
Classifier: Topic :: Utilities
