Scheduling & Logging reference

Introduction

Scheduling software traditionally costs thousands of dollars, often only available via expensive monthly lease arrangements. Even when using this expensive scheduling software, you don't usually have the ability to generate playlist segments that will last for exactly one hour, or some other target time, since the scheduling software does not know how the playout system will actually mix the tracks. How items are mixed affects how long a playlist consisting of those items will take to play. Ots Corporation have now brought the power of advanced playlist generation and scheduling to the masses, by introducing OtsAV with Scheduling & Logging features.

Scheduling & Logging overview

OtsAV "Scheduling & Logging" adds the following functionality to OtsAV:

1. Optional automatic logging of all played items, and in a separate log file, the logging of scheduling events.

2. A high-level event-driven scheduler, which can control various aspects of OtsAV, including the Playlist Generator.

3. Enhancements to the Playlist Generator, such that it can accurately generate playlist segments which are targeted to a very specific play duration, and will achieve this target to within +/- one second!! Perfect for timing accurately and automatically into the top of the hour for news, etc.

Logging overview

Logging is the simplest to understand feature of the new functionality. OtsAV will write to two separate log files, one, a play log, the other, a scheduling event log. The play log will include all items which were played to air. By "played to air", we mean that the song was in play mode in one of the decks, and the mixer was not preventing the song from going to air. Ie. if the deck was only being routed through the "cue" channel, and not the "air" channel, or if the crossfader was set to hard left or hard right so that the song could not be heard on air, or the level control for the deck was right down at the bottom (-96db), then the song is not considered to be "played to air". Even while a song is playing in this state, as soon as one of the conditions changes such that the song now can be heard on air, the log file entry will then be written at that point, and the song is now considered to have started playing to air. What this means is that you can try songs out in a spare deck on cue, etc, and not have a log entry added to the play log (which would be undesirable since you are not really playing the song at that time).

Please note that if you enable in OtsAV the Options->Do Not Update Item Last Play Info option, then songs which are played (even to air) will not be logged. This option is intended for when a DJ is "playing around" and wants to play songs in rehersal for a gig or a show, but does not want the last play info to be altered, since this rehersal is just that -- only a rehersal. This option prevents the last play info in the Media Library from being updated. Scheduling & Logging also respects this option, and supresses updates to the play log if it is enabled.

Therefore, since the play log only includes items which truly were played to air, and contains the exact time the item went to air (to-the-second), the play log is perfect for submission to the relevant broadcast authority within your country. If other additional fields are needed/required within these play logs, Scheduling & Logging will likely be updated to handle this, if there is sufficient feedback from customers.

The event log is simply a log of all events (or associated errors) triggered by the Scheduler. More information about the Scheduler is included later in this document. Note that if logging is disabled, then output to both the play log and the event log is suppressed.

Log file path and filenames

By default the log files are written to the C:\OtsLabs\Logs directory, though this can be overriden by specifying the /LOGPATH="C:\some\other\dir" option at program startup. The only reason why you would probably want to specify a different directory, is if you were running multiple instances of OtsAV, and were streaming say, 4 different stations. You would want a separate log directory for each instance, otherwise the log files may become corrupt as the different instances of OtsAV try and access it. Not only that, but it would be impossible to know which instance had written each line entry into the log file, so the log would become pretty meaningless. Apart from the scenario of running multiple instances, you are best leaving the log directory at its default of C:\OtsLabs\Logs.

Although the log path (directory) is configurable, the actual filenames of the two logs are not. This is because they are based on the current day's date. Each file will only ever contain one day's worth of logs, since at the change of date at midnight, the log filenames also change. The format used for the play log is as follows:

2002-05-19-playlog.txt

whereby the date is always the current day's date, as interpreted by your local timezone settings.

The format used for the scheduling event log is as follows:

2002-05-19-eventlog.txt

whereby the date is always the current day's date, as interpreted by your local timezone settings.

This means that over time you may find you log directory looks something like the following:

2002-05-01-eventlog.txt

2002-05-01-playlog.txt

2002-05-02-eventlog.txt

2002-05-02-playlog.txt

2002-05-03-eventlog.txt

2002-05-03-playlog.txt

with each file corresponding to one day.

This filenaming convention was chosen because it means that when viewing the log directory sorted in alphabetical order, it is easy to locate a file based by date, since the file listing will be in chronological order.

