NuVo Wireless Audio Driver

This driver controls up to 16 NuVo Wireless Audio players via the network.

Note: You should familiarize yourself with the operation of the NuVo system before creating a project with this driver. The NuVo system uses concepts that are unique to media players and the driver variable/command system will be extremely confusing to someone not familiar with the operation of the NuVo system.

Configuration

The only thing required to configure the driver is to let the driver know which player is which of the 16 possible players. The driver will find the players on the network without any need for a particular addressing scheme, even if the players are left to find addresses through DHCP. Any changes in player IP addresses will be discovered by the driver

Selected Player

The driver can control up to 16 players, commands can be sent to a specific player or to whichever player has been selected on that remote. Variables can show the status of a specific player or the status of a player selected on that remote. When a player is ‘selected’ using the commands in the [Selected Player] category it is the selected player for that remote/panel only. When the selected player for a device is changed the change is stored to persistent memory so that player will still be selected after a power failure or other reboot.

Transport and Audio Control/Basic Metadata

Audio Functions

Because the players are designed to be able to serve as a standalone player they include volume control that works with the internal amplifiers as well as (optionally) the line output of the device. The volume is scaled from 0-100 and can either be set directly with the 'Volume Set' command or adjusted relatively with volume up and down commands that allow you to select the interval to change by. If you want a fast change you can create volume up and down buttons that jump by 5 units instead of 1.

The Mute command defaults to a toggle command but parameters for discrete mute and unmute are available as well

These commands can be sent to a specific player or to the selected player on a device

Playback/Transport

Transport commands include Like and Dislike as well as Play, Pause, Stop, Next and Previous. These commands are not all available at once, so the player provides a way to only show the buttons usable at the current time. There is a set of variables named Show Stop, Show Pause etc. That will hide any buttons that aren't useable at the current moment. The Show Like variable for instance will only go high when Pandora is playing so that the button only appears when needed. Some services allow a Pause, but most broadcasts can't be paused and can only be stopped. This will also be reflected in the 'Show' variables.

The RK-3V in the sample file is a great place to see this. The transport buttons are along the bottom with the Stop, Play and Pause buttons stacked one on the other. Each transport button appears only when needed. When the player is playing, the Play button is hidden, but it comes back when the unit is stopped or paused. The Previous button disappears when Pandora is selected because Pandora does not allow skipping backwards. Likewise, the Like and Dislike buttons only appear when a service that supports ratings is being used.

Two additional boolean variables help you display the status of the machine when it's not playing music for some reason. Those variables will be true when the player is buffering music and when nothing has been selected to play (No Media)

Version 1.5 slightly changes the way transport functions work to make it easier to create simpler UI's. The pause command has been changed so that if the Show Pause variable is false, meaning pause is not available for this source, the driver will issue a stop instead. This means that a pause command WILL now stop a broadcast source like SiriusXM, where previously that had to be a different button. The sample files try to do that with visibility of different buttons, but this simplifies it. In addition, a separate command to toggle pause and play has been added.

Metadata

In the NuVo System the main metadata for the item currently being played is called the Info and comes with three main variables: Title, Sub-title and Description. The Title variable generally contains either the Artist or Station name while the actual song title is in the Sub-title. The description will contain the album name if the artist is in the Title. If the Title is a station name, then the Artist and Album names are both put into the Description.

The Now Playing Metadata is a more general description of what the system is playing: If an album is playing it will give the album title and artist as well as the number of tracks in the list and the year released. Radio stations generally just display the station name.

Browsing and Advanced Lists/Context

Browsing

The browse list has its own section in the command list as it is not dependent on any player. On startup the driver sets the browsing level of every remote to the top level. It also uses the names in that top-level list to fill in the names of the Direct Browse Buttons. Because the top menu level shows all the sources or services available in the system the Direct Browse buttons create a permanent top-level menu that can always bring your browse list to the top level of a source or service. Because the top level may vary over time as services are added, and because it is to some extent region dependent, these names are not hard coded into the driver. To create this list of buttons, use the Direct Browse Name Variables matched to buttons with the Direct Browse Commands on them. They generally get filled in at startup and do not change over time,

