Configuration reference#

Radiotomate is configurable through YAML files. The installer will generate files with reasonable default values. It also contains comments (lines that start with #) to help you read it but if you have never encountered YAML it is probably worth taking a few minutes on some YAML tutorial.

It uses two configuration files:

  • radiotomate_data/radiotomate.yaml for general settings
  • radiotomate_data/Beets/config.yaml for the music library.

We start by the general settings.

Playout configuration#

The core of the stream generation is configured below the playout_process_config node. We list all available options before displaying a complete example.

Configuring outputs#

Once provided with some music and jingles radiotomate can happily play forever, but you have to configure where to play that sound stream. This is configured in the outputs node, which should contain a sequence of mappings. Each mapping defines one output, and should have at least a driver node whose values can be

  • pulseaudio for sound cards,
  • or icecast

Sound cards#

If your machine has only one sound card, setting driver: pulseaudio should be enough and will let you configure the output with your usual mixer interface.

If you have multiple sound cards, you can explicitely set the name of the output you need by adding a device node along the driver. Use pactl list to find outputs names.

We also support driver: alsa, however this also suppose your container configuration allows the playout container to bind to alsa cards. If you manage to do this successfully, please tell us so we could document it too.

Icecast outputs#

Outputting to Icecast requires more settings, at least host, port, mount and password. If the Icecast server is on the same machine, set host to host.containers.internal (localhost or 127.0.0.1 won't work because we run Radiotomate in containers).

You must also choose an encoder and set its quality. We support the following encoders:

  • mp3cbr, for constant bitrate MP3, according to quality. We advise to set quality: 192 but usual values from 128 to 320 will do.
  • mp3vbr, for variable bitrate MP3. We advise to set quality: 2, you can set any value from 0 (best) to 9 (worst).
  • flac for 16 bits FLAC. In that case quality sets the compression level, choose one from 0 (low, fast) to 8 (better, consumes more CPU).
  • vorbiscbr for Ogg Vorbis at a constant bitrate set by quality. We advise to set quality: 160 but usual values from 128 to 320 will do.
  • vorbisvbr for Ogg Vorbis at a variable bitrate, according to quality. We advise for quality: 0.3 but you can set values between 0.1 (worst) to 0.9 (best).
  • wav for raw PCM streaming. quality is ignored.

Stream input options#

Sub-nodes prefixed by input_ configure the playout's live stream input:

    input_name: "stream"
    input_min_buffer: 5.
    input_max_buffer: 30.

input_name is the Icecast equivalent of "mountpoint". The two other options define how much time (in seconds) should be buffered before the input is considered active. This buffer implies that Radiotomate will introduce a delay between the input stream and the aired program. Using the default settings as above means the programs will be 5 to 30 seconds late. On the other hand, this buffer compensates for potential connection misses. If you usually have high-quality connections you can consider reducing this values, but we advise to experiment this progressively.

This input will be listening behind a port number defined by the containers configuration, by default 6800.

Minimal delay between two jingles#

When the auto-DJ is playing it will insert jingles regularly, between songs. This sets the minimal number of seconds between two jingles:

    jingles_delay: 780.

Start sound#

The start_sound gives the path to the file that Radiotomate should play when it starts.

    start_sound: /home/username/radiotomate_data/default_start_sound.wav

It must be below the data root folder. You can replace the default file by a specific jingle of yours, or disable it by setting it empty or removing that file, though we think airing a specific flag sound when starting is important.

Log path#

Playout's specific log path is defined by:

    log_path: /home/username/radiotomate_data/playout.log

This must be a path below a folder where the playout process can write, so we advise to keep it below the data root folder.

Inter-processes token#

This block also contains a secret used by Radiotomate's applications when they contact each other:

    token: b58f90045b88f583e061a9c35a82ecd1cac4f708664e266ff024cbee2ea101a2

You probably don't need to change it, but if you do you must restart all applications afterwards so they load the new version. You must ensure that it is not readable from the outside! In perticular, take care to remove it when asking for help.

A very complete example#

Here is a complete playout_process_config that includes 3 outputs:

playout_process_config:
    outputs:
        - driver: pulseaudio
          device: "alsa_output.pci-0000_80_01.0.analog-stereo"
        - driver: icecast
          encoder: mp3cbr
          quality: 192
          host: "host.containers.internal"
          port: 9000
          mount: "radio.mp3"
          password: "topsecret"
        - driver: icecast
          encoder: vorbisvbr
          quality: 0.1
          host: "backup.myradio.fm"
          port: 9876
          mount: "radio.ogg"
          password: "anothersecret"
    jingles_delay: 780.
    input_name: "stream"
    input_min_buffer: 5.
    input_max_buffer: 30.
    start_sound: /home/username/radiotomate_data/default_start_sound.wav
    log_path: /home/username/radiotomate_data/playout.log
    token: b58f90045b88f583e061a9c35a82ecd1cac4f708664e266ff024cbee2ea101a2

Maximum late starts#

New option in upcoming versions:

Sometimes a sound cart is schedules to play, but cannot start because a live stream is going on. This should set a maximum delay after we just abort playing that cart.

Metadata history and relay#

Radiotomate keeps track of what has been playing by storing each track's metadata and when it aired exactly. This is available in its "History" tab. Settings below the metadata_log node let you choose what's stored, and if the system should relay this metadata to an external service. For example:

metadata_log:
    extra_fields:
        - genre
        - year

    relay_to:
        - url: "https://website.radio/playlist/add_item"
          add_field:
              SECRET_KEY: "secret value"
              SOURCE_NAME: "radiotomate"
          add_header:
              Authorization: "Basic YWxhZGRpbjpvcGVuc2VzYW1l"
        - url: "https://website.radio/playlist/add_item"
          add_header:
              Authorization: "Basic YWxhZGRpbjpvcGVuc2VzYW1l"

By default Radiotomate only stores the artist and title metadata and internal information. You might be interested to have additional fields, for example to extract some statistics regularly, so you can list those in extra_fields.

For each url in relay_to, Radiotomate will issue an HTTP POST query to given URL each time playout starts a new track. It transmits the same fields as those stored in the metadata log (including those listed in extra_fields), each one is posted as a form field. As you probably need to secure this endpoint, the configuration lets you define additional HTTP header(s) with add_header, and/or additional form field(s) with add_field. add_field and add_header are optional and can be skipped entirely if you don't need them, you may also use both for a single URL.

Data root#

The data node should contain a root node that gives the path to the root data folder. This is where uploaded sounds go.

data:
    root: /home/username/radiotomate_data

The installer will put everything (including the configuration file) in this folder, but this options leaves you room for more adventurous sets.

Database configuration#

The db node is a SQLAlchemy engine configuration object. If you want to hack that part we refer to their documentation, but in most cases you only want to keep the url set by the installer. When debugging you may set echo to true to log DB queries.

db:
    url: "sqlite+aiosqlite:////home/martin/radiotomate/radio_data/radiotomate.db"
    echo: false

Interface settings#

The config file currently only sets a secret value that will help to secure cookies that identify users' session in the publicly available Web interface:

interface:
    cookie_salt: f301a56bd981633d596617529cd65676d79888051d6a45659781c899df4fe40b

This should not be read by others persons or programs, nor be copied on the internet. If it has been published by mistake, change this value quickly and restart Radiotomate (users will have to log in again).

Scheduler & interface logging configuration#

The logging node defines where and how the scheduler and interface programs log. It is a Python logging configuration dictionary. You might want to change their path or their level, which can be set to ERROR, WARNING, INFO or DEBUG (from the most quiet to the most verbose).

Music library#

In radiotomate the music library is actually managed by Beets, that has its own configuration file. By default it is located in radiotomate_data/Beets/config.yaml.

Removing settings set by the installer might disrupt the auto-DJ. But you can activate plug-ins or set additional options in that file. You also might be interested in tuning the dropbox or the loudness level, as follows.

The music dropbox#

Radiotomate installer will enable and start the drop2beets plug-in. It is watching a folder for new files: any music file dropped in will be automatically integrated to the music library after a dozen seconds. You can share this folder on your radio's local network (with Samba or NFS) to ease the insertion of music from other workstations (if you want to change that folder you will also have to update the configuration of the container running the dropbox watch, it is probably easier to configure Samba to share the default folder directly).

By default the folder is radiotomate_data/MusicDropbox/. The plug-in lets you write custom tagging logics. For example, you can force a track's genre or language depending on the sub-folder it has been dropped in. This is described in drop2beets' documentation.

Setting the radio's loudness level with replaygain#

When it receives any sound file, Radiotomate computes its average loudness. In the future the file will be played with a corrected gain (without re-encoding), to ensure that your stream has a fairly constant loundness.

This is performed via Beets' replaygain plug-in. This computation happens as a background process. It takes at most a few seconds, but the sound will be considered unavailable until computed. So don't try to add a sound to a cart that will play 3 seconds later 😉

Note that radiotomate re-uses this for sound carts too, so jingles and pre-recorded shows are also adjusted according to this target level. This means that Beets' targetlevel option sets the loudness level for the whole radio.

Container and pod configuration#

If you want to move folders after installation you'll probably have to update the containers' configuration too.

By default, radiotomate's containers are running in a pod as quadlets. Everything is defined from a Kubernetes-like pod manifest located by default at $HOME/.config/containers/systemd/radiotomate_pod_manifest.yaml.