mAirListDB HowTo

From mAirListWiki

(work in progress)

This article explains how to set up and use the built-in audio database mAirListDB which is available in mAirList 3.0.5 and above.

Important Note: mAirListDB is only available in the paid editions of mAirList (Personal Edition and Professional Edition).

About mAirListDB

mAirListDB (mAirList database) is a so-called music database or audio database. Its purpose is to store the list of audio files (but not the actual files), their properties (cue points etc.), and also to manage playlists built from these items.

You can manage mAirListDB using the database management application built in to mAirList (it is built into the mAirList.exe file just like the configuration tool and the file tagger). You can run this application by clicking Database in your mAirList Start menu folder (setup installation only) or by running mAirListDB.bat from your mAirList program folder.

mAirListDB is only available in the paid editions of mAirList (Personal Edition and Professional Edition). mAirListDB can be set up in two different modes:

In local mode, all data is stored in a single *.db file on your local hard disk.
In network mode (Professional Edition only), the data is stored on a PostgreSQL server which can be accessed from anywhere on your network. This is useful if you want to access and manage the database from multiple computers. (Please note that you are required to purchase a separate Management license for each computer.)

Once you have set up the database, you cannot change its mode, so you need to decide which mode (local or network) you want to use before you set up the database.

How to Create a New mAirListDB Database

The steps you use to create a new database are different for local mode and network mode databases, as described below.

Local Mode

To create a new mAirListDB database in local mode:

Open the mAirList configuration tool and navigate to the Databases page.
Click Add, and in the pop-up menu, click mAirListDB (local mode).
The mAirListDB configuration dialog will appear. Click Create new database.
Choose a file name for your new database. By default, the file will be saved in your mAirList program folder and will be named database.db, but you can choose any folder and any file name (with a .db extension) you wish.
After you confirm the folder and file name, a Setup completed successfully message box should appear after a few seconds.
If you wish, you can change the caption for your database (the default is Database). To change the caption, click the Miscellaneous tab and type a custom caption.
Click OK to close the setup dialog, then click Save (in the main configuration dialog) to save your changes.

Network Mode

Obtaining and Installing PostgreSQL

Before you can set up a mAirListDB in network mode, you must first install PostgreSQL, which is a free database management system. mAirListDB has only been tested with PostgreSQL 8.3. This is the most recent version, and is available for both Windows and Linux, as well as for several other Unix-like operating systems. Brief installation and setup instructions for Windows and Linux are below.

Windows

A so-called one-click installer is available from here. This distribution includes a very useful management application called pgAdmin III.

Download the installer and follow the installation instructions. If you encounter any problems, please refer to the PostgreSQL documentation.

After you have installed PostgreSQL, run pgAdmin. In the Object browser pane, double-click the PostgreSQL 8.3 (localhost:5432) node. You will be prompted for the server password you chose during the PostgreSQL setup.

Once you are connected, right-click the Login Roles node and click New Login Role. (In PostgreSQL terminology, a login role is the same thing as a database user.) Role names are case sensitive, and should ideally be all lower case, so in the New Login Role dialog, type mairlist as the role name, and pick a password. Leave all other options unchanged, especially the Role Privileges check boxes. Click OK to create the role.

Next, right-click the Databases node and click New Database. Just like role names, database names should ideally be all lower case, so type mairlist as the database name. Important: As the Owner, select the role mairlist which you created in the previous step. Make sure that Encoding is set to UTF8. Leave all other options unchanged. Now click OK to create the database. Once that's complete, you can close pgAdmin.

Linux

PostgreSQL 8.3 should be included in all recent Linux distributions. If not, you can download it from http://www.postgresql.org/download and install it separately.

pgAdmin III, the configuration tool mentioned in the Windows installation instructions above, is also available for Linux, so if you prefer a graphical setup, you can install it and follow the instructions above.

However, you can easily create the login role and database using the Linux console. First, open a console window and become root, usually using the su or sudo su command.

Next, change your user ID again, this time becoming the special PostgreSQL management user postgres:

# su postgres

The command prompt should now look something like postgres@computername$. With this user ID, you can create login roles and databases.

First, create a new login role named mairlist (in all lower case, as preferred by PostgreSQL):

# createuser -P mairlist

