Manifest Guide

Introduction

This guide describes the CUBE manifest structure. The manifest is used to configure the CUBE’s music and message playlists as well as device and network settings and scheduling information.

Basic VS Advanced VS Licensed Music

The CUBE offers individual apps such as Basic, Advanced, and Licensed Music. (The version running on a particular CUBE is shown in the web interface as Basic, Adv, LM etc).

The particular app running on the CUBE, affects the types of manifest operations that are permitted. The following configuration information will apply to all apps unless explicitly stated.

Provisioning a Manifest onto a CUBE

Manifests can be provisioned onto CUBEs by uploading them into the CUBE MC Web Application. A manifest can also be installed onto a CUBE via a USB stick.

To install a manifest via USB, the manifest file should be placed into the root folder of a USB stick and named Manifest*.xls or Manifest*.c3, where ‘*’ represents any combination of characters.

Manifest Layout

The actual manifest file itself is an Excel XP style format that can contain multiple tabs aka worksheets.

Arbitrary worksheets can be included in the Excel file – the CUBE will only look for the particular worksheets that it recognizes, and will ignore the rest.

The following are the worksheet names the CUBE will look for and recognize. These names are case sensitive, and each sheet name determines the kind of operation that that sheet provides. Sheets come in a couple of varieties: playlist sheets (ch1, ch2, music, message) and settings sheets (Device Settings, Network Settings):

• ch1-music – contains the music playlist for channel 1.
• ch1-msg – contains the message playlist for channel 1.
• ch2-music – contains the music playlist for channel 2. (LICENSED MUSIC)
• ch2-msg – contains the message playlist for channel 2. (LICENSED MUSIC)
• Device Settings – contains the device configuration settings related to audio playback.
• Network Settings – contains the unit’s network configuration.
• ch1-music-* – contains a scheduled music playlist for channel 1. (LICENSED MUSIC)
• ch2-music-* – contains a scheduled music playlist for channel 2. (LICENSED MUSIC)

NOTE: ‘*’ is used to represent any combination of characters

Playlist Sheets

Each of the playlist sheets contains a listing of the audio to be played back. The types of playlist sheets are chX-music and chX-msg type of sheets. The playlist simply consists of a list of audio in column A of the playlist sheet. Audio can be specified to be retrieved via the web if the file specified is a valid URL, otherwise the audio is attempted to be synced from the inserted USB stick.

The mechanics of playback differ between the Basic App and the Licensed Music App.

Basic App:

• Music is played continuously and messages are overlayed with the music.
• The device settings govern how the fading is done and the various audio levels.
• Scheduling of playlists and messages is not supported.
• Only one channel of playback is supported.

Licensed Music App:

• Music playlists are played continuously and messages are played between the gaps in songs.
• The device settings govern how often messages are queued and audio levels.
• Scheduling of playlists and messages is supported as described below.
• Up to two independent channels of playback is supported.
• Music playlists are shuffled by default.

Content Sync

Each time that a new manifest is loaded on the CUBE using either the USB or web based syncing methods, the following syncing process is conducted by the CUBE:

1. All of the items in column A in each of the channel music and message tabs are queued for syncing.
2. The CUBE checks if it already has any of the queued items. If it does, the CUBE skips each item it already has on board. Conversely, if it determines it no longer needs an audio piece already stored on the CUBE, that piece of audio will be removed.
3. For each of the remaining content items, the CUBE will attempt to retrieve the item for storage on board the CUBE. If the item is a valid http:// URL, the CUBE will attempt to fetch the item from the URL specified. In the case that it is not a URL, and that the manifest was applied via USB, the CUBE will attempt to retrieve the file from the USB drive. Any files that contain unplayable audio are not synced.
4. Any errors in the audio syncing process are reported to the web management interface (Please refer to the Web Management Interface Guide for more information)
5. If the manifest was applied via USB, the unit will beep 3 times to let the user know that syncing has completed.

Scheduling Information (LICENSED MUSIC ONLY)

Scheduling information is used to tell a CUBE to switch between music playlists at a certain date or time or to play a specific message at a specific date and time.

Scheduling Information Structure

The scheduling information for various actions is specified in a format known as cron style. This a columnar format using 5 columns, as follows:

*    *    *    *    *
-    -    -    -    -
|    |    |    |    |
|    |    |    |    |
|    |    |    |    +----- day of week (0 - 6) (Monday=0)
|    |    |    +---------- month (1 - 12)
|    |    +--------------- day of month (1 - 31)
|    +-------------------- hour (0 - 23)
+------------------------- minute (0 – 59)

Each of the columns can be a specific value, a range, a recurrence or a match-all. It is possible to combine these to make many arbitrary and specific scheduling rules.

Note

Think of this as a kind of time pattern. It’s rather similar to a filename pattern; for instance if one asks a computer for all files named MyFile-*.txt, it will pattern-match and find all files with names such as MyFile-Breakfast.txt, MyFile-Lunch.txt and so forth.

Time patterns work as follows: every minute the CUBE will check every time pattern against the current wall-time of the CUBE. If all 5 columns of a pattern matches the current time, the CUBE executes the particular trigger action.

For example:

Minute	Hour	Day of Month	Month	Day of Week
5	9	1	4	*	This time pattern will trigger at 9:05AM every April 1st, no matter what day of the week it falls on
0	12	1,15	*	*	This time pattern will trigger at 12 noon on the 1st and 15th of every month
0	8	*	*	0-4	This time pattern will trigger at 8AM on every weekday (but not weekends)
0	14	*/2	*	*	This time pattern triggers every other day at 2 PM
15,30	10-16/3	1-15,20	4,5	mon,thu,fri	This time pattern triggers at 10:15am, 10:30am, 1:15pm, 1:30pm, 4:15pm and 4:30pm on Mondays, Thursdays and Fridays, but only during 1-15 April, 20 April, 1-15 May and 20 May

Note

The specified date/time is in the CUBE’s local time. The local time is specified using the web management interface. Please refer to the Web Management Interface Guide for information on setting the CUBE’s local time.

The layout of scheduling information in the Manifest is always consistent, irrespective of whether music or messages are being scheduled. Column B contains a scheduling priority directive (either schedule or critical, see below), and then columns C to G are the 5 columns providing the time pattern.

Tip

In the above examples the “*” means “any value of”. As a shortcut in the CUBE Manifest, leaving any scheduling column blank, is the same as placing “*” in that column.

Schedule vs Critical Scheduling (LICENSED MUSIC ONLY)

A scheduled message or playlist is indicated by placing either schedule or critical in column B of the sheet, and then the scheduling time pattern following in columns C to G.

To schedule a music playlist switch, include this information at the top of the music playlist sheet with column A left blank.

It is possible to have several time patterns that should all trigger a switch to a music playlist. Simply place them all at the top of the sheet, each on a separate line.

To schedule a message, include this information in the same row as the message item (which will be in column A).

Again, it is possible to have several time patterns all triggering a particular message; simply place each on a subsequent line in the manifest.

Note

• Scheduled messages will not be included in the regular message playlist rotation.
• In Licensed Music operation, messages are played in the gaps between songs.

There are two types of scheduling priorities supported. They are the default schedule priority and critical priority. Each scheduled item must have an assigned priority.

Schedule scheduling priority

The CUBE will schedule the action to occur after the current piece of music is finished playing. In the case of playlists, the new music playlist will only commence after the currently playing music track is finished. In the case of a scheduled message, the message is appended to the back of the outgoing messages and the entire message queue is played out after the currently playing music track is finished.

Critical scheduling priority

The CUBE will immediately fade out the currently playing music, to perform the action straight away. In the case of music playlists, the new playlist commences immediately. In the case of messages, the message is pushed to the front of the queue of outgoing messages and the entire message queue is played out immediately.

Shuffling (LICENSED MUSIC ONLY)

Note

Only the Licensed Music app supports shuffling. Basic and Advanced apps will always play all playlists in the exact order defined in the manifest.

By default the music playlist will shuffle after each playthrough of the entire music sheet (each item is played once). Shuffling is enabled/disabled on a per music playlist basis. This is accomplished by including a row at the top of the sheet with Column A blank, Column B set to shuffle and Column C either on or off.

Comments and Formulas

Regular Excel formulas can be used to speed up the creation of manifest files. This allows one to reduce the amount of repetitive work done when creating manifests. A simple use case includes using formulas to create the path to web based content.

