Skip to main content

AV Sources

AV Sources are the audio and video content sources you can route to AV zones — cable/satellite boxes, Blu-ray and media players, streaming devices, audio servers, and any equipment that originates A/V content. Each source links to a device (for transport control and, on media players, now-playing info), optionally carries on/off macros that route the signal, and is either tied to one AV zone or made global to every zone.

Licensing

AV Sources, AV Zones, 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 sources keep working if a license later changes. See License.

Open AV Sources

Overview​

The AV Sources page is the library of every source available in the system. A source can be assigned to a specific AV zone (it appears only there) or left unassigned/global (it appears in every AV zone). When a user selects a source in a zone, GEM runs that source's On Macro to route the signal; when the source is dropped it runs the Off Macro.

Viewing AV Sources​

The grid lists all configured sources with these columns:

  • Device — the physical source device
  • AV Zone — the zone this source is tied to (blank for global sources)
  • AV Type — audio or video
  • Label — the display name shown to users
  • On Macro — macro run when the source is selected
  • Off Macro — macro run when the source is deselected
  • Address — matrix input number or routing identifier
  • Enabled — whether the source is available
  • Sort Index — display order

Grid Actions​

  • Add — create a new source
  • Edit — open a source in the creator
  • Sort — drag to reorder sources
  • Reload — refresh the grid
  • Delete — remove a source

Creating an AV Source​

  1. Click Add in the grid toolbar.
  2. The AV Source editor opens.
  3. Fill in the fields below — Device, AV Type, and Label are required.
  4. Click Create Source (the button reads Update Source when editing an existing one).

The editor is divided into four sections, in this order: Basic Configuration, Device Configuration, Macro Configuration, and Source Settings.

Basic Configuration​

AV Zone​

Pick the AV zone this source belongs to, or make it global:

  • A specific zone — the source appears only in that zone (a local source).
  • Global source (not zone-specific) — check this box and the AV Zone picker is disabled; the source then appears in every AV zone (unless a zone hides it via Hidden Global Sources, or has Local Sources Only turned on). Use global for anything shared across rooms — a Sonos system, a streaming service, a cable headend feeding a matrix.

AV Type (required)​

Choose Audio or Video from the dropdown. The stored value is lowercase audio / video; some on-screen layouts and filters key off this type.

Device (required)​

The physical device this source represents. The link does three things:

  • provides transport control (play, pause, stop, skip) when the user is on this source;
  • on media players that report it (for example Sonos), feeds now-playing metadata and presets/favorites back to the source view;
  • supplies the device address that macro commands can substitute for routing.

If you pick a device that is currently disabled, the editor shows a warning so you don't wire a source to dead hardware.

Examples: Blu-ray player, Apple TV, cable box, audio streamer.

Label (required)​

The user-friendly name shown in source selectors and on touchpanels.

Examples: "Apple TV", "Blu-ray", "Cable TV", "Sonos".

Device Configuration​

Address​

The matrix input number or routing address for this source. GEM makes the source's address available to its routing macros so one macro can serve many sources.

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

Advanced addressing — check the box to reveal four separate fields for matrices that switch audio and video independently (for example an HDBaseT matrix with a separate audio de-embed):

  • Video Routing
  • Video Endpoint
  • Audio Routing
  • Audio Endpoint

GEM stores the four values as a single pipe-delimited string (vr=…|ve=…|ar=…|ae=…); re-opening the source repopulates the four fields from it. Leave Advanced addressing off if one number routes both audio and video.

Icon​

Path to an icon (or an emoji) shown for this source in source selectors. Optional.

Component​

The on-screen control surface drawn for this source when a user selects it. The dropdown lists the built-in source-view panels — for example sonos, spotify, heos, bluesound, airplay, pandora, siriusxm, roku, appletv, directv, digital_cable (and the *_dvr variants), dvd, oppo_bluray, kaleidescape, youtube_tv, and multiview. Pick the panel that matches the device so the user gets the right buttons (a streamer's browse/now-playing UI, a DVR's transport/guide, a multi-window multiview grid, and so on). Optional — leave it blank for a generic source view.

