Skip to main content

Channels

Channels manages the TV channel lineups behind cable, satellite, and IPTV sources. A lineup gives the on-screen channel browser friendly names, channel numbers, station call signs, network logos, and favorites, so a user taps ESPN instead of remembering it's channel 501.

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 channel lineups keep working if a license later changes. See License.

Open Channels

Reach this page from the admin menu under AV → Channels.

How channels fit together​

  • A Channel Provider is one lineup — typically one per physical service (a Comcast headend, a DirecTV location, an IPTV package).
  • A Channel is one row in that lineup: number, name, call sign, logo, favorite and enabled flags, and a sort position.
  • An AV Source (the cable box, satellite receiver, or streamer) is bound to a provider with the Channel Provider dropdown in the AV Sources editor. When that source is selected in a zone, the on-screen channel browser shows that provider's enabled channels.
  • Tapping a channel sends a channel-change command to the source device.

A provider can be filled by hand, populated automatically from an online listings service (see Syncing Channels), or built automatically by a streaming driver that turns its installed apps into "channels" (see Channel logos).

Viewing channels​

Pick a provider from the Provider dropdown at the top of the page. The grid then lists that provider's channels — the grid is empty until a provider is selected.

Columns​

  • ID — channel identifier (unique within the provider)
  • Channel — channel number (2, 5, 48, 501, …), stored as text
  • Name — channel name (ABC, ESPN, HBO, …)
  • Logo — network logo URL or path
  • Call Sign — station call sign (WABC, KABC, …)
  • Favorite — favorite flag
  • Enabled — whether the channel appears in the browser (disabled channels are hidden)
  • Sort Index — display order

You can edit cells directly in the grid (for example, flip Favorite or Enabled, or correct a Channel number).

Grid actions​

  • Add — create a channel by hand
  • Delete — remove a channel
  • Sort — drag rows into the order you want, then click the Save Sort Order button (swap-sort icon) in the toolbar

Channel providers​

The Provider dropdown at the top of the page selects which lineup you are viewing and editing. Each entry shows as [id] name. Three buttons sit next to it:

  • New — create a provider
  • Edit — edit the selected provider (disabled until a provider is chosen)
  • Sync — pull the lineup from the online listings service (disabled until a provider is chosen and it has an External provider ID — see Syncing Channels)

Creating a provider​

Click New and fill in:

Name — internal identifier, auto-formatted to lowercase_with_underscores (required). Examples: cable_comcast, satellite_directv, iptv_stream.

External provider ID — the lineup ID from the online listings service (optional). Leave it blank for a hand-built lineup. Setting it is what enables the Sync button and what each daily auto-sync uses to find this provider's lineup.

Click Save, or Back to cancel. A provider holds only these two fields — its name and its External provider ID.

Editing a provider​

  1. Select the provider from the dropdown.
  2. Click Edit.
  3. Change the Name or External provider ID.
  4. Click Save.

Syncing channels​

GEM syncs lineups from xmltvlistings.com, an online XMLTV listings service. Sync downloads the provider's channel list and merges it into the grid.

API key required

Sync needs a service API key stored as a system attribute named xmltvlistings_api_key. Add it under System → Attributes: target System, attribute name xmltvlistings_api_key, value = your xmltvlistings.com key. Without it, every sync fails with "missing xmltvlistings api key".

What the Sync button does​

  1. Select the provider from the dropdown.
  2. Click Sync (it disables while the sync runs).
  3. GEM downloads this provider's lineup from the listings service using the API key and the provider's External provider ID, then merges it:
    • new channels are added (and marked enabled),
    • existing channels are updated — channel number and logo are refreshed.
  4. A message reports completion (or the per-provider error).

Sync adds and updates channels; it does not remove or flag channels that disappear from the service — clean those up by hand if a provider drops a channel. The downloaded lineup file is cached locally for 24 hours, so re-syncing within a day reuses the cached copy instead of re-downloading.

Automatic daily sync​

GEM re-syncs every provider that has an External provider ID once every 24 hours on its own — you do not have to schedule anything. The manual Sync button is for forcing an immediate refresh after a lineup change.

