mirror of
https://github.com/beetbox/beets.git
synced 2025-12-06 08:39:17 +01:00
Make lyrics plugin documentation slightly more clear
This commit is contained in:
Šarūnas Nejus
parent
2ff57505d8
commit
c40db1034a
2 changed files with 76 additions and 72 deletions
|
|
@ -893,8 +893,10 @@ class LyricsPlugin(plugins.BeetsPlugin):
|
|||
"dist_thresh": 0.11,
|
||||
"google_API_key": None,
|
||||
"google_engine_ID": "009217259823014548361:lndtuqkycfu",
|
||||
"genius_api_key": "Ryq93pUGm8bM6eUWwD_M3NOFFDAtp2yEE7W"
|
||||
"76V-uFL5jks5dNvcGCdarqFjDhP9c",
|
||||
"genius_api_key": (
|
||||
"Ryq93pUGm8bM6eUWwD_M3NOFFDAtp2yEE7W"
|
||||
"76V-uFL5jks5dNvcGCdarqFjDhP9c"
|
||||
),
|
||||
"fallback": None,
|
||||
"force": False,
|
||||
"local": False,
|
||||
|
|
|
|||
|
|
@ -2,25 +2,27 @@ Lyrics Plugin
|
|||
=============
|
||||
|
||||
The ``lyrics`` plugin fetches and stores song lyrics from databases on the Web.
|
||||
Namely, the current version of the plugin uses `Genius.com`_, `Tekstowo.pl`_, `LRCLIB`_
|
||||
and, optionally, the Google custom search API.
|
||||
Namely, the current version of the plugin uses `Genius.com`_, `Tekstowo.pl`_,
|
||||
`LRCLIB`_ and, optionally, the Google Custom Search API.
|
||||
|
||||
.. _Genius.com: https://genius.com/
|
||||
.. _Tekstowo.pl: https://www.tekstowo.pl/
|
||||
.. _LRCLIB: https://lrclib.net/
|
||||
|
||||
|
||||
Fetch Lyrics During Import
|
||||
--------------------------
|
||||
Install
|
||||
-------
|
||||
|
||||
To automatically fetch lyrics for songs you import, first enable it in your
|
||||
configuration (see :ref:`using-plugins`). Then, install ``beets`` with
|
||||
``lyrics`` extra
|
||||
Firstly, enable ``lyrics`` plugin in your configuration (see
|
||||
:ref:`using-plugins`). Then, install ``beets`` with ``lyrics`` extra
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
pip install "beets[lyrics]"
|
||||
|
||||
Fetch Lyrics During Import
|
||||
--------------------------
|
||||
|
||||
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
|
||||
|
|
@ -29,52 +31,52 @@ the files' tags.
|
|||
Configuration
|
||||
-------------
|
||||
|
||||
To configure the plugin, make a ``lyrics:`` section in your
|
||||
configuration file. The available options are:
|
||||
To configure the plugin, make a ``lyrics:`` section in your configuration file.
|
||||
Default configuration:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
lyrics:
|
||||
auto: yes
|
||||
bing_client_secret: null
|
||||
bing_lang_from: []
|
||||
bing_lang_to: null
|
||||
dist_thresh: 0.11
|
||||
fallback: null
|
||||
force: no
|
||||
google_API_key: null
|
||||
google_engine_ID: 009217259823014548361:lndtuqkycfu
|
||||
sources: [lrclib, google, genius, tekstowo]
|
||||
synced: no
|
||||
|
||||
The available options are:
|
||||
|
||||
- **auto**: Fetch lyrics automatically during import.
|
||||
Default: ``yes``.
|
||||
- **bing_client_secret**: Your Bing Translation application password
|
||||
(to :ref:`lyrics-translation`)
|
||||
(see :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.
|
||||
- **dist_thresh**: The maximum distance between the artist and title
|
||||
combination of the music file and lyrics candidate to consider them a match.
|
||||
Lower values will make the plugin more strict, higher values will make it
|
||||
more lenient. This does not apply to the ``lrclib`` backend as it matches
|
||||
durations.
|
||||
Default: ``0.11``.
|
||||
- **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: ``lrclib google genius tekstowo``, i.e., all the available sources. The
|
||||
``google`` source will be automatically deactivated if no ``google_API_key``
|
||||
is setup.
|
||||
The ``google``, ``genius``, and ``tekstowo`` sources will only be enabled if
|
||||
BeautifulSoup is installed.
|
||||
- **synced**: Prefer synced lyrics over plain lyrics if a source offers them. Currently `lrclib` is the only source that provides them. Default: `no`.
|
||||
|
||||
Here's an example of ``config.yaml``::
|
||||
|
||||
lyrics:
|
||||
fallback: ''
|
||||
google_API_key: AZERTYUIOPQSDFGHJKLMWXCVBN1234567890_ab
|
||||
google_engine_ID: 009217259823014548361:lndtuqkycfu
|
||||
to all available sources. The ``google`` source will be automatically
|
||||
deactivated if no ``google_API_key`` is setup.
|
||||
- **synced**: Prefer synced lyrics over plain lyrics if a source offers them.
|
||||
Currently ``lrclib`` is the only source that provides them.
|
||||
|
||||
.. _beets custom search engine: https://www.google.com:443/cse/publicurl?cx=009217259823014548361:lndtuqkycfu
|
||||
|
||||
|
|
@ -89,74 +91,74 @@ 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 ``-p, --print`` option to the ``lyrics`` command makes it print lyrics out
|
||||
to the console so you can view the fetched (or previously-stored) lyrics.
|
||||
|
||||
The ``-f`` option forces the command to fetch lyrics, even for tracks that
|
||||
already have lyrics. Inversely, the ``-l`` option restricts operations
|
||||
to lyrics that are locally available, which show lyrics faster without using
|
||||
the network at all.
|
||||
The ``-f, --force`` option forces the command to fetch lyrics, even for tracks
|
||||
that already have lyrics.
|
||||
|
||||
Inversely, the ``-l, --local`` option restricts operations to lyrics that are
|
||||
locally available, which show lyrics faster without using the network at all.
|
||||
|
||||
Rendering Lyrics into Other Formats
|
||||
-----------------------------------
|
||||
|
||||
The ``-r directory`` option renders all lyrics as `reStructuredText`_ (ReST)
|
||||
documents in ``directory`` (by default, the current directory). That
|
||||
directory, in turn, can be parsed by tools like `Sphinx`_ to generate HTML,
|
||||
ePUB, or PDF documents.
|
||||
The ``-r directory, --write-rest directory`` option renders all lyrics as
|
||||
`reStructuredText`_ (ReST) documents in ``directory`` (by default, the current
|
||||
directory). That directory, in turn, can be parsed by tools like `Sphinx`_ to
|
||||
generate HTML, ePUB, or PDF documents.
|
||||
|
||||
A minimal ``conf.py`` and ``index.rst`` files are created the first time the
|
||||
Minimal ``conf.py`` and ``index.rst`` files are created the first time the
|
||||
command is run. They are not overwritten on subsequent runs, so you can safely
|
||||
modify these files to customize the output.
|
||||
|
||||
.. _Sphinx: https://www.sphinx-doc.org/
|
||||
.. _reStructuredText: http://docutils.sourceforge.net/rst.html
|
||||
Sphinx supports various `builders`_, see a few suggestions:
|
||||
|
||||
Sphinx supports various `builders
|
||||
<https://www.sphinx-doc.org/en/stable/builders.html>`_, but here are a
|
||||
few suggestions.
|
||||
|
||||
* Build an HTML version::
|
||||
.. admonition:: Build an HTML version
|
||||
|
||||
::
|
||||
|
||||
sphinx-build -b html . _build/html
|
||||
|
||||
* Build an ePUB3 formatted file, usable on ebook readers::
|
||||
.. admonition:: Build an ePUB3 formatted file, usable on ebook readers
|
||||
|
||||
::
|
||||
|
||||
sphinx-build -b epub3 . _build/epub
|
||||
|
||||
* Build a PDF file, which incidentally also builds a LaTeX file::
|
||||
.. admonition:: Build a PDF file, which incidentally also builds a LaTeX file
|
||||
|
||||
::
|
||||
|
||||
sphinx-build -b latex %s _build/latex && make -C _build/latex all-pdf
|
||||
|
||||
.. _activate-google-custom-search:
|
||||
|
||||
.. _Sphinx: https://www.sphinx-doc.org/
|
||||
.. _reStructuredText: http://docutils.sourceforge.net/rst.html
|
||||
.. _builders: https://www.sphinx-doc.org/en/stable/builders.html
|
||||
|
||||
Activate Google Custom Search
|
||||
------------------------------
|
||||
|
||||
You 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
|
||||
``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: https://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.
|
||||
|
||||
.. _BeautifulSoup: https://www.crummy.com/software/BeautifulSoup/bs4/doc/
|
||||
.. _register for a Google API key: https://console.developers.google.com/
|
||||
.. _define a custom search engine: https://www.google.com/cse/all
|
||||
|
||||
Activate Genius and Tekstowo.pl Lyrics
|
||||
--------------------------------------
|
||||
|
||||
These backends are enabled by default.
|
||||
|
||||
.. _lyrics-translation:
|
||||
|
||||
|
|
@ -167,6 +169,6 @@ You 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`.
|
||||
``bing_lang_to`` target ``language code``.
|
||||
|
||||
.. _Microsoft Translator API: https://docs.microsoft.com/en-us/azure/cognitive-services/translator/translator-how-to-signup
|
||||
|
|
|
|||
Loading…
Reference in a new issue