Pick a password for the user and enter it twice. Answer all questions with no. (The user does not need to be a super-user, nor does it need to be able to add other users or databases.)

Next, create a database named mairlist (again, all lower case) owned by the user mairlist:

# createdb -O mairlist -E UTF8 mairlist

A few seconds later, your database is ready for use. You can try to log in by typing

# psql -U mairlist -d mairlist -W

A Note About Networking

By default, both the Windows and Linux distributions of PostgreSQL only allow connections from the local PC and will block any connection attempts from other computers on your network. To allow access to the PostgreSQL server from other computers, you need to edit the pg_hba.conf file. On Linux, this file is located somewhere in /etc/postgresql. On Windows, the file is usually in C:\Program Files\PostgreSQL\8.3\data. You need to add a line to this file to allow access to the database via MD5 password authentication over your IP network. For example, if your network uses the address space 192.168.1.nnn, add the following line:

host    all         all         192.168.1.0/24      md5

Don't forget to restart the PostgreSQL server after you have saved the pg_hba.conf file!

You will also need to install the PostgreSQL Client Library on each 'remote' mAirList computer (see below).

Obtaining and Installing the PostgreSQL Client Library

To access a PostgreSQL server, mAirList needs to use the PostgreSQL client library (libpq.dll).

Starting from mAirList 3.0.8, the older version 7.4 of the client library is included in all mAirList setup packages as well as the zip file distribution. It's a single DLL file named libpq74.dll.

The newer version 8 of the client library can also be used, however, it needs numerous extra 'support' DLLs which will bloat your installation, so it's better to use the old libpq74.dll which is perfectly ok for the purpose of mAirList. If you still want to use the newer version, you can download it from http://www.mairlist.com/download/misc/libpq/ and unzZIP the contents of the postgresql-libs-<version>.zip file into your mAirList program folder. Important: You must use this method on each computer which accesses mAirListDB (and PostgreSQL) across your network.

Setting Up mAirList

After you have installed and prepared PostgreSQL (by creating the login role and database), you can configure mAirList:

Open the mAirList configuration tool and navigate to the Databases page.
Click Add, and from the pop-up menu, choose mAirListDB (network mode).
On the Connection tab, enter the information used to connect to your PostgreSQL server. Database and User should both be mairlist if you followed the instructions above. Host is either localhost or the name/IP address of the computer running the PostgreSQL server. Password is the password you chose for the mairlist role during PostgreSQL setup.
On the Setup tab, click Perform Initial Setup. After a few seconds, a message box saying Setup completed should appear.
Optionally, go to the Options tab and enter a custom caption for your database. The default caption is Database.
Click OK to close the setup dialog and click Save in the main configuration dialog to save your changes.

When mAirList starts up, it will use the user credentials you entered for its automatic connection to the mAirListDB database. By default, mAirListDB only operates with a single database user (role). Optionally, you can create multiple login roles and assign the table privileges on PostgreSQL level to each of them, and check the Management mode requires login option. A login dialog will appear when the management interface is started, requiring the user to enter their personal credentials. However, at the moment, this is only recommended for advanced users with experience in PostgreSQL rights management.

Managing Your Library

Once the mAirListDB connection is set up in the configuration tool, you can run the database management tool either by selecting Database from the mAirList Start menu group, or by running mAirListDB.bat from your mAirList program folder.

Adding Storages

Before you can add your audio files to mAirListDB, you need to tell mAirListDB where your audio files are stored.

In mAirListDB terminology, the audio file folders on your hard disk or network file server are called storages. This term was chosen because future versions of mAirList might support other data sources (for example, a web server).

To add one or more folders as a storage, click Administration, Manage Storages…, Add…. mAirListDB scans your folders recursively, so you don't need to Add subfolders separately—and if you did, this would result in unexpected behaviour. By default, the storage name is the folder name, but you can add an alias if you want the storage to have a different name (for example, New Tracks Folder or Main Library Files).

Adding Virtual Folders

You can set up a hierarchy of virtual folders to help you organize your audio files. Virtual folders only exist within mAirListDB, and are completely separate from the real file folders where your audio files are stored.

Once created, virtual folders can contain audio files from any of your storages, so you no longer need to (for example) store all your oldies in the same real audio file folder on disk.

