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
Configinstance.
- 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
titlebyartist.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
Lyricsinstance, orNone.
- 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