mAirList Wiki

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Music Scheduling with mAirListDB ======


<WRAP info round>This article applies to mAirList 5.x and 6.x. For mAirList 4, see the [[tutorials:mairlistdb:music-scheduling-mairlist4|old version of this tutorial]].</WRAP>

In this article, we will show you how to import your audio files into mAirListDB and set up the "Mini Scheduler" music scheduling for 24/7 automated operation (or live assist, or mixed).

We assume that the mAirListDB connection has already been set up as described here:

  * [[setup-sqlite|SQLite backend setup]] (local mode)
  * [[setup-postgresql|PostgreSQL backend setup]] (networked)

You should be able to run the mAirListDB application ("database window") from the Windows Start Menu (mAirList (Version) -> Database).

===== Step 1: Add Audio Folders as Storages =====

mAirListDB keeps a list of your audio files in its Library, so the first step is to tell mAirListDB where your audio files are. We do this by registering one or more Windows folders (on your local hard driver or a network share) as **storages**. (In future versions, it might be possible to use other locations, e.g. servers in the cloud etc. - that's why the term "storages" is used instead of "folders").

So go to //Administration -> Configuration -> Storages// and add one or more folders.

Do not add individual subfolders of another storage! mAirListDB will automatically scan all subfolders!

{{ :tutorials:mairlistdb:pasted:20140221-111411.png }}

You will be able to enter a name and description for each storage that will later appear in the menus - by default, the name is just the folder name.

When you're done, click OK - you will be prompted to restart mAirListDB.
===== Step 2: Synchronize Storages =====

Now we are ready to scan your hard drive (the registered storages) for audio files. Click the //Synchronize// button, select the desired storage (if you have registered more than one), and the Synchronize dialog will appear:

{{ :tutorials:mairlistdb:pasted:20140221-112127.png }}

When the scan is complete, the list of new files (not yet part of the Library) is displayed on the left hand side. By default, all new items are selected, but if you don't want to import everything at this time, you can select individual items or a range of items with the mouse (hold down Ctrl or Shift and click).

It's a good idea to set the type of these files to "Music" (or whatever it is) at this point, in the Import Options section. You can also specify the virtual folder that the items should go into - as we haven't set up any folders yet, it's simply the Unsorted folder.

When ready, click //Import Selected Files//, and mAirListDB will open each file, analyze it (read tags, perform Auto Cue etc.), and add it to the Library.

When you add more files to your audio folder, you can return to the Synchronize dialog at any time and repeat the steps. If you happened to delete files, they will appear in the right-hand side list, and you have the option to remove them from the Library.
===== Step 3: Set up Virtual Folders =====

Your audio files have now been imported into the Library, but they are still in the //Unsorted// folder.

Now it's time to create a couple of library folders and sort your audio files into them. Library folders are purly **virtual** - they only exist in the database and are independet of your actual windows folders. You may or may not use the same folder structure as on your disk.

The virtual folders will later serve as music categories (or rotations).

So go to the //Library// tab and use the //New Folder// button in order to create one or more folders, then go to the //Unsorted// folder and move the audio files to the respective folder using the mouse (drag them from the list to the folder node in the tree on the left).

{{ :tutorials:mairlistdb:pasted:20140224-114037.png }}

Hint: If you are going to resemble the folder structure from Windows, it's a good idea to sort the item list by //Filename// (click the header), and then select a range files from the same Windows folder with the mouse while holding down Shift.
===== Step 4: Create Hour Templates =====

Music scheduling in mAirListDB works in an hourly grid, so we will be generating playlists worth 60 minutes each.

An //Hour Template// defines the structure on an hourly playlist, also called a **clock**. Clocks are often visualized in pie charts -- here's an example we will work with:

{{ :tutorials:mairlistdb:pasted:20150505-141935.png }}

There are four "fixed" blocks in this hour:

  * The news block (news, weather, traffic) at the top of the hour.
  * The first advertising block (at around xx:20)
  * The second advertising block (at around xx:40)
  * The third advertising block, right before the top of the hour.

In between these blocks, there is just music. Note that, on the clock/hour template level, we don't really care about the music, what categories/folder to use etc. -- this will be defined in the Music Templates later (see step 5 below).

==== Create an hour template ====

Go to //Administration -> Manage Templates//, stay on the first tab (//Hour Templates//), and click //New//. The hour template editor will appear -- on the first tab //General//, enter a useful name, then switch to the second tab //Items//:

{{ :tutorials:mairlistdb:pasted:20150505-142904.png?400 }}

The new hour template will initially have three items in it:

  * The start of the hour marker (with a fixed time of 00:00:00)
  * The end of the hour marker (with a fixed time of 01:00:00)
  * In between, a "fill with random items" block.

You can add more items by dragging them from the list on the left-hand side into the template, move the items around with the mouse (grab then in the first column), and edit their properties. In the next section, we will discuss the available template item types.
==== Available template items ====

=== Random item from folder ===

This will insert exactly one item from the specified folder (and optionally its subfolders). The scheduler will automatically pick the "best" items with regards to last use, track/title/artist separation etc. You can specify an optional attribute filter.

=== Fill with random items ===

Insert as many items from the specified folder to fill up the time until the following fixed-time item.

=== Specific item ===

Insert the item with the specified ID from the Library.

=== Music (one song) ===

Insert the next song from the specified music block. (Music blocks are discussed in step 5 below.)

=== Music block ===

Insert __the entire music block__ (or the remaining items from that block if you have used "one song" before).\\ 
Please note: If you try to give the music block a specific duration in the settings, it will be ignored.

=== Fill with music ===

Insert songs from the specified music block to fill up the time until the following fixed-time item or the defined duration in the settings.

=== Dummy ===

Insert a Dummy item -- you can specify artist, title, color and item type as required.

=== Start of hour marker ===

The "start of the hour" marker (turns into a Dummy item in the final playlist).

=== End of hour marker ===

The "end of the hour" marker (turns into a Dummy item in the final playlist).

The end of hour marker serves as a dummy item to ensure proper backtiming at the end of the hour, before the next hour is eventually loaded/appended to the playlist. **If you adjust the timing settings of the "start of the hour" marker, you must adjust the timing settings of the "end of the hour" marker accordingly!**

=== Sub-playlist as container ===

Sub-playlists allow you to manage more than playlist per hour, e.g. to keep advertising in a separate playlist. You can set them up in //Administration -> Configuration -> Sub-Playlists//.

This template item will make the scheduler take the entire content of the specified sub-playlist, wrap it into a container, and insert it into the playlist.

=== Next from sub-playlist ===

Inserts only one item from the specified sub-playlist (the next in queue).

=== All from sub-playlist ===

Inserts the entire sub-playlist, but without a container.

=== Region container ===

Inserts multiple sub-playlists, wrapped into a Region Container item.

=== Advertising ===

Inserts the specified advertising block. See [[Advertising Tutorial]].


==== Template item settings ====

In the respective //Properties// dialog, there is a couple of settings that most template items have in common.

=== Duration ===

Enter the **estimated** duration of this template item (or the playlist items it will generate).

//Infinite/fill// means that this template item fills the entire time between the surrounding items.

//Overflow by// instructs the scheduler to add additional songs to create an artificial/explicit overflow. It can only be used with //Fill with Random Items// and //Fill with Music//, and only when //inifinite/fill// is checked.

For most template items, duration entered here is solely for template design purposes in the template item editor. Generally, the duration of the generated playlist items will be unknown at the time you design the template (The "specific item" template item is an exception). 

//Fill with Random Items// and //Fill with Music// are an exception: If you enter an explicit duration here, the scheduler will create a block of that specific duration. On the other hand, if you check //infinite/fill//, the scheduler will fill the gap until the next fixed time items (plus an optional "overflow by" duration).


=== Timing ===

The following Timing options are available:

  * **Normal**: Item starts when the preceding item has finished (or reaches Start Next or Fade Out marker, whatever comes first).
  * **Hard fixed time**: Item is started at exactly the specified time.
  * **Soft fixed time**: Item is started at or after the specified time, when the current item has finished.
  * **Backtimed**: To be used directly before a //hard// or //soft// item; will propagate the fixed time further up the list, so that this item **finishes** at the fixed time. You can schedule multiple //backtimed// items in a row to build a "backtiming chain".
  * **Excluded from backtiming**: Item is ignored by the backtiming algorithm.

For //hard// and //soft// timing, enter the fixed time as required. Please note that fixed times in hour templates are always **relative to the top of the scheduled hour**. For example, a fixed time of 00:05:00 will be turned into 07:05:00 when the scheduler uses the template to generate a 07:00:00 hour. 

The option //Before top of the hour// lets you use "negative" fixed times, e.g. move the start of the hour to xx:55:00 in the preceding hour (- 00:05:00).

The setting //Time frame//, when used together with //soft// timing, lets you limit the playback duration of the current item. For example, with a //soft// fixed time of 00:30:00, and a time frame of 60 seconds, the item will be started when the current item has finished, but not later than 00:31:00.

=== Options ===

  * **Create a container if more than one item**: Only applies to template items which can result in more than one playlist item being added to the playlist (e.g. //Music block// or //Fill with random item//): Wrap the playlist items into a container if two or more items were added.
  * **Always create a container**: Wrap the resulting item(s) into a container, regardless of the number of items.

=== Opener and Closer ===

Specify the ID of an opener and/or closer element to be scheduled before and after the playlist items generated by this template item. Note: This will override any opener and closer set in the folder configuration.

=== Restrictions ===

On this tab, specify the days and hours in which this template item should be used. If you uncheck an hour, the template item will be ignored for that hour. Note: You can click the colum/row headers to toggle multiple cells at one time.

==== Example hour template ====

Here's our sample clock, introduced at the beginning of this chapter, built as an Hour Template in mAirListDB:

{{ :tutorials:mairlistdb:pasted:20150506-113058.png?400 }}

===== Step 5: Set up Music Templates =====

Next step is to create a music template.

==== About music templates ====

In the music template, you tell the scheduler how to pick the music for the generated hour playlists. Typically, this involves specifying one or more library folders (acting as categories, or rotations).

Earlier versions of mAirList only had hour templates, no music templates, and the music mix was defined directly inside the hour template. Since the introduction of mAirList 5, it is recommended that you use separate hour and music templates. (You can still use the "random item from folder" template item to mimic the old behavior, but this is not recommended.)

Separate music and hour templates have a couple of advantages:

  * Separation of concerns: Define the hour template (clock) without caring about the music, and define the music without caring about the structure of the hour.
  * Mix'n'match: You can reuse a music template for multiple hour templates, and also use different music templates with the same hour template.

If you are using an external scheduler (e.g. MusicMaster, Powergold, Music1, etc.), use a music template to specify the file names and options for your imported playlists. You can also mix internal and external scheduling (use import playlists for some blocks, and the internal scheduler for the other blocks).

==== About music blocks ====

We assume that music appears in **blocks** between other scheduled content (e.g. news, advertising, ...) within the hour. For instance, in the example hour template we discussed in Step 4 there were three music blocks: First between the news break and the first ad break, the second between the first and second ad break, and the third music block between the second ad break and the ad block at the end of the hour.

Music templates allow you define up to 16 blocks of music per hour, and specify separate rules for each block. However, when the rules are the same for all block, you can simply work with Block 1 only, and reuse it multiple times inside the hour template (depending on the hour template item you use, and the mode for that block -- see below).

==== Create a music template ====

Go to //Administration -> Edit templates//, switch to the //Music Templates// tab, and click //Add//. The music template editor will appear. Enter a useful name on the //General// tab, then go to the //Block definition// tab and observe the block configuraion:

{{ :tutorials:mairlistdb:pasted:20150506-120627.png?400 }}

Use the tabs at the top to switch between block 1 through 16. Under //Settings// you can specify the source for this block (internal scheduler or export from file -- the latter is discussed below), and the folder selection mode (also discussed below).

Then there is the list of folders to be used for this block (initially empty), and the list of available folders from the library -- just use the mouse to drag a folder to the list of used folders. You can double-click a folder to set a couple of options: Also use subfolders, opener and closer, and optional type/attribute filters.

==== Folder selection modes ====

In the //Mode// dropdown, you will find five different modes in which the scheduler can operate for this block:

=== Randomly pick from the list of folders/items ===

Whenever the scheduler needs a music item for this block, it first picks a random folder from the list of folders you specified, then selects a random item from that folder. This is the most simple way to pick music.

Note: This mode does not work with the //Music block// template item.

=== Use exact order ===

The scheduler will walk the list of folders you specified from top to bottom, picking one song from each folder. When the scheduler reaches the end of the folder list, no more music is generated for this block.

=== Use exact order, repeat if necessary ===

Same as above, but when used with //Fill with music//, the scheduler is allowed to restart from the top of the folder list if more music is needed than it got from a single iteration.

=== Maintain order, allow random selection ===

This works similar to //Use exact order//, however, it may skip folders from the **middle** of the list if you specified more folders than required.

To understand the difference, imagine you have specified five folders: A, B, C, D, E. Also assume that there is a //Fill with music// item for this block in the hour template, and the scheduler finds that it only needs three songs to fill up the time, not five:

  * With //Use exact order//, the folders A, B, and C will always be used. D and E will never be used.
  * With //Maintain order//, the following folder combinations will be possible: A-B-C, A-B-D, A-B-E, A-C-D, A-C-E, A-D-E.

So the order of the folders will always be maintained, but some folders from the **middle** of this list may be skipped, not only from the end.

=== Maintain order, allow random selection, repeat if necessary ===

Same as above, but allows the scheduler to restart if more music is required.

==== About "random" selection ====

When we say that the scheduler "randomly" picks an item from a folder, this isn't all "random", but of course there is a particular scheme that tries to maintain a rotation-like order of the songs while using as much "randomness" as possible.

If you are interested in the internals of the Mini Scheduler, here's an outline of the algorithm:

  * First, all songs of the folder are sorted according to the time they were last scheduled, with those that haven't been used for the longest time at the top of the list. Only full hours are respected, not the position within the hour.
  * If you specified any type or attribute filters, only the songs that match the filter will be considered in the following steps.
  * For all songs, the overall penalty is calculated according to the title/track/artist separation configuration.
  * The song with the minimum penalty will pe picked. If there is more than one song with minumum penalty, the scheduler will pick the first one (with a probability of 1/2), or the second one (with a probability of 1/4), and so on.

==== Import from external schedulers ====

If you are importing music logs from an external music scheduling software, go to the //Import Settings// tab and set up the file type and location of your music logs. 

{{ :tutorials:mairlistdb:pasted:20180109-182432.png?400 }}

Specify whether you have one file per day or per hour, or even per music block. Some formats can automatically split daily logs into hours automatically. For other formats, you have the option to split by time, title etc.

For the source folder and/our filename format, you can use the date/time [[reference:logging_variables|logging variables]] as placeholders.

Don't forget to set the //Source// of all relevant music blocks to //External scheduler//! The third option, //Hybrid//, will try to load the log from the specified file first, and fall back to internal scheduler if that fails.

==== Transitions ====

On the //Transitions// tab, you can instruct the scheduler to insert transition jingles between music items. Click //Add// to add a new transition rule:

{{ :tutorials:mairlistdb:pasted:20150506-140244.png?400 }}

Specify the number of songs that should be played in a row before the rule is applied, and also the folder to pick the jingle from, possibly including its subfolders. 

If you choose to specify **Conditions** for either item 1 or item 2, the rule will only be applied if the attributes of the music items satisfy the particular conditions. For example, you can set up a rule that is only applied for "fast" songs following a "slow" song, with a special set of jingles for this kind of (speed) transition.

Set up as many rules as you like. Rules are processed from top to bottom, and the first matching rule will win, so put more specific rules to the top, and more general rules to the bottom of the list.
===== Step 6: Set up Template Assignment =====

As mentioned earlier, you can easily setup multiple hour templates, each with a different kind of music. The missing piece of the puzzle is to tell mAirListDB which template to use on which day of the week and for which hour.

Go to //Administration -> Configuration -> Template Assignments//, and the following dialog will show up:

{{ :tutorials:mairlistdb:pasted:20150506-140848.png?400 }}

The 24x7 grid is initially empty - to set an assignment, select a range of hours/days with the mouse (hold down the left mouse button), the right-click and select the desired template. Repeat the steps until a template is assigned to all 24x7 slots.

Then switch to the //Music Template// tab, and repeat the above steps, selecting a music template for each day and hour.
===== Step 7: Generate Playlists =====

Ok, we're ready to generate playlists now.

==== Generate a Single Playlist ====

To generate a single playlist for a particular date and hour, go to the //Playlist// tab of mAirListDB and navigate to the desired hour.

Then click the small arrow next to the //Generate// button in the toolbar, and select the hour template from the list, then the music template from the submenu that pops up. The scheduler will generate a playlist and display it in the playlist editor. Click //Save// to save the playlist to the database.

==== Generate Multiple Playlists ====

Usually you wouldn't generate the playlists one by one, but schedule an entire day or week at once. This is where the //Mini Scheduler// dialog comes into play. To open it, click //Generate// in the toolbar.

{{ :tutorials:mairlistdb:pasted:20140224-152240.png }}

In the upper left section, select the start and end date for which you are going to generate playlists. Use the buttons as shortcuts for some common start days and perios.

In the upper right corner, check the hours for which playlists should be generated on the selected dates. Default is all hours (that is, all hours for which a template is assigned, see notes about hour template assignments above).

Then click //Go// and lean back while Mini Schedule does its job. When generation is finished, close the dialog and navigate through the playlists (and possibly edit them) in the playlist editor.
===== Step 8: Access Playlist from Playout Window =====

Now that we have playlists prepared for the current hour (and the next hours, days, ...), we can return to the playout window (main window) of mAirList and use them.

==== Database Playlist Browser ====

In a Live Assist situation, the presenter will probably want to load the playlist manually shortly before the hour. That's what the //Database Playlist// browser is used for. Click the small arrow next to the //Add// button in the browser section of the playout window, then select //Database Playlist//. The following tab will be added to the browser:

{{ :tutorials:mairlistdb:pasted:20140224-152953.png }}

The drop-down box at the top is used to select the database connection, in case you have set up multiple databases - otherwise it is not visible.

Below that you will find the controls to navigate through the hours. The playlist for the selected hour is display instantly as you switch between the hours. To load the list into the playout playlist, click the small "gear" button, and select one of the commands (load/append/...) from the menu.

==== Set up an Hourly Event for Automation ====

In an automated environment, mAirList must load the playlist for the next hour automatically at the top of the hour. This is achieved by adding a (single) event to the Event Scheduler. Click //Events// in the main toolbar, and in the dialog that appears, click //Add// to add a new event.

{{ :tutorials:mairlistdb:pasted:20140224-153823.png }}

=== Simple Event with Load and Play Database Playlist ===

The event is configured so that it runs each day, each hour at 0 minutes and 0 seconds (see screenshot). In the //Actions// section, add a new //Load and play database playlist// action, and leave all of its settings untouched.

{{ :tutorials:mairlistdb:pasted:20140224-154125.png }}

That's it - at the top of the hour, mAirList will grab the next playlist from the database and play it. All you have to do is to turn on AUTO mode.

=== Alternative Method using Append Database Playlist ===

Another option is to execute the event a few minutes before the top of the hour, and use the //Append Database Playlist// action instead.

**Important:** Check the //Load playlist of next hour// option in the event settings! (Remember it's still a few minutes before the top of the hour when the event runs.)

If the playlist has a soft or hard fixed time on its first item (which is usually the case), mAirList will automatically fade to that first item at xx:00:00 (hard fixed time), or when the last song has finished (soft fixed time).

The advantage of this method is that you can mix soft and hard fixed times by just changing the playlists in the database accordingly, and you can also schedule multi-hour content by removing the End of Hour marker, and leave the subsequent playlists empty in the database.

==== Generate Playlists from an Event ====

In a typical radio station environment, playlists for the next day(s) are generated manually from the Database application in advanced. For 24/7 unattended stations, you may choose to have the playoust process generate the playlists automatically. This is done by using the //Generate playlists// action in the Event Manager, either in another event (that runs a couple of minutes before the load/append event), or as another action inside the load/append event (take care of the correct order of actions - generate must happen first). By default, the //Generate Playlists// action will not overwrite existing playlists; so you can safely set it up as a "fallback" event, even if you plan to schedule manually in the general case.