# Rivendell Radio Automation System

Operations Guide
Fred
Gleason
Paravel Systems LLC

          41 West Lee Highway, Suite 59
          Warrenton
          VA
          20186

v1.0.0
-2003-2017
Fred Gleason

## System Overview

### Introducing Rivendell

Rivendell is a digital audio content management and delivery system that is targeted for use in professional radio broadcast environments. It includes robust tools for the acquisition, organization, management and play out of audio material from and to a diverse array of sources and destinations. Support for a wide variety of external third party hardware devices and software packages commonly used in the radio industry is featured, including interfaces for:

- Audio Routing Switchers
- Satellite Downlink Receivers
- Audio Mixing Consoles
- Commercial Traffic and Music Scheduling Systems

Rivendell is made available under the terms of the GNU General Public License version 2 (GPLv2), a copy of which can be found in Appendix A. As such, it comes with absolutely no warranty, not even the implied warranties of merchantability or fitness for a particular purpose. See the full text of the GPLv2 for details.

Rivendell has been designed and developed from the ground up to run on the popular and highly stable GNU/Linux operating system. Selected tools (mostly having to do with log generation) have also been ported to run in the Microsoft Windows environment as well. Full source code as well as binary installation packages for Windows and select Linux distributions are available on line. Consult the Rivendell Technical and Administration Guide for details.

Rivendell has been designed to be able to operate in a wide variety of roles, ranging from single, self-contained workstations to large, multi-station clusters consisting of multiple workstations and centralized servers. Also included are redundancy and hot-standby capabilities to allow for reliable operation even in the presence of hardware faults. Details can be found in the Rivendell Technical and Administration Guide.

Rivendell is implemented as a set of interactive tools or 'modules' that collectively provide the complete functionality of the system. Briefly, these modules and their functions are:

RDAdmin
  System wide configuration
RDLibrary
  Library content management
RDCatch
  Automatic event scheduler
RDAirPlay
  On-air play out application
RDLogEdit
  Log editing and voicetracking tool
RDLogManager
  Automated log generation and interface utility
RDLogin
  Set the current user on a Rivendell host
RDCartSlots
  Emulate a traditional broadcast cart machine
RDPanel
  Large "cart wall" application
RDCastManager
  Podcast feed manager

The operation of each of these modules is explained in detail in the chapters that follow. However, we first need to cover some basic concepts common to all Rivendell modules.

#### The Rivendell Security Paradigm

All Rivendell modules make use of the following four classes of system resources:

- Hosts
- Users
- Groups
- Services

We'll cover each of these concepts in turn.

##### Hosts

Every physical computer within a given network that is running Rivendell software is referred to as a host. Any host in a Rivendell network can be individually configured and controlled from any other host (provided the system administrator has enabled this capability). Hosts can be used for a wide variety of applications, including content ingestion and management, automatic recording (sometimes referred to as netcatching), on-air play out or log (sometimes also referred to as playlist) generation. It is also possible for a single host to perform all of these functions.

##### Users

Every host on a Rivendell network has one or more users available to it. In this context, a 'user' is merely a set of access policies established by the system administrator that defines what tasks a given host is or is not allowed to perform. Every host has at least one user, called the default user. As the name suggests, this is the set of user policies that are loaded by default when the system starts up. It is also possible to change the user currently in use on a given host by running the RDLogin module.

##### Groups

A Rivendell group is a system of categories that is used by the audio library to classify and organize the audio within the library. Groups are a very powerful capability, and many operations within Rivendell can be specified on the basis of group membership. The actual classification scheme, including the number of available groups and their names, is completely arbitrary so as to allow each facility to tailor a schema that best fits its own operational requirements. Designing and implementing the group schema is one of the most important tasks facing the Rivendell system administrator, as a well-designed schema can make long-term maintenance and management of the system substantially easier vis-a-vis a poorly thought out one. We will cover groups in detail in the chapters devoted to the RDLibrary and RDAdmin modules.

##### Services

Every facility at which Rivendell is deployed is presumed to have one or more ultimate destinations for which audio is intended. These could be radio stations (e.g. WAVA), satellite uplink channels, live Internet audio streams, or any mix of the above. Each of these sorts of destinations is referred to in Rivendell as a service, and certain parameters, particularly as regards audio play out and log (playlist) creation, can be configured on the basis of what particular service is being referenced.

#### The Rivendell Hardware Paradigm

In addition to the core computer hardware (CPU, motherboard, etc), each Rivendell host typically interacts with specialized hardware required to accomplish the task at hand. Three main categories of such 'special' hardware are of interest to us here, the three being audio adapters, serial ports and GPIO/switcher devices. We'll cover each below.

##### Audio Adapters

An audio adapter in Rivendell is simply a device or facility for getting audio into and/or out of a host on a realtime basis. Most commonly this will be a sound card, although other, more exotic possibilities (using TCP/IP networking or direct routing to other audio applications) also exist. The three main classes of audio adapters supported by Rivendell are:

Advanced Linux Sound Architecture (ALSA)

  The standard Linux sound card driver starting with the 2.6.x kernel series, ALSA supports a huge array of commercially available sound cards, ranging from entry level 'game' cards to high-end cards aimed at professional audio uses. More information, including a current list of supported cards, is available at the ALSA web site, http://www.alsa-project.org/.

HPI Adapters

  These are high-performance sound cards manufactured by AudioScience Corporation. Designed and built specifically for broadcast automation applications, many feature advanced capabilities (such as on-board MPEG codecs and AES3 i/o) specially aimed for use in that setting. They are so-called because Rivendell uses AudioScience's special 'HPI' driver to access and control them. More information is available at AudioScience's web site, http://www.audioscience.com/.

JACK Audio Interconnect Kit

  JACK is not a particular set of hardware devices, but rather an audio 'framework' that allows compliant applications to share audio resources and route audio in realtime amongst themselves. JACK is different from similar efforts within the Linux realm in that it was designed from the ground up for professional audio work, with particular focus upon low-latency operation and synchronous execution of all clients. More information can be found at the JACK web site, http://jackit.sourceforge.net/.

##### Serial Ports

Commonly known in the DOS/Windows world as 'COM ports', serial ports are often used to communicate with outboard gear, such as satellite receivers and audio switchers. Up to eight serial ports can be accessed simultaneously by each Rivendell host.

##### GPIO/Switcher Devices

Because these capabilities are often (although not always) bundled together in the same device, Rivendell lumps GPIO and switcher devices together within the same class. GPIO stands for 'General Purpose Input Output'. As the name implies, these devices can be used to interface to a huge variety of outboard equipment by means of control lines. GPI (General Purpose Input) lines can be used to sense changes in an outboard system's state (and Rivendell programmed to take various actions on the basis of that), while GPO (General Purpose Output) lines can be used to send commands to an outboard system. The actual physical interfacing of GPIO devices is complex and generally beyond the scope of this document. Readers are encouraged to consult a good handbook on radio engineering for more information. A current list of GPIO/Switcher devices supported by Rivendell can be found in 'docs/GPIO.txt' file in the Rivendell sources.

## Managing the Current User with RDLogin

### RDLogin

Rivendell uses a sophisticated system of user privileges to keep track of which users have permission to perform what operations. These privileges are tracked by the system on the basis of user accounts. Creating user accounts and administering their permissions are done in the RDAdmin module and are covered in the Rivendell Technical and Administration Guide.

It's important to note that these user accounts are not the same thing as the “Login Name” that is used to log into the computer system itself. Rather, they exist and have meaning only within the Rivendell system. For the rest of this discussion, when we talk about “users”, it is these “Rivendell users” that we are referring to.

Each Rivendell host has a default user. As the name implies, this is the user that is automatically logged in after the system is booted. By default, the name of this user is “user”, but the system administrator may have changed this to some other name.

For many sites, a single default user is all that is ever required. For some sites however, particularly larger ones, it is desirable to have multiple user accounts, each tailored to a particular person or “role”, with privileges assigned appropriately. Such sites require a means to log different users in and out of the system, without interfering with any playout operations that may be ongoing at the time. RDLogin is the module for doing this.

RDLogin will display a small window after being started, showing the currently logged-in user (see Illustration 1). To change to a different user, select the desired user name from the Username: control, enter the correct password, and then touch the Set User button. To “log out” of the system (in reality, just return to the default user), simply touch the Default User button (no password is required to set the default user). To exit RDLogin and do nothing, simply touch the Cancel button.

## Content Management with RDLibrary

### The Rivendell Library Structure and RDLibrary

#### Carts

The Rivendell Library consists of a set of objects called carts. A cart is a data container that holds either one or more pieces of audio (called an audio cart), or macro commands to the system (called a macro cart). The cart is the fundamental schedule building block in Rivendell, in that it is the smallest object or 'atom' that the outside world (like a traffic or music scheduler) can see.

RDLibrary, upon startup, will show the current list of all carts on the system, as in Illustration 2 below:

A number of important attributes of carts can be seen from this illustration. First is the cart's number. Each cart in the Library gets assigned a unique number when it is created. This number can range between 000001 and 999999, and is the primary 'handle' by which both Rivendell and external systems (like traffic or music schedulers) refer to the cart. Very often, sites have specific rules concerning which types of audio (commercials, promos, music, etc) and macros get assigned which numbers. We'll cover this area in some detail when we discuss groups.

Immediately to the left of the cart number is an icon indicating the type of cart. Just to the right of the cart number is the average length of the cart. Except in the case of where timescaling is in use (in which case it will be indicated in blue numerals), this value is calculated automatically by the system.

Next comes various columns showing information from the cart label – Title, Artist, Client and Agency data, etc. This information can be edited by opening RDLibrary's Edit Cart dialog (Illustration 3), either by double-clicking on the desired cart entry in the list, or by touching the desired cart entry and then touching the Edit button. In either case, you should get a dialog similar to that shown in Illustration 3.

Near the center of the dialog will be a dropdown box labeled `Schedule Cuts`. When set to `By Weight` (the default), this will allow cut rotation to be managed by means of daypart settings (see ). When set to `By Specified Order`, the precise rotation of the cuts within the cart can be set manually.

This is how an audio cart looks when loaded into the Edit Cart dialog. The upper half of the dialog is the cart label data. The meaning of most of these fields should be fairly self-evident, but a few call for special comment:

Enforce Length

  When checked, this indicates that timescaling should be applied to this cart when it is played in RDAirPlay, meaning that the cart will air at the length indicated by the Forced Length field, rather than the native length of the audio. Care is needed when implementing timescaling within a facility, as there are limits to how much the length can be altered, while only certain types of audio adapters support it at all. See the Rivendell Technical Guide for more information.

Group

  This is a pull down menu by which the group ownership for the cart can be set. The system administrator configures the list of available groups for each user in RDAdmin.

User Defined

  As the name implies, this field has no dedicated meaning to Rivendell itself, but is provided for each site to use as is seen fit.

The example in Illustration 3 shows an audio cart. As such, the bottom half of the dialog displays the lists of cuts contained within the cart.

#### Cuts

Each audio cart can contain one or more cuts. A Rivendell cut is an actual piece of audio, somewhat analogous to a 'track' on a CD. Up to 999 such cuts can exist within a single cart. Each line in the cut list contains information about the cut, including:

`WT`

  The weighting value for the cut. see for discussion.

`ORDER`

  The order value for the cut. see for discussion.

`DESCRIPTION`

  n arbitrary name, assignable by the user as an aid in keeping track of the content, it is roughly analogous to the 'Title' field in the cart label.

`LENGTH`

  The actual, measured play out length of the cut audio. This field is calculated automatically by the system.

`LAST PLAYED`

  he last date and time that the cut was aired by one of the on-air modules. Useful for keeping track of stale inventory.

`# OF PLAYS`

  The total number of times the cut has been aired by the one of the on-air modules.

`ORIGIN`

  The name of the host upon which the audio in the cut was last recorded, along with the date and time.

`OUTCUE`

  A user settable field. This line shows up in the RDAirPlay log when the cut is played.

`START DATE`

  The effective start date/time of the cut.

`END DATE`

  The effective end date/time of the cut.

`START DAYPART`

  The start time of the cut's daypart.

`END DAYPART`

  The start time of the cut's daypart.

`NAME`

  The internal CUTNAME of the cut as used in Rivendell's database.

`SHA1`

  The SHA-1 hash value of the cut's file in Rivendell's audio store.

##### Multiple Cuts in a Cart

What happens when more than one cut is placed into a cart? The answer, in a word, is rotation. Rotation is the ability to schedule a single cart in a log, but to have that cart play out different material at different times. This capability has a myriad of uses. One of the simplest, common in commercial radio facilities, is to allow multiple versions of a spot to be placed into the system, while still allowing the traffic department to have to track and schedule only one cart number. A more sophisticated use involves use of the cut's dayparting settings, forcing different cuts to play based upon certain date/time criteria, such as day of the week or time of day. Cut dayparting is a very powerful feature in Rivendell, and is something we will discuss shortly.

To edit the properties of a cut, either double-click its entry in the cut list, or touch it once to highlight and then touch the `Cut Info/Record` button. The Record Dialog (Illustration 4) will now open up.

Roughly the upper third of the dialog is for editing the various cut parameters, the middle section is for configuring the cut's daypart settings, and the bottom third is a record machine that can be used both to record new audio into the system and to audition any recording already made.

##### Cut Dayparting

For carts for which `Schedule Cuts` is set to `By Weight`,each cut in can be dayparted on the basis of these parameters:

- Weight
- Absolute Start and End Date-Time
- Relative Start and End Time
- Day of the Week

While not strictly a dayparting parameter, the `WEIGHT` setting of a cut can strongly influence the order (and hence placement) of when a particular cut will play. The weight value of each cut in a cart consistutes the numerator of a fraction, the denominator of which is the sum of the weight values of every cut in the cart. Rivendell's cut selection algorithm will seek to play each cut in like proportion. If it is important in some cases to be able to specify the precise order of each cut play-out, consider changing the `Schedule Cuts` dropdown to `By Specified Order`.

By default, each newly created cut in a `By Weight` cart starts out with dayparting disabled, meaning that it will be 'eligible to play' at all times. By clicking the `Enabled` radio button in the `Air Date/Time` box, an absolute start and end date for the cut can be entered, meaning that the cut will be prevented from airing in the on-air modules at any time outside the range of those date-times. Likewise, by selecting the `Enabled` radio button in the `Daypart` box, start and end times (relative to the day the cut is to air) can be entered. Cuts designated in this way will be allowed to air only within the specified range of times. Finally, by ticking or clearing the appropriate boxes in the `Day of the Week` box, a cut can be constrained to air only on certain days of the week.

All of the dayparting parameters can be used either singly or in combination with each other. When combined, the resulting 'eligibility' is calculated as the logical AND of the applied dayparting limits. For example, a cut with the 'Monday' box cleared will refuse to air on Mondays, regardless of whether any of the other daypart rules match.

It's important to remember that dayparting rules affect audio play out only within the on-air modules. You will still be able to audition and play the audio without limitation in the other Rivendell modules.

##### Cart and Cut Color Coding

Each cart or cut in RDLibrary is assigned a color to indicate it's 'playability' for air, as follows:

NO COLOR

  Event will play normally

CYAN

  Event will not play (cut datetime is in the future)

RED

  Event will not play (outside of dayparting limits or audio is not available)

GREEN

  Event will play an Evergreen

It's important to remember that the color displayed for each event indicates playability at the instant that the event is being viewed.

##### Recording and Auditioning a Cut in the Record Dialog

The lower third of the Record Dialog is used both to audition and record audio. To audition the cut, simply press the play button (the one with the triangular symbol). The button will illuminate, audio will show on the bar meter and start playing immediately. The audio will play to completion, unless either the stop button (square symbol) is pressed, or the Record Dialog is closed.

To record new material into a cut, first ensure that the `Channels` drop-down menu is set to record the appropriate number of channels, then touch the `Record` button (round symbol). If the cut contains audio that was recorded previously, a warning box will pop up at this point to inform you of this and to give you a chance to abort the recording without erasing what was previously recorded. If `Yes` is selected here, the previous recording will be overwritten and no longer accessible. The `Record` button will now be illuminated steadily, while the `Play` button will be flashing, indicating that the record machine is in 'ready' mode. The bar meter will also be active to indicate input levels, and this is the point where you want to verify that your levels are correct, with peaks just into the yellow area being optimal. Nothing is actually being recorded just yet.

We have two options for actually starting the record machine. We can start it manually by pressing the `Play` button, at which point the machine will immediately begin recording, or we can set the `Record Mode` drop-down menu to the `VOX` (short for voice activated) setting. When in `VOX` mode, the record machine will start automatically as soon as it senses the presence of audio at the input.

Once started, recording will continue until either the `Stop` button is pushed, or the maximum allowed length for a manual recording (set by the system administrator) has been reached. Once stopped, if the `AutoTrim` drop-down menu has been set to `On`, the Start and End markers will be automatically set to the beginning and end of detected audio within the cut. (We will discuss Markers in detail when we get to the section on the Edit Markers dialog).

### Alternative Methods of Audio Ingestion

In addition to manually recording material in realtime, RDLibrary supports two alternative methods for audio ingestion:

- Importing from a File
- Ripping from a CD

#### Importing Audio from a File

To import audio from a file directly into a cut, we start by opening the cut's parent cart in the Edit Cart Dialog. Next, touch the cut's entry in the cut list and then touch the `Import/Export` button to open the Import/Export Audio Dialog (Illustration 5).

Select the file you wish to import, either by entering the path and filename to it in the `Filename` field or by clicking the `Select` button to open a file browsing dialog. Rivendell is capable of importing the following types of audio files:

- Microsoft WAV (*.wav) – PCM16, PCM24 and MPEG are supported
- MPEG (*.mp1, *.mp2, *.mp3)
- OggVorbis (*.ogg)
- Free Lossless Audio Codec [FLAC] (*.flac)

Next, set the `Channels` drop-down menu to the appropriate number of channels. You may also wish to adjust the `Normalize` or `Autotrim` controls, although these will normally be set to reasonable default values by the system administrator and should seldom have to be altered. If `Normalize` is selected, then the imported audio will be peak normalized to the level indicated. The `Autotrim` does the same thing as in the Record Dialog (see section 2.0.1.2, 'Recording and Auditioning a Cut in the Record Dialog' above for details).

Finally, touch the `Import` button. A progress bar will indicate percentage completion of the import, followed by a popup box to announce completion. The Import Audio Dialog will automatically close after acknowledging completion. The audio is now imported, and can now be auditioned and otherwise processed in the usual way.

#### Ripping Audio from a CD Track

To rip audio directly off of a CD into a cut, we again start by opening the cut's parent cart in the Edit Cart Dialog. Next, select the cut's by touching the cut's entry in the cut list, and then touch the `Rip` button to open the Rip CD Dialog (Illustration 6).

Load a CD into the CD drive. After a few seconds, list of tracks should appear in the Tracks area. If the system administrator has enabled the FreeDB CD Lookup Service, the names of the various tracks may appear as well.

Set the `Channels`, `Normalize` and `Autotrim` controls appropriately (see section 2.1.0 for more details on using the `Normalize` and `Autotrim` controls). Next, touch the track you wish to rip and then press the `Rip Track` button. The track will now be ripped into the cut, with a progress bar keeping you informed of progress. When the rip is complete, a message box will pop up to inform you of this.

If FreeDB data was found for the CD, you can have the FreeDB track, artist and album names be automatically placed on the cart label for the cart by checking `Apply FreeDB Values to Cart` before closing the Dialog.

#### Ripping Multiple CD Tracks at a Time

Sometimes, when transferring multiple audio tracks from CD, it's more convenient to be able to set up the entire transfer at once and then let the rip run in a 'batch' mode. RDLibrary is capable of ripping audio in this manner as well. To do this, click the `Rip CD` button near the bottom of the main RDLibrary screen, bringing up the Rip Disk Dialog (Illustration 7).

This dialog is similar in many ways to the Rip CD Dialog described above, except that each track can be assigned to transfer to a different cut by double clicking on its listing, or by touching the listing and then the Set Cut button, bringing up the Select Cut Dialog (see Illustration 8).

The destination cut is selected by first choosing the cart from the left-hand pane, followed by the desired cut within that cart on the right-hand pane. The complete set of library filtering tools are available to you here – see section 2.2, 'Navigating the Audio Library' for details on their function, just as in the main RDLibrary screen.

Once all of the desired tracks have been assigned to cuts, be sure that the `Normalize`, `Autotrim`, `Channels` and `Apply FreeDB Values to Cart` controls have been set as desired, then click the `Rip Disk` button. A set of progress bars will keep you informed of the progress of each track, as well as overall progress. When, the rip is finished, a message box will let you know.

### Macro Carts

A macro cart is a cart that contains one or more commands written in Rivendell Macro Language (or 'RML' for short). The Edit Cart dialog for a macro cart is similar in many ways to that for an audio cart with the exception of the lower half, which contains a list of RML commands to be executed rather than a list of cuts (see Illustration 9). (NOTE: for a complete description of Rivendell Macro Language, including a breakdown of available commands, see Chapter Nine).

To add a new line of RML, select the desired location in the list and touch the `Add button`. Similarly, a line can be deleted by selecting it and then touching the `Delete` button, or modified by touching the `Edit` button. The RML can be tested, eight line-by-line or as a whole by touching the `Run Line` or `Run Cart` button respectively. It is also possible to `Copy` and `Paste` individual lines both within a given cart or between carts.

### Navigating the Audio Library

The uppermost section of RDLibrary's main window contains tools designed to allow for fast searching of the entire audio library, making locating a particular piece of audio easy even in a library containing thousands of carts. It's possible to control what carts are listed, as well as how they are sorted.

#### Changing the Cart Sort Order

The order in which carts are displayed in the cart list can be changed by simply clicking on the header of the column by which you want them sorted by. By default, the carts are sorted by Cart Number. To instead sort them alphabetically by Title, simply click the `TITLE` header once. To sort them by Title in reverse –i.e. from 'Z' to 'A' – click the `TITLE` header once again. Clicking the `TITLE` header a third time restores the sort to normal 'A' to 'Z' again. And so on for all of the columns in the cart list – it's possible to sort the Library by `ARTIST`, `LENGTH`, or any other parameter shown in the cart list.

#### Selecting Carts by the Filter Field

Very often, one will want to find a cart or set of carts whose label(s) contains a particular word or phrase. It's possible to narrow the list of displayed carts to this set by simply entering the desired word or phrase into the `Filter` field at the top of the main RDLibrary screen. The full list can be restored by clearing the `Filter` field or by clicking the Clear button.

#### Selecting Carts by Group

It's possible to limit the list of carts to only those in a particular group by setting the `Group` drop-down menu to the desired group name.

#### Selecting Carts by Type

You can tell RDLibrary what type of carts to list by checking the `Show Audio Carts` and `Show Macro Carts` boxes. Clearing both boxes obviously results in no carts at all being displayed.

It's also possible to combine all four of the above search and sorting methods.

#### Selecting and Opening Carts

Once the desired cart has been located on the cart list, load it into the Edit Cart Dialog (Illustration 3) by either double clicking its list entry, or by touching its list entry and then touching the `Edit` button.

### Library Maintenance

#### Editing Markers

Rivendell uses a system of cue points within audio cuts, referred to as markers. Markers can be used to specify a number of parameters for a piece of audio. Consult to see what markers are available, their purpose and their corresponding color.

Markers are set in the Edit Markers Dialog (see Illustration 10). To access the Dialog, open an audio cart, select the cut to open on the cut list and then touch the `Edit` button.

The Dialog is divided into three areas: the waveform area in the upper half, consisting of the waveform display and `Amplitude` and `Time` buttons; the transport controls area in the center, consisting of `Start`, `Pause`, `Stop` and `Loop` buttons along with an audio meter; and the marker button area in the lower third of the window, consisting of controls for selecting and positioning markers.

It's possible to 'zoom-in' on the waveform in various ways by clicking the `Amplitude` and `Time` buttons. By default, the waveform is displayed fully 'zoomed-out', thus showing the entire length of the audio cut. The `GoTo` buttons can be used to jump directly to the current play out cursor position, start or end of the waveform.

Audio can be played one of two ways: either by clicking on the waveform to indicate where play out should start and then clicking the left-hand `Play` button, causing play out to start from the selected position, or by clicking the right-hand `Play` button, which will cause play out to start from the Start Marker (just as it would in RDAirPlay). Clicking the `Pause` button while playing will cause audio to stop and the play out cursor (a thin vertical black line in the waveform area) to freeze at its current position, while pressing the `Stop` button will stop the audio while resetting the play out cursor to the position it was in when `Play` was started. Clicking the `Loop` button will cause the audio to play out continuously, looping from end back to start, until either the `Stop`, `Pause`, `Save` or `Cancel` buttons are clicked.

To set a marker, click on the corresponding marker button and then left-click on the waveform area to indicate where on the audio the marker should be placed. (NOTE: With the exception of the FadeUp and FadeDown markers, all markers in Rivendell are assigned in pairs. For example, placing a TalkStart marker will also cause a TalkEnd marker to be placed.) Markers that have already been placed can be moved by selecting the appropriate marker button and then dragging the marker to the desired location. It's also possible to specify the position of a marker in the form of hh:mm:ss.s (relative to time after the Start marker) by entering the desired value next to a selected marker button. It is also possible to remove a set of markers that have already been placed, either by accessing the marker menu by doing a right-click on the waveform display, or by touching the `Remove Marker` button and then touch the marker button corresponding to the marker to be removed. (NOTE: the exceptions to this are the Start / End markers, which are always present and hence cannot be removed.)

##### Rivendell Marker Types

Marker Type | Function | Color
--- | --- | ---
Start / Stop | Indicates start and end points of audio. | RED
TalkStart / Talk Stop | Indicates point to start and stop the Talk Counter in RDAirPlay. | BLUE
SegueStart / SegueEnd | Indicates the start and end of the audio overlap during Segue transitions in RDAirPlay. | CYAN
HookStart / HookEnd | Indicates "highlighted" audio, used by button panels and RDCartSlots when placed in Hook Mode. | VIOLET
FadeUp | Indicates the point at which audio should be faded up to full level after starting in RDAirPlay. | YELLOW
FadeDown | Indicates the point at which audio should start fading down to off before ending in RDAirPlay. | YELLOW

As an aid for accurately setting the Start and End markers, it's possible to use the `Trim Start` and `Trim End` buttons to automatically set the markers to the first and last instances of the level specified by the `Threshold` field, respectively.

#### Copying and Pasting Audio from Cut to Cut

