Working with the Scheduler

You have a question or need an advice about how to do something? Ask it here!
Post Reply
User avatar
radio42
Site Admin
Posts: 8295
Joined: 05 Apr 2012 16:26
Location: Hamburg, Germany
Contact:
Working with the Scheduler

Post by radio42 »

ProppFrexx uses scheduling a bit different than other systems, as it has a complete 'Outlook like' Scheduler build in.
In this scheduler you can define so called 'Programs'.
A 'Program' is an scheduler entry, which defines when (at what time and recurrence) a certain 'Script' should be executed.

When a 'Program' executes (because the scheduler is running and the defined time is reached, and such you are in automation mode), then the 'Program' always automatically opens a new playlist window and closes any other open (older) playlist windows automatically.
The scheduler then executes the 'Script' associated with the 'Program' in this newly opened playlist window.
This ensures much more precise scheduling to the second and also decouples the playlists - so that only have to care of one program within one playlist window.

So the 'Script' (which is defined in the 'Program') now executes in this new playlist window and automatically schedules new tracks to this playlist window.
The playlist is then run in 'AutoPlay' mode and such the scheduled tracks from the 'Script' will be automatically mixed and played one after the other one.

So the best is (if have a hourly program schedule) to define 24 or even more different 'Programs' and such 24 or more different 'Scripts'.

All can be defined on the fly in the Scheduler control, which is invoked from the ribbon page called "Scheduler Control" - just click on the "Scheduler" button to open it. In the scheduler control right-click in an empty area to invoke the context menu and e.g. select "New Program" resp. "New recurring Program".
This will bring up the 'Program Editor' dialog in which you can define the start and end time, the type and the 'Script' related to this new program.
A program "soft start" means, that the program might be delayed by some time (see below).
A program "fix start" means, that the program will always start accurate on time.

In the 'Script Editor' dialog you can then define your scripting. Meaning how new tracks should be added to a playlist automatically when the script executes.
Here you can e.g. add random tracks from any of your media library or even load the entries from any playlist file to the new playlist window, execute any control command etc.
How is the script executed?
When a script executes the script lines are executed one by one - if the last line is reached it starts at the defined loop line again. Each execution of a script line might result in new tracks added to the playlist window.
In the global settings dialog under 'Scripts/Scheduler' you can define various options.
- Max. Program Delay: used when soft start was selected for a program
- Playlist Look Ahead: a script line is executed until the playlist has this number of remaining tracks
E.g. if your first script line loads an entire playlist file, there might be already for example 20 tracks being added and such the scheduler will only execute the next script line, if these tracks have been played out.
User avatar
radio42
Site Admin
Posts: 8295
Joined: 05 Apr 2012 16:26
Location: Hamburg, Germany
Contact:
Working with the Scheduler

Post by radio42 »

Image
The above image shows the script configuration dialog:

Script Mode: Defines in which order the script lines are executed.
Sequential: The lines are executed one after the other. Once the end is reached it is started at the beginning again.
Random: The lines are executed in random order.

Reload: Defines which media libraries should be reloaded whenever the script is started.

Loop Script Line: Defines the script line which should be used to loop the script.
In sequential mode a script is looped once the script end has been reached. This value defines the line number which should be used to reset the script pointer - allowing you to skip certain entries at the beginning of the script (exclude them during looping).
In random mode this parameter is ignored.

Script History Count: Defines the size of the song history per script library.
A value of 0 disables the song history.
Note: This number also defines the maximum number of archive entries. The song history will not be cleared with each new script execution!
Left-Click: Opens the Song History Editor.

Clear History At Reload: If checked, the script library will clear it's SongHistory with every load or reload - else the SongHistory will never be cleared and always keep the last used tracks in the history.

Initial Track: If set, this entry will always be used as the very first track whenever the script is started.
Note: Automatic Cue Point Detection (ACPD) is always disabled with this entry.

Archive: Defines an optional archive playlist file in which track entries will be saved which are being used during the script execution.
Note: You might use the same file as an additional song history in order to make sure, that subsequent script executions doesn't contain the same tracks.

