Skip to main content

Savant Soundbar

A Savant soundbar, controlled over the LAN through the soundbar's built-in HTTP control interface. The driver gives you volume and mute on the soundbar's single audio output, and it keeps GEM's picture of the room in sync by polling the soundbar for its current level and mute state on a short timer.

Because the soundbar answers those status reads with its real values, a volume or mute change made from the soundbar's own remote or app shows up in GEM within a poll cycle — you don't have to do anything to keep them aligned.

How GEM sees the unit​

This driver represents one soundbar as a single device. It does not create a GEM control zone of its own, and it is not a matrix or controller. To get a room-level volume slider and mute button, you bind the device to an AV zone (see Linking to an AV zone below).

The soundbar exposes a single output — there is no per-zone routing, input switching, or power control in this driver. It is purely a volume-and-mute endpoint. Multi-output Savant audio gear should use a different driver.

What's controlled​

  • Volume as a 0–100 level, mapped to the soundbar's −60 … 0 dB range, plus one-step up / down
  • Mute on / off
  • Background polling (default every 2 seconds) that mirrors the soundbar's real volume and mute state back into GEM

Prerequisites​

  • A Savant soundbar reachable on the LAN, with its HTTP control interface exposed on the soundbar's IP. No username or password is required — control is open on the local network.
  • A stable IP for the soundbar — set a DHCP reservation or a static address so the control connection doesn't move. The driver talks to the standard HTTP port, so there is no port to configure.

Setup​

  1. Reserve the soundbar's IP (DHCP reservation or static) so it doesn't change.
  2. In GEM, open Devices and choose Add a Device.
  3. Give it a Name (lowercase letters, numbers, and underscores — e.g. living_soundbar) and an optional friendly Label.
  4. Under Driver, pick Savant Soundbar. GEM fills the Type in as soundbar for you and sets up a savant_soundbar command set automatically.
  5. Set the Subsystem to AV.
  6. In the Device Attributes section, set Soundbar IP to the soundbar's address. That is the only required field.
  7. (Optional) Expand the optional attributes to tune the volume scale and polling — see Attributes below. The defaults are sensible; you can skip this.
  8. Save. On connect, GEM begins polling the soundbar; the device's volume and mute fill in within a poll cycle.

Linking to an AV zone​

The soundbar feeds volume and mute into an AV zone rather than appearing as its own controllable zone:

  1. Open AV Zones and edit (or create) the zone for the room the soundbar serves.
  2. Set the Volume Device field to this Savant device.
  3. Save. From then on the zone's volume slider and mute button drive the soundbar, and each time the soundbar reports a new level the zone mirrors it back.
note

The soundbar has no single "toggle mute" command — only mute and unmute. When you place a mute button on an AV-zone touchpanel, GEM turns it into a toggle for you by tracking the last mute state it sent. If someone mutes or unmutes from the soundbar's own control instead, GEM's polled reading still updates, but a zone mute toggle button may need one extra press to line back up. For deterministic behavior in a macro, prefer explicit mute_on / mute_off.

Volume: the 0–100 scale and dB​

The soundbar's control interface carries volume as a dB value from −60 dB (effectively off) to 0 dB (maximum). The driver hides that: you always give it a 0–100 level, and it translates in both directions — so the room slider and any macro work in the same 0–100 units as every other GEM volume.

The mapping is linear in dB:

GEM levelApprox. level
0−60 dB (effectively off)
25−45 dB
50−30 dB
75−15 dB
1000 dB (maximum)

Each step of one on the 0–100 scale is roughly 0.6 dB. Because the translation rounds to whole steps in each direction, setting a level and reading it back can differ by one — that's expected and inaudible.

Attributes​

Device — required​

AttributeTypeDescription
ipstringThe soundbar's LAN IP (shown in the form as Soundbar IP).

Device — optional​

These tune the volume scale and polling. The defaults work for most installs.

AttributeTypeDefaultDescription
status_intervalint2000How often, in milliseconds, GEM polls the soundbar for volume and mute (shown as Status Poll Interval (ms)). The default is aggressive; raise it if the slider fights you while dragging.
volume_stepint3The 0–100 increment applied by volume up / volume down (shown as Volume Step).
minint0Lower clamp for the 0–100 range (shown as Minimum Volume). Volume up / down won't go below this.
maxint100Upper clamp for the 0–100 range (shown as Maximum Volume). Volume up / down won't go above this.

Device — reported state​

The driver fills these in from its poll as the soundbar reports them — they are status, not values you set:

AttributeTypeDescription
volumeintCurrent level on the 0–100 scale, refreshed each poll.
mutestringon / off, refreshed each poll.

Commands​

The driver sends form-encoded HTTP requests to the soundbar's /cgi-bin/avswitch control endpoint (?action=setAudio) and reads status back from ?action=showAllAudioPortsInJson. The "Sends" column shows the field it sets on the soundbar's single output, so you can match it against a packet capture.

CommandSendsNotes
volumeoutput1.volume=<dB>Set volume. You supply a 0–100 volume; the driver clamps it, converts to the soundbar's −60 … 0 dB value, and sends it. A non-numeric value is rejected with "invalid volume".
volume_upoutput1.volume=<dB>Raise volume by Volume Step from the current level, clamped to Minimum/Maximum.
volume_downoutput1.volume=<dB>Lower volume by Volume Step from the current level, clamped to Minimum/Maximum.
mute_onoutput1.mute=mutedMute the output.
mute_offoutput1.mute=not-mutedUnmute the output.

There is no power, input, or source command in this driver — the soundbar is a volume-and-mute endpoint only.

Known limitations and quirks​

  • Single output only. The driver controls the soundbar's one output. There's no per-zone routing or input selection, and it doesn't create GEM zones automatically — you attach it to an AV zone yourself.
  • No native mute toggle. Only mute and unmute exist on the wire. From an AV zone GEM synthesizes a toggle from its last-known state; a mute made on the soundbar itself can leave a toggle button one press out of phase until you press it again.
  • Aggressive default poll. Status polling defaults to 2 seconds. That keeps the slider responsive to changes made on the soundbar's remote, but while an operator is actively dragging the slider the incoming poll can make it snap — raise Status Poll Interval (ms) to 5000+ if you see that.
  • ±1 on read-back. The 0–100 ↔ dB translation rounds in each direction, so setting a level and reading it back can differ by one step. It's expected and inaudible.

Troubleshooting​

SymptomCheck
Device won't connectConfirm the Soundbar IP is correct and the soundbar is reachable on the LAN (its control interface uses the standard HTTP port; no auth is needed).
volume command rejected ("invalid volume")The value must be an integer 0–100. A blank or non-numeric value is refused.
Volume slider snaps back while draggingThe status poll is racing your input. Raise Status Poll Interval (ms) to 5000 or more while actively adjusting.
Volume changes on its ownThe soundbar was adjusted from its own remote or app. The next poll re-reads the real level and the slider catches up.
Zone mute button is one press behindThe soundbar was muted/unmuted outside GEM. Because there's no native toggle, the zone button tracks GEM's last command — press it once more to resync, or drive mute_on / mute_off explicitly.
Set level and read-back differ by oneExpected — the 0–100 ↔ dB translation rounds in each direction.