Bluesound / BluOS Player

Control a Bluesound or NAD BluOS player — Node, Powernode, Pulse, Vault, the NAD streaming amps and receivers, and any other BluOS-enabled product — over the player's local HTTP control API. One GEM device drives one player: playback transport, volume and mute, presets, station/genre browsing, queue management, physical-input selection, and speaker grouping. The driver also backs an on-screen Bluesound source view that end users get on a touchpanel, with a Stations/Genres browse surface, favorites, and live now-playing.

There is no cloud account and no pairing step — the driver talks straight to the player on the LAN, so once the BluOS app has set the player up, GEM only needs its IP.

How it connects

• The connection is plain HTTP to the player's IP on TCP port 11000 (the BluOS local control port). Responses come back as XML; the driver parses them for you.
• There is no authentication — any device on the LAN that can reach port 11000 can control the player. Keep players on a trusted/management VLAN if that matters on the job.
• Live state (volume, mute, transport, shuffle/repeat) is read with the BluOS long-poll status endpoint: the player holds the request open and replies the moment something changes, with a regular poll (the Status Poll Interval, default 5000 ms) as a backstop. Long gaps between updates when nothing is changing are normal — that is the long poll working, not a fault.

Prerequisites

• A Bluesound or NAD BluOS player on the LAN, already set up and signed in through the BluOS Controller app (this is where you add streaming services and define presets).
• A static IP or DHCP reservation on the player — the device row is pinned to one IP, so a lease change would silently break control.
• Network access to TCP 11000 from the GEM server to the player.

Setup

Open Devices

1. In the BluOS app, give the player a fixed address (static IP or a DHCP reservation) and note it down.
2. Go to System → Devices → Add Device and choose the Bluesound / BluOS Player driver.
3. Set Player IP to the player's LAN address. Leave Port at 11000.
4. (Optional) Set Status Poll Interval (ms) if you want the backstop poll faster or slower than the 5000 ms default — the long poll already delivers changes promptly, so most installs leave this alone.
5. Save. On connect the driver starts status polling and (when configured as a browsable source, below) syncs presets and stations from the player. The player is now controllable from macros, the AI assistant, and any widget bound to its state.

One device per player

This driver does not auto-discover or create a zone per speaker the way some multi-room drivers do — one BluOS player is one GEM device. For a multi-room BluOS system, add one device per player. Grouping several players together is done with the grouping commands below, not by combining them into one device.

Using a player as a room's volume / output

A BluOS player has its own amplifier or line output, so it usually is the audio output for a room rather than a source feeding a matrix. To give that room a volume slider and transport control, bind the player as an AV zone's Volume Device:

1. Open AV Zones and pick (or create) the zone for that room.
2. Set its Volume Device to this Bluesound device. Volume, mute, and transport commands sent to the zone now address the player.

The driver writes live state back onto the device as it changes, so these names are stable to build attribute triggers and bind widgets against:

Attribute	Type	Meaning
volume	int	Current volume, 0–100.
mute_state	string	on / off.
state	string	Transport state reported by the player (play, pause, stop, stream, connecting).
shuffle	bool	Shuffle on/off.
repeat	bool	Repeat on/off.
update_available	bool	Set true when the player reports a pending firmware update (see below).

Volume is absolute; up/down are dB steps

The volume command sets an absolute level 0–100. The volume_up / volume_down commands are relative ±5 dB steps (BluOS works in dB for nudges), not ±1 on the 0–100 scale — so a single step can move the slider by a few points depending on where it sits.

Using Bluesound as an on-screen source

To give a room the full browse / now-playing experience on a touchpanel:

1. Open AV Sources and create a source.
2. Set Device to this Bluesound device.
3. Set Component to one of:
   • bluesound — the generic BluOS browser. It lists what the player itself exposes (presets, enabled music services, and physical inputs) in a two-pane Stations / Genres view.
   • pandora, siriusxm, or amazon_music — a service-specific panel. These render their Bluesound variant automatically because the source's device uses this driver, opening straight into that service's browse.
4. Mark it Global source if every room should be able to pick it. Save.

The source view shows now-playing (title, sub-title, cover art) and a browse surface for the chosen service, and it tracks live changes from the player. See AV Sources for the full source editor and the Channels page for how favorites are stored.

Favorites

In the source view, long-press a station to add or remove it as a favorite. Favorites are saved as GEM channels tied to the source's channel provider, so they survive reboots and appear first when you reopen the browser. The favorites bar appears once the source is browsing a specific music service.

Optional source attributes

These are entered on the device as plain Attributes — they are not in the attribute picker's suggestion list, but the driver and source view read them:

Attribute	Type	Effect
provider	string	A music-service name exactly as BluOS spells it (e.g. SiriusXM, Pandora, TuneIn). Setting it makes the source view open into that service's channel browse and turns on a once-a-day background sync that mirrors the player's stations into GEM channels (so favorites and channel lists are ready without browsing first). Leave it unset for the generic browser.
banned_genres	json	An array of genre names/keys to hide from the source view's Genres pane — e.g. ["Talk","Sports"]. Useful for trimming a sprawling service catalog down to what a client cares about.
last_channel_sync	date	Written by the driver — the timestamp of the last station sync. Read-only state; you don't set it.