Requirements​

  • The xmltvlistings_api_key system attribute is set.
  • The provider has an External provider ID (its xmltvlistings lineup ID).
  • The server can reach xmltvlistings.com.

Manual channel entry​

For a hand-built lineup (no External provider ID), click Add and fill in:

  • Name — auto-formatted to lowercase (required). Friendly mixed-case names like "ABC" come from sync; a manually typed name is lowercased.
  • Provider — which lineup this channel belongs to (required).
  • Channel — the channel number, e.g. 2, 48, 501 (required).
  • Call Sign — station identifier, e.g. WABC-DT (optional).
  • Logo — logo URL or path (optional; normally filled by sync — see Channel logos).
  • Favorite — toggle on to mark a favorite.
  • Enabled — toggle on to show the channel in the browser.
  • Sort Index — display order; or leave it and drag-sort in the grid afterward.

Click Save, or Back to cancel.

Using channels in UIs​

The channel browser​

When a zone's selected source is bound to a Channel Provider, the on-screen channel browser shows that provider's enabled channels in Sort Index order, each with its logo, number, and name. Tapping a channel tunes it.

What the browser shows is tuned by attributes on the source device (set them in Devices → Attributes):

  • hide_channel_info — hide both the channel number and name
  • hide_channel_name — hide just the name
  • hide_channel_number — hide just the number
  • channel_background_color — background color for the channel buttons
  • channel_css_class — extra CSS class for custom styling

The browser also has a search field that filters by channel name.

Channel commands​

Tapping a channel sends the set_channel command (alias channel) with the channel number, e.g. {channel: 501}, to the source device.

How that turns into a tune depends on the device:

  • Devices with a native channel command — the driver tunes directly (for example a network-controlled receiver or streamer).
  • IR devices (the generic_ir driver), or any device that has no native channel command but is handed a channel number — GEM emulates the tune by sending each digit as its own command. The device's command set must have commands named 0 through 9; GEM sends them in order, then (unless suppressed) an enter or select command. See Commands for building these.

Preset enter behavior​

After sending the digits, GEM sends an enter (or select) command to confirm the channel. Some devices auto-tune after the last digit and don't need it.

To skip the confirm command for a device, set the preset_enter attribute to false on the device.

Preset padding​

Some devices need the channel zero-padded to a fixed width (channel 5 sent as 005). Set preset_padding to the digit count. When padding is set, the enter/select command is automatically skipped — the device knows the channel is complete once all the padded digits arrive.

Related device attributes (set in Devices → Attributes):

  • preset_enter — set to false to skip the enter/select command after the digits (default behavior is to send it)
  • preset_padding — zero-pad channel numbers to this many digits (e.g. 3 sends 5 as 005); also skips the enter command
  • channel_enter_delay — milliseconds to wait before the enter command (overrides the default per-digit pacing, which is ~700 ms)

Favorite channels​

Marking favorites​

  • In the grid, flip the Favorite column for the channels you want.
  • On a touchpanel, press and hold a channel in the browser to toggle its favorite.

How favorites display​

If a provider has any favorited channel, the channel browser shows only the favorites — it becomes a quick-access favorites view rather than the full lineup. With no favorites set, the browser shows the full enabled lineup.

Channel logos​

Automatic logo fetching​

Some streaming drivers build a provider automatically and fetch logos for you. The Apple TV and Android TV drivers turn each installed app into a channel: they create a Channel Provider named after the device, add one channel per app, fetch each app's icon from the App Store / iTunes lookup service, cache it locally under /images/icons/<device_name>/, and link the AV source to the new provider — no manual logo work needed.

Logos from sync​

When syncing from the listings service, each channel's logo is set to the network logo URL the service provides. If the service has no icon for a channel, GEM falls back to /images/channels/missing.png.

Manual logos​

The Logo column holds a URL or path to an image:

https://cdn.example.com/logos/abc.png
/images/channels/abc.png