To add a new virtual folder, select a folder in the tree on the Library page, then click New Folder in the toolbar. For example, you might create a virtual folder named Xmas to store all your Xmas-themed items, a virtual folder named 1950s to store all your items recorded in the years 1950–1959, or virtual folders like Ballads, Current Hits, Jingles, Sweepers, etc.

The virtual folder named Unsorted is always present and you cannot delete it. The Unsorted virtual folder contains all the audio files which you have not added to any other virtual folder.

Note that you can copy the same audio file into as many virtual folders as you like. So for example, you could copy the same station jingle audio file into virtual folders named Jingles, Station IDs, and Xmas Jingles; and the same song into virtual folders named 1970s, Disco, and Number Ones. This is helpful if you plan to use the Mini Scheduler to create playlists for automation.

On the other hand, if you are purely a live assist station which does not use scheduled playlists at all, we suggest that you at least create two virtual folders named Music and Jingles, but like everything in mAirList, how you set up your virtual folders is entirely your decision, based on how your station works.

Important: If you plan to use the Mini Scheduler to create playlists for automation, we suggest you first study how the Mini Scheduler works, then create virtual folders which will suit your hour templates.

Synchronizing a Storage

Once you have added a (real!) folder as a storage, you can import the list of audio files it contains and read the information (file tags etc.) from the audio files and MMD files in that folder and all its subfolders. The import process is called synchronization. To synchronize a storage, click Synchronize on the Playlist tab. If you have more than one storage, a menu will pop up to allow you to choose the storage you want to synchronize.

The synchronization dialog scans the storage and displays the list of new files on the left hand side. Select the files you want to import (by default, all files are selected), decide whether you want to Disable Auto Cue (the default is Enabled: see below), select the virtual folder where you want to save the imported files (the default is Unsorted), then click Import selected files.

Important: If Auto Cue is enabled in mAirList configuration, a synchronization will take much longer to run. This is why the Synchronization dialog contains a Disable Auto Cue check box, to allow you to 'switch off' Auto Cue for the current synchronization. Check this box if you have already set up cue points for all the files in the storage you are synchronizing. Even if Disable Auto Cue is unchecked, cue points will not be assigned during the synchronization unless Auto Cue is enabled in your mAirList configuration.

Depending on the speed of your computer, synchronization can process at least one thousand items in 35 minutes; or at least 1700 items per hour.

During the synchronization, mAirListDB reads all the ID3 tags and MMD files in the folder, exactly like dragging a file into mAirList (synchronization uses exactly the same mechanism). The progress of the synchronization is displayed in the status bar at the bottom of the dialog. When an item is successfully synchronized, it disappears from the New Files list.

You can interrupt the synchronization at any time by pressing the Esc key.

You can run a synchronization at any time to check for files which have been added to, renamed, or deleted from your storage since the last synchronization. If a file is missing, the dialog will give you the option to delete the corresponding database items. If a file has been renamed, it will appear in both lists (New and Missing). You can select both the old name and the new name, then click Fix renamed file to rename the file in the database.

After your files are synchronized, they appear in the virtual folder hierarchy on the Library tab. Double-click any item to edit its Properties.

Managing Playlists

If your station uses Automation for some or all of the broadcast day, mAirListDB can manage your hourly playlists (or 'music logs'); a playlist in this sense being a list of audio files to be played at a specific time on a specific day. In mAirList—like most other music scheduling applications—a playlist is scheduled to run 'on the hour,' so there is one playlist for each hourly 'slot' in the day. Hence, each playlist should have a duration of one hour, though you should make each playlist a few minutes longer than one hour, just in case an item in the playlist fails to play out or the playlist under-runs for any reason.

You manage your playlists using the Playlist tab in mAirListDB's main window. There's a date and time dropdown which you use to jump to a specific slot (day/hour), and two buttons labelled Previous and Next to display the playlist for one slot (hour) 'back' or 'forward,' respectively.

When you click Go To, a dialog will appear, displaying all the slots in the current week (you can also navigate to other weeks), along with the total duration of the playlist. Slots which already have some items assigned to them are displayed in green; slots which are empty are displayed in red. If a slot contains items which have a total playing time of less than one hour (which might result in a gap during automated playout), a small warning sign is displayed next to the duration.

