Q-SYS plugin,
documented for installers.

The Scheduling main category secondary categories pertain to the Transport Controls and Playback indicators (Play, Pause, Skip, Volume, IsPlaying, Progress, Remaining) and to the Programming capabilities (Login / Setup, Menu, Search, Program, Schedule Builder).

After choosing "Save to Core & Run" from the File menu, the UI of the plugin will render a splash screen during plugin initialization. After initialization completes, the Setup screen is displayed.

During initialization, the plugin checks if there is a folder called Activaire on the Core's storage, within the Audio root folder. If it does not exist, it is created.

Inside the Activaire folder, the plugin then checks for three particular folders, creating any that are missing:

• PlayablesArtworksCommon to all plugin instances on the Core.
• Tracks_<unique-suffix>Per-instance track storage.
• TracksArtworks_<unique-suffix>Per-instance track artwork storage.

<unique-suffix> is a unique alphanumeric string of 5 characters that is generated by each plugin instance dragged & dropped to a Schematic Page from the Schematic Elements.

This accommodates situations where either a design file contains more than one plugin instance, or there isn't one single design file deployed to a particular Core. Because the tracks and artwork folders are periodically cleaned up by the plugin, unique folders prevent one instance from erroneously cleaning up tracks in use by another. The PlayablesArtworks folder is shared across all plugin instances.

The Status control initially reads Fault - Unavailable Auth Token because the plugin does not hold any authentication token when first loaded onto a Core, so the auto login cannot be performed.

After the user has manually logged in at least once, the plugin obtains a valid authentication token from the remote backend and stores it securely inside a private embedded component, enabling auto login at plugin start.

After the user obtains a Pin Code from Activaire and types it on the plugin's keypad, the Connect button becomes enabled. Clicking it logs in the user and takes them to the Streams screen.

Pin codes are generated at activaire.com/qsys.

During logging in there is a series of statuses the plugin goes through, but because they happen rapidly in succession the user does not always see them. If the Event Log property is set to Normal, Plugin Status events similar to the following are encountered in the Event Log within Q-SYS Core Manager:

1. ACT|I|PS: INITIALIZING - Q-SYS Device IdentifiedCore is identified.
2. ACT|I|PS: INITIALIZING - Logged InLogin completes.
3. ACT|I|PS: INITIALIZING - Territory SupportedPlugin's territory is validated.
4. ACT|I|PS: INITIALIZING - Playlists Menu ObtainedMusic menu is fetched from backend.
5. ACT|I|PS: INITIALIZING - Playlists Menu ParsedMusic menu is parsed.
6. ACT|I|PS: OK - Navigation List InitializedUI is initialized; plugin is ready for use.

The Streams page contains a scrollable list of all Streams the user has access to, limited by the configured number of Audio Players via the Audio Players property.

If the user's Activaire account is set to have 7 Streams, but the plugin's Audio Players property is set to 6, the plugin will only show 6 Streams and will set the Status control to Compromised - 1 New Stream Audio Players Increase Needed.

In the reciprocal case, when the plugin has more Audio Player components than the user's Activaire account has Streams, the plugin simply uses only the number of Audio Player components it needs, leaving the rest unused.

The plugin instantly detects runtime changes in Stream count, refreshing the user's content and informing them through the same Status control as well as via corresponding Event Log messages.

When the user explores a Stream, they see the Music Library root entries: Scenes, Genres, Intensities and Vibes.

In the top-right corner the current Stream's index and name are shown. Slightly lower, the top card displays the currently playing song, if any.

Exploring a root entry such as Scenes reveals its main categories. Drilling further into a category such as Beauty reveals the secondary categories within it.

Three menu buttons, Home, Back and Search, are used to navigate to the Music Library's root, to step one level back, and to access search.

The scroll control on the right and the LOAD MORE button at the bottom can both be used to see all available items on the current Music Library level. Both controls hide automatically when there are fewer items than available places, and the LOAD MORE button also hides when the scroll thumb reaches the lowest position.

When exploring a main category of Genres, Intensities or Vibes, or a secondary category of Scenes, the user sees the Activaire playlists and scenes within that category.

In the background, the plugin downloads the artworks of the playlists and scenes to the PlayablesArtworks folder.

After clicking the Search menu button, typing a query and hitting enter, the user sees a list of playlists and scenes whose artworks are also automatically downloaded in the background, if not already present.

When the user taps on any playlist or scene, the plugin instantly communicates with the Music Manager, demanding songs from the selected playable, downloading them to the tracks folder, and also downloading their artworks to the tracks-artworks folder.

After the first song's .mp3 / .m4a and .jpeg files are written to the Core's storage, the plugin starts playback and takes the user to the Now Playing screen, changing the top card to display details about the currently playing playlist or scene.

From the Now Playing screen, the bottom-most control takes the user to the Feedback screen, which lets them react to the currently playing track.