There are two choices for selecting from the browse menu. One provides a quick and easy way to navigate the menu system and get what you want playing quickly. The other gives you much more control over you stations and lists.

Select from Browse List: This command is the quickest way to browse the contents of the NuVo System. Selecting an item from this list immediately executes it. If it’s a container (folder/album/genre/region etc) it will open it. If it’s a playable selection it will play it (and any other tracks in that folder if it’s an album).

Select Context from Browse List: The advanced features of the NuVo system are built on the concept of ‘Context’. Most of the items in any of the three lists (Browse, Now Playing, and Up Next) have additional information and options associated with them that are not immediately displayed. In the NuVo apps these are noted by a circle with a down pointing arrow. Selecting this arrow in their apps displays a dropdown menu showing these additional options.

If the Select Context command is used instead of the Select command on the browse menu then instead of selecting that item, the context for the item chosen will be displayed with the variables in the [browsing] Selected Item. The context has both the metadata of the selected item and commands that will act on the item.

The commands, which are in the [Browsing Context Menus] category, consist of one Menu Context Action command and up to 6 Context Button commands. The Context Buttons are also available in a 2 way list: Selected Item – Browse Context Menu (List). All the buttons have a variable for a label and all the context buttons have a matching visibility control variable.

The Action command executes on the selected item exactly the way selecting the item with the Select from Browse list command would have. It opens the item if it’s a container and executes or plays it if it’s an action item. There is an accompanying variable (Selected Item – action) that can be used to label the button so the user will know what pressing the button will do. The sample file actually combines the label variable with the Selected Item – Title variable to more descriptively label the button

The number of context commands available depends on the item selected. Each context button has an accompanying visibility variable (Selected Item – Browse Context Button x Text) as well as a label so that when a ‘Select Context from Browse’ command is executed the correct number of correctly labeled buttons can appear. Context commands execute automatically when selected but are completely in the hands of the player, the driver is not aware of what any button is programmed to do. Some context commands require a response or confirmation. For those commands the driver will turn on the Alert visibility flag which you can use to show an alert with up to two buttons as shown in the sample file. The buttons must get the accompanying Alert Button commands which will, besides executing the command, automatically turn off the visibility flag. Commands that don’t necessarily require confirmation but do want to display information to the user use the very similar Dialog variables and command.

Now Playing and Up Next Context work very similarly to the Browse context except that they are attached to specific players so A) the variables are found under the players themselves and B) the commands require a player as one of the parameters. Even if you’re directly assigning the commands to a player you have to have already set the ‘Selected Player’ to match. The driver is matching players to remotes when using these commands so it must know which players are in use on any remote. With this driver it’s always safest to set a selected zone for a remote when selecting sources to make sure the driver knows which set of variables to send to which panel.

Info Context is a set of context commands that are requested by the driver every time the Info metadata changes. This metadata is only available in a list, not as buttons. The driver still needs something to tell it to display the metadata so there is a command in the [Current Info] category that just sets the Show Info Context Menu for the player selected on that remote. Selecting something from the Info Context list will turn the flag off.

Top Ten (version 1.3)

Playback of ‘Top Ten’ Favorites

This section is being put here to put it in front of the Direct Preset section. If the Top Ten had been available from the beginning the Direct Preset section would probably not have been added as the Top Ten provides a method for presets to be created by the end user rather than having the integrator forced to specify them. There are however, fewer of them then there are direct presets.

Beginning with NuVo software version 1.11 the players display "Top Ten" as one of their top level 'sources'. The system tracks these presets itself and includes the command "Save to Top 10" in the context commands when browsing. You can support the playback of these without changes to your system (in fact, without even updating the driver) as they show up in the standard browsing menu, but you can't edit or alter the list without the newer commands. In addition to triggering playback from the browse menu the new driver contains the commands and variables needed to create a page of dedicated buttons, with artwork, that can trigger the Top Ten presets directly. The Sample File devices 'Advanced iPad', 'Direct Browse KX7' and 'NuVo KX2' all use these to directly select the favorite to play (obviously with no art on the KX2). The driver provides a title and subtitle for each top ten favorite as well as a dynamic image. The command to directly select a favorite is in the [Direct Selection] category and is called 'Direct Select Top 10 Item’.