Log file maintenance

There is very litte you need to do to maintain the logs. You simply read/access them as you need to. The one exception to this is that you would probably want to periodically clean out the log file directory and copy all logs older than one month or so, to another directory. You may zip them up, or simply group them by month into a sub-directory. The reason for this, apart from keeping things tidy, is that some filesystems (like FAT16/FAT32) do not handle directories which have thousands of files in them very well. Since OtsAV needs to regularly write to files in the logs directory, you probably don't want performance to suffer by having thousands of files in there. Periodic housecleaning is therefore recommended.

The NTFS filesystem that Windows 2000/XP/Vista uses is a lot better in this regard, but the same principles apply and performance can still suffer, therefore you don't want thousands of log files in the same directory -- even if you're using the NTFS filesysten.

Scheduling overview

Scheduling & Logging includes a high-level event-driven scheduler. High-level, for the fact that you do not use it to schedule individual items, but rather you use it to schedule playlist segments, via the Playlist Generator. The scheduler is able to control the Playlist Generator, and in addition, Scheduling & Logging enhances the Playlist Generator with powerful functionality enabling it to generate highly targeted playlist segments of an exact duration, usually one hour.

The Scheduler can control some other aspects of OtsAV too, but the real power is in its interaction with the Playlist Generator.

Before you can really understand how to use the Scheduler -- and how it will benefit you -- it's vital to understand how the Playlist Generator works, and the format employed with Ots Playlist Template (.OTM) files. If you have not read and understood these aspects, it is advisable to stop reading this document now, and return after having read the other relevant documents.

Using the Scheduler

In OtsAV's main menu, choose Edit->Scheduling & Logging to bring up the Scheduling Control Dialog. (You can also access this dialog box, and some other related functions, from the Options->Scheduling & Logging sub-menu.)

The Scheduler is based upon a script, much like the Generate Playlist function is based on a script (Ots Playlist Template). In the case of the Scheduler, this script is called the Scheduling Event Table. Just like the playlist templates, scheduling event tables can be saved and loaded to/from your hard disk or network share. Scheduling Event Tables have the file extension of .OSH. OtsAV can be launched, and the event table can be invoked, simply by double-clicking one of these files in Windows Explorer, or on your desktop. Usually though, you probably won't want to start OtsAV this way.

The Scheduler can be enabled or disabled, and logging can be enabled or disabled. You would normally leave logging enabled all of the time, unless you have a special reason for disabling it. The Scheduler should only be enabled when you want to give it the power to control OtsAV.

Starting the Scheduler from the command-line

If you would like to start OtsAV, and have the Scheduler automatically load a given .OSH file and enable itself, you can do it with the /SCHEDULE="scheduling_event_table_file.osh" command-line option.

The file specified must be a fully qualified filename, ie. it must contain the full path to the file. Providing that the file is valid, can be opened and loaded, and contains a valid event table, then OtsAV will automatically place the Scheduler in an enabled state once the file is loaded and applied.

Ots Scheduling Event Table format explained