You can create playlists manually, or automatically by using the built-in Mini Scheduler (see below), or you can import playlists created by external music scheduling applications such as RCS, SPC, or Music 1.

Manually Creating a Playlist

Creating a playlist manually is easy.

When you click the Playlist tab, the browser from the Library tab is displayed at the bottom of the screen. You can browse your virtual folders or search for an item, then use the mouse to drag any item into the playlist. To move items around within the playlist, drag them to the desired position. To delete an item from the playlist, press the Del key or click the Delete button.

To save the playlist, click the Save button in the toolbar.

You can customize any item in the playlist by overwriting the values in its Properties (like cue points, attributes, etc.) with different values which you want to apply only in this one playlist. For example, to make a song fade out earlier than it usually would: double-click the item to display its Properties dialog, click the PFL tab, adjust the Fade Out cue point, then click OK. If an item in the playlist has been customized, a small green pencil icon will appear beside the item in the playlist.

Using the Mini Scheduler

Creating playlists manually is fun, but is also hard work. At some point, you will want a way to create playlists automatically. This is what the Mini Scheduler does: it creates 'random' playlists by using some very basic rules.

Although the Mini Scheduler uses techniques and concepts very similar to those used in many professional music scheduling applications, it is not intended to replace them: the Mini Scheduler lacks many important features like fine-grained selection rules, artist separation rules, etc. That said, the Mini Scheduler is fine if all you want to do is create random playlists with the minimum effort.

Creating Hour Templates

Before the Mini Scheduler can create a playlist, it needs to know which virtual folders to pick files from, and in what order. To do this, you create a list called an hour template. For example, during a daytime hour, you might want a song from your Openers virtual folder, then one from Oldies, then a Current Hit followed by a Station ID, and so on. You can set up as many hour templates as you want. For example, you could create separate hour templates for daytime, drive time, night time, overnight, and weekends.

To create a new hour template, click Administration, Hour Templates in the main menu, then in the dialog which appears, click New. This will display the hour template editing dialog. First, type a name and an optional description for the new hour template. Next, add 'placeholder' items to the template list by clicking Add, then selecting the virtual folder to pick the item from when the actual playlist is generated later. Items you mark as Fixed will be placed in that position when the playlist is generated; non-Fixed items will be 'shuffled' into a random order during playlist generation. This lets you create any kind of hour template from a completely 'fixed' hour template (similar to a 'clockwheel' or 'format' in other music schedulers); to a free-format hour template which simply contains (for example) seven Current Hits and six Oldies in any order; or anything in between.

Once you have created and saved at least one hour template, you can click the Playlist tab in the main window, click the small arrow next to the Generate button, and select an hour template from the menu: this will create a playlist using the selected hour template and will load the generated template into the current selected slot (hour). More usually, you will want to create several playlists at the same time, but before you can do that, you need to assign hour templates to slots, as explained below.

Template Assignment

We suggested above that you might want to create different hour templates to generate playlists for different times of day (for example, speed metal might be fine during drive time but not during night time); and we also mentioned that you will probably want to generate playlists 'in bulk,' most likely for a whole week at a time.

You may already have worked out that the reason for these suggestions is that the Mini Scheduler, like most other music schedulers, needs to know which hour template you want it to use when generating the playlists for each hour of each day of the week (similar to setting up the items within your hour templates). In mAirListDB, this 'mapping' process is called template assignment.

To set up template assignments, click Administration, Template Assignments in the main menu. A dialog will appear displaying a 7×24 grid with one column for each day and one row for each slot (hour) of each day. Hold down the left mouse button and drag to select a range of slots, then right-click your selection, then click the hour template you want to use when generating the playlists for those slots. Repeat this process until you have selected an hour template for every slot which needs a playlist generated.

No playlists will be generated for empty slots, so you would definitely leave slots for pre-recorded shows empty. Depending on how your station works, you may want to leave your live assist hours empty or you may want to generate playlists for them.

Click OK to save your 'map' of template assignments.

Running the Mini Scheduler

Once you have created and assigned your hour templates, you can use the Mini Scheduler to create random playlists 'in bulk.' Click the Playlist tab, then click Generate. The Mini Scheduler dialog will appear.

