{
"info": {
"author": "James Thomas Moon",
"author_email": "",
"bugtrack_url": null,
"classifiers": [
"Development Status :: 3 - Alpha",
"Environment :: Console",
"License :: OSI Approved :: Apache Software License",
"Natural Language :: English",
"Operating System :: OS Independent",
"Programming Language :: Python :: 3.7",
"Topic :: Multimedia :: Sound/Audio"
],
"description": "CoverLovin2\n===========\n\n[](https://travis-ci.com/jtmoon79/coverlovin2)\n[](https://circleci.com/gh/jtmoon79/coverlovin2)\n[](https://codecov.io/gh/jtmoon79/coverlovin2)\n[](https://coveralls.io/github/jtmoon79/coverlovin2?branch=master)\n[](https://badge.fury.io/py/CoverLovin2)\n[](https://pypi.org/pypi/coverlovin2/)\n[](https://requires.io/github/jtmoon79/coverlovin2/requirements/?branch=master)\n[](https://opensource.org/licenses/Apache-2.0)\n\n*CoverLovin2* (Cover Loving, too!), Python name *coverlovin2*, is a Python\nscript for downloading album cover art images, either via local searching and\ncopying, or via downloading from various online services.\nA common use-case is creating \"`cover.jpg`\" files for a large collection of\nripped Compact Disc albums.\n\ncoverlovin2 can only be run by Python version 3.7 (or greater).\n\n# Table of Contents\n\n* [Script Usage](#script-usage)\n* [Installation](#installation)\n* [Development](#development)\n* [Other Miscellaneous Notes](#other-miscellaneous-notes)\n * [Issues\u203c \ud83d\udc1b \ud83d\udc35](#issues---)\n * [run phases](#run-phases)\n\nScript Usage\n------------\n\nTo see what it will do without changing any files\n\n coverlovin2 -s- --test /path/to/music/library\n\nThe verbose `--help` message\n\n```Text\nusage: coverlovin2.py [-h] [-n IMAGE_NAME] [-i {jpg,png,gif}] [-o] [-s*] [-s-]\n [-sl] [-se] [-sm] [-sg] [-sgz {small,medium,large}]\n [--sgid GID] [--sgkey GKEY] [-v] [-r REFERER] [-d]\n [--test]\n DIRS [DIRS ...]\n\nThis Python-based program is for automating downloading album cover art images.\nA common use-case is creating a \"cover.jpg\" file for a collection of ripped\nCompact Disc albums.\n\nGiven a list of directories, DIRS, recursively identify \"album\" directories.\n\"Album\" directories have audio files, e.g. files with extensions like .mp3 or\n.flac. For each \"album\" directory, attempt to determine the Artist and Album.\nThen find an album cover image file using the requested --search providers. If\nan album cover image file is found then write it to IMAGE_NAME.IMAGE_TYPE within\neach \"album\" directory.\n\nAudio files supported are .mp3, .m4a, .mp4, .flac, .ogg, .wma, .asf.\n\noptional arguments:\n -h, --help show this help message and exit\n\nRequired Arguments:\n DIRS directories to scan for audio files (Required)\n\nRecommended:\n -n IMAGE_NAME, --image-name IMAGE_NAME\n cover image file name IMAGE_NAME. This is the file\n name that will be created within passed DIRS. This\n will be appended with the preferred image TYPE, e.g.\n \"jpg\", \"png\", etc. (default: \"cover\")\n -i {jpg,png,gif}, --image-type {jpg,png,gif}\n image format IMAGE_TYPE (default: \"jpg\")\n -o, --overwrite overwrite any previous file of the same file\n IMAGE_NAME and IMAGE_TYPE (default: False)\n\nSearch all:\n -s*, --search-all Search for album cover images using all methods and\n services\n -s-, --search-all-no-init\n Search for album cover images using all methods and\n services that do not require user initialization (e.g.\n no Google CSE).\n\nSearch the local directory for likely album cover images:\n -sl, --search-likely-cover\n For any directory with audio media files but no file\n \"IMAGE_NAME.IMAGE_TYPE\", search the directory for\n files that are likely album cover images. For example,\n given options: --name \"cover\" --type \"jpg\", and a\n directory of .mp3 files with a file \"album.jpg\", it is\n reasonable to guess \"album.jpg\" is a an album cover\n image file. So copy file \"album.jpg\" to \"cover.jpg\" .\n This will skip an internet image lookup and download\n and could be a more reliable way to retrieve the\n correct album cover image.\n\nSearch the local directory for an embedded album cover image:\n -se, --search-embedded\n Search audio media files for embedded images. If\n found, attempt to extract the embedded image.\n\nSearch Musicbrainz NGS webservice:\n -sm, --search-musicbrainz\n Search for album cover images using musicbrainz NGS\n webservice. MusicBrainz lookup is the most reliable\n search method.\n\nSearch Google Custom Search Engine (CSE):\n -sg, --search-googlecse\n Search for album cover images using Google CSE. Using\n the Google CSE requires an Engine ID and API Key.\n Google CSE reliability entirely depends upon the added\n \"Sites to search\". The end of this help message has\n more advice around using Google CSE.\n -sgz {small,medium,large}, --sgsize {small,medium,large}\n Google CSE optional image file size (default: \"large\")\n --sgid GID Google CSE ID (URL parameter \"cx\") typically looks\n like \"009494817879853929660:efj39xwwkng\". REQUIRED to\n use Google CSE.\n --sgkey GKEY Google CSE API Key (URL parameter \"key\") typically\n looks like \"KVEIA49cnkwoaaKZKGX_OSIxhatybxc9kd59Dst\".\n REQUIRED to use Google CSE.\n\nDebugging and Miscellanea:\n -v, --version show program's version number and exit\n -r REFERER, --referer REFERER\n Referer url used in HTTP GET requests (default:\n \"https://github.com/jtmoon79/coverlovin2\")\n -d, --debug Print debugging messages\n --test Only test, do not write any files\n\nThis program attempts to create album cover image files for the passed DIRS. It\ndoes this several ways, searching for album cover image files already present in\nthe directory (-sl). If not found, it attempts to figure out the Artist and\nAlbum for that directory then searches online services for an album cover image\n(-sm or -sg).\n\nDirectories are searched recursively. Any directory that contains one or more\nwith file name extension .mp3 or .m4a or .mp4 or .flac or .ogg or .wma or .asf\nis presumed to be an album directory. Given a directory of such files, file\ncontents will be read for the Artist name and Album name using embedded audio\ntags (ID3, Windows Media, etc.). If no embedded media tags are present then a\nreasonable guess will be made about the Artist and Album based on the directory\nname; specifically this will try to match a directory name with a pattern like\n\"Artist - Year - Album\" or \"Artist - Album\".\nFrom there, online search services are used to search for the required album\ncover image. If found, it is written to the album directory to file name\nIMAGE_NAME.IMAGE_TYPE (-n \u2026 -i \u2026).\n\nIf option --search-googlecse is chosen then you must create your Google Custom\nSearch Engine (CSE). This can be setup at https://cse.google.com/cse/all . It\ntakes about 5 minutes. This is where your own values for --sgid and --sgkey can\nbe created. --sgid is \"Search engine ID\" (URI parameter \"cx\") and --sgkey is\nunder the \"Custom Search JSON API\" from which you can generate an API Key (URI\nparameter \"key\"). A key can be generated at\nhttps://console.developers.google.com/apis/credentials.\nGoogle CSE settings must have \"Image search\" as \"ON\" and \"Search the entire\nweb\" as \"OFF\".\n\nPyPi project: https://pypi.org/project/CoverLovin2/\nSource code: https://github.com/jtmoon79/coverlovin2\n\nInspired by the program coverlovin.\n```\n\nInstallation\n------------\n\n* Using `pip` from pypi:\n\n pip install coverlovin2\n\n* Using `pip` from source:\n\n pip install mutagen musicbrainzngs Pillow\n pip install https://github.com/jtmoon79/coverlovin2/archive/master.zip\n\n*coverlovin2* depends on non-standard libraries [mutagen](https://pypi.org/project/mutagen/),\n[musicbrainzngs](https://pypi.org/project/musicbrainzngs/), and [Pillow](https://pypi.org/project/Pillow/).\n\nDevelopment\n-----------\n\nInstall `pipenv`.\n\nClone the repository:\n\n git clone git@github.com:jtmoon79/coverlovin2.git\n\nStart the Python virtual environment and install the dependencies:\n\n cd coverlovin2\n pipenv --python 3.7 shell\n pipenv install --dev\n\nThis will install more non-standard libraries. See the [Pipfile](./Pipfile).\n\nOther Miscellaneous Notes\n-------------------------\n\ncoverlovin2 is inspired by [coverlovin](https://github.com/amorphic/coverlovin).\n\n_Sonos_ systems will use file `folder.jpg` for album cover art (if available).\n\n_Winamp_ will use file `cover.jpg` for album cover art (if available).\n\ncoverlovin2 is a practice project for sake of the author catching up to changes\nin the Python Universe and the github Universe.
\nSome things the author explored:\n- project badges (are fun _and useful_)!\n- online services\n - CI Services\n - [Travis CI](https://travis-ci.com/jtmoon79/coverlovin2)\n - [Circle CI](https://circleci.com/gh/jtmoon79/coverlovin2)\n - [codecov.io](https://codecov.io/gh/jtmoon79/coverlovin2)\n - [Requires.io](https://requires.io/github/jtmoon79/coverlovin2)\n - \u2639 landscape.io ([had too many problems](https://github.com/landscapeio/landscape-issues/issues))\n - package distribution service [pypi](https://pypi.org/project/CoverLovin2/)\n- [pytests](./coverlovin2/test)!\n - pytest [code coverage](https://pypi.org/project/pytest-cov/)!\n- type-hinting\u203c
\ncoverlovin2 is very type-hinted code and could be even more so. The author\nthinks type-hinting is a good idea but it still needs improvement. In it's\ncurrent form in Python 3.7, it feels clumsy to write and to grok. Also, PyCharm\nand mypy seem to catch different type-hint warnings.\n - mypy (and [bugs](https://github.com/python/mypy/issues/6476)? \u2639)\n- Python 3.7 classes and programming (like `SimpleQueue` and `namedtuple`)\n - virtual environment manager `pipenv`.\n- printing odd UTF-8 characters (for example, `\\uFF5B`, `\uff5b`) and coercing UTF8\nmode (within a context without UTF8 support; MinGW bash on Windows)\n\n#### Issues\u203c \ud83d\udc1b \ud83d\udc35\n\nOther projects Bug Issues \ud83d\udc1b and Feature Issues \ud83d\udc35 the author created in the\ncourse of writing this application:\n\n\ud83d\udc35 [pypa/pipenv #3505](https://github.com/pypa/pipenv/issues/3505)\n\n\ud83d\udc1b [pypa/pipenv #3521](https://github.com/pypa/pipenv/issues/3521)\n\n\ud83d\udc1b [pypa/pipenv #3523](https://github.com/pypa/pipenv/issues/3523)\n\n\ud83d\udc1b [pypa/pipenv #3529](https://github.com/pypa/pipenv/issues/3529)\n\n\ud83d\udc1b [pypa/pipenv #3573](https://github.com/pypa/pipenv/issues/3573)\n\n\ud83d\udc1b [python/mypy #6476](https://github.com/python/mypy/issues/6476)\n\n\ud83d\udc1b [python/mypy #6473](https://github.com/python/mypy/issues/6473)\n\n\ud83d\udc1b [ant-druha/PowerShell #16](https://github.com/ant-druha/PowerShell/issues/16)\n\n#### run phases\n\ncoverlovin2 runs in a few phases:\n\n1. recursively search passed directory paths for \"album\" directories. An \"album\"\ndirectory merely holds audio files of type `.mp3`, `.m4a`, `.mp4`, `.flac`,\n`.ogg`, `.wma`, or `.asf`. (see [`coverlovin2/coverlovin2.py::AUDIO_TYPES`](./coverlovin2/coverlovin2.py)).\n2. employ a few techniques for determining the artist and album for that\ndirectory. The most reliable technique is to read available embedded audio tags\nwithin the directory. (see [`coverlovin2/coverlovin2.py::process_dir`](./coverlovin2/coverlovin2.py))\n3. using user-passed search options, search for the album cover art image file.\n4. if album cover art is found, create that image file into the \"album\"\ndirectory. The name and type of image (`.jpg`, `.png`, `.gif`) is based on\nuser-passed options for the `IMAGE_NAME` and `IMAGE_TYPE`.\n\n
\n\n----\n\n![\"profile](\"https://stackexchange.com/users/flair/216253.png\" "\\"profile")
\n\n",
"description_content_type": "text/markdown",
"docs_url": null,
"download_url": "",
"downloads": {
"last_day": -1,
"last_month": -1,
"last_week": -1
},
"home_page": "https://github.com/jtmoon79/coverlovin2",
"keywords": "audio image music",
"license": "Apache License 2.0 (Apache-2.0)",
"maintainer": "",
"maintainer_email": "",
"name": "CoverLovin2",
"package_url": "https://pypi.org/project/CoverLovin2/",
"platform": "",
"project_url": "https://pypi.org/project/CoverLovin2/",
"project_urls": {
"Bug Reports": "https://github.com/jtmoon79/coverlovin2/issues",
"Homepage": "https://github.com/jtmoon79/coverlovin2",
"Say Thanks!": "http://saythanks.io/to/coverlovin2",
"Source": "https://github.com/jtmoon79/coverlovin2"
},
"release_url": "https://pypi.org/project/CoverLovin2/0.5.7/",
"requires_dist": [
"musicbrainzngs (>=0.6)",
"mutagen (>=1.42.0)",
"Pillow (>=5.4.1)"
],
"requires_python": ">=3.7",
"summary": "Download music album cover art for a music collection.",
"version": "0.5.7"
},
"last_serial": 5527428,
"releases": {
"0.5.2": [
{
"comment_text": "",
"digests": {
"md5": "ab5a16be5e8b7e9a79fe263935cc9d5a",
"sha256": "451abec8344828a68b26f13a2a1017594b3f3c6eb5761bf449d7c1ea4785d692"
},
"downloads": -1,
"filename": "CoverLovin2-0.5.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ab5a16be5e8b7e9a79fe263935cc9d5a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 21548,
"upload_time": "2019-02-13T07:37:19",
"url": "https://files.pythonhosted.org/packages/98/50/913d2daa7fbf5cd8dd4d6c8ac4b5777a9d655d9d76e670df0c9c3b7d6bb4/CoverLovin2-0.5.2-py3-none-any.whl"
}
],
"0.5.3": [
{
"comment_text": "",
"digests": {
"md5": "83ecaf29aeaf96e77b538297b6bf0a7d",
"sha256": "46a5c9f5c3313316f53b1480139d7df657889b5cd72b333021bff3f40d5555b5"
},
"downloads": -1,
"filename": "CoverLovin2-0.5.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "83ecaf29aeaf96e77b538297b6bf0a7d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 21699,
"upload_time": "2019-02-13T07:53:39",
"url": "https://files.pythonhosted.org/packages/14/f9/5457459f35c103d0259791d687cac856fb00b236d1cb513b4d21a41c98cb/CoverLovin2-0.5.3-py3-none-any.whl"
}
],
"0.5.5": [
{
"comment_text": "",
"digests": {
"md5": "21497cbda1cd7701f8a2612836d8d97d",
"sha256": "4391882becd493072f61a6d519e9fc6502e308a5b8c631cdd52d8eb7a1e9d4f2"
},
"downloads": -1,
"filename": "CoverLovin2-0.5.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "21497cbda1cd7701f8a2612836d8d97d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 22938,
"upload_time": "2019-02-26T09:18:22",
"url": "https://files.pythonhosted.org/packages/88/01/7a16e69fa4cfa131020d655e7876af38e9ad85e817b3e454703264c56a66/CoverLovin2-0.5.5-py3-none-any.whl"
}
],
"0.5.6": [
{
"comment_text": "",
"digests": {
"md5": "af835937b1ea9f167544fc6afa638bc1",
"sha256": "cd75305e7a6c5fd2704a9b2a7c8fd782c34603adebe5b0fa36e69f0273309c80"
},
"downloads": -1,
"filename": "CoverLovin2-0.5.6-py3-none-any.whl",
"has_sig": false,
"md5_digest": "af835937b1ea9f167544fc6afa638bc1",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 23890,
"upload_time": "2019-02-27T10:13:33",
"url": "https://files.pythonhosted.org/packages/86/a6/8a92dba47ba55783b3c10c5c82374ec488b78bc33f617a986b1ac2ab18bd/CoverLovin2-0.5.6-py3-none-any.whl"
}
],
"0.5.7": [
{
"comment_text": "",
"digests": {
"md5": "410e950038b08b9a761b80121f77470e",
"sha256": "fe4c7763e619bd83ff3a17dbd11d6b403dd14806d2a1c3f0d390b2473e29e80d"
},
"downloads": -1,
"filename": "CoverLovin2-0.5.7-py3-none-any.whl",
"has_sig": false,
"md5_digest": "410e950038b08b9a761b80121f77470e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 25935,
"upload_time": "2019-07-13T17:07:47",
"url": "https://files.pythonhosted.org/packages/68/74/bcc746c55e4519aabb32a8745e217f21368161c6e74efe5db5c22851a569/CoverLovin2-0.5.7-py3-none-any.whl"
}
]
},
"urls": [
{
"comment_text": "",
"digests": {
"md5": "410e950038b08b9a761b80121f77470e",
"sha256": "fe4c7763e619bd83ff3a17dbd11d6b403dd14806d2a1c3f0d390b2473e29e80d"
},
"downloads": -1,
"filename": "CoverLovin2-0.5.7-py3-none-any.whl",
"has_sig": false,
"md5_digest": "410e950038b08b9a761b80121f77470e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 25935,
"upload_time": "2019-07-13T17:07:47",
"url": "https://files.pythonhosted.org/packages/68/74/bcc746c55e4519aabb32a8745e217f21368161c6e74efe5db5c22851a569/CoverLovin2-0.5.7-py3-none-any.whl"
}
]
}