App constants

source/AppConstants.brs exposes a single function AppConstants() that returns an associative array of every tunable value in the application. Centralizing configuration here avoids magic numbers scattered across the codebase and makes it easy to audit and update values before a release.

source/AppConstants.brs

function AppConstants() as Object
    return {
        ' ... all constants ...
    }
end function

Call AppConstants() anywhere in BrightScript to get a fresh copy of the table. There is no global singleton — the AA is constructed on each call.

Server & endpoints

Constant	Value	Description
`SERVER_LIST`	`["http://172.17.11.2:3333", "https://admin.globaltv.lat"]`	Ordered list of backend servers. Index 0 is the LAN server; index 1 is the production server. The app tries servers in order and falls back on failure.
`PATH_HEALTH`	`/health`	Health-check endpoint. Polled to determine if a server is reachable before attempting auth.
`PATH_HANDSHAKE`	`/api/v1/app/devices/handshake`	Device handshake endpoint called at startup to register the device.
`PATH_AUTH_TPL`	`/auth/{user}/{pass}`	URL template for authentication. `{user}` and `{pass}` are substituted at runtime.
`PATH_PLAYLIST_TPL`	`/auth/{user}/{pass}/playlist/m3u8/hls`	URL template for fetching the HLS channel playlist after successful auth.
`PATH_ADS`	`/api/v1/app/ads/active`	Endpoint for fetching the current active ad snapshot from the main backend.
`PATH_METRICS`	`/api/v1/app/metrics/track`	Endpoint for posting playback and engagement metrics.

SERVER_LIST[0] (172.17.11.2:3333) is a LAN address intended for local development. In production environments the app selects the best available server from the list based on health-check results.

Ads backend

Constant	Value	Description
`ADS_API_BASE_URL`	`https://ads.globaltv.lat/api/v1`	Base URL for the dedicated ads backend. All `ADS_PATH_*` constants are relative to this base.
`ADS_PATH_HANDSHAKE`	`/app/devices/handshake`	Ads backend handshake path.
`ADS_PATH_HANDSHAKE_FALLBACK`	`""`	Fallback path for the ads handshake. Empty string disables the fallback.
`ADS_PATH_ACTIVE`	`/app/ads/active`	Path for fetching the active ad snapshot from the ads backend.
`ADS_PATH_ACTIVE_FALLBACK`	`""`	Fallback path for the active ad snapshot. Empty string disables the fallback.
`ADS_PATH_IMPRESSIONS`	`/app/impressions/events/batch`	Path for posting impression events in batch.
`ADS_PATH_IMPRESSIONS_FALLBACK`	`""`	Fallback path for impression batch posting. Empty string disables the fallback.
`ADS_USE_DEDICATED`	`true`	When `true`, the app uses `ADS_API_BASE_URL` for all ad requests instead of the main backend.
`ADS_HANDSHAKE_ENABLED`	`true`	When `true`, the app performs the ads handshake before fetching ad snapshots.

Timeouts & retries

Constant	Value	Description
`TIMEOUT_HEALTH`	`2500` ms	Maximum wait time for a health-check response. Kept low so server selection is fast.
`TIMEOUT_AUTH`	`15000` ms	Maximum wait time for an authentication response. Higher to accommodate slow connections.
`TIMEOUT_HTTP`	`12000` ms	Default timeout for general HTTP requests (playlist fetch, metrics, etc.).
`RETRY_MAX`	`3`	Maximum number of retry attempts for a failed HTTP request before giving up.
`SERVER_LAN_FORCE_RETRIES`	`3`	Number of forced retries specifically for the LAN server (`SERVER_LIST[0]`) before falling back to the next server.

Polling intervals

Constant	Value	Description
`ADS_POLL_MS`	`10000` ms	Interval between ad snapshot polls in `AdsPollingTask`.
`NET_RETRY_MS`	`30000` ms	Interval between connectivity retries in `ConnectivityTask` after a network failure is detected.
`FREEZE_CHECK_MS`	`10000` ms	Interval at which the player checks for a frozen or stalled video stream.
`SESSION_AUTH_CHECK_MS`	`420000` ms (7 min)	Interval between periodic re-authentication checks to detect expired or revoked sessions.

Registry keys

The Roku registry is persistent key-value storage that survives channel reinstalls. All GlobalTV registry entries are stored under the GlobalTV section.

Constant	Value	Description
`REG_SECTION`	`"GlobalTV"`	Registry section name under which all keys are stored.
`REG_KEY_USER`	`"username"`	Stores the authenticated username.
`REG_KEY_PASS`	`"password"`	Stores the authenticated password.
`REG_KEY_SERVER`	`"lastServer"`	Stores the URL of the last successfully used server.
`REG_KEY_CHANNEL`	`"lastChannelIndex"`	Stores the index of the last watched channel for auto-resume.
`REG_KEY_SAFE_MARGIN`	`"uiSafeMarginPct"`	Stores the user-configured safe area margin percentage (0–10).
`REG_KEY_SERVER_PROFILES`	`"serverProfiles"`	Stores serialized server profile data for the server management panel.

Auth reason codes