Adding to the ‘Top Ten’ List

To change the list, you must use the ‘Add to Top 10’ button that gets exposed as a context button when a menu item is selected from the browse list. This means that in order to edit the list you have to select from the list with the ‘Select Context from Browse List’ commands rather than the “Select from Browse List” commands. This will fill and expose the Context Buttons, allowing you to see the “Send to Top 10’ Context button. When that context button is selected the “Top 10 Confirmation Visibility” should be used to show the ‘dialog’ that holds the Top 10 List variable. This will show you the current list and, if there are any unused spaces, show you that spot to put the new item there at the end.

Once the buttons are visible (because the visibility variable is high), there are only a couple ways to make it go away: The ‘Cancel out of the Top Ten’ command and the Select Top 10 Location button placed on the Top 10 List variable

This will essentially give you a pop-up to select a favorites ‘slot’, every time you try to write a favorite via the context button. Both the advanced iPad sample and the advanced KX-7 have pop-ups that become visible when it the driver needs to assign a Top Ten to a slot. The pop-up will show all current Top Ten items so they can be replaced as well as allowing you to put the new favorite at the end if there’s more at the list.

Removing from the ‘Top Ten’ List

To remove an item from the Top Ten you need to use the browse list. When selected from the list (with the ‘Select Context from Browse List’ command) the context commands will have one that says ‘Remove from Top 10’. Selecting that command will remove the selected item from the list, moving all the others up one if needed to fill in the spot.

Presets (version 1.1)

Directly playing specific stations

You can create dedicated buttons to directly access Pandora Stations as well as TuneIn and SiriusXM Favorites with the new 'Direct Selection' commands. There are two version of each of these commands. The first is the easiest for interfaces that don't display cover art: just use the Direct Select TuneIn Favorite by Name command (or the Pandora or Sirius versions) and put in a station name for the parameter. The command can be sent to any player or the selected player. When the command is executed the driver looks through the appropriate list of stations and tries to find the parameter in the station title. If it finds a match it jumps to that station. Partial texts are matched up as well.

If your Favorites list contains:

89.3 | The Current (Eclectic)

You can enter that entire text, or you can enter only 89.3, or Current (or just Curr for that matter). The driver will find that the text you supply in the title and play that station. Obviously, you need to enter enough text to be unique. The driver will play the first item it finds.

The second option takes a little more planning but will supply you with an icon for your station. With the Direct Select Pandora Station (or TuneIn or SiriusXM) command you put the text to match in the configuration of the driver on the driver tab of the processor's Properties page. When the driver starts it will browse the TuneIn, Pandora and SiriusXM services and find stations that contain the text in the configuration. Once it finds matches it will fill the Direct Pandora/TuneIn/SiriusXM Dynamic Image variables as well as text variables that contain the full titles for the stations that were found. Other than that the command works identically to the Select with Name commands, when executed it will play the station with a matching title

If the favorite is deleted the button will no longer work. If the preset is resaved it will begin to work again but it could take a couple hours for the driver to add it back into the list.

Line Inputs (version 1.2)

Directly accessing Line lnputs

You can also access a player’s line input directly. In fact any player can play audio from any other's line input. There is a considerable delay when doing this so it can't be used to play TV audio for instance. The Direct Line In Select command allows you to choose which player (or selected) should playback audio from which line input. In the command you choose which player's line input is used but a variable exists allowing you to label the button with the name given to the input in the NuVo app. In the sample file the iPad samples, the KX2 and the T2i all can select from the line inputs in the system.

Groups/Syncing (version 1.2)

What 'Grouping' means to the NuVo

