We are in the process of migrating the Spacial Wiki content to our new Help Center at spacial.com.
Please visit the Help Center for latest Tips and Tricks, Documentation and Troubleshooting.

Category Based Rotations

From SpacialAudio

Jump to: navigation, search


Category Based Rotations

This section will provide a step-by-step guide to initialize a category-based rotation logic script. This section is by no means a complete overview of category based rotation, but will give a good start in exploring the power of SAM's rotation logic.

'Note: Advanced users can achieve the same logic as described here using a PAL script.'

Configure SAM to use category based logic rotation

Lets first activate the SAM4 Category based rotation logic module.

Open up the SAM4 configuration and browse to
SAM4->Config->Playlist rotation rules

Under Playlist logic modules select the Category Playlist rotation logic module and click on the Configure button.

This will bring up the Category rotation logic configuration dialog.

Ignore the values in the Adjust weight on events section for now and look at the Rotation clockwheel format section.

Once you have the Rotation clockwheel format window in front of you and can specify your own clockwheel format.


Creating your own Rotation Clockwheel Format

A review of the buttons - from top to bottom:

+ Category - Select a song from a category rule.
+ Directory - Select a song from a directory rule.
+ Request - Select a pending request to be moved to the queue.
+ Comment - Add a comment or description to the clockwheel that helps you follow the logic or provides more information.
Clear - completely empties the clockwheel.
Load - Load a clockwheel format from a file.
Save - Save the current clockwheel format to a file.

Example clockwheel

