[] [] [] []
Next: Running the UBS Up: Unattended Broadcasting System User Previous: Installing the UBS   Contents

Configuring the UBS

Before the UBS can be run, it needs to have a configuration file which specifies default settings for the system. Unless the location to such a file is specified from the command line (see chapter, "Running the UBS"), this file is PREFIX/etc/ubs.conf. If this file does not exist, or contains an error, the UBS will fail to start. A default configuration file is included with the UBS, and is installed as ubs.conf.default. This file can be renamed to ubs.conf, and edited as necessary. The file is well commented, and should be fairly straightforward.
The configuration file has a relatively simple format. Settings are specified, one per line. Any line beginning with the '#' symbol is treated as a comment, and ignored by the UBS. All other lines are in the following format:
context.subcontext = "argument"
Here, the "context" describes the section of the particular setting. The global context is read by all daemons, and each daemon can have its own context, which is suitable for particular settings not applicable to other daemons. The "subcontext", in turn, describes the particular parameter that is to be set. For instance, the configuration line:
play.media = "mpg123 -g 0 -q \%s"
will set the "media" variable for the "play" context (which is parsed by the ubs-play daemon) to be the program "mpg123" with the arguments given above. In particular, the song's filename will also be substituted in for "%s". Note that most things in the configuration file can be left commented out, in which case the UBS will resort to the built in default settings. The following variables are recognized by the UBS's global context:
errorlog
Where to log program errors. (Default: "log/error.log")
loglevel
Determines how much information is to be sent to the error logs. Each loglevel also encompasses all levels less than its value, which means that the "error" level will also print out messages marked as "status" and "emergency". (Default: "2") The recognized loglevels are:
0
Emergency messages and critical errors only.
1
Status messages.
2
Non-fatal error messages.
3
Debugging information. This level will produce a great deal of logging output and is recommended for developers only.
prefix
Where the UBS looks for its relevant subdirectories. Only used upon program initialization. (Default: "/usr/local/ubs")
queue
Location of queue file for songs to play. (Default: "var/queue")
songlog
Where to log songs that have been played on the air. (Default: "log/playlist.log")
The following commands are recognized by the "play" context, which is read in by the ubs-play daemon:
media
The name of the media player to use for all files. Accepts substitution of "%s" for the song filename. (Default: "ogg123 -q %s")
killmedia
Determines whether or not to stop the media player upon program exit. Acceptable values are "yes" or "no". If this value is not set, when a "stop" command is issued, the UBS itself will terminate, but it will leave the song playing on the air until it is finished. This can be useful for stations that want to avoid sudden stops, but it also means that a sudden restart of the UBS may play two songs on the air at once. If killmedia is set to be on, then the media player will be immediately stopped when ubs-play exits. (Default: "no")
The ubs.conf file also contains the schedule of shows, which is parsed by the ubs-sched daemon. This must be specified in the configuration file, or else the UBS will not run. In order to set up a schedule of shows, the following configuration option needs to be set:
sched.numshows = "?"
Where '?' corresponds to the number of total shows. Each show must then be specified with the following format (not necessarily in this order):
showN.name = "name"
showN.start = time
showN.end = time
showN.repeat = "frequency"
showN.dir = "directory"
showN.type = "type"
Where 'N' is the show number, starting with '1'. If any one of these values are left blank, the show will be considered invalid and the scheduling daemon will not run. For each one of the shows, the context is simply the word "show" combined with the particular number of the show, starting at the number 1. Thus, if three shows are given in sched.numshows, then they would be given contexts of show1, show2, and show3, respectively. The order that these shows are given doesn't matter, but all three shows must be completed at some point in the configuration file.
Each show may have the following parameters, as specified above:
banner
(Optional) If specified, then the argument given will be queued as the first song when the show rotates on the air. This can be helpful for having a certain announcement be played to announce an upcoming show.
end
Time the show is to stop playing. Same format as start time.
dir
The directory which to use for music for this show. This will also recursively include music in all subdirectories of this directory. This can also be the name of an M3U playlist, if the show is to be playlisted (see the "type" variable).
name
A brief description of the show. Used only for informational purposes; can be any string.
repeat
How often the show is to repeat. Only the "daily" and "weekly" frequencies are currently supported. If the show is to be weekly, then the "when" directive must also be used.
start
What time the show is supposed to start, in 24-hour military time. The time format can be given in the format HH:MM, or simply HH. Currently, the UBS schedules shows in even 30 minute blocks.
type
Type of show to schedule. Value can either be "random", or "m3u". In the case of the former value, the "dir" parameter must point to a directory tree containing music files, which will be queued at random. For type "m3u", the "dir" parameter must be the name of a m3u playlist, which will then be queued up exactly as it appears.
when
(Only needed if show is "weekly") Specifies what day of the week the show should occur. Recognized values are "sun", "mon", "tues", "wed", "thurs", "fri", and "sat".
Other directives for the sched context include:
miscdir
Location to queue music from if no valid show is found for the current timeslot. (Default: "misc", which is a subdirectory of the UBS prefix)
searchback
How far back to look in the logfiles for potential matches. For example, if this value is set to 10, then no two songs will be queued up by the same artist, song title, or filename until at least 10 other songs have been played. (Default: 30)
For events to be used by the ubs-event daemon, a similar structure is used to that of the shows. In the configuration file, the following directive must be set:
event.numevents = "?"
Where '?' again corresponds to the number of events that will be declared in the configuration file. The format of events is similar to that of shows; each event is given a context in the format of "eventN", where 'N' is the number of the particular event. Each event must contain the following parameters:
eventN.name = "program arguments"
eventN.time = time
eventN.logfile = "logfile"
As in the show configuration, an event must have all of the above parameters to be a valid. Subcontexts for the particular events are:
logfile
Where to log success of the event. Note that this is not by default a file in the logging directory, and this must be specified with a path as "log/name.log" to be stored in the UBS's logfile location.
name
The event to run. Unlike the name given for shows, this corresponds to the event to run. The program must be the name of an executable located in PREFIX/bin. Arguments to this program are optional, but permitted.
time
When to run the event. If given as a flat number (such as "30"), the event will be played every hour at that time. Otherwise, a specific time can be given (such as "12:30"), and the UBS will only play that event at 12:30pm, once a day.
Note that the UBS configuration file allows for additional, user-defined contexts. This can be very useful when writing custom modules. Note that most UBS daemons simply only parse for the "global" context and their own respective context. Additional contexts can be safely ignored.


[] [] [] []
Next: Running the UBS Up: Unattended Broadcasting System User Previous: Installing the UBS   Contents
2003-10-30