Configuring Showergel

A configuration file is needed to start Showergel. It tells the program what to do, where data should be written, how to contact Liquidsoap, etc. Showergel’s installer creates a minimal configuration, including comments if you’re hurried to tweak it. This section will tell you all configuration details and their implications, if any.

What’s a .toml configuration file

Showergel uses the TOML format. If you have never encountered it, let’s start by describing how this configuration is written. It is a text file, encoded in UTF-8, that you can edit with the same program as your Liquidsoap script.

Configuration properties have a key (usually a word) and a value (a character string, a list, number, …). Properties are grouped by sections, like [listen] or [db.sqlalchemy].

Do not mix properties between sections: the program will look for a property below one perticular section. Comments are notes that will be ignored by the program: they start with a #.

A TOML file looks like this:

[section]
property = "value"
somelist = ["foo", "bar", "baz"]
somenumber = 9876

[another_section]
# this line starts with a sharp : programs will ignore it
# you can use comments to note why a value is defined
# or to put aside old configuration values
debug = true  # comments can be at end of lines too

[db.sqlalchemy]

This section should at least include a path to the instance’s database file:

url = "sqlite:////home/me/path/to/showergel.db"

Yes, that’s four /. Use only 3 if you prefer a relative path (relative to Showergel’s working directory), for example sqlite:///showergel.db.

In demo mode, you might want to set sqlite:///:memory: to avoid writing a file.

If you have a DB server at hand, you can use it for Showergel too. You will have to install the DBAPI package youself, and refer to SQLAlchemy’s documentation for the URL format - see pages about PostgreSQL or MySQL.

When debugging, you may display DB requests in Showergel’s log by setting the property echo = true.

[interface]

You may change the name displayed in the interface’s left bar:

name = "Showergel Radio 98.7 FM"

[listen]

This defines Showergel’s address for your browser and liquidsoap. For example:

address = "localhost"
port = 2345

Using these (default) values, Showergel’s interface will be available at the URL http://localhost:2345/. If you are running multiple instances of Showergel on the same machine, be careful to set a different port for each one.

For some features (user authentication, metadata logging), Showergel’s URL must be set in your Liquidsoap script too. See Showergel integration in Liquidsoap scripts.

Warning

The address property may be an IP address. If you change the address, ensure it is only accessible on a private network.

To have a more detailed server log you can add debug = true.

[liquidsoap]

This section defines how Showgel can contact Liquidsoap:

method = "telnet"
host = "localhost"
port = 1234

This should match Liquidsoap’s telnet parameters - see Showergel integration in Liquidsoap scripts.

Other values can be set as method:

  • none if you don’t want to enable Showergel’s “current track” display.

  • demo will simulate a Liquidsoap connection. In that case host and port are ignored. This is used by Showergel’s online demo.

  • anything else, or if the parameter is missing, will simulate a Liquidsoap connection by generating different data each time it’s called. This should only be used for Showergel’s unit tests.

You can also add a line stating ouput = "identifier" to force Showergel to get its “Now playing” information from the output having id="identifier" in your Liquidsoap script (see Display/skip current track).

[metadata_log]

This section configures how Showergel stores tracks’ metadata. It may contain extra_fields: a list of metadata fields that should be stored, when available.

[metadata_log]
extra_fields = [
    "genre",
    "language",
    "year",
    "track*",
]

A * in the field name represents any characters or nothing. In the example above, track* will match track, but also track_number or tracktotal. Field names are stored as they are, so Showergel will store track_number or tracktotal.

Logging configuration

This follows Python’s configuration dictionary schema for logging.