It's possible to make copies of existing an audio cut on the system by opening up the cut's parent cart in the Edit Cart Dialog, selecting it on the cut list and clicking the `Copy` button. To paste the copied audio, simply select the desired destination cut (within the same cart or a different one) and press `Paste`.

### Generating Library Reports

Various Library reports can be generated by touching the `Reports` button on the main RDLibrary screen and then selecting the desired report and touching the `Generate` button. The following reports are available:

#### The Cart Report

The cart report consists of a list of all selected carts on the system, with their attributes.

#### The Cut Report

The cut report consists of a list of all cuts contained by the selected carts on the system, with their attributes.

#### The Cart Data Dump (fixed width)

The fixed-width cart data dump is a special type of report that consists of column-aligned data elements, one line per cut for the selected carts on the system. It is intended for use where a 'dump' of available carts in the system is desired for import into an external system (such as a music scheduling system).

#### The Cart Data Dump (CSV)

The CSV cart data dump is a special type of report that consists of CSV formatted data elements, one line per cut for the selected carts on the system. It is intended for use where a 'dump' of available carts in the system is desired for import into an external system (such as a music scheduling system).

## Automating Tasks with RDCatch

### Choosing the Correct Automation Tool

Rivendell includes two modules specially optimized for performing automatic operations: The RDCatch and RDAirPlay modules. The two modules take radically different approaches in how they go about organizing and controlling operations, so a few words regarding each may be in order here.

RDCatch is aimed at executing actions on the basis of a strict time-based schedule, referred to as an event list. Each action (which can be a recording, a play out, an up- or download, a macro execution or an operation on an audio switcher device) executes on the basis of its scheduled time in the event list, independently of all other actions. As such, RDCatch is often best suited for use in settings such as network head end operations or 'auxiliary' roles at broadcast stations, where the transitions between events are generally not an important part of the presentation.

RDAirPlay takes a very different approach, in that most events are organized into one or more playlists or logs. A Rivendell log is a list of one or more carts, organized in chronological order. As the name implies, RDAirPlay is optimized for use in situations where the transitions between the various program elements are a key part of the delivery and presentation of the content, such as in live air play environments.

Of course, it's entirely possible to use both modules, even together on the same machine at the same time – the Linux OS makes for a very robust and capable multitasking system.

### The RDCatch Main Window

After starting up RDCatch, you should see the main RDCatch window, looking something like Illustration 11. The window consists of four areas: the record / play out decks at the top, the filter areas just below the decks, the events list and the audition buttons and other buttons at the bottom. We'll cover each of these in turn.

#### The Record / Play Out Deck Area

If the system administrator has configured one or more RDCatch record or play out decks, they will be visible at the top of the RDCatch main window. A record deck is a virtual 'recorder' that can be used to make automated recordings, while a play out deck can be used to automatically play out audio. It does not matter on which particular host a particular deck 'resides' – all Rivendell decks throughout the system are visible in RDCatch, regardless of which host it is run upon.

Starting at the left-hand edge of each deck, there is the deck's name, consisting of the name of the deck's host machine followed by a number and a letter, an 'R' to indicate a record deck and a 'P' to indicate a play out deck. Next, for record decks, there is a MON button, used to monitor the audio present at the deck input, followed by an ABORT button, used to manually stop an event running in the deck. A description of the currently running event next appears (this area will be blank if no event is currently active), followed by the deck's status, which could be any of the values shown in Table 2.

##### RDCatch Event States

Status | Meaning
--- | ---
IDLE | The deck is available for events
READY | The deck has started monitoring audio but the transport is not yet rolling (record decks only).
WAITING | The deck is waiting for a GPI event (record decks only)
RECORDING | The deck is recording (record decks only)
PLAYING | The deck is playing out (play out decks only)
OFFLINE | The deck is configured but not available

Finally, each deck has an audio meter on its right-hand end, used to verify audio levels in realtime.

#### The Filter Area

Immediately below the decks is the filter area, consisting of the Show Only Active Events, Show Only Today's Events and Show DayOfWeek controls. These controls are used to select which events will be visible in the events list area immediately below.

#### The Event List

The event list is a system wide list of all events to be executed by RDCatch on all of the various hosts on the Rivendell network, with each event occupying a single line. The status of each event is indicated by its background color, as shown in Table 3.

##### RDCatch Event State Colors

Color | Meaning
--- | ---
YELLOW | The event is next to be executed.
GREEN | The event is active.
CYAN | The event is in the READY state.
VIOLET | The event is in the WAITING state.
RED/PINK | The event is reporting an error.

Each entry in the event list starts with an icon that indicates the type of the event, as shown in Table 4.

##### RDCatch Event Icons

[RECORD_ICON] | Record Event
[PLAYOUT ICON] | Play Out Event
[SWITCH ICON] | Switch Event
[MACRO ICON] | Macro Event
[UPLOAD ICON] | Upload Event
[DOWNLOAD ICON] | Download Event

Next on each line comes the description (settable by the user) and location for the event, the location being the name of the host/deck where the event will run. Then, comes the start and end parameters. These time-based parameters come in one of three different forms: a hard time, which is simply an absolute time (in twenty-four hour 'military' format), a length (in HH:MM format, relative to an earlier start time), or a GPI start. The GPI parameters can be somewhat involved. They are specified in the following format:

Gpi: <start-time>,<end-time>,<gpi-num>,<wait-time>

Where:

<start-time>

  The time, in HH:MM:SS format, when RDCatch will start looking for a GPI event (also sometimes referred to as the window start time).

<end-time>

  The time, in HH:MM:SS format, when RDCatch will stop looking for a GPI event (also sometime referred to as the window end time).

<gpi-num>

  The number of the GPI event to wait for, in the format MATRIX:LINE. We will deal with GPI matrix and line numbers in detail when we cover RDAdmin.

<wait-time>

  The amount of time to wait, in MM:SS format, between the reception of the GPI event and the actual start of the event (used only for Start parameters).

For example, the start parameter 'Gpi: 14:00:00,14:05:59,0:1,01:00' has a window start time of 14:00:00 [2:00:00 PM], a window end time of 14:05:59, looks for a GPI event on line 0:1 and will wait one minute [01:00] after receiving the GPI before starting the event.

Next come the source and destination fields. The uses of these will vary depending upon what type of event is being listed, but should normally be fairly self-evident. For example, for a record event, the source field indicates the audio source from which the recording is to be made, while the destination indicates the cat/cut combo to which the recording should be made. Some events may leave one or the other of these fields blank.

Now come the day of the week fields. These indicate on which days of the week the listed event should be executed, followed by the origin field, which is simply a readout of the Origin data of the events underlying cut. There are a number of other fields which follow, but these are less important for understanding the operation of RDCatch.

#### The Button Area

At the bottom of the main window are various buttons. On the left-hand side, the Add, Edit and Delete buttons are used to manage events in the event list. Clicking the Scroll button toggles RDCatch into and out of 'scroll mode'. In this mode, the event list display will be advanced automatically so as to keep the first actively running event centered within the event list area.

On the right hand side, in addition to Close, are three audition buttons. These buttons can be used to audition the head and tail of each cut referenced by an event, thus making it possible to quickly verify that a set of automatic recordings were properly executed.

### Adding New Events

A new event can be added to the event list by simply clicking the Add button to bring up the Add Event Dialog (see Illustration 12). Simply clicking the button that correspond to the desired type of event will create it.

### Automating Recordings

Automated recordings are configured by means of the Edit Recording dialog (see Illustration 13), which can be accessed either by clicking the Recording button in the Add Event dialog to create a new record event or by touching the Edit button to modify an existing event.

#### The 'Start Parameters' Section

The start parameters of each recording are configured in the 'Start Parameters' section. A recording can be programmed to start on the basis of the wall clock time, referred to the hard start time, or upon reception of a general-purpose input, or GPI event originated by a satellite receiver, tone decoder or other external device. Programming a hard start time is merely a matter of entering the desired start time, in 24 hour 'military' format. Programming a GPI start involves, in addition to entry of the GPI parameters themselves (matrix and GPI line numbers) that Window Start and Windows End times be entered, that define the 'window' during which reception of the appropriate GPI event will be 'recognized' by RDCatch. It is also optionally possible to specify a Start Delay between reception of the GPI event and the actual start of the recording.

#### The 'End Parameters' Section

The end parameters of each recording are configured in the 'End Parameters' section. A recording can be programmed to end on the basis of a hard time, its absolute length or in response to a GPI event. Programming of the Hard Time and Length parameters should be fairly self-explanatory, while the parameters needed to program a GPI event are similar to those used for the start parameters, with the exception of the 'Max Record Length' setting, which limits the maximum length of the recording in the event that the expected GPI event is never received.

#### Programming Multiple Recordings in a Single Event

If a record event is configured to use GPI for its start and Length or GPI for its end parameter, then it is possible to configure the event to make repeated, multiple recordings within a single event by checking the 'Allow Multiple Recordings Within This Window' box in the 'Start Parameters' section. This can significantly reduce the amount of required record events when capturing material with high on-air turnover, such as newscasts or traffic reports.

#### Selecting a Record Source

If the selected record deck (chosen in the Location drop-down menu at the top of the dialog) as been configured to operate with an audio switcher device, the appropriate audio input can be chosen from the Source drop-down menu.

#### Selecting a Record Destination

Each programmed recording must have a 'destination', a designated Cart/Cut which will hold the audio. The currently programmed destination is shown in the Destination field, and can be changed by clicking the Select button.

#### Setting the Active Days for a Recording

A check should be placed next to each day of the week for which a recording should be made in the Active Days box. If no days are checked, then no recordings at all will be made.

#### Record List Management with Event Active and Make OneShot

The record event will be actually executed only if Event Active (in the upper left corner of the dialog box) is checked. By clearing this box, it's possible to 'bank' a record event without actually having it run, useful for events that are only used sporadically.

For events that need to be executed only once, the Make OneShot box can be checked. Such an event will execute just once, and then automatically delete itself from the event list.

### Automating Playouts

Automated playouts are configured by means of the Edit Playout dialog (see Illustration 14), which can be accessed either by clicking the Playout button in the Add Event dialog to create a new record event or by touching the Edit button to modify an existing event. The process of configuring a playout is very similar to that for configuring a recording – see the relevant part of Section 3.3, 'Automating Recordings' above for details.

### Automating Uploads/Downloads

It's possible to use RDCatch to automatically upload and download material from both local and Internet-based servers. Automated downloads are configured by means of the Edit Download dialog, which can be accessed either by clicking the Download button in the Add Event dialog (see Illustration 15) to create a new record event or by touching the Edit button to modify an existing event.

With the exception of the Url, Username and Password controls, the process of configuring a download is very similar to that for configuring a recording – see the relevant part of Section 3.3, 'Automating Recordings' above for details.

The Url control is used to specify the Uniform Resource Locater for the material to be downloaded. The following download types are supported: http, ftp, smb and file. The URL field can also include wildcard characters that can be used to construct date-based URLs, as shown in Table 5.

The Username and Password fields are used to indicate the username and password required for access to the server referenced in the URL. For public web pages and anonymous FTP servers, these fields can be left blank.

Automated uploads are configured by means of the Edit Upload dialog (see Illustration 16), which can be accessed either by clicking the Upload button in the Add Event dialog to create a new record event or by touching the Edit button to modify an existing event. The following upload types are supported: ftp, smb and file. As with downloads, the URL field can also include wildcard characters that can be used to construct date-based URLs, as shown in Table 5.

Configuration of an upload event is very similar to that of a download, with the addition of the Export Format control. This is used to set what file format should be used for the upload. Depending upon what software encoders have been installed by the system administrator, the following export types may be available:

- PCM16 Linear (*.wav)
- Free Lossless Audio Codec [FLAC] (*.flac)
- MPEG Layer 2 (*.mp2)
- MPEG Layer 3 (*.mp3)
- OggVorbis (*.ogg)

The desired upload format and parameters are set by clicking the Set button.

### Automating Macro Execution

It's possible to configure the automatic execution of a Macro Cart by means of the Edit Cart Event dialog (see Illustration 17), which can be accessed either by clicking the Macro Cart button in the Add Event dialog to create a new Macro Cart event or by touching the Edit button to modify an existing event. The process of configuring a macro cart event is very similar to that for configuring a recording – see the relevant part of Section 3.3, 'Automating Recordings' above for details.

### Automating Switcher Operations

It's possible to configure an automatic operation on a switcher device by means of the Edit Switcher Event dialog (see Illustration 18), which can be accessed either by clicking the Switch Event button in the Add Event dialog to create a new switch event or by touching the Edit button to modify an existing event.

In addition to the usual fields, a switch event has Switch Matrix (the name of one of the switch matrices associated with the selected Location), Switch Input and Switch Output controls. When executed, a switch events causes a take operation to be performed on the specified switcher device between the specified input and output. It is possible to specify the input and output either by their alphanumeric names (assigned in RDAdmin) or by their absolute numbers.

## Generating and Maintaining Logs with RDLogEdit

### Logs and Log Events

A Rivendell log is a sequence of one or more events to be executed by the system, arranged in chronological order. (This functionality is sometimes referred to as a playlist in other automation systems). Several different types of events can be included in a log, along with parameters governing how and under what circumstances they will be executed.

Upon startup, RDLogEdit will show the current list of all logs on the system, as in Illustration 19. A number of important attributes of logs can be seen from this illustration, the first being the log name, with a summary status indicator next to it. The name is an alpha-numeric label that is used as a unique “handle” by the system to reference each log, and can be up to a maximum of 64 characters long. The status indicator is intended as a quick visual guide as to whether a particular log is ready for air (green check mark) or not (red ex).