Any item that isn’t recognized by the CUBE as part of the above descriptions, is treated as a comment (i.e., ignored by the CUBE). This allows one to keep detailed notes of the manifest within the manifest itself without breaking functionality.

Downloadable Examples:

• Example 1 - Contains an example of a USB syncable manifest containing a single music playlist on channel 1.
• Example 2 - Contains an example of a USB syncable manifest containing a single music playlist on channel 1 with a single message playlist on channel 1.
• Example 3 - Contains an example of a USB syncable manifest containing music playlists on channel 1 and channel 2.
• Example 4 - Contains an example of a USB syncable manifest containing music and message playlists on channel 1 and 2.
• Example 5 - Contains an example of a USB syncable manifest containing a single music and message playlist on channel 1 with scheduled messages.
• Example 6 - Contains an example of a USB syncable manifest containing multiple channel 1 music playlists whose play order is determined via schedule switches.
• Example 7 - Contains an example of a USB syncable manifest containing a single music playlist on channel 1 that contains an example of remotely retrieving content.
• Example 8 - Contains an example of a USB syncable manifest containing a single music playlist on channel 1 that has shuffle specifically turned off.
• Example 9 - Contains an example of a USB syncable manifest containing a single music playlist on channel 1 that remotely retrieves audio from URL’s that are constructed using Excel formulas.

Device Configuration

The various settings sheets are used to configure the CUBE. These sheets can be included in a spreadsheet that contains playlist information or as a separate Manifest entirely. If the installed manifest contains only configuration settings, the currently running playlist and audio will be left intact. This feature lets one configure the CUBE without worrying about modifying the current audio playback information.

Device Settings

The Device Settings tab is used to configure the CUBE’s playback parameters. This includes global playback parameters like Master Volume and channel specific playback parameters.

The following settings pertain to channel 1:

Key	Path	Allowable Values	Base Default	Description
masterVolume	1	0 to 100	50	Changes the maximum output volume of channel 1. Also controllable by the keyboard.
min_vol	1/music	0 to 100	60	Volume of the music as a percentage of masterVolume when faded down for message overlay (primarily applies to Basic App)
max_vol	1/music	0 to 100	100	Volume of music as a percentage of masterVolume while not faded down
fade_time	1/music	0 on up	2	The time in seconds that it should take to fade up and down to and from min_vol and max_vol (Basic App Only)
wait_time	1/msg	0 on up	5	For the Basic App, this is the time in seconds between messages (not including the time it takes to fade).
max_vol	1/msg	0 to 100	100	Volume of the messages.
min_vol	1/msg	0 to 100	100	Volume of the messages.

To modify the settings for channel 2, simply duplicate the settings for channel 1 then replace every occurrence of 1 in the path with 2.

An example Device Settings Manifest can be seen here: Default device settings file

Network Settings

The Network Settings tab is used to configure the CUBE’s network parameters. This is where the CUBE can be configured to use DHCP or Static address configuration, use alternate DNS servers for domain name lookups and use an external proxy for http traffic.

Key	Path	Allowable Values	Base Default	Description
mode		Either dhcp or static	dhcp	IP configuration parameters
address		A valid IPv4 address		Statically configured IP address
netmask		A valid IPv4 address		Statically configured network netmask
gateway		A valid IPv4 address		Statically configured gateway
dns/1		A valid IPv4 address		Primary DNS server
dns/2		A valid IPv4 address		Secondary DNS server
dns/3		A valid IPv4 address		Tertiary DNS server
proxy	proxy	Either on or off	off	The flag to indicate whether to use proxy or not
address	proxy	A valid IPv4 address		The proxy address
port	proxy	Any port number 0 or greater		The proxy port number
username	proxy			Proxy authentication username
password	proxy			Proxy authentication password

Note

The static parameters address, netmask, gateway, dns/1, dns/2, dns/3 are used only when mode is static. They are ignored when mode is dhcp.

An example Network Settings Manifest can be seen here: Default network settings file

Manifest Errors

If the CUBE is network-connected and is operational, errors in the manifest configuration are reported to the web management interface. Please refer to the Web Management Interface Guide for instructions on viewing the various types of errors.