Square PNG/JPG logos render best. There is no logo-upload tool on this page — host the image (in the server's static directory or on a reachable URL) and reference it in the Logo field, or let sync / a streaming driver fill it in.

Channel order​

Channels display in Sort Index order — both in the admin grid and in the on-screen browser. To reorder a lineup, drag rows in the grid and click Save Sort Order, or edit the Sort Index values directly. There is no automatic "by name" or "by category" ordering; sort index is the single order the browser uses.

Multiple providers​

Different sources can use different lineups. Bind each source to its own provider with the Channel Provider dropdown in the AV Sources editor:

Living Room cable box  → cable_comcast    (provider 1)
Bedroom satellite      → satellite_directv (provider 2)
Guest house streamer   → iptv_stream       (provider 3)

Each zone shows the lineup of whichever source is currently selected in it.

What is not yet built​

  • Channel categories — there is no grouping of channels (news/sports/movies) and the channel browser does not filter by category. (An unused channel-category schema that previously existed has been removed.)
  • Program guide (EPG) data — sync imports only each channel's name, number, call sign, and logo. It does not store what's on now/next, and there is no on-screen program guide.

Troubleshooting​

Channels not displaying​

  1. Provider selected — a provider is chosen in the dropdown (the grid is empty otherwise).
  2. Source bound — the AV source has a Channel Provider set in the AV Sources editor.
  3. Channels enabled — the channels are marked Enabled (disabled channels are hidden).
  4. Favorites filter — if some channels are favorited, the browser shows favorites only; clear the favorite flags to see the whole lineup.

Sync failed​

  1. API key — the xmltvlistings_api_key system attribute is set (the most common cause).
  2. External provider ID — the provider has its xmltvlistings lineup ID set.
  3. Network — the server can reach xmltvlistings.com.
  4. Already cached — a sync within the last 24 hours reuses the cached lineup; the listings file refreshes once a day.

Channel logos not showing​

  1. URL/path — the logo URL or path is valid and reachable.
  2. File exists — a local path resolves to a real file the server can read.
  3. Format — the image is a PNG or JPG.

Wrong channels tuning​

  1. Channel number — the number in the grid matches what the device expects.
  2. Digit commands — for IR/generic devices, the device's command set has commands 0–9 plus enter/select.
  3. Padding — preset_padding matches the device's expected digit count, if it needs fixed-width entry.
  4. Provider — the source is bound to the correct provider.

Best practices​

  1. Set the API key once — add xmltvlistings_api_key at the system level so every provider with a lineup ID syncs (and re-syncs daily) automatically.
  2. One provider per service — keep separate lineups for separate headends/receivers and bind each source to the right one.
  3. Pre-set favorites — favorite the handful of channels each room actually uses; the browser collapses to those.
  4. Reorder with sort index — drag-sort the grid to put the most-used channels first.
  5. Test after syncing — tune a few channels on real hardware to confirm digit commands and padding are right.

AI assistant​

  • Voice — "what channels do I have?", "what apps are on the Roku?", "show me my favorites" (the list_channels skill) lists the enabled channels on the active source of the asker's AV zone (or a zone named by room), with optional favorites-only and keyword filters ("what sports channels do I have?"). Read-only — "turn to CNN" still routes through the channel-matching skill that tunes a single channel. Replies are capped at 40 channels; sources with no bound provider answer that the source doesn't use channels.
  • Admin — "clone the family room cable lineup for the master bedroom box", "duplicate the roku favorites for the second Roku" (the clone_channel_provider skill) deep-copies a provider and every channel in it — number, name, call sign, logo, enabled/favorite flags, and sort order — to one or many new providers in one atomic call. It's the fast path for fanning a hand-built lineup across identical hardware, since the grid has no clone-provider button and each channel is otherwise a separate row. The External provider ID is not copied by default, so clones start as manual lineups; point each new source at its clone with the Channel Provider dropdown afterward.
  • AV Sources — binding a source to a channel provider
  • AV Zones — zone configuration
  • Devices — cable box / tuner / streamer configuration and the channel attributes
  • Commands — channel-change and digit commands