Firmware-update alerts

Once an hour the driver asks the player whether a BluOS firmware update is pending. When one appears it sets the update_available attribute true and sends an email through GEM's mailer noting which player needs updating. An out-of-date player can stop responding correctly, so treat the alert as actionable — run the update from the BluOS app. The flag clears on the next hourly check after the player is current.

Commands

Set these from a macro, a control, or the AI assistant. Argument names are the exact strings you put in a macro step's arguments.

Transport

Command	Args	Description
play	—	Resume / start playback.
pause	—	Pause.
pause_toggle	—	Toggle play/pause.
back	—	Back / previous track.
skip_forward	—	Skip to the next track.
play_seek	seconds	Seek to a position (seconds) in the current track.
play_input	input	Switch to a physical input. input is one of analog, spdif, hdmi, bluetooth (which inputs exist depends on the model).
set_channel	channel	Play a stream by URL — point the player at any reachable audio stream.

Volume and mute

Command	Args	Description
volume	level	Set absolute volume, 0–100.
volume_up	—	Raise volume by 5 dB.
volume_down	—	Lower volume by 5 dB.
mute_on	—	Mute.
mute_off	—	Unmute.

Play modes

Command	Args	Description
shuffle_on / shuffle_off	—	Turn shuffle on/off.
repeat_on	—	Repeat the queue.
repeat_off	—	Turn repeat off.

Presets

Presets are the numbered favorites you define in the BluOS app; the driver plays them by slot.

Command	Args	Description
list_presets	—	Return the player's defined presets.
play_preset	id	Play preset number id.
next_preset	—	Play the next preset.
previous_preset	—	Play the previous preset.

Browse, queue, and playlists

Command	Args	Description
browse	key, search	Browse a service/library node by its key, optionally filtered by search.
browse_radio	service	Browse a radio service's directory.
list_tracks	start, end	Read the current play queue over a range.
clear_queue	—	Empty the play queue.
delete_track	id	Remove one track from the queue by id.
save_queue	name	Save the current queue as a playlist named name.

Grouping (multi-room)

Bluesound groups are master-and-slaves. Send these commands to the master player's device and name the player you are adding/removing by its IP and port.

Command	Args	Description
group_player	ip, port	Add the player at ip:port as a slave of this (master) player.
ungroup_player	ip, port	Remove that slave from the group.

Group against the master

group_player runs on the device you send it to — that device becomes (or stays) the group master, and the ip / port arguments identify the slave to fold in. Set up the master device first, confirm each slave is reachable on its own IP and port 11000, then add slaves.

Status and advanced

Command	Args	Description
get_status	—	Read full now-playing + transport state on demand.
player_info	—	Player identity and group/sync status.
action	service, action, value	Run a service-specific action (e.g. a thumbs-up).
passthrough	value	Send a raw BluOS API path — an escape hatch for anything not listed above.

Behavior and limitations

• No power command. BluOS players are always-on streamers, so there is no discrete on/off — use pause to stop audio and play to resume. On models with physical inputs, play_input switches between them.
• One connection, one player. Each device controls exactly the player at its IP. Grouping links players for synchronized playback but does not merge them into one device.
• State is etag-gated. The driver only writes a state attribute when the player's status actually changes, so triggers fire on real transitions rather than on every poll.
• Presets and stations come from the player. The driver mirrors what the player exposes — define presets and add streaming services in the BluOS app first; they appear in GEM after the next sync.

Troubleshooting

Symptom	Check
Device shows disconnected.	Confirm the player answers on http://<ip>:11000/Status from the GEM host's network. A wrong IP after a DHCP lease change is the usual cause — give the player a reservation.
Live updates stop after a while.	A network drop can leave the long poll stuck. Toggle the device disabled then enabled (or wait for the Status Poll Interval backstop to recover the connection).
Presets list is empty.	Define presets in the BluOS app first — the driver only mirrors what the player exposes.
Group command does nothing / "no slave".	Send group_player to the intended master, and verify the slave is reachable on its own IP and port 11000 before grouping.
Source view shows controls but no browse.	The source's Component must be bluesound (or pandora/siriusxm/amazon_music) and its Device must be this player. For a service browse, also set the provider attribute to that service's BluOS name.
Volume "jumps" more than expected on up/down.	volume_up / volume_down move by 5 dB, not one step on the 0–100 scale. Use the volume command with a level for precise absolute settings.
Recurring "update available" email.	The player has a pending BluOS firmware update — run it from the BluOS app; the alert clears on the next hourly check.

Related

• Sonos — the other major multi-room audio integration, for comparison of patterns.
• Denon HEOS — HEOS whole-home audio (Denon/Marantz), another browsable-source driver.
• AV Sources — set the Component and Device for the Bluesound source view.
• AV Zones — bind a player as a zone's Volume Device.
• Channels — how favorites and synced stations are stored.
• Multiview — show a Bluesound source alongside others on one screen.
• Attributes — where you add the optional provider / banned_genres attributes.
• Commands — the command list this driver publishes.
• Triggers — fire automations off the player's state / volume / mute_state.