AV Zones

AV Zones represent audio and video listening/viewing areas that can play content from various sources. Each AV zone is linked to a regular zone and extended with AV-specific configuration like source assignments, on/off macros, and volume control.

Licensing

AV Zones, AV Sources, Channels, and Multiview are part of the AV System module. Creating any of them requires the module in your license; the nav items are locked otherwise. Trials and development builds unlock it, and existing AV zones keep working if a license later changes. See License.

Overview

AV Zones bridge standard zone control with AV-specific features:

• Source assignment: choose which audio/video sources are available in each zone
• Macro integration: run power-on/off and source-routing sequences automatically
• Volume control: optional dedicated volume device per zone
• Matrix routing: drive a matrix switcher from source macros using dynamic address placeholders
• Multi-room audio: coordinated control and saved listening scenes across rooms

Viewing AV Zones

The main grid displays all configured AV zones with the following columns:

• Zone ID - The parent zone this AV zone extends
• On Macro - Macro executed when zone turns on
• Off Macro - Macro executed when zone turns off
• Address - Matrix output number or routing identifier
• Volume Device - Separate volume control device (if applicable)
• Enabled - Whether AV features are active
• Sort Index - Display order

Grid Actions

• Add - Create a new AV zone
• Edit - Modify an existing AV zone
• Delete - Remove AV zone (keeps parent zone)
• Sort - Reorder AV zones
• Reload - Refresh the grid data

Quick Actions

• View AV Sources icon - Opens the zone's sources in a modal over the grid (see Managing AV Sources below)

Creating an AV Zone

To create a new AV zone:

1. Click Add in the grid toolbar
2. The AV Zone editor opens (titled New AV Zone)
3. Configure the settings below
4. Click Create AV Zone (the button reads Update AV Zone when editing an existing one)

The editor is laid out in five sections — Basic Configuration, Macro Configuration, Device Configuration, Source Configuration, and Zone Settings — described below.

Basic Configuration

AV Type

Required. Choose Audio (ceiling speakers, soundbar, multi-room audio) or Video (display, projector, matrix output). The type also filters which global sources can appear in this zone — an audio zone only offers audio global sources, and vice-versa.

Zone Name

Every AV zone extends one underlying zone in the AV subsystem. Choose how that zone is provided:

• New zone (default): the field is a text box — type a name and GEM creates a new zone in the AV subsystem and links it when you save.
• Bind to existing zone: check Bind to existing zone and the field becomes a searchable picker. The picker lists only zones already in the AV subsystem, not every zone in System → Zones. Use this when you pre-created the AV zone there, or are re-pointing this AV zone at a different backing zone.

Macro Configuration

These two macros drive what physically happens when the zone powers on and off. Routing a source to the zone is handled by the source's macros (see Source Configuration and How routing works); the zone macros handle whole-zone power/defaults.

On Macro

• Pick an existing macro from the searchable dropdown, or click the + icon to create one on the spot. The + prompts for a name (defaulting to <zone>_on) and creates a new, empty macro filed under the av subsystem — you then add its steps (turn on the receiver, select an input, set a default volume) in the Macros editor. The steps icon next to the On Macro label opens the selected macro's steps inline, and once a macro is selected, an open-in-editor icon inside the picker opens its full editor in a modal.
• Runs when the zone turns on (and, because GEM re-runs zone macros on source changes, also when switching sources within an already-on zone).

Skipping warm-up on source switches

Because the on macro also re-runs when you switch sources in an already-on zone, a fixed equipment warm-up delay would re-fire on every source change. GEM maintains a system-managed already_on boolean attribute on the zone for exactly this case: it is set after each on/source dispatch (true for any active source, false on power-off), so a macro reads the pre-dispatch value. Gate the warm-up step with an If Attribute (or If Expression) step on already_on == true → skip next step — a cold start (missing or false) warms up, while switches and re-runs skip the delay. The latch self-heals on the next dispatch.

Off Macro

• Same controls as On Macro. Runs when the zone turns off (source set to off). Typical steps: mute audio, power down the receiver/display.

Device Configuration

Address

The matrix output number (or routing identifier) for this zone — the destination a source gets routed to. GEM makes this address available to routing macros so one macro can serve many zones (see How routing works).

Simple address — type a single output number (e.g. 1, 2, 3). GEM applies that one value to the zone's video-routing, video-endpoint, audio-routing, and audio-endpoint slots, so a routing command can reference any of them and still resolve.

Advanced addressing — check the Advanced addressing box to reveal four separate fields for systems that switch audio and video independently (separate audio and video matrices, or an HDBaseT matrix with a separate audio path):

• Video Routing — video matrix output number
• Video Endpoint — video endpoint identifier
• Audio Routing — audio matrix output number
• Audio Endpoint — audio endpoint identifier

GEM stores the four values as a single pipe-delimited string with the keys vr (video routing), ve (video endpoint), ar (audio routing), and ae (audio endpoint), e.g. vr=1|ar=3|ve=1|ae=3. The order of the keys isn't significant — GEM reads each by its prefix — and re-opening the zone repopulates the four fields from it. Leave Advanced addressing off if one number routes both audio and video.