Additional Song History: Defines an optional song history playlist file which will be (re)loaded with each script execution.
Note: You might use the same file as the archive file in order to make sure, that subsequent script executions doesn't contain the same tracks.

Advert Inserts: Defines if and how advertising entries should be added during the script execution.
If a media library is specified, tracks are taken from it in the frequency range given.
E.g. if you specify 4-7, this means, that after each 4 to 7 script tracks an additional entry is taken from the advertising lib and inserted during script execution.

Jingle Inserts: Defines if and how jingle entries should be added during the script execution.
If a cardwall library is specified, tracks are taken from it in the frequency range given.
E.g. if you specify 4-7, this means, that after each 4 to 7 script tracks an additional entry is taken from the jingle lib and inserted during script execution.


Script Lines:
Each “Script-Line” has the following parameters:
(note, that each column contains an edit or button)

Mode: Defines what this line should actually do (the content of the Entry-Parameter depends on this one).
Sequential: Adds new track(s) from the given media lib to the playlist by sequentially picking the next tracks from the lib.
Random: Adds new track(s) from the given media lib to the playlist by randomly picking the next tracks from the lib.
LoadTrack: Adds the given audio track directly to the playlist.
LoadPlaylist: Adds the content of the given playlist file to the playlist.
Execute: Executes another script dynamically.
Command: Executes the given Control-Command and then goes to the next script-line.
Cardwall: Adds new track(s) from the given cardwall lib to the playlist by randomly picking the next tracks from the lib.
Advert: Adds an advert container to the playlist by selecting tracks from the defined Advert Slot.
Container: Adds a dynamic script, advert or overlay container which will be evaluated/resolved at playtime.
LoadFolder: Loads up to 'Count' tracks contained within a specified folder in a certain sort order.
Placeholder: Adds a placeholder entry
(Click on the 'T' button to specify an optional trackname for this entry, typically be used with embedded containers).


Entry: The value depends on the Mode selected...
Sequential: Specify a media library to pick tracks from.
Random: Specify a media library to pick tracks from.
LoadTrack: Specify a physical path to an audio file which should be taken.
LoadPlaylist: Specify a physical path to a playlist file whose content should be added.
Execute: Specify a name of any other script to execute.
Command: Specify a Control-Command.
Cardwall: Specify a media library to pick tracks from.
Advert: Specify an Advert Slot to use (all assigned adverts are used).
Container: Adds a dynamic script, advert slot or overlay container which will be evaluated/resolved.
LoadFolder: Specify a directory (all files within this folder will be used, up to the given 'Count' number).
Placeholder: Specify a placeholder name and duration.
(Click on the '...' button to open a dialog to select/specify the appropriate entry).

Count: Defines the number of entries to schedule (only used for mode Sequential, Random, Cardwall and LoadFolder - ignored with other modes).

Options: Here you can specify various script-line options and specific track related control-commands to be executed with the tracks scheduled.
(Click on the 'arrow icon' to specify Track Control-Commands incl. a soundbed file to assign to this script line).

Filter: Allows you to define additional selection/filter criterias when querying entries from a media library (only used for mode Sequential, Random and Cardwall - ignored with other modes).

Note: The script and global song history is never checked for the modes LoadTrack, LoadPlaylist, Placeholder, Container and Execute; or if the 'SupressHistoryCheck' option is set.
User avatar
radio42
Site Admin
Posts: 8295
Joined: 05 Apr 2012 16:26
Location: Hamburg, Germany
Contact:
Working with the Scheduler

Post by radio42 »

Image
The above image shows the program editor.
A 'Program' is actually an entry within the outlook-like scheduler and defines when and how a script should be started.
You can invoke the 'Program Scheduler' from the 'Scheduler Control' ribbon tab by clicking on the 'Program Scheduler' button.

A program scheduler entry (when started) does the following:
- it opens a new playlist window
- assigns the given 'Script' to that playlist window
- and starts to AutoPlay this playlist at the defined start time
- stops/closes any previous running playlist

