mirror of
https://github.com/beetbox/beets.git
synced 2025-12-15 21:14:19 +01:00
63aa3b3165
this makes the ePUB easier to parse by e-readers, because they do not need to load one giant HTML file, but one per author. it also makes sphinx rendering more efficient and interactive
188 lines
6.8 KiB
ReStructuredText
188 lines
6.8 KiB
ReStructuredText
Lyrics Plugin
|
|
=============
|
|
|
|
The ``lyrics`` plugin fetches and stores song lyrics from databases on the Web.
|
|
Namely, the current version of the plugin uses `Lyric Wiki`_,
|
|
`Musixmatch`_, `Genius.com`_, and, optionally, the Google custom search API.
|
|
|
|
.. _Lyric Wiki: http://lyrics.wikia.com/
|
|
.. _Musixmatch: https://www.musixmatch.com/
|
|
.. _Genius.com: http://genius.com/
|
|
|
|
|
|
Fetch Lyrics During Import
|
|
--------------------------
|
|
|
|
To automatically fetch lyrics for songs you import, enable the ``lyrics``
|
|
plugin in your configuration (see :ref:`using-plugins`).
|
|
Then, install the `requests`_ library by typing::
|
|
|
|
pip install requests
|
|
|
|
The plugin uses `requests`_ to download lyrics.
|
|
|
|
When importing new files, beets will now fetch lyrics for files that don't
|
|
already have them. The lyrics will be stored in the beets database. If the
|
|
``import.write`` config option is on, then the lyrics will also be written to
|
|
the files' tags.
|
|
|
|
.. _requests: http://docs.python-requests.org/en/latest/
|
|
|
|
|
|
Configuration
|
|
-------------
|
|
|
|
To configure the plugin, make a ``lyrics:`` section in your
|
|
configuration file. The available options are:
|
|
|
|
- **auto**: Fetch lyrics automatically during import.
|
|
Default: ``yes``.
|
|
- **bing_client_secret**: Your Bing Translation application password
|
|
(to :ref:`lyrics-translation`)
|
|
- **bing_lang_from**: By default all lyrics with a language other than
|
|
``bing_lang_to`` are translated. Use a list of lang codes to restrict the set
|
|
of source languages to translate.
|
|
Default: ``[]``
|
|
- **bing_lang_to**: Language to translate lyrics into.
|
|
Default: None.
|
|
- **fallback**: By default, the file will be left unchanged when no lyrics are
|
|
found. Use the empty string ``''`` to reset the lyrics in such a case.
|
|
Default: None.
|
|
- **force**: By default, beets won't fetch lyrics if the files already have
|
|
ones. To instead always fetch lyrics, set the ``force`` option to ``yes``.
|
|
Default: ``no``.
|
|
- **google_API_key**: Your Google API key (to enable the Google Custom Search
|
|
backend).
|
|
Default: None.
|
|
- **google_engine_ID**: The custom search engine to use.
|
|
Default: The `beets custom search engine`_, which gathers an updated list of
|
|
sources known to be scrapeable.
|
|
- **sources**: List of sources to search for lyrics. An asterisk ``*`` expands
|
|
to all available sources.
|
|
Default: ``google lyricwiki musixmatch``, i.e., all the
|
|
sources except for `genius`. The `google` source will be automatically
|
|
deactivated if no ``google_API_key`` is setup.
|
|
|
|
Here's an example of ``config.yaml``::
|
|
|
|
lyrics:
|
|
fallback: ''
|
|
google_API_key: AZERTYUIOPQSDFGHJKLMWXCVBN1234567890_ab
|
|
google_engine_ID: 009217259823014548361:lndtuqkycfu
|
|
|
|
.. _beets custom search engine: https://www.google.com:443/cse/publicurl?cx=009217259823014548361:lndtuqkycfu
|
|
|
|
Fetching Lyrics Manually
|
|
------------------------
|
|
|
|
The ``lyrics`` command provided by this plugin fetches lyrics for items that
|
|
match a query (see :doc:`/reference/query`). For example, ``beet lyrics magnetic
|
|
fields absolutely cuckoo`` will get the lyrics for the appropriate Magnetic
|
|
Fields song, ``beet lyrics magnetic fields`` will get lyrics for all my tracks
|
|
by that band, and ``beet lyrics`` will get lyrics for my entire library. The
|
|
lyrics will be added to the beets database and, if ``import.write`` is on,
|
|
embedded into files' metadata.
|
|
|
|
The ``-p`` option to the ``lyrics`` command makes it print lyrics out to the
|
|
console so you can view the fetched (or previously-stored) lyrics. The
|
|
``-r directory`` option similarly shows all lyrics as an RST (ReStructuredText)
|
|
document structure located in ``directory`` (which defaults to the
|
|
current directory). That document, in turn, can be parsed by tools like Sphinx
|
|
to generate HTML, ePUB or PDF formatted documents. Use, for example,
|
|
the following ``conf.py``::
|
|
|
|
# -*- coding: utf-8 -*-
|
|
master_doc = 'index'
|
|
project = u'Lyrics'
|
|
copyright = u'none'
|
|
author = u'Various Authors'
|
|
latex_documents = [
|
|
(master_doc, 'Lyrics.tex', project,
|
|
author, 'manual'),
|
|
]
|
|
epub_title = project
|
|
epub_author = author
|
|
epub_publisher = author
|
|
epub_copyright = copyright
|
|
epub_exclude_files = ['search.html']
|
|
epub_tocdepth = 1
|
|
epub_tocdup = False
|
|
|
|
Then the output can be written to ``index.rst``. An alternative is to
|
|
use the following ``index.rst`` file, which will also generate an
|
|
index of song titles::
|
|
|
|
Lyrics
|
|
======
|
|
|
|
* :ref:`Song index <genindex>`
|
|
* :ref:`search`
|
|
|
|
Artist index:
|
|
|
|
.. toctree::
|
|
:maxdepth: 1
|
|
|
|
artists
|
|
|
|
Then the correct format can be generated with one of::
|
|
|
|
sphinx-build -b epub3 . _build/epub
|
|
sphinx-build -b latex . _build/latex
|
|
sphinx-build -b html . _build/html
|
|
|
|
The ``-f`` option forces the command to fetch lyrics, even for tracks that
|
|
already have lyrics. Inversely, the ``-s`` option skips lyrics that
|
|
are not locally available, to dump lyrics faster.
|
|
|
|
.. _activate-google-custom-search:
|
|
|
|
Activate Google custom search
|
|
------------------------------
|
|
|
|
Using the Google backend requires `BeautifulSoup`_, which you can install
|
|
using `pip`_ by typing::
|
|
|
|
pip install beautifulsoup4
|
|
|
|
You also need to `register for a Google API key`_. Set the ``google_API_key``
|
|
configuration option to your key.
|
|
Then add ``google`` to the list of sources in your configuration (or use
|
|
default list, which includes it as long as you have an API key).
|
|
If you use default ``google_engine_ID``, we recommend limiting the sources to
|
|
``musixmatch google`` as the other sources are already included in the Google
|
|
results.
|
|
|
|
.. _register for a Google API key: https://console.developers.google.com/
|
|
|
|
Optionally, you can `define a custom search engine`_. Get your search engine's
|
|
token and use it for your ``google_engine_ID`` configuration option. By
|
|
default, beets use a list of sources known to be scrapeable.
|
|
|
|
.. _define a custom search engine: http://www.google.com/cse/all
|
|
|
|
Note that the Google custom search API is limited to 100 queries per day.
|
|
After that, the lyrics plugin will fall back on other declared data sources.
|
|
|
|
.. _pip: http://www.pip-installer.org/
|
|
.. _BeautifulSoup: http://www.crummy.com/software/BeautifulSoup/bs4/doc/
|
|
|
|
.. _lyrics-translation:
|
|
|
|
Activate On-the-Fly Translation
|
|
-------------------------------
|
|
|
|
Using the Bing Translation API requires `langdetect`_, which you can install
|
|
using `pip`_ by typing::
|
|
|
|
pip install langdetect
|
|
|
|
You also need to register for a Microsoft Azure Marketplace free account and
|
|
to the `Microsoft Translator API`_. Follow the four steps process, specifically
|
|
at step 3 enter ``beets`` as *Client ID* and copy/paste the generated
|
|
*Client secret* into your ``bing_client_secret`` configuration, alongside
|
|
``bing_lang_to`` target `language code`_.
|
|
|
|
.. _langdetect: https://pypi.python.org/pypi/langdetect
|
|
.. _Microsoft Translator API: https://www.microsoft.com/en-us/translator/getstarted.aspx
|
|
.. _language code: https://msdn.microsoft.com/en-us/library/hh456380.aspx
|