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. Four 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)
  • Preview — open the provider's lineup in the same channel browser users see on a touchpanel (disabled until a provider is chosen — see Previewing a lineup)

Under the grid, a Used by line names every AV Source bound to the selected provider — click one to open it in place, without losing the provider selection. When nothing is bound yet the line says so, which is the usual reason a freshly synced lineup shows nowhere on a touchpanel.

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.

Lineup source — which online listings service the provider syncs from: XMLTV Listings (xmltvlistings.com, the default) or Schedules Direct. Existing providers keep syncing from XMLTV Listings unless you change this.

External provider ID — the lineup ID from the selected 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.

  • For XMLTV Listings this is the numeric xmltvlistings.com lineup ID.
  • For Schedules Direct this is the lineup ID in COUNTRY-lineup-device form, e.g. USA-CA61222-X (cable/satellite) or USA-OTA-90210 (antenna, keyed by zip code).

Click Save, or Back to cancel.

Editing a provider​

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

Syncing channels​

GEM syncs lineups from the provider's Lineup source — xmltvlistings.com (an online XMLTV listings service) or Schedules Direct (a low-cost listings service with US/Canada cable, satellite, and antenna lineups). Sync downloads the provider's channel list and merges it into the grid.

Credentials required

Both services need credentials stored as system attributes under System → Attributes (target System):

  • XMLTV Listings — one attribute, xmltvlistings_api_key, value = your xmltvlistings.com API key. Without it, every sync fails with "missing xmltvlistings api key".
  • Schedules Direct — two attributes, schedulesdirect_username and schedulesdirect_password, your schedulesdirect.org account login. The password is stored encrypted. A Schedules Direct membership covers all of a site's lineups; GEM adds a provider's lineup to the account automatically on first sync.

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 its listings service using the stored credentials 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,
    • network logos are downloaded and stored locally (see Logos from sync).
  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 lineup source's credentials are set: xmltvlistings_api_key for XMLTV Listings, or schedulesdirect_username / schedulesdirect_password for Schedules Direct.
  • The provider has an External provider ID (its lineup ID on the selected service).
  • The server can reach the listings service (xmltvlistings.com or json.schedulesdirect.org).

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.

Previewing a lineup​

Click Preview (any provider — synced or hand-built) to open the lineup in the same channel browser users see when a source bound to this provider is selected: enabled channels only, sort-index order, logos, and the favorites collapse. It's the fast way to check the result of a sync, or to curate a lineup, without walking to a touchpanel.

Inside the preview:

  • Search filters channels by name, exactly like the touchpanel search.
  • Favorites only mirrors the browser's collapse behavior — it switches on automatically when the lineup has any favorites; untick it to see the full lineup.
  • Tap a channel to see what it would tune (no command is sent from the preview).
  • Press-and-hold toggles the channel's favorite flag for real, just as it does for users — the grid refreshes with the change when you close the preview. This is the quickest way to build a favorites list after a big sync.

Note that device-level display attributes (hide_channel_number, channel_background_color, …) are not applied in the preview — those belong to the source device, and the preview shows the provider's lineup with default styling.

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_button_scale — size multiplier for the channel buttons, for users who have trouble seeing. 1 is the standard size; 1.5 or 2 enlarges the logo, name, number badge and spacing together, and the grid reflows to fit. Accepts 0.25 to 5. Applies to the channel browser only, not the channel widget.
  • 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.

Favorites also drive generated RTI remotes: a source gets a Channels page only when at least one of its channels is favorited, favorites order first, and the rest of the enabled lineup follows — continuing onto numbered pages as needed, up to 60 channels per source.

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, GEM downloads each channel's network logo and stores it on the controller, under /images/channels/<provider id>/. The channel row then points at that local copy, so channel browsers load logos straight from GEM — no per-client internet fetch, and lineups keep their artwork on sites with no (or filtered) internet access.

The details:

  • A logo is downloaded once; later syncs reuse the file on disk. If the service starts serving a different logo URL for a channel, the next sync downloads the new image and cleans up the old file.
  • If a download fails (service unreachable, unsupported image type), the external URL is stored instead and the client fetches it through the image proxy exactly as before — the next sync retries the download. Repeated failures pause logo downloads for the rest of that sync run so a dead CDN can't stall it.
  • If the service has no icon for a channel at all, GEM falls back to /images/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. The Used by line under the channel grid answers this without leaving the page.
  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. Credentials — the lineup source's system attributes are set (the most common cause): xmltvlistings_api_key, or schedulesdirect_username / schedulesdirect_password.
  2. External provider ID — the provider has its lineup ID set, in the form its Lineup source expects.
  3. Network — the server can reach the listings service.
  4. Already cached — a sync within the last 24 hours reuses the cached lineup; the listings file refreshes once a day.
  5. Schedules Direct account limits — a "lineup error … add failed" message usually means the account is at its lineup limit (4 by default) or its lineup-change limit for the day; remove unused lineups at schedulesdirect.org and re-sync.

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 credentials once — add the lineup source's system attributes (xmltvlistings_api_key, or schedulesdirect_username / schedulesdirect_password) 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 Lineup source setting is copied, but the External provider ID is not copied by default — so clones start as manual lineups (a clone that is asked to copy the ID keeps syncing from the same listings service). 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