If the chosen reaction is one from the top half (positive), the track continues to play and the reaction button is highlighted.

If the user reacts negatively (one of the bottom-half reactions), the track is skipped immediately.

After a track is over or skipped, the first run of the plugin's cleanup flow, which runs every 10 minutes, will remove both its corresponding files: the .mp3 / .m4a song file and the .jpeg artwork file.

Every 10 minutes, each active Stream has at most Cached Tracks + 1 song files and song artwork files locally on the Core's storage.

The plugin continuously communicates with the Music Manager to grab the next songs and to inform it of playback actions like Skip, Pause or Play. The Music Manager informs the plugin of how many Skips per hour are left.

Another continuous channel runs between the plugin and the remote backend: the plugin notifies the backend of volume changes and song reactions, while the backend communicates remote actions performed in Curator on the web back to the plugin so they are reflected on the plugin side as well.

The Generic UI page contains cards grouped per functionality, that can be incorporated into a custom UCI. The style and visibility of the controls present on this page do not change at run time, so they are fit for building a custom UCI with a certain theme and structure (including layers and visibility rules).

The controls included on this page cover all the functionalities of the plugin.

The top-left card is the Setup card, which can be used to programmatically introduce the PIN code and then hit the arrow button for the plugin to automatically log in with a certain PIN, via script or manual action.

It also includes a clear button that erases the text box, and a QR code that links to the Q-SYS section on the Activaire site.

The two cards underneath the Setup card are the AllStreams card and the Injectable card. These cards are unique within this page; each one embeds dedicated controls for a specific part or flow of the plugin.

The AllStreams card includes metadata for the Stream that was last explored via the plugin's All N Streams page, transport controls, and a paginated drop-down list of stations for controlling all Streams at once.

The Injectable card includes a specific schedule builder that, when active, can program up to 5 different segments to be played by all the streams at the same time.

The card under the AllStreams and Injectable cards is the Menu card, which holds the flat, alphabetically sorted, paginated list of the programs that form the entire Music Library the user has access to in the All N Streams page.

This list is read-only, selecting any of its items doesn't do anything. However, the items of this list form the default list of choices for all the paginated drop-down lists of stations from the other cards.

The bottom-left card is the Search card, which can be used to incorporate some or all of the search functionality controls into a custom UCI.

It contains a text box where the search query is introduced, an arrow button for launching the search, a clear button for clearing the query, and a flat, alphabetically sorted, paginated list where the search results are published.

When a search is performed, the results replace the choices in all the paginated drop-down lists of stations on the other cards, so the user can use those lists to select the desired station for any particular Stream. When resetting the search (using the clear button), all those lists return to their initial choices.

Starting from the 3rd column onwards, all odd columns are populated with Stream cards which, similarly to the AllStreams card, include metadata, transport controls and paginated drop-down list of stations for the Stream indicated in the card header.

These Stream cards also include two playback indicators, one for the progress of the currently playing track, and one for the remaining time.

Metadata shown:

• The name of the Stream
• The type of the program (playlist / scene), the name and artwork of it, and whether it's explicit
• The state of playback (playing / paused), the title, artist, album and artwork of the track, and explicit flag

Transport controls include the ability to play, pause, skip and change volume. The paginated drop-down list of stations allows for easy selection of the desired program.

Starting from the 4th column onwards, all even columns are populated with Schedule cards which, similarly to the Injectable card, include a schedule builder that, when active, can program up to 5 different segments to be played by the Stream indicated in the leftward card header.

The schedule builder contains a toggle in the top part, which controls whether the schedule is active or not. For edits done to an active schedule, a toggle off and then a toggle on is needed for the plugin to apply the edit. In the top-right corner there is a clear button which resets all 5 segments to their initial state.

Each segment is defined by a starting hour and minute and an ending hour and minute. These values are set from two pairs of drop-down lists. A segment also has an assigned program, selected via the included paginated drop-down list of stations.

After all 5 values are set (start hour, start minute, end hour, end minute, and program), an LED indicator on the right side of the card lights up if that segment is valid, meaning its end time is bigger than its start time (with the exception of when the end time is midnight) and it does not overlap with another segment.

To work properly, the plugin needs access to the internet. In case of an internet outage, the music in a Stream will not stop, it will loop after all the cached tracks for that Stream are consumed.

If internet is restored before the loop happens, that Stream's music will not replay.

If the music replayed due to such an internet outage, when the internet is restored the music will continue its normal sequence, except when a skip is ordered. In that case, instead of performing a simple skip, the plugin will skip to the end of the group of cached tracks that were already played, assuring a fresh new segment.

Disk space scales with two variables, the Cached Tracks count N and the number of active Streams Z, plus a fixed ~20 MB allowance for playable artworks. Use the formulas to project storage for your specific deployment, or read off the table for common combinations.

For escalation, package up your evidence, exported Event Log entries (.csv) and the autosaved console output, and email Activaire support with a clear description of what was happening when the issue occurred.