From c40db1034acb5e8164fa113860427ace2e7308c1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=A0ar=C5=ABnas=20Nejus?= Date: Tue, 27 Aug 2024 13:43:31 +0100 Subject: [PATCH] Make lyrics plugin documentation slightly more clear --- beetsplug/lyrics.py | 6 +- docs/plugins/lyrics.rst | 142 ++++++++++++++++++++-------------------- 2 files changed, 76 insertions(+), 72 deletions(-) diff --git a/beetsplug/lyrics.py b/beetsplug/lyrics.py index 84bc26ea7..2f8998d96 100644 --- a/beetsplug/lyrics.py +++ b/beetsplug/lyrics.py @@ -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, diff --git a/docs/plugins/lyrics.rst b/docs/plugins/lyrics.rst index d080b1f94..f034cf47a 100644 --- a/docs/plugins/lyrics.rst +++ b/docs/plugins/lyrics.rst @@ -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 supports various `builders`_, see a few suggestions: + + +.. admonition:: Build an HTML version + + :: + + sphinx-build -b html . _build/html + +.. admonition:: Build an ePUB3 formatted file, usable on ebook readers + + :: + + sphinx-build -b epub3 . _build/epub + +.. 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 + + .. _Sphinx: https://www.sphinx-doc.org/ .. _reStructuredText: http://docutils.sourceforge.net/rst.html - -Sphinx supports various `builders -`_, but here are a -few suggestions. - - * Build an HTML version:: - - sphinx-build -b html . _build/html - - * 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:: - - sphinx-build -b latex %s _build/latex && make -C _build/latex all-pdf - -.. _activate-google-custom-search: +.. _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