These codes are returned by GTV_AuthClassifyFailure() to describe why an authentication attempt failed. They are used to drive the error messaging shown to the user.

Constant	Value	Description
`AUTH_REASON_NONE`	`0`	Auth succeeded or failure reason is unknown.
`AUTH_REASON_NETWORK_DOWN`	`460`	HTTP response code `-1` — no network connectivity.
`AUTH_REASON_CREDENTIALS`	`401`	Bad username or password (HTTP 401, 403, 404, or credential signal in response body).
`AUTH_REASON_INACTIVE`	`470`	Account exists but subscriber is inactive or disabled.
`AUTH_REASON_PASSWORD_CHANGED`	`471`	Session was revoked because the password was changed or reset.

Colors

All color values use Roku’s 0xRRGGBBAA hex format (8 digits including alpha). Fully opaque colors end in FF.

Constant	Value	Description
`COLOR_PRIMARY`	`0x2D57C1FF`	Brand blue. Used for focused elements, buttons, and section headers. Matches `docs.json` primary color `#2D57C1`.
`COLOR_BG`	`0x0F1020FF`	Main background color. Deep navy, used for screen backgrounds.
`COLOR_BG_CARD`	`0x1A1A2EFF`	Card and panel background. Also used as `splash_color=#1a1a2e` in the manifest.
`COLOR_TEXT`	`0xFFFFFFFF`	Primary text color. Full white.
`COLOR_TEXT_DIM`	`0x9E9E9EFF`	Dimmed text color. Used for secondary labels and hints.
`COLOR_ERROR`	`0xE53935FF`	Error state color. Red.
`COLOR_SUCCESS`	`0x43A047FF`	Success state color. Green.
`COLOR_WARNING`	`0xFB8C00FF`	Warning state color. Amber.
`COLOR_OVERLAY`	`0x000000CC`	Semi-transparent black overlay (80% opacity). Used behind modals and player overlays.

Typography

Font size values are integers representing points in the Roku design coordinate space (1920×1080).

Constant	Value (pt)	Description
`FONT_H1`	`48`	Primary heading size. Used for screen titles.
`FONT_H2`	`36`	Secondary heading size. Used for section headings and card titles.
`FONT_BODY`	`24`	Body text size. Used for descriptions, labels, and list items.
`FONT_SMALL`	`18`	Small text size. Used for hints, timestamps, and metadata.
`FONT_NUMBER`	`72`	Large number display. Used for channel number overlays.

UI & layout

Timing

Constant	Value	Description
`SPLASH_MS`	`1500` ms	Duration the in-app splash screen is displayed. Matches `splash_min_time` in the manifest.
`BANNER_MS`	`3000` ms	Duration a notification banner stays visible before auto-dismissing.
`BANNER_FADE_MS`	`300` ms	Duration of the banner fade-out animation.
`CHANNEL_BUF_MS`	`1200` ms	Buffer delay before switching to a new channel, preventing rapid flipping from triggering unnecessary stream loads.

Safe area

Constant	Value	Description
`UI_SAFE_MARGIN_PCT`	`0`	Default safe area margin as a percentage of the screen dimension. `0` means no margin applied by default.
`UI_SAFE_MARGIN_MIN_PCT`	`0`	Minimum allowed safe area margin. Enforced by `GTV_GetSafeMarginPct()`.
`UI_SAFE_MARGIN_MAX_PCT`	`10`	Maximum allowed safe area margin. User-configurable up to 10% via the Settings screen.

The user-configured value is persisted to the registry under REG_KEY_SAFE_MARGIN and read back by GTV_GetSafeMarginPct() at runtime, which clamps it to [UI_SAFE_MARGIN_MIN_PCT, UI_SAFE_MARGIN_MAX_PCT].

Channel grid

Constant	Value	Description
`CHANNEL_TILE_MODE`	`"badge_only"`	Controls how channel tiles are rendered in the main grid. `badge_only` shows only the channel number badge without artwork.
`PARSER_STRICT_CHANNEL_NUMBER`	`true`	When `true`, the playlist parser rejects channels with non-numeric or missing channel numbers rather than assigning a fallback value.

Diagnostic flags

Constant	Value	Description
`LAYOUT_DIAG`	`false`	Enables verbose layout diagnostics printed to the telnet log via `GTV_LayoutPrint()`.
`MAINSCREEN_GRID_DIAG`	`false`	Enables grid layout diagnostic output in `MainScreen`.
`ADS_FLOW_DIAG`	`false`	Enables ad flow diagnostic output in the ads subsystem.

Set any of these to true locally to trace layout or ads behavior. All three default to false and should remain false in production builds.

Get Started

Architecture

Core Features

Configuration

Build & Deploy

Reference

Server & endpoints

Ads backend

Timeouts & retries

Polling intervals

Registry keys

Auth reason codes

Colors

Typography

UI & layout

​Server & endpoints

​Ads backend

​Timeouts & retries

​Polling intervals

​Registry keys

​Auth reason codes

​Colors

​Typography

​UI & layout

Server & endpoints

Ads backend

Timeouts & retries

Polling intervals

Registry keys

Auth reason codes

Colors

Typography

UI & layout