Instructions on how to use the Activaire Q-SYS plugin
1. After choosing "Save to Core & Run" from the File menu, the UI of the plugin will render a splash screen during plugin initialization, after which the Setup page will be displayed
2. During initialization, among other actions, the plugin checks if there is a folder called "Activaire" on the Core's storage, within the "Audio" root folder, and if there isn't, it creates it
3. After this, it checks for the following 3 folders inside the "Activaire" folder, and if there aren't, it creates them
4. The Status control initially reads "Fault - Unavailable Auth Token" because the plugin doesn't hold any authentication token when it's first loaded on a Core, so the auto login cannot be performed. But later, after the user has manually logged in at least once, thus the plugin obtained a valid authentication token from the remote backend, the plugin stores the token securely inside a private embedded component, enabling it to auto login at plugin start.
5. After the user obtains a Pin Code from Activaire and it types it on the plugin's keypad, the Connect button gets enabled and upon clicking it, the plugin logs in the user, taking it to the Zones page
6. During logging in, there is a series of statuses the plugin goes through, but because they are rapidly in succession, the user doesn't always get to see them. However, if "Event Log" plugin property is set to "Normal", Plugin Status events similar to the following should be encountered in Event Log within Q-SYS Core Manager
The Core is identified first, then the actual login takes place, then the music menu is obtained and parsed, and finally, the UI is initialized, so the plugin can be used by the user.
7. The Zones page contains a scrollable list of all zones the user has access to, limited by the configured number of Audio Players via the "Audio Players" plugin's property. Thus, if the user's Activaire account is set to have 10 zones, but the plugin's "Audio Players" property is set to 6, the plugin will only show 6 zones and will set the Status control to Compromised
8. In the reciprocal case, when the plugin has more Audio Player components than the user's Activaire account has zones, the plugin simply uses the number of Audio Player components that it needs, leaving the rest unused.
9. The plugin instantly detects runtime changes in zones number, refreshing the user's content and informing it through the same Status control, but also through corresponding messages in Event Log
10. When the user explores a certain zone, it sees the root entries from the Music Library, namely Scenes, Genres, Intensities and Vibes
11. Also, in the top right corner, it sees the current zone's index and name. Then, in the middle and a little bit lower but still on top, the card displays the currently playing song, if any. Upon exploring let's say the Scenes entry, the user sees the main categories of it, and if going deeper, selecting Beauty category let's say, it discovers the secondary categories of it
12. The 3 menu buttons, Home, Back, and Search can be used to navigate all the way back, to the Music Library's root entries, to navigate one step back, to the previous level, and to access the search functionality of the plugin.
13. Also, the scroll control on the right and the LOAD MORE button on the bottom can both be used by the user to see all available items on the current Music Library level. Both controls automatically hide when there are fewer items than there are available places. In addition, the LOAD MORE button also hides when the scroll's thumb reaches the lowest position.
14. When exploring a main category of Genres, Intensities or Vibes, or a secondary category of Scenes, the user gets to see the Activaire playlists and scenes within that category.
15. In the background, the plugin downloads the artworks of the playlists & scenes to the folder "Playables Artworks"
16. In a similar fashion, after clicking the Search menu button, typing a search query and hitting the enter button, the user sees a list of playlists and scenes that have their artworks automatically downloaded in the background by the plugin, if not already present
17. When the user taps on any playlist or scene, the plugin instantly communicates with the Music Manager, demanding 2 songs from the selected playable, downloading them to the "Tracks" folder, and also downloading their artworks to the "TracksArtworks" folder
18. After getting the first song's .m4a and .jpeg files written to the Core's storage, the plugin starts the playback and takes the user to the Now Playing page, changing the top card to display details about the currently playing playlist / scene
19. From the Now Playing page, the most bottom control takes the user to the Feedback page, which enables the user to react to the currently playing track. If the chosen reaction is one from the top half, the track continues to play and the reaction button that was pressed gets highlighted, but if the user reacts negatively, choosing one reaction from the bottom half, the track is skipped immediately
20. Once a track is over or it gets skipped, the plugin cleans both its files, that is the .m4a song file and the .jpeg song's artwork file, so that at any given point in time, each active zone has at most 2 song files and 2 song artwork files on the Core's storage.
21. The plugin continuously communicates with the Music Manager to grab the next songs, or to inform it on playback actions like skip, pause or play. On the other hand, the Music Manager informs the plugin of how many skips per hour are left.
22. Another continuous communication of the plugin is that with the remote backend, which gets notified by the plugin of volume changes and of song reactions. From the backend's direction, remote actions are communicated to the plugin, as performed by Curator from the web, in order to be reflected on the plugin side as well.