Channel Provider​

Link the source to a channel provider to attach a TV channel lineup. When set, the source can present a channel guide for direct channel selection. See Channels.

Macro Configuration​

On Macro​

The macro GEM runs when this source is selected in a zone. Use it to route the matrix input to the zone's output, power on the source, select an input on a receiver, or set a default volume. Click the + icon next to the field to create a new macro on the spot (it's filed under the av subsystem).

Off Macro​

The macro GEM runs when this source is deselected — because another source was chosen, or the zone turned off. Use it to release routing, power down the source, or mute. When a user switches sources, GEM runs the outgoing source's Off Macro and then the incoming source's On Macro.

Writing routing macros — dynamic placeholders​

Inside the command steps of an on/off macro, use these dynamic value placeholders (the same ones offered in the command argument editor) so one macro works for any source/zone:

  • [@av_source.address] — this source's matrix input address
  • [@av_zone.address] — the target AV zone's matrix output address
  • [@zone.address] — the underlying zone's address
  • [@device.address] — the source device's address
  • [@device.id] — the source device's ID

They resolve at run time to whichever source and zone triggered the macro, so a single "route source to zone" macro can be reused everywhere instead of hard-coding inputs and outputs.

Source Settings​

Re-run Macros​

When on, the source's on/off macros run every time the source is selected, even if it's already the active source in that zone. When off (the default), the macros only run when the source actually changes. Turn it on for hardware that needs its route re-asserted on every press.

Enabled​

Toggle the source available or unavailable without deleting it.

Sort Index​

Display order in source lists — lower numbers appear first.

Global vs. zone-specific sources​

Global sources​

A source with Global source checked (no AV zone assigned):

  • appears in all AV zones by default;
  • can be hidden in a given zone via that zone's Hidden Global Sources list;
  • is the right choice for shared equipment — whole-home audio, streaming services, a shared cable box feeding a matrix.

Zone-specific (local) sources​

A source assigned to one AV zone:

  • appears only in that zone;
  • is the right choice for gear physically wired to a single room (a local Blu-ray player, an in-room game console).

A zone with Local Sources Only enabled shows only its own local sources and suppresses every global source.

Auto-generated source macros​

You don't have to author every routing macro by hand. When you create or edit an AV Zone, the editor's Local Sources section has Create source on macros (on by default) and Create source off macros (off by default). With these checked, GEM generates starter on/off macros for that zone's sources containing basic routing steps, which you can then refine in Macros.

Troubleshooting​

Source not routing​

  1. Address — the source has the correct matrix input address.
  2. Zone address — the AV zone has the correct matrix output address.
  3. Matrix online — the matrix device is connected.
  4. On Macro — the source's On Macro has the correct routing steps (and the right dynamic placeholders, not hard-coded inputs).

Source not appearing in a zone​

  1. Enabled — the source is enabled.
  2. Zone assignment — it's assigned to the right zone, or marked Global.
  3. Hidden — it isn't in that zone's Hidden Global Sources list.
  4. Local Sources Only — the zone doesn't have Local Sources Only turned on (which hides all global sources).

Source not controlling the device​

  1. Device assigned — the source has a device linked.
  2. Device online — that device is connected.
  3. Command set — the device has a command set with transport controls.

AI assistant​

  • Voice — "what can I watch in here?", "what sources are in the theater?", "what can I listen to in the kitchen?" (the list_sources skill) lists the sources routable on the asker's AV zone (or a zone named by room) — local plus global/matrix sources, honoring the zone's Local Sources Only flag — and flags which source is on now. Optional filters narrow by keyword ("what Sonos gear is in the kitchen?") or by audio/video type. Read-only — "watch Roku" still routes through source switching — and capped at 20 sources per reply.
  • AV Zones — assigning sources to zones, hidden/local sources, and auto-generated macros
  • Channels — TV channel lineups and providers
  • Multiview — multi-window source layouts
  • Devices — configuring the source devices
  • Commands — dynamic value placeholders for routing macros
  • Macros — source-selection automation