Volume Device

Optional device for independent volume control. Select from the device dropdown.

• Leave blank if the source device or the zone's own device controls volume.
• Set it if a separate receiver, amplifier, or zone processor handles volume — GEM then sends volume/mute commands to this device for the zone.

Source Configuration

Local Sources

A device multi-selector. Each device you add becomes a local AV source for this zone (one source row per device), created when you save. Removing a device prompts to delete that source from the zone.

Two checkboxes below control whether GEM also creates routing macros for newly added sources:

• Create source on macros (on by default) — for each newly added source, GEM creates an empty starter "on" macro (named <zone>_<device>_on, filed under the av subsystem) that you then fill with the routing/power steps in Macros.
• Create source off macros (off by default) — same, for the "off" macro.

When a checkbox is off, a macro picker appears next to it; the macro you choose there is assigned as the on (or off) macro for every source you add in this save. These options only affect newly added sources — existing sources keep their macros.

Hidden Global Sources

Global sources (sources with no specific zone) normally appear in every AV zone. Use this multi-selector to hide specific global sources from this zone — the list is filtered to the zone's AV Type. The selection is stored on the zone as the hidden_global_sources attribute.

Zone Settings

• Enabled — toggle AV functionality for this zone on or off.
• Local Sources Only — when on, the zone shows only its locally-assigned sources; when off, both local and global sources appear.
• Sort Index — display order in AV interfaces (lower numbers first).

Managing AV Sources

Click the View AV Sources icon on any AV zone row to open that zone's sources in a modal. This shows a grid of all sources assigned to the zone where you can add, edit, delete, sort, and reload sources — the AV Zones grid stays underneath, so closing the modal drops you right back where you were.

See AV Sources for details on source configuration.

Common Workflows

Creating Single-Room Audio Zone

For a room with ceiling speakers:

1. Click Add on the AV Zones grid
2. Set AV Type: Audio
3. Enter a zone name: living_room_audio (leave Bind to existing zone unchecked to create the backing zone)
4. On Macro: click + to create an empty living_room_audio_on macro, then add its power/input steps later
5. Off Macro: click + to create the matching off macro
6. Set Address: 1 (output on audio matrix)
7. Set Volume Device: audio_matrix (if it handles volume)
8. Add local sources: Sonos, Spotify, Radio (leave Create source on macros checked to get starter routing macros)
9. Turn Enabled on
10. Click Create AV Zone

Creating Home Theater Zone

For a dedicated theater room:

1. Click Add on the AV Zones grid
2. Set AV Type: Video
3. Enter a zone name: theater_video
4. Create (+) or select an On Macro — turn on the projector, receiver, set defaults
5. Create (+) or select an Off Macro — mute, power off
6. Set Address: 1 (projector output on matrix)
7. Set Volume Device: theater_receiver
8. Add local sources: Blu-ray, Apple TV, Game Console
9. Turn Enabled on
10. Click Create AV Zone

Creating Multi-Room Audio

For whole-home audio with shared matrix:

1. Create an AV zone for each room:

   living_room_audio - Address: 1
   kitchen_audio - Address: 2
   bedroom_audio - Address: 3
   patio_audio - Address: 4

2. All zones connect to the same audio matrix

3. Assign sources per zone (can be same or different):

   • Shared sources: Sonos, Spotify
   • Room-specific: Bedroom might exclude party sources

4. Users select source per room independently

The end-user AV view

The Audio / Video controls page offers two ways to look at the same rooms, switchable from buttons in the bottom bar (the choice is remembered per panel):

• By Room (default) — a room list on the left; selecting a room shows its power/mute/volume card and the sources it can play. Tapping a source starts it in that room and opens the source's control page. Sites with a single AV zone get this view full-width automatically.
• By Source — a source list on the left; selecting a source shows every room that can play it as a live card. Rooms already playing the selected source highlight blue; rooms playing a different source show amber with the other source's name, keep a working volume slider, and offer an explicit "Play … here" action so nobody steals a room by accident.

The sidebar (menu button, top right) is the whole-house controller: every active room appears as a card with its now-playing source, transport buttons, mute, power and volume; a Start a room section below lists the rooms that are off with a one-tap source picker; and All Vol+/− / All Off act on every active room at once.

The bottom media bar always targets one room for its volume and transport buttons — the room named on the blue chip under the now-playing text. Tap the chip to re-target the bar at any other active room. Tapping the now-playing thumbnail opens the active source's own control page — the same convention as tapping a source's icon elsewhere — in every layout; with nothing playing it opens the Audio / Video page.

All three surfaces are driven by one live subscription to the zones' source / volume / mute_state attributes, so they update in real time and never disagree.

Saving a listening scene

From the sidebar's Scenes button, users can save the current multi-room state — which source each active zone is playing and at what volume — as a named scene, then recall it with one tap later. Each scene is stored as an av_scene_* macro under the av subsystem and runs like any other macro, so it also shows up in the Macros grid. Scenes are created and managed entirely from the sidebar; there is no separate admin page for them.