The Ots Scheduling Event Table (from herein referred to as "event table") format is actually a very simple format. It is a plain-text (ASCII) file. Blank lines are ignored, and lines which begin with the hash (#) symbol are treated as comments (ignored).

Apart from blank lines and comments, each line represents an event. If a line is invalid or does not conform to the correct syntax, you will get a "parsing error" when you try to apply the event table. Unfortunately OtsAV does not as of yet tell you exactly which line caused the error, so you must pay attention to your syntax. Please note that case is not an issue -- you can use all lower, all upper, or a combination of both, without any change in meaning of your event table.

An event contains a trigger and an action. The trigger is a way of describing when you want this event to occur. The action defines what you want to occur.

An example line in an event table is:

Tue-08:00 Play

This line simply says "at 8am on Tuesday, start playing".

Event Table Triggers explained

A trigger is fairly flexible. It can describe an exact time, or wildcards can be used in certain areas. The rough format of a trigger is:

day-hh:mm

where day should be the first three letters of the day-of-the-week you want this trigger to match with, hh is the hour (in 24-hour time), and mm is the minute. There are also some special values for some of the fields.

For the day field, the following values are all valid:

Sun, Mon, Tue, Wed, Thu, Fri, Sat - meaning is as you would expect.

WKD - means "any weekday", ie. Monday to Friday

WKE - means "weekend", ie. Saturday or Sunday

* - means "everyday"

Note that you can also omit the day field altogether, and it is then assumed that you mean "everyday". Therefore, the two following triggers are identical in meaning:

*-09:30

09:30

For the hour field, you must either specify a specific hour in 24-hour time, such as "00", "09", "18", etc, or you may specify a wildcard with "*", which means that every hour will match and cause the event to be triggered.

Note that although it is good practice to specify two digits for the hour field, such as "09", you can actually just specify "9", and the meaning will be the same, without any error.

The final field is the minute field. This field must have a value between "00" and "59". You can not use a wildcard in place of the minute field.

Some trigger examples, and their associated meanings:

Fri-13:30	1:30pm on Fridays.
*-10:07	10:07am everyday.
10:07	10:07am everyday.
*:20	20 minutes past the hour, every hour of every day.
Thu-*:45	45 minutes past the hour, every hour, but only on Thursdays.
WKD-11:40	11:40am on weekdays (Monday to Friday).
WKE-*:10	10 minutes past the hour, every hour, but only on weekends (Saturday & Sunday).

Event Table Action reference

After the trigger, you must specify an action. Actions are always a single word (or combined word), but some actions take additional arguments which must be specified after them on the same line.

Valid actions are:

AutoDJ

AutoDJ must be specified with either "On" or "Off" as the first and only argument. This action turns OtsAV's Auto DJ feature on or off, just as if you had clicked the toolbar button yourself, or used the Ctrl+D keyboard shortcut.

Examples:

10:30 AutoDJ Off

12:30 AutoDJ On

Clear

This action clears the current playlist. Example:

WKD-15:30 Clear

Clear/Eject

This action clears the current playlist and ejects both decks (stopping play if either of them were currently playing). Example:

18:00 Clear/Eject

Disable

This action disables the Scheduler. OtsAV is not stopped, but no more events can be triggered, because the Scheduler is now disabled. You would have to re-enable the Scheduler manually to give it the power to trigger any more events. Example:

18:02 Disable

Eject

This action ejects both decks (stopping play if either of them were currently playing). Example:

22:00 Eject

Exit

This action causes OtsAV to exit. The Media Library is automatically saved to the current OML file. If you have Live Protection enabled in OtsAV, then you will receive a prompt about exiting, so you should not use Live Protection if you want the Scheduler to truly be able to exit OtsAV. This is deliberate behaviour as we feel that Live Protection should really be live protection -- ie. nothing, including the Scheduler should be able to exit OtsAV without the operator's consent. Live Protection is typically used by DJs who are performing live at a gig, whereby an unexpected program exit would be embarrassing!

Play

This action is the same as pressing the Play button on the OtsAV toolbar. If a deck is loaded, it will begin playing. If no deck is loaded, the first item in the playlist will be loaded and started. If both decks are empty, and the playlist is empty, then this action will do nothing. Example:

WKE:09:00 Play

SaveOML

This action is identical to using the File->Media Library->Save menu option in OtsAV. The current state of the Media Library is saved to the current OML file. It may be a good idea to have this occur once every hour, so that in the event of a power failure or system crash, you would not lose very much data. (Remember that OtsAV is constantly updating the last play info for each item as items are played, so even if you haven't done much that you think would change the Media Library, there is still all of the last play info that needs to be saved if you care about your OMQL queries, and hence playlist segments, being accurately based upon your rules). Example:

*-*:01 SaveOML

Stop

This action is identical to clicking the Stop button on the OtsAV toolbar. The playing deck (or decks) are stopped. Example:

16:30 Stop

Template

This is the most powerful and complicated action, though it is still quite simple to use and understand. Basically, this action causes a playlist segment to be generated, just as if you had gone into the Playlist Generator manually, loaded an Ots Playlist Template (.OTM) file, and clicked "Generate...".

The Template action requires 3 arguments. First here's a quick example, then the details of each argument follow:

WKD-*:07 Template End 1 My Cool Hourly Template.otm

The first argument may be one of the following three options:

End

Replace

Replace/Play

"End" causes the generated playlist to be appended to the end of the current playlist.

"Replace" causes the generated playlist to replace the current playlist.

"Replace/Play" is the same as Replace, except that it also causes OtsAV to start playing the new playlist once it has been generated.

The second argument is a value (between 0 and 65535 -- though some high values will cause errors in the Playlist Generator). This value is used to override the value used in the playlist template in the global "~length" option. If you specify zero here, then no overriding takes place, and the value from the template is used as is. Let's say that the playlist template had "~length items=150", and you specified "250" as the override value, then the playlist template would be generated as if it had said "~length items=250" for that particular option. If it has "~length iterations=1", then a value of "3" specified here will override this to be 3 iterations.

The primary use of this is when the playlist template is using the special enhanced target mode, which Scheduling & Logging provides, and you have a length option like "~length iterations=1, target=60", which would ordinarily generate exactly one hour worth of programming, but you want to generate more hours without having to trigger more events.

The final argument is simply the filename of the Ots Playlist Template (.OTM) file you wish to generate a playlist against. If you specify just the filename, then it is assumed that it resides in the default template directory, which is at C:\OtsLabs\Templates (unless you installed Ots somewhere else). In addition, if you have used the /TemplatePath="some_directory" command-line option when starting OtsAV, then this alternative directory is assumed to be the default instead. Finally, if you specify a fully-qualified .OTM filename (ie. including the full path), then it is referenced as is, and the default template directory becomes irrelevant to this event.

The filename may contain spaces. Do not surround the filename with quotation marks. The filename is terminated by the end of the line (so make sure you do not have any additional spaces after the ".otm").

Viewing the current Event Table

When you load or type in a new event table, the Scheduler will ask you whether you want to apply it when you go to exit the dialog box, or enable the Scheduler. "Applying" the event table, simply means that the table becomes the current event table -- ie. the table that is currently active if the Scheduler is enabled, or would be active if the Scheduler was enabled. If you choose "No" to the apply question, then you have not affected the current event table, however the event table you see in the dialog box will still be the new version that you had edited or loaded (but not applied). Therefore you can't always rely on the event table you see in the dialog box being the same as the one that is actually the current one.

To view the current event table, simply click the "Current..." button, or choose the Options->Scheduling & Logging->Show Current Scheduling Event Table menu option. This gives you positive confirmation of the event table that the Scheduler is actually running on right now (if the Scheduler is enabled), or would run on (if it were enabled).

Playlist Segment generation

Although there are a lot of different ways you can use the scheduling functionality, by using the basic building blocks provided by the various event actions, the usual way that it is intended that a full-time radio station will use the Scheduler is as follows:

Create playlist template files for each of the various programming styles you wish to broadcast. Although it is not required, it is probably easier if each of these templates are based on a one-hour iteration length. Most radio stations use one-hourly blocks as their basic programming building blocks, and we recommend you do the same. For very simple programming situations, where your music style/pattern does not vary much from hour to hour, you may find that generating just one playlist template is all you need to do! For most stations however, you will want a different style of mix in the morning as you would in the evening, for example. You may have 3 unique hourly templates, you may have ten, or you may even have 168 (one for every hour of the week)! That's really up to you and the sound/variety you wish to have for your station. Obviously creating 168 templates is a lot more work than creating just a few.

Many stations will have a different template for each (or most) hours of the normal weekday. Ie, they will have a template for 9am, and for 10am, etc, but the templates for each of these hours will be the same between the various days of Monday, Tuesday, ... Friday. On Saturday and Sunday however, they will have different templates. This is really all up to you. The Scheduler does not care how you set up your station. The main thing is that for every hour that you plan to be on the air, you do have a template which you are happy to be used for this hour of programming.

Create an event table that references your various playlist templates, at the correct times. Now here is where the fun part begins! What is the correct time to generate a new hourly playlist segment? Well, again, it really is up to you. You can use a JIT (just-in-time) style of programming, whereby you only generate the next complete hour of programming just a few minutes before that hour is due to go to air. However, for most stations, JIT programming is a nightmare, plus you do not get the benefit of item title/artist separation, since the playlist is almost empty by the time the new segment is generated.

The best time to generate a new hourly playlist segment is at least one hour, but preferably two hours, before the playlist segment being generated will actually go to air. If you don't care about having flexibility right up to a few hours before, then you may even take this one step further, and generate you entire day's worth of programming at pretty much the start of each day, during off-peak time. This will be suitable for many, but of course is no good for those that want to be able to make "close-to-last-minute" changes to their programming. Of course you can always make changes to your OtsAV playlist manually, no matter how much programming you have pre-generated. For changes at the template or scheduling level -- if you want to have the flexibility of doing these close to the last minute -- then you probably should generate playlist segments approximately two hours before that segment is due to go on air.

Using this system, you are always adding the freshly generated playlist to the end of the current playlist. The replace and replace/play options are more useful for people who do things on a 9am - 5pm basis, say for an automated office music system.

Event clashes

Although unlikely, it is possible for an event to fail because it clashed with another (incompatible) event that was going on in the system at the same time. For a fully automated system, this will not happen unless you program your events in a careless manner. For a system that has a live jock sitting there some of the time, you will want to make them aware of certain things that should not be done.

You can not trigger more than one event at the same time. If the Scheduler encounters two events in the event table that match the same time, it will only trigger the first one. By implication, that means that events will always be separated by at least one minute, since seconds can not be specified in the trigger. This one-minute separation time, basically prevents any clashes, even if you did create a careless event table. There are some exceptions however. Although playlist generation is normally very quick -- just a second or two for a one-hour segment -- it's possible that you could tell the Scheduler to generate a huge number of iterations of your playlist template. Although this would be silly, it would tie up the Playlist Generator for quite a while, perhaps minutes, which would mean that if another "template" event occured while the Playlist Generator was still busy, then this second one would fail. Although this will not happen if you do things sensibly, it's good to be aware of it. Look at the event log file for info about what was triggered and when. If an error occurs, it will normally be logged in the event log, although it is possible for some errors to occur which are not logged (we will try to improve this in a later version).

For the scenario of a live jock sitting there, playing around, if they do something such as generate a playlist themself, at the exact time that the Scheduler tries to generate a playlist, then obviously the operation will fail. You wouldn't imagine that it would make sense for them to do this though -- either you're running automated or manual! However, it would be a good idea to tell them that "at 1 minute past each hour, the Media Library is saved and at 3 minutes past each hour, another hourly segment is generated and added to the end of the playlist -- don't fiddle with things at those times!"

Importing/Refreshing Ots files also locks out the Playlist Generator from working at the same time, so be sure to not do these (manual) things when the Scheduler is about to trigger another playlist segment, unless you don't really care about the event failing.

Generating targeted hourly playlist segments

If you're a 24/7 radio station, and using the above system, then two things are vital:

1. That each of the hourly playlist segments really do last for one hour.

2. That the whole thing doesn't slowly get out of sync, from an announcer speaking a bit too long during a break, or natural sound card drift, or whatever.

Scheduling & Logging allows you to generate targeted playlist segments. What you do is generate a playlist template just like you normally would, except that you try and structure it such that, under normal circumstances and average song selection conditions, it would last for about one hour. For mainstream music, and a programming format that does not have tons of ads, this means that you can fit about 15 songs in an hour, so you should structure the main iteration in your playlist template that way. What you also do, is use the special "target" enhancement that can be used within the length global option. For 99% of users who will be using target times of an hour, you would have:

~length iterations=1, target=60

This tells the Playlist Generator to generate one iteration as normal, except that it is now running in a special mode whereby it will guarantee (well almost!) that the generated iteration will last for exactly 60 minutes (one hour), within about one second of tolerance. It takes OtsAV's mixing into account, so basically, when you play these playlist segments, you can be sure that they will last for one hour, if that's what you have asked for. The magical thing about this, is that it means you can time exactly into the news at the top of the hour, or a new playlist segment, without having to fade out the currently playing song only half-way through, which is a very unprofessional sounding thing to do within the professional radio arena. Other radio stations usually do this manually, by choosing a song that will fit as their last song for the hour. OtsAV's Scheduling & Logging does this for you automatically, and it does it while still respecting all of the rules/restrictions (OMQL item queries) you have placed within your playlist template!

There are some things to be aware of however, and some additional options which may be used.

As stated above, an iteration referencing 15 songs, will normally be able to be targeted to one hour without too much difficulty (provided you have sufficient music in your Media Library). However, if a long song is selected that lasts for 8 or 10 minutes (for example), then the playlist generator may not be able to fit all of the other 14 songs in. Since statistically, you want all songs that fulfil your rules to be eligible for play, even if they are long, then this issue needs to be addressed. Basically, the Playlist Generator needs some scope. You give the generator scope by declaring some items as optional. Read the full Ots Playlist Template specification for full details of using the "~optional group x" option, but basically, it allows the generator to omit some items if it needs to do this to achieve the target. For a one-hour iteration, having 18 songs in total, with 6 of them declared as optional, should give the playlist generator all of the scope it would ever need.

Although the iteration will last for exactly one hour, within one second of tolerance, one second is still one second. Over a period of hours, the scheduling will drift. That's why we strongly recommend that you begin each playlist template iteration with a TimeSync directive that matches to the top of the hour (or 10-seconds-to-the-hour, or whatever point you want to call your post). What this means is that when the TimeSync directive is about to fire the next item, the currently-playing-item is about to end anyway, naturally, because of the excellent job the Playlist Generator did with the targeted iteration. However, if it's one second out, which it is allowed to be, the TimeSync directive performs the job of "cleaning up", and ensuring that we are still right on schedule, and never drift from our point of reference (usually the top of the hour).

Another very important thing to be aware of is that for the target mode to work, you obviously have to have sufficient music in your Media Library. If you only have 250 songs, then forget it! You really need about 2000 songs minimum to get reliable and good results. This should pose no problem for any serious radio station. Also, you must be careful not to place too many restrictions on the playlist generator with your OMQL item queries. You might have 10,000 songs in your library, but if every item query restricts the song selection down to only a couple hundred, then you'll run into problems. Note that it is okay and expected that many of your item queries will restrict the song selection to a small number of songs -- that's fine -- but you MUST have at least a couple of song positions where you are not restricting the song selection too much for that position. Otherwise, there is nothing the playlist generator can do -- you have been far too hard and restrictive with your rules. The generator does try very hard to achieve the target, even if you specify nonsense things, but if it can't achieve the goal no matter what, then it will spit out a playlist segment that is not exactly the duration of your target. This is a sign that you need to re-think your template!

What if your radio format is based upon live announcer breaks? How are these handled by the scheduler and playlist generator? No problem! Basically, you still use the Stop & ReCue directive just like you would whenever you want to insert a live announcer break. However, you have to "tell" the playlist generator about the expected duration of time that the announcer plans to speak for. You do this by using the ~seconds option. Example:

@StopReCue

~seconds 30

Having this appear within the iteration of your playlist template will tell the target mode to factor in another 30 seconds that isn't actually there among the specified items. You don't have to place the ~seconds 30 right after or before the Stop & ReCue directive, but it makes sense to do so, since they relate to one another.

Conclusion

By harnessing the OtsAV Media Library, OMQL, Playlist Templates, and Scheduling & Logging, you have a powerful set of tools that allow for anything from the creation of some well-balanced playlists, to full-scale 24/7 intelligent automation!

Scheduling Event Table example:

The following event table is used for a very basic 24/7 setup whereby you simply want each hour of programming generated approximately two hours before it is due to go to air. The Media Library is saved once each hour in case of a power failure or system crash. This occurs at 1 minute past the hour. At 3 minutes past the hour, another hour of programming is generated and appended to the end of the playlist. Once running, this setup will run forever without getting out of sync. When you first start it however, you will have to generate the first two hours of programming manually, if you really do want to maintain two hours of programming in the playlist at all times. Note that even this can be automated to an extent by specifying an OTM file on the command-line of the icon you use to fire up your station!

*:01 SaveOML

*:03 Template End 1 MyHourlyTemplate.otm

Playlist Template example:

The following template is a real-life example that has been used in a commercial environment. Of course the category names will probably be different to your own, but the principles remain the same. This example makes use of the "target" keyword and "optional group" options.

# Generate a playlist segment of exactly 1 hour :-
~length iterations=1, target=60

# Main iteration :-

# sync to top of hour
@TimeSync=*:59:57

# hourly beep
M:\OtsFiles\Main\Spots\HourBeep.ots|1

# news!
@LiveInput=on
@Pause=300
@LiveInput=off

# general spot
~iq avail & spot_gen & lastplay > 30 minutes

# 2 general songs
~iq=2 avail & !spot & rating > 0 & (1970s|1980s|1990s|classic|double) & itemsep artist > 40 & itemsep title > 40