Lyrics providers

A lyrics provider is where the getLyrics API endpoint looks for the lyrics of a song. Each one listed in the [plugins] section lyrics option is asked in turn, in the order they’re listed, and the first one finding anything answers the request. When none does, the client is told there are no lyrics.

Even reading lyrics off the library is done by providers: embedded reads them from the tags of the track files and sidecar from a text file next to them, and both are listed by default. Like any other, they can be reordered, left out, or listed alongside providers of your own.

Contrary to scrobblers, a provider has nothing to do with users: lyrics are the same for everyone. It therefore has no routes, no fragment on the profile page and no tables, and comes down to a single method.

Loading

Providers are loaded from the lyrics option of the [plugins] section, a space-separated list:

[plugins]
lyrics = embedded sidecar myplugins.lyricsdir

A bare name is one of the providers shipped with Supysonic. A name holding a dot is the path of a Python module to import as-is, which must be importable from the process running the web application. Note that this means a top-level module can’t be used directly: put it in a package, so it has a dotted path.

The module must hold a PROVIDER attribute naming its LyricsProvider subclass. Anything else — a module that can’t be imported, one without that attribute, or an attribute that isn’t a LyricsProvider subclass — aborts the startup with a LyricsProviderImportError naming the offending configuration value.

Each loaded provider is then built with the whole configuration, and asked whether it’s configured. One that says no is dropped, as if it hadn’t been listed at all, and a warning in the log says so. The rest of the application may therefore assume that a loaded provider is usable.

The LyricsProvider interface

class supysonic.lyrics.LyricsProvider(config)

A source of song lyrics.

Providers are asked in the order they’re listed, until one of them answers. Subclasses are self-contained: they own their configuration section and whatever they need to find lyrics.

The configuration handed to __init__() is the whole of it, out of which the provider reads its own section — see Configuration.

name = None

Short identifier, mostly for logging.

Not the name to list in the configuration file, which is the module path.

abstractmethod __init__(config)

Build the provider off the whole config.

Subclasses read their own section out of it, with config.section(TheirSection).

Parameters:

config -- whole Config instance.

abstract property configured

Whether the provider was given what it needs to be usable.

One saying no isn’t loaded at all. A provider needing no configuration simply says yes.

abstractmethod get_lyrics(artist, title)

Look for the lyrics of the song title by artist.

Both come as-is from the client, and are matched however loosely the provider sees fit.

Not finding any is not an error, and neither is a service that’s down or a file that can’t be read: all are reasons to return None, logging at most, so the next provider gets its chance. Raising would turn a lyrics lookup into an API error on the client side.

Parameters:
  • artist -- Name of the artist.

  • title -- Title of the song.

Returns:

a Lyrics instance, or None.

class supysonic.lyrics.Lyrics(artist: str, title: str, text: str)

Lyrics found by a provider, along with what they were found for.

The artist and title are the ones the provider matched, which may differ from the ones asked for: the search is loose, the answer isn’t.

The artist and title a client sends are whatever its user typed or whatever its own tags say, so they’re best treated as search terms, not identifiers. They’re also untrusted input: a provider building a file path or a URL out of them has to make sure they can’t point anywhere else than intended.

Errors

Errors raised about a lyrics provider.

exception supysonic.lyrics.exceptions.LyricsProviderError

Base class for lyrics provider related errors.

exception supysonic.lyrics.exceptions.LyricsProviderImportError

A configured lyrics provider couldn’t be imported and loaded.

Only LyricsProviderImportError is raised, by Supysonic as it loads the providers. A provider itself never raises: see get_lyrics().

A simple example

Here’s a provider reading lyrics from a directory of text files, each named after the artist and title of a song. It lives in a package, so that it has a dotted path to list in the configuration file:

myplugins/
    __init__.py
    lyricsdir.py

myplugins/lyricsdir.py:

import logging
import os.path

from supysonic.config import Option, Section
from supysonic.lyrics import Lyrics, LyricsProvider

logger = logging.getLogger(__name__)


class LyricsDirSection(Section, section="lyricsdir"):
    path = Option()


class LyricsDirProvider(LyricsProvider):
    name = "lyricsdir"

    def __init__(self, config):
        self.__path = config.section(LyricsDirSection).path

    @property
    def configured(self):
        return self.__path is not None and os.path.isdir(self.__path)

    def get_lyrics(self, artist, title):
        filename = f"{artist} - {title}.txt"
        # Both come from the client: don't let them escape the directory
        if os.path.basename(filename) != filename:
            return None

        try:
            with open(os.path.join(self.__path, filename), encoding="utf-8") as f:
                return Lyrics(artist, title, f.read())
        except FileNotFoundError:
            return None
        except (OSError, UnicodeError) as e:
            logger.warning("Can't read lyrics file %r: %s", filename, e)
            return None


PROVIDER = LyricsDirProvider

And the configuration enabling it, after the providers shipped with Supysonic:

[plugins]
lyrics = embedded sidecar myplugins.lyricsdir

[lyricsdir]
path = /srv/music/lyrics