How routing works

GEM does not have a hidden "matrix engine" that switches inputs on its own. Routing happens through macros, and the address fields just supply the numbers those macros plug in. The flow when a user selects a source in a zone:

1. The user picks a source (e.g. "Apple TV") in the zone UI.
2. GEM records it as the zone's current source.
3. GEM runs the outgoing source's Off Macro (if the source changed), then the incoming source's On Macro. If the zone is turning on or off, the zone's On/Off Macro runs too.
4. Whatever route command you placed in those macros fires — switching the matrix, selecting a receiver input, recalling a DSP preset, etc.

To make routing automatic, put your matrix (or receiver/DSP) route command in the source's On Macro and use a dynamic value placeholder in the command's argument so one macro serves every source/zone instead of hard-coding numbers:

• [@av_source.address] — the selected source's matrix input address
• [@av_zone.address] — this zone's matrix output address (the Address field above)
• [@zone.address] — the underlying zone's address
• [@device.address] — the source device's address
• [@device.id] — the source device's ID

These are the same placeholders offered in the Commands argument editor, and they resolve at run time to whichever source and zone triggered the macro. Checking Create source on macros when you add Local Sources gives you the starter macros to drop these route commands into. See AV Sources → Writing routing macros for the full pattern.

Separate audio and video matrices

When you use Advanced addressing (above) on both the zone and the source, GEM exposes each piece separately to the routing macro, so one macro can issue two routes:

Zone: living_room
  Video Routing: 1   (video matrix output)
  Audio Routing: 3   (audio matrix output)

Source: apple_tv
  Video Routing: 2   (video matrix input)
  Audio Routing: 4   (audio matrix input)

Macro result: route video input 2 → output 1, audio input 4 → output 3

Author the macro with one route step for the video matrix and one for the audio matrix, each referencing the appropriate input/output address.

Physical Power Reconciliation

GEM's AV state is optimistic: pressing off sets the zone's source attribute to 0 and runs the off macro. If the off command is lost in transit (network blip, device briefly unreachable), GEM shows the zone off while the amp keeps playing — and the off controls disappear from the UI because GEM believes there is nothing to turn off.

For amps whose driver polls physical state (AudioControl Director, RTI AD-8/AD-8x, AVPro AC-MAX, and any driver that writes the zone power_state attribute), GEM detects and self-heals this automatically:

1. When power_state reports on while source is 0, a debounce timer starts (default 30 seconds — long enough for a normal power-off ramp plus a couple of poll cycles).
2. If the divergence is still present when the timer fires, GEM adopts the physical state: source is restored — mapped from the amp's reported input when possible, otherwise the source that was playing before the off. On/source macros are suppressed for this write (the zone is already on; re-running warmup or routing would be wrong).
3. The zone now shows on in the UI, so the off controls return and a normal off can be dispatched.
4. If no source can be resolved, GEM raises the AV Zone Power Divergence alarm instead — select any source in GEM and turn the zone off, or power it down at the amp.

The reverse direction (physically off while GEM shows on) is deliberately not reconciled: that state is benign — the off controls are visible and pressing off simply converges the states.

Zone attributes:

Attribute	Default	Purpose
power_reconcile	true	Set false to disable reconciliation for a zone that intentionally diverges
power_reconcile_seconds	30	Debounce window before a divergence is confirmed and reconciled

Troubleshooting

Source Not Appearing in Zone

Check:

1. Source Assignment: Source is assigned to the AV zone (local sources) or is a global source
2. Hidden Sources: Source is not in the Hidden Global Sources list
3. Local Sources Only: If enabled, only locally-assigned sources appear
4. Source Enabled: The source itself is enabled (AV Sources page)
5. Zone Enabled: The AV zone is enabled

Matrix Not Routing

Remember routing is done by the source's On Macro, not automatically (see How routing works).

Check:

1. Address configured: the zone has its Address (matrix output) set, and the source has its address (matrix input) set
2. Route step present: the source's On Macro actually contains the matrix route command
3. Placeholders, not hard-coded numbers: the route command uses [@av_source.address] / [@av_zone.address] so it resolves to the right input/output
4. Matrix online: the matrix switcher device is connected
5. Advanced addressing: if using separate audio/video matrices, verify all four address fields on both zone and source

On Macro Not Executing

Check:

1. Macro enabled: the on macro is enabled (Automation → Macros)
2. Macro assigned: the on macro is selected in the AV zone's On Macro field
3. Macro steps valid: all macro steps are correctly configured
4. Logs: check system logs for macro execution errors

Volume Not Working

Check:

1. Volume Device: Correct device assigned in Volume Device field
2. Device Online: Volume device is connected
3. Commands: Device supports volume commands in its command set

Related Documentation

• AV Sources - Managing AV source library
• Zones - Creating parent zones
• Macros - Creating on/off macros
• Devices - Configuring matrix switchers and AV equipment
• Channels - TV channel integration