Skip to content

lyrics

Jump to bottom
Ronald Record edited this page Aug 29, 2022 · 2 revisions

Lyrics Plugin

The lyrics plugin fetches and stores song lyrics from databases on the Web. Namely, the current version of the plugin uses Musixmatch, Genius.com, Tekstowo.pl, and, optionally, the Google custom search API.

Fetch Lyrics During Import

To automatically fetch lyrics for songs you import, enable the lyrics plugin in your configuration (see using-plugins{.interpreted-text role="ref"}). 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.

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 lyrics-translation{.interpreted-text role="ref"})
  • 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 musixmatch 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.

Here's an example of config.yaml:

lyrics:
  fallback: ''
  google_API_key: AZERTYUIOPQSDFGHJKLMWXCVBN1234567890_ab
  google_engine_ID: 009217259823014548361:lndtuqkycfu

Fetching Lyrics Manually

The lyrics command provided by this plugin fetches lyrics for items that match a query (see /reference/query{.interpreted-text role="doc"}). 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 -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.

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.

A 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, 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

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.

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.

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.

Activate Genius and Tekstowo.pl Lyrics

Using the Genius or Tekstowo.pl backends requires BeautifulSoup, which you can install using pip by typing:

pip install beautifulsoup4

These backends are enabled by default.

Activate On-the-Fly Translation {#lyrics-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]{.title-ref}.

Clone this wiki locally