As such the playlist will execute the given script as long as the program runs (which is typically until a new program is started by the scheduler). The playlist's script will (during that time) query new entries to the playlist by executing the script whenever needed.
If all script lines have been executed, the script will loop, meaning start from the beginning (resp. the defined LoopLine).

Program: Gives any program entry a unique name.
Type: Just for info (each program might get a different color in the scheduler).

Description: Allows you to further describe the program entry (just for information).

Script: Identifies the script to execute when the program is started (select an existing, click on ‘New’ to define a new one or click on the ‘Edit’ button to modify an existing/selected one).

Reload Script before Start: If checked the Script content is reloaded before the program will actually start.

Start Type: Defines, if the program should start exactly at the given Start Time (fixed) or if it might be delayed (soft).
Fixed: When a 'Fixed' start is specified the program will start at exactly this time and any currently playing track will be stopped immediately.
Soft: In case of 'Soft' start, the remaining playtime of a currently playing track will be evaluated. If the remaining playtime is less than the given Maximum Delay the track will play til the end until this program is started. If the remaining time is bigger than the Maximum Delay the track is stopped immediately and the program starts on time.
Manual: The program will be shown right on time but needs to be started manually (also note, that you need to stop and close the current program manually in this case)!
Auto: Will use either 'Soft' or 'Manual' depending on the current 'AutoPlay' setting. In case of AutoPlay the 'Soft' start type will be used. In case AutoPlay is turned off, the 'Manual' start type will be used.
Fixed/Soft TimeUpdateSync: Instead of starting the program in a new playlist window any existing scheduler playlist window will be reused and a TimeUpdateSync entry is used to change the running script.

Start Time: The date and time when the program should start.

End Time: The date and time when the program should end.
Note: This setting is just for information, as any program/script runs as long as a new program/script is started or as defined in the Overlay!

Duration: A duration is automatically determined by the Start and End Time. However, you might alternatively specify a duration here, so that the End Time will be calculated accordingly.

Mixing Time: Is the mix time in milliseconds between two programs (which is the mixing time of the last track of the previous script and the first track of this script).
When a new script is started the first track of that script is played this milliseconds before the last track of the current script is cued out.