Specify the period for which you want to generate playlists by selecting the first and last day of the period. To make this easier, there are a few shortcut buttons for frequently-used start dates and periods, such as Next Monday and One Week. You can also exclude the generation of playlists for specific slots (hours) by de-selecting those slots in the grid in the upper right corner of the dialog: this is useful if you have a temporary change to your normal schedule (for example, when broadcasting an external feed like an outside broadcast or an incoming audio stream from the Internet).

To start generating the playlists, click Go!. Progress will be displayed in the bottom half of the dialog, and you can preview each playlist as it is generated.

Importing Playlists Created By External Music Scheduling Applications

This feature is planned for implementation, but is not available at the time of writing.

Accessing the database from mAirList

Once you have created and set up your mAirListDB database, you can use it in the main mAirList application. Note that the techniques described below apply to all supported music databases (eldoDB, radioDB, …), including mAirListDB.

We assume that you already know how to use the main mAirList window, add mAirList browsers, etc.

You can use three types of mAirList browsers to access your database and the items inside it: a database browser, a database search browser, and a database playlist browser.

You can also automate the loading of your playlists using Events and Actions.

Using the Database Browser

Use the Database browser to browse the entire database in a tree, like the tree on the Library tab in the mAirListDB application. In the same way, you can expand any (virtual) folder to see the items inside it.

Like any other mAirList browser, use the mouse to drag an item into the playlist. You can also drag a folder if you want to add all the items in the folder to the playlist.

Using the Database Search Browser

Use the Database Search browser to search for items in the database. Type the text you want to find into the text box, then press the Enter key to search.

If you have more than one database, you can choose whether to search in all databases or in one specific database. The results are displayed in a list below the search text field.

In mAirList v3.0.5, you can only search in the Artist and Title fields.

You can set a minimum length for the search term you type into the Database Search browser by manually editing the GUI.ini configuration file. For example, adding the following two lines to GUI.ini will only allow search terms of at least three characters:

[DatabaseSearch]
MinChars=3

Using the Database Playlist Browser

Use the Database Playlist browser to browse the hourly playlists you have created with the Mini Scheduler (or manually).

You can navigate through your playlists using the date selection field, an hour selection dropdown, and the Previous/Next buttons. The playlist you select is loaded into the browser. You can then drag the individual items into the playlist; or you can click the small 'gearwheel' button, then use the menu to copy or append all the items into the playlist.

Events and Actions

If you want your station to operate unattended, you need to load a database playlist for each hour automatically. You do this by using the mAirList event scheduler using a special set of Actions.

We assume that you already know how to manage Events and Event lists.

The five Actions available for database playlists are:

Load database playlist
Load and play database playlist
Insert database playlist
Insert and play database playlist
Append database playlist

Note that:

Load means that the current contents of the main playlist are replaced by the database playlist.
Insert means that the database playlist is inserted after the currently playing item.
Append means that the database playlist is inserted at the end of the main playlist.

The … and play … Actions will issue an Automation PLAY or NEXT command after loading/inserting the database playlist, provided that mAirList is in AUTO mode at the time the Action is executed.

There are several Playlist Options available in the Properties dialog of these Actions:

Load the playlist for the next hour instead of the current one
By default, the database playlist for the current hour is loaded. If you are 'pre-loading' the playlist a few minutes before the hour, check this option so that the playlist for the next hour is loaded instead. (Checking this option is the same as setting the Time Adjustment to 01:00:00 on the Options tab.)

Set fixed time on first element
Check this option if you want a fixed time to be set on the first item of the database playlist. The beginning of the hour is used at the fixed time. This option is particularly useful when used together with the Append database playlist action.

Use soft fixed time
If checked, a soft fixed time is used instead of a hard one (the set fixed time option must be checked as well), so the current song will be finished before the automation jumps to the fixed time item.

Use an extra dummy element for fixed time
Instead of setting the fixed time of the first element, an extra dummy element titled "Top of the hour" is inserted at the top of the database playlist, and the fixed time is set on that extra item.

Report error if playlist is empty
By default, when the database playlist for the selected slot is empty, nothing will happen because there is nothing to insert. When this option is checked, an error is reported to the System Log when the playlist does not contain any items. Additionally, any emergency actions you might have set up will be executed.