In the NuVo System, groups have no master and are totally dynamic, disappearing when the last player leaves. In the NuVo app, any zone whose icon is in a titled box is in a group, even if that group is only one player. If the icon is at the bottom of the list of groups, below the area that says 'Drag Here To Start' it is not considered to be in a group. When it is not in a group you cannot start it by hitting play because it has nothing to play. Technically you assign music to a group and not a player. The players will automatically 'create' a group for themselves however if told to play an audio file or stream.

What 'Grouping' means to the driver

To fit into the RTI system, the driver interprets the group status of a player this way:

1) A player that is not in a group is 'Not Playing'. Its metadata is cleared and both its Info Subtitle and it's Now Playing Title are set to 'Not Playing' and the Not Playing variable is set to true. The variables that make the transport buttons all go false because you must select from the browse list to make the player play again (or sync the player to a player already in a group).

2) When a player joins a group, it is now said to be playing and gets the metadata for the group and its 'Is Playing' variable is set to true. The group itself is not tracked in the driver as the driver does not interact with groups directly.

3) When a player is in a group with multiple members its 'Grouped' variable is set to true. Any commands sent to a member of the group effects every player in the group.

The Transport category of commands has two commands to support grouping. The group command needs two players as parameters, one that is already in a group and will be joined by the other. Either of these can be the selected player for the view. This allows you to create a set of buttons that will allow you to sync any player to the selected, or a set that will sync the selected player to another one. The second command removes a player from its group, essentially stopping it.

The Advanced iPad device in the sample file has one example of how grouping can be handled, the KX2 sample has another, simpler one. On the iPad there is a new Groups button in the top left that will highlight whenever the iPad is grouped with other players. Pressing this button brings up a dialog that shows a grouping button for all three players that show whether they're grouped to the selected player. Pressing the button for the player triggers a macro that toggle the player in and out of the group of the selected player. If you press the button for the selected player, it will leave its own group and show Not Playing.

The KX2 just permanently shows similar buttons on the final frame of the first page

Revision History
1.0 The initial release of the driver

Version 1.0 of this driver used the new 3rd party API from NuVo. The API is still in active development so there are a few functions that are not yet implemented. Several of these are already planned for in the driver and will just work based on new NuVo upgrades, some may require driver updates:

1) There is no search function

2) Pandora stations cannot be renamed.

3) The Info Context for SiriusXM always says Add to Presets, even if it already is a preset

4) Context commands that say "More from artists..." are not active anywhere. They appear in both the Library and the Rhapsody.

5) The Browse Context command for removing something from the Rhapsody library works but the Info Context version of the command do not.

1.1 Adds direct presets for SiriusXM, TuneIn and Pandora (See below)

1.11 fixed transport button visibility issues caused by software version 1.7, adds ability to hide 'Bluetooth' and 'Line In' from the menu and Direct Browse buttons

1.12 slight adjustments in text for Pro Control release

1.15 Expanded the number of players to 16.

1.2 Adds player syncing, direct access to player line inputs and fixes foreign language issues.

1.21 Adds missing grouping variables.

1.22 Adds missing icons lost with 1.21

1.23 Fixes a problem which can cause the driver to fail on startup

1.24 Fixes the Blend on SiriusXM

1.25 Modified the error message variables to include "Are you still there?" from Pandora, added error flag event.

1.3 Adds support for the Top 10 feature introduced in NuVo software 1.11.

1.31 Removes non-critical errors (Pandora stream error in particular) from the error variable

1.32 Fixes (Once again!) the problem with International characters and adds Direct Presets for iHeart Radio to match those of Pandora, SiriusXM, and TuneIn

1.33 Fixes browsing of local library and USB by folders

1.4 Adds support for Power commands and variables, as well as Input switching on the new P400 and P500 models (soundbars and standalone speakers)

1.41 Fixes the boolean variables for the sources
1.42 Adds a boolean for Spotify
1.43 APEX only fixes: Mispelled Progress tag prevents gauge autoprogramming, and Player numbers don't increment.

1.5 Usability fixes (see Transport section), changed tagging of presets so titles show on templates.