Next comes the log's description. This is a free-form alpha-numeric label that can be used to record any information that might be useful to have appear on the log list (e.g. “This log for Sunday's show, don't modify!”).

Next comes a column showing the owning service. Each log is owned by exactly one service, which determines under what circumstances the log can be played and where electronic log reconciliation (ELR) data resulting from log playouts is sent (for an overview of Rivendell services, see section 1.1.3).

Next comes three “status indicator” columns ("MUSIC", "TRAFFIC" and "TRACKS") indicating the log's degree of readiness for air. A red indicator indicates that the particular data element is required but currently missing, a green indicator indicates an element is required and present, while a white indicator indicates that an element is not required. Additionally, the “TRACKS” column contains a pair of numbers indicating how many completed voice tracks exist in the log versus how many total track markers exist (the subject of voice tracks and track markers will be covered in more detail below). When all three of these status indicators show either green or white, the summary status indicator (at the beginning of the log's entry in the list) will show as a green check mark, while a red indicator in any of these three fields will show a red ex. (NOTE: because a log sports a red ex does not indicate that the respective log cannot be played. It is merely a visual indicator to allow logs to be quickly "eyeballed" for completeness).

Next comes a pair of columns indicating the valid start date and end date for the log.

Finally, there is a column indicating the log's origin –i.e. the place, date and time it was originally created.

A report that lists the available logs on the system can be generated by touching the Log Report button.

A new log can be created by touching the Add button and entering a name, or an existing log inspected and modified by touching its entry on the log list and then touching the Edit button, resulting in the log being opened in the Edit Log dialog as shown in Illustration 20. The Edit Log dialog consists of three parts: the top section, where much of the information shown on the log list can be inspected and modified; the middle section, which shows the list of events comprising the log, and the bottom section, where buttons for modifying and saving the log are located. Each event in a log can be one of several different types, indicated by the icon displayed at the start of the line (see Table 6 for a breakdown of the various icons). The following types of events can be incorporated into a Rivendell log:

#### Audio Carts

The first, and usually most common type of log event is an audio cart. As the name implies, audio carts are Library entries that contain audio material intended for playout. Audio carts were covered in detail in Chapter Two in the discussion about RDLibrary.

#### Macro Carts

A macro cart is a cart from the Library that contains one or more system commands that can be used to cause the system to take various actions. They were touched upon in Chapter Two in the discussion about RDLibrary, and will be discussed in detail in Chapter Seven.

#### Note Markers

A note marker is an entry in the log that contains text intended to be seen by operators and used as a guide or reminder (program coders sometimes refer to this sort of functionality as a remark or comment, as seen in the REM command used by BASIC programmers). Note markers belong to a class of log events known as meta events because (unlike carts, which exist in the Library independently of whether they are placed in a log or not), they have no independent existence outside of the specific log where they are placed. A note marker has absolutely no effect on the execution of a log other than to simply display some text at a specified point in a log, and as such can be useful as a mechanism for making notes or reminders to oneself or to others who may be executing the log.

#### Track Markers

A track marker is another meta event that is very similar in operation to note markers, with one key addition: track markers designate or "bookmark" a place in the log where a voice track is to be recorded. (The entire topic of voice tracks and tracking will be covered in detail in Chapter Eight). As with note markers, track markers have absolutely no effect on the execution of a log.

#### Chain Events

Each event in a log has a transition type, shown in the "TRANS" column of the Edit Log dialog. The transition type determines what happens when one event in a log ends and the next starts. Three basic transition types can exist in a Rivendell log: PLAY, SEGUE and STOP.

#### Import Links

An import link is a placeholder event that shows where events imported from the external music or traffic scheduling system will eventually go. They will be covered in detail in the chapter on RDLogManager.

Each event in a Rivendell log can have its parameters modified by touching its entry in the Edit Log dialog and then clicking the Edit button, thus opening up the Edit Log Entry dialog, shown in Illustration 21 for a cart event, or Illustration 22 for a meta event.

### Event Transitions

Each event in a log has a transition type, shown in the "TRANS" column of the Edit Log dialog. The transition type determines what happens when one event in a log ends and the next starts. Three basic transition types can exist in a Rivendell log: PLAY, SEGUE and STOP.

#### Log Event Type Icons

[AUDIO_ICON] | Audio Cart
[TRACK AUDIO ICON] | Voice Track Audio Cart
[MACRO ICON] | Macro Cart
[NOTE ICON] | Note Marker
[TRACK ICON] | Track Marker
[CHAINTO ICON] | Chain Event
[MUSICLINK ICON] | Music Import Link
[TRAFFICLINK ICON] | Traffic Import Link

#### The PLAY Transition

If an event has a PLAY transition, then it will begin playing when the previous event has finished. PLAY transitions are used when automatic event sequencing is desired with no audio overlap (such as when playing two voice-only announcements back-to-back).

#### The SEGUE Transition

SEGUE transitions are similar to PLAY transitions, with one key difference: if the finishing event contains segue data (either from the Library or from a custom transition programmed in the voice tracker), then the event will start before the prior event is finished, causing the two pieces of audio to overlap and mix together. SEGUE transitions can be a very powerful tool for creating a variety of special effects, particularly when used in conjunction with musical material.

#### The STOP Transition

As the name implies, STOP transitions cause execution of the log to be suspended prior to execution of the event. This is often the desired behavior in situations where the log playout needs to be synchronized to one or more external audio sources (such as remote satellite feeds), and is commonly used in conjunction with Hard Timed events (see below).

### Time and Time Types

All Rivendell log events have an associated time type, which controls what effect (if any) the passage of time will have on the event. There are two basic time types: relative and hard. Additionally, the hard time type has several additional options that further modify its behavior.

#### The Relative Time Type

The default time type for log events, a relative time type simply means that the event is assumed to have a start time of whenever the previous event ends (if it has a PLAY or SEGUE transition) or whenever it is started (if it has a STOP transition).

#### The Hard Time Type

A hard time type causes the event to be executed or otherwise acted upon when the wall clock equals the time associated with the event. Hard times are a powerful feature that can be used to synchronize the log to various external events. An event can be assigned a hard time by clicking the Start at check box in the Edit Log Entry and filling in the desired time, and will show up with the letter 'T' appearing at the beginning of its listed time in the "TIME" column of the Edit Log dialog. An event which has been assigned a hard time can also be set to be a Post Point by checking the Make Post Point check box (the concept of post points will be discussed in detail in the chapter covering RDAirPlay).

The specific action that is performed when the time matches is determined by the option parameters supplied as part of the event. Three basic actions are possible:

- Start the event immediately
- Cue to the event ("Make Next")
1
- Wait up to N Seconds, then start the event

##### Start Immediately

As implied by the name, if the event is set to start immediately, it will be started as soon as the hard time is reached. Any currently playing events in the log will be stopped down.

##### Cue to the Event ("Make Next")

If set to 'Make Next', the event will be cued up to become the next event to be executed in the log, bypassing any intervening events in the log between the currently playing event and the hard timed one. Any currently playing events are unaffected.

##### Wait up to N Seconds, then start the event

Very similar to "start immediately", with the difference that, if one or more events are currently playing, the log will wait up to the specified number of seconds before stopping them and starting the new event.

### Editing Log Event Parameters

#### Specifying a Cart

The cart number to use for an event can be specified by touching the Select Cart button in the Edit Log Entry dialog, which will open up the Select Cart dialog, as shown in Illustration 23. Alternatively, it is possible to simply enter the cart number in the Cart field if the number is already known. The Title and Artist information will be automatically supplied by the system from the cart's label.

#### Specifying Meta Event Parameters

Note marker and track marker events each take only a single parameter: a Comment text that will show up on the log entry. In the case of a chain event, the name of the log to chain to must be supplied in the Log Name field, or the Select button can be touched to bring up the Select Log dialog to allow a name to picked from a list of all those available. Note that meta events are assigned transition and time types just the same as cart events.

#### Rearranging Log Events

Existing events in a log can be cut, copied, pasted or rearranged by touching the appropriate buttons in the Edit Log dialog. In addition, touch the Delete button will cause the selected log event(s) to be removed from the log.

#### Saving or Abandoning Changes to a Log

Any changes made to a log can be saved by touching either the Save or OK buttons in the Edit Log dialog. The current log can be saved under a different name by touching the Save As button, while touching Cancel will abandon any changes made since the last save.

#### Missing/Invalid Cart Events