Max. Delay: When a program is defined as soft start (so it doesn't have to start at exactly that time) it might be delayed by this maximum number of seconds.
When a new script is about to be started the remaining time of the current Track of the current script is checked. If the remaining time is less than this maximum delay time, the Track will be played til the end before the new script is started (which will then result in a delayed script start).
But if the remaining time is greater than this maximum delay time the current Track is faded-out immediately and the script start will not be delayed.
Note: Programs defined as fixed start will always start on time.

Overlay: If a program is defined as an Overlay it will not stop any previous program/script, but just suspend it. Any previous script will be resumed depending on the overlay type (either after one script cycle or at the defined end time of this program).
No Overlay: This script runs until a new program is started.
Overlay One Cycle: This script executes exactly one cycle (the script lines are not looped).
Overlay End Time: This script executes until the defines End Time is reached.

Allow Overlay Delay: If checked this Overlay Program can be delayed by the user before it has actually started.

Allow Overlay Cancel: If checked this Overlay Program can be cancelled by the user before it has actually started.

Recurrence: Click here to (re)define or delete the recurrence settings.
A recurring program will be repeated in defined intervals. If a program is not recurring it will only be executed once.

Control Commands: Click here to define program specific control commands which will be executed whenever a program is started, suspended, resumed or stopped.


The Overlays are somewhat special, as it allows you to define special program entries, which are running in parallel to an existing program, but suspend the currently running one.
E.g. if you want to define a news or advertising block, which should start at 14:15:00 a'clock, you might define a second program in parallel to an existing one (which for example starts at 14:00:00 and ends at 15:00:00).
This second (parallel) program might now be defined as an "Overlay".
As such the currently running program (script) will be suspended for the time of the overlay program.
Once the overlay program finishes, the suspended program will be continued.
User avatar
radio42
Site Admin
Posts: 8295
Joined: 05 Apr 2012 16:26
Location: Hamburg, Germany
Contact:
Working with the Scheduler

Post by radio42 »

Using FILTERs within a Script-Line:

The 'Filter' of a script-line is actually a text in which you can describe your selection criteria's.
The same expressions are used as already used in the "Find-Window".

Click on the '?' button to invoke the 'Advanced Find Expression Builder'.

Here is a description with some examples (using the simple mode):

The filter expression consists of a <prefix> and <criteria> (separated by a colon ‘:’).
The <prefix> tells the parser what to search for and the <criteria> contains the actual value to look after.

The following <prefix> are supported:
'title' or 't': title contains key
'artist' or 'a': artist contains key
'album' or 'l': album contains key
'mood' or 'm': mood contains key
'grouping' or 'g': grouping contains key
'isrc' or 'i': isrc contains key
'rating' or 'r': rating contains key
'bpm' or 'b': bpm greater than key
'year' or 'y': year contains key
'genre' or 'e': genre contains key

Combinations:
Use '&' or '+' to combine multiple keys
Exclusions:
Use '!' in front of the <prefix> to negate the key.

Note:
The prefixes ‘bpm’ or ‘b’ as well as ‘rating’ or ‘r’ are somewhat special, as they perform a numeric evaluation of the <criteria> key.
Which means the standard match performs a numeric ‘GreaterOrEqual’ comparison – whereas the exclusion performs a numeric ‘Less’ comparison.
All other prefixes perform a case-insensitive string based ‘Contains’ comparison.

Here are some examples:

't:hello & a:james'
Will match, if the TITLE contains “hello” and the ARTIST contains “james”!

'b:120 + !b:131'
Will match, if the BPM is between 120 and 130!

'r:1 + !r:101'
Will match, if the RATING is between 1 and 100!

'r:80 + !r:81'
Will match, if the RATING is exactly 80!

'r:40'
Will match, if the RATING is greater or equal to 40!

'!r:1'
Will match, if the RATING is less than 1 (meaning only 0 is matched)!

'!r:100'
Will match, if the RATING is less than 100!

'r:40 + !r:61'
Will match, if the RATING is between 40 and 60!

'r:40 + !r:61 & a:toto'
Will match, if the RATING is between 40 and 60 and the ARTIST contains “toto”!


Some more notes:
a) As the new script filter rules might not guarantee, that any track at all in your selected media lib matches the criteria’s, I had to implement some maximum within the try-matching algorithm. This means there is an upper limit of 2 times the number of tracks contained in your media lib or a maximum of 300 tries. If the script cannot determine a track which matches the filter criteria, it will take a next track anyhow. This is needed in order to prevent the script from not being able to deliver new tracks to a playlist.
b) As you might be using folder based media libraries the TAG data is not read from the related audio tracks at startup (unless you have specified the ‘Force TAG reading’ option in the settings).
As such the script evaluates this and might need to read the TAG data on-the-fly if needed.
The result might be, that this on-the-fly TAG reading will cost some time and performance – especially when a lot of tracks needs to be tested.
So an advice would be to use the ProppFrexx-Playlist-Format (.pfp) to store your media entries in (and use the .pfp files as your media libraries) – as the .pfp playlist format directly keeps all TAG data within its format and such no extra TAG reading is needed.
c) This is also the difference between the Find-Window and the Script-Filter option. The Find-Window will not perform any on-the-fly TAG reading! This because, when you are search you entire media libraries with thousands of tracks, any on-the-fly TAG reading would simply kill your system IO performance, if all tracks needs to be accessed for TAG reading.
So using the search criteria’s in the Find-Window will also work best, when using .pfp based media libraries.
d) But of course folder based media libraries works quite well, as:
- in the Find-Window you typically search for a title or artist – if the folder based media entries haven’t read any TAG data yet, the Find-Window also evaluates the filename in its search.
- for the Script Filter on-the-fly TAG reading is performed to guarantee exact results (you might simply discover a little higher IO/CPU hit)

Post Reply