{# Add tracks from various categories #}<br>
Cat['Music (All)'].QueueBottom(smLemmingLogic, EnforceRules);<br>
Cat['Tracks'].QueueBottom(smLRPA, EnforceRules);<br>

{# Add a station ID followed by an advertisement #}<br>
Cat['Station IDs (All)'].QueueBottom(smRandom, NoRules);<br>
Cat['Advertisements (All)'].QueueBottom(smLRP, NoRules);<br>

{# Add a requested track to the bottom of the queue #}<br>


Category based rotation - Examples

Example 1: A very simple clockwheel
Click on the Clear button to start a new clockwheel; then click on the Category button.
This will bring up the Select category dialog. From the categories on the left choose the Tracks category.

On the right are various options:

Enforce playlist rotation rules
Specifies whether SAM will use the Playlist rotation logic rules when selecting a track out of this category.
Selection method specifies what logic to use when selecting a track. The Least recently played logic, for example, will select the song that hasn't played for the longest time. For a complete overview, please refer to the documentation Selection method .
For this example, check the Enforce playlist rotation rules checkbox and click the Lemming Rules selection method.
Now click on OK.

The clockwheel format script should now look like this:
Cat.QueueBottom('Tracks',smLemmingLogic, prEnforceRules);

Now click on OK to save the current configuration.
SAM will now select a song out of the Tracks category EACH time SAM needs a song for rotation. SAM will ONLY select songs inside the Tracks category. If a song is not located inside the Tracks category, it will not be played.

Example 2: More advanced clockwheel

In this example, songs will be inserted from two categories, a station ID will run, and then a featured artist from files located inside a certain directory will be added to the queue.

'''Cat.QueueBottom('Tracks',smLemmingLogic, prEnforceRules);'''<br>
'''Cat.QueueBottom('Music (All)',smWeighted, prEnforceRules);'''<br>

# Insert Station ID<br>
'''Cat.QueueBottom('Station IDs (All)',smWeighted, prNoRules);'''<br>
# Insert song from one of our featured artists<br>
'''SubDir.QueueBottom('C:\Music',smLRPA, prEnforceRules, NoScan);'''<br>


The first line is exactly the same as in Example 1.
The second line was created by clicking on the Category button and browsing to the Special>Content->Music->Music (All) category. The Weighted selection method was chosen and the Enforce rules checkbox checked.

For the third line, click on the Category button and browse for the Special->Sweepers->Stations IDs->Stations IDs (All) category. Do NOT check the Enforce rules checkbox since most stations only have a few station IDs that play often. Thus the Do not repeat song within [xx] minutes rule will almost never be able to select a valid station ID for play. Consequently, this command skips the playlist logic rules for station IDs and simply selects the one that has the best balance according to weighted rotation.

Then, on the next line, use a directory category to only select songs located inside a certain directory. To accomplish this, click on the Directory button and browse to the directory containing the music. (In this example, it was c:\music\ ). If the music is nicely sorted in subdirectories, and to have the logic also search the subdirectories for songs, check the Include subdirectories checkbox. Do not check the Rescan directory if there are a lot of files in the folder, as rescanning each time will waste considerable CPU power. Songs will have to either manually be added to the media library each time new files are added to the c:\music directory, or a PAL script will need to be created to automatically check for new files on a daily basis - or else the files will not be in the media library and SAM4 will not select them for rotation.


How SAM works with the clockwheel:

As SAM plays songs it will refer to the playlist rotation logic module each time it requires a song for rotation. The Category based rotation module decides which song to play according to a clockwheel format script.

Cat.QueueBottom('Tracks',smLemmingLogic, prEnforceRules);
Cat.QueueBottom('Music (All)',smWeighted, prEnforceRules); 
Cat.QueueBottom('Station IDs (All)',smWeighted, prNoRules); 
SubDir.QueueBottom('C:\Music',smLRPA, prEnforceRules, NoScan);

The above script does the following:

First, select a song from the Tracks category, using Lemming Rules (which basically means random logic) and make sure the song selected obeys all playlist rotation rules.

Then select a song from all songs inside the media library (excluding Sound FX, stations ID, etc) using weighted rotation selection logic (song with higher weight will get played more often), once again obeying all playlist rotation rules when selecting the song.

The third song selected will be a station ID, selected from the list of ALL songs marked as a station ID. Once again, the weighted selection method is used, but we do not enforce the playlist rotation rules. (See notes below.)

Finally, select a song located inside the c:\music directory or a song located in one of the subdirectories located under c:\music. Use the Least recently played artist selection method logic since this will give us a nice rotation between artists. Playlist rules are enforced, but do not rescan since it might put our CPU under too much load with a large amount of songs under that directory.

When a category selection method can not find a valid song that plays within the playlist rotation rules and Enforce rules is used, the specific selection will return an EMPTY result - meaning NO song will be inserted from that category and one from the NEXT category will be inserted instead.
A common mistake is to enforce rules on Station IDs, Sweepers, etc., causing them to be not valid under the rules and returning an empty result set. This in turn causes your clockwheel format to be "broken" - i.e., not playing songs in the correct "format" Using rescan for small directories (Less than 1000 songs) will read the files inside the directory/subdirectories and also remove invalid files. This is very useful if you simply want to copy featured songs into a directory without needing to manually add them to the media library. Just be warned that for big directories running rescan in your playlist category script is NOT recommended. Rather, use a PAL script to rescan it daily or once every few hours.


Properly using Categories for rotation

Categories will make life easier and can make the music format sound like a professional radio station - if used properly. First, before reading this section, read the Understanding playlist categories section to get a proper background on the subject.

This section only applies if SAM4 is using the Category based rotation logic module or using a PAL script that inserts songs for rotation using categories.

Refer to the following example
Category Based Rotation - Examples

Things to keep in mind while working with category based rotation logic:

Make sure there are enough songs in the category to rotate within the bounds of the playlist rotation rules, or else the category will be skipped. This is a common mistake with categories like Promos, Station IDs, Sweepers, etc. Always use the NoRules parameter for those categories.
When using directories as categories, remember that the songs must already be in the media library before they can be selected for rotation. The Rescan flag will, of course, scan the directory for new files and remove invalid files - but that can take a lot of time and CPU with large directories.
Category names are not case sensitive, but spelling must be exactly the same as the actual category as located in the Playlist.
- A PAL script will warn you inside the output window if it could not find the specified category.
- The Category based rotation module currently will not report any problems with the category name. It will simply skip that category script line. Therefore, it is very important to double-check the name of categories in your scripts.
Parent and Grouped categories are not valid names for category-based rotation!
Parent categories do not contain any songs, only other categories. They cannot be used for category-based rotation. In the future, the support for grouped categories for rotation logic may occur.
If a category is the parent of other categories, but also contains a list of songs - from where will the selection be made? This is the main difference between categories and directories

a) Using the Dir['c:\music\'].QueueBottom(...) command, songs will only be selected from the main root directory. No songs from any subdirectories will be included in the search.

b) Using the SubDir['c:\music\'].QueueBottom(...) command, songs will be selected from the main root directory and songs from any subdirectories will also be included in the search.

c) Using the Cat['MyCategory'].QueueBottom(...) command, songs will only be selected from the 'parent' category. No songs from any child-categories will be included in the search. Thus, it works similar to (a).


Personal tools