If a given event has a problem (such as referencing a cart that does not exist in the Library, or that is not enabled for play on the log's owning service) its entry will be highlighted either RED (indicating a missing/invalid cart) or MAGENTA (indicating a cart without permission to run on the owning service). It's also possible to generate an exception report summarizing problem cart entries by touching the Check Log button.

### Generating Log Reports

Various Log reports can be generated by touching the Reports button on the Edit Log dialog and then selecting the desired report and touching the Generate button. The following reports are available:

#### Log Listing

A chronological listing of all events in the log.

#### Log Exception Report

A list of missing/unplayable carts referenced in the log.

### Auditioning Audio

The audio referenced by an audio event can be sampled in the Edit Audio dialog by highlighting the desired event and then touching the play button. No attempt to evaluate the rotation logic of the event is made – the audio played is intended solely as a 'sample' to help identify the type of material.

## Running Logs with RDAirPlay

### Overview

RDAirPlay is the Rivendell module used to run logs generated by the RDLogEdit or RDLogManager (for an overview of Rivendell logs, see Chapter Four). It contains a wide array of features for enabling playout of audio content in live assist as well as fully automated environments.

### Log Machines

Fundamental to the operation of RDAirPlay is the concept of a log machine. A log machine is a virtual “device” into which a Rivendell log may be loaded and executed. RDAirPlay has three such log machines, called Main Log, Aux 1 Log and Aux 2 Log. Each of these log machines is completely independent of the others in the sense that different logs can be loaded and executed simultaneously in the respective machines.

### Layout

As shown in Illustration 24, the RDAirPlay main screen consists of four primary areas: the top area, which contains a variety of indicators for use in live assist situations as well as a set of audio meters; the button widget, which occupies the bulk of the left-hand side of the screen; the right-hand side, which displays either a SoundPanel array or a full log width; and the edit buttons in the lower left-hand corner of the screen.

The top area contains the following indicators:

#### The Wall Clock

In the upper left-hand corner is wall clock indicator, which indicates the current system date and time. The style used for displaying times throughout RDAirPlay can be toggled between 24 hour “military” format and the traditional “AM/PM” presentation by clicking once on this display. If the system administrator has enabled it, this display will also flash RED to indicate possible clock inaccuracy due to loss of master clock synchronization.

#### The Post Point Counter

Immediately to the right of the wall clock is the Post Point Counter. A post point is an attribute applied to a log event with a hard time type. The post point counter uses this information to display countdown and timing information.

The counter can be in one of four possible states: Idle, On Time, Under Time or Over Time. If the next upcoming hard timed event does not have its post point attribute set, then the counter will be in Idle mode (see Illustration 26). If the attribute is set however, then the counter will provide an estimate of how “on-time” the log currently is, on the basis of the current time and events still scheduled to be played.

If the playout is such that the post point will be reached within one second of its programmed time, then the counter will be in On Time mode (see Illustration 27). The value shown in the square brackets is the scheduled time of the point point.

If the playout is such that the post point will be reached one second or more before its programmed time, then the counter will be in Early mode (see Illustration 28). It will also give an indication of how much more material would need to be added to make the join on time.

If the playout is such that the post point will be reached one second or more after its programmed time, then the counter will be in Late mode (see Illustration 29). It will also give an indication of how much material would need to be removed to make the join on time.

#### The Audio Meter

Immediately beneath the wall clock and post point counter is the audio meter. The meter shows the current peak levels of audio being played out of RDAirPlay, with '0' level referenced to -16 dBFS.

#### The Pie Wedge Widget

In the top center of the top area is the pie wedge widget. This widget counts down the final few seconds of each event. The length of time it counts down, along with whether it counts to the start of the next transition or the absolute end of the event are both configurable in RDADmin. The color of the band that grows as the countdown progresses (shown RED in Illustration 31) will change color to indicate if the currently playing event is the last event before a log stopdown. If it is the last, it will be RED, if not, GREEN. A BLUE band and countdown will also appear to indicate the event's talk time (if talk time markers have been set in the underlying cart).

#### The Next Stop Counter

Immediately to the right of the pie wedge widget is the next stop counter. The large numerals indicate the predicted interval of time before the next stopdown of the Main Log machine, with the actual predicted time in the square brackets. If the Main Log is already stopped, then the counter simply displays 'Stopped'.

#### The Mode Indicator

In the upper right-hand corner of the top area is the mode indicator, showing the current automation mode of the log machines. Three different modes are possible: Automatic, in which all log features, including PLAY and SEGUE transitions and hard times are fully enabled; LiveAssist, in which no automatic transitions or hard start times are executed but automatic crossfades are done between elements; and Manual, which is very similar to LiveAssist except that not even automatic crossfades are enabled (thus permitting fully manual crossfade control by means of an external console). To change RDAirPlay to a different mode, simply touch the mode indicator until the desired mode is indicated.

#### The Label Area

Immediately below the next stop counter and mode indicator is the label area. Text messages can be made to appear here (by means of RML commands) to signal the operator concerning the state of the system or need to take some kind of action.

#### The Right-Hand Side

Directly below the label area is the right-hand side. The right-hand side can display either a SoundPanel array or a full log widget for each of the three log machines, selected by clicking the appropriate button in the lower right-hand corner of the screen. (NOTE: depending upon how the system administrator has configured the system, not all of the log machine buttons may be visible on your system).

#### The Full Log Widget

As the name implies, the full log widget can be used to view the contents of a log over its entire length. To load a log, touch the Select Log button to bring up the Select Log dialog, select the desired log from the list and then touch Load. The currently loaded log can also be saved by touching the Save or Save As buttons, or the current log unloaded by touching Unload. See Illustration 36.

Once a log is loaded, it can be started at any point by touching an event and then pressing the Play button. Any playing event can likewise be stopped by touching in the event and then pressing the Stop button. To cue-up an event so that it is the next to play (indicated by the event being the first with a light green background), touch the event and then press the Make Next button. The play parameters of an event can be modified by touching the event, then pressing the Modify button, bringing up the Edit Event dialog (see Illustration 37).

In addition to having the ability to modify the event's time and transition parameters, the Edit Event dialog can be used to audition the event's audio in Cue or set the start position of the audio for on-air playback (so as to allow a program to be joined "in progress", for example). To audition the audio, simply press the play button. The slider can be moved to adjust where in the audio to audition from. To set the start position, press the Start button and then position the slider where you wish the start to be. The red line on progress display indicates the current start position. Pressing the Start button again returns the dialog to Audition mode.

When running a log, it is often desirable to have the currently playing event always in sight. To do this, toggle the Scroll button on (blue background).

#### The Button Log Widget

To the left of the full log widget is the button log widget, consisting of a column of seven large buttons adjacent to cart labels. This widget provides another, specialized “view” of the Main Log log machine. Specifically, the first seven currently playing and/or next events in that log machine will always be visible here. Events visible in the button log will be shown in the full log widget as having a green background. Unlike the full log widget, the button log is always visible, regardless of which display has been selected for the right-hand side.

To start an event from the button log, simply touch an event's corresponding Start button. Touching the button of a running event will either (depending upon how the system administrator has configured RDAirPlay) stop or pause it. To modify an event's parameters (via the Edit Event dialog), simply double-click the event's cart label.

### Editing a Log

It is possible to edit the log loaded into any of the three log machines by means of the log edit buttons in the lower left-hand corner of the screen.

#### Adding an Event

To add an event, touch the ADD button to open the Select Cart dialog, pick the desired cart and then touch OK. To place the selected cart using the button log widget, simply touch one of the yellow WHERE? buttons. To place it using the full log widget, click the event where you wish it to go and then touch the yellow WHERE? button. If, after selecting a cart from the Select Cart dialog, you decide you don't want to add it after all, simply touch the ADD button again to cancel the operation (see Illustration 39).

#### Deleting an Event

To delete an event, touch the DEL button, then touch one of the violet DELETE buttons in the button log widget, or select an event and then touch the violet DELETE button. To cancel the operation, simply touch the DEL button again (see Illustration 40).

#### Moving an Event

To move an event, touch the Move button, then touch one of the violet MOVE buttons in the button log widget, or select an event and then touch the violet MOVE button, then touch one of the yellow TO buttons in the button log widget, or select an event and then touch the yellow TO button. To cancel the operation at any stage, simply touch the MOVE button again. It is perfectly permissible to move an event between two different log machines.

#### Copying an Event

To copy an event, touch the Copy button, then touch one of the violet COPY buttons in the button log widget, or select an event and then touch the violet COPY button, then touch one of the yellow TO buttons in the button log widget, or select an event and then touch the yellow TO button. To cancel the operation at any stage, simply touch the COPY button again. It is perfectly permissible to copy an event between two different log machines.

#### The SoundPanel

The SoundPanel is an array of buttons that appears in the right-hand side of RDAirPlay when the Sound Panel button is selected (see Illustration 41). Each button can be associated with a particular cart in the Library (either Audio or Macro carts), which is then played each time the button is clicked. The soundpanel is particularly useful in live assist situations where it is desired to drop in some piece of audio on a live, improvised basis.

#### Panel Types

The SoundPanel has multiple panels or “panes” that can scrolled through by touching the double-left or double-right arrow buttons. Each panel has a designator, (displayed just to the right of the arrow keys), consisting of the letter 'U' or 'S' followed by a number. An 'S' indicates that the panel is a 'system' panel, meaning that its button assignments will show up in all RDAirPlay instances across a given site; while a 'U' indicates a 'user' panel, one which is associated with a particular user and that will "follow around" that user where ever he logs in in the site. (Depending upon how the system administrator has configured RDAirPlay, you may not have both of these panel types available to you).

#### Programming a SoundPanel Button

To associate a cart with a panel button, first touch the Setup button, which will begin to flash. (Depending upon how the system administrator has configured RDAirPlay, the Setup button may be disabled). Next, touch the button you wish to program, opening the Edit Button dialog (see Illustration 41).

Touch the Set Cart button to open the Select Cart dialog and pick a cart. To clear the button –i.e. have no cart associated with it – touch the Clear button. To assign a custom background color to the button, touch the Set Color button. A custom label can be entered in the Label field, or the name of the cart will be used by default. Touch the OK button when done. When done programming all the desired buttons, touch the Setup button again to toggle off Setup mode.

## Generating Logs with RDLogManager

### Overview

RDLogManager is a tool for generating Rivendell logs. It is different from RDLogEdit in that, instead of building logs line-by-line, it allows log structures to be defined by a series of rules (called events and clocks) that are then plugged into a time framework (called a grid). This grid is then used to automatically generate logs on an as-needed basis. Each Rivendell service has its own, separately defined grid, thus allowing for separate log generation rules for each service. This system of rules allows for very powerful, modular features, including the ability to import and use scheduling data from various external third party systems, such as music schedulers and traffic and billing systems.

RDLogManager also includes facilities for generating reports. Reports are data outputs that detail whether certain events aired as scheduled, and under what circumstances. Reports are available in various formats. Some are intended to be read by humans, while others are intended for use by other, external software systems as a means of reconciling exported schedules.

When RDLogManager is started, it displays its main menu (see Illustration 42).

### Grids

Each Rivendell service has an RDLogManager grid. To see the list of available grids, touch the Edit Grids button to open the Log Grids dialog (see Illustration 43).

To open a particular grid, select its service name and touch the Edit button (see Illustration 44).

Each grid has slots for every hour of every day of the broadcast week – 168 slots in all. By specifying a particular clock to go into each of these slots, a set of rules that RDLogManager can use to generate a log for any given day of the week is built up. To specify a clock, simply touch the particular hour of interest to open up the Select Log Clock dialog (see Illustration 45).

Click the desired clock, then touch the OK button. To clear the assignment of any clock to the selected hour, touch the Clear button, then OK.

It is possible to 'drill down' directly to the underlying configuration of a clock (to be covered shortly) by right-clicking on the relevant hour in a grid and selecting Edit Clock.

### Clocks

An RDLogManager clock is a collection of RDLogManager events, arranged in terms of their start time (relative to the beginning of the hour) and length. It basically can be thought of as the "schedule" of an hour – any hour. Once defined, a clock can be plugged into any hour of a grid of any service, thus making for easy modularization and changes to a service's schedule.

To see the list of available clocks, touch the Edit Clocks button in RDLogManager's Main Menu to open the Log Clocks dialog (see Illustration 46). Each RDLogManager clock can be assigned a three-letter code and color, as an aid in identifying it when assigned to grids. To add a new clock, touch the Add button, or to edit a clock's parameters, click on it and touch the Edit button. In each case, the Edit Clock dialog (see Illustration 47) will open. Clocks can also be deleted by touching the Delete button or renamed by touching the Rename button.

The Edit Clock dialog consists of three main sections: a tabular list of events in chronological order, a graphical depiction of the clock in the traditional “broadcast clock” format, and a series of action buttons across the bottom. The clock's three-letter code is set by means of the Code: field in the upper right-hand corner of the table area. Its color can be set by touching the Color button. To save the clock without exiting the dialog, touch the Save or Save As buttons. To add a new event to the clock, touch the Add button, or to edit an existing entry touch the Edit button. In either case, the Edit Event Assignment dialog will open (see Illustration 48). To delete an entry, touch the Delete button. As in the case of grids, it is possible to 'drill down' into the underlying RDLogManager event by right-clicking on the respective entry in the clock event table and selecting Edit Event.

The Edit Event Assignment dialog simply consists of an Event field for the name of the RDLogManager event and Start Time: and End Time: fields for the start and end times relative to the start of the hour. A list of available events can be brought up by touching the Select button to bring up the Log Events dialog.

Each clock can be designated as being associated with one or more services. This can make finding the correct clock for a given service much faster, as the Filter control on the List Clocks dialog can then be used. To program these associations, touch the Services List button in the Edit Clock dialog to bring up the Service Associations dialog (see Illustration 49).

To designate a service as being valid for this clock, select the services name in the Available Services list and then touch the Add >> button. Likewise, to deselect a service, select its name in the Enabled Services list and then touch the << Remove button.

### Events

An RDLogManager event is a set of rules that define a series of log elements (audio carts, macro carts, markers, etc) that should be inserted into a log, along with the appropriate log event parameters (transition type, time type, etc) that should be associated with them. The actual elements to be inserted can be specified directly within the event itself, or imported from a data file generated by an external scheduling system. Up to two such external scheduling sources can be defined for each service. While for convenience sake these are designated as 'Traffic' and 'Music' within RDLogManager, they can each be used anywhere a means of importing external scheduling data into the system is needed, regardless of whether such data actually references commercial or musical material or not.

To see the list of available RDLogManager events, touch the Edit Events button on the RDLogManager Main Menu to open the Log Events dialog (see Illustration 50). It is possible to filter the list of available events to only those used for a particular service by selecting the service in the Filter: control. To add a new event, touch the Add button, or to edit an event's parameters, click on it and touch the Edit button. In each case, the Edit Event dialog (see Illustration 51) will open. Events can also be deleted by touching the Delete button or renamed by touching the Rename button.

The Edit Event dialog consists of two main parts: a Library cart picker widget on the left side, and an area showing the various event parameters on the right. Audio contained within audio carts can be sampled by selecting the desired cart and then touching the Play button. Programming an event basically consists of specifying four things: its log parameters (transition and time types), the list of pre-import events, the event import (if any) and the list of post-import events. The first matter to be decided is if the event should have a hard start time: if so, then the Use hard start time box in the TIMED START section should be checked. Checking this box will enable all of the usual hard start parameters to be specified. If an automatic timed start is not desired, then it is possible to check the Cue to this event box in the PREPOSITION LOG section. This will cause RDLogManager to place a hard time with a 'Make Next' attribute on the first item of the event – effectively, causing the event to be automatically “cued up” at the scheduled time – something that can be particularly handy for keeping spot breaks in sync when "overscheduling" music.

Next, if it is desired to have RDLogManager try to insert automatically material from the Autofill List to ensure that the event has the length indicated by its parent clock, the Use Autofill box in the ENFORCING LENGTH section should be checked. (Configuring the Autofill List is covered in detail in the Rivendell Technical and Administration Guide). If Autofill is enabled, it is also possible to check the Warn if fill is under or over box to have RDLogManager generate a warning if it was unable to properly fill the event when the log was generated.

Next, the list of log events (if any) to be inserted before the data import should be placed in the PRE-IMPORT CARTS list. For audio or macro carts, these can be simply dragged and dropped from the Library cart list on the left-hand side of the dialog. Meta events can be inserted by right-clicking on the list and selecting the desired element. It is also possible to edit or delete elements and set the transition type of each element through the right-click menu.

The IMPORT section then defines which (if any) source will be used for importing external scheduling events into the log. Either Music, Traffic or None can be selected. If Music or Traffic is selected, then RDLogManager will import any events from those sources that fall within the start and end times of the event (as supplied by the parent clock). These start and end times can be further broadened by means of 'slop factors' entered into the Import carts scheduled controls (this is sometimes necessary to get the import to work properly with certain external scheduler systems). The transition types to be used for the first and subsequent imported elements can be specified with the First cart has a and Imported carts have a controls. If Music has been selected as the import source, it is also possible to specify the event to use to import traffic breaks embedded in the music log with the Import inline traffic with the control. (Configuration of the actual parser parameters for data importation is covered in the Rivendell Technical and Administration Guide).

Finally, the list of log events (if any) to be inserted after the data import should be placed in the POST-IMPORT CARTS list. Configuration of the events work very similarly to that of the PRE-IMPORT CARTS list.

The color of the event (as seen in the Edit Clock dialog) can be set by touching the Color button. The list of services for which this event is valid can be edited by touching the Services List button. To save the event without exiting the dialog, touch the Save or Save As buttons.

### Generating Logs

After all of the appropriate hours have been populated in a service's grid, it's time to start generating logs. To do this, touch the Generate Logs button in RDLogManager's Main Menu to open the Generate Log dialog (see Illustration 52).

Depending upon how many external scheduling sources are involved, generating a log involves one, two or three steps. Before performing any of the steps, it is first necessary to select the relevant service for which to generate the log (using the Service: control) and the log date (either by entering the date in the Date: control or by touching the Select button and picking it off of the calendar).

In all cases, a new log is initially generated by touching the Create New Log button. If the log for the selected date and service does not already exist, it will be created at this point (becoming visible in RDLogEdit). It the log already exists, it will be overwritten. (NOTE: if completed voicetracks exist in the old log, they will be deleted when the log is overwritten!)

When generating a log, RDLogManager will look for possible problems (such as scheduled carts that are missing in the Library) and generate an exception report if it finds any.

Once generated, the status lights in the Generate Log dialog indicate which (if any) additional import data are needed to complete the log. Two types of status light exist: Available, which indicates if the required data file is available to RDLogManager, and Merged, indicating whether the data has been merged into the log as yet. Each light can show one of three different colors: GREEN, meaning "yes", RED, meaning "no" and WHITE, meaning "not required".

For an example, see Illustration 53. This is showing a log that has been generated and has music data available but not yet merged. To perform the merge, touch the Merge Music button. The dialog now changes to that shown in Illustration 54, indicating that Music data has been merged but that traffic data is still needed. Once a log has reached this state – that of having any necessary music data merged – it can be voicetracked without having to wait for traffic data to become available. Traffic data can be merged at any time before, during or after the generation of voicetracks. The actual traffic merge is performed by touching the Merge Traffic button, resulting in a dialog like that shown in Illustration 55. (NOTE: the configuration of the various data file names and parser parameters needed for data import is done in the RDAdmin module and is covered in the Rivendell Technical and Administration Guide).

It is important to note that the sequence of operations from the example above is typical, but may vary depending upon how the system administrator has configured RDLogManager at each site. Some services, for example, will have no music data, only traffic, so the music indicator lights will be "whited out" accordingly.

### Generating Reports

A Rivendell report is a data output that details whether certain events aired as scheduled, and under what circumstances. Reports are available in various formats. Some are intended to be directly read by humans, while others are intended for use by other, external software systems as a means of reconciling exported schedules.

Rivendell has the ability to filter the data that go into any particular report on the basis of the type of material played (traffic spots, music or all), the playing service(s) and the originating host(s). The configuration of reports is done in the RDAdmin module and is covered in the Rivendell Technical and Administration Guide. Once configured however, reports are actually generated by the RDLogManager module.

To generate a report, touch the Manage Reports button on the RDLogManager Main Menu to open the Select Service dialog (see Illustration 56). The dialog will show each service on the system, along with the date of the oldest data available for generating reports. Touch the Generate Reports button to open the Select Report Dates dialog (see Illustration 57). The desired report can be selected with the Report: control, and the start and end dates of the report specified with the Start Date: and End Date: controls, respectively (NOTE: not all reports are capable of being generated so as to span more than one day). Once the parameters are set, touch the Generate Report button to write out the report.

#### Purging Old Report Data

Rivendell keeps the raw data used to generate reports indefinitely, until manually purged out of the system. Periodic purging of old data is a good idea from the standpoint of minimizing the amount of system resources utilized, and can be done by selecting the desired service and then touching the Purge Data button in the Select Service dialog, opening up a calendar dialog (see Illustration 58). Each date that has data eligible for purging will be shown in bold. To purge a particular day, select it and the touch the Purge Data button. (NOTE: once purged, no reports can be generated for that particular service/date, so be sure that all required reports have been produced before purging!)

## VoiceTracking

### Voicetracking in Rivendell

Voicetracking is a capability wherein custom "one-off" content is created and inserted into logs, making it possible to create programming that sounds very spontaneous and "live". In Rivendell, such voicetracks are placed into a special type of audio cart known as a voicetrack cart. These carts are automatically created, deleted and managed by the voicetracker interface (part of the RDLogEdit module), with no manual user intervention required. The voicetracker module also includes extensive capabilities for allowing customization of the transitions between log elements.

#### Prerequisites

Before beginning voicetracking for a particular service, a voicetracker group and pool of available cart numbers must be configured in the RDAdmin module. These procedures are detailed in the Rivendell Technical and Administration Guide.

#### VoiceTrack Markers

A voicetrack marker is a meta event that can be inserted into a log as a "placeholder" to others to indicate where a voicetrack is to be recorded. Track markers can be inserted by RDLogEdit, RDLogManager events or even embedded in data generated by external schedulers.

### Using the Voicetrack Interface

#### The VoiceTracker Dialog

To voicetrack a log, start the RDLogEdit module (see Illustration 19), highlight the desired log and touch the VoiceTracker button, opening the VoiceTracker dialog (see Illustration 59). This dialog consists of three major parts: the waveform area, the log list and the control buttons.

The waveform area is in the upper center part of the dialog, and consists of four "panes". The upper three display waveform depictions while the fourth contains audition control buttons, an audio meter and various counters. Directly below this is the log list, showing a copy of the currently loaded log. The control buttons occupy the bottom and right-hand edges of the dialog.

#### Editing Transitions

When an event is selected in the log list, a graphical depiction of the transition into that event is loaded into the waveform area. If the selected event and its prior event in the log is not a voicetrack or track marker, then the selected event will be displayed in the third pane of the waveform area and the previous event displayed in the first pane. If the selected event or its prior event is a voicetrack or track marker, then voicetrack or marker will be displayed in the second pane of the waveform area.

Once selected, a transition can be auditioned by touching the play button in the fourth pane of the waveform area. Play will start from the left-hand edge of the topmost waveform. This start location can be adjusted by dragging the topmost waveform to the left or right by means of the mouse or touchscreen. If the transition type of the selected event is SEGUE, it is also possible to adjust the degree of audio overlap by dragging the second or third waveform as well. It's possible to “undo” changes made in the segue overlap by right-clicking on the waveform and selecting Undo Segue Changes from the menu. To make the overlap permanent, touch the Save button. To restore the transition to its default state (calculated on the basis of segue markers from the Library) touch the Do Over button. The transition type can be changed by right-clicking on an event and selecting the desired transition type from the menu.

#### Inserting and Deleting Track Markers

It is possible to insert a new voicetrack marker by selecting the desired location in the log list and touching the Insert Track button. An existing voicetrack marker can likewise by deleted by selecting it in the log list and touching the Delete Track button.

#### Moving Between Track Markers

It is possible to move directly to the next or previous voicetrack marker simply by touching the Next Track or Previous Track buttons, respectively.

#### Recording a Voicetrack

Once the desired voicetrack marker has been selected, the process of recording a voicetrack consists of four steps, each initiated by one of the four square control buttons in the upper right-hand corner of the dialog. (See Illustration 50).

To begin, touch the topmost Start button. This will cause the audio in the topmost pane to begin playing, with a cursor to show playback position (see Illustration 61). To begin the actual recording, touch the Record button (see Illustration 62). To start the following event (in the third pane), touch the second Start button (see Illustration 63). Finally, to stop recording, touch the Save button (see Illustration 64). The record process can be canceled at any time by touching the Abort button, restoring the transition to its default state. It is also possible to undo a completed voicetrack by touching the Do Over button.

Once completed, the segue overlaps into and out of a voicetrack can be adjusted in the same manner as for simple transitions –i.e. by dragging the appropriate waveforms with the mouse.

#### Adjusting Transition Levels

It is possible to adjust the audio fade levels applied during transitions by means of rubber bands on the waveform displays. These are green lines with small square targets. To adjust a rubber band, use the mouse to grab one of the targets and drag it to the desired location.

#### Importing Voicetracks

In addition to recording in realtime, it's possible to import a voicetrack directly from an audio file. To do so, select the desired voicetrack marker and then touch the Import button to open the Import/Export Audio dialog (see Illustration 5). (For more information on using the Import/Export Audio dialog, see Section 3.1.0 Importing Audio from a File). Once imported, the voicetrack can be manipulated in the same manner as those that were directly recorded.

#### Hitting the Post

If the event following a voicetrack has its Talk Time markers set, it is possible to set the transition so that the end of the voicetrack automatically aligns with the end of the Talk Time (commonly referred to as hitting the post). To do this, simply touch the Hit Post button.

## Rivendell Macro Langauge

### Overview

Rivendell Macro Language (or RML for short) is a set of commands implemented within Rivendell that can be used to program the system to take various actions. A wide variety of commands exist, ranging from control of outboard gear (such as switchers and GPIO devices) to control of various aspects of log playout in RDAirPlay, to Rivendell user management.

### Protocol

The Normal form of a command takes the following syntax:

cmd [arg] [...]!

cmd

  A command mneumonic consisting of two alpha-numeric characters indicating the action to be performed.

arg

  Zero or more arguments, delimited by spaces or, if the last argument, by ! (see below)

!

  The ASCII character 33, indicating the end of the command sequence.

### Command Delivery

To be executed by a Rivendell system, an appropriate command should be delivered to UDP ports 5858 or 5859 on said system, using the SOCK_DGRAM connectionless protocol. Commands delivered to port 5858 may receive a reply back to the originating IP address at UDP socket 5860 to indicated command success/failure, while commanders delivered to 5859 will be processed, but no reply made.

### Command Reply

If delivered to UDP port 5858, each command may receive a reply, formulated as follows:

rpy `+`|`-`

rpy

  The full command string (including arguments) originally received

`+`

  ACK response, indicates success of the command.

`-`

  NAK response, indicates failure of the command.

### Specifying Color

In places where a color can be specified as a macro argument, the following predefined values are valid:

- `white`
- `red`
- `green`
- `blue`
- `cyan`
- `magenta`
- `yellow`
- `gray`
- `lightGray`
- `black`
- `darkRed`
- `darkGreen`
- `darkBlue`
- `darkCyan`
- `darkMagenta`
- `darkYellow`
- `darkGray`

### Binary Data

Certain commands (e.g. `SO` and `UO`) have the ability to transmit arbitrary binary data in addition to textual characters. Such arbitrary binary data can be specified by means of escape codes as follows:

`%`hexcode

hexcode
  Two digit numeric value of the byte to send in hexidecimal.

For example, the sequence 'TEST' followed by a carriage return/newline could be specified as:

`TEST%0D%0A`

### Commands

#### Air Gate [AG]

Module
  `ripcd` 8
Mnemonic
  `AG`

Process an RML only if the On-Air flag is ON.

`AG` rml!

Execute RML rml only if the On-Air flag on the local machine is ON.

#### Add Next [PX]

Module
  `rdairplay` 1
Mnemonic
  `PX`

Insert a cart in a log in the next to play position.

`PX mach cart!`

Insert cart cart> in the next to play position on log machine mach.

#### Binary Serial Out [BO]

Module
  `ripcd` 8
Mnemonic
  `BO`

Output a string of binary codes.

`BO portnum hexcode ..!`

Output a string of binary codes represented by hexcode .. on serial port portnum!

#### Clear Serial Trap [SC]

Module
  `ripcd` 8
Mnemonic
  `SC`

Clear a serial trap.

`SC portnum cart string!`

`SC portnum cart!`

`SC portnum!`

Clear a serial trap. The three argument form will clear all traps on port that reference cart and string. The two argument form will clear all traps on port that reference cart, while the one argument form will clear all traps on port.

#### Command Send [CC]

Module
  `ripcd` 8
Mnemonic
  `CC`

Send RML to a remote host.

`CC dest [`:`udpport] rml!`

Send the RML command rml to dest.dest may be either a Rivendell host name or an IP address. A UDP port value may be optionally specified as udpport (default value 5859).

#### Connect Jack Ports [JC]

Module
  `ripcd` 8
Mnemonic
  `JC`

Connect a JACK input port to an output port.

`JC output input!`

Attempt to connect JACK input port input to output.

#### Console Label [CL]

Module
  `ripcd` 8
Mnemonic
  `CL`

Set the label on a control surface.

`CL matrix surface chan label!`

On matrix matrix, set the input chan module label of control surface surface to label.

#### Copy Cut [CP]

Module
  `rdcatchd` 8
Mnemonic
  `CP`

Copy cut audio and metadata.

`CP srccart srccut dstcart dstcut!`

Copy the audio and metadata from cut number srccut in cart srccart to cut number dstcut in cart dstcart. The destination cart/cut must already exist.

#### Cut Event [CE]

Module
  `rdcatchd` 8
Mnemonic
  `CE`

Place a cut event at the current location of an active RDCatch recording.

`CE decknum eventnum!`

Place a cut event with event number eventnum at the current position of the active recording in RDCatch Deck decknum.

#### Database Backup [DB]

Module
  `ripcd` 8
Mnemonic
  `DB`

Backup the Rivendell database.

`DB filename!`

Create a backup copy of the active Rivendell database in filename.

#### Disconnect Jack Ports [JD]

Module
  `ripcd` 8
Mnemonic
  `JD`

Disconnect a JACK input port from an output port.

`JD output input!`

Attempt to disconnect JACK input port input from output.

#### Duck Panel Button [PD]

Module
  `rdairplay` 1
Mnemonic
  `PD`

Set the duck level of a SoundPanel button in RDAirPlay.

`PD panel col row level fade [mport]!`

Set the duck level of button at column, row> of panel panel. Panel: `S1`...`S50` or `U1`...`U50`; `C` for panel means currently selected panel. If col and/or row is `0`: duck all buttons in col or row. If playing, the audio fades to level (in dbFS) in fade msecs. If specified, only stop carts playing on panel port mport. The duck level will be set to 0 after the playback is finished, or the button is stopped or reset.

#### Execute Breakaway [DX]

Module
  `rdcartslots` 1
Mnemonic
  `DX`

Execute a breakaway.

`DX slotlen!`

Execute a breakaway of length len (in mS) using the autofill carts configured for the service currently loaded in the slot slot. The slot must be in Breakaway mode. If a breakaway is currently executing, it will immediately be aborted and a new one started. Passing a '0' for len will cause any currently executing breakaway immediately to be aborted and input audio restored.

#### Execute Cart [EX]

Module
  `rdcatchd` 8
Mnemonic
  `EX`

Execute a macro cart.

`EX cartnum!`

Execute macro cart cartnum on the local host.

#### Fire Salvo [FS]

Module
  `ripcd` 8
Mnemonic
  `FS`

Execute a switcher salvo.

`FS matrix salvo!`

Fire salvo number salvo on matrix matrix.

#### GPI Enable [GE]

Module
  `ripcd` 8
Mnemonic
  `GE`

Enable/disable a GPI line.

`GE matrix type gpinum state!`

Enable or disable the GPI line of type type indicated by gpinum on matrix matrix. Possible types are:

`I`
  Input
`O`
  Output

#### GPI Enable [GE] (old format, deprecated)

Module
  `ripcd` 8
Mnemonic
  `GE`

Enable/disable a GPI line.

`GE matrix gpinum state!`

Enable or disable the GPI line indicated by gpinum on matrix matrix.

#### GPI Set [GI]

Module
  `ripcd` 8
Mnemonic
  `GI`

Set action in response to a GPIO event.

`GI matrix type gpinum state cart!`

Execute the macro cart cart upon transition of the GPIO of type type and line gpinum on matrix matrix to state. Possible types are:

`I`
  Input
`O`
  Output

#### GPI Set [GI] (old format, deprecated)

Module
  `ripcd` 8
Mnemonic
  `GI`

Set action in response to a GPIO event.

`GI matrix gpinum state cart!`

Execute the macro cart cart upon transition of the GPIO of line gpinum on matrix matrix to state.

#### GPO Set [GO]

Module
  `ripcd` 8
Mnemonic
  `GO`

Set the state of a GPIO line.

`GO matrix type gponum state length!`

Command GPIO line gponum of type type on matrix matrix> to state for length> mS. A length of `0` indicates to hold the state indefinitely. Possible types are:

`I`
  Input
`O`
  Output

Possible states are:

`0`
  OFF
`1`
  ON
`-1`
  Passthrough hardware input (valid only for Input type)

#### GPO Set [GO] (old format, deprecated)

Module
  `ripcd` 8
Mnemonic
  `GO`

Set the state of a GPIO line.

`GO matrix gponum state length!`

Command GPIO line gponum on matrix matrix> to state for length> mS. A length of `0` indicates to hold the state indefinitely.

#### Insert Serial Trap [SI]

Module
  `ripcd` 8
Mnemonic
  `SI`

Insert a serial trap to detect a character sequence.

`SI portnum cart string!`

Insert a serial trap to execute the macro cart cart upon receipt of string on serial port port.

#### Label Panel [PC]

Module
  `rdairplay` 1
Mnemonic
  `PC`

Set the label of a SoundPanel button in RDAirPlay.

`PC panel col row label color!`

Set the button at col, row of panel panel to have a text label of label and a background color of color. Panel: `S1`...`S50` or `U1`...`U50`; `C` for panel means currently selected panel.

#### Load Log [LL]

Module
  `rdairplay` 1
Mnemonic
  `LL`

Load a log into RDAirPlay.

`LL mach [logname] [startline]!`

Load the log logname in log machine mach. After loading, start the log at line startline if it is >=0. If startline is -2, the log will be started at the first event if that event does not have a 'stop' transition. Default startline=-1. If no log> is specified, the machine's current log is unloaded.

#### Load Panel [PE]

Module
  `rdairplay` 1
Mnemonic
  `PE`

Load a cart into a SoundPanel button in RDAirPlay.

`PE panel col row cart!`

Load cart cart into the button at col,row of panel panel. Panel: `S1`...`S50` or `U1`...`U50`; `C` for panel means currently selected panel.

#### Load Slot [DL]

Module
  `rdcartslots` 1
Mnemonic
  `DL`

Load an RDCartSlots slot.

This command has two syntaxes, depending upon the mode of the slot.

Cart Deck Mode syntax:

`DL slot cart!`

Load the cart cart into the slot slot. Passing a '0' for cart will cause the slot to be unloaded. This command will be ignored if the slot is currently playing.

Breakaway Mode syntax:

`DL slot svcname!`

Set the slot slot to use service svcname. Omitting the svcname argument will cause the slot to be unloaded. This command will be ignored if the slot is currently executing a breakaway.

#### Login [LO]

Module
  `ripcd` 8
Mnemonic
  `LO`

Change the active Rivendell user context.

`LO user password!`

Set the current Rivendell user to user. If no arguments are supplied, log out the station --i.e. revert to the default user.

#### Macro Timer [MT]

Module
  `ripcd` 8
Mnemonic
  `MT`

Timer for running macro carts.

`MT timernum timeout cart!`

Set the macro timer timernum to execute macro cart cart in timeout milliseconds. Setting timeout to `0` disables the timer. Sixteen macro timers (numbered 1-16) are available on each Rivendell host.

#### Make Next [MN]

Module
  `rdairplay` 1
Mnemonic
  `MN`

Load changes to a currently loaded log in RDAirPlay.

`RL mach line!`

Set the next event for log machine mach to line line>.

#### Message Box [MB]

Module
  `ripcd` 8
Mnemonic
  `MB`

Display a popup message box on a host display.

`MB display severity msg!`

Display the text msg in a popup window on X display display, with an icon to indicate severity. Valid values of severity are:

`1`
  Information
`2`
  Warning
`3`
  Critical

#### Pause Panel [PU]

Module
  `rdairplay` 1
Mnemonic
  `PU`

Pause a SoundPanel button in RDAirPlay.

`PU panel col row [mport]!`

Pause the button at col, row of panel panel. Panel: `S1`...`S50` or `U1`...`U50`; `C` for panel means currently selected panel. If col and/or row is `0`: pause all playing buttons in col or row. If specified, start the playout on panel port mport.

#### Play Panel [PP]

Module
  `rdairplay` 1
Mnemonic
  `PP`

Load a cart into a SoundPanel button in RDAirPlay.

`PP panel col row [mport] [0|1]!`

Play the button at col, row of panel panel. Panel: `S1`...`S50` or `U1`...`U50`; `C` for panel means currently selected panel. If col and/or row is `0`: Start the first loaded button that is not active. If specified, start the playout on panel port mport. The started panel will stay active when finished, if the 5th argument is `1`.

#### Play Slot [DP]

Module
  `rdcartslots` 1
Mnemonic
  `DP`

Play an RDCartSlots slot.

`DP slot!`

Play the cart currently loaded in the slot slot. The slot must be in Cart Deck mode. This command will be ignored if the slot is unloaded or already playing.

#### Refresh Log [RL]

Module
  `rdairplay` 1
Mnemonic
  `RL`

Load changes to a currently loaded log in RDAirPlay.

`RL mach!`

Refresh the log currently loaded in log machine mach.

#### Run Shell Command [RN]

Module
  `ripcd` 8
Mnemonic
  `RN`

Run a shell command.

`RN cmd!`

Run the shell command cmd.

#### Select Widget [PW]

Module
  `rdairplay` 1
Mnemonic
  `PW`

Select right-hand widget in RDAirPlay.

`PW mach!`

Select right-hand widget to log-machine mach or `0` for sound panel.

#### Serial Out [SO]

Module
  `ripcd` 8
Mnemonic
  `SO`

Output a string on a serial port.

`SO portnum data!`

Output data on serial port portnum. data can consist of arbitrary binary data as well as textual characters (see `Binary Data` above).

#### Serial Reload [SY]

Module
  `ripcd` 8
Mnemonic
  `SY`

Reload the configuration for a serial port.

`SY portnum!`

Reload the configuration for serial port portnum. Normally, this should only be issued by RDAdmin following a configuration change.

#### Set Color Label [LC]

Module
  `rdairplay` 1
Mnemonic
  `LC`

Display a color message in the label widget on RDAirPlay.

`LC color string!`

Display string> in color color in the message widget.

#### Set Default Now & Next Cart [SN]

Module
  `rdairplay` 1
Mnemonic
  `SN`

Set the default Now & Next cart.

`SN now`|`next mach cart!`

Set the default Now & Next cart for log mach to cart.

#### Set Display [SD]

Module
  `ripcd` 8
Mnemonic
  `SD`

Set a console display.

`SD matrix display line col attr label!`

On matrix matrix, set the console display display to label, starting at position line, col and using message attributes attr.

The message attributes value is constructed as follows:

Bit 7
  Display mode
Bits 6,5
  Video attribute
Bit 2,1,0
  Message Text Color

Display Mode:

0
  Overwrite text
1
  Insert text

Video Attribute:

00
  Normal
01
  Flash
02
  Reverse

Text Color:

000
  White
001
  Red
010
  Yellow
011
  Green
100
  Cyan
101
  Magenta

#### Set Duck Level [MD]

Module
  `rdairplay` 1
Mnemonic
  `MD`

Set duck level for an RDAirPlay log machine.

`MD mach level fade [mport]!`

Set the duck level of mach, or `0` for all log machines. If playing, the audio fades to level (in dbFS) in fade msecs. If specified, only affect carts playing on machine port mport. Loading or clearing a log will set the duck level back to 0.

#### Set Label [LB]

Module
  `rdairplay` 1
Mnemonic
  `LB`

Display a message in the label widget on RDAirPlay.

`LB string!`

Display string> in the message widget.

#### Set Mode [PM]

Module
  `rdairplay` 1
Mnemonic
  `PM`

Set the mode of an RDAirPlay log machine.

`PM mode [mach]!`

Set log machine mach to mode mode. If mode is not given or the Mode Control Style is set to 'Unified', then all log machines are set to mode. Valid values for mode are:

1
  LiveAssist
2
  Auto
3
  Manual

#### Sleep [SP]

Module
  `ripcd` 8
Mnemonic
  `SP`

Pause for specified time.

`SP msecs!`

Wait for msecs milliseconds.

#### Start [PL]

Module
  `rdairplay` 1
Mnemonic
  `PL`

Start a log at a specified line.

`PL mach line!`

Start log machine mach at line line if stopped, otherwise do nothing.

#### Start Button [PB]

Module
  `rdairplay` 1
Mnemonic
  `PB`

Push an RDAirPlay Start button.

`PB button!`

Push button button.

#### Start Next [PN]

Module
  `rdairplay` 1
Mnemonic
  `PN`

Start the next event in a log.

`PN mach [mport] [skip]!`

Start log machine mach> if stopped, or start next event if already running. If specified, start the playout on machine port mport>. If skip is supplied, equal to '1' and the log machine is in Manual or Live Assist mode, then any intervening meta-events in log between the current 'next' event and the next cart will be skipped over.

#### Start Record Deck [RS]

Module
  `rdcatchd` 8
Mnemonic
  `RS`

Start an RDCatch Recording

`RS decknum cartnum cutnum maxlen!`

Start recording to cut cutnum of cart cartnum, using RDCatch record deck decknum for a maximum time of maxlen mS. The record parameters used (format, sample rate, channels, etc) will be those configured for the selected deck in RDAdmin->ManageHosts->RDCatch. The selected cart and cut must already exist. Any audio previously residing in the selected cart and cut will be overwritten.

#### Stop [PS]

Module
  `rdairplay` 1
Mnemonic
  `PS`

Stop a log in RDAirPlay.

`PS mach|`0` [fade] [mport]!`

Stop log machine mach, or `0` for all log machines. If specified, only stop carts playing on machine port mport. If specified, fade out fade msecs.

#### Stop Panel [PT]

Module
  `rdairplay` 1
Mnemonic
  `PT`

Stop a SoundPanel button in RDAirPlay.

`PT panel col row [mport] [0|1] fade!`

Stop the button at col, row of panel panel. Panel: `S1`...`S50` or `U1`...`U50`; `C` for panel means currently selected panel. If col and/or row is `0`: stop all playing buttons in col or row. If specified, start the playout on panel port mport. The stopped panel will stay active when finished, if the 5th argument is `1`.

#### Stop Record Deck [RR]

Module
  `rdcatchd` 8
Mnemonic
  `RR`

Stop an RDCatch Recording

`RR decknum!`

Stop any active recording on RDCatch deck decknum.

#### Stop Slot [DS]

Module
  `rdcartslots` 1
Mnemonic
  `DS`

Stop an RDCartSlots slot.

`DS slot!`

Stop the cart currently loaded in the slot slot. The slot must be in Cart Deck mode. This command will be ignored if the slot is unloaded or already playing.

#### Switch Add [SA]

Module
  `ripcd` 8
Mnemonic
  `SA`

Add an input to an output.

`SA matrix input output!`

Command switch matrix number matrix to add input number input to output number output. Unlike `SWITCH TAKE`, this command leaves any other previously assigned inputs unchanged.

#### `Switch Add With Gain [SG]`

Module
  `ripcd` 8
Mnemonic
  `SG`

Add an input to an output while specifyng the crosspoint gain.

`SG matrix input output gain!`

Command switch matrix number matrix to add input number input to output number output at gain gain. The gain is specified in 1/10 of a dB, with 0 = unity gain. Unlike `SWITCH TAKE`, this command leaves any other previously assigned inputs unchanged.

#### `Switch Crosspoint Gain [SX]`

Module
  `ripcd` 8
Mnemonic
  `SX`

Set crosspoint gain.

`SX matrix input output level!`

Command switch matrix number matrix to adjust the gain of the crosspoint connecting input input to output output to level dB.

#### `Switch Level [SL]`

Module
  `ripcd` 8
Mnemonic
  `SL`

Set input gain.

`SL matrix input level!`

Command switch matrix number matrix to adjust the gain of input number input to level dB.

#### `Switch Reload [SZ]`

Module
  `ripcd` 8
Mnemonic
  `SZ`

Reload the configuration for a switch matrix.

`SZ matrix!`

Reload the configuration for switch matrix matrix. Normally, this should only be issued by RDAdmin following a configuration change.

#### `Switch Remove [SR]`

Module
  `ripcd` 8
Mnemonic
  `SR`

Remove an input from an output.

`SR matrix input output!`

Command switch matrix number matrix to remove input number input from output number output. Unlike `SWITCH TAKE`, this command leaves any other previously assigned inputs unchanged.

#### `Switch Take [ST]`

Module
  `ripcd` 8
Mnemonic
  `ST`

Exclusively route an input to an output.

`ST matrix input output!`

Command switch matrix number matrix to take input number input to output number output. "Take" in this context implies removing any previously assigned inputs from the referenced output.

#### `Toggle On Air Flag [TA]`

Module
  `ripcd` 8
Mnemonic
  `TA`

Set the state of the On Air flag.

`TA 0`|`1!`

Set the On-Air flag to ON [`1`] or OFF [`0`].

#### `UDP Out [UO]`

Module
  `ripcd` 8
Mnemonic
  `UO`

Send data to a UDP port.

`UO ipaddr udpport data!`

Send data in a UDP packet to port udpport at ipaddr. data can consist of arbitrary binary data as well as textual characters (see `Binary Data` above).

## Interfacing with the Linux Ecosystem: Command-Line Utilities

### RMLSend

RMLSend is a small utility that can be used to send RML commands to a local or remote Rivendell host. It can operate in two modes: GUI or a command line interface (CLI).

If started with no arguments, RMLSend will come up in GUI mode (see Illustration 65).

The Sent To: should have the name or IP address of the system to which to send the RML. Dest: controls the method by which the command will be sent. 'RML' is standard RML transmission that returns an echo code to indicate success/failure. 'RML (No echo)' does not return an echo code, while 'Set Port' allows the destination UDP port to be set (useful for controlling Rivendell from outside firewalls). Command: is the RML command to be sent, and Response: will show any echo code returned from the remote system (or 'No response' if no reply is received). Touching the Send Command button actually sends the command.

RMLSend also has a full-featured command-line facility that allows Rivendell commands to be sent using the standard Linux CLI utilities. Consult the `rmlsend` 1 man page for details.

### RDImport

RDImport is a command-line interface (CLI) program that can be used to import audio material into the Rivendell Library. It is particularly useful in situations where a large number of audio files need to be imported in an automated fashion, and is capable of importing thousands of files with a single command-line invocation. Consult the `rdimport` 1 man page for details.

## The GNU General Public License, Version Two

### GNU GENERAL PUBLIC LICENSE

Version 2, June 1991

Copyright (C) 1989, 1991 Free Software Foundation, Inc. 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA.

Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.

#### Preamble

The licenses for most software are designed to take away your freedom to share and change it. By contrast, the GNU General Public License is intended to guarantee your freedom to share and change free software--to make sure the software is free for all its users. This General Public License applies to most of the Free Software Foundation's software and to any other program whose authors commit to using it. (Some other Free Software Foundation software is covered by the GNU Library General Public License instead.) You can apply it to your programs, too.

When we speak of free software, we are referring to freedom, not price. Our General Public Licenses are designed to make sure that you have the freedom to distribute copies of free software (and charge for this service if you wish), that you receive source code or can get it if you want it, that you can change the software or use pieces of it in new free programs; and that you know you can do these things.

To protect your rights, we need to make restrictions that forbid anyone to deny you these rights or to ask you to surrender the rights. These restrictions translate to certain responsibilities for you if you distribute copies of the software, or if you modify it.

For example, if you distribute copies of such a program, whether gratis or for a fee, you must give the recipients all the rights that you have. You must make sure that they, too, receive or can get the source code. And you must show them these terms so they know their rights.

We protect your rights with two steps: (1) copyright the software, and (2) offer you this license which gives you legal permission to copy, distribute and/or modify the software.

Also, for each author's protection and ours, we want to make certain that everyone understands that there is no warranty for this free software. If the software is modified by someone else and passed on, we want its recipients to know that what they have is not the original, so that any problems introduced by others will not reflect on the original authors' reputations.

Finally, any free program is threatened constantly by software patents. We wish to avoid the danger that redistributors of a free program will individually obtain patent licenses, in effect making the program proprietary. To prevent this, we have made it clear that any patent must be licensed for everyone's free use or not licensed at all.

The precise terms and conditions for copying, distribution and modification follow.

#### GNU GENERAL PUBLIC LICENSE

TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION

1. This License applies to any program or other work which contains a notice placed by the copyright holder saying it may be distributed under the terms of this General Public License. The "Program", below, refers to any such program or work, and a "work based on the Program" means either the Program or any derivative work under copyright law: that is to say, a work containing the Program or a portion of it, either verbatim or with modifications and/or translated into another language. (Hereinafter, translation is included without limitation in the term "modification".) Each licensee is addressed as "you".

   Activities other than copying, distribution and modification are not covered by this License; they are outside its scope. The act of running the Program is not restricted, and the output from the Program is covered only if its contents constitute a work based on the Program (independent of having been made by running the Program). Whether that is true depends on what the Program does.

2. You may copy and distribute verbatim copies of the Program's source code as you receive it, in any medium, provided that you conspicuously and appropriately publish on each copy an appropriate copyright notice and disclaimer of warranty; keep intact all the notices that refer to this License and to the absence of any warranty; and give any other recipients of the Program a copy of this License along with the Program.

   You may charge a fee for the physical act of transferring a copy, and you may at your option offer warranty protection in exchange for a fee.

3. You may modify your copy or copies of the Program or any portion of it, thus forming a work based on the Program, and copy and distribute such modifications or work under the terms of Section 1 above, provided that you also meet all of these conditions:

   1. You must cause the modified files to carry prominent notices stating that you changed the files and the date of any change.

   2. You must cause any work that you distribute or publish, that in whole or in part contains or is derived from the Program or any part thereof, to be licensed as a whole at no charge to all third parties under the terms of this License.

   3. If the modified program normally reads commands interactively when run, you must cause it, when started running for such interactive use in the most ordinary way, to print or display an announcement including an appropriate copyright notice and a notice that there is no warranty (or else, saying that you provide a warranty) and that users may redistribute the program under these conditions, and telling the user how to view a copy of this License. (Exception: if the Program itself is interactive but does not normally print such an announcement, your work based on the Program is not required to print an announcement.)

      These requirements apply to the modified work as a whole. If identifiable sections of that work are not derived from the Program, and can be reasonably considered independent and separate works in themselves, then this License, and its terms, do not apply to those sections when you distribute them as separate works. But when you distribute the same sections as part of a whole which is a work based on the Program, the distribution of the whole must be on the terms of this License, whose permissions for other licensees extend to the entire whole, and thus to each and every part regardless of who wrote it.

      Thus, it is not the intent of this section to claim rights or contest your rights to work written entirely by you; rather, the intent is to exercise the right to control the distribution of derivative or collective works based on the Program.

      In addition, mere aggregation of another work not based on the Program with the Program (or with a work based on the Program) on a volume of a storage or distribution medium does not bring the other work under the scope of this License.

4. You may copy and distribute the Program (or a work based on it, under Section 2) in object code or executable form under the terms of Sections 1 and 2 above provided that you also do one of the following:

   1. Accompany it with the complete corresponding machine-readable source code, which must be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange; or,

   2. Accompany it with a written offer, valid for at least three years, to give any third party, for a charge no more than your cost of physically performing source distribution, a complete machine-readable copy of the corresponding source code, to be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange; or,

   3. Accompany it with the information you received as to the offer to distribute corresponding source code. (This alternative is allowed only for noncommercial distribution and only if you received the program in object code or executable form with such an offer, in accord with Subsection b above.)

   The source code for a work means the preferred form of the work for making modifications to it. For an executable work, complete source code means all the source code for all modules it contains, plus any associated interface definition files, plus the scripts used to control compilation and installation of the executable. However, as a special exception, the source code distributed need not include anything that is normally distributed (in either source or binary form) with the major components (compiler, kernel, and so on) of the operating system on which the executable runs, unless that component itself accompanies the executable.

   If distribution of executable or object code is made by offering access to copy from a designated place, then offering equivalent access to copy the source code from the same place counts as distribution of the source code, even though third parties are not compelled to copy the source along with the object code.

5. You may not copy, modify, sublicense, or distribute the Program except as expressly provided under this License. Any attempt otherwise to copy, modify, sublicense or distribute the Program is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance.

6. You are not required to accept this License, since you have not signed it. However, nothing else grants you permission to modify or distribute the Program or its derivative works. These actions are prohibited by law if you do not accept this License. Therefore, by modifying or distributing the Program (or any work based on the Program), you indicate your acceptance of this License to do so, and all its terms and conditions for copying, distributing or modifying the Program or works based on it.

7. Each time you redistribute the Program (or any work based on the Program), the recipient automatically receives a license from the original licensor to copy, distribute or modify the Program subject to these terms and conditions. You may not impose any further restrictions on the recipients' exercise of the rights granted herein. You are not responsible for enforcing compliance by third parties to this License.

8. If, as a consequence of a court judgment or allegation of patent infringement or for any other reason (not limited to patent issues), conditions are imposed on you (whether by court order, agreement or otherwise) that contradict the conditions of this License, they do not excuse you from the conditions of this License. If you cannot distribute so as to satisfy simultaneously your obligations under this License and any other pertinent obligations, then as a consequence you may not distribute the Program at all. For example, if a patent license would not permit royalty-free redistribution of the Program by all those who receive copies directly or indirectly through you, then the only way you could satisfy both it and this License would be to refrain entirely from distribution of the Program.

   If any portion of this section is held invalid or unenforceable under any particular circumstance, the balance of the section is intended to apply and the section as a whole is intended to apply in other circumstances.

   It is not the purpose of this section to induce you to infringe any patents or other property right claims or to contest validity of any such claims; this section has the sole purpose of protecting the integrity of the free software distribution system, which is implemented by public license practices. Many people have made generous contributions to the wide range of software distributed through that system in reliance on consistent application of that system; it is up to the author/donor to decide if he or she is willing to distribute software through any other system and a licensee cannot impose that choice.

   This section is intended to make thoroughly clear what is believed to be a consequence of the rest of this License.

9. If the distribution and/or use of the Program is restricted in certain countries either by patents or by copyrighted interfaces, the original copyright holder who places the Program under this License may add an explicit geographical distribution limitation excluding those countries, so that distribution is permitted only in or among countries not thus excluded. In such case, this License incorporates the limitation as if written in the body of this License.

10. The Free Software Foundation may publish revised and/or new versions of the General Public License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns.

    Each version is given a distinguishing version number. If the Program specifies a version number of this License which applies to it and "any later version", you have the option of following the terms and conditions either of that version or of any later version published by the Free Software Foundation. If the Program does not specify a version number of this License, you may choose any version ever published by the Free Software Foundation.

11. If you wish to incorporate parts of the Program into other free programs whose distribution conditions are different, write to the author to ask for permission. For software which is copyrighted by the Free Software Foundation, write to the Free Software Foundation; we sometimes make exceptions for this. Our decision will be guided by the two goals of preserving the free status of all derivatives of our free software and of promoting the sharing and reuse of software generally.

#### NO WARRANTY

1. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.

2. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

#### END OF TERMS AND CONDITIONS

### How to Apply These Terms to Your New Programs

If you develop a new program, and you want it to be of the greatest possible use to the public, the best way to achieve this is to make it free software which everyone can redistribute and change under these terms.

To do so, attach the following notices to the program. It is safest to attach them to the start of each source file to most effectively convey the exclusion of warranty; and each file should have at least the "copyright" line and a pointer to where the full notice is found.

    	  <one line to give the program's name and a brief idea of what it does.>
    	  Copyright (C) <year>  <name of author>

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA

Also add information on how to contact you by electronic and paper mail.

If the program is interactive, make it output a short notice like this when it starts in an interactive mode:

    	Gnomovision version 69, Copyright (C) year  name of author
    	Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
    	This is free software, and you are welcome to redistribute it
    under certain conditions; type `show c' for details.

The hypothetical commands `show w' and `show c' should show the appropriate parts of the General Public License. Of course, the commands you use may be called something other than `show w' and `show c'; they could even be mouse-clicks or menu items --whatever suits your program.

You should also get your employer (if you work as a programmer) or your school, if any, to sign a "copyright disclaimer" for the program, if necessary. Here is a sample; alter the names:

Yoyodyne, Inc., hereby disclaims all copyright interest in the program `Gnomovision' (which makes passes at compilers) written by James Hacker.

    	<signature of Ty Coon>, 1 April 1989
    	Ty Coon, President of Vice

This General Public License does not permit incorporating your program into proprietary programs. If your program is a subroutine library, you may consider it more useful to permit linking proprietary applications with the library. If this is what you want to do, use the GNU Library General Public License instead of this License.